# 中文键盘组件库

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

这是一个Vue 3的中文键盘组件库，支持拼音输入和手写输入。

## 功能特点

- 🔌 即插即用，自动绑定输入框
- ✨ 支持拼音输入，带候选词选择功能
- ✏️ 支持手写输入识别，支持连笔和简写
- 🔧 可自定义手写识别算法
- 📏 键盘大小可自定义缩放，灵活适配各种界面布局
- 🌐 纯前端实现，可作为静态网页部署，无需服务端支持

## 安装

```bash
npm install @zh-keyboard/vue
# 或者
yarn add @zh-keyboard/vue
# 或者
pnpm add @zh-keyboard/vue
```

## 属性

### Props

| 属性名           | 类型                              | 默认值    | 说明                                |
| --------------- | --------------------------------- | -------- | ---------------------------------- |
| defaultMode     | 'en' \| 'zh' \| 'hand' \| 'num'  | 'en'     | 默认的键盘模式                      |
| enableHandwriting| boolean                          | false    | 是否启用手写输入                    |
| position        | 'static' \| 'float' \| 'bottom'  | 'static' | 键盘定位模式                       |
| floatMarginTop  | number                            | 10       | 浮动模式下键盘与输入框的距离        |
| disableWhenNoFocus| boolean                         | true     | 当没有input获得焦点时是否禁用键盘   |
| requireInputmode| boolean                          | false    | 是否只对带有 data-inputmode 属性的 input 弹出键盘 |
| numKeys         | string[][]                   | -        | 数字键盘的行配置                    |

### 事件

| 事件名 | 参数类型 | 说明 |
| ------ | -------- | ---- |
| key    | KeyEvent | 当用户在键盘上点击按键时触发 |

## 基本使用

### 全局配置

可以在项目入口文件中设置全局配置：

```typescript
import { setKeyboardConfig } from '@zh-keyboard/vue'

setKeyboardConfig({
  enableHandwriting: true
})
```

### 基础用法

- 为了防止移动端设备弹出系统默认的键盘，建议在输入框上设置 `inputmode="none"` 属性。
- 可以通过在输入框上设置 `data-inputmode` 属性来指定组件默认打开的键盘类型 (可选值为 `'en'`, `'zh'`, `'hand'`, `'num'`)，具体键盘模式的说明请参考 `defaultMode` 属性。
- 设置 `:require-inputmode="true"` 可以让键盘**只**在带有 `data-inputmode` 属性的 input 上弹出，适用于需要精确控制哪些输入框使用虚拟键盘的场景。

```vue
<script setup>
import { ZhKeyboard } from '@zh-keyboard/vue'
import { ref } from 'vue'
import '@zh-keyboard/vue/style.css'

const inputText = ref('')
</script>

<template>
  <div>
    <input v-model="inputText" data-inputmode="en" inputmode="none" placeholder="点击使用键盘输入" />
    <!-- 静态定位的键盘 -->
    <ZhKeyboard v-model="inputText" />

    <!-- 浮动定位的键盘（跟随输入框） -->
    <ZhKeyboard v-model="inputText" position="float" />

    <!-- 底部固定的键盘 -->
    <ZhKeyboard v-model="inputText" position="bottom" />

    <!-- 启用手写输入的键盘 -->
    <ZhKeyboard v-model="inputText" :enable-handwriting="true" />

    <!-- 数字键盘 -->
    <ZhKeyboard v-model="inputText" default-mode="num" />
  </div>
</template>
```

## 拼音引擎初始化

### 使用 RIME WASM 拼音引擎

拼音输入功能需要初始化拼音引擎。推荐使用基于 RIME WASM 的拼音引擎：

```typescript
import { RimePinyinEngine } from '@zh-keyboard/pinyin'
import { registerPinyinEngine } from '@zh-keyboard/vue'

// 注册 RIME 拼音引擎
registerPinyinEngine(new RimePinyinEngine({
  wasmDir: '/data', // rime-api.js/wasm 所在路径
  dictVersion: '1.0.0', // 词库版本号（可选），版本一致时跳过下载直接使用
  simplified: true, // 默认使用简体中文（可选，默认 true）
}))
```

### 引擎加载与就绪

`RimePinyinEngine` 在构造时自动开始加载，无需手动调用 `initialize()`。UI 层可通过 `whenReady()` 方法等待引擎就绪：

```typescript
const engine = new RimePinyinEngine({ wasmDir: '/data' })
await engine.whenReady() // 等待加载完成
```

