在这里插入图片描述

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的App!
📌 关注本专栏《零基础学鸿蒙开发》,一起变强!
每一节内容我都会持续更新,配图+代码+解释全都有,欢迎点个关注,不走丢,我是小白酷爱学习,我们一起上路 🚀

前言

很多开发者第一次做深色模式适配时,第一反应是给 ViewModel 加一个 isDark 状态变量,再在每个组件里判断一次,把颜色值硬编码进去。这样的做法可以跑通,但维护成本会随着页面数量增长。

HarmonyOS 提供了另一条路:把深浅色的颜色值分别放进两组资源目录,让 ArkUI 在运行时自动读取对应的那一份。代码里不需要感知当前是深色还是浅色,系统切换主题,界面颜色跟着变。

这篇文章就把这个机制从头捋一遍。

一、if/else 的问题在哪里

用状态变量控制颜色,最直接的写法大概是这样:

@State isDark: boolean = false

Text('标题')
  .fontColor(this.isDark ? '#FFFFFF' : '#1A1A1A')
  .backgroundColor(this.isDark ? '#2C2C2C' : '#F5F5F5')

问题不是这样写会报错,而是:

  • 每加一个颜色,都需要配对维护两个色值;
  • 页面变多以后,颜色分散在各个组件里,统一调整很麻烦;
  • 如果系统在运行时切换主题,还需要主动监听配置变化并更新状态;
  • 实际上是把本该属于资源管理层的逻辑放进了 UI 层。

HarmonyOS 的资源限定词机制,解决的就是这个"让谁来决定用哪组值"的问题。

二、资源限定词:让目录代替判断

HarmonyOS 的资源体系允许开发者按照设备配置特征组织资源目录,框架在运行时根据当前设备状态自动选取匹配的目录。颜色模式是其中支持的限定维度之一。

对于深浅色适配,官方约定的目录命名规则是:

src/main/resources/
├── base/
│   └── element/
│       └── color.json       ← 默认(浅色)颜色
└── dark/
    └── element/
        └── color.json       ← 深色模式颜色

base 目录是通用资源的存放位置,当没有更具体的限定词目录能匹配当前配置时,系统会回退到 base。dark 是颜色模式限定词,对应系统深色主题。

当系统处于浅色模式,$r('app.color.xxx') 读取 base/element/color.json 中的值;系统切换到深色模式,同一个 $r() 调用自动读取 dark/element/color.json 中同名条目的值。整个过程对组件代码透明。

这个机制在 HarmonyOS API 9 及以上版本可用,基于 Stage 模型的工程默认支持。

三、准备两组颜色资源

先在 base/element/color.json 里定义浅色组:

{
  "color": [
    {
      "name": "page_bg",
      "value": "#F5F5F5"
    },
    {
      "name": "card_bg",
      "value": "#FFFFFF"
    },
    {
      "name": "primary_text",
      "value": "#1A1A1A"
    },
    {
      "name": "secondary_text",
      "value": "#666666"
    },
    {
      "name": "divider",
      "value": "#E0E0E0"
    }
  ]
}

再在 dark/element/color.json 里定义深色组,条目名称必须和 base 里完全一致:

{
  "color": [
    {
      "name": "page_bg",
      "value": "#121212"
    },
    {
      "name": "card_bg",
      "value": "#1E1E1E"
    },
    {
      "name": "primary_text",
      "value": "#E8E8E8"
    },
    {
      "name": "secondary_text",
      "value": "#AAAAAA"
    },
    {
      "name": "divider",
      "value": "#2C2C2C"
    }
  ]
}

两份文件只有 value 不同,name 保持一致,这是系统能够对应匹配的前提。

如果 dark/element/color.json 里缺少某个 name,系统会回退到 base 里的同名条目,而不是报错。这个 fallback 行为意味着可以只在 dark 里覆盖需要变化的颜色,不用每条都重复一遍——不过为了维护清晰,建议保持两份文件同步。

四、在 ArkUI 组件里使用

有了资源之后,组件里直接用 $r() 引用就行:

@Component
struct ArticleCard {
  build() {
    Column() {
      Row() {
        Text('文章标题')
          .fontSize(16)
          .fontColor($r('app.color.primary_text'))
      }
      .width('100%')
      .padding({ left: 16, right: 16, top: 12, bottom: 4 })

      Text('这里是摘要文字,用来展示次要颜色的效果。')
        .fontSize(13)
        .fontColor($r('app.color.secondary_text'))
        .padding({ left: 16, right: 16, bottom: 12 })

      Divider()
        .color($r('app.color.divider'))
    }
    .backgroundColor($r('app.color.card_bg'))
    .borderRadius(8)
    .margin({ left: 16, right: 16, bottom: 12 })
  }
}

@Entry
@Component
struct DemoPage {
  build() {
    Column() {
      ArticleCard()
      ArticleCard()
    }
    .width('100%')
    .height('100%')
    .backgroundColor($r('app.color.page_bg'))
  }
}

整个组件里没有一个 isDark 判断,也没有三目运算符。颜色来源只有一个:资源文件。系统主题是浅色,框架取浅色组的值;切到深色,同一行代码取深色组的值。

五、几个值得单独说的地方

1. $r() 引用的是资源 ID,不是字符串

