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

# 鸿蒙(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)