主题与兼容性

「外观」页的主题卡（选主题、导入、导出、主题市场）与底部的主题编辑器卡，以及自制主题、修复个别应用显示问题的方法。

获取更多主题

主题包 .wtheme 0.122 新增

主题一旦带了背景图、图标这类资源，单个 .toml 文件就分发不动了——图片没法塞进 TOML。 主题包把主题文件和它引用的资源打成一个 .wtheme，收发都只是一个文件。

纯配色主题不需要它，继续用 .toml 或链接分享即可。

装一个主题包：

• 「外观」页 → 主题卡 → 导入主题 → 选择文件（.toml 与 .wtheme 在同一个选择框里）
• 或双击 .wtheme 文件——这条需要先在系统集成注册关联； 不想注册关联的话走上面那条，一样能装

两条路都会先弹确认框告诉你包里是什么（主题名、作者、版本、几个资源文件）再决定装不装—— 主题包多半是从网上下回来的，双击就直接改掉当前外观不合适。撞上同名主题时会问要不要覆盖。

做一个主题包：「外观」页 → 主题卡 → 导出主题，选个保存位置即可。 导出的是主题选择里此刻选中的那个，改了还没保存也照导——所见即所导。

命令行也能做，且能直接指定要导哪个，见 wind_input theme export：

wind_input theme export 我的主题 D:\分享\我的主题.wtheme

内置主题也导得出——把内置主题改了配色想发给别人，这是最省事的路子。

包里装什么：

主题目录里的其它文件（编辑器草稿、系统生成的缩略图数据库等）不会进包。

主题编辑器

开启后，Web 版主题编辑器可以直接读写本机主题，边改边看效果——不必反复导出导入文件。

服务仅监听本机回环地址，不对外网开放。三档：

开启后可复制本地连接地址，粘贴到编辑器里建立连接。

自制主题

把主题文件放入 %APPDATA%\WindInput\themes\<主题名>\theme.toml（macOS 为 ~/Library/Application Support/WindInput/themes/<主题名>/theme.toml），即可在「主题选择」中出现。若主题名与内置主题相同（如 default），你这份会整份替换内置的那个，见同结构覆盖机制。

快速上手：继承内置主题

声明 base 并只写要改的颜色，其余从内置主题继承：

base = "default"

[meta]
name = "我的蓝色主题"

[colors]
primary = "#0066CC"     # 只改主色，其余外观沿用 default

主题文件结构

主题由若干顶层块组成，均可选，未写的部分从被继承主题回退：

[colors] 块是所有颜色的唯一来源：

• 亮暗分设：值写成 { light = "...", dark = "..." } 表示亮暗不同颜色；写成单个字符串则亮暗共用；只写一侧时另一侧自动回退
• token 引用："${tokenName}" 引用同表中另一个 token 的值
• 颜色格式："#RRGGBB" / "#RRGGBBAA"（支持 alpha 透明度）/ "transparent"
• 3 位简写 "#RGB" 0.123 新增："#F80" 即 "#FF8800"，必须带 #（fed、ace 这类英文单词 不会被当成颜色）。0.122 及更早的版本其实不认 3 位写法，写了等于没配、回落到继承来的颜色；升级后这些 颜色开始生效，用过 3 位色的主题外观会随之变化。语言栏的颜色配置同样适用

[behavior] 中的值是主题给用户的推荐默认，用户可在「外观」页单独覆盖，覆盖跨主题切换保持：

[views] 按具名节点描述各窗口的盒模型（内外边距、边框、圆角、背景、字体、阴影等），字段较多且随版本演进。制作或调整几何时，建议直接以内置主题文件为模板，或用主题编辑器可视化编辑。

背景图的九宫格中段 0.122 新增

背景图配了 slice（九宫格边距）时，中段默认是拉伸的。候选窗的宽度随候选内容不停变，于是有纹理的背景会跟着「呼吸」——这在中段占了原图大半宽度的主题上尤其明显。

给那个图片节点加 slice_repeat 即可改成平铺：

slice_repeat = "repeat"                 # 两轴都平铺
slice_repeat = ["repeat", "stretch"]    # 横轴平铺、纵轴拉伸

取值只有 repeat 与 stretch（不写 = stretch，即 0.121 及以前的行为）。分轴写是有用的：横轴随宽度变，纵轴通常固定，一个值管两轴会让一张宽图在 40px 高的编码条里从「压扁到条高」变成「只取顶部 40 行」。

文字角色色 0.123 新增

候选注释与悬停提示里的文字，每一段都带着一个角色——它是哪个变量产出的（pinyin、code_rev……）， 或是模板里写死的文字（literal）、气泡的段名（title）。主题可以按角色配色，不用改模板：

[comment.roles]
pinyin   = "${text_dim}"
code_rev = "${accent_text}"
literal  = { light = "#B0B0B0", dark = "#606060" }

