中文键盘 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：常用类型
• 以及 @tdh-keyboard/core 的全部公开导出

Props

| 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | defaultMode | 'en' \| 'zh' \| 'en_cap' \| 'hand' \| 'num' \| 'num_pure' \| 'id_card' \| 'num_en_cap' \| '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 | 是否启用手动打开模式 | | width | string \| number | - | 键盘宽度，传 number 时按 px 处理 | | height | string \| number | - | 键盘高度，传 number 时按 px 处理 | | numKeys | string[][] | - | 自定义数字键盘布局 | | className | string | - | 自定义根节点类名 | | style | React.CSSProperties | - | 自定义根节点样式 | | onKey | (payload: KeyEvent) => void | - | 按键回调 |

基本使用

全局配置

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

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

基础用法

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

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" width={360} height={260} />
    </div>
  )
}

export default App

更多展示方式示例：

<>
  <TdhKeyboard />
  <TdhKeyboard position="float" floatPlacement="left" />
  <TdhKeyboard position="bottom" />
  <TdhKeyboard width={420} height={280} />
  <TdhKeyboard enableHandwriting />
  <TdhKeyboard defaultMode="num" />
  <TdhKeyboard defaultMode="num_en_cap" />
</>

如果只想调尺寸，优先使用 width / height；仍然可以继续通过 style 传其他根节点样式。

手动打开模式

设置 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

适合输入数字、金额、小数等内容。会复用通用工具栏，默认提供换行、清空和收起，不显示手写切换按钮。

纯数字输入模式 num_pure

仅支持 0-9 输入。会复用通用工具栏，默认提供换行、清空和收起，不显示手写切换按钮。

身份证输入模式 id_card

适用于身份证号输入，支持 0-9 和 X。会复用通用工具栏，默认提供换行、清空和收起，不显示手写切换按钮。

数字字母大写模式 num_en_cap

固定展示 0-9 和大写 A-Z，不提供空格、符号和输入切换入口。会复用通用工具栏，默认提供换行、清空和收起，不显示手写切换按钮。

符号输入模式 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())