靓企鹅·中州韵 用户指南（Rime-only 版）

适用范围：本仓库 fx-rime-only 分支构建的 Android 应用（应用 ID org.fcitx.fcitx5.android.fx.rime；简繁中文显示名"靓企鹅·中州韵"，其他语言显示 Fcitx5.fx.rime）。本文面向普通用户，说明安装、迁移、Rime 配置、键盘布局、宏、主题、剪贴板同步、更新与常见问题。

交接报告、实施方案 和 可行性报告 是维护者交接或历史方案资料，不应作为当前版本的用户操作手册。若本文与应用实际界面不一致，请以当前版本界面和发布说明为准。

1. 这个版本是什么

Fcitx5.fx.rime 是一个将 Fcitx5、Rime（中州韵）和 Android 输入法界面集成在同一 APK 中的版本：

• 不需要另外安装 Rime 插件 APK；
• Rime 是本版本唯一的输入引擎；
• 首次启动时应用会自动安装一批内置键盘布局、键盘主题和图标主题（由社区群友贡献，开箱即用，无需手动导入），并内置了一套默认弹出字符定义；这些资源可以在设置中正常修改或删除，应用不会覆盖用户改动；
• 保留自定义键盘布局、宏、主题、候选栏、剪贴板、语音入口、远端剪贴板同步和更新检查等 Android 侧功能；
• 不再提供原版中的拼音、码表及其他输入引擎页面；
• “语言键”默认不轮换 Fcitx 输入法，而是向 Rime 发送一次 Shift，由 Rime 的 ascii_mode 规则处理中英文切换；长按或专用动作仍可打开系统输入法选择器。

Rime 的“方案”（schema，例如朙月拼音、仓颉、五笔）和应用的“键盘布局”不是同一件事：

• Rime 方案决定输入规则、词典、候选和中英文状态；
• 键盘布局决定屏幕上有哪些键、每个键显示什么以及点击、滑动、长按后执行什么动作。

2. 安装与首次启用

2.1 安装前

1. 从可信发布页面取得与设备 ABI 匹配的 APK。目前项目 CI 主要验证 arm64-v8a；其他 ABI 是否提供，以具体发布产物为准。
2. 如果是覆盖安装，请确认 APK 的包名和签名与已安装版本一致。签名不同的 APK 不能直接覆盖。
3. 如果从其他包名或其他 fork 迁移，请先在旧应用中导出用户数据，参见第 4 节。

Android 可能提示“允许安装未知应用”。只应为当前使用的文件管理器或浏览器临时授权；安装后可以关闭该授权。

2.2 启用输入法

首次打开应用会显示两步设置向导：

1. 点 启用输入法，在 Android 的“语言和输入法/屏幕键盘”设置中启用 Fcitx5.fx.rime；
2. 返回应用，点 选择输入法，将它选为当前输入法。

也可以在任意文本框中通过系统输入法切换按钮重新选择。首次启动时应用会自动预置 Rime 为默认启用的输入法，通常无需手动添加。

2.3 首次启动 Rime

首次启用或更新内置 Rime 数据后，应用需要初始化 Fcitx5 与 Rime。第一次出现键盘可能比平时慢。初始化期间请不要反复结束进程或连续点击“重启 Fcitx 实例”。

进入任意文本框，能够看到键盘并输入候选，即表示基础安装完成。

3. 主设置页速览

设置首页顶部有搜索框，下方按「日常调整 / 按需进入」两组排列。

3.0 搜索设置项

首页顶部的搜索框可以直接搜设置项，支持中文名、英文别名与拼音：

• 输入即搜，结果实时刷新；每条结果下方标注它所在的层级路径。
• 多个词之间是**「都要命中」**的关系，例如输入「空格 长按」会收敛到空格键长按行为这一项，而不是把所有含"空格"或含"长按"的项都列出来。
• 匹配范围包括设置项名称、所在页面路径、以及预置的同义词（如「键盘高度」可搜 height、gaodu）。
• 点击结果直接跳到对应设置页，并自动滚动到那一项（例如搜「键盘高度」，进「键盘 → 布局与尺寸」后会直接定位到该行）。属于主题「配置」页的项还会自动切到该页。
• 有搜索结果时，按返回键（或左上角箭头）先退出搜索、回到未搜索的设置主页，需要再按一次才离开设置页。
• 从搜索结果进入子页面再返回时，搜索结果仍在，可以继续查看其它结果。
• 清空输入框即恢复常规列表。
• 搜索框不会在进入设置页时自动获得焦点，因此不会一进来就弹出键盘；需要搜索时点一下输入框即可。

3.1 日常调整

入口	用途
输入与候选	中州韵设置、全局选项、候选栏样式、候选窗口
键盘	键盘、按键和工具栏设置（含工具栏大小）、分体/浮动/单手键盘、键盘布局自定义（含弹出字符设定）
外观	主题、图标主题、字体设定
便捷功能	剪贴板（含远端同步入口）、文本编辑、表情和符号、语音输入

3.2 按需进入

入口	用途
数据与备份	浏览用户数据目录、导出/导入完整用户数据
高级	附加组件、隐藏快捷键配置等兼容性开关、开发者选项

其中 输入与候选 下有两页由引擎直接提供的原始配置项：

入口	用途
中州韵设置	Rime 引擎配置、方案/目录及部署或同步动作（实际项目取决于当前 Rime 配置描述）
全局选项	Fcitx 全局行为（触发键、共享输入状态等）

附加组件在 高级 里：查看本 APK 中保留的 Fcitx 组件；Rime-only 不代表列表一定完全为空。

2026-09-29 调整：原先这三页统一收在「高级 → 引擎配置」二级入口下，而该入口本身还要再点一层。现在按「用户想调什么」重新分层——中州韵设置与全局选项调的是怎么输入，与候选栏同属「输入与候选」；附加组件是引擎侧插件管理，与兼容性开关一起留在「高级」。「引擎配置」这一层已取消，路径比原先少一次点击。

这些页面由引擎的配置描述树自动生成。若某项目没有提供中文描述，界面会直接显示引擎内部键名（例如 HiddenNotifications），这是上游的限制。

应用主页右上角菜单还有「常见问题」「开发者」「关于」三项；「关于 → 当前版本」可检查更新。

设置名称可能随系统语言和版本略有变化。

3.2.1 工具栏大小

路径：应用主页 → 键盘 → 工具栏 → 工具栏大小。

默认 100%，可调范围 80%–200%，每次增减 10%。

• 栏高与图标一起缩放：调大后工具栏整体变高、按钮上的图标也随之变大；调小则相反。
• 横向占用宽度不变：放大只吃掉图标周围的留白，每个按钮占的位置（44dp）不随百分比变化。因此调到 200% 也不会让中间那排按钮变少或退回横向滚动——200% 时图标约 40dp、留白约 2dp，100% 时图标 24dp、留白 10dp。
• 候选项字号和候选格子的宽度不会跟着变：它们是候选栏自己的参数，只受 应用主页 → 外观 → 字体设定 里的候选字号（cand_font）和候选栏自身设置影响。
• 想让候选字变大：正确顺序是先把工具栏调高（给候选行腾出高度），再去「字体设定」调大候选字号。只调字体设定会被候选行的高度卡住——候选文字的高度自动缩放只会缩小、不会放大。
• 下限是 80%：工具栏同时承载状态区、隐藏键盘等按钮，再小按钮就不好点了。

搜索框里搜「工具栏大小」「候选栏」「候选大小」都能找到这一项（见 3.0 节）。

3.3 浮动键盘、单手键盘与分体键盘

路径：应用主页 → 键盘 → 分体、浮动与单手键盘。

浮动与单手键盘此前只能通过工具栏或状态区按钮触发、设置里没有入口，现已补上；分体键盘的开关也在这页里：

• 浮动键盘：键盘脱离屏幕底部，可拖动位置、拖动右下角手柄缩放。
• 单手键盘：键盘缩窄到一侧，方便单手拇指触达；可设置靠左还是靠右。
• 两者互斥——开启其一会自动关闭另一个。
• 用开关关闭后，键盘恢复为常规停靠状态；开关状态与工具栏按钮同步。
• 横屏时自动使用浮动键盘（同页 浮动键盘 → 横屏时自动使用浮动键盘，默认关闭）：打开后，屏幕转到横屏时会自动换成浮动键盘，转回竖屏再自动恢复成原来的停靠或分体形态。它有两条明确的边界：你已经手动开了浮动或单手键盘时它不介入（尊重你的选择）；调整键盘模式下也不介入。它永远不会覆盖或改写你手动选的形态——横屏只是临时借用浮动形态，不会把「我想用浮动键盘」写进设置，所以转回竖屏一定能恢复原样。
• 分体键盘：键盘较宽时（平板、折叠屏展开、横屏）自动左右分体，便于双手持握时用两根拇指打字。同页可设置中缝宽度（校准）、分体时是否采用横屏布局参数、奇数字符行是否复制中间键，以及是否强制左右两半在中缝处对齐（详见 6.10 节）。

