羽球联盟 HarmonyOS NEXT 实战系列 (06/20)：主题Token、Resource颜色与深色模式准备

文章导读

• 颜色、字号、间距、圆角集中在 主题定义，页面只引用语义 token。
• Resource 颜色通过 base 与 dark 资源自动适配深浅色。
• 少量字符串色保留给 badge/tag 等数据模型字段。

页面效果

个人中心、首页卡片和底部导航应使用同一套主色、背景色、文字层级和圆角节奏，切换深浅色后仍保持可读。

实战拆解

一个资讯应用页面很多，如果每个页面都直接写 #0F7B5F、16、8，视觉会很快失控。羽球联盟把主题拆成 AppColors 和 AppSizes，页面只关心语义：主色、正文色、页面背景、卡片背景、分割线、常用字号和间距。

这里最值得写清楚的是 Resource 颜色和字符串色的边界。会跟随深色模式变化的页面背景、文本、主色，使用 $r 引用资源；作为数据标签传入的 tagColor 仍保留 string，因为 Tag 组件可能需要拼接或从模型读取字符串色。

关键代码

export class AppColors { static readonly primary: Resource = $r('app.color.primary'); static readonly textPrimary: Resource = $r('app.color.text_primary'); static readonly bgPage: Resource = $r('app.color.bg_page'); } export class AppSizes { static readonly s16: number = 16; static readonly r8: number = 8; }

主题 token 把视觉值收束到语义层，页面代码读到的是“主色”和“页面背景”，不是一堆散落数字。

取舍分析

这里的取舍可以从两个方向看：一边要让当前页面足够直观，用户打开后能马上理解入口、状态和反馈；另一边要给后续迭代留下余量，避免把数据处理、视觉样式和跳转逻辑全部写死在同一个地方。颜色、字号、间距和圆角应先有语义，再进入页面。 会随系统外观变化的颜色用资源承载，标签色等数据色保持字符串更灵活。

设计落点

• 颜色、字号、间距和圆角应先有语义，再进入页面。
• 会随系统外观变化的颜色用资源承载，标签色等数据色保持字符串更灵活。
• 深色模式不是最后补丁，而是页面持续使用 token 后自然生效。

易踩坑

• 不要把 Resource 和 string 颜色混用到难以追踪，先定义语义边界。
• 不要在卡片内部再发明局部颜色体系，除非它是可复用组件的明确变体。

验证方式

• 切换系统深浅色，检查背景、正文和分割线可读性。
• 观察首页、详情页、个人中心是否使用一致间距。
• 修改主色后确认底部导航和按钮同步变化。

小结

主题Token、Resource颜色与深色模式准备 的价值在于把页面现象和工程边界放在一起看：用户看到的是流畅的入口、列表、详情和反馈，开发者真正维护的是状态、模型和组件之间的关系。这个思路迁移到其他 ArkTS 项目时，比单独记某个 API 更可靠。