HarmonyOS鸿蒙Next开发者技术支持-深色模式开发指导

鸿蒙深色模式开发指导

在鸿蒙应用开发中，用户希望在不同光照环境下获得舒适的视觉体验。系统提供了深色模式（Dark Mode）

方案一：标准化资源管理

步骤1：创建分层颜色资源文件

{ “color”: { “primary_blue”: “#007DFF”, “primary_blue_dark”: “#5C9EFF”, “text_primary”: “#182431”, “text_primary_dark”: “#E6FFFFFF”, “background_primary”: “#FFFFFF”, “background_primary_dark”: “#0C0C0C” } }

步骤2：定义语义颜色映射

{ “semantic”: { “color_bg_primary”: { “light”: “$color:background_primary”, “dark”: “$color:background_primary_dark” }, “color_text_primary”: { “light”: “$color:text_primary”, “dark”: “$color:text_primary_dark” } } }

步骤3：组件级颜色配置

{ “component”: { “button_primary”: { “background”: “$semantic:color_primary”, “text”: “$semantic:color_text_on_primary” }, “card_background”: { “light”: “$color:background_card_light”, “dark”: “$color:background_card_dark” } } }

方案二：动态主题切换实现

步骤1：创建主题管理器

// utils/ThemeManager.ets import configuration from ‘@ohos.application.Configuration’; import common from ‘@ohos.app.ability.common’;

export class ThemeManager { private static instance: ThemeManager; private currentTheme: AppTheme = AppTheme.AUTO;

// 主题枚举 export enum AppTheme { LIGHT = ‘light’, DARK = ‘dark’, AUTO = ‘auto’ }

// 单例模式 static getInstance(): ThemeManager { if (!ThemeManager.instance) { ThemeManager.instance = new ThemeManager(); } return ThemeManager.instance; }

// 初始化监听系统主题变化 init(context: common.UIAbilityContext): void { const config = configuration.getConfiguration(); this.handleConfigurationUpdate(config);

// 监听系统配置变化
configuration.on('configurationUpdate', (config: configuration.Configuration) => {
  this.handleConfigurationUpdate(config);
});

}

// 处理配置更新 private handleConfigurationUpdate(config: configuration.Configuration): void { const colorMode = config.colorMode;

if (this.currentTheme === AppTheme.AUTO) {
  const isDarkMode = colorMode === configuration.ColorMode.COLOR_MODE_DARK;
  this.applyTheme(isDarkMode ? AppTheme.DARK : AppTheme.LIGHT);
}

}

// 应用主题 applyTheme(theme: AppTheme): void { this.currentTheme = theme;

// 更新所有已注册的监听器
this.notifyThemeChange(theme);

// 持久化存储用户选择
this.saveThemePreference(theme);

}

// 获取当前主题 getCurrentTheme(): AppTheme { return this.currentTheme; }

// 判断是否为深色模式 isDarkMode(): boolean { if (this.currentTheme === AppTheme.AUTO) { const config = configuration.getConfiguration(); return config.colorMode === configuration.ColorMode.COLOR_MODE_DARK; } return this.currentTheme === AppTheme.DARK; } }

步骤2：创建主题适配组件

// components/ThemeWrapper.ets @Component export struct ThemeWrapper { @State currentTheme: ThemeManager.AppTheme = ThemeManager.AppTheme.AUTO;

private themeManager = ThemeManager.getInstance();

aboutToAppear(): void { this.currentTheme = this.themeManager.getCurrentTheme(); this.themeManager.addThemeChangeListener((theme) => { this.currentTheme = theme; }); }

