kitchen/packages/鸿蒙分层图标配置指南.md

鸿蒙(HarmonyOS) 分层图标配置指南

适用场景: 华为应用审核要求配置分层图标（前景图 + 后景图），标准尺寸 1024×1024px 更新时间: 2026-04-25 关联脚本: gen_hmos_icons.py

---

一、为什么需要分层图标？

华为应用上架审核会检查以下警告：

为了提供更好的应用启动体验，请使用分层图标。
应用未配置图标的前景图和后景图，标准要求尺寸1024px*1024px

原因: 鸿蒙系统支持"分层图标"机制，将图标拆分为前景层 + 背景层，系统可动态组合：

• 桌面主题切换时自动替换背景色
• 深色/浅色模式自适应
• 不同设备形态统一视觉

---

二、规范要求

2.1 图片规格

属性	前景图 (foreground)	背景图 (background)
尺寸	1024 × 1024 px	1024 × 1024 px
格式	PNG	PNG
透明度	✅ 支持（非核心区域透明）	❌ 禁止透明像素
圆角	❌ 不要手动加圆角	❌ 不要手动加圆角
内容	App 图标主体（Logo/图形）	纯色或简单渐变

2.2 设计要点

┌─────────────────────┐
│                     │  ← 四角：100% 透明（系统自动裁切圆角）
│   ┌───────────┐     │
│   │           │     │  ← 前景：保留核心图形
│   │  APP LOGO │     │
│   │           │     │
│   └───────────┘     │
│                     │
└─────────────────────┘

┌─────────────────────┐
│░░░░░░░░░░░░░░░░░░░░░│  ← 背景：纯色填充，无任何透明区域
│░░░░░░░░░░░░░░░░░░░░░│
│░░░░░░░░░░░░░░░░░░░░░│  （建议与前景主色调一致）
│░░░░░░░░░░░░░░░░░░░░░│
│░░░░░░░░░░░░░░░░░░░░░│
└─────────────────────┘

2.3 常见错误

错误	说明	正确做法
背景含透明像素	审核直接拒绝	导出为不透明纯色 PNG
手动加圆角	与系统裁切冲突	保持正方形，系统自动处理
尺寸不是 1024	不符合规范	必须精确 1024×1024
使用单层图标	触发警告	改用 foreground + background 双层

---

三、文件结构

3.1 需要的文件

ohos/
├── AppScope/
│   └── resources/
│       └── base/
│           └── media/
│               ├── background_icon.png      # 背景层（纯色）
│               ├── foreground_icon.png      # 前景层（透明PNG）
│               ├── layered_image.json       # ⭐ 分层配置文件
│               └── app_icon.png             # 单层备用图标（startWindowIcon 用）
│
└── entry/
    └── src/main/resources/base/media/
        ├── background_icon.png              # 同上（entry 目录副本）
        ├── foreground_icon.png              # 同上
        ├── layered_image.json               # 同上
        └── icon.png                         # 启动窗口图标（实际图片，非 JSON）

3.2 关键：layered_image.json 格式

⚠️ 这是最容易出错的地方！必须包含外层 "layered-image" 键

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

常见错误格式（❌ 不识别）：

// ❌ 缺少外层键 — 系统无法解析
{
  "foreground": "$media:foreground_icon",
  "background": "$media:background_icon"
}

// ❌ 多余字段 — 不符合规范
{
  "foreground": "...",
  "background": "...",
  "size": { "width": 1024, "height": 1024 }
}

---

四、配置引用

4.1 app.json5（全局应用图标）

// ohos/AppScope/app.json5
{
  "app": {
    "bundleName": "cute.major.kitchen",
    "vendor": "微风暴",
    "versionCode": 26042001,
    "versionName": "1.1.0",
    "icon": "$media:layered_image",          // ← 引用分层配置
    "label": "$string:app_name"
  }
}

4.2 module.json5（入口 Ability 图标）

// ohos/entry/src/main/module.json5
{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "icon": "$media:layered_image",       // ← 桌面图标：分层配置
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",     // ← 启动窗口：实际 PNG 图片！
        "startWindowBackground": "$color:start_window_background",
        "skills": [...]
      }
    ]
  }
}

4.3 字段区别（重要！）

字段	引用类型	说明
icon	$media:layered_image	桌面/应用列表图标 → JSON 配置
startWindowIcon	$media:icon	启动闪屏图标 → 实际 PNG 图片

⚠️ startWindowIcon 不能指向 layered_image.json，必须是真实图片文件！

