企业官网建设流程全解析

前言

HarmonyOS 应用启动图标采用「分层设计」，由前景（foreground）+ 背景（background）+ 配置（layered_image.json）三部分组成。这种设计让一个图标可以适配多种形状的桌面蒙版（圆形、方形、圆角矩形）。本篇以小分享 App 的 layered_image 配置为例，讲解启动图标的分层设计。详细规范可参考 HarmonyOS 启动图标官方文档。

一、layered_image 配置文件

1.1 layered_image.json 全文

小分享 App 的resources/base/media/layered_image.json如下：

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

1.2 字段说明

字段说明如下：

1.3 配置位置

配置位置如下：

• 配置文件：entry/src/main/resources/base/media/layered_image.json
• 背景图片：entry/src/main/resources/base/media/background.png
• 前景图片：entry/src/main/resources/base/media/foreground.png

提示：分层图标的资源文件名必须与 JSON 配置一致，否则会找不到资源。

二、在 module.json5 中引用

2.1 引用方式

小分享 App 在module.json5中通过$media:layered_image引用：

{ "abilities": [ { "name": "EntryAbility", "icon": "$media:layered_image", "label": "$string:EntryAbility_label", "startWindowIcon": "$media:startIcon", "startWindowBackground": "$color:start_window_background" } ] }

2.2 icon vs startWindowIcon

icon和startWindowIcon的区别如下：

2.3 startWindowBackground

startWindowBackground是启动时的背景色：

"startWindowBackground": "$color:start_window_background"

引用resources/base/element/color.json中的start_window_background键：

{ "color": [ { "name": "start_window_background", "value": "#FFFFFF" } ] }

三、分层图标的尺寸规范

3.1 标准尺寸

HarmonyOS 分层图标的尺寸规范如下：

3.2 安全区域

前景图必须在 216 × 216 的安全区域内，超出部分会被系统蒙版裁剪。

3.3 设计要点

设计要点如下：

1. 背景层：纯色或简单图案，避免复杂细节
2. 前景层：放置应用 Logo 或核心元素
3. 安全区：前景图保留 25% 边距，避免被裁剪

提示：使用 SVG 或矢量格式可以保证在不同分辨率下的清晰度。

四、layered_image 与 Adaptive Icon 的关系

4.1 设计哲学

HarmonyOS 的分层图标设计借鉴了 Android Adaptive Icon 的理念：

• 前景层：可被系统蒙版裁剪的元素
• 背景层：稳定的背景色或图案

4.2 跨平台一致性

跨平台一致性如下：

• iOS：使用单层 PNG 图标，不支持蒙版
• Android：Adaptive Icon，支持前景+背景两层
• HarmonyOS：layered-image，支持前景+背景两层

提示：跨平台设计建议先做 HarmonyOS / Android 的分层图标，再为 iOS 单独出图。

五、分层图标的资源适配

5.1 多分辨率适配

HarmonyOS 通过资源目录的密度限定词来适配不同分辨率：

resources/ base/ # 默认（mdpi） media/ background.png foreground.png phone/ # 手机专用 media/ background.png foreground.png

5.2 深浅色适配

深浅色模式下的图标资源适配：

resources/ base/ media/ background.png # 浅色背景 foreground.png dark/ media/ background.png # 深色背景 foreground.png

5.3 实战建议

实战建议如下：

1. 默认资源放base/
2. 高分辨率图放phone/
3. 深色图标放dark/

六、layered_image.json 的扩展配置

6.1 完整配置示例

除了基础的前景+背景，layered_image.json 还支持更多扩展：

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

6.2 字段说明

扩展字段说明如下：

6.3 使用场景

使用场景如下：

• 简单纯色背景图标（无需 PNG）
• 快速原型设计

七、本篇核心知识点

7.1 分层图标核心要素

分层图标核心要素总结如下：

1. layered_image.json：配置文件
2. background.png：背景层
3. foreground.png：前景层
4. $media:layered_image：在 module.json5 中引用

7.2 实战开发要点

实战开发中需要重点关注以下几个要点：

• 前景图必须在 216 × 216 安全区域内
• 背景图推荐 324 × 324
• 深浅色图标分别放在base/和dark/
• 配置文件名必须与 JSON 引用一致

总结

本文详细讲解了 HarmonyOS layered_image.json 启动图标的分层设计，结合小分享 App 的实际配置讲解了 JSON 配置、资源引用、尺寸规范、深浅色适配等核心知识点。下一篇我们将看 ArkTS 接口定义最佳实践——interfaces.ets 公共类型。

附录：完整实现细节

1. 核心 API 参考

2. 完整代码示例

// 核心功能代码 // 详见正文中的完整实现

3. 常见问题排查

4. 最佳实践

1. 错误处理完善，使用 try/catch 包裹
2. 资源及时释放，避免内存泄漏
3. 异步操作使用 async/await
4. 权限配置完整，按需申请

5. 完整代码文件索引

6. 实现要点总结

核心实现要点：

1. API 的正确使用方法和参数说明
2. 完整的代码实现流程
3. 常见问题的排查方案
4. 性能优化和安全建议

7. 总结

本文详细讲解了小分享 App 中对应功能的完整实现。通过本文的学习，读者可以掌握 HarmonyOS 开发的核心 API 使用方法和最佳实践。

开发注意事项

1. API 版本兼容性

确保使用的 API 在目标 SDK 版本中可用。不同版本的 HarmonyOS 可能对 API 的支持有所不同，建议查阅官方文档确认。

2. 权限配置

根据功能需求配置相应的系统权限。权限在 module.json5 中声明，运行时通过 abilityAccessCtrl 申请。

3. 错误处理

所有异步操作使用 try/catch 包裹，确保异常不会导致应用崩溃。错误信息通过 hilog 输出，便于调试。

4. 资源释放

使用完毕后及时释放系统资源，避免内存泄漏。例如：文件操作后关闭文件句柄，数据库操作后关闭 ResultSet。

5. 性能优化

避免在主线程执行耗时操作，使用异步 API 处理耗时任务。大量数据渲染时使用 LazyForEach 懒加载。

完整代码文件索引

核心 API 参考

总结

本文详细讲解了小分享 App 中对应功能的完整实现，涵盖 API 使用、代码示例、常见问题、性能优化等核心知识点。通过本文的学习，读者可以掌握 HarmonyOS 开发的完整流程。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！