# 鸿蒙(HarmonyOS) 分层图标配置指南 > **适用场景**: 华为应用审核要求配置分层图标（前景图 + 后景图），标准尺寸 1024×1024px > **更新时间**: 2026-04-25 > **关联脚本**: [gen_hmos_icons.py](../scripts/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"` 键** ```json { "layered-image": { "foreground": "$media:foreground_icon", "background": "$media:background_icon" } } ``` **常见错误格式**（❌ 不识别）： ```json // ❌ 缺少外层键 — 系统无法解析 { "foreground": "$media:foreground_icon", "background": "$media:background_icon" } // ❌ 多余字段 — 不符合规范 { "foreground": "...", "background": "...", "size": { "width": 1024, "height": 1024 } } ``` --- ## 四、配置引用 ### 4.1 app.json5（全局应用图标） ```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 图标） ```json5 // 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](../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 运行方式 ```bash # 前置依赖 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 参数调整 如需自定义，修改脚本顶部常量： ```python 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 --- ## 九、参考链接 - [华为官方：配置应用图标和名称](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/layered-image) - [OpenHarmony 文档：分层图标](https://github.com/openharmony/docs/blob/master/zh-cn/application-dev/quick-start/layered-image.md) - [华为开发者社区：分层图标 FAQ](https://developer.huawei.com/consumer/cn/forum/topic/0203201129389706916)