深色模式不一定要写 if/else,资源限定词帮你自动切【鸿蒙心迹】

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的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')),深色模式切换时这个颜色不会变。
八、排查颜色适配不生效时的顺序
- 确认
dark/element/color.json文件确实存在,路径是src/main/resources/dark/element/color.json; - 确认文件里的
name和base/element/color.json里完全一致; - 确认组件属性里引用的是
$r('app.color.xxx'),而不是硬编码字符串; - 在 DevEco Studio Previewer 里切换颜色模式,确认预览时是否正常;
- 如果预览正常但真机不生效,检查设备系统设置里的深色模式开关是否真的打开;
- 如果某一个颜色总是显示浅色值,重新比对两份
color.json的name,找遗漏或拼写不一致的条目。
开发经验总结
- 深浅色适配的核心工作量在资源文件里,不在组件逻辑里;
base放浅色,dark放深色,name对齐,$r()引用,框架自动处理切换;onConfigurationUpdate是感知主题变化的通知接口,不是触发 UI 颜色更新的前提;- 组件里出现硬编码颜色字符串,是深色适配最常见的遗漏点;
dark目录里可以只放需要覆盖的条目,缺少的会 fallback 到base,但为了维护清晰建议保持同步。
如果你正在做深色模式适配,可以检查一下现有页面里有多少颜色值是直接写在组件属性里的,而不是通过 $r() 引用资源。这类散落的硬编码颜色,往往比缺少 dark 目录更难批量修正。
❤️ 如果本文帮到了你…
- 请点个赞,让我知道你还在坚持阅读技术长文!
- 请收藏本文,因为你以后一定还会用上!
- 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
更多推荐



所有评论(0)