3.4 手动选择主题

路径：应用主页 → 外观 → 主题 → 配置。

• 手动选择的主题：关闭「跟随系统夜间模式」后生效的主题。开启跟随时该项置灰（此时改它不会生效，界面会明确显示为不可用）。
• 亮色模式主题 / 暗色模式主题：跟随系统夜间模式时，按系统当前明暗分别使用。
• 也可以在主题列表里直接点选一张卡片；若「跟随系统夜间模式」开着，会先询问是否关闭它再切换。

3.5 密码输入框中的工具栏

路径：应用主页 → 虚拟键盘 → 工具栏 → 输入密码时在工具栏上显示数字行。

• 开启后，字母类密码输入框在没有更高优先级内容时显示可点击的数字行；数字按键使用主题的普通按键文字颜色,字体与字号跟随虚拟键盘的按键字体设置。数字行文字不参与键盘"文字大小"缩放,避免在工具栏高度内被缩到不可见。
• 关闭后，密码输入框隐藏普通工具栏按钮及其点击区域，只保留最右侧的收起键盘按钮。
• 纯数字密码框已经使用数字键盘，因此不重复显示工具栏数字行；普通工具栏按钮仍保持隐藏，只保留收起键盘按钮。
• 剪贴板提示与内联建议沿用原有优先级；它们消失后再回到上述密码工具栏状态。

3.6 文本编辑

路径：应用主页 → 便捷功能 → 文本编辑。

「文本编辑」是键盘上那排光标/选择/剪切复制粘贴按键所在的底部栏（工具栏上的光标按钮也直接打开它）。这一页决定它用哪种风格、手势参数如何、提示文字写什么。

• 文本编辑风格：默认是传统底部栏；选 Foxy 滑动风格 后换成 Foxy 输入法那种触控板式光标——按住光标键滑动即可移动光标，长按先进入选取模式，之后继续滑动就是选中文字，松开结束选取。切换风格后需要打开一次文本编辑底部栏才会看到变化。
• Foxy 光标移动步长：滑动多少距离移动一格光标，默认 18dp，可调 4–80dp。调小更细腻、调大更快。
• Foxy 长按选取延迟：按住多久进入选取模式，默认 300 毫秒，可调 100–1200 毫秒（步进 10）。手速快就调小，容易误触选字就调大。
• 四条提示文案（移动 / 长按 / 选取中 / 松开结束选取）：触控板上显示的手势提示语。留空则使用内置提示文字，只有 Foxy 滑动风格下才可编辑。
• 编辑 Foxy 底部布局：直接跳到键盘布局编辑器里那份 text_editor 布局。底部栏上有哪些键、键的顺序与宽度，全部由这份布局决定，改它不需要改代码；编辑器里的预览和真机键盘用的是同一套按键解析，所以编辑器里是什么样，真机上就是什么样。

只有 Foxy 滑动风格下才需要管步长、延迟和提示文案；用默认风格时这些项是灰的。 text_editor 也是「键盘布局自定义」里可编辑的布局之一，可以从那边进入同一份文件（见第 6 节）。

4. 升级、备份与迁移

4.1 同包名覆盖升级

正常覆盖安装会保留应用数据。建议升级前仍执行一次手工导出，尤其是在以下情况下：

• 跨越多个版本；
• 更换 fork、签名或包名；
• 修改过 Rime YAML、键盘布局、宏、主题或自定义图标；
• 剪贴板历史中有需要保留的固定内容。

升级后如果界面正常但 Rime 行为未更新，可按顺序尝试：

1. 在 中州韵设置中执行部署；
2. 关闭并重新打开一个输入框；
3. 在 开发者入口中使用 重启 Fcitx 实例；
4. 仍不正常时再检查用户 YAML 和日志。

不要把“删除并同步运行数据”当作普通刷新按钮；它会重建应用部署的运行数据，应在已经备份后用于修复损坏或版本残留。

4.2 导出完整用户数据

路径：应用主页 → 数据与备份 → 导出用户数据。同页还有 浏览用户数据目录，可用系统文件浏览器直接查看应用的全部数据文件（中州韵设置里的用户数据目录入口长按也可直达 Rime 目录）。

应用会生成 ZIP，内容包括主要偏好设置、剪贴板数据库和外部用户文件。导出前会请求 Fcitx 保存状态。

重要提示：

• 备份 ZIP 未加密；其中可能包含剪贴板历史、布局、主题、Rime 用户文件及同步设置；
• 不要上传到公开网盘、聊天群或 issue；
• 如果必须放入云盘，请先用可信工具加密；
• 导出完成后，建议在文件管理器中确认文件大小不为 0，并保留至少两份副本。

4.3 导入完整用户数据

路径：应用主页 → 数据与备份 → 导入用户数据。

1. 选择此前导出的 ZIP；
2. 确认覆盖提示；
3. 应用会停止 Fcitx、覆盖本地设置和输入历史，然后要求重启；
4. 重启后检查 Rime 方案、键盘布局、主题和剪贴板历史。

注意：

• 导入会覆盖当前本地设置与输入历史；先导出当前状态再操作；
• 来自更新版本的剪贴板数据库可能无法导入，应先把当前应用升级到不低于备份来源的版本；
• 导入过程不是“合并”，不要期望同时保留两边的同名布局或主题；
• 不要导入来源不明的 ZIP。

4.4 从其他 Fcitx5 Android 版本迁移

当前导入器接受以 org.fcitx.fcitx5.android 开头的构建变体备份（含原版、fxliang fork 与本版），并会处理包名相关的偏好文件名。推荐流程：

1. 在旧应用中导出完整用户数据；
2. 在新应用中完成首次启用，确认键盘可以出现；
3. 在新应用中先导出一份空白基线备份；
4. 导入旧备份并按提示重启；
5. 检查 Rime 用户目录、当前方案、布局、主题和剪贴板；
6. 确认无误后再卸载旧应用。

从非 Rime-only 版本迁移时，其他输入引擎的配置可能仍存在于备份中，但本版本不会加载已删除的引擎。不要把旧版拼音词典、码表入口或插件说明当作本版本功能。

4.5 只迁移 Rime 配置

如果不想覆盖整个应用，可只迁移 Rime 用户文件：

1. 在 中州韵设置中找到用户数据目录入口；
2. 点按后会打开应用的 DocumentsProvider（浏览全部应用数据）；长按该入口可直接打开当前 profile 对应的物理目录（默认目录是 data/rime，若在 Rime 设置里切换过配置目录，以长按打开的位置为准）；
3. 复制需要的 *.yaml、用户词典及其他 Rime 文件；
4. 返回设置执行 部署。

不要覆盖不理解的编译产物或运行数据库。迁移到新设备时，优先复制自己维护的 YAML 和词典源文件，再让 Rime 重新部署。

5. Rime 方案与用户配置

5.0 本版本不预置任何输入方案（首次安装须知）

本版本 不随 APK 附带任何输入方案，也不附带预置词汇表 essay.txt，只附带 Rime 的通用预设资源（default.yaml、key_bindings.yaml、punctuation.yaml、symbols.yaml）。

因此首次安装并启用后，键盘可以正常弹出，但没有任何可用的输入方案，打不出汉字——这是预期行为，不是故障。

要开始使用，请自行准备方案，按以下步骤操作：

1. 把方案文件（*.schema.yaml，含其依赖的 *.dict.yaml 等）放入 Rime 用户数据目录。可在 中州韵设置 中打开用户数据目录，路径为应用外部文件目录下的 data/rime。

2. 在同目录新建或编辑 default.custom.yaml，在其中 patch schema_list 列出你要用的方案，例如：

   patch:
     schema_list:
       - schema: your_schema

3. 回到 中州韵设置 执行部署，等待完成。

4. 部署成功后即可通过方案选单（默认 Control+grave 或 F4）切换使用。

注意事项：