[tooltip.roles]
title    = "${tooltip_accent}"
readings = "#9AD0FF"

注释模板是 ${code_rev}{ (${pinyin})} 时，编码显示为强调色、注音为次要文字色，括号为浅灰。

写在哪：

只有注释、上方注释条与悬停提示读这张表，写在其它节点下的 roles 被忽略。

值的写法与节点的 color 相同："${token}"、"#RRGGBB"、{ light = "…", dark = "…" }。另外：

• "" 表示不配色、跟随正文色。派生主题用它撤销被继承主题配的某个角色。
• "transparent" 与完全透明的颜色（如 "#FF000000"）不收，按没配处理——文字占着位置却看不见，只会是误写。
• 派生主题的 roles 与被继承主题的逐个角色合并，只写要改的那几个即可。
• [tooltip.roles] 里写 "${error}" 取到的是候选窗用的 error（为浅色底调的深红）。气泡里要可读的版本， 写 "${tooltip_error}"，见标准色。
• 引擎不检查角色名：写错了（如 pinyn）只是不生效，不报错。
• 彩色 emoji 自带颜色，emoji 角色的配色对它基本无效。

角色名

几条细则：

• ${a|b|c} 的角色是实际取到值的那个变量：${code_hint|code_rev} 取到反查码时是 code_rev。
• ${name:参数} 的角色就是 name，参数不影响。
• 段名里的变量（如 编码{(${code_source})} 里的 五笔）没单独配色时跟 title 走，整个段名同色。
• 变量名拼错而原样显示的 ${pinyn} 没有角色，始终是正文色，在段名里也不跟 title。
• 截断加的 … 与它前面那个字同色。

哪个颜色生效

一段文字按这个顺序取色，取到即止：

1. 模板里的内联颜色 $[颜色]{…}（它另有一套 选中与悬停的规则）；
2. 选中或悬停时，[comment.selected.roles] / [comment.hover.roles] 里给这个角色配的颜色（上方条读 [comment_above.selected.roles] / [comment_above.hover.roles]，没写则回退到注释的同名表）；
3. 选中或悬停时，若主题给这个状态换了注释颜色（[comment.selected] color 等），用换过的那个；
4. [comment.roles] / [tooltip.roles] 里给这个角色配的颜色（上方条读 [comment_above.roles]，没写则回退 [comment.roles]）；
5. 段名里的变量：title 的颜色；
6. 正文色（节点的 color）。

第 3 条是为可读性兜底：选中底换成深色实心块的主题，必然也把选中态注释换成了浅色；平时为浅色底调的 角色色直接搬到深色底上多半看不清，退回主题作者为这个状态亲自选的颜色最稳妥。想在选中时仍然分色， 就在 [comment.selected.roles] 里单列（见下面的配方）。

「换了」看的是最终显示的颜色：写了 [comment.selected] color、但与平时相同，也算没换。亮色、暗色模式 各自判断。出厂主题都没给选中、悬停换注释颜色，所以角色色在选中时照常显示。

出厂主题的角色色

出厂主题都继承基础主题 _base，它给悬停提示配了这一组角色色（颜色名见标准色）。 候选注释不配，保持原来的注释色：

• 写的是 tooltip_*：角色表里的 ${…} 按字面取色，不像模板内联色那样先找 tooltip_ 版本， 写 ${info} 在亮色模式下拿到的是为浅色底调的深蓝，压在深色气泡上看不清。
• 继承 _base 的主题自动拿到这张表。要换色，在自己的 [tooltip.roles] 里写同名角色；要去掉，写 ""。 想给候选注释分色，自己写 [comment.roles]。
• 没写 base 的主题不继承这张表，气泡保持正文色。
• 模板里的内联颜色优先于这些角色色。

上方注释条 0.124 新增

打开「注释首行显示在候选上方」后，注释的上段画在候选上方， 它的样式由 [comment_above] 节点管，字段与 [comment] 相同。

回退规则——没写的字段这样取：

边距不继承，是因为 [comment] 的 margin.left 是「文字与右侧注释的间距」，只给右侧用； 上方条若继承会被推歪。上方条与主行之间的间距，用它自己的 padding.bottom（或 margin.bottom）调。

上方条同样消费背景、边框（含选中、悬停态）；背景图与渐变只作用于基态。这些装饰不继承 [comment]， 状态节点也是：[comment.selected] 只贡献字体、颜色与 roles，它的底色、边框、边距不会带到 [comment_above.selected]。模板里的内联颜色与 roles 对上方条同样生效。

最小示例——上方条比基础主题的注释（font_size = -4，字号是相对正文的偏移）再小一号、换成次要文字色，并与主行留出 2 的间距：

[comment_above]
font_size = -6
color = "${text_dim}"
padding = { bottom = 2 }

