鸿蒙应用图标实战：分层图标、安全区与那些踩过的坑

把一张设计好的 3D 工具箱 logo 换成鸿蒙 App 图标，本以为是「拖个图替换」的活，结果踩了一串坑。这篇把鸿蒙图标的结构、安全区取舍、以及 AppScope/entry 的区别讲清楚。

一、鸿蒙图标是「分层图标」，不是一张方图

鸿蒙的自适应图标由 app.json5 引用：

// AppScope/app.json5
"icon": "$media:layered_image",

layered_image.json 把图标拆成前景层 + 背景层：

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

foreground.png：主体（应透明背景，让背景层透出来）
background.png：纯色/渐变底

启动器会对这两层套蒙版（圆形 / 圆角方形 / squircle，随主题变化）并合成。理解这点是后面所有决策的基础。

二、第一个坑：前景里「藏」了一层奶白面板

打开项目原有的 foreground.png 一量，发现它不是干净的主体透明图，而是 「奶白圆角面板(占 80%) + 里面更小的工具箱」。也就是说：

背景层是纯白；
前景层自带一块奶白面板，工具箱缩在面板中央。

结果就是图标里工具箱又小、留白又大。正确做法应该是：

foreground.png = 工具箱主体抠成透明；
background.png = 奶白纯色铺满。

这样背景色由背景层负责铺满整个蒙版形状，前景只放主体，主体就能做大。

三、安全区：太保守反而「显小」

鸿蒙/安卓常见的「内容控制在中心 62.5% 安全区」建议，是为了在圆形蒙版下不被裁。我第一版老实按 ~68% 做，真机一看——更小了。

原因：启动器蒙版本身只显示画布中央一块，再叠加我留的 68%，两层缩放叠起来主体就很小。

关键反转点：既然背景层会铺满整个蒙版形状，前景的工具箱 bbox 四角又本来就是透明的（工具箱是圆乎乎的形状），就可以大胆放大到 ~86%，圆角方形蒙版完全裁不到主体。

fill = 0.86                       # 主体最大边占画布比例（从 0.68 提到 0.86）
target = int(SZ * fill)
scale = target / max(sub_w, sub_h)

放大前先用蒙版预览验证不裁切，比反复编译装机快得多：

mask = Image.new('L', (SZ, SZ), 0)
ImageDraw.Draw(mask).rounded_rectangle([0, 0, SZ-1, SZ-1], radius=int(SZ*0.23), fill=255)
out = Image.new('RGBA', (SZ, SZ), (0,0,0,0))
out.paste(composite, (0, 0), mask)   # 看主体是否被圆角裁到

经验：安全区不是「越保守越好」。背景层铺满 + 主体形状圆润时，前景可以做得比 62.5% 大很多。先用蒙版图预览，别靠装机试。

四、第二个坑：桌面图标是 AppScope，不是 entry

需求方说「放到 entry/src/main/resources/base/media/」，我照做了，但桌面/启动器显示的 App 图标其实由 AppScope 驱动：

AppScope/app.json5 → $media:layered_image → 读 AppScope/resources/base/media/ ← 桌面 App 图标
entry/.../module.json5 → $media:layered_image → 读 entry 的 media ← EntryAbility 图标（任务卡片等）

两套是独立资源，要效果一致就两边都得更新。只改 entry，桌面图标纹丝不动。

五、顺手发现的两个隐患

AppScope 缺 background.png：它的 layered_image.json 引用了 $media:background，但目录里只有 foreground.png，背景资源缺失。补上一份纯色背景即可。
拼写错误的 forground.png（少个 e）：源码无任何引用，只在 build 缓存里残留，属无用文件，清掉。

六、图标改了不刷新？卸载重装

鸿蒙启动器对图标缓存很顽固，覆盖安装经常不刷新。改完图标的正确验证姿势：

DevEco Studio：Build → Clean Project
先卸载设备/模拟器上的旧 App（关键）
重新编译安装

小结

鸿蒙图标是 foreground + background 分层，别当一张方图替换。
前景放主体透明、背景放纯色，主体才能做大。
安全区按蒙版预览来定，背景铺满时可大到 ~86%。
桌面图标看 AppScope，ability 图标看 entry，两套都要改。
改完图标卸载重装，绕过启动器缓存。

目录CONTENT

鸿蒙应用图标实战-分层图标与安全区