【口算王17】HarmonyOS ArkTS 亮暗色与视觉令牌实战集中颜色、间距和交互状态避免页面割裂证据边界本文依据 D:/huawei/one16-11 当前可读取源码与资源文件整理本轮未执行构建、模拟器、真机、系统暗色切换、字体缩放或 AppGallery 审核。迁移路线属于建议实现不代表双主题已完成。视觉一致性不是“所有页面都用同一个蓝色”。一个可维护的主题系统需要回答背景和卡片是什么关系主文字与提示文字如何分级收藏、正确、错误和警告分别表达什么语义字号、圆角、间距和触控尺寸由谁统一管理以及系统切到暗色时应用究竟跟随还是保持浅色。口算王当前选择了明确的浅色策略EntryAbility调用setColorMode(COLOR_MODE_LIGHT)页面主要消费librarya导出的Colors和Sizes。蓝色作为主操作色橙色作为强调色背景、表面、文字、分割线和答题状态都有集中常量。但源码也存在三类边界base 与 dark 的资源颜色完全相同且仍是旧绿色方案ArkTS 页面没有使用app.color.*entry 与 librarya 各有一份 ThemeConstants另有 15 个文件仍包含硬编码色值。本文基于口算王项目D:\huawei\one16-11的真实源码复核EntryAbility.ets、entry 与 librarya 中的ThemeConstants.ets、base/darkcolor.json、PracticePage.ets、HomePage.ets、FavoritePage.ets、SearchPage.ets、SettingsPage.ets与共享组件。包名com.jiaweikang.one16是本文草稿核验使用的唯一标记。项目目标和兼容 SDK 均为 HarmonyOS 6.0 系列本文方法适用于 HarmonyOS 5.0 及以上 ArkUI 应用。本文将完成六件事区分“锁定浅色”和“完成亮暗色适配”梳理品牌、背景、文字和状态令牌分析字号、间距、圆角与触控尺寸的统一作用复核答题选中、正确、错误等真实交互状态找出资源颜色、重复常量和硬编码颜色的漂移风险给出从浅色锁定迁移到资源化双主题的实施路径。一、先明确当前真实主题策略应用启动时执行this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT)这表示应用主动锁定浅色模式。系统切换到暗色时应用仍应保持浅色视觉不是自动解析 dark 资源。因此当前能力应准确描述为已实现浅色模式锁定已建立浅色视觉令牌已提供 dark 资源目录但内容未形成暗色配色未实现用户主题开关未实现跟随系统的动态双主题。把 dark 目录存在等同于暗色适配完成会造成能力夸大。二、为什么锁定浅色也需要验证系统暗色锁定浅色并不意味着可以跳过暗色环境测试。系统状态栏、导航栏、启动窗口和某些系统组件仍可能受系统模式影响。必须在设备开启暗色时检查页面背景是否仍是预期浅色状态栏图标是否与浅背景有足够对比启动窗口是否闪现深色系统弹窗和应用自定义弹窗衔接是否突兀图片、图标是否被错误反色Web 或第三方组件是否自行跟随系统。当前源码主动设置浅色是一个产品选择也是一项需要全链路验证的发布约束。三、颜色令牌按语义分层librarya 的 Colors 不是平铺色板而是按角色组织。品牌层PRIMARY#2F6BFFPRIMARY_DARK#1746C8PRIMARY_LIGHT #EAF1FFACCENT#E46B18PRIMARY 用于主按钮、选中、链接和重要图标PRIMARY_DARK 用于渐变深端PRIMARY_LIGHT 用于浅底标签和选中背景ACCENT 提供第二强调色。表面层BACKGROUND#F6F8FFBACKGROUND_ALT#FFF8EASURFACE #FFFFFFBACKGROUND 是页面底色SURFACE 是卡片和操作栏BACKGROUND_ALT 用于提示、说明和局部强调区。内容层TEXT_PRIMARY#111B3DTEXT_SECONDARY#34405ETEXT_HINT #6A7388三级文本不是通过随意调透明度产生而是使用稳定色值表达标题、正文和提示层级。状态层SUCCESS#21A66BERROR#B3261EWARNING #8A5A00DIVIDER#E3E8F5状态色承担业务语义不能只当装饰色使用。四、浅色主题不是单一蓝色口算王同时使用蓝、橙、绿、红和暖黄色背景。蓝色负责主路径橙色负责强调绿色表达正确与成功红色表达错误和破坏性操作暖黄色承担提示。这种一主多语义配色避免整个应用只剩蓝色深浅变化。不同颜色的使用规则比色值本身更重要主操作统一蓝色次级强调优先橙色正确只使用 SUCCESS错误、删除和高风险只使用 ERROR提示文字不使用状态色浅色背景必须搭配足够深的文字或边框。五、答题选项拥有完整状态令牌PracticePage 的答案选项使用专门令牌状态背景边框默认OPTION_BGOPTION_BORDER已选OPTION_SELECTED_BGOPTION_SELECTED_BORDER正确OPTION_CORRECT_BGOPTION_CORRECT_BORDER错误OPTION_WRONG_BGOPTION_WRONG_BORDER页面根据是否提交、当前答案和正确答案选择颜色if(!submitted) {returnselectedKeykey? Colors.OPTION_SELECTED_BG:Colors.OPTION_BG}if (key question.answer) return Colors.OPTION_CORRECT_BGif(keyselectedKey)returnColors.OPTION_WRONG_BGreturnColors.OPTION_BG这比在 Builder 中散落六七个十六进制值更容易审查也能保证所有答案按钮状态一致。六、颜色之外还要有结构令牌Sizes 集中管理字号、圆角、图标、间距和固定控件高度H1_FONT22H2_FONT18TITLE_FONT 16BODY_FONT14CAPTION_FONT12SMALL_FONT 10CARD_RADIUS16BTN_RADIUS24PADDING_SMALL 8PADDING_MEDIUM12PADDING_LARGE16PADDING_XL 20librarya 版本还定义TOUCH_TARGET 44并包含导航栏、搜索栏和 Banner 高度。它们共同决定页面节奏而不仅是“几个常量”。七、字号体系需要结合审核下限当前 SMALL_FONT 为 10CAPTION_FONT 为 12BODY_FONT 为 14。10vp 小字主要用于 Tab 标签、徽标或次要信息不应承担关键正文。发布前应逐项检查正文优先保持 14vp说明与辅助文字保持 12vp10vp 只用于非常次要且短的标签PC/2in1 常规文字应验证是否需要至少 14vp系统字体放大后容器不截断长文本有 maxLines、ellipsis 或可增长高度。视觉令牌统一了默认值但不能替代具体页面的可读性验证。八、触控尺寸是视觉系统的一部分44vp 的 TOUCH_TARGET 不只是交互常量也决定图标按钮周围的留白。SearchPage 的返回、搜索等按钮使用固定触控容器图标尺寸小于容器既保持视觉轻量又让点击区域足够大。如果页面直接把 18vp 图标作为点击目标即使颜色和圆角一致交互体验仍不合格。令牌应区分图标视觉尺寸按钮触控尺寸控件间最小间距文本与图标的基线关系。九、输入框令牌补足可编辑状态librarya 的 Colors 还包含INPUT_TEXTINPUT_PLACEHOLDERINPUT_BGFavoritePage 和 PracticePage 的输入区域使用这些值并把光标设为 PRIMARY、边框设为 DIVIDER。输入状态至少需要验证默认、聚焦、已输入、占位、错误和禁用。当前项目集中管理了基础文本与背景但没有完整的 focus/error 输入令牌矩阵后续可补充 INPUT_FOCUS_BORDER、INPUT_ERROR_BORDER 和 DISABLED 系列。十、组件消费语义令牌而不是页面猜颜色共享组件 BankCard、GreenButton、ProgressBar、TopBar 和 EmptyState 都从 Colors/Sizes 取得样式。页面使用组件时只传业务数据和交互不需要重新决定主色、卡片背景和圆角。理想依赖方向是Theme Tokens-Shared Components- Feature Pages页面不应反向定义组件颜色也不应让不同业务模块复制同一套按钮样式。十一、alpha 工具统一透明色格式ThemeConstants 提供alpha(color, alphaHex)把#RRGGBB转为 ArkUI 使用的#AARRGGBBreturn#alphaHexcolor.substring(1,7)它可以用于投影、遮罩和浅色选中层减少手工拼错 alpha 位置。当前函数只做最小长度检查没有验证输入一定是合法六位颜色也不支持已有 alpha 的八位颜色。作为内部受控工具足够若开放给更多模块建议增加格式校验和明确返回类型。十二、base 与 dark 资源当前完全相同项目存在entry/src/main/resources/base/element/color.jsonentry/src/main/resources/dark/element/color.json但两份内容相同包括白色背景、绿色 primary 和灰色文字。dark 目录没有深色表面与浅色文字。更关键的是ArkTS 页面搜索不到$r(app.color...)的消费。页面实际使用的是 Colors 字符串常量。也就是说这两套资源目前不是页面主题真值。十三、资源颜色与实际蓝色主题已经漂移资源文件的 primary 是#4CAF50绿色而实际 Colors.PRIMARY 是#2F6BFF蓝色。start window 使用资源背景页面进入后使用常量背景。这会产生两个风险启动窗口与首个页面色彩不一致开发者误以为修改 color.json 就能改变全局主题。主题系统必须只有一个清晰真源。若选择资源化应把蓝橙方案迁入 base/dark 并让组件消费资源若暂时保留常量就应明确资源仅服务启动窗口避免同名令牌表达不同色值。十四、entry 与 librarya 存在重复 ThemeConstantsentry 目录和 librarya 都有 ThemeConstants。大多数页面从 librarya 导入 Colors/Sizesentry 版本还包含题型图标和带印章资源的等级映射。两份颜色常量当前大体一致但已经出现能力差异librarya 增加 INPUT_*librarya 增加 TOUCH_TARGETentry 的 RankInfo 包含 stamp Resourceentry 的题型函数引用 app.media。重复文件会让“修改了一个却没有生效”变得常见。更合理的拆分是librarya 保留纯颜色、尺寸和无 app 资源依赖的模型entry 保留题型图标、印章等产品资源映射entry 不再复制 Colors/Sizes。十五、硬编码颜色并非全部错误源码中 15 个 ArkTS 文件仍含十六进制颜色。它们大致分为三类。合理局部色图片上的半透明黑色遮罩白色渐变文字题型专属色特定插画背景。应抽取的语义色输入状态色收藏未选中颜色提示按钮颜色多处重复的弹窗遮罩。应资源化的主题色-主文字页面背景卡片表面分割线主品牌色。目标不是消灭所有#而是消灭重复且具有跨组件语义的硬编码。十六、遮罩透明度也应形成令牌多个页面使用#66000000作为弹窗遮罩卡片图片上还出现#8A000000、#33000000和#29000000。这些透明黑色有不同职责ModalScrim阻断背景交互ImageScrimStrong保证图片上白字可读ImageScrimSoft轻度压暗图片ShadowColor表达层级而非遮挡。为它们命名后设计调整不需要全仓搜索十六进制值也能避免同一种遮罩在不同页面透明度漂移。十七、状态不能只靠颜色表达答题正确使用绿色、错误使用红色但无障碍与低色觉用户不能只依赖色相判断。当前 PracticePage 同时会显示解析、边框与状态变化结果页也有“正确/错误/未答”图例。后续仍应检查正确项是否有文字或图标错误项是否显示实际选择选中项是否有边框或形状变化禁用项是否仍可辨认图例是否与实际网格一致高对比模式下语义是否保留。十八、对比度必须用实际组合验证只检查单个色值没有意义对比度属于前景与背景组合。重点组合包括前景背景场景TEXT_PRIMARYSURFACE卡片正文TEXT_HINTBACKGROUND辅助说明PRIMARYPRIMARY_LIGHT标签与链接SUCCESSOPTION_CORRECT_BG正确答案ERROROPTION_WRONG_BG错误答案白色PRIMARY/PRIMARY_DARK渐变主卡占位文字INPUT_BG输入框正文目标应高于 4.5:1关键图标和较大文字至少应高于 3:1。禁用态也不能淡到不可识别。十九、浅色锁定下的系统栏必须一起设计EntryAbility 设置了浅色模式但当前文章范围内没有看到统一的窗口系统栏颜色策略。页面背景是近白蓝系统栏图标应使用适合浅背景的深色样式。需要实机验证Splash 到 Index 时状态栏是否闪烁顶部背景变化时图标是否可读全屏图片页是否需要单独调整底部导航与系统导航区背景是否连续横屏和分屏时系统栏是否出现割裂。锁定应用颜色模式并不会自动完成所有系统栏适配。二十、如果未来跟随系统应先资源化真正的双主题不适合继续维护两套 ArkTS 字符串常量。更稳妥的路径是在 base color.json 定义浅色语义值在 dark color.json 用相同 name 定义暗色值组件改用$r(app.color.token_name)移除 EntryAbility 的浅色锁定或改为跟随系统为图片和图标提供可着色资源或暗色变体验证窗口生命周期中的模式变化。同名资源是关键组件只引用语义名称系统根据 qualifier 选择实际色值。二十一、暗色不是把背景改黑暗色主题需要重新设计层级页面背景与卡片表面必须有可见差异主文字、次文字和提示文字重新建立亮度层级PRIMARY_LIGHT 不能继续使用很亮的浅蓝底SUCCESS/ERROR 在深色背景上需要调整明度与饱和度阴影可能需要改为描边或表面层级图片遮罩与白字组合要重新验证输入框、弹窗、底部栏和分割线全部需要暗色值。直接沿用当前 dark 文件会得到白色背景因此它不能算暗色实现。二十二、主题迁移要分阶段避免大面积回归建议按风险从低到高迁移第一阶段清理真源删除 Colors/Sizes 重复定义统一由 librarya 提供entry 只保留资源映射。第二阶段补齐语义抽取遮罩、输入焦点、禁用、悬停、按压和收藏状态令牌。第三阶段资源化基础组件先迁移 TopBar、GreenButton、BankCard、ProgressBar、EmptyState。第四阶段迁移页面按 Home、Practice、Favorite、Settings 等主流程逐页替换。第五阶段建立 dark 值完成双主题资源、移除浅色锁定并运行全页面回归。二十三、主题测试矩阵维度测试场景模式系统浅色、系统暗色、应用锁定浅色页面启动、首页、训练、挑战、收藏、我的、设置状态默认、选中、按压、禁用、正确、错误、警告输入空、占位、聚焦、已输入、错误覆盖层弹窗、底部 Sheet、图片遮罩设备手机、平板、2in1、小窗、横屏字体默认、放大、长文本系统区状态栏、导航栏、手势区每个场景都要检查颜色、对比度、文字溢出、图标可见性和操作状态。二十四、视觉令牌也需要自动检查可在本地增加轻量审计脚本扫描页面中的硬编码颜色检查重复色值是否已有令牌对关键前景/背景组合计算对比度检查 base/dark 是否拥有相同资源名检查 dark 值是否与 base 完全相同检查字号是否低于项目下限检查触控容器是否小于 44vp。脚本不能替代目视检查但能提前拦截明显漂移。二十五、发布审核前的视觉检查发布前应确认App 图标在浅色、暗色、启动页和商店中清晰应用实际是锁定浅色还是跟随系统文档与代码一致状态栏、导航栏和页面背景连续正文对比度高于 4.5:1关键图标和大文字对比度高于 3:1正确、错误、警告不只靠颜色弹窗遮罩下内容仍可辨认输入框占位和禁用态不过淡字体放大后按钮和卡片不截断所有设备形态没有白字白底或深字深底。二十六、常见问题排查表症状可能原因检查点修改 color.json 页面不变页面使用 Colors 字符串导入来源系统暗色下仍是浅色EntryAbility 强制 LIGHT当前产品策略dark 目录存在但页面不暗dark 值与 base 相同资源内容启动页绿色、页面蓝色资源与常量主题漂移start window某些输入框颜色不同librarya 与 entry 常量能力不同重复 ThemeConstants弹窗遮罩深浅不一透明黑色硬编码抽取 Scrim 令牌正确答案不易识别只依赖绿色增加文字、图标和边框小字难读SMALL_FONT 用于关键内容字号职责深色迁移后浅蓝底刺眼PRIMARY_LIGHT 未提供暗色值语义资源2in1 控件难操作只验证颜色未验证输入焦点与触控尺寸二十七、总结令牌统一的是语义不只是色值口算王当前视觉系统的真实基础是应用锁定浅色librarya 的 Colors/Sizes 提供蓝橙品牌、表面层级、三级文字、状态色、答题选项色、字号、间距、圆角和触控尺寸共享组件与页面广泛消费这些令牌。这已经明显降低了页面割裂。同样需要正视三项未完成工作base/dark 资源仍是相同的旧绿色方案页面没有消费 app.color 资源entry 与 librarya 存在重复主题常量部分语义颜色仍散落在页面。下一步不应直接“加一套黑色”而应先统一主题真源、补全语义令牌、迁移共享组件再建立同名的浅色和暗色资源。视觉令牌真正统一的是“这个颜色在表达什么”只有语义稳定亮暗色、多设备和交互状态才能一起演进。二十三、从锁定浅色迁移到双主题的最小实施顺序如果团队决定从当前的锁定浅色迁移到跟随系统第一步不应立即删除COLOR_MODE_LIGHT而是先消除令牌源的分叉。entry 与 librarya 同时维护ThemeConstants意味着相同名字可能在两个模块中得到不同值页面一旦混用后续很难判断某个颜色究竟来自哪个版本。应先确定唯一公共出口逐个修正导入路径再用搜索确认旧出口没有剩余调用。第二步是处理硬编码色值。搜索十六进制颜色只是入口还要区分品牌常量、临时调试值、透明遮罩和真正的页面私有颜色。能够表达业务含义的值应改成语义令牌例如“主按钮背景”“次级文字”“错误边框”而不是按视觉外观命名为“深蓝”“浅灰”。这样即使暗色模式下实际色值变化组件含义仍然稳定。第三步才是资源化。为 base 与 dark 提供同名颜色资源并让令牌层通过资源引用获得实际值。资源名称应表达角色而不是模式例如page_background、surface_primary、text_secondary不要创建light_background和dark_background后再由页面手工判断模式。模式解析应交给资源系统业务页面只消费统一语义。第四步是补齐交互状态。按钮、输入框、列表项、答案选项和开关不能只验证默认状态。至少应覆盖默认、按下、选中、聚焦、禁用、正确、错误和加载中并检查每个状态在浅色与暗色下是否仍可区分。状态不能只依赖颜色还应结合图标、边框、文字或形状反馈避免色觉差异用户无法理解。第五步才移除强制浅色并进行验证。验证范围应包含首次启动、前后台切换、系统模式实时切换、状态栏与导航栏、弹窗、键盘、长文本、字体放大、小窗、横竖屏以及平板或 2in1。图片和自定义图标也要单独检查因为它们可能不会自动响应资源变化。这套顺序的关键是把“代码收敛”“资源映射”和“运行验证”拆开。若三件事同时进行一旦出现文字不可见或页面闪色很难定位是重复常量、错误资源还是生命周期刷新导致。逐层迁移虽然步骤更多但每一步都有可搜索、可回滚、可复核的验收点。二十四、发布前可执行的视觉令牌检查表提交前可以用一份短检查表降低遗漏概率确认页面不新增散落色值确认所有关键文字和背景达到可读对比确认 10vp 小字不承载核心信息确认图标视觉尺寸与触控区域分离确认正确、错误、警告没有混用语义确认禁用状态仍能看清但不会误导为可点击确认状态栏和导航栏在实际背景上可读确认系统字体放大后按钮和卡片不会截断。对于当前口算王工程这份检查表只能作为下一轮验证计划。本文没有执行构建、模拟器或真机切换因此不能据此宣称暗色适配、对比度审核或多设备体验已经通过。可靠的结论仍然是工程已经建立较完整的浅色令牌基础同时存在双份常量、未差异化 dark 资源和硬编码色值等迁移风险。