• 方案若引用了 symbols（标点）、key_binder（按键绑定）等预设资源，本版本已随包提供，无需自行补装。
• 若方案追求更好的候选排序，可自行准备 essay.txt（Rime 官方「八股文」词频表，来自 rime/rime-essay），放进同一个用户数据目录即可生效。方案通常以 use_preset_vocabulary: true 声明依赖它；这个文件缺失不会导致部署失败，只是词典会少一批预置短语与词频，候选排序质量下降。
• 如果 schema_list 里列出的方案文件不存在，部署会失败并提示缺少输入方案；请先确认文件名与 schema_id 与清单一致。
• 升级应用不会删除你放在用户数据目录中的方案。

5.1 选择或配置方案

进入 中州韵设置。该页面由 Rime/Fcitx 提供的配置描述动态生成，不同内置数据版本显示的选项可能不同。

常见操作包括：

• 选择启用的输入方案；
• 设置当前 profile 或用户数据目录；
• 执行部署；
• 执行用户数据同步；
• 调整 Rime addon 暴露的其他选项。

修改方案文件后通常需要重新部署才会生效。

5.2 使用补丁文件

Rime 通常建议用 *.custom.yaml 覆盖配置，而不是直接修改内置方案。例如：

default.custom.yaml

your_schema.custom.yaml

这样升级内置数据时更容易保留自定义内容。具体键名取决于所用方案，请参考该方案自己的文档。

5.3 部署与同步不是一回事

• 部署：读取 YAML 和词典源文件，生成当前设备使用的运行数据。修改配置后使用。
• 同步：把 Rime 用户数据与同步目录交换，用于用户词典等数据的迁移或备份。
• 应用完整备份：导出应用设置、数据库和外部文件，是本应用层面的整包备份。

三者不能互相替代。为了避免退出输入法时长时间卡顿，本版本不会在每次退出时强制执行完整 Rime 同步；重要数据请主动同步并定期导出完整备份。

部署期间打字会怎样（2026-09-28 起的行为）：部署进行时，键盘的预编辑/候选区会显示 「正在部署」，此期间按下的字母会被丢弃——不会进入编码区，也不会再被当作普通字符直接上屏。等提示消失后再打字即可。首次安装、改了配置或新增了词典时都会走这条路径；从其它输入法切回来时也会短暂出现。

这一条在此前版本里是明显的问题：部署期间的按键既没进编码区，又被当成普通字符灌进输入框，表现为「刚切回来打前几个字母，字母没进编码，却直接出现在文字里」。现已修好，且冷启动不会再每次都触发一次全量部署（只有配置真的变了才部署）。

5.4 中英文切换

默认语言键向 Rime 发送一次 Shift，由 Rime 的 ascii_composer/ascii_mode 配置决定行为。长按语言键则弹出 Rime 方案选单，点选即切换方案（与工具栏的「方案选单」按钮同一入口）。如果语言键不能按预期切换：

1. 检查当前方案是否定义 Shift 切换；
2. 检查 ascii_composer 配置；
3. 确认没有把该键改成其他宏动作（长按已被方案选单占用，自定义布局里的语言键需自行保留或覆盖该行为）；
4. 如需切换到另一款 Android 输入法，请长按工具栏的语言切换按钮打开系统输入法选择器，而不是期待语言键切换 Fcitx 内部引擎。

5.5 长按退格的保护范围

长按退格把输入区（拼音编码）删空之后，继续按住不会再删除已经上屏的正文，直到手指抬起。这是有意设计，用来避免连续退格越过编码区边界、把正文一起删掉，与万象拼音 super_processor/enable_backspace_limit 的桌面行为一致。

• 手指抬起后再按退格，恢复正常删除（删正文）；抬手瞬间的轻微回弹按压不会误删。
• 单次退格，以及输入区本来就是空的时候按退格删正文，都不受影响。
• 进入保护后被拦下的那些退格不再产生按键反馈：如果开启了「长按重复时震动」，删空编码前的重复退格照常震动，删空进入保护后的重复退格不再震动，作为"已经删到底、不会再删正文"的手感提示。删码起始的按键音只在按下时响一次，长按过程本就不重复播放，不受影响。
• 该保护由本应用实现：万象的 Lua 处理器在移动端会被平台判断跳过，而空输入区的退格在本实现里会直接落到编辑器正文，因此必须在应用层拦住（详见第 11.14 节）。

5.6 候选词手势：按住上滑选字、按住下滑呼出菜单

在候选词上按住（判定时间与按键长按一致，即设置里的「长按延迟」，默认 300 ms）：

• 按住向上滑：弹出选字窗，把该候选按字拆开；滑到哪个字就高亮哪个，抬手提交该字；把手指移出选字窗再抬手则取消，不提交任何字符。
• 按住向下滑：呼出该候选的操作菜单（如「忘记词汇」）。
• 按住不动直接抬手：仍是原有长按菜单，与改动前一致。
• 没有按住就上下滑：仍然是列表自身的滚动，展开的候选列表照常上下翻页。

一次按住只走一个方向：先滑动的那一方生效，之后不再改向，抬手时只执行该方向的动作。

为什么是"按住后再滑"而不是直接滑：直接滑需要在手指刚按下时就夺走触摸，父级候选列表收不到滚动事件，展开候选面板就没法翻页了。改成本手势后，只有按满判定时间才接管触摸，未按住时的滑动完全留给列表。

5.7 退格键上滑清空

长按退格键进入连续删除后，退格键正上方会浮现一条 「上滑清空🆑」 提示条；此时手指不要抬起，直接向上滑进提示条区域，即可一次性清空当前输入框里的全部文字（含已上屏的正文），省去反复退格。

• 触发条件是"长按进入连删 + 手指滑进提示条区域"。提示条只是提示，本身不接收触摸，判定按手指相对退格键的坐标计算：横向为退格键宽度的两倍（以键中心对齐），纵向为键上方一个提示条高度以内。
• 清空通过系统的 InputConnection（全选后覆写空串）完成，不经过 Rime 引擎，因此在任何输入框里表现一致，与当前使用的输入方案无关。
• 滑进提示条触发清空后，抬起手指不会再补一次滑删，不会多删一个字符。
• 清空与第 5.5 节的退格保护互不干扰：清空会把该保护序列一并复位，因此清空后立刻再按退格可以正常删除正文，不会被"白吞"。
• 触发清空时会有一次长按级别的振动反馈（与是否开启「长按重复时震动」无关）。

5.8 符号 / 表情 / 颜文字面板

键盘上的 !?#、:-)、^_^ 等按键（以及数字键盘上的 !?#）会打开符号面板。面板采用左侧分组栏 + 右侧符号网格的布局，并独占整个键盘区域（底部不再有键盘行）：

• 左侧是分组名列表，可上下滚动；点击切换分组，当前分组会高亮。
• 右侧是该分组的符号网格，可上下滚动。符号 / 表情为 6 列；颜文字为单列（颜文字条目很长，多列会把它们缩到看不清）。
• 左栏最底部有两个小键（位置与 Foxy 输入法一致）：
  • ⌨ 返回文字键盘；
  • ⌫ 退格删除，长按可连续删除。
• 顶部的 「最近」 分组记录你最近点选的符号（单个半角 / 全角数字不入列，避免面板一打开就被数字占满）。
• 长按表情键可弹出肤色变体（与「表情和符号」设置里的默认肤色设置配合）。
• 选中即上屏，不经过 Rime 编码，因此在任何输入框、任何输入方案下表现一致。

想在键盘上放一个直达某类面板的按键？ 面板内部不带面板互切键（与 Foxy 一致）， 跳转由布局按键或宏配置：

• 布局：键盘 → 键盘布局自定义 → 修改键盘定义，给某个 LayoutSwitchKey 把 「目标」选成 表情选择器 或 颜文字选择器（另有 符号选择器）；
• 宏：在「切层」动作的目标里选这三个面板，列表里显示为 Symbol（符号面板） / Emoji（表情面板） / Kaomoji（颜文字面板）。

这三个目标写入配置的值就是 Symbol / Emoji / Kaomoji（英文枚举名）， 括号里只是给人看的提示。颜文字面板早期叫 Emoticon，旧配置仍能正常识别， 无需手动改。

工具栏（Kawaii Bar）保持主键盘原样：面板打开时工具栏上的按钮一个都不变， 只有最左侧那个按钮会从「状态区」变成返回箭头，点它即回到文字键盘。

三个面板的数据随 APK 内置，共约 6900 条去重条目：

面板	分组数	条目数
符号	62	4773
表情（Emoji）	10	1926
颜文字	19	999

