中文键盘原生 DOM 组件库

这是一个不依赖 Vue / React 的中文虚拟键盘包，基于原生 DOM 实现，支持拼音输入、手写输入、数字键盘和符号键盘。

安装

npm install @tdh-keyboard/native

如果你需要拼音输入和手写输入，还可以按需安装：

npm install @tdh-keyboard/pinyin @tdh-keyboard/recognizer

导出内容

• TdhKeyboard：键盘类
• createKeyboard(options?)：快捷创建键盘实例
• setKeyboardConfig / getKeyboardConfig：全局配置
• registerPinyinEngine / registerHandwritingRecognizer：注册拼音引擎和手写识别器
• TdhKeyboardOptions / KeyboardInstance / KeyEvent / KeyBoardMode：常用类型
• 以及 @tdh-keyboard/core 的全部公开导出

基本使用

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

const keyboard = new TdhKeyboard({
  position: 'bottom',
  enableHandwriting: true,
  width: '100%',
  height: 'auto',
  floatPlacement: 'auto',
})

keyboard.mount()

<input inputmode="none" placeholder="点击使用键盘输入" />

说明：

• position: 'bottom' | 'float' 时，默认挂载到 document.body
• position: 'static' 时，需要手动传入挂载容器
• 建议输入框加上 inputmode="none"，避免移动端弹出系统键盘
• 可以通过 data-inputmode="zh|en|en_cap|hand|num|num_pure|id_card|num_en_cap" 指定某个输入框的默认键盘模式

使用 createKeyboard

import { createKeyboard } from '@tdh-keyboard/native'
import '@tdh-keyboard/native/style.css'

const keyboard = createKeyboard({
  position: 'float',
})

keyboard.mount()

静态挂载

const container = document.querySelector('#keyboard-root')

const keyboard = new TdhKeyboard({
  position: 'static',
  enableHandwriting: true,
  width: 420,
  height: 280,
})

keyboard.mount(container)

手动打开模式

const input = document.querySelector('input')

const keyboard = new TdhKeyboard({
  manual: true,
  position: 'bottom',
  floatPlacement: 'left',
})

keyboard.mount()
keyboard.open(input)

实例方法说明：

• mount(container?)：挂载键盘 DOM；非 static 模式可省略参数
• open(target?)：打开键盘，可选传入当前要写入的 input / textarea
• close()：关闭键盘
• destroy()：销毁键盘实例并移除事件监听
• getElement()：获取键盘根 DOM 元素

拼音引擎初始化

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

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

RIME 相关文件需要部署到静态资源目录中，文件来源于 @tdh-keyboard/pinyin/data/。

手写识别初始化

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

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

全局配置

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

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

选项说明

TdhKeyboardOptions 支持以下常用字段：

• defaultMode：默认键盘模式
• enableHandwriting：是否启用手写输入
• position：static / float / bottom
• floatMarginTop：浮动模式下的边距
• floatPlacement：浮动模式下的方向
• disableWhenNoFocus：无聚焦输入框时是否禁用
• manual：是否启用手动打开模式
• width：键盘宽度，支持 number | string
• height：键盘高度，支持 number | string
• numKeys：自定义数字键盘布局
• className：自定义类名
• style：自定义内联样式
• container：默认挂载容器
• onKey：按键回调

传 number 时会按 px 处理；如果只想调整键盘尺寸，优先使用 width / height，style 仍适合补充其他样式。

输入模式补充说明：

• num：数字输入模式，会复用通用工具栏，默认提供换行、清空和收起，不显示手写切换按钮
• num_pure：纯数字输入模式，仅支持 0-9，会复用通用工具栏，默认提供换行、清空和收起，不显示手写切换按钮
• id_card：身份证输入模式，支持 0-9 和 X，会复用通用工具栏，默认提供换行、清空和收起，不显示手写切换按钮
• num_en_cap：固定数字字母键盘，只显示 0-9 和大写 A-Z，不提供空格、符号或其他输入切换入口；同时会复用通用工具栏，默认提供换行、清空和收起，不显示手写切换按钮

工具栏行为

• 当候选词栏未显示时，拼音、英文、手写和各类数字键盘都会使用统一工具栏。
• 清空输入 会先在按钮左侧弹出确认浮层，点击确认后才会真正清空内容。
• 工具栏分割线只会在左右两侧都有可见一级动作时显示。