24 KiB
设置程序的页面与设置项
设置程序 apps/settings 三个平台共用一份，替掉了 macOS 偏好设置和 Windows 设置程序（两者留一个版本作回退）；Linux 以前没有设置界面，也用它。
本文定的是：分哪几页、每一项放哪页、页里怎么分组排序、标题怎么写、用什么控件。
原则
- 按用户想改的事分页，不按代码里的分节分页。 配置文件是
[general]一大节，以前的「通用」页照搬了这一节，结果什么都往里放。 - 标题就是说明。 能用一个短语说清的不加说明行。少数必须解释的，放进标题右边的 ⓘ，鼠标悬停（或键盘聚焦）才显示，页面上不出现大段灰字。
- 一件事只在一处。 以前「打包日志到桌面」「打开日志目录」在「高级」和「关于」各有一份，这次每项只出现在一页。
- 只在某个平台有的项，在别的平台不显示，不显示成灰的。哪项在哪个平台显示由
src/support/的表决定：每项登记三个平台是支持、不适用还是待实现，后两种都不显示。 - 跟别的设置有依赖的项（比如字体只对青简渲染器生效）显示成灰的，不另写说明；ⓘ 里写清依赖哪一项。
页面
旧的「通用」拆成「输入」「候选」「中英文」三页，旧的「候选窗口」改名「外观」，模糊音和辅码并进「输入」，页数不变（11 页）；之后加了「生词本」「实验功能」，共 13 页。
| # | 页 | 图标 | 内容 | 旧位置 |
|---|---|---|---|---|
| 1 | 输入 | 键盘 | 方案、五笔、模糊音、辅码 | 通用、模糊音、辅码 |
| 2 | 候选 | 列表 | 每页几个、译文、繁体、emoji、排序、英文词 | 通用、高级、云服务 |
| 3 | 中英文 | 中/英 | 英文模式、切换键、标点、状态条 | 通用、候选窗口 |
| 4 | 外观 | 调色板 | 预览、主题、排布、文字、动效 | 候选窗口 |
| 5 | 快捷键 | ⌘ | 全部可改的键 | 快捷键 |
| 6 | 自定义短语 | 引号 | 短语表格 | 自定义短语（只 macOS 有） |
| 7 | 词库 | 书 | 随包词库、导入的词库 | 词库 |
| 8 | 云服务 | 云 | 云联想 | 云服务 |
| 9 | 统计 | 柱状图 | 输入量、词汇 | 统计 |
| 10 | 生词本 | 卡片 | 时间线、词表、导出 | 新加 |
| 11 | 高级 | 齿轮 | 配置文件、日志、学习数据 | 高级、关于 |
| 12 | 实验功能 | 烧瓶 | 下载、启用知意与含章·知微（macOS、Windows） | 新加 |
| 13 | 关于 | 竹简 | 版本、更新、许可、数据来源、隐私 | 关于 |
各页
下表里「控件」一列：开关是 Switch，分段是 Segmented，下拉是 Select，步进是 Stepper，勾选是 Checkbox，按键是录键按钮（点一下再按键），文本是单行输入框。 「ⓘ」一列是悬停说明的全文，空着就是没有。
1 输入
方案
| 标题 | 控件 | 配置 | ⓘ |
|---|---|---|---|
| 拼音 | 下拉：全拼 / 小鹤双拼 / 自然码 / 微软双拼 / 搜狗双拼 / 智能ABC / 小浪双拼 / 首道双拼 / 拼音加加 / 紫光双拼 / 大千注音 / 关（只用形码） | general.scheme |
双拼与注音下 v、u、i 是按键，表达式和问字改用 Shift + V、Shift + U 进 |
| 输入框显示按键 | 开关，只在双拼时出现 | general.shuangpin_raw_preedit |
输入框里显示敲的字母，候选窗口里照旧是全拼 |
| 五笔（86 版） | 开关 | general.wubi |
跟拼音同时开就是混输，五笔打全的词排在前面 |
模糊音：九个勾选，排成三列，拼音关着时变灰：z = zh、c = ch、s = sh、n = l、f = h、l = r、an = ang、en = eng、in = ing（fuzzy.*）。
辅码
| 标题 | 控件 | 配置 | ⓘ |
|---|---|---|---|
| 启用 | 开关 | aux_code.enabled |
拼音打完敲触发键，再敲码筛选候选 |
| 触发键 | 录键（单个不带修饰键的符号，按 is_valid_aux_code_key 校验） |
general.aux_code_key |
微软、搜狗、紫光双拼里分号先当韵母 |
| 候选上显示码 | 开关 | general.aux_code_show |
|
| 码删空后留在辅码 | 开关 | general.aux_code_keep_empty |
|
| 码表 | 列表：每行勾选 + 名称 + 条数 + 移除；底下「导入码表…」 | aux_code.disabled |
辅码关着时下面几行变灰。码表列表单独一组「码表」：随包的（没有「移除」）、导入的，末尾一行导入。 整个辅码只在 Windows 显示：现在只有 Windows 的输入法加载码表，macOS、Linux 的输入法接上码表之前不显示，免得开了没用。
2 候选
显示
| 标题 | 控件 | 配置 | ⓘ |
|---|---|---|---|
| 每页候选数 | 步进 1–9 | general.page_size |
|
| 译文 | 下拉：英语 / 日语 / 西班牙语 / 越南语 / 不显示 | general.learning_language |
不显示时生词标记也关掉 |
| 繁体 | 开关 | general.traditional |
只换字形，不换用语 |
| emoji | 开关 | general.emoji |
排序
| 标题 | 控件 | 配置 | ⓘ |
|---|---|---|---|
| 学习输入习惯 | 开关 | general.learning |
关掉后不再学，已学的照样用 |
| 本地整句模型 | 开关 | model.enabled |
在本机给整句重新排序，不联网 |
「学习输入习惯」以前在「高级」，「本地整句模型」以前在「云服务」，可它们都在本机运行、改的都是候选顺序。
英文词
| 标题 | 控件 | 配置 | ⓘ |
|---|---|---|---|
| 打拼音时也给英文词 | 开关 | general.english_in_chinese |
hello、compa → company；关掉后句末英文词也一并停（nanine 不出「那nine」） |
| 英文候选最多几个 | 步进 1–4，「打拼音时也给英文词」关着时变灰 | general.english_max_in_chinese |
1 时只留最靠前的一条 |
| 英文词最高排到第几位 | 步进 1–9，「打拼音时也给英文词」关着时变灰 | general.english_min_position |
有中文候选时；1 为不限 |
| 中文排在英文词前面 | 开关，「打拼音时也给英文词」关着时变灰 | general.chinese_first |
3 中英文
英文
| 标题 | 控件 | 配置 | ⓘ | 平台 |
|---|---|---|---|---|
| 英文模式 | 开关 | general.english_mode |
关掉后固定中文，要英文就切到别的输入法 | 全部 |
| 切换键 | 三个勾选：单击 Shift / 单击 Ctrl / Ctrl + Alt + Space | shortcut.switch_mode |
Windows | |
| 英文模式也给候选 | 开关 | general.english_candidates |
Tab 或方向键选词，不选时跟直接打字一样 | 全部 |
| 只在写字的应用里给 | 勾选，挂在上一行下面 | apps.english_candidates_on |
浏览器、聊天、文档类应用；名单在配置文件里改 | 全部 |
| Shift + 字母 | 分段：交给应用 / 进组句 | general.shift_letter |
进组句才能打出「C盘」 | 全部 |
macOS 的切换键是 Caps Lock，由系统决定，所以不显示「切换键」这一行。
标点
| 标题 | 控件 | 配置 | 平台 |
|---|---|---|---|
| 中文标点 | 分段：全角 / 半角 | general.full_width_punctuation |
全部 |
| 英文标点 | 分段：半角 / 全角 | general.english_full_width_punctuation |
Windows、Linux |
| 标点先上屏候选 | 开关，ⓘ：nihao, 一气打完「你好，」 | general.punct_commits |
全部 |
状态条（只有 Windows）：悬浮状态条，开关，status_bar.enabled。以前放在「候选窗口」页，可它显示和切换的是中 / 英与标点。
4 外观
就是已经做好的「候选窗口」页，换个名字，内容不变：预览，主题卡片，然后分外观、排布、文字、动效四组。改动只有两处：
- 「拼音显示位置」挪到「排布」组（现在就在那里），ⓘ 写「终端里行内拼音显示不正常时选只在窗口」。
- 「悬浮状态条」移去「中英文」页。
5 快捷键
翻页与模式
| 标题 | 控件 | 配置 |
|---|---|---|
| 翻页键 | 分段：[ ] / , . / - = | general.page_keys |
| 表达式 | 分段：v / u / i | shortcut.expression |
| 问字 | 分段：v / u / i | shortcut.question |
| ? 也进问字 | 开关 | shortcut.question_mark |
候选
| 标题 | 控件 | 配置 |
|---|---|---|
| 上屏第一个译词 | 录键（按住修饰键再按个数字，记修饰键） | shortcut.translation |
| 上屏第二个译词 | 同上 | shortcut.translation_second |
| 翻译选中文字 | 按键（组合键） | shortcut.translate_selection |
| 按需 AI 联想（macOS、Windows） | 按键（组合键） | shortcut.predict |
页底一个「恢复默认」按钮，下面用小字列出组句中固定、不能改的键（空格、1–9、回车、Esc 等），这是全页唯一保留的一段说明文字。
模式键只有 v、u、i 三个能选，选了另一个正在用的字母就两个对调，不报错。 录键：点一下按钮进入录制（显示提示），按下的键能用就写进配置、结束录制；不能用（缺修饰键、跟另外两组修饰键撞了、 翻译键不是字母数字）就在这一行下面说原因、接着等；Esc 或点别处取消。修饰键只按着不算，要再按一个键。 字符键按不带修饰键时的字认（⌥1 记成 ⌥ 加 1），Windows 上 ⌘ 那一位记的是 Win 键。 Windows 旧设置程序里「翻译选中文字」只能改修饰键，这里整组都能录。「恢复默认」不动辅码触发键（它在「输入」页）。
6 自定义短语
每条一行：开关（勾选，标签是输入码）、权重、内容的第一行（太长截断）、「编辑」；末尾一行「新增…」。
新增、编辑在对话框里：输入码、权重（输入框，1–999，新增时 10）、内容（多行，回车换行），「取消」「保存」，编辑时左边多一个「删除」（点两下）。
保存时整张表交给 Config::set_custom_phrases 校验（输入码 1–32 个小写字母、权重在范围内、同码同内容不能重复），不过就在卡片里说原因、草稿留着；
打开编辑后这条在别处被改了，保存不覆盖。Esc 或「取消」扔掉草稿，换页也关掉卡片。
表下面一行开关「也用系统的文本替换」（只 macOS，general.system_text_replacements）。
Windows 和 Linux 以前没有这一页，这次都有了。
7 词库
随包词库：十一本领域词库排成两列勾选（dictionaries.domains），名字去掉统一的「青简领域词库：」前缀，后面跟条数。基础词库一直启用，不列。
导入的词库：每行勾选 + 名称 + 条数 + 许可证 + 移除（dictionaries.disabled）；末尾一行「导入词库」，可多选文件。
转换在后台线程（大的 Rime 词库要几秒），每个文件一行结果显示在按钮下面；导入成功的同名词库若之前关过会重新打开。
源文件里有没写读音的词（只有词的 txt / 混了无读音行的 Rime 词库）时走 import::import_dictionary：读音按随包基础词库与领域词库派生，
结果行写明跳过了几条、前几个是哪些词；全带读音的 TSV / Rime 与 .qj 仍走普通导入，行为不变。
移除是挪进目录里的 removed/，不真删；输入法发现文件变了自己重载。清单进这一页时扫一次，导入、移除后重扫。
随包词库的位置：macOS 先找设置程序自己所在的 .app，再找装好的 Qingjian.app/Contents/Resources/dicts；其他平台在随包根的 data/generated/dicts。
8 云服务
| 标题 | 控件 | 配置 | ⓘ |
|---|---|---|---|
| 启用 | 开关 | predict.enabled |
打字时把光标附近几十个字发给下面的服务，密码框里不发 |
| 云端词 | 步进 0–4，0 显示「不要」 | predict.slots |
补进第一页末尾这几格 |
| 自动联想（macOS、Windows） | 开关 | predict.automatic |
关闭后用按需联想快捷键请求 |
| 停键等待（macOS、Windows） | 步进 100–10000 毫秒 | predict.debounce_ms |
自动联想关闭时变灰 |
| 最短请求间隔（macOS、Windows） | 步进 1000–60000 毫秒 | predict.min_interval_ms |
自动和手动请求共用，缓存复用不联网 |
| 整句补全 | 开关 | predict.sentence |
按 Tab 采用 |
| 生词本整句翻译（macOS、Windows） | 开关 | predict.vocabulary_translation |
打完一句话后单独把这句发给服务，译文记进生词本的时间线；不发光标前后的文字 |
| 接口地址 | 文本 | predict.base_url |
|
| 模型 | 文本 | predict.model |
|
| API 密钥 | 文本（密文），已设置时占位符写「已设置」 | predict.api_key |
只存在这台电脑的配置文件里，打包日志时会抹掉 |
| 连接 | 「测试连接」按钮，结果显示在按钮下面 |
云联想关着时「云端词」「整句补全」变灰；地址、模型、密钥照样能填能测，先测通再打开。 输入框回车或离开时才存（离开包括换页），Esc 扔掉没存的改动；密钥框不显示已存的密钥。macOS 以前缺「整句补全」，这次补上。
密钥存哪：三个平台都写进配置文件的 [predict] api_key。macOS 偏好设置以前写在配置同目录的 .env，
可输入法重读 .env 时不覆盖已有的环境变量，换密钥要重启输入法才生效；写进配置文件热加载就生效，Windows 一直是这么存的。
旧的 .env 照样读（设置程序启动时也读进来，好显示「已设置」），配置文件里写了的优先。
9 统计
顶上分段切「输入 / 云服务」两层（不做侧栏折叠：侧栏只为一页多一层展开状态不值）；云服务层只在记用量的平台显示（support 表的 ApiUsage）。
两层结构一样，切换时布局不跳、只换数：今天 / 本周（周日起，同 GitHub 的提交日历）/ 本月 / 累计四张数字卡，近一年按天的格子图（一列一周、周日在上，颜色按当天量相对一年里最多那天开方后分四档），
过去 24 小时的柱状图（最右是现在这个钟点；比「今天」好：早上打开不是空的，跨零点的夜里也连着），再下面详情。图表是 bamboo-slip 的 Heatmap / BarChart，悬停浮出说明。
输入层详情：最多的一天、日均、速度（今天 / 平均 / 最快一天，只算键间停顿不超过 5 秒的时间）、首选率、一次打对（上屏前没删过的比例）、平均码长、跟一本书比；末尾是词汇一组
（见过、看熟、上屏过、直接打出过、本周新见一句话，有等级表时一张按级的表）。云服务层详情：最多的一天、请求次数一句、Token 表。
数据由输入法写在数据目录（usage-hourly.tsv 与只读的老 usage.tsv、api-usage.json 与 api-usage-hourly.tsv、user-vocab.tsv），设置程序进这一页时读一次，不写。
--png 截图在最后装一份样例数据（offscreen/sample.rs）拍这两层。
等级表的位置：macOS 在 Qingjian.app/Contents/Resources/levels-<语言>.tsv，其他平台在随包根的 assets/levels/。
10 生词本
照 #570 引用的中英输入法的样子做：按语言分开记，顶上一行分段切「时间线 / 词表」，记过两门以上语言时旁边再一个分段切语言。
时间线（缺省）：数据是输入法追加的 vocab-log.tsv，一次相遇一行。
「‹ 日期 ›」跳到前后有记录的日子；大字的相遇次数加「个词与你相遇」；一段话「其中 N 个是你今天第一次见到的生词。已连续输入 K 天」（第一次见到按 user-vocab.tsv 的首见日，连续按输入统计里有汉字的日子）；
记忆色带：卡片里统计页同款的柱状图（BarChart），一个钟点一根，悬停浮出「16:00–17:00 · 12 个词」，今天的话现在这个钟点高亮；再下面「今天 N 个词」一组，每条左边圆点，说法大字（日语后面跟假名），中文在下，单个词再带例句，右边「下午 4:53」。每页 50 条。
读音这一列现在只有日语有，留给以后的英语音标；发音以后接系统朗读，不用另存。
词表：数据是 user-vocab.tsv。一句汇总，一组筛选（全部 / 生词 / 本周新见 / 认识了）、排序（最近 / 次数 / 字母）、搜索；
每行分层：译词大字加粗、后面一个带底色的小标签（生词用强调色、认识了灰的），下一行中文，再下一行「例句 …」，最后小字的次数与最近日期，右边「认识了」与「删除」。每页 50 个。
生词本之前记的英语词没有中文，按随包 glossary-zh 反查一个补上显示与导出，不写回。
两个视图末尾都是「导出与清空」：导出列出的词（CSV / Anki / 网页，按词表当前的筛选与搜索）、清空生词本（点两下，连同时间线）。
标认识、删除、清空当场写回；输入法也在写 user-vocab.tsv，两边写之前都先合并对方的改动（VocabularyBook::refresh），输入法每 60 秒落盘时看一眼；时间线输入法只追加，清空时设置程序整个重写。
学习语言关着时这一页只有一句说明。
没做成虚拟列表：整页在一个滚动区里，列表只是页里的一段，按可见范围只建几行要知道列表在页里的位置；按页翻已经够用。
11 高级
| 组 | 项 | 控件 |
|---|---|---|
| 配置文件 | 在编辑器中打开 | 按钮 |
| 配置文件 | 打开数据目录 | 按钮 |
| 日志 | 详细日志（ⓘ：会记下敲的内容，排查完关掉） | 开关 general.log_level |
| 日志 | 打开日志目录、打包到桌面 | 两个按钮排一行，做完的结果显示在按钮下面 |
| 输入日志 | 记录输入日志（ⓘ：只存在这台电脑上） | 开关 general.input_log |
| 输入日志 | 清空 | 按钮，第一下变成「再点一次清空」，第二下才清 |
「复制诊断信息」要输入法进程里的运行状态（当前方案、词库加载情况等），设置程序是另一个进程拿不到，先不放；以后由输入法把诊断信息写成文件再说。
12 实验功能
页首一句说明：还在试用、本机运行不联网、同一时间只用一个。「候选」页的「本地整句模型」关着时再多一句提醒。 每个可下载的模型一组（知意在前，组标题带「推荐」），第一行是模型名，说明行写大小与一句介绍：
| 状态 | 控件 |
|---|---|
| 没下载 | 「下载」按钮；另一个正在下时灰掉 |
| 下载中 | 「取消」按钮；下面一行「正在下载 x / y MB」与进度条 |
| 解压中 | 灰掉的「正在安装…」 |
| 下载失败 | 「重试」按钮，下面写原因 |
| 下好了 | 开关 model.name：开了写这个模型，关了写回 tongbian；下完自动打开 |
知意开着时多一行「档位」（分段：省电 / 均衡 / 准确，model.zhiyi_tier）。
下载同时问 Gitee 与 GitHub 要清单、先答的那边先下，某块失败换另一边（模型仓库 qingjian-team/qingjian-models 的 Release，标签写死在 jobs/model_download/pack.rs），
逐块核对 SHA-256 再核对整个压缩包，解到临时目录后换进用户目录的 models/zhiyi/（Windows 是 int8 ONNX 版 models/zhiyi-onnx/）、models/hanzhang-zhiwei/。关掉窗口下载就停，下次从头下。
Linux 的输入法还没接，support 表登记「待实现」，侧栏不出这一页。
13 关于
- 顶部：logo、「青简」、版本与构建号、官网和 GitHub 链接。
- 更新：自动检查（开关
update.check）、渠道（分段：正式版 / 测试版，update.channel）、「立即检查」（后台线程查完写update.json，结果显示在按钮下面）； 有新版时多一行「新版本 x.y.z」带「下载」按钮，下面列更新日志的前几条。自动检查仍由输入法每天做，设置程序打开时读它落盘的update.json。 本地开发版（-dev）不查，测提示时用QINGJIAN_UPDATE_VERSION顶替版本号。 - 许可：一行「GPL-3.0-or-later 自由软件」。
- 数据来源：每个来源一行（词库、语言模型、释义表、emoji、英文词表、词汇等级、五笔码表、笔画码表），默认收起，点「展开」才列出来。
- 隐私：保留现在那段话，这是关于页唯一一段长文字。
日志相关的按钮从这里移去「高级」。
要新做的控件与功能
| 项 | 用在 |
|---|---|
| 悬停说明 ⓘ（tooltip） | 各页 |
| 单行文本输入（含密文、占位符、IME 组字） | 云服务、短语编辑 |
| 多行文本输入 | 短语内容 |
| 录键按钮 | 快捷键、辅码触发键 |
| 列表 / 表格（选中、双击、滚动） | 短语、词库、码表 |
| 弹出卡片（模态） | 短语编辑、清空确认 |
| 文件对话框（多选） | 导入词库、码表；三平台各接各的系统对话框 |
| 折叠组 | 关于页数据来源 |
| 统计用的数字卡 | 统计 |
| 菜单的键盘导航 | 所有下拉 |
实施顺序
- 只用现有控件的页：输入（触发键与码表列表除外）、候选、中英文、外观、高级、关于。引擎为此加了折行的段落。
- 文本输入 + ⓘ：云服务。引擎为此加了输入框（输入法组字、选区、复制粘贴）、悬停说明的浮层、后台线程叫醒窗口。
- 录键：快捷键、辅码触发键。引擎为此加了录键按钮，修饰键补上原样的 ⌃ / Ctrl 与 ⌘ / Win，字符键按不带修饰键时的字认。
- 列表、文件对话框：词库、码表。文件选择用 rfd（与 Windows 旧设置程序同一个），清单是普通的分组行，没有另做列表控件。
- 弹出卡片、多行文本：自定义短语。引擎为此加了对话框（盖住整窗的底加一张卡片）与多行输入框，列表仍用分组行，没做表格。
- 统计。到这一步十一页都有内容了。
- 搜索：搜设置行、分组标题、勾选项的标题，行里控件上的字（分段的各项、下拉框的全部选项、录好的键），以及 ⓘ 全文，按这个顺序排；记不清标题时搜选项里的字也能找到那一行。 输入时侧栏的导航换成结果，点结果（或回车取第一条）跳到那页，那一行滚进视野、铺一层底色再淡出，Esc 清空。 索引不手写：设置行这些控件建树时自己登记，开始搜时离屏把每页建一遍收来，所以按当前配置藏起来的项（别的平台的、依赖没开的）也搜不到。
- 换掉旧设置程序：新程序装进安装包，输入法菜单「设置…」、Windows 状态条的 ⚙、开始菜单与 Linux 应用菜单的「青简设置」打开它。
- 安装位置：macOS 是
Qingjian.app/Contents/Applications/QingjianSettings.app（独立的 .app，自己的 Dock 图标与名字，open打开；随包数据从外层Qingjian.app读）； Windows 是与 Server 同目录的qingjian-settings.exe（只开一个，第二次启动把已开的带到前台）；Linux 是<前缀>/bin/qingjian-settings加一个.desktop。 - 回退：旧的 macOS 偏好设置（菜单「旧版设置…」）与 Windows 设置程序（
qingjian-settings-legacy.exe，任务栏「中 / 英」右键菜单「旧版设置…」与开始菜单「青简旧版设置」）保留作兜底；新版设置为主，缺省打开新版。 新程序打不开时用旧版；某项不生效靠测试拦：config_keys离屏点遍每一页的控件，变了的键用输入法的Config读回核对。 - ⓘ 可点：悬停仍是短说明，末尾一行「点一下 ⓘ 打开文档」，点了打开官网文档对应的一段（
docs.rs一张表，按页与行标题对到docs/user/的某个标题， 锚点照官网的headingId生成）。测试核对表里每一段在文档里真有这个标题、每一行在那页上真有 ⓘ，文档改标题时测试报错。 - 用户文档的设置窗口总览（
docs/user/getting-started/settings.md）按新的页与组重写，别处的「偏好设置 → 通用」这类指路改成新的页名。 - 「复制诊断信息」还没有：要输入法把运行状态写成文件，留到以后；反馈时先用「高级 → 打包到桌面」。
- 安装位置：macOS 是
待定
- macOS 输入法菜单里的「模糊音」子菜单保留：设置里它已经不是单独一页了，菜单里留着反倒是最快的入口。