HarmonyOS 鸿蒙Next的深色模式该如何适配？

【问题背景】：HarmonyOS的深色模式该如何适配？

【解决思路】：

1. 应用跟随系统的深浅色模式：应用颜色 / 资源随系统模式自动切换；
2. 应用主动设置深浅色模式：应用固定某一模式，不随系统变化。

一、应用跟随系统深浅色模式

需从颜色、图片、组件、监听等维度实现适配，核心是通过 “资源配置” 或 “系统资源调用” 实现自动切换。

1. 颜色适配（两种实现方式）

2. 图片资源适配

• 普通图片：在dark/media目录放与基础目录同名的深色图片，通过$r('app.media.xxx')加载，系统自动切换；
• SVG 图标：无需两套图片，通过fillColor绑定系统资源实现颜色切换，示例：
  Image($r('app.media.pic_svg')).width(50).fillColor($r('sys.color.ohos_id_color_text_primary'))。

3. 特殊组件适配

• Web 组件：需单独配置前端页面深色模式，参考 “Web 组件深色模式” 文档；
• 自定义节点（BuilderNode/ComponentContent）：需手动传递系统环境变化事件，通过updateConfiguration()触发全量更新，需在FrameCallback的onFrame()中调用更新逻辑。

4. 监听系统模式切换事件

无论是否跟随系统，该监听均生效，用于自定义资源初始化逻辑，分 4 步：

1. 在AbilityStage.onCreate()中，将当前颜色模式存入AppStorage：
   AppStorage.setOrCreate('currentColorMode', this.context.config.colorMode)；
2. 在AbilityStage.onConfigurationUpdate()中，刷新AppStorage的模式值；
3. 在 Page 中用@StorageProp + @Watch监听模式变化：
   @StorageProp('currentColorMode') @Watch('onColorModeChange') currentMode: number = ...；
4. 在aboutToAppear()（初始化）和onColorModeChange()（切换时）中执行适配逻辑。

5. 局部深浅色适配

通过WithTheme组件设置局部模式（跟随系统 / 浅色 / 深色），作用范围内的组件样式将按指定模式读取资源，详情参考 “设置应用页面局部深浅色” 文档。

三、应用主动设置深浅色模式

应用默认跟随系统，若需固定模式，通过setColorMode接口实现：

1. 固定为浅色模式（未适配深色时推荐，避免显示异常）：

onCreate(): void {
  this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT);
}

1. 重置为跟随系统（全系统组件开发时，需显式设置以保证切换）：
   this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET)。

四、系统判定应用深浅色模式的规则

1. 优先级 1：应用主动调用setColorMode，则以接口设置为准；
2. 优先级 2：未主动设置时：
   • 若工程有dark目录及深色资源，系统组件自动切深色；
   • 若无dark目录资源，系统组件保持浅色。

五、使用建议与注意事项

1. 推荐方法

• 跟随系统时，用AbilityStage或Ability的监听回调，绑定状态变量执行业务逻辑，确保模式切换时逻辑生效。

2. 不推荐方法

• 避免在属性设置中通过函数判断模式（如getResource()返回色值），因热更新场景下，属性代码可能不重新执行，导致适配失效，示例：

// 不推荐：依赖属性重新执行，可靠性低
getResource(): string { return colorMode === "dark" ? "#000000" : "#FFFFFF"; }
Button.backgroundColor(this.getResource())

六、优化深浅色模式切换开销（API 20+）

默认切换需全量重绘，性能随 UI 复杂度上升，可通过metadata配置开启高性能切换：

1. 在module.json5中新增配置：

"metadata": [
  { "name": "configColorModeChangePerformanceInArkUI", "value": "true" }
]

1. 注意：开启前需确保所有 “函数适配深浅色” 的逻辑已整改（避免逻辑失效）。

七、反色能力快速适配（API 20+）

适用于存量代码多、需快速适配深色的场景，基于 “优化切换开销” 开启，通过反色算法自动调整颜色，无需大量资源配置：

1. 核心接口：OH_ArkUI_SetForceDarkConfig，支持系统默认反色 / 自定义反色算法，仅对 “非资源值设置的颜色属性” 生效（资源配置优先）；
2. 调用要求：
   • 需先加载OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_NODE, "ArkUI_NativeNodeAPI_1")；
   • 在 UI 线程、节点创建前调用；
   • 仅进程级生效，不支持部分组件单独启用 / 禁用（如全局禁用则所有组件禁用）；
3. 生效优先级：开发者深色资源 > 控件级反色算法 > 全局反色算法；
4. 不支持场景：DatePickerDialog/TimePickerDialog等无实体节点的组件、CAPI 创建的节点。

【官方文档示例详解】