Windows Terminal 设置 UI 的设计与实现：从 1564 规格书到 Cascadia 源码

2026-09-04 13:55:25作者：郦嵘贵Just

Windows Terminal 的设置界面（Settings UI）是整个应用中用户感知最强的功能之一。本文基于仓库中的规格文档 doc/specs/#1564 - Settings UI/spec.md 及其配套设计文档 [design.md](https://gitcode.com/GitHub_Trending/term/terminal/blob/20588130d8ef2ba40eb56bdae88e04cce7fc5b5d/doc/specs/?utm_source=gitcode_repo_files#1564 - Settings UI/design.md)，完整梳理设置 UI 的产品定位、打开方式、保存机制与导航结构，并结合 src/cascadia 下的实际源码，说明这些设计是如何一步步落地为可运行的功能的。读完后，你将理解设置 UI 的完整功能边界、openSettings 动作的参数体系，以及各配置页在源码中的对应实现位置。

一、产品定位：设置 UI 是默认体验

规格书给出的第一个决策是：设置 UI 将成为 Windows Terminal 的默认体验。用户不再需要直接打开 settings.json 用文本编辑器改 JSON，而是通过图形界面完成配置；同时官方会提供选项让用户跳过 UI、直接编辑原始 JSON 文件。

这一决策来自 [spec.md](https://gitcode.com/GitHub_Trending/term/terminal/blob/20588130d8ef2ba40eb56bdae88e04cce7fc5b5d/doc/specs/?utm_source=gitcode_repo_files#1564 - Settings UI/spec.md) 的 Solution Design 部分。它意味着两件事：

默认行为变更：点击"设置"入口后，优先打开的是 UI 页面而不是 JSON 文件；
必须提供逃生通道：保留直接访问 settings.json 的途径，供高级用户继续使用文本编辑器工作流。

二、可禁用 UI：`openSettings` 动作与 `settingsUI` 选项

规格书提出，通过更新 openSettings 键位绑定的参数来实现"是否显示设置 UI"的控制：

若用户不喜欢 UI，可以保留直接打开 JSON 文件的旧行为；
若用户喜欢 UI 但偶尔想改 JSON，可以在设置 UI 的导航菜单底部提供一个"打开 JSON 文件"按钮。

在仓库源码中，这一设计已经落地为带 target 参数的动作体系。defaults.json 中定义了四种内置命令（见 defaults.json#L522-L525）：

{ "command": { "action": "openSettings", "target": "settingsUI" }, "id": "Terminal.OpenSettingsUI" },
{ "command": { "action": "openSettings", "target": "settingsFile" }, "id": "Terminal.OpenSettingsFile" },
{ "command": { "action": "openSettings", "target": "defaultsFile" }, "id": "Terminal.OpenDefaultSettingsFile" },
{ "command": { "action": "openSettings", "target": "directory" }, "id": "Terminal.OpenSettingsDirectory" }

可以看到，规格书设想的 settingsUI 选项如今扩展成了完整的 target 族：settingsUI（打开设置 UI）、settingsFile（打开 JSON 文件，即规格书中"打开 JSON 文件"按钮的等价能力）、defaultsFile（打开默认设置文件）与 directory（打开设置目录）。OpenSettingsArgs 结构体在 ActionArgs.h 中定义，并通过 ACTION_ARGS_STRUCT(OpenSettingsArgs, OPEN_SETTINGS_ARGS) 宏注册；应用侧的处理器 _HandleOpenSettings 位于 AppActionHandlers.cpp，负责根据 target 分发到对应行为。

三、启动方式：在新标签页中打开

规格书选择了"点击下拉菜单中的设置按钮后，在新标签页中打开设置 UI"作为方案，理由是：

这是 Terminal 支持"标签页内放置非终端内容"的第一步；
用户可以在设置 UI 内置的预览窗口中直接看到视觉变更效果。

作为对比，规格书还讨论了"在新窗口中打开"的方案：它的好处是能边改边看 Terminal 实时刷新，但任务栏中会出现多个 Terminal 窗口的图标。最终新标签页方案胜出。

源码印证了"标签页内嵌设置页"的实现。Tab.cpp 在序列化标签页状态时有一段特殊处理（见 Tab.cpp#L575-L586）：当标签页内只有一个 pane 且它是 settings pane 时，会被提升为一个 openSettings 动作而非普通 newTab 动作——注释明确指出，openSettings 动作自身带有一套"防止出现多个顶级设置标签页"的机制。这正是规格书中"设置 UI 作为标签页"设计的直接产物。

入口方面，TerminalWindow.cpp 的下拉菜单项通过 _OpenSettingsUI 调用 TerminalPage.cpp 中的 OpenSettingsUI()（见 TerminalWindow.cpp#L845-L847），完成了"下拉菜单 → 新标签页内设置 UI"这条完整链路。

四、编辑与保存：Save 按钮 + 内置预览窗口

规格书在编辑保存机制上做出了两个关键选择：

实现 Save 按钮：用户只有点击"Save"后，变更才会写入 settings.json。这与"在文本编辑器里改 JSON 再保存"的既有体验一致，也避免了误操作即时落盘；
内置 TerminalControl 预览：在设置 UI 中嵌入一个 TerminalControl，让用户在真正保存前预览变更效果。

作为对比，"自动保存"方案（编辑即写盘、实时生效）被讨论过但最终未采用。

配套设计文档 [design.md](https://gitcode.com/GitHub_Trending/term/terminal/blob/20588130d8ef2ba40eb56bdae88e04cce7fc5b5d/doc/specs/?utm_source=gitcode_repo_files#1564 - Settings UI/design.md) 进一步界定了预览窗口的出现位置：仅出现在 Appearance - Color Schemes 和 Profiles - Appearance 两个页面，因为这两个页面直接决定终端的视觉呈现。在源码中，这一预览连接能力对应 TerminalSettingsEditor 目录下的 PreviewConnection.cpp / PreviewConnection.h；而 NullableColorPicker 等自定义控件则支撑了设计稿中大量的"color picker"控件。

五、顶层导航：分组式导航 vs 对齐 JSON 结构

这是规格书中最有实质内容的设计决策。规格书提出了两版导航结构：

方案 A（最终采纳）：更具描述性的分组导航

导航菜单被拆分为更易于消化的区块，与其他终端产品的习惯对齐。提案的导航项为：

General（通用）
- Startup（启动）
- Interaction（交互）
- Rendering（渲染）
Appearance（外观）
- Global（全局）
- Color schemes（配色方案）
- Themes*（主题）
Profiles（配置文件）
- Defaults（默认值）
- Enumerate profiles（枚举配置文件）
- Add new（新建）
Keyboard（键盘）
Mouse*（鼠标）
Command Palette*（命令面板）
Marketplace*（市场）

其中标注星号的 Themes、Mouse、Command Palette 与 Marketplace 会在对应功能实现后加入导航。

![设置 UI 分组式导航结构](https://gitcode.com/GitHub_Trending/term/terminal/blob/20588130d8ef2ba40eb56bdae88e04cce7fc5b5d/doc/specs/?utm_source=gitcode_repo_files#1564 - Settings UI/navigation-2.png)

方案 B（被考虑）：对齐 settings.json 的顶层结构

设置 UI 的顶层导航直接对应 settings.json 的整体结构：Globals、Profiles、Color schemes、Bindings（其中 Bindings 内再含 key bindings、mouse bindings、command palette 三个子项）。这一方案的优点是用户能从 JSON 文件无缝迁移心智模型，最终未被采纳。

![设置 UI 对齐 JSON 结构的备选导航](https://gitcode.com/GitHub_Trending/term/terminal/blob/20588130d8ef2ba40eb56bdae88e04cce7fc5b5d/doc/specs/?utm_source=gitcode_repo_files#1564 - Settings UI/navigation.png)

从仓库结构看，方案 A 的导航项如今与 src/cascadia/TerminalSettingsEditor/ 目录下的页面文件一一对应，可以逐页印证：

导航页	源码实现
General - Startup	`src/cascadia/TerminalSettingsEditor/Launch.cpp`
General - Interaction	`src/cascadia/TerminalSettingsEditor/Interaction.cpp`
General - Rendering	`src/cascadia/TerminalSettingsEditor/Rendering.cpp`
Appearance - Global	`src/cascadia/TerminalSettingsEditor/GlobalAppearance.cpp`
Appearance - Color schemes	`src/cascadia/TerminalSettingsEditor/ColorSchemes.cpp`
Profiles（默认/枚举/高级）	`src/cascadia/TerminalSettingsEditor/Profiles_Base.cpp`、`Profiles_Advanced.cpp`、`Profiles_Appearance.cpp`
Profiles - Add new	`src/cascadia/TerminalSettingsEditor/AddProfile.cpp`
Keyboard	`src/cascadia/TerminalSettingsEditor/Actions.cpp`

设计文档中还描述了键盘页的交互细节：页面以表格列出全部已启用键位绑定，鼠标悬停时浮现 Edit/Delete 按钮；点击 Edit 后弹出模态框，且当所选命令带有额外参数/动作时，模态框会随参数动态加高。设计稿还提到未来希望输入框能"监听"用户按下的键组合（listen 按钮）——这一能力在源码中由 KeyChordListener.cpp 实现。

各页面承载的配置项

design.md 给出了完整的页面-配置项映射（此处按页面归纳，控件类型与原文档一致）：

General - Startup：Default profile（下拉）、Launch on startup（复选框）、Launch size（单选）、Launch position（文本框）、Columns on first launch / Rows on first launch（数字选择器）、Automatically create new profiles when new shells are installed（复选框）；
General - Interaction：Copy after selection is made（复选框）、Copy formatting（复选框）、Word delimiters（文本框）、Window resize behavior（复选框）；
General - Rendering：Software rendering（复选框）、Screen redrawing（复选框）；
Appearance - Global：Theme（单选）、Show/Hide the title bar（复选框）、Show terminal title in title bar（复选框）、Always show tabs（复选框）、Tab width mode（单选）、Hide close all tabs popup（复选框）；
Appearance - Color Schemes：Name（文本框）加 16 个 ANSI 颜色（Cursor color、Selection background、Background、Black/Blue/Cyan/Green/Purple/Red/White/Yellow 及 Bright 变体，均为 color picker）；
Profiles - Global（默认值）：General 组（Command line、Starting directory、Icon、Tab title、Scrollbar visibility）、Appearance 组（Font face、Font size、Font weight、Padding、Cursor shape、Cursor color、Cursor height、Color scheme、Foreground/Background/Selection background color、Enable acrylic、Acrylic opacity、Background image 及其 stretch mode/alignment/opacity、Retro terminal effects）、Advanced 组（Hide profile from dropdown、Suppress title changes、Antialiasing text、AltGr aliasing、Scroll to input when typing、History size、How the profile closes）；
Profiles - Enumerate profiles / Add new：对每个配置文件提供与默认值页相同的 General / Appearance / Advanced 三组控件，外加 GUID（文本框）。

六、能力评估（Capabilities）

规格书对各非功能维度给出了明确结论：

Accessibility（可访问性）：设置 UI 是全新的 UI 元素，必须通过完整的可访问性测试——所有条目都要支持屏幕阅读器和键盘操作，并且整个设置 UI 需要本地化；
Security（安全性）：无影响；
Reliability（可靠性）：不会提升可靠性；
Compatibility（兼容性）：默认体验从"文本编辑器打开 JSON"变为"打开设置 UI"，该行为可以通过上文 openSettings 的选项回退；
Performance / Power / Efficiency：不影响性能、功耗与效率。

七、未来考量（Future Considerations）

规格书在结尾列出了数项需要后续处理的问题，它们也解释了今天 Windows Terminal 设置 UI 的若干特性由来：

所有内容页都需要经过设计评审；
hidden 属性需要特殊考虑——理想情况下，无论 hidden 是否为 true，所有配置文件都应出现在设置中；
需要撤销功能：文本编辑器里可以 Ctrl+Z，而设置 UI 的撤销机制更为复杂；
待主题与扩展市场（marketplace）就绪后，将其加入顶层导航；
随着功能增加，顶层导航可能为提升可用性而调整。

八、小结：从规格到实现

回看整份规格文档，它回答了设置 UI 的三个根本问题——能否关闭（openSettings 的 target 参数，见 defaults.json）、如何打开（新标签页 + 防重复标签机制，见 Tab.cpp 与 TerminalWindow.cpp）、如何保存（Save 按钮 + TerminalControl 预览，见 TerminalSettingsEditor 中 PreviewConnection 与各 ViewModel）。规格书中的导航分组方案最终成为 TerminalSettingsEditor 目录组织的蓝图，而"键盘页模态框 + 键位监听"等设计细节也演进为 Actions.cpp、EditAction.cpp、KeyChordListener.cpp 等具体实现。如果你想深入某一条设置的 JSON 字段语义，可继续参考 profiles.schema.json 与 AddASetting.md。