与旧版的差异：旧版符号 / 表情面板用的是内置硬编码的粗分类（符号 7 类、表情 9 类、颜文字 6 类）， 且用顶部横向标签栏切换。旧版颜文字只有约 254 条，现在增至 999 条；符号从约 584 条增至 4773 条。 「最近使用」的记录会保留，不会因升级而清空。

5.9 自定义符号数据（自定义 catalog）

三类面板的数据默认随 APK 内置，每一类都可以换成你自己的 JSON 文件。

路径：应用主页 → 表情和符号 → 自定义符号数据 / 自定义表情数据 / 自定义颜文字数据。

• 选「内置数据」= 使用随包数据（默认）。
• 选某个自定义文件 = 改用该文件。文件不存在或解析失败时自动回退内置，面板不会变空。
• 点「导入」可从文件管理器挑一个 .json：应用先校验格式再复制到 config/symbol_catalogs/<symbols|emoji|kaomoji>/ 并自动选中（重名自动加序号，不覆盖）。
• 选中的文件被删除后，设置页会提示「自定义文件缺失，改用内置」，面板仍正常工作。

自定义文件格式（与 Foxy 输入法一致）：

{
  "multiLine": false,
  "groups": [
    { "names": { "zh": "我的符号", "zh-Hant": "我的符號", "en": "My symbols" },
      "symbols": ["★", "☆", "✦"] }
  ]
}

• names 是多语言字典：组名按系统语言回退（完整标签 → zh-TW/zh-HK/zh-MO 走 zh-Hant → 语言主标签 → 字典里的第一个值）。只写 "zh" 一项也可以。
• multiLine: true 表示该文件含长条目（颜文字），仅作语义标记——列数由面板决定： 颜文字固定单列，符号与表情固定 6 列。
• 支持 // 行注释（与其它用户 JSON 配置一致）。
• 文件名须以 .json 结尾、总长 > 5、且不含路径分隔符；不合规的文件不会被列出或导入。
• 没有 symbols 条目的分组会被跳过；顶层未知字段会被忽略。

6. 自定义键盘布局

路径：应用主页 → 键盘 → 键盘布局自定义 → 修改键盘定义。

同一页面附近还提供：

• 切换键盘定义配置：在多份布局文件之间切换；
• 新建/重命名/删除布局文件；
• 弹出字符设定（长按按键弹出的字符映射）；
• 数字键盘布局；
• 在线编辑器。

字体设定不在本页：它是外观类设置，入口在 应用主页 → 外观 → 字体设定。 「弹出字符设定」原先也在外观下，后移入本页——它改的是长按按键弹出的字符， 属于键盘的内容定义。

6.0 内置布局与默认弹出定义

首次启动时，应用会自动把一批社区贡献的布局文件安装到布局文件列表中（例如「大同-9+18+26keys」「九键布局」「行之-26键」「行之-万象九键v2」「QM-朝花」「Sandy-数字行26+万象九键」等），并把第一份设为当前布局；首次使用即可在 切换键盘定义配置 里看到并切换它们。

「弹出字符设定」（长按弹出的候选字符，即 config/PopupPreset.json）在没有用户文件时使用应用内置的一套默认定义；只有当你在弹出字符编辑器里保存过自己的版本后，才会整体替换默认定义。

这些内置资源只是普通文件：编辑、重命名、删除都照常工作，应用不会在下次启动时把删掉的文件塞回来。内置资源在后续版本中更新内容时，应用只会替换"从未被用户修改过"的旧内置文件；你改过或换过名的文件始终保留。

内置布局的内容会随版本更新（例如「Sandy-数字行26+万象九键」的 ⌨ 键长按已改为呼出方案选单，「大同-9+18+26keys」不再为各层写死键盘高度、改为跟随全局设置）。这些更新只对你没有改过那份文件时生效：一旦你在编辑器里保存过，该文件就被视为你的版本，之后不再被内置更新覆盖。

6.1 推荐编辑流程

1. 先新建一份布局文件，并选择“复制当前文件内容”；
2. 打开 修改键盘定义；
3. 选择 rime 默认布局或需要的 Rime 子模式布局（见 6.2 节的下拉框说明）；
4. 逐行调整按键、权重、行高、标签和动作；
5. 使用预览或文本测试区检查；
6. 明确点击保存，再到真实输入框验证。

不要直接在唯一一份布局上进行大改。编辑器会在部分保存场景创建备份，但手工导出仍是最可靠的恢复方式。

6.2 全局、Rime 与子模式布局

布局编辑器可存在多层匹配：

• 全局共享布局；
• rime 的默认布局；
• 特定 Rime 子模式/方案的专用布局；
• 数字或符号等子布局。

如果某个方案没有专用布局，会回退到较通用的布局。为多个方案分别定制前，先确认默认 rime 布局工作正常。

子模式下拉框与「默认」项

选中 rime 这类带方案的布局后，编辑器顶部会出现一个子模式下拉框，第一项固定是「默认」，其后才是各个方案名：

• 选「默认」：编辑的是该布局的默认布局，也就是布局文件里 "rime": { "default": [...] } 这一份。它同时是所有没有专用布局的方案在打字时实际使用的布局，改动它会影响这些方案。
• 选某个方案：编辑的是该方案的专用布局。若这个方案还没有专用布局，编辑器会提示"没有专用布局，其按键来自默认布局"，此时删除按钮不会生效——要删除的其实是默认布局，请先切到「默认」项，或先用 + 为该方案新建一份专用布局。

编辑器工具栏的副标题始终显示当前实际编辑的位置（显示为 布局文件:rime 就是默认布局）。打开编辑器时，如果当前方案没有专用布局，下拉框会自动停在「默认」项。

6.3 导入和分享布局

布局编辑器支持二维码分块分享/导入。接收多张二维码时应按提示扫描全部分块；导入结果先进入编辑器内存，仍需保存才会持久化。

建议同时保留完整用户数据 ZIP。二维码适合分享单份布局，不等价于整机备份。

6.4 在线编辑器安全提示

路径：键盘 → 键盘布局自定义 → 在线编辑器（开关式入口，开启后弹窗给出地址）。

该功能会在手机上启动本地 HTTP 服务，供浏览器编辑布局、popup 或主题。当前版本的 LAN 编辑桥不适合在不可信网络中使用：

• 仅在可信的个人 Wi-Fi 或离线热点中短时开启；
• 不要在公司、学校、酒店、商场等共享网络中开启；
• 用完后回到该入口再次点击，在弹窗中 停止服务；
• 不要把编辑器 URL 发给他人；
• 若只需手机内编辑，优先使用内置编辑器。

6.5 空格键的划动动作

空格键和其它按键一样可以在 修改键盘定义 → 选中空格键 → 划动事件 里配置划动动作，并填一个划动标签（填了标签后键面会像其它可划动键一样显示该提示字样）。

需要特别注意的是，空格键的划动与设置里的「划动空格键以移动光标」互斥，开关优先级更高：

• 开关开启（默认）：划动空格键用于移动光标，在这里配置的划动动作不生效；
• 开关关闭：划动空格键触发你配置的划动动作，一次划动只触发一次；触发方向与其它按键的划动一致（默认向下划，可在 虚拟键盘 → 按键行为 → 符号划动方向（符号隐藏时） 里改为向上划或禁用；填了划动标签时，方向跟随该标签在键面上的显示位置）。

按键编辑页在空格键的划动事件旁会直接给出这条提示。若配置后划动没有反应，先到 虚拟键盘 → 按键行为 → 划动空格键以移动光标 把它关掉。两者都不成立时（开关关闭且没配划动动作），空格键不参与划动，按住在空格上移动不会打断长按。

6.6 空格键长按重复输入空格

虚拟键盘 → 按键行为 → 空格键长按行为 里新增了 「重复输入空格（按住连续输入）」 一项：

• 选中后，按住空格键不放即连续输入空格，适合快速缩进、对齐或连打多个空格；抬手立即停止。
• 重复节奏与退格键长按连删一致（按住超过「长按延迟」后开始，之后每 50 ms 一次）；是否震动跟随 反馈 页的「长按重复时震动」。
• 与「按住说话」等其它选项一样是多选一：选了这一项，空格键长按就不再执行原来选中的动作（如轮换输入法、按住说话）。

这一项不影响空格键的划动行为：划动仍由 6.5 节的「划动空格键以移动光标」开关与按键自身配置决定，两者互不干扰。

6.7 宏键的「显示文本」优先于「标签」

宏按键（MacroKey）有两个文字设置，作用不同，容易混淆：

