构建Qt Virtual Keyboard

概述

本文档介绍了如何构建Qt Virtual Keyboard 插件。

该项目分为以下子项目：

examples/virtualkeyboard/basic	Qt Virtual Keyboard 演示应用程序
src/components/	Qt Virtual Keyboard 组件 QML 插件（QtQuick.VirtualKeyboard.Components ）
src/plugin/	Qt Virtual Keyboard 平台输入上下文插件。该插件提供 QPlatformInputContext 接口，并在 QML 输入上下文与平台之间充当中间层。
src/plugins/	一个包含Qt Virtual Keyboard 插件（QtQuick.VirtualKeyboard.Plugins）的目录，这些插件实现了复杂的输入法，例如HunspellInputMethod。构建时的配置用于指定哪些插件将在运行时被构建和加载。
src/settings/	Qt Virtual Keyboard Settings QML 插件（QtQuick.VirtualKeyboard.Settings ）。该插件为虚拟键盘提供了可由应用程序配置的设置。
src/styles/	Qt Virtual Keyboard 样式 QML 插件（QtQuick.VirtualKeyboard.Styles ）。
src/virtualkeyboard/	Qt Virtual Keyboard 模块和 QML 插件。

配置选项

下表列出了用于配置虚拟键盘功能的顶级选项。这些选项将传递给configure工具。

选项	参数	描述	备注
-vkb-enable <code>[,<code>]*"	支持的语言代码或“all”	启用指定的语言	可通过此选项显式启用指定的语言。每个语言代码的格式为language[_country]，其中： language是小写、两个字母的 ISO 639 语言代码 country是两个大写的字母组成的 ISO 3166 国家代码可使用此选项根据需要定义语言支持。虚拟键盘可同时支持一种或多种语言。例如，`-vkb-enable de_DE,fi_FI` 可启用对德语和芬兰语的支持。如果未指定其他语言，虚拟键盘将自动包含所有受支持的语言。
-vkb-handwriting	[no\|example-hwr\|myscript-hwr\|cerence-hwr]	启用或禁用手写输入	此标志用于启用手写输入。默认情况下，即使不使用此选项，只要手写引擎位于正确的插件文件夹中，它也会自动激活。但是，如果 MyScript 和 Cerence SDK 共存，则必须配置 [no\|myscript-hwr\|cerence-hwr] 中的一个选项。example-hwr选项需要显式启用。此操作可用于开发和测试目的。
[-no]-vkb-arrow-keynavigation		启用或禁用键盘的箭头键导航功能	允许使用方向键和回车键控制键盘。此功能默认处于关闭状态。
-vkb-style	[standard\|retro]	选择虚拟键盘的样式	Qt Virtual Keyboard 支持两种样式：标准和复古。两种样式都会包含在软件包中，但此选项允许您更改内置的默认样式。
[-no]-vkb-sound-effects		启用或禁用音效	此选项用于启用或禁用音效支持。该功能取决于多媒体模块，当该模块可用时，此功能会默认启用。请注意，实际的音效文件由键盘样式定义，因此仅启用此选项并不会使音效可听。
[-no]-vkb-cangjie		启用或禁用繁体中文的仓颉输入法。	此选项用于启用或禁用繁体中文的仓颉输入法。如果已启用繁体中文支持，则该输入法默认处于启用状态。
[-no]-vkb-zhuyin		启用或禁用繁体中文的注音输入法。	此选项用于启用或禁用繁体中文的注音输入法。如果启用了对繁体中文的支持，则该输入法默认处于启用状态。
[-no]-vkb-desktop		启用或禁用桌面集成	默认情况下，当目标环境为 X11 或 Windows 桌面时，桌面集成功能处于启用状态。使用此选项可禁用桌面集成功能。注意：对于嵌入式集成（即由应用程序实例化InputPanel 的情况），无需显式使用此选项。如果应用程序在焦点设置到输入字段之前创建了InputPanel ，则虚拟键盘不会创建桌面输入面板。
[-no]-vkb-layouts		启用或禁用内置布局	默认情况下，虚拟键盘插件包含英语键盘布局。通过指定-no-vkb-layouts，可将内置布局从虚拟键盘插件中排除。注意：在此情况下，应在运行应用程序之前，将`QT_VIRTUALKEYBOARD_LAYOUT_PATH` 环境变量设置为包含自定义键盘布局的文件系统目录。
-vkb-hunspell	[no\|3rdparty\|system]	选择 Hunspell 集成方式	强制将 Hunspell 集成方式设置为指定的选项。选项3rdparty会使用虚拟键盘存储库中的项目文件，选择 Hunspell 源代码的本地构建版本。此选项要求已将 Hunspell git 存储库克隆到src/plugins/hunspell/3rdparty/hunspell目录中。“system”选项通过pkg-config选择系统软件包。“no”选项禁用Hunspell插件。
-vkb-no-bundle-pinyin	不适用	禁用拼音资源的打包	此选项将拼音资源从插件二进制文件中排除。此选项可用于减小插件二进制文件的大小。
-vkb-no-bundle-tcime	不适用	禁用 tcime 资源的打包	此选项将 tcime 资源从插件二进制文件中排除。此选项可用于减小插件二进制文件的大小。
-vkb-cerence-sdk	cerence/sdk的路径	配置 Cerence SDK 的位置，并启用 Cerence 手写识别和 XT9 集成。	必须使用src/plugins/cerence/unpack.py脚本解压 Cerence SDK 的 zip 文件。默认情况下，SDK 将解压到src/plugins/cerence/sdk 目录，构建脚本可自动从中获取相关文件。不过，通过unpack.py脚本的第二个参数，可以指定SDK的其他位置。在这种情况下，必须使用-vkb-cerence-sdk命令行参数将该位置传递给构建脚本。
-vkb-cerence-static	手写	启用 Cerence 手写识别引擎的静态链接。	Cerence 手写识别引擎默认采用动态链接。请使用-vkb-cerence-static强制静态链接。
-vkb-bundle-cerence-hwr或-vkb-bundle-cerence	不适用	启用 Cerence 手写识别资源的打包	此选项将 Cerence 手写识别资源打包到插件二进制文件中。
-vkb-bundle-xt9或-vkb-bundle-cerence	不适用	启用 XT9 资源打包	此选项将 XT9 资源打包到插件二进制文件中。
-vkb-myscript-sdk	path/to/myscript/sdk	配置 MyScript Text SDK 的位置并启用 MyScript 手写功能集成。	解压到src/plugins/myscript/sdk 目录的 MyScript Text SDK（zip 包）可被构建脚本自动识别。不过，该 SDK 也可放置在其他位置。在这种情况下，必须通过`-vkb-myscript-sdk` 命令行参数将位置传递给构建脚本。
-vkb-myscript-arch	[x86\|x64\|armv7hf\|armv7\|arm64]	配置目标 CPU 架构	MyScript Text SDK 为不同的 CPU 架构提供了共享（动态）库——Linux 版本支持[x86\|x64\|armv7hf\|armv7\|arm64]，Windows 版本支持[x86\|x64]。该设置可自动配置。不过，用户也可以使用`-vkb-myscript-arch` 命令行参数指定目标 CPU 架构。