---

五、Python 自动生成脚本

5.1 脚本位置

scripts/gen_hmos_icons.py

5.2 功能说明

从源图标 assets/icons/icon_1024x1024.png 自动提取：

1. 背景层 (background_icon.png) — 采样源图标四角颜色，生成纯色背景
2. 前景层 (foreground_icon.png) — 抠去背景色，保留图标主体，添加圆角遮罩
3. 配置文件 (layered_image.json) — 生成标准格式的分层配置

5.3 工作原理

源图标 icon_1024x1024.png
         │
         ▼
  ┌──────────────┐
  │ 采样背景颜色   │ → 从10个角落/边缘点取平均色
  └──────┬───────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌──────────┐
│背景层  │ │  前景层   │
│纯色填充│ │ 去背+圆角 │
│ 5KB   │ │ 1372KB   │
└───────┘ └──────────┘
    │         │
    └────┬────┘
         ▼
  layered_image.json
  (标准格式输出)

5.4 运行方式

# 前置依赖
pip install Pillow

# 运行脚本
python scripts/gen_hmos_icons.py

5.5 输出示例

源图标: assets/icons/icon_1024x1024.png
  尺寸: (1024, 1024)
  背景色采样: RGB(237, 189, 109)

--- AppScope/resources/base/media ---
  background: .../background_icon.png (5.2KB)
    颜色: RGB(237, 189, 109)
  foreground: .../foreground_icon.png (1371.8KB)
  layered_image.json: .../layered_image.json

--- entry/src/main/resources/base/media ---
  background: .../background_icon.png (5.2KB)
  foreground: .../foreground_icon.png (1371.8KB)
  layered_image.json: .../layered_image.json

完成!

5.6 参数调整

如需自定义，修改脚本顶部常量：

SOURCE_ICON = "assets/icons/icon_1024x1024.png"  # 源图标路径
OUTPUT_SIZE = 1024                                # 输出尺寸
# generate_foreground() 中:
#   tolerance=50    # 背景色容差（越小越严格抠图）
#   radius=int(OUTPUT_SIZE * 0.22)  # 圆角半径（0.22 ≈ 华为默认圆角比例）

---

六、手动制作流程（备选方案）

如果不想用脚本，可以手动在 Figma / Photoshop / Sketch 中操作：

步骤 1: 制作背景图

1. 新建 1024×1024 画布
2. 填充纯色（取自原图主色调）
3. 导出为 background_icon.png（确保无透明）

步骤 2: 制作前景图

1. 打开原图 1024×1024
2. 删除/隐藏背景图层，只保留图形主体
3. 不要加圆角
4. 导出为 foreground_icon.png（保留透明通道）

步骤 3: 配置 JSON

创建 layered_image.json（见第三章 3.2）

步骤 4: 放置文件

按第三章 3.1 结构放入对应目录

---

七、验证清单

部署前逐项检查：

• background_icon.png 存在于两个 media 目录
• foreground_icon.png 存在于两个 media 目录
• layered_image.json 格式正确（有 "layered-image" 外层键）
• app.json5 的 "icon" 指向 $media:layered_image
• module.json5 的 "icon" 指向 $media:layered_image
• module.json5 的 "startWindowIcon" 指向 $media:icon（实际图片）
• 两张图片均为 1024×1024 PNG
• 背景图不含任何透明像素
• 前景图没有手动圆角

---

八、常见问题排查

Q1: 配置后仍有警告？

检查优先级: module.json5 的 icon 会覆盖 app.json5。如果 module.json5 配了旧的单层图标引用，全局配置不会生效。

解决: 确保 module.json5 中 abilities 的 icon 也改为 $media:layered_image。

Q2: 启动时图标空白？

原因: startWindowIcon 指向了 layered_image.json（这是 JSON 不是图片）。

解决: startWindowIcon 必须指向实际 PNG 文件，如 $media:icon。

Q3: DevEco Studio 版本要求？

华为要求 DevEco Studio ≥ 5.0.5.315 进行图标处理。低版本升级后可能有残留配置，需清理后重新打包。

Q4: 图标显示模糊/有锯齿？

• 确保前景图透明区域是 100% 透明（alpha=0），不是半透明
• 使用标准 PNG 格式，避免非标准转换导致失真
• 源图分辨率至少 1024×1024

---

九、参考链接

• 华为官方：配置应用图标和名称
• OpenHarmony 文档：分层图标
• 华为开发者社区：分层图标 FAQ