设置	作用
标签	按键的固有名称；显示文本留空时，键面就显示它
显示文本	显示在键面上的文字；填了就以它为准

取值规则：

• 填了显示文本：键面按你填的原样显示。填 A 就是大写 A，不会因为没按 Shift 就被改写成 a。
• 留空显示文本：回落到标签文本，此时如同字母键，随 Shift 变换大小写。
• 单个小写字母的例外：即使填了显示文本，按住 Shift 时它仍会临时显示为大写，松开即恢复原样——这是保留的字母键习惯。填大写字母或多字符（如 全选、Ctrl）则完全不受 Shift 影响。
• 子模式专用布局里可以按方案分别设置显示文本；某个方案没有对应取值时视为「未填写」，回落到标签。

内置的 26 键字母布局中，宏按键的显示文本与标签原本取值完全相同，已统一清除这层冗余：留空即显示标签，键面效果不变。

6.8 分体键盘布局（每个子布局各配一套）

分体键盘每行要在某处断成左右两半，断点在哪、两侧各放什么键，是合体时完全不需要考虑的问题。所以它值得有另一套行集合，而且这套行集合属于某一个具体的子布局——给「倉頡五代」单独配一套分体键位、其它方案沿用默认那份，是这个功能最主要的用途。

入口就在方案下拉框的正下方：勾选 「分体键盘布局」。

情况	勾选后会怎样
当前子布局已经配过分体布局	直接进入它的编辑，行列表与预览都换成那一份
还没配过	先弹一句「『XX』还没有自己的分体布局。要从它当前的排列复制一份、开始编辑吗？」，确认后以当前排列为初值新建

• 勾选框右侧始终提示当前状态：已有独立的分体布局，或者未单独设置，分体时沿用普通布局。
• 长按勾选框会弹出一句完整说明（这一行只有标签和状态，放不下整段话）。
• 「当前子布局」就是你此刻在下拉框里选中的那一项：选「默认」→ 配的是布局本体的分体布局；选「倉頡五代」→ 配的是倉頡五代自己的。切换方案时勾选状态会跟着重新判定，不会出现"以为在改倉頡、其实改的是默认"。
• 勾选状态下工具栏的 🗑 删掉的是这一份分体布局（不是方案布局）；+ 在该状态下置灰——分体布局要么已经被你打开，要么由勾选框负责新建，没有第三种情况。
• 编辑器里的预览会按分体渲染你正在编辑的那份，即使预览框的宽度本不会触发分体。
• 只影响按键怎么排：键盘高度仍由布局高度设置与全局设置控制。

没有配置任何分体布局时，键盘行为与以前完全一致。

在布局文件里长什么样

分体布局写在它所属的那个子布局对象内部，与它的 default 平级：

{
  "rime": {
    "default": [ ... ],
    "__variant__:split": [ ... ],
    "倉頡五代": {
      "default": [ ... ],
      "__variant__:split": [ ... ]
    }
  }
}

查找顺序是先分体、再普通，每一档里都是先当前方案、再布局本体：

1. 当前方案的分体布局 → 布局本体的分体布局；
2. 都没有，就用当前方案的普通布局 → 布局本体的普通布局。

中间那一档（布局本体的分体布局）是必要的：绝大多数方案并不会自己配分体布局，而你在「默认」下配好的那一份，理应继续对新方案生效。

__variant__:split 是机器的内部键名，不会出现在方案下拉框里；请勿把它当成方案名使用。 只有「普通」和「分体」两种排列——横屏不单独占一种。屏幕变宽只是把同一套行拉伸得更宽，键盘高度另有 keyboard_height_percent_landscape 负责。

6.9 指定分体键盘的断点

分体时每一行默认从几何中点断开。行的键宽不均匀、或含空格这类"跨中缝"的键时，自动断点很难预测。在按键编辑页勾选 「分体键盘在本键之后断开」 就能为该行指定断点。

• 只影响分体状态；合体时不受影响。
• 同一行勾了多个时，以最后一个为准。
• 有该标记的行不再自动复制中间键（见「分体、浮动与单手键盘 → 分体键盘 → 分体时复制中间字母键」）：两者是互斥的两种做法，混用会让断点落到意料之外的位置。

6.10 分体键盘按键变窄？关掉中缝强制对齐

路径：应用主页 → 键盘 → 分体、浮动与单手键盘 → 分体键盘 → 强制左右两半在中缝处对齐（默认开启）。

开启（旧行为）：两侧各占键盘宽度的一半，因此每行都在同一位置断开、上下行断点严格对齐。代价是：某一侧键多时，该侧每一枚键都要被压窄才能塞进半宽，于是分体后按键明显比合体时窄。

关闭：两侧各自靠外沿固定，每一枚键都保持它在合体状态下、也保持它在布局文件里写的那个宽度（弹性键同样只按行内剩余空间计算，不受分体影响）。中缝不再是"预留一段固定宽度"，而是两侧排完之后剩下的那块空间：

键盘宽度 = 左半真实宽度 + 中缝 + 右半真实宽度
                          ↑ 这一块是挤出来的，不是设出来的

因此关掉对齐后，中缝的实际宽度会随每一行的内容变化，代价是各行断点位置可能不齐。

如果你觉得"分体后按键变窄了"，把它关掉即可。

用空白占位键把按键往中缝方向挤

关闭对齐之后，行里多出来的宽度会落到哪里是可以控的——这正是「空白占位键」在分体下的主要用法（见 6.11 节）：占位键在它那一侧占住多少宽度，这一侧的所有按键就被整体往中缝方向推多少。

典型场景是让两侧的 G 各向中间凸出一点（配合「分体时复制中间字母键」，asdfghjkl 变成 asdfg‖ghjkl）：

1. 关闭 强制左右两半在中缝处对齐；
2. 在 asdfghjkl 这一行的最左端和最右端各加一枚空白占位键；
3. 占位键的权重宽度填多少，G 就向中缝凸出多少——填 0.05 就各推 5%，想让 G 更靠中间就把它加大。

这个逻辑对分体布局的每一行都成立，不只是 asdfghjkl。 顶行 qwertyuiop、zxcvbnm、你的自定义行、数字行……任意一行、任意一侧加占位键，都会把那一侧往中间推；占位键放在半边的哪个位置都可以（放在最外沿是整半平移，放在中间则让它右侧的键整体内移），位移量恒等于占位键的宽度。

要点：

• 占位键不影响同一行其它按键的宽度。它只按自己的宽度占位，其它键该多宽还是多宽——这一点是特意做的，否则"加键"会变成"把全行压窄一遍"，凸出的效果根本出不来；
• 占位键也不会改变这一行从哪里断开。断点只按"真正会打出字的键"来算，占位键不参与——否则两端各加一枚占位键就会把断点推偏一位，变成只有一侧有 G；
• 反过来，占位键把中缝挤窄了。加到一定程度两侧会贴到一起，此时系统只能重新等比压窄按键（保底留 2% 中缝）。想让 G 凸出而不想挤没中缝，就别把占位键加得太宽；
• 唯一的例外是含空格键的那一行（典型是字母键盘最底下一行）。空格的宽度本来就要跟着中缝走（中缝变宽，空格也变宽，否则拇指按不到），那一行的中缝由空格自己占着，不参与"占位键往中间推"的算法。想在那一行调位置，直接改空格的权重宽度。

6.11 空白占位键

按键类型下拉框里有一项 空白占位键。它不接收任何输入——不是"点了没反应"，而是触摸事件根本不会落在它上面，因此既不震动、也没有按压高亮，也不会挡住同一位置父容器的滚动。

两种用法：

配置	效果
主字符、副字符都留空，关闭「自定义颜色」（默认）	键盘上一块完全看不见的空白
填了字符，或打开「自定义颜色」	纯装饰键：画你指定的字符/配色，但依然点不动

常见用途：

• 调位置：某行想空出一段、或把按键挤到一侧，插一个占位键比改权重更直观；
• 分体时把按键往中缝方向挤：关闭「强制左右两半在中缝处对齐」后，在一行两端（或半边的任意位置）各插一枚占位键，占比多少就把那一侧往里推多少——分体布局的每一行都适用（G 向中间凸出的做法，见 6.10 节）；
• 拇指休息区：在空格键两侧留出不可误触的空白；
• 纯装饰：做一枚只显示符号、不执行动作的"图例键"。

可设置的项：

