深色模式适配踩坑记：从界面错乱到完美切换的3步逆袭

摘要：本文分享了鸿蒙应用深色模式适配的实战经验。作者通过实习生遇到的界面错乱案例，系统讲解了深色模式适配的核心原理（资源目录自动切换）和三个关键步骤：颜色资源适配（需在base/dark目录分别定义）、媒体资源适配（图片/图标优化）和状态栏交互元素适配。文章提供了详细的代码示例，包括颜色配置文件、模式切换实现逻辑和设置页面组件代码，并针对常见问题给出解决方案。适配深色模式不仅能提升用户体验，还能

m0_37663100

608人浏览 · 2026-02-04 16:38:20

m0_37663100 · 2026-02-04 16:38:20 发布

深色模式适配踩坑记：从界面错乱到完美切换的3步逆袭

作者自我介绍

大家好啊～我是那个在代码海洋里扑腾了10+年的老水手，目前主业是"鸿蒙应用开发+Web全栈开发"双面间谍。
这些年写过的BUG能绕地球半圈，填过的坑能养活一个施工队，当然也攒了点有用的经验（毕竟吃一堑长一智嘛）。
平时最大的爱好就是把复杂的技术掰碎了、嚼烂了，做成普通人也能看懂的小甜点分享给大家。
如果你也喜欢折腾代码、踩坑、填坑，或者想找个人唠唠技术嗑，欢迎关注我一起交流～毕竟，独乐乐不如众乐乐，一起进步才是正经事！

引言：从一个深夜Bug说起

上周三凌晨两点，我正抱着手机刷剧，突然收到实习生的紧急消息：“哥，我做的应用在深色模式下炸了！”

打开截图一看，我差点笑出声——应用切换到深色模式后，状态栏变成了黑色，弹窗背景还是白色，文字颜色没跟上，整个界面活像被人用调色板乱涂了一遍。

"这不是典型的深色模式适配没做好吗？"我回复他。

其实，深色模式适配这件事，说难不难，说简单也不简单。它不是简单地把背景变黑、文字变白，而是一套完整的设计体系。今天，我就结合华为官方文档和实际项目经验，跟大家聊聊深色模式适配的那些事儿。

一、深色模式适配的核心原理

1. 为什么需要适配深色模式？

深色模式（Dark Mode）不是简单的"背景变黑"，而是：

减少屏幕亮度对眼睛的刺激，缓解视觉疲劳
在OLED屏幕上降低功耗，提升续航
提供更现代、更专业的视觉体验

2. 实现原理：资源目录自动切换

鸿蒙系统的深色模式适配，核心在于资源目录。当系统切换到深色模式后，应用会自动加载对应资源目录下的资源文件。

浅色模式资源：src/main/resources/base/
深色模式资源：src/main/resources/dark/

注意：在进行资源定义时，需要在base目录与dark目录中定义同名的资源。例如在base/element/color.json中定义text_color为黑色，在dark/element/color.json中定义text_color为白色。

二、深色模式适配的3个核心步骤

步骤1：颜色资源适配

颜色资源是深色模式适配的基础，包括：

字体颜色
背景颜色
元素边框颜色
交互反馈颜色

实践案例：颜色配置文件

浅色模式颜色配置（base/element/color.json）：

{
  "color": [
    {
      "name": "app_background_color",
      "value": "#F1F3F5"
    },
    {
      "name": "font_color",
      "value": "#E6000000"
    },
    {
      "name": "item_box",
      "value": "#FFFFFF"
    },
    // 其他颜色定义...
  ]
}

深色模式颜色配置（dark/element/color.json）：

{
  "color": [
    {
      "name": "app_background_color",
      "value": "#000000"
    },
    {
      "name": "font_color",
      "value": "#E6FFFFFF"
    },
    {
      "name": "item_box",
      "value": "#1A1A1A"
    },
    // 其他颜色定义...
  ]
}

步骤2：媒体资源适配

媒体资源包括图片、图标等，需要考虑：

SVG图标：使用fillColor()属性适配
图片：提供深色模式下的替代图片
图标：确保在深色背景下清晰可见

实践案例：资源目录结构

resources/
├── base/
│   ├── media/
│   │   ├── app_icon.png
│   │   ├── background.png
│   ├── element/
│   │   ├── color.json
├── dark/
│   ├── media/
│   │   ├── app_icon.png  // 深色模式下的图标
│   │   ├── background.png  // 深色模式下的背景
│   ├── element/
│   │   ├── color.json  // 深色模式下的颜色定义

步骤3：状态栏与交互元素适配

状态栏：根据当前模式动态调整背景色和文字颜色
系统控件：确保系统弹窗、对话框等在深色模式下正常显示
自定义组件：检查所有自定义组件在深色模式下的表现

三、深色模式切换的实现

1. 跟随系统模式

当应用跟随系统深色模式时，只需设置：

import { common, ConfigurationConstant } from "@kit.AbilityKit";

export const setAutoColorMode = (context: common.UIAbilityContext) => {
  context.getApplicationContext().setColorMode(
    ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET
  );
};

2. 手动控制模式

提供用户手动切换深色/浅色模式的选项：

// 切换到深色模式
export const setDarkColorMode = (context: common.UIAbilityContext) => {
  context.getApplicationContext().setColorMode(
    ConfigurationConstant.ColorMode.COLOR_MODE_DARK
  );
};

// 切换到浅色模式
export const setLightColorMode = (context: common.UIAbilityContext) => {
  context.getApplicationContext().setColorMode(
    ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT
  );
};

3. 实践案例：深色模式设置页面

import { common } from '@kit.AbilityKit';
import { setDarkColorMode, setLightColorMode, setAutoColorMode } from '../viewmodel/ColorModeChangeFunctions';

@Component
export struct DarkModeSetting {
  @StorageProp('enableDarkMode') enableDarkMode: boolean = false;
  @StorageProp('isFollowSystemSetting') isFollowSystemSetting: boolean = true;
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;

  build() {
    NavDestination() {
      Column() {
        // 跟随系统设置
        Row() {
          Text($r('app.string.follow_system_settings'))
            .fontColor($r('app.color.font_color'))
            .fontSize(16)
          Toggle({ type: ToggleType.Switch, isOn: this.isFollowSystemSetting })
            .onChange((isOn: boolean) => {
              if (isOn) {
                this.isFollowSystemSetting = true;
                this.enableDarkMode = false;
                setAutoColorMode(this.context);
              } else {
                this.isFollowSystemSetting = false;
                if (this.enableDarkMode) {
                  setDarkColorMode(this.context);
                } else {
                  setLightColorMode(this.context);
                }
              }
            })
        }

        // 手动切换深色模式
        Row() {
          Text($r('app.string.dark_mode'))
            .fontColor($r('app.color.font_color'))
            .fontSize(16)
          Toggle({ type: ToggleType.Switch, isOn: this.enableDarkMode })
            .onChange((isOn: boolean) => {
              this.enableDarkMode = isOn;
              if (isOn) {
                this.isFollowSystemSetting = false;
                setDarkColorMode(this.context);
              } else if (!this.isFollowSystemSetting) {
                setLightColorMode(this.context);
              }
            })
        }
      }
    }
  }
}