前言深浅色模式Dark Mode已经成为现代移动应用的标配。HarmonyOS 提供了完善的ColorMode机制让应用可以跟随系统主题或由用户手动切换。本篇以小分享 App 的EntryAbility为例讲解深浅色模式的设置与切换。详细 API 可参考 HarmonyOS Configuration 官方文档。一、小分享 App 的 ColorMode 设置1.1 EntryAbility.ets 中的实现小分享 App 在EntryAbility.ets的onCreate中设置了颜色模式import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from kit.AbilityKit; import { hilog } from kit.PerformanceAnalysisKit; const DOMAIN 0x0000; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { try { this.context.getApplicationContext().setColorMode( ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET ); } catch (err) { hilog.error(DOMAIN, testTag, Failed to set colorMode: %{public}s, JSON.stringify(err)); } hilog.info(DOMAIN, testTag, %{public}s, Ability onCreate); } }1.2 关键 API 解析关键 API 解析如下this.contextUIAbilityContext提供 Ability 级 APIgetApplicationContext()获取应用级 ContextsetColorMode(mode)设置颜色模式ConfigurationConstant.ColorMode颜色模式枚举提示setColorMode必须在onCreate中调用否则可能不生效。二、ColorMode 三种取值2.1 取值对比ConfigurationConstant.ColorMode的三个取值如下取值含义适用场景COLOR_MODE_NOT_SET未设置跟随系统默认推荐COLOR_MODE_DARK强制深色用户手动切换深色COLOR_MODE_LIGHT强制浅色用户手动切换浅色2.2 选型建议选型建议如下默认应用COLOR_MODE_NOT_SET跟随系统提供「深色/浅色/跟随系统」三选项的设置页切换时调用setColorMode即可实时生效三、ConfigurationConstant 完整枚举3.1 完整代码示例完整的 ColorMode 枚举如下enum ColorMode { COLOR_MODE_NOT_SET -1, COLOR_MODE_DARK 0, COLOR_MODE_LIGHT 1 }3.2 取值说明取值说明如下COLOR_MODE_NOT_SET -1未设置默认跟随系统COLOR_MODE_DARK 0深色模式COLOR_MODE_LIGHT 1浅色模式提示枚举值是负数和零正数不要直接用数字硬编码。四、获取当前 ColorMode4.1 获取当前颜色模式通过getColorMode可以获取当前的颜色模式const currentMode this.context.getApplicationContext().getColorMode(); hilog.info(DOMAIN, testTag, Current color mode: %{public}d, currentMode);4.2 实战场景实战场景如下应用启动时读取用户偏好的颜色模式设置页展示当前模式并允许切换切换后保存到 Preferences下次启动恢复五、监听系统颜色模式变化5.1 注册监听如果使用COLOR_MODE_NOT_SET当用户在系统设置中切换深色模式时应用会自动响应。但如果需要做一些自定义处理可以注册监听onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { this.context.getApplicationContext().on(systemEnvironmentChanged, (config) { const colorMode config.colorMode; hilog.info(DOMAIN, testTag, System color mode changed: %{public}d, colorMode); // 在这里做一些自定义处理 }); }5.2 取消监听在onDestroy中取消监听避免内存泄漏onDestroy(): void { this.context.getApplicationContext().off(systemEnvironmentChanged); }提示注册和取消监听必须成对出现否则会导致内存泄漏。六、深浅色资源适配6.1 资源目录结构HarmonyOS 通过资源目录的命名约定来支持深浅色模式resources/ base/ # 默认资源 element/ color.json dark/ # 深色模式资源 element/ color.json light/ # 浅色模式资源可选 element/ color.json6.2 color.json 配置示例base/element/color.json默认{ color: [ { name: bg_color, value: #FFFFFF }, { name: text_color, value: #1A1A1A } ] }dark/element/color.json深色模式{ color: [ { name: bg_color, value: #1A1A1A }, { name: text_color, value: #FFFFFF } ] }6.3 在代码中引用在 ArkUI 代码中通过$r(app.color.bg_color)引用系统会根据当前 ColorMode 自动选择Column() .backgroundColor($r(app.color.bg_color)) Text(Hello HarmonyOS) .fontColor($r(app.color.text_color))七、本篇核心知识点7.1 ColorMode 核心 APIColorMode 核心 API 总结如下setColorMode(mode)设置颜色模式getColorMode()获取当前颜色模式on(systemEnvironmentChanged, cb)监听系统颜色变化off(systemEnvironmentChanged)取消监听7.2 实战开发要点实战开发中需要重点关注以下几个要点默认使用COLOR_MODE_NOT_SET跟随系统提供「深色/浅色/跟随系统」三选项深浅色资源分别放在base/和dark/目录通过$r(app.color.xxx)引用资源总结本文详细讲解了 HarmonyOS ColorMode 深浅色模式的设置与切换结合小分享 App 的EntryAbility实现演示了setColorMode、getColorMode、监听系统变化、资源适配等核心知识点。下一篇我们将看 layered_image.json 启动图标分层设计。附录完整实现细节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 开发的完整流程。app.json5 全局配置layered_image.json 启动图标如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力