$r('app.color.page_bg') 返回的是 Resource 类型,不是字符串 #F5F5F5。ArkUI 的颜色属性(fontColor、backgroundColor 等)接受 Resource 类型,可以直接传入,框架在渲染时解析实际值。

如果需要在代码逻辑中获取颜色值字符串,可以通过 getContext().resourceManager.getColorSync() 方法,但这不是颜色显示的推荐路径,组件渲染场景直接传 $r() 即可。

2. dark 目录只针对颜色模式

dark 限定词只在颜色模式这一维度生效。如果同时需要适配语言、屏幕方向或屏幕尺寸,需要按照各自的限定词命名目录,如 zh_CN、horizontal、large 等。多个限定词可以组合,例如 dark_zh_CN,目录命名规则参考官方资源限定词组合规范。

3. 颜色值支持 8 位十六进制(含透明度)

color.json 中的 value 支持以下格式:

  • #RGB
  • #ARGB
  • #RRGGBB
  • #AARRGGBB

深色模式下带透明度的蒙层颜色经常用到 8 位格式,比如 #1AFFFFFF 表示白色带 10% 透明度的叠加层。

4. 预览器支持颜色模式切换

DevEco Studio 的预览器(Previewer)支持切换颜色模式。在预览面板顶部可以找到深浅色切换按钮,不需要每次都打包到真机或模拟器上验证效果。这对快速确认两组颜色是否都符合预期很有帮助。

六、和配置变化的关联

资源限定词机制处理的是"渲染时用哪组值",这件事框架自动完成。但有时候需要在应用代码里感知当前颜色模式,比如给第三方绘制库传参,或者记录用户的主题偏好。这时候就需要用到配置变化回调。

在 UIAbility 里,系统主题切换会触发 onConfigurationUpdate 回调:

import { UIAbility, Configuration } from '@kit.AbilityKit';
import { ConfigurationConstant } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onConfigurationUpdate(newConfig: Configuration): void {
    if (newConfig.colorMode === ConfigurationConstant.ColorMode.COLOR_MODE_DARK) {
      // 当前切换为深色模式
    } else if (newConfig.colorMode === ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT) {
      // 当前切换为浅色模式
    }
  }
}

Configuration.colorMode 的类型是 ConfigurationConstant.ColorMode,是一个枚举,包含 COLOR_MODE_DARK、COLOR_MODE_LIGHT 和 COLOR_MODE_NOT_SET 三个值。

这里有一个常见的理解偏差:onConfigurationUpdate 不是触发 ArkUI 颜色更新的原因。资源限定词的自动切换是框架层在渲染时独立完成的,onConfigurationUpdate 只是一个通知钩子,告诉应用层配置发生了变化。开发者如果在这里手动更新状态变量再传给组件,实际上是多做了一层。绝大多数界面颜色适配只需要资源文件 + $r() 就够了,不需要主动监听这个回调。

七、容易出问题的地方

dark 目录里的颜色条目 name 写错

如果 dark/element/color.json 里某个条目的 name 和 base 里的不一致,不会报编译错误,运行时也不会崩溃——框架会静默回退到 base 里的值。结果是深色模式下这个颜色没有切换,而且不容易察觉原因。

建议在两份文件写完之后,对比一遍所有 name。

在 dark 目录放了 color.json 以外的资源

dark 目录下只有 element/color.json 是深色模式资源的标准位置。图片、字符串等其他资源有各自对应的目录结构。如果误把图片放在 dark/media/ 下,图片资源的深色适配是否能生效,需要按官方文档对应的图片限定词规则核对,不要和颜色资源的配置方式混用。

把颜色值直接写在组件属性里

这是资源限定词机制发挥不了作用的情况。如果组件里写的是 .backgroundColor('#FFFFFF') 而不是 .backgroundColor($r('app.color.card_bg')),深色模式切换时这个颜色不会变。

八、排查颜色适配不生效时的顺序

  1. 确认 dark/element/color.json 文件确实存在,路径是 src/main/resources/dark/element/color.json;
  2. 确认文件里的 name 和 base/element/color.json 里完全一致;
  3. 确认组件属性里引用的是 $r('app.color.xxx'),而不是硬编码字符串;
  4. 在 DevEco Studio Previewer 里切换颜色模式,确认预览时是否正常;
  5. 如果预览正常但真机不生效,检查设备系统设置里的深色模式开关是否真的打开;
  6. 如果某一个颜色总是显示浅色值,重新比对两份 color.json 的 name,找遗漏或拼写不一致的条目。

开发经验总结

  • 深浅色适配的核心工作量在资源文件里,不在组件逻辑里;
  • base 放浅色,dark 放深色,name 对齐,$r() 引用,框架自动处理切换;
  • onConfigurationUpdate 是感知主题变化的通知接口,不是触发 UI 颜色更新的前提;
  • 组件里出现硬编码颜色字符串,是深色适配最常见的遗漏点;
  • dark 目录里可以只放需要覆盖的条目,缺少的会 fallback 到 base,但为了维护清晰建议保持同步。

如果你正在做深色模式适配,可以检查一下现有页面里有多少颜色值是直接写在组件属性里的,而不是通过 $r() 引用资源。这类散落的硬编码颜色,往往比缺少 dark 目录更难批量修正。

❤️ 如果本文帮到了你…

  • 请点个赞,让我知道你还在坚持阅读技术长文!
  • 请收藏本文,因为你以后一定还会用上!
  • 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