Open Harmony 高端精致：layered-image 分层图标资源配置实践 ✨

前言 🌟

应用图标是用户接触应用的第一个视觉元素。一个页面可以慢慢优化，但应用图标往往在安装、桌面展示、任务列表等场景中最先被看到。

当前 OpenHarmony 项目中使用了 layered-image 分层图标配置，这个点非常适合写成一篇“高端精致”方向的文章。

本文基于当前项目真实资源文件展开，不虚构复杂图标设计流程，只分析项目中已经存在的分层图标结构，以及这种资源组织方式的工程意义。

当前项目中的图标引用 📦

应用级配置位于：

AppScope/app.json5

其中图标字段是：

"icon": "$media:layered_image"

模块 Ability 中也引用了图标资源：

"icon": "$media:layered_image",
"startWindowIcon": "$media:startIcon"

这说明当前项目至少有两类图标相关资源：

1. 应用图标：layered_image
2. 启动窗口图标：startIcon

图标不是直接写死图片路径，而是通过 $media 资源引用。

layered_image.json 的结构 🎨

当前项目中存在分层图标配置：

{
  "layered-image": {
    "background": "$media:background",
    "foreground": "$media:foreground"
  }
}

这个配置表达得很清楚：图标由背景层和前景层组成。

项目中对应的资源包括：

1. background.png
2. foreground.png
3. layered_image.json

这种方式比单张图片更有结构感。背景和前景分开管理，可以让图标资源更清晰，也方便后续替换或调整。

分层资源的查找路径 🔍

当前项目里，分层图标不是孤立存在的。它至少涉及三个层次：

app.json5 / module.json5
  -> $media:layered_image
    -> layered_image.json
      -> background.png / foreground.png

当配置中写：

"icon": "$media:layered_image"

系统并不是直接去找一张叫 layered_image.png 的图片，而是根据资源名找到 layered_image.json，再根据里面的 background 和 foreground 继续找到具体图片资源。

这也是分层图标和普通图片引用不太一样的地方。它更像是一个图标描述文件，而不是一张最终图片。

为什么不要把图标写死成单张图片？📌

在小 demo 中，直接用一张图片当图标当然也能跑。但项目一旦希望做得更规范，分层资源会更适合维护。

比如后续只想替换前景标识，不想动背景，就可以保持 background.png 不变，只调整 foreground.png。如果要统一应用级图标和模块级图标，也可以比较两个 layered_image.json 的引用是否一致。

当前项目没有复杂品牌设计稿，所以本文不讨论图标视觉设计规范。但从工程组织角度看，背景、前景、启动图标分开，是一个很好的基础。

为什么分层图标更适合精致体验？✨

“高端精致”不是只靠页面大图和动画。图标、启动页、主题色、字号这些细节，同样会影响用户对应用质量的判断。

分层图标的优势在于：

1. 结构更清晰：背景和前景各自独立。
2. 资源更可维护：修改前景不一定影响背景。
3. 表达更灵活：可以根据设计需要调整层次。
4. 工程更规范：通过资源引用统一管理。

当前项目虽然还不是完整产品级图标方案，但已经使用了分层图标结构，这是一个不错的起点。

AppScope 和 entry 模块中的资源关系 🧩

当前项目中，AppScope/resources/base/media/layered_image.json 和 entry/src/main/resources/base/media/layered_image.json 都存在类似配置。

这说明项目在应用级和模块级都保留了图标资源。

可以这样理解：

1. AppScope 更偏应用全局资源。
2. entry 模块资源更贴近模块内部配置。
3. app.json5 和 module.json5 会分别引用相关资源。

对于新手来说，这里容易混淆。不是所有资源都写在一个目录下，OpenHarmony 项目会根据作用范围组织资源。

从当前项目看，应用级 app.json5 使用的是 AppScope 资源，而模块级 module.json5 更贴近 entry 下的资源。写文章时可以把这点讲清楚：同样叫 layered_image，也要注意它所在的资源范围。

startWindowIcon 与 layered-image 的区别 🚀

module.json5 中还有：

"startWindowIcon": "$media:startIcon"

这和应用图标配置不是同一个字段。

icon 更偏应用或 Ability 的图标展示，startWindowIcon 更偏启动窗口展示。当前项目已经配置了启动图标，这说明项目从启动体验层面也保留了基础配置。

不过需要注意，当前项目没有做复杂启动页动画，也没有自定义启动流程。这里只是使用了启动窗口图标配置。

图标资源命名的工程建议 ✅

基于当前项目，可以总结几个图标资源管理建议：

1. 图标资源命名要清晰，例如 foreground、background、startIcon。
2. 应用级图标和模块级图标不要随意混用。
3. 如果更换品牌图标，要同步检查 app.json5 和 module.json5。
4. 分层图标配置要保证前景、背景资源都存在。
5. 图标不是页面 UI，但属于用户体验的一部分。

当前项目在资源命名上还比较基础，后续如果正式化，可以把资源命名调整得更贴合品牌。

排查图标不生效时看哪里？🔧

如果后续替换图标后发现效果没有变化，可以按下面顺序排查：

1. app.json5 中是否仍然引用 $media:layered_image。
2. module.json5 中 Ability 图标是否引用了正确资源。
3. layered_image.json 中的 background 和 foreground 是否写对。
4. 对应的 PNG 资源是否真的存在于 media 目录。
5. 是否只改了 AppScope，但实际展示使用的是 entry 模块资源。

这类问题很常见，因为资源名、资源目录和配置引用之间隔了几层。理解这条链路后，排查就不会只盯着某一张图片。

和高端精致主题的关系 🌈

这篇文章对应 高端精致 方向。

原因很直接：应用图标是视觉体验的入口。一个应用如果页面做得很好，但图标粗糙、启动图标不统一，整体观感仍然会打折扣。

当前项目用 layered-image 组织图标资源，说明它已经具备继续做视觉规范的基础。后续如果配合统一色彩、启动页背景、页面资源 token，就能逐步形成更完整的视觉系统。

总结 ✨

当前项目真实存在以下图标相关配置：

1. app.json5 中的 $media:layered_image。
2. module.json5 中的 $media:layered_image。
3. module.json5 中的 $media:startIcon。
4. layered_image.json 中的 background 和 foreground。
5. 对应的 PNG 图标资源。

分层图标不是复杂功能，但它是应用精致感的一部分。OpenHarmony 项目想要做得更像正式产品，就不能只关注页面，也要关注图标、启动窗口和资源组织这些容易被忽略的细节。