`CandidateBar` 组件内部已集成 loading 状态，引擎加载期间会显示 **"加载拼音引擎中…"** 提示。

### WASM 及词库文件部署

需要将以下文件发布到 `public/data/` 目录（`wasmDir` 对应 `/data`）：

- `rime-api.js` / `rime-api.wasm` / `rime-api.data` — RIME WASM 引擎
- `source/default.yaml` — 默认配置
- `source/luna_pinyin.schema.yaml` — 拼音方案
- `source/luna_pinyin.dict.yaml` — 词典
- `source/symbols.yaml` — 符号表
- `source/essay.txt` — 语料

这些文件来自 `@zh-keyboard/pinyin` 包的 `data/` 目录。引擎首次加载时会自动从 `source/` 编译词库并缓存到 IndexedDB，后续启动直接使用缓存，无需重新编译。

> 若 `dictVersion` 有变更，引擎会自动检测版本不一致并重新下载编译；
> 若版本一致则直接加载 IndexedDB 缓存，实现秒级启动。

worker 写法参考 `examples`。

## 输入模式

### 拼音输入模式 (zh)

拼音输入模式支持单字拼音输入，具有以下特性：

- 支持单字模糊拼音匹配
- 使用内置词库进行单字匹配
- 支持中英文快速切换

> 注：目前仅支持单个汉字的拼音输入，连续词组输入功能正在开发中

### 英文输入模式 (en)

标准的英文键盘布局，支持英文字母、数字和常用符号的输入。

### 手写输入模式 (hand)

手写输入模式允许用户通过手写输入汉字，启用此模式需要设置 `enableHandwriting` 为 `true`。

### 数字输入模式 (num)

数字输入模式提供一个数字和小数点键盘，方便用户输入数字、金额等。

## 手写识别

组件库支持自定义手写识别服务。您可以注册自己的手写识别服务来处理用户的手写输入。

### 手写识别接口

手写识别服务需要实现以下接口：

```typescript
interface HandwritingRecognizer {
  /**
   * 初始化手写识别服务
   * @returns 返回是否初始化成功
   */
  initialize(): Promise<boolean>

  /**
   * 识别手写笔迹
   * @param strokeData 笔迹数据，格式为 x y c x y c ...，其中x和y是坐标，c表示是否为笔画的最后一点(1表示是，0表示否)
   * @returns 识别结果列表
   */
  recognize(strokeData: number[]): Promise<string[]>

  /**
   * 关闭手写识别服务
   */
  close(): Promise<void>
}
```

### 笔迹数据格式

笔迹数据以数组形式存储，格式为 `[x1, y1, c1, x2, y2, c2, ...]`，其中：
- `x`、`y` 是坐标点
- `c` 表示是否为笔画的最后一点：1表示是最后一点，0表示不是

例如，一个简单的笔画可能是：`[100, 150, 0, 101, 151, 0, 102, 152, 1]`，表示三个点的笔画，最后一个点是笔画的结束点。

### 注册手写识别服务

```typescript
import { registerHandwritingRecognizer } from 'zh-keyboard'
import { MyHandwritingRecognizer } from './MyHandwritingRecognizer'

// 创建并注册您的手写识别服务
const recognizer = new MyHandwritingRecognizer()
registerHandwritingRecognizer(recognizer)
```

### 示例实现

以下是一个简单的手写识别服务示例实现：

```typescript
import type { HandwritingRecognizer } from 'zh-keyboard'

export class MyHandwritingRecognizer implements HandwritingRecognizer {
  private initialized = false

  async initialize(): Promise<boolean> {
    console.log('初始化手写识别服务...')
    // 在实际应用中，这里可能需要加载模型或连接到服务器
    this.initialized = true
    return true
  }

  async recognize(strokeData: number[]): Promise<string[]> {
    if (!this.initialized) {
      throw new Error('手写识别服务未初始化')
    }

    console.log('识别笔迹数据:', strokeData)

    // 这里调用您的手写识别API
    // 返回识别结果
    return ['你', '我', '他', '好', '的']
  }

  async close(): Promise<void> {
    console.log('关闭手写识别服务')
    this.initialized = false
  }
}
```

## 生命周期

1. 当手写输入组件挂载时，会自动调用手写识别服务的 `initialize()` 方法
2. 当用户完成一个笔画时，会调用 `recognize()` 方法进行识别
3. 当手写输入组件卸载时，会调用 `close()` 方法关闭手写识别服务