候选注释

候选注释是候选词右侧的那行小字。默认显示编码提示（如五笔前缀候选的剩余编码），你可以把它 改成注音、拆字字根，或几种信息的组合。

设置位置：设置工具 →「外观」→ 候选标注 →「候选注释」→ 设置。

快速上手

横排注释建议留 ${code_hint|code_rev|shuangpin} 或干脆留空：横排候选窗的宽度由所有候选共享，放注音或 字根很容易把窗口撑得很宽。

变量

${chaizi} 限单字是有意的：拆字回答的是「这个字由哪些字根构成」，词组的字根串既难读、 又会把候选行推得很宽。确实需要词组字根时用 ${chaizi_all}。

${code_rev} 和 ${shuangpin} 的分别

两者回答的是不同的问题：

• ${code_rev} —— 这个词在主码表里怎么打。它去码表词库里查反向索引，所以能查到 什么完全取决于你配了哪个主码表。
• ${shuangpin} —— 这个词的双拼怎么敲。它是算出来的：拿候选自带的拼音和音节划分， 逐个音节过一遍双拼布局。

双拼编码不存在于任何词库里（双拼词库就是全拼词库，双拼只是「全拼 + 一张键盘布局」）， 所以它只能算不能查——这也是为什么它得单列一个变量，而不是让 ${code_rev} 换个码源了事。

三个变量都只对拼音来源的候选有值——形码方案下候选的编码就是你自己打的，再显示一遍是冗余。

出厂模板用 ${code_rev}（只给全码）而不是 ${code_rev_all}：一个字往往有三四个码位， 全列出来会把候选行推得很宽，横排尤其明显。想一眼看全简码、又用竖排的话再换 ${code_rev_all}。

变量参数

${chaizi_all}、${chaizi_code_all} 与 ${code_rev_all} 支持用冒号指定分隔符：

冒号后的内容原样使用，空格不会被忽略。

语法

${a|b} 取首个非空

按顺序取第一个有内容的变量。默认模板 ${code_hint|code_rev|shuangpin} 的意思是：优先用 引擎给的编码提示，没有就退回主码表反查码，再没有（比如你没配主码表）就显示双拼编码。

{ … } 可选段

段内的变量全部为空时，整段（包括里面的括号、标签文字）一起消失。

这是配装饰字符的关键。对比：

段内有多个变量时，只要有一个非空就保留整段，空的那个连同紧邻的一个空格一起省去：

{(拼: ${pinyin} ${chaizi})}

  都有值   →  (拼: nǐ hǎo 亻尔)
  字根为空 →  (拼: nǐ hǎo)
  都为空   →  （不显示）

可选段嵌套 0.123 新增

可选段里可以再套可选段，内层只管自己的变量，外层在它里面任一变量有值时保留：

{${chaizi}{ [${chaizi_code}]}}

  字根、编码都有 →  女子 [vbg]
  只有字根       →  人
  都没有         →  （不显示）

