@tdh-keyboard/core 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,542 @@
+# @tdh-keyboard/core
+
+`@tdh-keyboard/core` 是中文虚拟键盘组件库的底层能力包，提供全局配置、输入框写入、键盘定位、长按连发、手写画布，以及拼音引擎和手写识别器的通用接口。
+
+它本身不包含 UI，更适合以下场景：
+
+- 给 `@tdh-keyboard/vue`、`@tdh-keyboard/react` 提供底层能力
+- 在你自己的组件中复用输入框写入和长按逻辑
+- 接入自定义拼音引擎或手写识别服务
+
+## 安装
+
+```bash
+npm install @tdh-keyboard/core
+```
+
+## 导出总览
+
+| 导出 | 类型 | 作用 |
+| --- | --- | --- |
+| `setKeyboardConfig` | function | 设置全局键盘默认配置 |
+| `getKeyboardConfig` | function | 读取当前全局键盘配置 |
+| `registerPinyinEngine` | function | 注册全局拼音引擎实例 |
+| `getPinyinEngine` | function | 获取已注册的拼音引擎 |
+| `registerHandwritingRecognizer` | function | 注册全局手写识别器实例 |
+| `getHandwritingRecognizer` | function | 获取已注册的手写识别器 |
+| `isInputElement` | function | 判断元素是否为可写入的输入框 |
+| `getInputElement` | function | 获取当前激活的输入框 |
+| `writeToInputElement` | function | 在输入框光标位置写入文本 |
+| `delToInputElement` | function | 删除输入框选区或光标前字符 |
+| `moveCursor` | function | 移动输入框光标 |
+| `calculateKeyboardPosition` | function | 计算键盘浮动/底部定位坐标 |
+| `createKeyRepeater` | function | 创建长按连发控制器 |
+| `CanvasDrawer` | class | 管理手写画布、笔迹和自动清屏 |
+| `KeyboardConfig` | interface | 键盘全局配置类型 |
+| `PinyinEngine` | interface | 拼音引擎通用接口 |
+| `PinyinState` | interface | 拼音候选状态类型 |
+| `Candidate` | interface | 拼音候选项类型 |
+| `HandwritingRecognizer` | interface | 手写识别器通用接口 |
+| `RecognizerInitOptions` | interface | 手写识别初始化参数 |
+| `TextInputElement` | type | 文本输入元素类型别名 |
+| `KeyboardPosition` | interface | 键盘定位结果类型 |
+| `KeyRepeatOptions` | interface | 长按连发参数类型 |
+| `KeyRepeater` | interface | 长按连发实例类型 |
+| `CanvasDrawerOptions` | interface | 手写画布配置类型 |
+
+## 快速示例
+
+```ts
+import {
+  createKeyRepeater,
+  delToInputElement,
+  setKeyboardConfig,
+  writeToInputElement,
+} from '@tdh-keyboard/core'
+
+setKeyboardConfig({
+  defaultMode: 'zh',
+  position: 'bottom',
+})
+
+const input = document.querySelector('input')
+const repeater = createKeyRepeater({
+  delay: 400,
+  interval: 60,
+})
+
+if (input) {
+  writeToInputElement(input, '你')
+}
+
+const backspaceButton = document.querySelector('#backspace')
+
+backspaceButton?.addEventListener('mousedown', () => {
+  if (input) {
+    repeater.start(() => delToInputElement(input))
+  }
+})
+
+backspaceButton?.addEventListener('mouseup', () => {
+  repeater.stop()
+})
+```
+
+## API 说明
+
+### 配置与服务注册
+
+#### `setKeyboardConfig(config)`
+
+```ts
+function setKeyboardConfig(config: KeyboardConfig): void
+```
+
+设置全局键盘配置。
+
+- 作用：统一设置默认输入模式、定位方式、是否启用手写等行为
+- 入参：`KeyboardConfig`，支持只传一部分字段
+- 行为：会和当前配置合并，不是整体覆盖
+- 适用场景：应用初始化时设置默认行为
+
+常用配置项：
+
+- `defaultMode`：默认键盘模式，可选 `'en' | 'zh' | 'hand' | 'num' | 'symbol'`
+- `enableHandwriting`：是否启用手写模式
+- `position`：键盘定位方式，可选 `'static' | 'float' | 'bottom'`
+- `floatMarginTop`：浮动模式下键盘与输入框的垂直间距
+- `disableWhenNoFocus`：没有聚焦输入框时是否禁用键盘
+- `manual`：是否改为手动打开模式
+- `numKeys`：数字键盘的行布局
+- `wasmDir`：默认拼音引擎使用的 RIME 资源目录
+
+示例：
+
+```ts
+import { setKeyboardConfig } from '@tdh-keyboard/core'
+
+setKeyboardConfig({
+  defaultMode: 'zh',
+  enableHandwriting: true,
+  position: 'float',
+  floatMarginTop: 12,
+})
+```
+
+#### `getKeyboardConfig()`
+
+```ts
+function getKeyboardConfig(): KeyboardConfig
+```
+
+读取当前全局键盘配置。
+
+- 作用：获取当前生效的配置快照
+- 返回：`KeyboardConfig`
+- 适用场景：组件初始化时读取全局默认配置
+
+#### `registerPinyinEngine(engine)`
+
+```ts
+function registerPinyinEngine(engine: PinyinEngine): void
+```
+
+注册全局拼音引擎实例。
+
+- 作用：让上层键盘组件复用你提供的拼音引擎，而不是内部默认实现
+- 入参：实现了 `PinyinEngine` 接口的实例
+- 适用场景：接入自定义拼音服务，或者把拼音逻辑放到 Worker 中运行
+
+#### `getPinyinEngine()`
+
+```ts
+function getPinyinEngine(): PinyinEngine | null
+```
+
+获取当前已注册的拼音引擎。
+
+- 返回：`PinyinEngine | null`
+- 返回 `null` 的情况：还没有调用过 `registerPinyinEngine`
+
+#### `registerHandwritingRecognizer(recognizer)`
+
+```ts
+function registerHandwritingRecognizer(recognizer: HandwritingRecognizer): void
+```
+
+注册全局手写识别器实例。
+
+- 作用：把手写识别逻辑注入到键盘组件中
+- 入参：实现了 `HandwritingRecognizer` 接口的实例
+- 适用场景：接入本地模型、远程识别接口，或你自己的识别实现
+
+#### `getHandwritingRecognizer()`
+
+```ts
+function getHandwritingRecognizer(): HandwritingRecognizer | null
+```
+
+获取当前已注册的手写识别器。
+
+- 返回：`HandwritingRecognizer | null`
+- 返回 `null` 的情况：还没有注册识别器
+
+### 输入框操作
+
+#### `isInputElement(el)`
+
+```ts
+function isInputElement(el?: Element | null): el is TextInputElement
+```
+
+判断一个 DOM 元素是否为可写入的文本输入元素。
+
+- 支持：`input`、`textarea`
+- 不支持：`checkbox`、`radio`、`file`、`date`、`time` 等非文本类 `input`
+- 返回：类型守卫，返回 `true` 时可当作 `HTMLInputElement | HTMLTextAreaElement` 使用
+
+#### `getInputElement()`
+
+```ts
+function getInputElement(): TextInputElement
+```
+
+获取当前页面上正在聚焦的输入框。
+
+- 作用：直接从 `document.activeElement` 中取当前激活输入框
+- 返回：`HTMLInputElement | HTMLTextAreaElement`
+- 注意：如果当前没有激活的可输入元素，会抛出异常
+
+#### `writeToInputElement(inputElement, text)`
+
+```ts
+function writeToInputElement(inputElement: TextInputElement, text: string): void
+```
+
+向输入框当前光标位置写入文本。
+
+- 作用：模拟键盘输入，把 `text` 插入到光标位置或替换当前选区
+- 行为：写入后会自动更新光标位置，并派发一次 `input` 事件
+- 细节：如果设置了 `maxlength`，超出限制时不会写入
+- 适用场景：自定义虚拟键盘点击字符键时写入文本
+
+示例：
+
+```ts
+import { writeToInputElement } from '@tdh-keyboard/core'
+
+const input = document.querySelector('input')
+
+if (input) {
+  input.focus()
+  writeToInputElement(input, 'hello')
+}
+```
+
+#### `delToInputElement(inputElement)`
+
+```ts
+function delToInputElement(inputElement: TextInputElement): void
+```
+
+删除输入框中的内容。
+
+- 作用：模拟退格键
+- 行为：优先删除当前选区；没有选区时删除光标前一个字符
+- 副作用：删除后会更新光标位置，并派发一次 `input` 事件
+- 适用场景：自定义虚拟键盘点击删除键，或长按连续删除
+
+#### `moveCursor(inputElement, index)`
+
+```ts
+function moveCursor(inputElement: TextInputElement, index: number): void
+```
+
+移动输入框光标到指定位置。
+
+- 作用：同时设置 `selectionStart` 和 `selectionEnd`
+- 入参：`index` 为目标光标位置
+- 适用场景：插入文本后同步光标，或实现左右移动光标能力
+
+### 键盘定位
+
+#### `calculateKeyboardPosition(inputElement, keyboardElement, positionMode, floatMarginTop?)`
+
+```ts
+function calculateKeyboardPosition(
+  inputElement: HTMLElement | null,
+  keyboardElement: HTMLElement | null,
+  positionMode: 'static' | 'float' | 'bottom',
+  floatMarginTop?: number,
+): KeyboardPosition | null
+```
+
+根据定位模式计算键盘 DOM 的位置。
+
+- 返回：`{ top: string, left: string } | null`
+- `static`：不计算位置，直接返回 `null`
+- `bottom`：固定在窗口底部，`left` 为 `0`
+- `float`：根据输入框位置浮动显示，并自动限制在视口范围内
+- `floatMarginTop`：浮动模式下，键盘与输入框底部之间的额外距离
+- 适用场景：浮动键盘、底部固定键盘的定位计算
+
+### 长按连发
+
+#### `createKeyRepeater(options?)`
+
+```ts
+function createKeyRepeater(options?: KeyRepeatOptions): KeyRepeater
+```
+
+创建一个“长按后连续触发”的小工具。
+
+- 返回：`KeyRepeater`
+- 用途：实现删除键长按连续删除、方向键长按连续移动等行为
+- 默认行为：
+  - `start(action)` 调用时会先立即执行一次 `action`
+  - 之后等待 `delay` 毫秒
+  - 再按 `interval` 的间隔重复执行 `action`
+  - 调用 `stop()` 后停止重复
+
+可选参数：
+
+- `delay`：开始重复前的等待时间，默认 `400ms`
+- `interval`：重复执行间隔，默认 `60ms`
+
+返回对象：
+
+- `start(action)`：启动连发
+- `stop()`：停止连发并清理定时器
+
+示例：
+
+```ts
+import { createKeyRepeater } from '@tdh-keyboard/core'
+
+const repeater = createKeyRepeater({
+  delay: 300,
+  interval: 50,
+})
+
+button.addEventListener('mousedown', () => {
+  repeater.start(() => {
+    console.log('repeat')
+  })
+})
+
+button.addEventListener('mouseup', () => {
+  repeater.stop()
+})
+```
+
+### 手写画布
+
+#### `new CanvasDrawer(canvas, options?)`
+
+```ts
+new CanvasDrawer(canvas: HTMLCanvasElement, options?: CanvasDrawerOptions)
+```
+
+创建一个手写画布控制器。
+
+- 作用：接管一个 `canvas`，自动处理鼠标和触摸绘制
+- 能力：记录笔迹、绘制网格、在停止书写后自动清空
+- 适用场景：手写输入面板
+
+可选参数：
+
+- `onDrawEnd`：每次一笔书写结束后的回调
+- `clearDelay`：停止书写后自动清空的延迟，默认 `1000ms`
+
+示例：
+
+```ts
+import { CanvasDrawer } from '@tdh-keyboard/core'
+
+const canvas = document.querySelector('canvas')
+
+if (canvas) {
+  const drawer = new CanvasDrawer(canvas, {
+    onDrawEnd() {
+      console.log(drawer.getStrokeData())
+    },
+    clearDelay: 1500,
+  })
+}
+```
+
+常用实例方法：
+
+#### `canvasDrawer.clearCanvas()`
+
+```ts
+canvasDrawer.clearCanvas(): void
+```
+
+清空画布并重绘辅助网格，同时清空当前笔迹数据。
+
+#### `canvasDrawer.getStrokeData()`
+
+```ts
+canvasDrawer.getStrokeData(): ReadonlyArray<number>
+```
+
+获取当前笔迹数据。
+
+- 返回：只读数组 `ReadonlyArray<number>`
+- 数据格式：`[x1, y1, c1, x2, y2, c2, ...]`
+- 其中 `c` 为笔画结束标记，`1` 表示该点是当前笔画最后一点
+
+#### `canvasDrawer.startClearTimer()`
+
+```ts
+canvasDrawer.startClearTimer(): void
+```
+
+启动自动清空计时器，常用于一笔书写结束后延迟清屏。
+
+#### `canvasDrawer.resetClearTimer()`
+
+```ts
+canvasDrawer.resetClearTimer(): void
+```
+
+取消当前自动清空计时器。
+
+#### `canvasDrawer.destroy()`
+
+```ts
+canvasDrawer.destroy(): void
+```
+
+销毁画布控制器。
+
+- 作用：移除已绑定的鼠标和触摸事件，并清理定时器
+- 适用场景：组件卸载时释放资源
+
+#### `canvasDrawer.getCanvas()`
+
+```ts
+canvasDrawer.getCanvas(): HTMLCanvasElement
+```
+
+返回构造时传入的 `canvas` 元素。
+
+#### `canvasDrawer.getContext()`
+
+```ts
+canvasDrawer.getContext(): CanvasRenderingContext2D
+```
+
+返回内部使用的 `CanvasRenderingContext2D`。
+
+## 类型接口
+
+### `KeyboardConfig`
+
+键盘全局配置类型，用于 `setKeyboardConfig()`。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `defaultMode` | `'en' \| 'zh' \| 'hand' \| 'num' \| 'symbol'` | 默认键盘模式 |
+| `enableHandwriting` | `boolean` | 是否启用手写输入 |
+| `position` | `'static' \| 'float' \| 'bottom'` | 键盘定位方式 |
+| `floatMarginTop` | `number` | 浮动模式的顶部间距 |
+| `disableWhenNoFocus` | `boolean` | 无聚焦输入框时是否禁用键盘 |
+| `manual` | `boolean` | 是否手动控制打开关闭 |
+| `numKeys` | `string[][]` | 数字键盘布局 |
+| `wasmDir` | `string` | 默认 RIME 资源目录 |
+
+### `PinyinEngine`
+
+拼音引擎的通用接口，供自定义实现接入。
+
+- `initialize()`：初始化引擎资源
+- `processInput(pinyin)`：处理完整拼音串，返回候选状态
+- `pickCandidate(index)`：按候选索引选词
+- `clearInput()`：清空当前拼音组合
+- `setSimplified?(simplified)`：可选，实现简繁切换
+- `destroy()`：销毁引擎
+
+```ts
+import type { PinyinEngine } from '@tdh-keyboard/core'
+
+class CustomPinyinEngine implements PinyinEngine {
+  async initialize() {}
+  async processInput(pinyin: string) {
+    return {
+      committed: null,
+      preeditHead: '',
+      preeditBody: pinyin,
+      preeditTail: '',
+      cursorPos: pinyin.length,
+      candidates: [],
+      pageNo: 0,
+      isLastPage: true,
+      highlightedIndex: 0,
+      selectLabels: [],
+    }
+  }
+  async pickCandidate() {
+    throw new Error('Not implemented')
+  }
+  async clearInput() {}
+  async destroy() {}
+}
+```
+
+### `PinyinState`
+
+拼音候选状态。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `committed` | `string \| null` | 已提交文本 |
+| `preeditHead` | `string` | 光标前的预编辑文本 |
+| `preeditBody` | `string` | 当前高亮的预编辑文本 |
+| `preeditTail` | `string` | 光标后的预编辑文本 |
+| `cursorPos` | `number` | 预编辑中的光标位置 |
+| `candidates` | `Candidate[]` | 当前候选项列表 |
+| `pageNo` | `number` | 当前页码，从 `0` 开始 |
+| `isLastPage` | `boolean` | 是否最后一页 |
+| `highlightedIndex` | `number` | 当前高亮候选索引 |
+| `selectLabels` | `string[]` | 候选快捷选择标签 |
+
+### `Candidate`
+
+拼音候选项类型。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `text` | `string` | 候选文本 |
+| `comment` | `string` | 候选注释 |
+
+### `HandwritingRecognizer`
+
+手写识别器的通用接口，供自定义识别服务实现。
+
+- `initialize(options?)`：初始化识别器
+- `recognize(strokeData)`：识别笔迹，返回候选文字列表
+- `close()`：释放识别器资源
+
+```ts
+import type { HandwritingRecognizer } from '@tdh-keyboard/core'
+
+class CustomRecognizer implements HandwritingRecognizer {
+  async initialize() {
+    return true
+  }
+  async recognize(strokeData: number[]) {
+    return strokeData.length ? ['中'] : []
+  }
+  async close() {}
+}
+```
+
+### `RecognizerInitOptions`
+
+手写识别初始化参数。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `onProgress` | `(progress: number) => void` | 初始化进度回调，范围 `0` 到 `1` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tdh-keyboard/core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "中文虚拟键盘组件库核心包",
   "author": "tdh",
   "license": "Apache 2.0",
@@ -21,7 +21,8 @@
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "devDependencies": {
     "tsdown": "^0.21.2",