# KeyTone

**Repository Path**: ukSir/KeyTone

## Basic Information

- **Project Name**: KeyTone
- **Description**: No description available
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-02-02
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KeyTone

[![GitHub Stars](https://img.shields.io/github/stars/itcastWsy/KeyTone?style=social)](https://github.com/itcastWsy/KeyTone)
[![GitHub Forks](https://img.shields.io/github/forks/itcastWsy/KeyTone?style=social)](https://github.com/itcastWsy/KeyTone)
[![GitHub License](https://img.shields.io/github/license/itcastWsy/KeyTone)](https://github.com/itcastWsy/KeyTone/blob/main/LICENSE)
[![NPM Version](https://img.shields.io/npm/v/keytone)](https://www.npmjs.com/package/keytone)

KeyTone 是一个用于 HarmonyOS 应用的按键音管理库。它提供了一套完整的解决方案，包括音频资源的加载、播放管理、状态持久化以及开箱即用的 UI 组件和工具函数。

## 功能特性

- 🎵 **开箱即用**：内置按键音资源，无需额外配置。
- ⚡ **高性能**：使用 AVPlayer 进行音频播放，支持资源预加载和防抖处理。
- 💾 **状态持久化**：自动保存用户的按键音开关设置，重启后保持状态。
- 🔘 **UI 组件**：提供 `ToneButton` 和 `KeyToneSwitch` 组件，方便快速集成。
- 🪝 **Hook 工具**：提供 `withKeyTone` 系列 Hook 函数，灵活控制按键音播放。
- 📱 **纯 ArkTS**：完全基于 ArkTS 和 ArkUI 开发，兼容性好。
- 🚀 **V2 状态管理**：使用最新的 V2 状态管理，性能更优。

## 安装

```bash
ohpm install keytone
```

## 使用方法

### 1. 初始化

在应用入口（如 `EntryAbility` 或页面的 `aboutToAppear`）中初始化管理器：

```typescript
import { KeyToneManager } from 'keytone';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  aboutToAppear() {
    let context = getContext(this) as common.UIAbilityContext;
    KeyToneManager.getInstance().init(context);
  }

  build() {
    // ...
  }
}
```

### 2. 使用 Hook 工具（推荐）

#### 基础用法

```typescript
import { withKeyTone } from 'keytone';

Button('点击')
  .onClick(withKeyTone((event: ClickEvent) => {
    // 自动播放按键音，可以访问事件参数
    console.log('点击位置:', event.screenX, event.screenY);
  }))
```

#### 带条件判断

```typescript
import { withKeyToneConditional } from 'keytone';

Button('点击')
  .onClick(withKeyToneConditional(
    () => this.shouldPlay, // 条件函数
    (event: ClickEvent) => {
      // 业务逻辑
    }
  ))
```

#### 带配置

```typescript
import { withKeyToneConfig, KeyToneConfig } from 'keytone';

let config: KeyToneConfig = {
  enabled: true,
  async: false,
  beforePlay: (event) => console.log('准备播放'),
  afterPlay: (event) => console.log('播放完成'),
  callback: (event: ClickEvent) => {
    // 业务逻辑
  }
};

Button('点击')
  .onClick(withKeyToneConfig(config))
```

### 3. 使用 ToneButton 组件

```typescript
import { ToneButton, withKeyTone } from 'keytone';

// 使用按键音
ToneButton({
  text: '1',
  btnWidth: 72,
  btnHeight: 72,
  btnBackgroundColor: Color.White,
  fontColor: '#182431'
})
  .onClick(withKeyTone((event: ClickEvent) => {
    console.log('按键1被点击');
  }))

// 不使用按键音
ToneButton({
  text: 'Cancel',
  btnWidth: 120,
  btnHeight: 40
})
  .onClick((event: ClickEvent) => {
    console.log('取消操作');
  })

// 自定义内容
ToneButton() {
  Row() {
    Text('🔔')
    Text('自定义内容')
      .margin({ left: 8 })
  }
}
  .btnWidth(200)
  .btnHeight(48)
  .onClick(withKeyTone(() => {
    console.log('自定义按钮被点击');
  }))
```

### 4. 集成设置开关

```typescript
import { KeyToneSwitch } from 'keytone';

@Entry
@Component
struct SettingsPage {
  build() {
    Column() {
      KeyToneSwitch()
    }
  }
}
```

### 5. 直接使用 KeyToneManager

```typescript
import { KeyToneManager } from 'keytone';

// 播放按键音
KeyToneManager.getInstance().play();

// 获取/设置状态
let enabled = KeyToneManager.getInstance().isEnabled();
KeyToneManager.getInstance().setEnabled(false);

// 释放资源（在页面销毁时调用）
KeyToneManager.getInstance().release();
```

## API 文档

### KeyToneManager

| 方法 | 说明 |
|------|------|
| `getInstance(): KeyToneManager` | 获取单例实例 |
| `init(context: common.UIAbilityContext): Promise<void>` | 初始化管理器，预加载资源 |
| `play(): void` | 播放按键音（自动检查开关状态，包含防抖） |
| `isEnabled(): boolean` | 获取当前按键音是否开启 |
| `setEnabled(enable: boolean): void` | 设置按键音开启/关闭 |
| `release(): void` | 释放资源 |

### Hook 工具函数

| 函数 | 说明 |
|------|------|
| `withKeyTone(callback: (event: ClickEvent) => void)` | 基础按键音包装函数 |
| `withKeyToneConditional(shouldPlay: () => boolean, callback: (event: ClickEvent) => void)` | 带条件判断的按键音包装函数 |
| `withKeyToneConfig(config: KeyToneConfig)` | 可配置的按键音包装函数 |

### ToneButton 组件

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `text` | `string \| ResourceStr` | `''` | 按钮文本 |
| `content` | `@BuilderParam` | - | 自定义内容构建器 |
| `stateEffect` | `boolean` | `true` | 是否启用状态效果 |
| `type` | `ButtonType` | `ButtonType.Normal` | 按钮类型 |
| `fontColor` | `ResourceColor` | `Color.White` | 字体颜色 |
| `fontSize` | `number \| string \| Resource` | `16` | 字体大小 |
| `fontWeight` | `FontWeight \| number \| string` | `FontWeight.Normal` | 字体粗细 |
| `fontStyle` | `FontStyle` | `FontStyle.Normal` | 字体样式 |
| `fontFamily` | `string \| Resource` | `''` | 字体家族 |
| `btnWidth` | `Length` | `'100%'` | 按钮宽度 |
| `btnHeight` | `Length` | `48` | 按钮高度 |
| `btnBackgroundColor` | `ResourceColor` | `$r('sys.color.ohos_id_color_primary')` | 按钮背景颜色 |
| `btnBorderRadius` | `Length` | `8` | 按钮圆角半径 |
| `btnEnabled` | `boolean` | `true` | 按钮是否可用 |

### KeyToneSwitch 组件

一个标准的 Toggle 开关组件，内部自动绑定了 `KeyToneManager` 的状态。

### KeyToneConfig 接口

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `enabled` | `boolean` | 否 | 是否启用按键音 |
| `async` | `boolean` | 否 | 是否异步播放 |
| `beforePlay` | `(event?: ClickEvent) => void` | 否 | 播放前的回调 |
| `afterPlay` | `(event?: ClickEvent) => void` | 否 | 播放后的回调 |
| `callback` | `(event: ClickEvent) => void` | 是 | 业务逻辑回调 |

## 版本历史

详细更新日志请查看 [CHANGELOG.md](./CHANGELOG.md)

## 作者信息

万少：yeah126139163@163.com

公众号：HarmonyOS 万少

博客地址：https://blog.zbztb.cn

GitHub：https://github.com/itcastWsy/KeyTone

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个库。

## 开源协议

本项目基于 [Apache-2.0](LICENSE) 协议开源。