Unicode 图标为什么适合原型、不适合长期数据项目早期为了快速验证功能曾经用 Unicode 字符表示图标☀ ☾ ✓ ♥ ♫优点很明显不需要准备图片资源Text 组件就能显示写几个字符即可覆盖原型。但进入正式版本后问题也会出现不同字体的字形差异很大某些字符在不同设备上基线不一致字符可能被渲染为彩色 Emoji图标粗细无法和系统风格统一持久化后很难知道“这个字符的业务含义是什么”更换图标体系时需要迁移旧数据。因此 HarmonyOS 版本最终使用SymbolGlyph和稳定语义 Key。一、磁盘里保存语义不保存 Resource 对象习惯模型中的图标字段是字符串exportinterfaceHabit{id:string;name:string;icon:string;color:string;// 其他字段}但这里的字符串不再是“☾”而是moon_z figure_run book drop checkmark_circle这些值是应用自己的语义协议。好处是不依赖某个具体系统资源对象能否 JSON 序列化业务数据可以跨版本保存将来替换成自定义图标时不必重写 Habit中英日切换不影响图标身份导出文件仍然可读。二、通过一层映射连接业务 Key 与系统 Symbol页面集中维护privateiconResource(icon:string):Resource{switch(normalizedIconKey(icon)){casesun_max:return$r(sys.symbol.sun_max);caseface_smiling:return$r(sys.symbol.face_smiling);casewater_waves:return$r(sys.symbol.water_waves);casemoon_z:return$r(sys.symbol.moon_z);casefigure_run:return$r(sys.symbol.figure_run);casebook:return$r(sys.symbol.book);default:return$r(sys.symbol.circle);}}这层映射看起来比直接在页面写$r()多了一步却带来清晰边界业务数据moon_z → 映射层sys.symbol.moon_z → UISymbolGlyph系统资源名变化或设计决定替换图标时只需调整映射层。三、封装统一的图标 Builder项目用一个 Builder 统一尺寸和颜色入口BuilderprivateAppIcon(icon:string,size:number,color:string){SymbolGlyph(this.iconResource(icon)).fontSize(size).fontColor([color])}圆形底图也进一步封装BuilderprivateIconBadge(icon:string,size:number,color:string,diameter:number,background:string){Stack({alignContent:Alignment.Center}){this.AppIcon(icon,size,color)}.width(diameter).height(diameter).backgroundColor(background).borderRadius(diameter/2)}这样心情、标签、习惯和设置页不会各自维护一套 Symbol 样式。四、旧 Unicode 数据必须在读取路径中兼容应用一旦发布磁盘数据就是需要长期兼容的协议。不能把编辑器中的 Unicode 替换成新 Key 后就假设旧用户数据自动变化。项目提供归一化函数exportfunctionnormalizedIconKey(icon:string):string{switch(icon){case☀:returnsun_max;case≈:returnwater_waves;case☾:returnmoon_z;case▣:returnbriefcase;case↗:returnfigure_run;case◇:returndrop;case▤:returnbook;case✓:returncheckmark_circle;case♥:returnheart;case♫:case♬:returnmusic;default:returnicon;}}显示图标和打开习惯编辑器时都先归一化this.habitIconDraftnormalizedIconKey(habit?.icon??HABIT_ICONS[0]);这样旧数据仍能显示用户下次保存习惯时会自然迁移到新的语义 Key。五、懒迁移和一次性迁移怎么选当前项目使用“读取兼容、编辑时迁移”的懒迁移。适合旧格式数量很少映射完全确定不迁移也不影响显示数据规模小。另一种方式是在 Repository 加载后一次性改写parsed.habitsparsed.habits.map((habit)({...habit,icon:normalizedIconKey(habit.icon)}));然后保存新版本。一次性迁移适合后续代码不希望长期携带兼容分支新旧格式混用会造成错误迁移结果可验证失败时有回滚策略。无论选择哪种都不应该直接把未知值清空。六、未知图标需要稳定回退导入文件、测试版本或未来资源变化可能带来未知 Key。映射层默认返回return$r(sys.symbol.circle);回退图标的目标不是“看起来完美”而是保证页面不会因为单个坏值崩溃用户仍能打开编辑器并重新选择导出和其他数据不受影响问题可以通过日志或测试定位。七、图标颜色也应该是数据的一部分吗当前习惯保存color:#5E7CE2这让用户选择的颜色能够持久化但也意味着设计系统调整时旧数据仍保留旧色值。可以有两种模型保存实际色值适合允许用户自由选择颜色导出结果直观。保存语义色 Key例如habit-blue habit-mint habit-gold适合需要统一适配深色模式或未来更换主题的产品。当前项目色板固定且规模较小直接保存色值足够。如果后续增加深色模式和主题系统语义色 Key 会更易维护。八、Symbol 不能替代无障碍名称一个“锁”图标对开发者很直观但屏幕阅读器需要知道它代表“应用锁”还是“隐私政策”。因此可点击 Symbol 应与明确文本、控件标签或无障碍描述结合不能只依靠图形表达业务操作。尤其要避免多个只显示图标的按钮没有名称颜色是区分状态的唯一方式选中态只改变图标粗细删除和归档使用过于相似的图形。九、系统 Symbol 的测试清单所有配置 Key 都能映射到资源未知 Key 显示回退圆形旧 Unicode 数据能打开和编辑不同字号下图标没有截断选中和未选中颜色对比清楚中文、英文、日文下布局一致真机系统版本包含使用到的 Symbol重要操作有文字或无障碍名称导出再导入后语义 Key 不丢失。总结从 Unicode 字符迁移到 SymbolGlyph真正重要的不是“图标更好看”而是建立了一套稳定协议磁盘保存业务语义 Key映射层连接系统 SymbolBuilder 统一视觉样式旧数据通过归一化函数兼容未知值有安全回退图标仍需要无障碍语义。这套模式同样适用于系统图标、自定义 SVG 和图片资源之间的后续替换。本文案例来自“心晴手记MoodMemoir”HarmonyOS 版的心情、标签与习惯图标系统。参考资料HarmonyOS 图标小符号 SymbolGlyph/SymbolSpan