阅读时长：约 17 分钟 | 难度：★★★☆☆ | 篇章：第 1 篇 · 项目架构与设计哲学
对应源码：entry/src/main/ets/common/constants/Colors.ets、Styles.ets

前言

在大型 HarmonyOS 应用中，颜色与样式的管理直接决定了 UI 一致性、可维护性以及未来主题切换的可行性。玄象项目通过Colors.ets和Styles.ets两个常量类，构建了一套统一的"设计令牌（Design Tokens）"体系，让 45 个.ets文件共享同一套视觉语言。本篇将深入剖析玄象项目的设计令牌体系，带您掌握在 ArkTS 中实现可维护样式管理的最佳实践。

提示：设计令牌是设计系统（Design System）的核心概念，指将颜色、字号、间距、圆角等视觉元素抽象为命名常量。玄象项目虽小，但其令牌体系已具备工业级雏形。

一、设计令牌的三层抽象

1.1 三层架构总览

玄象项目的设计令牌体系分为三层：

1.2 三层关系图

element/color.json Colors.ets Styles.ets ───────────────── ────────── ────────── "primary_gold": "#D4A843" PRIMARY_GOLD = '#D4A843' GOLD_GRADIENT = { LIGHT_GOLD = '#F0D078' angle: 135, DARK_GOLD = '#A07830' colors: [ {color:'#F0D078',ratio:0}, {color:'#D4A843',ratio:0.5}, {color:'#A07830',ratio:1} ] }

提示：玄象项目当前Colors.ets与color.json存在一定的重复定义。生产环境可通过代码生成工具从color.json自动生成Colors.ets，消除冗余。

二、Colors.ets 颜色令牌体系

2.1 完整源码