• 主字符 / 副字符：都可以留空，渲染时按你填的原样显示，不随 Shift、Caps 或标点映射变化；
• 权重宽度：与其它键一致，也是调整占位宽度的主要手段（0 表示占满剩余空间）；
• 行高百分比：与其它键一致；
• 自定义颜色：关闭时键底、边框、阴影与按压高亮一概不画，只有文字可见；打开后它像一枚正常按键那样有底色与间距，可以单独设置主/副文字色、背景色与阴影色，只是点不动。

在布局文件里它就是一个普通的键对象，main/alt 省略即"不显示字符"：

{ "type": "PlaceholderKey", "weight": 0.5 }

{ "type": "PlaceholderKey", "main": "⇧", "transparent": false, "backgroundColor": -16777216 }

transparent 只在打开自定义颜色时写成 false；省略表示"透明"，也就是默认的完全空白形态。 占位键不参与"分体时复制中间字母键"，也不提供「合成态按键」入口——它永远进不了合成态。

7. 宏与按键动作

宏不是独立入口，而是在布局编辑器中给按键的点击、滑动或长按事件配置的一组步骤。

支持的步骤以当前编辑器为准，常见类型包括：

• 点击一个 Fcitx 或 Android 按键；
• 按下/释放按键；
• 发送带 Ctrl、Alt、Shift、Meta 的快捷键；
• 输入固定文本；
• 复制、剪切、粘贴、全选、撤销、重做；
• 切换键盘层或返回上一层；
• 执行应用动作，例如打开设置或编辑器；其中包含切换系统输入法与弹出 Rime 方案选单两个动作，可用来把方案切换挂到任意按键上。

7.1 创建宏

1. 打开 修改键盘定义；
2. 选择或新建一个按键；
3. 选择点击、滑动或长按事件；
4. 将动作类型设为宏；
5. 按顺序添加步骤并保存；
6. 在普通文本框中测试，而不是先在密码框、终端或重要文档中使用。

同一按键的上划与下划宏

需要让同一个按键的两个物理方向执行不同动作时，在按键编辑器中分别打开 上划事件 和 下划事件，两者可以同时配置。以 Enter 为例：

• 上划事件添加一个快捷键步骤，选择 Ctrl+Shift+Enter；
• 下划事件添加一个快捷键步骤，选择 Shift+Enter；
• 如果编辑的是自带的 ReturnKey（回车键），上下宏直接按物理方向生效，不受全局「符号划动方向」限制；如果使用 MacroKey 自定义一个回车键，则到 虚拟键盘 → 按键行为 → 符号划动方向（符号隐藏时） 选择 自动，让上划和下划两个物理方向都参与宏选择。选择「上划」「下划」或「禁用」时，MacroKey 仍会按该全局限制只允许对应方向或不触发。

物理方向宏按手指实际的上/下方向选择，优先于按键副标签的划动动作。支持方向标签的回车、退格、大小写、符号和布局切换键也分别提供上下划标签；当「标点符号位置」设为「无」时，这些功能键的方向标签与手势仍保持可用。旧布局里的单个 swipe / swipeLabel 会在读取、编辑或保存时按兼容规则迁移到方向字段；已配置的 swipeUp 与 swipeDown 会同时保留。

7.2 宏使用注意事项

• Down 和 Up 必须配对；普通快捷键优先使用“快捷键”步骤；
• 某些应用会拦截 Android 快捷键，不能保证所有宏跨应用一致；
• 固定文本宏不要保存密码、恢复码或私钥；完整备份会包含布局和宏；
• 长宏是顺序执行的，切换应用、关闭输入框或重启输入法可能中断；
• 修改切层宏后，要验证返回路径，避免停留在没有返回键的层。

8. 主题、背景、字体和图标

8.1 选择与编辑主题

路径：应用主页 → 外观 → 主题。

主题页包含主题列表和配置页，可预览键盘外观。

主题列表：点击卡片即选用该主题。自定义主题卡片左下角有导出按钮、右上角有编辑按钮（长按卡片同样可以导出，两种方式等价）。内置主题不显示导出按钮——它们没有对应的可导出文件。

配置页：可调按键边框、圆角、边距、水波纹、标点位置、导航栏背景，以及手动/亮色/暗色三档主题选择（详见 3.4）。

配置页里还有两项专管工具栏里那条候选栏里被选中候选的高亮背景：候选栏高亮圆角半径（默认 4，0–48dp，0 是直角）与候选栏高亮边距（默认 8，0–24dp，控制高亮边框 ↔ 候选文字的左右间距）。高亮离格子四边固定留 4dp，上下不再贴边；改「边距」不会让高亮铺满或离开整格，只改变文字到高亮框的松紧。这两项只影响工具栏候选栏——独立候选窗口（候选弹窗）的高亮是另一项设置，在「输入与候选」的「候选」里，两边互不影响，改错地方不会有任何效果；九宫格展开的候选页不受这两项影响（高亮铺满整格）。

自定义主题编辑器：颜色项已全部提供中文名称（整体背景、顶栏、按键背景、候选文字、水波纹效果等），并按语义分成五组——背景与顶栏 / 按键 / 候选区 / 弹出与剪贴板 / 分隔线与选中态。默认展开前两组，其余点分组标题即可展开或收起。颜色项名称与分组只用于显示，不会写进主题文件，因此升级后已保存的主题不受影响。

首次启动时，应用会自动安装一批社区贡献的键盘主题（如「森林集·write」「长日将烬」「isGboard」「WeChat Dark/WeChat Light」「Braun Minimal Dark/Light」「Caramel Dawn/Caramel Ember」「GitHub Dark Dim」「Sage Journey」等），可直接在主题列表中选用；删除后不会被再次自动安装。

8.2 导入与分享主题

主题列表菜单支持：

• 分享当前激活主题；
• 通过 ZIP 导入/分享带背景资源的主题；
• 分享主题二维码图片；
• 扫码导入或从二维码图片导入。

导入同名主题时应用会询问是否覆盖。操作前建议先分享或导出旧主题。

Monet 颜色映射：卡片上有动态图标时表示该主题支持自定义颜色映射；若当前设备不支持，点击编辑会提示「当前设备不支持自定义颜色映射」而不是毫无反应。

安全提示：只导入可信来源的主题 ZIP 或二维码。主题包可以包含图片和配置，不应把“只是皮肤”视为绝对安全。

8.3 字体与图标主题

• 字体入口：应用主页 → 外观 → 字体设定；
• 图标主题入口：应用主页 → 外观 → 图标主题。

字体设定页可以逐项设置基础字体、按键主字体、按键副字体、候选字体、注释字体、弹出按键字体、预编辑字体。

• 改字号：点每行右侧的当前值（形如 23 sp）或它后面的齿轮图标，打开滑杆（范围 8–72 sp，可「重置」回默认）。点行标题或下面的预览行打开的是字体选择（勾选多个字体可按顺序回退、拖拽调整优先），两者入口不同。
• 多个字体可按序回退：某一项勾选了多个字体时，排在前面的找不到对应字形就依次回退到后面的，最后才回退到系统字体。

保存后立即生效，不需要重启输入法：写完点右上角保存，当前已经打开的那套键盘会立刻换上新字号与新字体——键帽文字、候选栏、展开的候选面板、浮动候选窗、预编辑行、弹出按键气泡都会跟着变。不必强杀输入法重开，也不必切走再切回。

有两处「看起来没换过来」其实属于正常现象：

• 候选字被候选行高度卡住：候选文字的高度自动缩放只会缩小、不会放大。想让候选字真正变大，要先按 3.2.1 节把工具栏调高，再调候选字号。
• 长按弹出气泡要看比例：气泡里的字符是自适应缩放的，字号改了以后气泡本身也会跟着变大变小，观感变化不如候选栏明显。

若保存后确实只换了一部分（例如候选栏换了、键帽没换），见 11.18 节。

首次启动时，应用会自动安装几套社区贡献的图标主题（如「谷歌」「无题」「长日将烬」等），可在图标主题页直接选用；删除后不会被再次自动安装。

自定义字体和复杂 SVG 可能增加首次载入时间。若出现方框、字号异常或图标不显示，先切回系统字体/内置图标主题，再逐项排查文件是否仍存在。

9. 剪贴板与远端同步

9.1 本地剪贴板

路径：应用主页 → 剪贴板。

这里可设置本地/远端/媒体历史上限，并进入远端同步设置。密码框或应用标记为敏感的剪贴板内容可能受到 Android 系统限制；仍应定期清理不需要的敏感历史。

