阅读时长约 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 三层架构总览玄象项目的设计令牌体系分为三层层级文件职责引用方式原始令牌element/color.json颜色资源定义$r(app.color.xxx)语义令牌Colors.etsArkTS 语义化颜色常量Colors.PRIMARY_GOLD复合样式Styles.ets多属性复合样式封装Styles.GOLD_GRADIENT1.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 设计令牌的命名规范玄象项目的颜色命名遵循类别_语义模式便于阅读与查找类别命名示例语义说明主色PRIMARY_GOLD主品牌色金背景色BG_DARK/BG_CARD页面背景 / 卡片背景文字色TEXT_PRIMARY/TEXT_DIM主文字 / 暗淡文字五行色WOOD_GREEN/FIRE_RED木色 / 火色四象色DRAGON_CYAN/TIGER_WHITE青龙色 / 白虎色四季色SEASON_SPRING/SEASON_WINTER春色 / 冬色透明度GOLD_TRANSPARENT/CARD_OVERLAY半透明金 / 卡片蒙层2.3static readonly的意义玄象项目所有颜色常量使用static readonly修饰staticreadonlyPRIMARY_GOLD:string#D4A843;这种修饰方式带来三大好处静态访问无需实例化即可通过Colors.PRIMARY_GOLD访问减少对象创建开销。只读保证readonly在编译期阻止意外修改确保常量稳定。类型明确显式标注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:number1;staticreadonlyGOLD_CARD_RADIUS:number12;staticreadonlyGOLD_CARD_PADDING:number16;// 通用边距staticreadonlyPAGE_PADDING:number16;staticreadonlySECTION_SPACE:number20;staticreadonlyITEM_SPACE:number12;// 圆角staticreadonlyRADIUS_SMALL:number8;staticreadonlyRADIUS_MEDIUM:number12;staticreadonlyRADIUS_LARGE:number20;staticreadonlyRADIUS_FULL:number999;// 阴影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封装了玄象项目所有页面共用的样式常量数值常量边距、圆角、宽度等数值。复合样式对象阴影ShadowStyle、渐变LinearGradient等。颜色引用通过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类型字段字段类型说明radiusnumber阴影模糊半径colorstring阴影颜色可带透明度offsetXnumberX 轴偏移offsetYnumberY 轴偏移LinearGradient类型字段字段类型说明anglenumber渐变角度0-360colorsArray颜色断点数组colors[].colorstring断点颜色colors[].rationumber断点位置0-1提示玄象项目的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 主题切换可行性基于设计令牌体系玄象项目未来可通过以下方式实现主题切换定义多套 ColorsColorsGold、ColorsQing、ColorsInk等。运行时切换通过Provide注入当前主题子组件通过Consume获取。持久化用户偏好将主题选择保存到ohos.data.preferences下次启动自动应用。提示主题切换是中大型应用的必备能力。玄象项目的设计令牌体系已经为这一能力铺平了道路本系列第 94 篇会详细演示主题切换的完整实现。六、设计令牌的扩展方向6.1 字体令牌玄象项目当前在组件内联中硬编码字体大小未来可扩展为字体令牌exportclassTypography{staticreadonlyH1_SIZE:number56;staticreadonlyH2_SIZE:number28;staticreadonlyBODY_SIZE:number16;staticreadonlyCAPTION_SIZE:number12;staticreadonlyH1_WEIGHT:FontWeightFontWeight.Bold;staticreadonlyBODY_WEIGHT:FontWeightFontWeight.Normal;}6.2 动画令牌将动画时长与曲线封装为令牌exportclassMotion{staticreadonlyDURATION_FAST:number200;staticreadonlyDURATION_BASE:number300;staticreadonlyDURATION_SLOW:number500;staticreadonlyEASE_OUT:CurveCurve.EaseOut;staticreadonlyEASE_IN_OUT:CurveCurve.EaseInOut;}6.3 Z-index 令牌避免层级冲突定义统一的 z-index 令牌exportclassZIndex{staticreadonlyBASE:number0;staticreadonlyDROPDOWN:number100;staticreadonlyMODAL:number1000;staticreadonlyTOAST:number2000;}七、玄象项目设计令牌的不足与改进7.1 当前不足玄象项目的设计令牌体系仍有以下改进空间颜色与样式的关联较弱GOLD_CARD_BORDER_WIDTH与PRIMARY_GOLD未组成卡片样式包。缺乏响应式断点未定义不同屏幕尺寸下的间距 / 字号缩放规则。令牌文档缺失缺少令牌清单与使用规范文档。7.2 改进建议建议玄象项目后续引入以下改进样式包封装将相关样式属性打包为样式包例如CardStylePack包含边框、圆角、阴影、背景色。响应式令牌引入MediaQuery监听屏幕尺寸动态切换令牌值。令牌清单自动化通过脚本扫描Colors.ets与Styles.ets自动生成令牌清单 Markdown 文档。九、常见问题与解答9.1 Colors.ets 与 color.json 重复定义怎么办玄象项目当前Colors.ets与color.json存在重复定义。生产环境可通过脚本从color.json自动生成Colors.ets// build/scripts/generate-colors.js (示意)constcolorsrequire(./resources/base/element/color.json);constoutputexport class Colors {\n;colors.color.forEach(c{outputstatic readonly${c.name.toUpperCase()}: string ${c.value};\n;});output};// 写入 Colors.ets9.2 如何实现主题切换基于设计令牌体系可实现运行时主题切换定义多套 Color 类ColorsGold、ColorsQing、ColorsInk通过Provide注入当前主题子组件通过Consume获取主题颜色用户偏好通过ohos.data.preferences持久化9.3 设计令牌如何与设计师协作建议将Colors.ets与设计稿的「设计系统」色板保持同步在项目初期建立色板映射表设计稿色板Colors.ets 常量色值品牌色/金PRIMARY_GOLD#D4A843背景色/深色BG_DARK#0A0E17文字色/主TEXT_PRIMARY#FFFFFF总结本篇以玄象项目的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