Package Exports

@tdh-keyboard/react
@tdh-keyboard/react/style.css

Readme

中文键盘 React 组件库

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

功能特点

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

安装

npm install @tdh-keyboard/react
# 或者
yarn add @tdh-keyboard/react
# 或者
pnpm add @tdh-keyboard/react

导出内容

TdhKeyboard：键盘组件
setKeyboardConfig / getKeyboardConfig：全局配置
registerPinyinEngine / registerHandwritingRecognizer：注册拼音引擎和手写识别器
KeyboardInstance / KeyEvent / KeyBoardMode：常用类型

Props

属性名	类型	默认值	说明
`defaultMode`	`'en' \| 'zh' \| 'en_cap' \| 'hand' \| 'num' \| 'symbol'`	`'en'`	默认键盘模式
`enableHandwriting`	`boolean`	`false`	是否启用手写输入
`position`	`'static' \| 'float' \| 'bottom'`	`'static'`	键盘定位模式
`floatMarginTop`	`number`	`0`	浮动模式下键盘与输入框的距离
`floatPlacement`	`'auto' \| 'top' \| 'right' \| 'bottom' \| 'left'`	`'auto'`	浮动模式下的渲染方向
`disableWhenNoFocus`	`boolean`	`true`	没有输入框聚焦时是否禁用键盘
`manual`	`boolean`	`false`	是否启用手动打开模式
`numKeys`	`string[][]`	-	自定义数字键盘布局
`className`	`string`	-	自定义根节点类名
`style`	`React.CSSProperties`	-	自定义根节点样式
`onKey`	`(payload: KeyEvent) => void`	-	按键回调

基本使用

全局配置

import { setKeyboardConfig } from '@tdh-keyboard/react'

setKeyboardConfig({
  defaultMode: 'zh',
  enableHandwriting: true,
  position: 'float',
  floatPlacement: 'auto',
})

基础用法

建议在输入框上设置 inputMode="none"，避免移动端弹出系统键盘。
可以通过 data-inputmode 指定默认键盘模式，可选值为 'en'、'zh'、'en_cap'、'hand'、'num'。

import { useState } from 'react'
import { TdhKeyboard } from '@tdh-keyboard/react'
import '@tdh-keyboard/react/style.css'

function App() {
  const [inputText, setInputText] = useState('')

  return (
    <div>
      <input
        value={inputText}
        onChange={e => setInputText(e.target.value)}
        data-inputmode="zh"
        inputMode="none"
        placeholder="点击使用键盘输入"
      />

      <TdhKeyboard position="float" />
    </div>
  )
}

export default App

更多展示方式示例：

<>
  <TdhKeyboard />
  <TdhKeyboard position="float" floatPlacement="left" />
  <TdhKeyboard position="bottom" />
  <TdhKeyboard enableHandwriting />
  <TdhKeyboard defaultMode="num" />
</>

手动打开模式

设置 manual 后，键盘不会再根据输入框焦点自动显示，需要通过 ref 手动控制：

import { useRef } from 'react'
import type { KeyboardInstance } from '@tdh-keyboard/react'
import { TdhKeyboard } from '@tdh-keyboard/react'

function App() {
  const keyboardRef = useRef<KeyboardInstance>(null)
  const inputRef = useRef<HTMLInputElement>(null)

  return (
    <>
      <input ref={inputRef} inputMode="none" />
      <button onClick={() => keyboardRef.current?.open(inputRef.current)}>打开键盘</button>
      <button onClick={() => keyboardRef.current?.close()}>关闭键盘</button>
      <button onClick={() => keyboardRef.current?.destroy()}>销毁键盘</button>
      <TdhKeyboard ref={keyboardRef} manual position="bottom" />
    </>
  )
}

实例方法说明：

open(target?)：打开键盘，可选传入要写入的 input / textarea
close()：关闭键盘
destroy()：销毁当前键盘状态并清空绑定的输入框

拼音引擎初始化

使用 RIME WASM 拼音引擎

import { RimePinyinEngine } from '@tdh-keyboard/pinyin'
import { registerPinyinEngine } from '@tdh-keyboard/react'

registerPinyinEngine(new RimePinyinEngine({
  wasmDir: '/rime',
}))

WASM 文件部署

需要将 @tdh-keyboard/pinyin/data/ 中的资源文件发布到静态资源目录，并保证 wasmDir 指向该目录。

常见文件包括：

rime-api.wasm
default.yaml
luna_pinyin.schema.yaml
luna_pinyin.table.bin
luna_pinyin.prism.bin
luna_pinyin.reverse.bin

手写识别初始化

import { registerHandwritingRecognizer } from '@tdh-keyboard/react'
import { TdhRecognizer } from '@tdh-keyboard/recognizer'

registerHandwritingRecognizer(new TdhRecognizer({
  modelPath: '/models/handwrite/model.json',
  dictPath: '/models/dict.txt',
}))

输入模式

拼音输入模式 `zh`

拼音输入模式支持拼音输入、候选词展示和中英文切换。

英文输入模式 `en`

标准英文键盘布局。

大写英文模式 `en_cap`

以大写字母形式输入英文。

手写输入模式 `hand`

需要将 enableHandwriting 设为 true，并提前注册手写识别器。

数字输入模式 `num`

适合输入数字、金额、小数等内容。

符号输入模式 `symbol`

用于输入中英文符号，通常由键盘内部切换进入。

自定义手写识别服务

import type { HandwritingRecognizer } from '@tdh-keyboard/react'
import { registerHandwritingRecognizer } from '@tdh-keyboard/react'

class MyHandwritingRecognizer implements HandwritingRecognizer {
  async initialize() {
    return true
  }

  async recognize(strokeData: number[]) {
    console.log(strokeData)
    return ['你', '我', '他']
  }

  async close() {}
}

registerHandwritingRecognizer(new MyHandwritingRecognizer())

@tdh-keyboard/react