输入法里的剪贴板入口在 Kawaii Bar 的剪贴板按钮（或状态区里的同名入口），打开后是剪贴板窗口。窗口内还有 搜索 按钮，可对历史做实时搜索：

1. 点搜索按钮后界面回到键盘，工具栏中间变成搜索框；
2. 直接打字即可过滤历史，匹配结果以卡片形式显示在键盘上方的辅助栏（最多 50 条，单条最多 3 行）；
3. 退格修改查询；工具栏最左侧按钮此时是返回箭头，点它退出搜索并恢复常规工具栏；
4. 切换输入框、离开键盘或进入悬浮键盘都会结束搜索并清理结果。

搜索只在本机剪贴板历史里做匹配，不外发任何数据；结果过多时请用更精确的关键词缩小范围。

9.2 配置远端同步

路径：剪贴板 → 远端剪贴板同步设置。

当前可选择 SyncClipboard、OneClip、ClipCascade 或自定义 profile（自定义支持保存多个命名配置）。推荐顺序：

1. 选择与服务端匹配的 profile；
2. 填写服务器地址、账户和密码；
3. 优先使用 https:// 或 wss://；
4. 设置同步间隔、过滤规则和后台常驻行为；
5. 开启 同步；
6. 执行连接测试；
7. 分别从手机和另一端复制一条无敏感信息的测试文本。

当前版本允许明文 HTTP，且某些默认示例地址使用局域网 HTTP。HTTP 会暴露账号和剪贴板内容，只应在完全可信、隔离的局域网中临时使用；通过互联网或不可信 Wi-Fi 时必须使用 HTTPS/WSS 或可信 VPN。

9.3 Android 剪贴板限制

Android 10 及更高版本会限制后台应用读取系统剪贴板。作为当前默认输入法且输入法正在使用时，捕获通常更可靠；系统/OEM 仍可能限制后台活动。

可尝试：

• 允许通知和后台运行；
• 在 OEM 电池设置中取消对本应用的过度限制；
• 使用同步通知中的 抓取并同步 做一次前台捕获；
• 确认快速设置磁贴和通知没有被系统禁用。

9.4 同步新截屏

开启 同步新截屏 后需要图片读取权限。截屏保存后，应用会把图片 URI 加入剪贴板并尝试同步。若不工作：

1. 检查图片权限；
2. 检查同步总开关；
3. 确认服务端支持文件/图片；
4. 亮屏后再试一次；
5. 查看通知或日志中的连接错误。

9.5 隐私建议

• 不同步密码、验证码、私钥、证件照或医疗信息；
• 给同步服务使用独立账号和强密码；
• 不要把服务直接暴露到公网，除非配置了 TLS、认证和访问控制；
• 定期清理服务端和本地历史；
• 导出用户数据前牢记备份 ZIP 可能包含剪贴板历史和同步设置。

10. 更新

路径：应用主页菜单 → 关于 → 当前版本（应用主页右上角菜单里也有 关于 入口）。

进入当前版本即可检查更新、查看发布说明并下载可用安装包。安装前请确认：

• 来源仓库和发布者正确；
• APK ABI 与设备匹配；
• 覆盖升级所需签名一致；
• 已完成手工备份。

Nightly/自动构建通常未经完整设备矩阵验证，适合愿意反馈问题的测试用户。不要仅凭文件名判断版本新旧，以应用显示的版本、提交哈希和发布说明为准。

11. 故障排查

11.1 键盘不出现

1. 在 Android 设置确认输入法已启用；
2. 在文本框中用系统输入法切换器重新选择；
3. 确认没有处于不允许第三方输入法的安全界面；
4. 重启 Fcitx 实例；
5. 必要时重启应用或设备。

11.2 有键盘但没有候选

本版本不预置输入方案，所以首次安装后“有键盘但没有候选”属于预期状态，请先按第 5.0 节放入方案并部署。若已放入方案仍无候选，再依次排查：

1. 打开 中州韵设置，确认至少启用了一个 Rime 方案（default.custom.yaml 的 schema_list 非空）；
2. 执行部署并等待完成；
3. 检查 YAML 是否有缩进或语法错误；
4. 临时移走最近修改的 *.custom.yaml 后重新部署；
5. 检查当前是否在 ascii_mode；
6. 查看日志中的 Rime/Fcitx 错误。

11.3 语言键不能切换中英文

确认当前 Rime 方案的 Shift/ascii_composer 设置。该键在 Rime-only 版中不是“切换内部输入法”按钮：短按发一次 Shift，长按弹出 Rime 方案选单。如需切换 Android 输入法，请长按工具栏的语言切换按钮打开系统输入法选择器。

11.4 修改 YAML 后没有变化

Rime 配置一般需要部署。确认修改的是当前 profile 的用户目录，而不是旧应用、旧 profile 或只读内置目录。部署失败时先修复 YAML，再重试。

11.5 自定义布局没有生效

1. 确认当前选择的是刚编辑的布局文件；
2. 确认编辑的是 rime 默认布局、当前子模式布局或正确的回退层：看编辑器顶部的子模式下拉框，选「默认」项改的是默认布局（影响所有无专用布局的方案），选方案名改的是该方案专用布局；工具栏副标题显示的是当前实际编辑的位置；
3. 分体键盘下改了没反应：先看方案下拉框下面那个 「分体键盘布局」 勾选框是否勾着，以及它右边写的是「已有独立的分体布局」还是「未单独设置，分体时沿用普通布局」（见 6.8 节）。没配分体布局时，分体键盘用的就是普通布局那份行——在普通排列里改的按键，分体下当然跟着变，反过来也一样；想让分体单独一套，先勾上它、按提示新建；
4. 分体布局改了，方案之间却互相影响：确认你配的是哪个子布局的那一份。勾选框作用于当前下拉框里选中的那一项：停在「默认」上配的分体布局，是给所有没有自己分体布局的方案用的；只有切到某个方案再勾选，配出来的才是它专属的（文件里写在该方案对象内部，见 6.8 节）；
5. 确认已点击保存；
6. 关闭当前输入框后重新打开；
7. 如仍不生效，切回内置布局判断是匹配问题还是文件损坏。

若编辑器提示布局文件无法读取，不要直接覆盖；先复制损坏文件并检查 JSON。

11.6 分体键盘按键变窄 / 各行断点不齐

这两件事互为代价，由 应用主页 → 键盘 → 分体、浮动与单手键盘 → 分体键盘 → 强制左右两半在中缝处对齐 决定，详见 6.10 节：

• 按键变窄：该开关处于开启（默认）。两侧被强行拉成等宽，键多的那一侧只好压窄按键。关掉即可让按键保持原本宽度。
• 各行断点不齐：该开关处于关闭。此时各行按自己的按键宽度自然断开——这正是关掉对齐后的预期表现。若希望某一行固定从某处断开，在按键编辑页勾选「分体键盘在本键之后断开」（见 6.9 节）。
• 想让两侧的按键往中间靠一点：也在关闭对齐的状态下做——在一行两端各加一枚空白占位键，它占多宽就把这一侧往里推多远（见 6.10 节）。

11.7 分体键盘用了不是我为它配的那套按键

分体键盘的按键来自三处，按顺序找（详见 6.8 节）：

1. 当前方案的分体布局——在下拉框选中该方案、勾上「分体键盘布局」后配的那份；
2. 布局本体的分体布局——在下拉框停在「默认」时配的那份；
3. 都没有，用普通布局（先当前方案、再布局本体）。

所以：

• 分体下看到的是普通布局 → 说明这两处都没配过，勾选「分体键盘布局」按提示新建即可；
• 给某个方案单独配的分体布局没生效 → 确认配的时候下拉框确实停在该方案上（右侧状态提示与工具栏副标题都会写明当前编辑的是哪一份）；
• 反过来，某个方案莫名其妙用上了一份分体布局 → 那是第 2 步在起作用：它在「默认」下配的分体布局对所有没自己配过的方案都生效，包括这个方案。要让它走普通布局，请单独给它配一份。

11.8 主题或背景丢失

• 检查图片/字体/图标文件是否被移动或删除；
• 切换到内置主题，再重新导入；
• 跨设备迁移时使用包含资源的主题 ZIP，而不是只复制一段 JSON；
• 同名导入前确认是否选择了覆盖。

11.9 剪贴板不同步

1. 检查同步开关和当前 profile；
2. 检查 URL、账号、密码以及 HTTPS 证书；
3. 用连接测试确认服务端可达；
4. 关闭并重新开启同步；
5. 检查 Android 后台、通知和剪贴板限制；
6. 用普通短文本测试，排除文件大小或服务端格式问题。