Hunspell 集成

默认情况下，除非找到 Hunspell 库和开发头文件，否则HunspellInputMethod将不可用。对于 Linux/X11 目标平台，可通过安装 libhunspell-dev 软件包来提供 Hunspell 库。或者，可以将 Hunspell git 仓库克隆到src/plugins/hunspell/3rdparty/hunspell目录中。qmake 会自动检测源代码，并配置项目以使用本地的 Hunspell。如果使用 Hunspell 源代码，则还必须将词典文件复制到src/plugins/hunspell/3rdparty/hunspell/data目录中。

以下列出了设置 Hunspell 源代码和词典文件后，目录结构应呈现的示例：

3rdparty
└── hunspell
    ├── data
    │   ├── en_GB.aff
    │   └── en_GB.dic
    ├── hunspell <-- Hunspell git repository
    └── CMakeLists.txt

Cerence 手写识别集成

Cerence 手写集成支持字母输入引擎和 CJK（中日韩）输入引擎。这两个引擎均通过 T9WriteInputMethod 进行集成。输入法每次仅初始化一个引擎，引擎选择会根据当前输入区域设置自动进行。

Cerence 手写识别兼容性

Qt Virtual Keyboard 兼容 Cerence 手写识别 v8.7 或更高版本。

Cerence 手写识别构建准备

必须使用位于cerence目录中的unpack.py脚本解压 SDK 内容。这可确保建立正确的目录结构，以便 CMake 能找到相关内容。

$ cd src/plugins/cerence/
$ python unpack.py filename.zip

此操作将内容解压到src/plugins/cerence/sdk目录，CMake 可以自动识别该目录。

此外，您也可以通过在命令行中添加额外参数，将内容解压到任何其他目录。在这种情况下，必须将 SDK 的位置传递给configure脚本。

