兼容性与自定义主题
兼容性配置
兼容性规则用于修复特定应用中候选框定位、光标获取等问题。规则文件为 TOML 的 [[apps]] 数组表，加载顺序为系统预置（<安装目录>\data\compat.toml）→ 用户覆盖（%APPDATA%\WindInput\compat.toml），用户层同进程名规则覆盖系统层。
[[apps]]
process = "Weixin.exe" # 进程名（不区分大小写）
comment = "微信 - 使用 rect.top 定位候选框"
caret_use_top = true # 使用 caret rect 的 top 而非 bottom 定位候选框字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
process | string | 进程名，不区分大小写，如 Notepad.exe |
comment | string | 备注说明，仅用于文档与可读性 |
caret_use_top | bool | 使用 caret rect 的 top 而非 bottom 定位候选框 |
caret_use_top 适用于 GetTextExt 返回的 height 不稳定的 WebView 应用（如微信的 Qt WebView 输入框，height 在 1↔20px 间跳变导致 bottom 漂移，但 top 始终稳定）。
清风输入法内置了微信的兼容性规则，会自动修正候选框定位。如果其他应用也有类似问题，可在用户 compat.toml 中添加规则；修改后通过托盘菜单的重载配置即可生效。
自定义主题
将主题文件放入以下目录，即可在设置工具的「外观」页选择：
- Windows：
%APPDATA%\WindInput\themes\<主题名>\theme.toml - macOS：
~/Library/Application Support/WindInput/themes/<主题名>/theme.toml
主题文件为 TOML 格式
主题文件为 TOML 格式（v3）（theme.toml）。制作主题最省事的方式是继承一个内置主题，只覆盖需要改动的部分；复杂的几何与配色建议直接用主题编辑器可视化制作。
主题文件结构
主题由若干顶层块组成，均可选，未写的部分从被继承主题回退：
# 继承内置主题（未写的字段从它继承）；内置基础主题以 _ 前缀命名（如 _base / _qingfeng）
base = "default"
[meta]
name = "我的主题" # 必填
version = "1.0" # 可选
author = "作者" # 可选
[colors]
# 颜色 token 表（扁平）：支持亮暗分设与 ${token} 引用
primary = "#3b82f6"
bg = { light = "#FFFFFF", dark = "#121826" } # 亮/暗分设
text = { light = "#1A1D24", dark = "#F2F3F7" }
accent = "${primary}" # 引用其他 token
[behavior]
# 主题给用户的推荐默认，用户可在设置工具「外观」页单独覆盖
always_show_pager = false
show_page_number = true各顶层块职责：
| 块 | 说明 |
|---|---|
base | 继承的内置主题名（default / msime 或内置基础主题 _base / _qingfeng） |
[meta] | 元信息：name（必填）、version、author 等 |
[colors] | 颜色 token 表（扁平），语义色的唯一来源，[views] 通过 ${token} 引用 |
[resources] | 图片资源引用（可选，支持亮暗分设） |
[views] | 几何与布局（候选窗 / 工具栏 / 菜单的盒模型） |
[behavior] | 主题推荐的行为默认（见下表） |
快速上手：继承内置主题
最简单的方式是声明 base 并只写要改的颜色，其余从内置主题继承：
base = "default"
[meta]
name = "我的蓝色主题"
[colors]
primary = "#0066CC" # 只改主色，其余外观沿用 default颜色系统
[colors] 块是所有颜色的唯一来源。
亮暗分设： 值写成 { light = "...", dark = "..." } 表示亮暗使用不同颜色；写成单个字符串则亮暗共用；只写一侧时另一侧自动回退到已写的一侧。
token 引用： "${tokenName}" 引用同表中另一个 token 的值。
颜色格式： "#RGB" / "#RRGGBB" / "#RRGGBBAA"（支持 alpha 透明度）/ "transparent"。
behavior 字段
[behavior] 中的值是主题给用户的推荐默认，用户可在设置工具「外观」页单独覆盖，覆盖跨主题切换保持。
| 字段 | 类型 | 说明 |
|---|---|---|
font_size | number | 候选字号基准（pt） |
always_show_pager | bool | 始终显示翻页栏（即使只有一页） |
hide_pager | bool | 隐藏整个翻页栏（含箭头） |
show_page_number | bool | 显示页码文字 |
pager_align | string | 独立翻页栏行的水平对齐（left / center / right，默认 center）；仅竖排独立翻页栏生效，翻页栏并入编码栏时固定右对齐 |
vertical_max_width | number | 竖排模式最大宽度（像素） |
views 几何
[views] 按具名节点描述各窗口的盒模型（内外边距、边框、圆角、背景色/渐变/图、字体、阴影、覆盖图层等）：
| 节点 | 说明 |
|---|---|
window / preedit_bar / candidate_list / item / index / text / comment | 候选窗骨架：窗口容器、编码栏、候选列表、单个候选、序号、词条文本、注释 |
accent_bar / footer_bar | 选中候选左侧强调条；底部翻页栏（可自定义翻页箭头图/字符） |
mode_label | 模式指示标签（临拼/临英等） |
status / tooltip / toast | 状态气泡、候选悬停提示框、toast 通知 |
toolbar | 工具栏：背景/边框 + 高度、按钮宽度/内边距/圆角等几何 + 按钮中英状态覆盖 + 设置齿轮 |
menu | 右键弹出菜单：容器、菜单项（含 hover/disabled）、分隔线 |
通用约定：
- 尺寸单位 — 裸数字或
"8dp"为密度无关像素（随 DPI 缩放）；"1px"为设备像素（发丝边框不随 DPI 加粗）；"50%"为百分比（仅覆盖图偏移等少数字段）。 - 状态覆盖 —
item等节点可写selected/hover/disabled子表覆盖颜色、背景、字重等（不覆盖几何，避免候选框跳动）。 - 图片资源 — 背景图与覆盖图经
ref引用顶层[resources]中登记的图片（支持亮暗分设、九宫格拉伸、单色染色随主题变色）。
字段较多且随版本演进，制作或调整几何时，建议直接以内置主题文件为模板，或使用主题编辑器可视化编辑，避免逐字段手写出错。
内置主题参考
清风输入法内置五个可选主题，可作为模板起点：
- 清风·蓝（
default）— 默认主题，清风设计体系，主色现代蓝 - 清风·绿（
jade）/ 清风·橙（amber）/ 清风·紫（violet）— 同体系配色变体，只覆盖主色相关 token，是「继承 + 改色」的最小示例 - 微软风格（
msime）— 微软蓝主色、紧凑布局、文字序号、左侧强调条
内置主题文件位于安装目录下的 data\themes\ 文件夹（含以 _ 前缀命名、不在列表显示的内置基础主题 _base / _qingfeng）。你也可以在设置工具中选中一个内置主题后查看其外观，作为自定义的参考。