11.10 更新无法覆盖安装

通常是签名或包名不同。先导出数据，再卸载旧包并安装新包，最后导入。卸载会清除应用私有数据，未备份前不要操作。

11.11 输入法退出或切换后词库没有立即同步

这是当前版本避免 Rime 完整同步长时间阻塞的设计折中。需要保证数据落盘时，请在 中州韵设置中主动执行同步，并定期导出完整用户数据。

11.12 工具栏中间的按钮整排消失

现象：开关悬浮键盘、开关单手键盘，或者进出状态区、剪贴板窗口之后，Kawaii Bar 中间那一排按钮整排不见了——左右两个固定按钮还在，中间那块区域点也没反应。

• 原因：2026-09-14 修复（0.1.3-588 及更早的构建）之前，中间按钮行会把"上一次的布局状态"延续到宽度变化之后，导致整行没有被排到可见区域。
• 临时规避：收起键盘再打开；或点一次左上角状态区按钮再收起。两种操作都会让整行重建。
• 彻底解决：更新到 2026-09-14 及之后的构建（含 fix(工具栏): 中央按钮行改为确定性布局）。该版本把中间行改成每次布局都按当前宽度重新计算，不再需要任何"救活"操作。

若更新后仍能复现，请按第 12 节提供版本号、复现步骤和日志（打开 开发者入口 → 详细记录日志 能记录到工具栏自身报告的布局状态，如 KawaiiBarRow: mode=... viewport=... children=...）。

11.13 连续移动候选时出现两个高亮

现象：在候选栏上连续按键（或长按）移动高亮候选时，上一个候选和当前候选同时高亮；且不是每次按键都出现——往往只在候选较多、高亮移出屏幕首行的那一步出现。

• 原因：2026-09-14 修复（0.1.3-589 及更早的构建）之前，候选栏把候选列表从"窗口截断"恢复为"整列"时，旧高亮的清除通知打在了位移后的错误位置上，导致旧高亮残留。
• 彻底解决：更新到 2026-09-14 及之后的构建（含 fix(候选栏): 高亮重绑按结构位移后的坐标解析，修复双高亮）。
• 若更新后仍能复现，请记录当时的候选内容和按键次数（是否恰好是高亮移出首行的那一步），并按第 12 节提供日志。

11.14 长按退格删完编码后不再继续删正文

现象：长按退格把拼音编码删空之后，继续按住不再删除已经上屏的正文，松手后再按才会继续删。

• 这是有意行为，不是故障：目的是防止长按退格越过编码区边界误删正文，与万象拼音的桌面退格保护一致，详见第 5.5 节。
• 需要连正文一起快速删除时：松开手指后再长按退格即可（此时输入区已空，不再触发保护）。
• 若松手瞬间仍会多删一个字，或按退格时出现"点了没反应"，请按第 12 节提供日志（日志中 handleBackspaceKey: consumed at composing boundary 记录的是被保护吞掉的退格）。

11.15 自定义图标按钮左右多出一块空隙

现象：在 Kawaii Bar 上新建按钮、图标导入自定义图片（尤其是 SVG）后，这个按钮比旁边的按钮宽很多，图标居中显示，左右各空出一块，把整排按钮挤窄。

• 原因：2026-09-19 修复之前，导入的 SVG 若只在根标签里写了 viewBox 而没有 width/height（尺寸写在 style="width:1em" 里也算"没有"），渲染时会退回一个很大的默认画布，按钮被撑宽后再居中绘制图标，空隙就出现了。PNG 等图片若原始尺寸很大也会有同样效果。
• 临时规避：换一个自带 width/height 属性的 SVG，或换尺寸较小（约 24–96 px）的 PNG。
• 彻底解决：更新到 2026-09-19 及之后的构建（含 fix(工具栏): 自定义图标统一归一到标准尺寸），所有自定义图标都会按标准图标尺寸（24dp）显示，与内置图标等宽。
• 若更新后个别图标反而变模糊，说明原图本身很小、被放大了；换一张更大尺寸的源图即可（应用不会再把它放大到超过 24dp 的显示尺寸）。

11.16 刚切回输入法时，前几个字母没进编码却直接出现在文字里

现象：从其它输入法切回来、键盘一弹出就立刻打字，最前面几个字母没有进入候选/编码区，而是作为普通字符直接上屏，出现在输入框里。

• 原因：2026-09-28 修复之前有两个问题叠加。① Rime 用数据目录的时间戳判断配置是否改动，而同一目录里大量与配置无关的活动（用户词典落盘、垃圾清理、同步临时目录、installation.yaml 重写）都会推新时间戳，于是每次冷启动都跑一次全量部署；② 部署期间按下的键在引擎里被直接丢弃、又被回吐给输入框当普通字符处理。
• 彻底解决：更新到 2026-09-28 及之后的构建。该版本改为按配置文件内容求指纹来判断是否需要部署（无关活动不再触发部署），并且部署期间的按键只被丢弃、不再直接上屏，同时在键盘预编辑区显示「正在部署」提示，详见第 5.3 节。
• 若更新后仍能复现，请记录：切回输入法到开始打字的间隔、当时是否显示「正在部署」、以及输入框里直接出现的具体字符，并按第 12 节提供日志。

11.17 空白占位键看不见了 / 占位键点不动

这是设计如此，不是 bug（见 6.11 节）：

• 看不见：主副字符都留空、且「自定义颜色」关闭时，它本来就不画任何东西。想在编辑器里确认它还在，看键列表——占位键会显示成一个 · 记号。
• 点不动：占位键不接收任何输入，点了当然没反应，也不会震动或高亮。想要一枚"能点但什么都不做"的键，请改用宏键配一个空动作，或者干脆用普通键。
• 想让它可见：填上主字符，或打开「自定义颜色」。
• 占位键填的字符被 Shift/Caps 改掉了：不会——占位键的字符按原样显示，不参与大小写与标点映射。若确实出现大小写变化，说明这个键不是占位键，请检查它的 type。

11.18 改完字体设定，键盘只换了一部分 / 要强杀输入法才生效

现象：在 应用主页 → 外观 → 字体设定 里改了候选、按键或预编辑的字体/字号并保存，回到键盘只换掉一部分——有的候选变了、键帽没变，或者再打几个字、甚至强杀输入法重开才全部换过来。

• 原因：这是旧版本的缺陷。刷新信号是一个一次性标志，会被键盘侧先读走并清零，候选侧随后读到的恒为「不需要刷新」；再加上若干处字号是构造期快照，复用的旧控件永远拿不到新值。
• 彻底解决：更新到 2026-10-04 及之后的构建。该版本改用单调递增的字体数据版本号，任何一侧都能按「我上次用的是哪个版本」自行判断，不再有人「消费」这个信号；所有基准字号也改成按版本号重读。
• 两处属于正常现象、不是没生效：候选字被候选行高度卡住（高度自动缩放只会缩小不会放大，见 3.2.1 节），以及长按弹出气泡用自适应缩放、大小变化不明显（见 8.3 节）。
• 若更新后仍能复现，请记录：改的是哪几项、当时键盘是显示还是收起、有没有接物理键盘，以及哪些部分换了哪些没换，并按第 12 节提供日志与版本哈希。

12. 报告问题时应提供什么

为了便于定位，请提供：

• 应用版本和构建提交哈希；
• Android 版本、设备型号和 ABI；
• 当前 Rime 方案/profile；
• 可重复的最短步骤、期望结果与实际结果；
• 是否使用自定义 YAML、布局、宏、主题、字体或同步服务；
• 脱敏后的相关日志。

不要公开上传：完整备份 ZIP、剪贴板数据库、同步密码、私钥、真实输入内容或包含个人信息的截图。能够用最小配置复现时，优先提供最小配置。

13. 数据保护检查清单

在升级、迁移或大改配置前确认：

• [ ] 已导出完整用户数据 ZIP；
• [ ] 备份 ZIP 已加密或保存在可信位置；
• [ ] 重要 Rime YAML/词典另有文本副本；
• [ ] 重要布局和主题已单独分享或导出；
• [ ] 已记录当前版本、提交哈希和使用的 Rime 方案；
• [ ] 已确认新 APK 的来源、包名、签名和 ABI；
• [ ] 已准备好回退到上一版本的方法。

---

文档维护原则：只描述当前 Rime-only 应用中可从界面到达、源码仍存在的功能；历史分支名、旧快照、已删除插件和旧 Nightly 流程留在维护者历史文档中，不再混入用户指南。