不打开开关时这个节点不起作用。

标准色 0.123 新增

下面这些颜色名由内置基础主题 _base 给出默认值，内置主题都继承它；不继承任何主题的独立主题没写的， 输入法按下面的规则补上。所以模板的内联颜色 在任何主题里写这些名字都一定能取到，并跟随主题与明暗。

主题里也可以覆盖它们，或用 ${名字} 引用。注意补上的名字只供模板取色：不继承 _base 的主题， [colors] 和各窗口配置里的 ${名字} 只能引用主题自己写了的名字。

没继承 _base 的主题怎么补（没写 base，或 base 链上没有 _base）：

• 主题 [colors] 里写了的名字用主题自己的，一个都不会被换掉；没写的才补。
• 补的只有下面两张表里的名字。_base 的其它内容（窗口布局、菜单、工具栏的颜色……）一概不带进来。
• 补的值取 _base 的；其中引用别的名字的，按本主题的颜色算：accent_text 是本主题的 accent， selection_text 是本主题的 text，tooltip_text 暗色那一档是本主题的 text。本主题也没写的， 再用 _base 的。
• 例外：主题连气泡底色 tooltip_bg 也没写时，tooltip_text 用输入法原来的气泡文字色（浅灰白 #F0F0F5， 亮暗一样），气泡看起来和以前完全一样。

候选窗用（为候选窗底色调）：

表中是 _base 的值，各主题可以覆盖：清风系主题（清风·蓝 / 橙 / 绿 / 紫）的 text 三档与 accent_text 都是自己调过的，名字不变。

悬停提示用（为深色气泡底调）：上表每个名字 x 都有一个 tooltip_x。内联颜色在气泡里写 x 时先取 tooltip_x，所以同一个模板在候选窗和气泡里都看得清。

tooltip_on_accent、tooltip_selection_text 在气泡里没有对应的场景，等于气泡文字色，写了也看得清。

tooltip_accent 随主题的强调色换：

配方：给注释与气泡分色 0.123 新增

以下片段都写在你自己的主题文件里，放法见上文「自制主题」。

淡化装饰、突出信息

括号、冒号这类装饰退后，编码与注音更醒目：

base = "default"

[meta]
name = "清风·蓝·分色"

[comment.roles]
literal   = { light = "#B8BDC8", dark = "#4A5163" }   # 括号、冒号更淡
code_hint = "${accent_text}"
code_rev  = "${accent_text}"
pinyin    = "${text_dim}"
chaizi    = "${text_dim}"

[tooltip.roles]
title    = "${tooltip_text_hint}"   # 段名退后
literal  = "${tooltip_text_hint}"
readings = "${tooltip_accent}"

派生主题只改角色色

喜欢某个主题的整体外观，只想加点分色：继承它，只写 roles。

base = "violet"

[meta]
name = "清风·紫·编码高亮"

[comment.roles]
code_rev = "${accent_text}"

[tooltip.roles]
title = "${tooltip_accent}"

被继承的主题已经配了角色、你想去掉其中一个时，写空串：

[comment.roles]
pinyin = ""   # 拼音回到注释正文色

选中时保留编码高亮

主题把选中态注释换了颜色时（例如选中底是深色实心块），平时配的角色色在选中时会统一回落到那个颜色 （见哪个颜色生效）。想让编码在选中时仍然醒目，在 [comment.selected.roles] 里 为深色底另配一个：

[comment.roles]
code_rev = "${accent_text}"

[comment.selected]
color = "${on_accent}"        # 选中态注释改为白色（你的主题本来就有这一行）

[comment.selected.roles]
code_rev = "#FFE08A"          # 选中时编码用浅黄，其余注释仍是白色

出厂主题没有换选中态注释颜色，用不着这一步。模板里的内联颜色对应的写法是 selected=，见 选中与悬停时的颜色。

macOS 上的生效范围

主题在 macOS 上只覆盖输入法自绘的界面：候选窗完全生效，状态提示气泡与候选悬停提示框的配色生效。

不生效的两处：

• 功能主菜单——macOS 上是原生系统菜单，由系统绘制，外观跟随 macOS 自身的浅色 / 深色与强调色。主题里的菜单配色与几何对它无效
• 工具栏——macOS 没有浮动工具栏，改用菜单栏的输入模式指示器，主题里的工具栏节点无处落地

也就是说，同一份主题在两个平台通用，[views] 里的菜单与工具栏节点在 macOS 上被忽略、其余部分照常。「主题风格」（跟随系统 / 浅色 / 深色）仍然有效。详见 macOS 版 · 菜单不支持主题。

应用兼容性规则

候选框在某个程序里飘到错误位置、候选窗被盖住看不见、或想让某个程序默认英文——这些靠 compat.toml 的逐应用规则修正，与主题无关。完整字段与用法见应用兼容性规则。