随之而来的一条要求：模板里的字面花括号必须成对出现。可选段按层数配对，段内落单的 { 会去和后面的 } 配对。此前段内第一个 } 就结束本段，落单的 { 原样输出——像 {(${a}{)} 这种写法，升级后显示会不同。

候选悬停提示的段名与段内容用的也是这套模板语法， 「拆字 / 拼音」合并段正是靠嵌套可选段写出来的。

两条自动规则

• 空变量吞掉紧邻的一个空格或制表符，所以你可以放心用空格分隔变量，不必担心某个变量为空时留下 多余间距。
• 整个模板的变量全为空时不显示任何内容。所以 拼:${pinyin} 在查不到读音时不会剩下一个 孤零零的 拼:。

注释显示在候选上方 0.124 新增

注释很长时（拼音 + 拆字 + 其它），全挤在候选右侧容易放不下。打开这个开关后，可以把注释的 首行挪到候选上方单独占一行，其余内容仍在右侧：

    nǐ hǎo                 ← 上方注释条
1.  你好   亻尔 女子        ← 序号 + 候选文字 + 右侧注释

设置位置：设置工具 →「外观」→ 候选标注 →「候选注释」→ 设置 → 开关「注释首行显示在候选上方」。 对应配置键 ui.candidate.comment_above，默认关闭；关闭时与以前完全一样。

怎么拆：开启后，模板里字面写的第一个换行 \n 把渲染结果拆成两段——上段显示在候选上方， 下段仍在候选右侧。

• 变量值自带的换行（如注释库词条里的换行）不算分隔符，不会误拆；上方条恒为单行， 上段里出现的变量换行会折成一个空格。
• 第一个 \n 之后的其它 \n 留在下段，撑高右侧注释，与以前一样。
• 模板里没有 \n，全部内容都在右侧，与关闭时一致。

两条写法约束：

1. \n 要写在可选段 { … } 之外。写在段内时，该段为空则 \n 一并消失，内容会落到右侧而不是上方：

   ${pinyin}{\n${chaizi}}     ← 错：拆字为空时 \n 消失，拼音掉到右侧
   ${pinyin}\n${chaizi}       ← 对

2. 上段的装饰文字也要包进 { … }，否则上段变量为空时会孤零零留下装饰：

   拼:${pinyin}\n${chaizi}      ← 错：拼音为空、拆字有值时，上方条显示「拼:」
   {拼:${pinyin}}\n${chaizi}    ← 对：拼音为空时装饰一起消失

版面：

• 上方条左边对齐候选文字的起点（序号右边）。
• 一页里只要有任一候选带上段，整页所有候选都预留这一行的高度，避免高低不一。因此翻到 没有上段的页时，候选窗高度可能变化。
• 蒙古文竖排（直立）不支持，上段会并回右侧。
• 上方条的字体、颜色、间距由主题的 [comment_above] 节点控制，见 上方注释条。

常用组合：上方拼音 + 翻译，右侧编码与字根

下面五套是用户反馈里常见的搭配，都是「上方一行拼音（可带词典翻译），右侧一行编码 / 字根」。 都要先打开「注释首行显示在候选上方」，否则模板里的 \n 只会让右侧注释变成两行。

♬ ♩ 𝄞 只是分隔用的装饰符，随便换。

几处写法的用意：

• 翻译指 ${dict}，需要先挂载注释词库（或词库自带 comment 列）。没挂时 { ♬ ${dict}} 整段消失，上方只剩拼音，不会留下孤零零的 ♬。
• 短句四码用 ${code_rev}（取最长的全码）；这里不必写成 ${code_rev|code}——code 只是 code_rev 的旧别名，两个取的是同一个值，| 兜不到底。
• 单字编码想连简码一起看，用 ${code_all}（即 ${code_rev_all}，全部码位，短的在前）。 第 4 套里 ${code_hint|code_all} 表示：引擎给了编码提示（如形码前缀候选的剩余编码）就用提示， 没有再退回全部码位。
• ${chaizi_code_all} 是拆字库里的编码，与 ${code_rev}（主码表编码）来源不同：前者跟着 拆字库走，后者跟着你配的主码表走。两者按需选，不必同时放。
• 分隔符只在词组里可见（逐字拼接时插在字与字之间）；单字候选只有一项，不会出现 ♩ 𝄞。
• 第 2、4、5 套末尾的 {【…】} 是可选段：查不到字根时【】一并消失。
• 𝄞 在音乐符号区（U+1D11E），个别字体没有这个字形，候选窗会退到系统的符号字体； 显示成方框时换成 ♪ ♩ · 之类常见字符即可。
• \n 均在 { … } 之外，符合写法约束；上方拼音有装饰文字时（如 拼:） 记得同样包进 { … }。

内联颜色 $[颜色]{内容} 0.123 新增

给模板里的一段文字指定颜色：方括号里写颜色，花括号里写要上色的内容，内容可以是变量、文字， 也可以再套可选段。

$[accent_text]{${code_hint|code_rev}}{ $[text_dim]{(${pinyin})}}

  编码显示为强调色，注音显示为次要文字色

颜色的写法：

• 颜色名只由小写字母、数字、下划线组成，写成 $[Accent] 不认。
• 方括号里逗号、等号两侧的空格可有可无。selected= 以外的 键=值 暂不认，直接忽略——留给以后 的版本扩展，写了也不会让整段失效。
• 不想改模板、只想让某类信息换个颜色的话，主题可以按变量名统一配色，见 文字角色色。模板里写的颜色优先于主题配的。
• 出厂主题不给注释配色，默认注释保持原来的颜色。想让编码显示为蓝色，把模板改成 $[info]{${code_hint|code_rev|shuangpin}}。

只管上色，不是可选段

$[…]{…} 里的变量全为空时，它自己不会消失：

要「空则消失」，像后两行那样再套一层可选段，套在里外都一样。

反过来，上色也不改变可选段的判断：$[…]{…} 里的变量照常算进外层可选段与整个模板的「有没有值」， 两条自动规则照旧——空变量吞掉紧邻的空格时，那个空格在颜色范围之外也照样吞。

所以给现成模板加颜色是纯加法：挑一段花括号成对的片段、在外面包上 $[颜色]{ 和 }，显示的文字 一个字都不变，只是多了颜色。只包住半个可选段（如包住 {(${pinyin} 不包 )}）会改变花括号的配对， 那就不只是加颜色了。

复制、上屏拿到的文字里不带 $[…]，颜色只影响显示。

写错颜色会怎样

• 颜色写错——$[红]{…}、$[#GG0000]{…}、$[]{…}、当前主题里没有的颜色名、transparent 或 完全透明的颜色（如 #FF000000）：内容照常显示，用注释原本的颜色，不会冒出一串 $[…]。 颜色只是装饰，写错时丢的只是颜色，内容本身完整。
• 写法不完整才当普通文字：] 后面没紧跟 {、花括号没有闭合、方括号里出现花括号或换行、方括号里 超过 64 个字节。这时 $[ 原样显示出来。
• 写在 $[…]{} 里的变量名拼错时，原样显示的 ${pinyn} 也是这个颜色。

选中与悬停时的颜色

• 写了 selected=：候选被选中时用它。
• 没写：看主题有没有给选中（或鼠标悬停）的候选换一个注释颜色。
  • 换了（多见于选中底色是深色实心块的主题，注释要换成浅色才看得清）：这段改用主题给的那个颜色。 否则为浅色底调的颜色压在深色底上，多半看不清。
  • 没换：照常显示你写的颜色。出厂主题都没换，所以选中时颜色不变。

判断的是最终显示的颜色：主题写了选中态的注释颜色、但与平时相同，也算没换。亮色、暗色模式各自判断。 悬停没有单独的写法，只按上面这条跟随主题。

写错了会怎样

变量名拼错时会原样显示出来（如 ${pinyn}），这样你一眼就能看到是哪里写错了。 未闭合的 ${ 或 { 按普通文字处理，不会报错也不会崩溃。

• ${emoji} 取不到值时（功能没开、这个词没有 emoji 等）按空值处理 0.123 新增：所在可选段 整段消失。此前的版本会把字面的 ${emoji} 原样显示在候选旁边，像是变量名写错了。

关于注音的准确性

多音字的读音由词典决定，不是逐字取最常用读音：

• 拼音方案下，候选自带词条编码，行长 的编码是 hang zhang，注音即 háng zhǎng。
• 形码方案下，候选没有拼音编码，输入法会枚举各字读音、找出能在拼音词典里查回该词的 那个组合。行长 同样得到 háng zhǎng 而不是 xíng cháng。

有一种情况无法自动判断：同音异调。「好」的 hǎo 和 hào 去掉声调都是 hao，而编码里 不含声调信息，此时显示最常用的那个读音。

注释词库

上面那些变量的内容都由输入法自己算出来。${dict} 变量显示的则是词库里写好的注释—— 英汉解释、emoji 名称、字义、专业术语说明。它有两个来源：

• 词库自带的 comment 列：自动识别，无需配置
• 单独挂载的注释词库：由你放置文件并添加

输入法不随附独立的注释词库（词典内容多有版权），需要你自己准备文件。

词库自带的注释 0.121 新增

方案使用的词库如果在 columns 里声明了 comment 列，输入法会自动把这一列当作注释源， 不需要另行挂载。外观 → 候选标注 → 自动使用词库自带的注释控制此行为，出厂开启。

朗月拼音随附的错音错字表就是这种形态。拼音方案下输入 zhujiao，候选「主角」右侧显示 zhǔ jué：

name: corrections
columns:
  - text
  - code
  - weight
  - comment
...
主角	zhu jiao	0	zhǔ jué

识别规则：

• 判据是 columns 中显式声明了 comment。未声明 columns 的词库不计入——码表通常是 text / code / weight 三列，若按注释词库的默认列序读取，会把编码当成注释。
• Rime 主表用 import_tables 引入的子表同样逐一检测，各自独立成条。上面那份错音错字表 即由 rime_frost.dict.yaml 引入。
• 识别出的词库出现在注释词库列表中，标有「自动」。可以启停与排序，但路径和适用方案 由检测得出、不可编辑；适用方案即声明该词库的方案。
• 默认排在手工添加的词库之后。同一词条两处都有注释时取列表靠前者，拖动手柄可调整。

关掉某个自动条目或改变其位置后，配置文件里会写入一条只含 id / auto / enabled 的记录； 路径与适用方案不写入，每次启动重新检测。

词库格式

纯文本，与 Rime 词库同形态：可选的 YAML 头 + ... 分隔行 + 每行一条的制表符分隔正文。

name: en_cn
columns:
  - text
  - comment
...
apple	n. 苹果
banana	n. 香蕉

• columns 声明各列含义，必须包含 text 与 comment；省略 columns 时按 [text, comment] 处理。
• 可选的第三列 code 用于同词多义的消歧（见下）。声明了 code 列但某行没有编码时， 那一行写两列即可。
• 以 # 开头的行是注释，空行忽略。
• 没有 ... 分隔行时，整个文件都当作正文（裸 TSV 也能直接用）。

挂载

把词库文件放进 schemas/comments/（用户数据目录下，没有则新建），再到 外观 → 候选标注 → 注释词库 → 添加词库…：该目录下的 .dict.yaml 会自动列出， 选中后标识、显示名、路径自动填入，只需确认适用方案。缺 comment 列的文件也会列出并 标注，便于排查。

词库放在 comments/ 以外的位置时，用同一弹层中的手动填写路径…。

可挂多个，列表顺序即优先级，拖动左侧手柄可调整。也可以直接写配置（两种方式等价）：

[[ui.comment_dicts]]
id = "en_cn"
label = "英汉词典"
path = "comments/en_cn.dict.yaml"
enabled = true
schemas = ["english"]

[[ui.comment_dicts]]
id = "emoji"
label = "Emoji 名称"
path = "comments/emoji.dict.yaml"

schemas 用来避免无谓开销。一份十万条的英汉词典挂在五笔方案上，每次输入都要多查一次 注定查不到的表；写上 schemas = ["english"] 后，中文方案下就不会去查它。

词库本身仍然是启动时一次性加载好的（走内存映射，占用与词库大小基本无关），schemas 过滤发生在每次查询那一步——所以切换方案不会重新加载词库，临时英文这类"方案套方案" 的场景也能正确按 english 分流。

配好后把 ${dict} 放进模板即可：

comment_template_vertical = "${dict}"
# 或与自动信息并列，优先显示词库释义、没有则退回注音
comment_template_vertical = "${dict|pinyin}"

大小写

查询先按原样精确匹配，没有再依次试全小写、首字母大写、全大写。所以词库里写 apple 一条，输入 Apple / APPLE 时同样能查到；反过来词库里的大写缩写 ABC，输入 abc 也能查到。

精确匹配始终优先：词库里同时有 US（美国）和 us（我们）时，两者各显示各的，不会互相顶替。

这条回退只对含拉丁字母的词生效，中文词条不受影响。

同词多义的消歧

同一个词在不同方案下想显示不同注释时，用第三列 code 标注该条属于哪个编码：

columns:
  - text
  - comment
  - code
...
行	háng 行列、行业	tfhh
行	xíng 行走、可以	tfhx

查询时优先取编码精确匹配的那条；当前候选的编码对不上（比如拿拼音方案的编码去比对五笔码） 则回退到该词的第一条——跨方案共用一份词库是常态，不该因为编码对不上就什么都不显示。

性能与占用

词库首次加载时会被转成二进制缓存（.wcmt，与词库的 .wdat 放在同一个缓存目录下），之后 每次启动都是内存映射打开，常驻内存与词库大小基本无关，几十万条的大词典也不会让内存变大。 缓存按文件独立，加挂一个新词库不会让其他词库重建；同一个词库被多个方案引用时也只加载一份。

源文件改动后下次加载该词库时会自动重建（重启输入法，或在设置里改动挂载列表）， 你不需要手动清理缓存文件。已经卸载的词库，其缓存也会被自动清掉。

分模式设置

反查类的信息（注音、拆字、词典释义）在大多数时候是干扰，只在特定场景才想看到。 临时英文、临时拼音、网址输入、快捷输入、引导键特殊模式都可以有自己的注释模板， 进入该模式期间覆盖全局设置，退出自动恢复。

[input.temp_english]
comment_template_vertical   = "${dict}"
comment_template_horizontal = "${dict}"

[input.temp_pinyin]
comment_template_vertical   = ""     # 临拼期间不显示任何注释
comment_template_horizontal = ""

键名与全局的两个键完全一致，横排竖排也是各配各的。三种状态：

「不写」和「写空串」是两回事：前者跟随全局，后者是明确要求不显示。

可用位置：

# config.toml
[input.temp_english]      # 临时英文
[input.temp_pinyin]       # 临时拼音
[input.url]               # 网址输入
[[schema.mix_modes]]      # 快捷输入等融合模式（每个实例独立）

# <方案id>.schema.toml 或 schema_overrides/<方案id>.toml
[overlay]                 # 引导键特殊模式（每个方案独立）

推荐用法：把词典释义只留给英文

如果你挂了英汉注释库，最好不要把 ${dict} 写进全局模板，而是只写进临时英文：

[ui.candidate]
comment_template_vertical = "${code_hint|code_rev}"  # 中文输入时只显示编码提示

[input.temp_english]
comment_template_vertical = "${dict}"              # 打英文时才查词典

这样中文输入时输入法根本不会去查注释词库——不是"查得快"，而是压根不查。

长度控制

「注释最大字数」超出后截断并加省略号，0 表示不限。

候选窗不支持文字折行，注释过长时会被窗口右边缘裁掉，所以：

• 竖排每行独占一行，空间较宽裕，放注音或字根都合适；
• 横排所有候选共享一行宽度，注释稍长就会明显撑宽窗口。

这也是横排与竖排分开配置的原因。

• 开启注释显示在候选上方后，字数上限按每段计算 0.124 新增：上方条与右侧 注释各自数各自的，互不挤占；关闭时含义不变。

完整示例

# 五笔用户：竖排看注音和字根，横排只留编码提示
comment_template_vertical   = "{〔${chaizi}〕}{ ${pinyin}}"
comment_template_horizontal = "${code_hint}"

# 拼音用户：学五笔，竖排显示该词的五笔编码
comment_template_vertical   = "{[${code_rev}]}"
comment_template_horizontal = "${code_hint|code_rev}"

# 忘了某个字的双拼怎么敲时，候选后面就摆着它的双拼码（全拼方案下同样有效）
comment_template_vertical   = "${shuangpin}"

# 双拼 + 五笔两种码一起看（需把「编码提示来源」设为 auto）
comment_template_vertical   = "${code_hint|code_rev}{ [${shuangpin}]}"

# 悬停提示同款信息（字根 + 编码 + 读音），只对单字有完整效果
comment_template_vertical   = "{${chaizi}}{ [${chaizi_code}]}{ ${pinyin}}"
comment_template_horizontal = ""

# 拼音悬在候选上方，拆字和词库释义留在右侧（需打开「注释首行显示在候选上方」）
comment_template_vertical   = "{拼:${pinyin}}\n{〔${chaizi}〕}${dict}"

# 完全关闭注释
comment_template_vertical   = ""
comment_template_horizontal = ""