exportclassColors{// 主色staticreadonlyPRIMARY_GOLD:string='#D4A843';staticreadonlyLIGHT_GOLD:string='#F0D078';staticreadonlyDARK_GOLD:string='#A07830';// 背景色staticreadonlyBG_DARK:string='#0A0E17';staticreadonlyBG_CARD:string='#1A1F2E';staticreadonlyBG_CARD_BORDER:string='#2A3040';staticreadonlyBG_CARD_HIGHLIGHT:string='#252B3D';// 文字色staticreadonlyTEXT_PRIMARY:string='#FFFFFF';staticreadonlyTEXT_SECONDARY:string='#B0B0B0';staticreadonlyTEXT_GOLD:string='#D4A843';staticreadonlyTEXT_DIM:string='#808080';// 五行色staticreadonlyWOOD_GREEN:string='#4CAF50';staticreadonlyFIRE_RED:string='#F44336';staticreadonlyEARTH_YELLOW:string='#FFC107';staticreadonlyMETAL_WHITE:string='#E0E0E0';staticreadonlyWATER_BLUE:string='#2196F3';// 宜忌色staticreadonlyYI_GREEN:string='#4CAF50';staticreadonlyJI_RED:string='#F44336';// 四象色staticreadonlyDRAGON_CYAN:string='#00BCD4';staticreadonlyBIRD_RED:string='#E91E63';staticreadonlyTIGER_WHITE:string='#ECEFF1';staticreadonlyTURTLE_PURPLE:string='#9C27B0';// 四季色staticreadonlySEASON_SPRING:string='#4CAF50';staticreadonlySEASON_SUMMER:string='#F44336';staticreadonlySEASON_AUTUMN:string='#FF9800';staticreadonlySEASON_WINTER:string='#2196F3';// 透明度staticreadonlyTRANSPARENT:string='#00000000';staticreadonlyGOLD_TRANSPARENT:string='#33D4A843';staticreadonlyCARD_OVERLAY:string='#CC1A1F2E';}

2.2 设计令牌的命名规范

玄象项目的颜色命名遵循类别_语义模式，便于阅读与查找：

2.3static readonly的意义

玄象项目所有颜色常量使用static readonly修饰：

staticreadonlyPRIMARY_GOLD:string='#D4A843';

这种修饰方式带来三大好处：

1. 静态访问：无需实例化即可通过Colors.PRIMARY_GOLD访问，减少对象创建开销。
2. 只读保证：readonly在编译期阻止意外修改，确保常量稳定。
3. 类型明确：显式标注string类型，让 IDE 智能补全更精准。

提示：在 ArkTS 严格模式下，未标注类型的常量会触发警告。玄象项目所有常量都显式标注类型，符合@typescript-eslint/recommended规则集。

2.4 颜色值格式选择

玄象项目颜色值统一采用#RRGGBB6 位 16 进制格式，对带透明度的颜色采用#AARRGGBB8 位格式。这种选择基于以下考量：

• 6 位格式：简洁、可读、与 CSS 一致。
• 8 位格式：明确表达透明度，避免rgba()函数调用的复杂语法。
• 避免命名颜色：'red'等命名颜色在不同浏览器渲染不一致，玄象项目避免使用。

三、Styles.ets 样式令牌体系

3.1 完整源码

import{Colors}from'./Colors';exportclassStyles{// 金色卡片样式staticreadonlyGOLD_CARD_BORDER_WIDTH:number=1;staticreadonlyGOLD_CARD_RADIUS:number=12;staticreadonlyGOLD_CARD_PADDING:number=16;// 通用边距staticreadonlyPAGE_PADDING:number=16;staticreadonlySECTION_SPACE:number=20;staticreadonlyITEM_SPACE:number=12;// 圆角staticreadonlyRADIUS_SMALL:number=8;staticreadonlyRADIUS_MEDIUM:number=12;staticreadonlyRADIUS_LARGE:number=20;staticreadonlyRADIUS_FULL:number=999;// 阴影staticreadonlySHADOW_GOLD:ShadowStyle={radius:10,color:'#33D4A843',offsetX:0,offsetY:4};// 金色渐变staticreadonlyGOLD_GRADIENT:LinearGradient={angle:135,colors:[{color:'#F0D078',ratio:0},{color:'#D4A843',ratio:0.5},{color:'#A07830',ratio:1}]};// 深色卡片渐变staticreadonlyDARK_CARD_GRADIENT:LinearGradient={angle:180,colors:[{color:'#1E2438',ratio:0},{color:'#1A1F2E',ratio:1}]};}

3.2 Styles.ets 的内容分类

Styles.ets封装了玄象项目所有页面共用的样式常量：

1. 数值常量：边距、圆角、宽度等数值。
2. 复合样式对象：阴影ShadowStyle、渐变LinearGradient等。
3. 颜色引用：通过import { Colors }间接引用颜色令牌。

3.3 ArkUI 类型化样式对象

玄象项目的SHADOW_GOLD与GOLD_GRADIENT直接使用 ArkUI 提供的类型化对象：

// 阴影样式对象staticreadonlySHADOW_GOLD:ShadowStyle={radius:10,color:'#33D4A843',offsetX:0,offsetY:4};// 渐变样式对象staticreadonlyGOLD_GRADIENT:LinearGradient={angle:135,colors:[{color:'#F0D078',ratio:0},{color:'#D4A843',ratio:0.5},{color:'#A07830',ratio:1}]};

ShadowStyle类型字段：

LinearGradient类型字段：

提示：玄象项目的GOLD_GRADIENT使用 135 度斜向渐变，模拟金属光泽。ratio字段表示颜色断点在渐变路径上的位置（0 = 起点，1 = 终点）。

四、设计令牌的使用方式

4.1 在 ArkUI 组件中引用颜色

// 直接引用 Colors 常量Text('玄象').fontSize(56).fontWeight(FontWeight.Bold).fontColor(Colors.PRIMARY_GOLD)// 在 Stack 容器设置背景Stack(){// ...}.backgroundColor(Colors.BG_DARK)

4.2 在 ArkUI 组件中引用复合样式

// 使用渐变背景Column(){// ...}.linearGradient(Styles.GOLD_GRADIENT)// 使用阴影Card(){// ...}.shadow(Styles.SHADOW_GOLD)// 使用统一圆角Column(){// ...}.borderRadius(Styles.RADIUS_MEDIUM)

4.3 在 border 中组合多个令牌

玄象项目的金边卡片组合使用多个令牌：

GoldBorderCard{// 等价于：// borderWidth = Styles.GOLD_CARD_BORDER_WIDTH// borderColor = Colors.PRIMARY_GOLD// borderRadius = Styles.GOLD_CARD_RADIUS// padding = Styles.GOLD_CARD_PADDING}

五、设计令牌带来的工程价值

5.1 一致性保证

玄象项目 45 个.ets文件统一引用Colors与Styles，确保：

• 同类元素颜色一致（所有卡片背景均为BG_CARD）。
• 同类元素圆角一致（所有中圆角均为RADIUS_MEDIUM= 12）。
• 同类元素间距一致（所有页面内边距均为PAGE_PADDING= 16）。

5.2 可维护性提升

当需要调整主题色时，仅需修改Colors.ets中一处定义，所有引用自动同步。例如将主金色从#D4A843调整为更鲜艳的#E6B84F，全应用瞬间生效。

5.3 主题切换可行性

基于设计令牌体系，玄象项目未来可通过以下方式实现主题切换：

1. 定义多套 Colors：ColorsGold、ColorsQing、ColorsInk等。
2. 运行时切换：通过@Provide注入当前主题，子组件通过@Consume获取。
3. 持久化用户偏好：将主题选择保存到@ohos.data.preferences，下次启动自动应用。

提示：主题切换是中大型应用的必备能力。玄象项目的设计令牌体系已经为这一能力铺平了道路，本系列第 94 篇会详细演示主题切换的完整实现。

六、设计令牌的扩展方向

6.1 字体令牌

玄象项目当前在组件内联中硬编码字体大小，未来可扩展为字体令牌：

exportclassTypography{staticreadonlyH1_SIZE:number=56;staticreadonlyH2_SIZE:number=28;staticreadonlyBODY_SIZE:number=16;staticreadonlyCAPTION_SIZE:number=12;staticreadonlyH1_WEIGHT:FontWeight=FontWeight.Bold;staticreadonlyBODY_WEIGHT:FontWeight=FontWeight.Normal;}

6.2 动画令牌

将动画时长与曲线封装为令牌：

exportclassMotion{staticreadonlyDURATION_FAST:number=200;staticreadonlyDURATION_BASE:number=300;staticreadonlyDURATION_SLOW:number=500;staticreadonlyEASE_OUT:Curve=Curve.EaseOut;staticreadonlyEASE_IN_OUT:Curve=Curve.EaseInOut;}

6.3 Z-index 令牌

避免层级冲突，定义统一的 z-index 令牌：

exportclassZIndex{staticreadonlyBASE:number=0;staticreadonlyDROPDOWN:number=100;staticreadonlyMODAL:number=1000;staticreadonlyTOAST:number=2000;}

七、玄象项目设计令牌的不足与改进

7.1 当前不足

玄象项目的设计令牌体系仍有以下改进空间：

1. 颜色与样式的关联较弱：GOLD_CARD_BORDER_WIDTH与PRIMARY_GOLD未组成"卡片样式包"。
2. 缺乏响应式断点：未定义不同屏幕尺寸下的间距 / 字号缩放规则。
3. 令牌文档缺失：缺少令牌清单与使用规范文档。

7.2 改进建议

建议玄象项目后续引入以下改进：

1. 样式包封装：将相关样式属性打包为"样式包"，例如CardStylePack包含边框、圆角、阴影、背景色。
2. 响应式令牌：引入MediaQuery监听屏幕尺寸，动态切换令牌值。
3. 令牌清单自动化：通过脚本扫描Colors.ets与Styles.ets，自动生成令牌清单 Markdown 文档。

九、常见问题与解答

9.1 Colors.ets 与 color.json 重复定义怎么办？

玄象项目当前Colors.ets与color.json存在重复定义。生产环境可通过脚本从color.json自动生成Colors.ets：

// build/scripts/generate-colors.js (示意)constcolors=require('./resources/base/element/color.json');constoutput='export class Colors {\n';colors.color.forEach(c=>{output+=`static readonly${c.name.toUpperCase()}: string = '${c.value}';\n`;});output+='}';// 写入 Colors.ets

9.2 如何实现主题切换？

基于设计令牌体系，可实现运行时主题切换：

1. 定义多套 Color 类：ColorsGold、ColorsQing、ColorsInk
2. 通过@Provide注入当前主题
3. 子组件通过@Consume获取主题颜色
4. 用户偏好通过@ohos.data.preferences持久化

9.3 设计令牌如何与设计师协作？

建议将Colors.ets与设计稿的「设计系统」色板保持同步，在项目初期建立色板映射表：

总结

本篇以玄象项目的Colors.ets与Styles.ets为蓝本，深入剖析了"设计令牌"体系在 ArkTS 中的实现方式。从三层抽象架构、命名规范、类型化样式对象，到一致性保证、可维护性提升、主题切换可行性，再到字体 / 动画 / Z-index 令牌的扩展方向，本篇为您展示了在 HarmonyOS 应用中构建工业级样式管理体系的完整路径。

下一篇：《05 · Navigation 容器与 @Entry 路由根的搭建》，将带您进入玄象项目 ArkUI 实战的核心，从路由根Index.ets开始搭建。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

• HarmonyOS 官方文档：ArkTS 常量与枚举
• HarmonyOS 官方文档：ShadowStyle 类型
• HarmonyOS 官方文档：LinearGradient 类型
• 开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
• 设计令牌规范：W3C Design Tokens Format Module