configure ... -vkb-cerence-sdk /path/to/cerence/sdk

Cerence SDK 的结构

解压后的 SDK 内容结构如下：

sdk
├───t9write
│   ├───api
│   ├───data
│   │   ├───arabic
│   │   ├───hebrew
│   │   └───thai
│   └───lib
│       ├───linux
│       │   ├───arm64
│       │   │   ├───shared
│       │   │   │   ├───alphabetic
│       │   │   │   └───cjk
│       │   │   └───static
│       │   │       ├───alphabetic
│       │   │       └───cjk
│       │   └───x86_64
│       │       ├───shared
│       │       │   ├───alphabetic
│       │       │   └───cjk
│       │       └───static
│       │           ├───alphabetic
│       │           └───cjk
│       └───win32
│           ├───x86
│           │   ├───shared
│           │   │   ├───alphabetic
│           │   │   └───cjk
│           │   └───static
│           │       ├───alphabetic
│           │       └───cjk
│           └───x86_64
│               ├───shared
│               │   ├───alphabetic
│               │   └───cjk
│               └───static
│                   ├───alphabetic
│                   └───cjk
└───xt9
    ├───api
    ├───data
    └───lib
        ├───linux
        │   ├───arm64
        │   │   ├───shared
        │   │   └───static
        │   └───x86_64
        │       ├───shared
        │       └───static
        └───win32
            ├───x86
            │   ├───shared
            │   └───static
            └───x86_64
                ├───shared
                └───static

各目录的具体内容如下：

目录	描述	备注
api	该目录应包含所有 API 文件	API 文件通常位于 SDK 的“api”和“public”目录中，但有时也会位于“demo”目录中。当同时使用字母引擎和 CJK 引擎时，任何重叠的文件都可以从任一 SDK 中复制过来。
data	该目录应包含所有 HWR 数据库，以及可选的 XT9 数据库。	Cerence Handwriting Alphabetic 的 HWR 数据库： _databas_le.bin Cerence 手写 CJK 的 HWR 数据库： cjk_HK_std_le.hdb香港中文 cjk_J_std_le.hdb日语 cjk_K_mkt_le.hdb韩语 cjk_S_gb18030_le.hdb简体中文 cjk_T_std_le.hdb繁体中文语言数据库：文件扩展名可以是.ldb或.phd
lib/<目标>/<链接方式>/<引擎变体>	存放受支持的目标构建的目录结构。	这些目录应包含所需的目标库。如果同时存在共享库和静态库，则优先使用共享库。

描述

备注

api

该目录应包含所有 API 文件

API 文件通常位于 SDK 的“api”和“public”目录中，但有时也会位于“demo”目录中。

当同时使用字母引擎和 CJK 引擎时，任何重叠的文件都可以从任一 SDK 中复制过来。

data

该目录应包含所有 HWR 数据库，以及可选的 XT9 数据库。

Cerence Handwriting Alphabetic 的 HWR 数据库：

_databas_le.bin

Cerence 手写 CJK 的 HWR 数据库：

cjk_HK_std_le.hdb香港中文
cjk_J_std_le.hdb日语
cjk_K_mkt_le.hdb韩语
cjk_S_gb18030_le.hdb简体中文
cjk_T_std_le.hdb繁体中文

语言数据库：

文件扩展名可以是.ldb或.phd

lib/<目标>/<链接方式>/<引擎变体>

存放受支持的目标构建的目录结构。

这些目录应包含所需的目标库。如果同时存在共享库和静态库，则优先使用共享库。

当检测到 Cerence SDK 时，Cerence 手写识别和 XT9 集成代码将自动激活。

在构建 Cerence 扩展之前，应从[qtbase]/plugins/virtualkeyboard目录中清除所有其他扩展，以避免运行时发生冲突。Cerence 扩展无需任何其他虚拟键盘插件即可正常运行。

XT9 的手写数据库和语言数据库安装在[qtbase]/qtvirtualkeyboard/cerence目录中。此外，还有两种其他方式可以定位这些文件：

通过环境变量定义的自定义运行时位置
使用-vkb-bundle-cerence命令行选项将资源嵌入插件二进制文件中

MyScript Text SDK 集成

MyScript Text 专为构建支持手写文本识别的应用程序而设计。MyScript Text 支持孤立字符、连笔字、印刷体以及重叠书写的识别。 MyScript 重叠书写功能已集成到Qt Virtual Keyboard 中。它能够识别层层叠写的字母、单词或单词片段，且连续片段之间无需明确分隔。该功能可在内存和 CPU 资源受限的设备上运行。