build() { Column() { // 子组件 this.ContentSlot() } .width(‘100%’) .height(‘100%’) .backgroundColor(this.getBackgroundColor()) }

@Builder ContentSlot() { // 插槽内容 }

// 根据主题获取颜色 private getBackgroundColor(): ResourceColor { return this.currentTheme === ThemeManager.AppTheme.DARK ? $r(‘app.color.background_dark’) : $r(‘app.color.background_light’); } }

步骤3：在EntryAbility中初始化

// entryability/EntryAbility.ets import ThemeManager from ‘…/utils/ThemeManager’;

export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // 初始化主题管理器 ThemeManager.getInstance().init(this.context); } }

方案三：组件级适配规范

通用组件适配示例：

// components/AdaptiveCard.ets @Component export struct AdaptiveCard { @Prop title: string = ‘’; @Prop content: string = ‘’;

private themeManager = ThemeManager.getInstance();

build() { Column() { // 标题 Text(this.title) .fontColor(this.getTextColor(‘primary’)) .fontSize(18) .fontWeight(FontWeight.Medium) .margin({ top: 12, bottom: 8 })

  // 内容
  Text(this.content)
    .fontColor(this.getTextColor('secondary'))
    .fontSize(14)
    .margin({ bottom: 12 })
}
.width('100%')
.padding(16)
.backgroundColor(this.getCardBackground())
.borderRadius(8)
.shadow(this.getShadowStyle())

}

// 根据主题获取文本颜色 private getTextColor(type: ‘primary’ | ‘secondary’): ResourceColor { const isDark = this.themeManager.isDarkMode();

if (type === 'primary') {
  return isDark ? $r('app.color.text_primary_dark') : 
                  $r('app.color.text_primary_light');
} else {
  return isDark ? $r('app.color.text_secondary_dark') : 
                  $r('app.color.text_secondary_light');
}

}

// 获取卡片背景 private getCardBackground(): ResourceColor { return this.themeManager.isDarkMode() ? $r(‘app.color.background_card_dark’) : $r(‘app.color.background_card_light’); }

// 获取阴影样式 private getShadowStyle(): ShadowStyle { return this.themeManager.isDarkMode() ? { radius: 8, color: Color.Black, offsetX: 0, offsetY: 2 } : { radius: 12, color: ‘#1A000000’, offsetX: 0, offsetY: 4 }; } }

方案四：深色模式测试方案

步骤1：创建测试工具类

// test/ThemeTestUtils.ets export class ThemeTestUtils { // 切换主题并等待渲染完成 static async switchThemeAndWait( theme: ThemeManager.AppTheme, timeout: number = 500 ): Promise<void> { ThemeManager.getInstance().applyTheme(theme); await new Promise(resolve => setTimeout(resolve, timeout)); }

// 验证元素颜色 static verifyElementColor( element: any, expectedColorKey: string, theme: ThemeManager.AppTheme ): boolean { const expectedColor = this.getExpectedColor(expectedColorKey, theme); const actualColor = this.getElementColor(element);

return this.colorsMatch(expectedColor, actualColor);

}

// 生成主题测试用例 static generateThemeTestCases() { return [ { name: ‘浅色模式基础测试’, theme: ThemeManager.AppTheme.LIGHT, assertions: [ { element: ‘background’, colorKey: ‘background_primary’ }, { element: ‘text_primary’, colorKey: ‘text_primary’ } ] }, { name: ‘深色模式基础测试’, theme: ThemeManager.AppTheme.DARK, assertions: [ { element: ‘background’, colorKey: ‘background_primary_dark’ }, { element: ‘text_primary’, colorKey: ‘text_primary_dark’ } ] } ]; } }

实施效果

1. 工具库

theme-utils/ ├── ThemeManager.ets # 主题管理核心类 ├── ThemeWrapper.ets # 主题包装组件 ├── ColorParser.ets # 颜色解析工具 └── ThemeTestUtils.ets # 测试工具类

2. 资源模板

resources/ ├── base/ │ ├── element/ │ │ ├── colors.json # 基础色值 │ │ ├── semantic_colors.json # 语义颜色 │ │ └── component_colors.json # 组件颜色 │ └── media/ # 图片资源（深色/浅色版本） └── dark/ # 深色模式覆盖资源

3. 最佳实践文档

• 《鸿蒙深色模式设计规范》
• 《组件适配checklist》
• 《主题切换性能优化指南》
• 《深色模式测试用例模板》