中文键盘 Vue 3 组件库

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

功能特点

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

安装

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

导出内容

• 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[][] | - | 自定义数字键盘布局 |

事件

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

基本使用

全局配置

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

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'。
• TdhKeyboard 不提供 v-model，它会直接把内容写入当前聚焦的 input / textarea。

<script setup lang="ts">
import { ref } from 'vue'
import { TdhKeyboard } from '@tdh-keyboard/vue'
import '@tdh-keyboard/vue/style.css'

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

<template>
  <div>
    <input
      v-model="inputText"
      data-inputmode="zh"
      inputmode="none"
      placeholder="点击使用键盘输入"
    />

    <TdhKeyboard position="float" :width="360" :height="260" />
  </div>
</template>

更多展示方式示例：

<template>
  <TdhKeyboard />
  <TdhKeyboard position="float" float-placement="right" />
  <TdhKeyboard position="bottom" />
  <TdhKeyboard :width="420" :height="280" />
  <TdhKeyboard :enable-handwriting="true" />
  <TdhKeyboard default-mode="num" />
  <TdhKeyboard default-mode="num_en_cap" />
</template>

如果只是调整键盘尺寸，推荐直接使用 width / height；style 仍可继续透传给根节点做其他样式扩展。

与 Element Plus 一起使用

如果你的项目已经安装了 element-plus，ElInput 内部仍然是原生 input / textarea，只要把 inputmode="none" 和 data-inputmode 透传给组件，就可以直接和虚拟键盘联动。

import 'element-plus/dist/index.css'

<script setup lang="ts">
import { ElInput } from 'element-plus'
import { ref } from 'vue'
import { TdhKeyboard } from '@tdh-keyboard/vue'

const text = ref('')
const textarea = ref('Element Plus 多行输入')
</script>

<template>
  <ElInput
    v-model="text"
    data-inputmode="zh"
    inputmode="none"
    placeholder="点击这里使用虚拟键盘"
  />

  <ElInput
    v-model="textarea"
    type="textarea"
    data-inputmode="zh"
    inputmode="none"
    :rows="4"
  />

  <TdhKeyboard position="float" />
</template>

手动打开模式

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

<script setup lang="ts">
import type { KeyboardInstance } from '@tdh-keyboard/vue'
import { ref } from 'vue'
import { TdhKeyboard } from '@tdh-keyboard/vue'

const keyboardRef = ref<KeyboardInstance>()
const inputRef = ref<HTMLInputElement>()

function openKeyboard() {
  keyboardRef.value?.open(inputRef.value)
}

function closeKeyboard() {
  keyboardRef.value?.close()
}

function destroyKeyboard() {
  keyboardRef.value?.destroy()
}
</script>

<template>
  <input ref="inputRef" inputmode="none" />
  <button @click="openKeyboard">打开键盘</button>
  <button @click="closeKeyboard">关闭键盘</button>
  <button @click="destroyKeyboard">销毁键盘</button>
  <TdhKeyboard ref="keyboardRef" manual position="bottom" />
</template>

实例方法说明：

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

拼音引擎初始化

使用 RIME WASM 拼音引擎

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

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/vue'
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/vue'
import { registerHandwritingRecognizer } from '@tdh-keyboard/vue'

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

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

  async close() {}
}

registerHandwritingRecognizer(new MyHandwritingRecognizer())