MyScript Text SDK 支持的手写输入样式

最终用户可以将一个单词片段书写在另一个之上，或者将一个字符书写在另一个之上，如下图所示。两个书写单词之间的空格会自动添加，因此无需进行明确的手势操作。

将一个字符书写在另一个字符之上

将单词片段书写在其他片段之上

MyScript Text SDK 支持的语言

MyScript Superimposed 支持 72 种语言。

MyScript Text SDK 软件包安装

MyScript交付团队可为您提供包含各种.zip 归档文件的软件包。若要获取构建您自己的手写应用程序所需的所有代码、工具和资源，请将所有软件包解压到与src/plugins/myscript/sdk相同的目标文件夹中，这样CMake可以自动识别这些文件。

此外，您也可以将软件包解压到任何其他目录。在这种情况下，必须将 SDK 的位置传递给configure脚本。

configure ... -vkb-myscript-sdk /path/to/myscript/sdk

文件结构应如下所示：

myscript
└── sdk
    ├─── conf
    ├─── doc
    ├─── edk
    ├─── engine
    │   └─── bin
    │       ├─── lin-arm64
    │       │   └─── *.so
    │       ├─── lin-armv7
    │       │   └─── *.so
    │       ├─── lin-armv7hf
    │       │   └─── *.so
    │       ├─── lin-x64
    │       │   └─── *.so
    │       ├─── lin-x86
    │       │   └─── *.so
    │       ├─── win-x64
    │       │   └─── *.dll
    │       ├─── win-x86
    │       │   └─── *.dll
    │       (etc.)
    ├─── rdk
    ├─── resources
    │   ├─── ar
    │   │   └─── *.res
    │   ├─── en_GB
    │   │   └─── *.res
    │   ├─── ja_JP
    │   │   └─── *.res
    │   ├─── ko_KR
    │   │   └─── *.res
    │   ├─── zh_CN
    │   │   └─── *.res
    │   (etc.)
    ├─── tools
    └─── voim
        ├─── api
        ├─── bin
        │   ├─── lin-arm64
        │   │   └─── *.so
        │   ├─── lin-armv7
        │   │   └─── *.so
        │   ├─── lin-armv7hf
        │   │   └─── *.so
        │   ├─── lin-x64
        │   │   └─── *.so
        │   ├─── lin-x86
        │   │   └─── *.so
        │   ├─── win-x64
        │   │   └─── *.dll
        │   ├─── win-x86
        │   │   └─── *.dll
        │   (etc.)
        └─── conf

各目录内容的说明如下：

目录	描述
conf	包含引擎用于配置语言资源的语言配置文件。
doc	包含 HTML 文档文件。文件`index.html` 显示主页面。
edk	包含引擎开发工具包（Engine Development Kit）以及每种受支持编程语言 API 的手写编程组件，包括代码示例。
engine	包含各个引擎对象的库，根据目标平台的不同，可能是 SO、A 或 DLL 格式。
rdk	包含资源开发工具包（Resource Development Kit），即用于创建自定义资源的工具和示例。
资源	包含扩展名为 /c .res 的资源文件。这些是二进制资源，由各种 MyScript 技术在运行时使用，以实现各种识别任务。
工具	包含有用的编程工具，包括用于墨迹测试的 InkTool。
voim	包含 MyScript 文本输入法的库。这是对 MyScript 文本识别系统的扩展 SDK，旨在帮助开发者轻松、快速地构建基于手写识别的输入法。

设置 MyScript Text SDK 的证书

使用 MyScript Text SDK 必须具备有效的证书。这是一项安全措施，用于唯一标识您作为 MyScript 技术的合法客户。该证书有助于 MyScript 追踪客户身份及已购买的产品。

证书包含在[your_login].vo.zip package 中。解压该包后，证书会自动放置在相应位置。这可确保证书在您所获得的服务和代码示例中立即可用。

如何使用 MyScript Text SDK 构建Qt Virtual Keyboard

当检测到 MyScript Text SDK 时，MyScript 集成代码会自动激活。

MyScript Text SDK 的语言资源安装在[qtbase]/qtvirtualkeyboard/myscript目录中。

静态构建

Qt Virtual Keyboard 可以进行静态构建，并与应用程序静态链接。这意味着 Qt 也需进行静态构建（通过在 configure 命令行中使用 -static 选项）。

Cerence XT9 高级输入部署指南

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.