主题定制 dev 5.2.x 沿用 main 4.1.x 三层主题

版本边界（以 qxj_harmony_next_pad_nsp_browser 仓库为准）

• main 4.1.54 已交付三层相互独立的配色能力：工具栏 10 套主题、浏览器界面亮 / 暗、网页内容暗色，均支持持久化。
• dev 5.2.89 没有扩展主题体系：无品牌色运行时注入、无字号倍率、无应用图标切换（全仓检索均无对应实现），新增视图统一复用既有色板。
• 旧文档中关于品牌色定制、字号缩放、图标切换的内容无代码依据，已删除；「main 仅跟随系统暗色」的说法亦不准确。

1. 设计思路：三层独立配色

浏览器的视觉由三个作用域不同的配色层叠加而成，互相不耦合、可独立组合：

配色层	作用对象	工具 / 数据	持久化键	AppStorage 键	默认值
工具栏主题	顶部工具栏（地址栏、按钮、芯片）	BrowserThemeUtil + 10 套 BrowserTheme	browser_theme	browser_theme_id	dark 深邃黑
界面亮 / 暗	浏览器自身页面与弹层（菜单、设置、历史等）	BrowserUiModeUtil + UiPalette	ui_dark_mode	browser_ui_dark_mode	dark（暗）
网页暗色	Web 内网页内容	WebDarkModeUtil（Web .darkScheme）	web_dark_mode	—	dark（暗）

拆成三层的原因是三者的语义不同：工具栏主题是「品牌与个性化表达」，界面亮暗是「应用 chrome 的整体观感」，网页暗色是「第三方内容的反色算法」——合成一个总开关会牺牲组合自由度，例如可以「深邃黑工具栏 + 亮色页面区 + 强制网页暗色」这样混搭使用。

4. 交付版（main 4.1.x · 甲方交付）

4.1 工具栏：10 套主题色板

BrowserTheme 不是单一颜色，而是一套包含 7 个字段的完整色板：

• toolbarBg：工具栏背景色；
• chipBg：按钮 / 地址栏容器底色（彩色主题用半透白叠出层次感）；
• textPrimary：主文字色（地址栏网址）；
• textSecondary：次要文字与图标色（导航、菜单按钮）；
• textPlaceholder：占位与弱提示色；
• textDisabled：禁用态文字色；
• clearBtnBg：地址栏清空按钮底色。

每套主题都提供全部 7 个字段，保证切换后无任何「漏网」原色。10 套预置如下（顺序即菜单展示顺序）：

id	名称	主背景色
default	默认白	#FFFFFF
dark	深邃黑（默认）	#202124
blue	晴空蓝	#1A73E8
green	薄荷绿	#34A853
orange	暖阳橙	#F29900
indigo	靛青蓝	#3F51B5
purple	黛紫	#9334E6
teal	青碧	#00897B
pink	樱粉	#E91E63
graphite	石墨灰	#5F6368

主题选择在浏览器菜单中以色板圆点横排展示，点击即时生效。BrowserThemeUtil 在读取时做 id 合法性校验（isValidId，不在预置列表中的脏值会被拒），并提供 getThemeById；BrowserView 通过 @Watch 监听主题变化重取色板（onThemeIdChange），无需重建页面。

4.2 浏览器界面：亮 / 暗模式

• BrowserUiModeUtil 维护 LIGHT、DARK 两套 UiPalette（12 字段），覆盖页面底色、分区底色、分割线、各级文字、图标等浏览器自有界面所需的全部颜色。
• 开关经 AppStorage 键 browser_ui_dark_mode 在 BrowserView、菜单弹框、各设置页之间共享；任一处切换，所有持有该键的组件经 @Watch 重取色板即时联动。
• 默认 dark，与平板设备常见的深色使用环境一致。
• 该层只影响应用自己的界面，不影响网页内容——网页区域由下一层控制。

4.3 网页内容：暗色算法

• WebDarkModeUtil 通过 Web 组件的暗色方案（.darkScheme）让内核对网页内容做智能反色，对未提供暗色样式的第三方站点同样生效。
• 开关独立持久化（web_dark_mode，默认 dark），在菜单中显示当前为「深色 / 浅色」。
• 与浏览器界面暗色完全解耦：界面暗色只改 chrome，网页暗色只改内容区，可分别开关。

4.4 三层之间的联动边界

• 三套设置各写各的首选项键、各推各的 AppStorage 键，互不感知，因此组合数为 10 × 2 × 2。
• 新打开的弹层 / 页面（如错误页、菜单）一律从 UiPalette 与当前 BrowserTheme 取色，保证三层切换后任意角落颜色一致，不出现硬编码色值。

5. 实验版（dev 5.2.x）

dev 分支在主题上的原则是只复用、不扩张：

• 三层配色机制、10 套工具栏色板、亮 / 暗默认值在 dev 与 main 完全一致。
• 多标签相关的新视图（标签条、标签管理页、查找条、阅读模式、下载弹层、错误页、二维码页、开发者工具等）全部从 UiPalette 与当前工具栏 BrowserTheme 取色，深浅模式与主题切换时自动跟随；这也是这些文件头部普遍注释「颜色取自 UiPalette，深浅模式自适应」的原因。
• 旧文档提到的「品牌色运行时注入、字号倍率调节、应用图标切换」经全仓检索（FontScale、BRAND_COLOR、setIcon 等关键字）确认在两个分支均不存在，属于无依据的规划性描述，不再作为功能记录。

因此主题能力的交付与面试讲解均以 main 4.1.x 的三层体系为准。

6. 设计要点回顾

• 分层解耦：工具栏主题、界面亮暗、网页暗色作用域清晰、独立持久化，用简单的组合关系覆盖丰富的视觉场景。
• 色板而非单值：每套主题提供完整字段，切换时零残留；新增界面只需从色板取色，天然可主题化。
• 脏值防御：主题 id 读取即校验，防止持久化数据被外部污染后渲染异常。
• 响应式集中管理：AppStorage 键 + @Watch 让跨页面、跨弹层的主题联动只需声明，不必手工广播。
• 文档忠于代码：未实现的「品牌色 / 字号 / 图标」规划不写入功能文档，保证交付材料的可验证性。