前言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 字段说明字段说明如下字段作用资源示例background图标背景图background.pngforeground图标前景图foreground.png1.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 startWindowIconicon和startWindowIcon的区别如下字段用途显示时机icon桌面图标桌面长按显示startWindowIcon启动图标应用启动瞬间2.3 startWindowBackgroundstartWindowBackground是启动时的背景色startWindowBackground: $color:start_window_background引用resources/base/element/color.json中的start_window_background键{ color: [ { name: start_window_background, value: #FFFFFF } ] }三、分层图标的尺寸规范3.1 标准尺寸HarmonyOS 分层图标的尺寸规范如下资源推荐尺寸px用途background.png324 × 324图标背景层foreground.png216 × 216图标前景层startIcon.png288 × 288启动图单层3.2 安全区域前景图必须在 216 × 216 的安全区域内超出部分会被系统蒙版裁剪。3.3 设计要点设计要点如下背景层纯色或简单图案避免复杂细节前景层放置应用 Logo 或核心元素安全区前景图保留 25% 边距避免被裁剪提示使用 SVG 或矢量格式可以保证在不同分辨率下的清晰度。四、layered_image 与 Adaptive Icon 的关系4.1 设计哲学HarmonyOS 的分层图标设计借鉴了 Android Adaptive Icon 的理念前景层可被系统蒙版裁剪的元素背景层稳定的背景色或图案4.2 跨平台一致性跨平台一致性如下iOS使用单层 PNG 图标不支持蒙版AndroidAdaptive Icon支持前景背景两层HarmonyOSlayered-image支持前景背景两层提示跨平台设计建议先做 HarmonyOS / Android 的分层图标再为 iOS 单独出图。五、分层图标的资源适配5.1 多分辨率适配HarmonyOS 通过资源目录的密度限定词来适配不同分辨率resources/ base/ # 默认mdpi media/ background.png foreground.png phone/ # 手机专用 media/ background.png foreground.png5.2 深浅色适配深浅色模式下的图标资源适配resources/ base/ media/ background.png # 浅色背景 foreground.png dark/ media/ background.png # 深色背景 foreground.png5.3 实战建议实战建议如下默认资源放base/高分辨率图放phone/深色图标放dark/六、layered_image.json 的扩展配置6.1 完整配置示例除了基础的前景背景layered_image.json 还支持更多扩展{ layered-image: { background: $media:background, foreground: $media:foreground, background-color: #F5A623 } }6.2 字段说明扩展字段说明如下字段作用background-color纯色背景优先级低于 background6.3 使用场景使用场景如下简单纯色背景图标无需 PNG快速原型设计七、本篇核心知识点7.1 分层图标核心要素分层图标核心要素总结如下layered_image.json配置文件background.png背景层foreground.png前景层$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 参考API作用说明本文涉及的核心 API功能实现参见华为官方文档2. 完整代码示例// 核心功能代码 // 详见正文中的完整实现3. 常见问题排查问题原因解决方案编译错误import 路径错误检查路径和 API 版本运行时异常参数不合法使用 try/catch 捕获性能问题主线程耗时操作使用异步 API4. 最佳实践错误处理完善使用 try/catch 包裹资源及时释放避免内存泄漏异步操作使用 async/await权限配置完整按需申请5. 完整代码文件索引文件路径说明本文涉及的代码文件见正文6. 实现要点总结核心实现要点API 的正确使用方法和参数说明完整的代码实现流程常见问题的排查方案性能优化和安全建议7. 总结本文详细讲解了小分享 App 中对应功能的完整实现。通过本文的学习读者可以掌握 HarmonyOS 开发的核心 API 使用方法和最佳实践。开发注意事项1. API 版本兼容性确保使用的 API 在目标 SDK 版本中可用。不同版本的 HarmonyOS 可能对 API 的支持有所不同建议查阅官方文档确认。2. 权限配置根据功能需求配置相应的系统权限。权限在 module.json5 中声明运行时通过 abilityAccessCtrl 申请。3. 错误处理所有异步操作使用 try/catch 包裹确保异常不会导致应用崩溃。错误信息通过 hilog 输出便于调试。4. 资源释放使用完毕后及时释放系统资源避免内存泄漏。例如文件操作后关闭文件句柄数据库操作后关闭 ResultSet。5. 性能优化避免在主线程执行耗时操作使用异步 API 处理耗时任务。大量数据渲染时使用 LazyForEach 懒加载。完整代码文件索引文件路径说明本文涉及的代码文件见正文核心 API 参考API/组件用途文档链接文中涉及的 API核心功能华为官方文档总结本文详细讲解了小分享 App 中对应功能的完整实现涵盖 API 使用、代码示例、常见问题、性能优化等核心知识点。通过本文的学习读者可以掌握 HarmonyOS 开发的完整流程。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力