目录

设置应用内主题换肤

概述

对于采用ArkTS开发的应用，提供了应用内组件的主题换肤功能，支持局部的深浅色切换及动态换肤。目前，该功能只支持设置应用内主题换肤，暂不支持在UIAbility或窗口层面进行主题设置，同时也不支持C-API和Node-API。

自定义主题色

当应用需要使用换肤功能时，应自定义主题颜色。CustomTheme用于自定义主题色的内容，其属性可选，仅需对需要修改的token字段赋值，其余token将继承系统默认颜色值，可参考系统默认的token颜色值。请参照以下示例自定义主题色：

import { CustomColors, CustomTheme } from '@kit.ArkUI';

export class AppColors implements CustomColors {
  // 自定义主题色
  public brand: ResourceColor = '#FF75D9';
  // 使用$r，让一级警示色在深色和浅色模式下，设置为不同的颜色
  public warning: ResourceColor = $r('sys.color.ohos_id_color_warning');
}

export class AppTheme implements CustomTheme {
  public colors: AppColors = new AppColors();
}

export let gAppTheme: CustomTheme = new AppTheme();

设置应用内组件自定义主题色

设置应用局部页面自定义主题风格

通过设置WithTheme，将自定义主题Theme的配色应用于内部组件的默认样式。在WithTheme的作用范围内，组件的配色会根据Theme的配色进行调整。

在自定义节点BuilderNode中使用WithTheme，为了确保显示效果正确，需手动传递系统环境变化事件，触发节点的全量更新，详细请参考BuilderNode系统环境变化更新updateConfiguration。

如示例所示，使用WithTheme({ theme: this.customTheme })可将作用域内组件的配色设置为自定义主题风格。后续可以通过更新this.customTheme来更换主题风格。onWillApplyTheme回调函数用于使自定义组件能够获取当前生效的Theme对象。

import { CustomColors, CustomTheme, Theme } from '@kit.ArkUI';
import { common } from '@kit.AbilityKit';
// 请将$r('app.color.xxx')替换为实际资源文件
class AppColors implements CustomColors {
  public fontPrimary: ResourceColor = $r('app.color.brand_purple');
  public backgroundEmphasize: ResourceColor = $r('app.color.brand_purple');
}

class AppColorsSec implements CustomColors {
  public fontPrimary: ResourceColor = $r('app.color.brand');
  public backgroundEmphasize: ResourceColor = $r('app.color.brand');
}

class AppTheme implements CustomTheme {
  public colors: AppColors = new AppColors();
}

class AppThemeSec implements CustomTheme {
  public colors: AppColors = new AppColorsSec();
}

@Entry
@Component
struct DisplayPage1 {
  @State customTheme: CustomTheme = new AppTheme();
  // 请将$r('app.string.SetCustomThemeStyle')替换为实际资源文件，在本示例中该资源文件的value值为"设置应用局部页面自定义主题风格"
  @State message: ResourceStr = $r('app.string.SetCustomThemeStyle');
  count = 0;

  build() {
    WithTheme({ theme: this.customTheme }) {
      Row(){
        Column() {
          Text('WithTheme')
            .fontSize(30)
            .margin({bottom: 10})
          Text(this.message)
            .margin({bottom: 10})
          Button('change theme').onClick(() => {
            this.count++;
            if (this.count > 1) {
              this.count = 0;
            }
            switch (this.count) {
              case 0:
                this.customTheme = new AppTheme();
                break;
              case 1:
                this.customTheme = new AppThemeSec();
                break;
              default:
                break;
            }
          })
        }
        .width('100%')
      }
      .height('100%')
      .width('100%')
    }
  }
}

设置应用页面局部深浅色

通过WithTheme可以设置三种颜色模式，跟随系统模式，浅色模式和深色模式。

在WithTheme的作用范围内，组件的样式资源值会根据指定的模式，读取对应的深浅色模式系统和应用资源值。这意味着，在WithTheme作用范围内，组件的配色会根据所指定的深浅模式进行调整。

如下面的示例所示，通过WithTheme({ colorMode: ThemeColorMode.DARK })，可以将作用范围内的组件设置为深色模式。

设置局部深浅色时，需要添加dark.json资源文件，深浅色模式才会生效。

dark.json数据示例：

  {
    "color": [
      {
        "name": "start_window_background",
        "value": "#000000"
      }
    ]
  }
import { ThemeControl } from '@kit.ArkUI';

ThemeControl.setDefaultTheme(undefined);

@Entry
@Component
struct DisplayPage3 {
  @State message: string = 'Hello World';
  @State colorMode: ThemeColorMode = ThemeColorMode.DARK;

  build() {
    WithTheme({ colorMode: this.colorMode }) {
      Row() {
        Column() {
          Text(this.message)
            .fontSize(50)
            .fontWeight(FontWeight.Bold)
          Button('Switch ColorMode').onClick(() => {
            if (this.colorMode === ThemeColorMode.LIGHT) {
              this.colorMode = ThemeColorMode.DARK;
            } else if (this.colorMode === ThemeColorMode.DARK) {
              this.colorMode = ThemeColorMode.LIGHT;
            }
          })
        }
        .width('100%')
      }
      .backgroundColor($r('sys.color.background_primary'))
      .height('100%')
      // 扩展安全区，实现沉浸式深浅色变更效果
      .expandSafeArea(
        [SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.END, SafeAreaEdge.BOTTOM, SafeAreaEdge.START])
    }
  }
}

系统缺省token色值

Token 场景类别 Light 说明 Dark 说明
theme.colors.brand 品牌色 #ff0a59f7 #ff317af7
theme.colors.warning 一级警示色 #ffe84026 #ffd94838
theme.colors.alert 二级警示色 #ffed6f21 #ffdb6b42
theme.colors.confirm 确认色 #ff64bb5c #ff5be854
theme.colors.fontPrimary 一级文本 #e5000000 #e5ffffff
theme.colors.fontSecondary 二级文本 #99000000 #99ffffff
theme.colors.fontTertiary 三级文本 #66000000 #66ffffff
theme.colors.fontFourth 四级文本 #33000000 #33ffffff
theme.colors.fontEmphasize 高亮文本 #ff0a59f7 #ff317af7
theme.colors.fontOnPrimary 一级文本反色 #ffffffff #ff000000
theme.colors.fontOnSecondary 二级文本反色 #99ffffff #99000000
theme.colors.fontOnTertiary 三级文本反色 #66ffffff #66000000
theme.colors.fontOnFourth 四级文本反色 #33ffffff #33000000
theme.colors.iconPrimary 一级图标 #e5000000 #e5ffffff
theme.colors.iconSecondary 二级图标 #99000000 #99ffffff
theme.colors.iconTertiary 三级图标 #66000000 #66ffffff
theme.colors.iconFourth 四级图标 #33000000 #33ffffff
theme.colors.iconEmphasize 高亮图标 #ff0a59f7 #ff317af7
theme.colors.iconSubEmphasize 高亮辅助图标 #660a59f7 #66317af7
theme.colors.iconOnPrimary 一级图标反色 #ffffffff #ff000000
theme.colors.iconOnSecondary 二级图标反色 #99ffffff #99000000
theme.colors.iconOnTertiary 三级图标反色 #66ffffff #66000000
theme.colors.iconOnFourth 四级图标反色 #33ffffff #33000000
theme.colors.backgroundPrimary 一级背景（实色/不透明色） #ffffffff #ffe5e5e5
theme.colors.backgroundSecondary 二级背景（实色/不透明色） #fff1f3f5 #ff191a1c
theme.colors.backgroundTertiary 三级背景（实色/不透明色） #ffe5e5ea #ff202224
theme.colors.backgroundFourth 四级背景（实色/不透明色） #ffd1d1d6 #ff2e3033
theme.colors.backgroundEmphasize 高亮背景（实色/不透明色） #ff0a59f7 #ff317af7
theme.colors.compForegroundPrimary 前背景 #ff000000 #ffe5e5e5
theme.colors.compBackgroundPrimary 白色背景 #ffffffff #ffffffff
theme.colors.compBackgroundPrimaryTran 白色透明背景 #ffffffff #33ffffff
theme.colors.compBackgroundPrimaryContrary 常亮背景 #ffffffff #ffe5e5e5
theme.colors.compBackgroundGray 灰色背景 #fff1f3f5 #ffe5e5ea
theme.colors.compBackgroundSecondary 二级背景 #19000000 #19ffffff
theme.colors.compBackgroundTertiary 三级背景 #0c000000 #0cffffff
theme.colors.compBackgroundEmphasize 高亮背景 #ff0a59f7 #ff317af7
theme.colors.compBackgroundNeutral 黑色中性高亮背景 #ff000000 #ffffffff
theme.colors.compEmphasizeSecondary 20%高亮背景 #330a59f7 #33317af7
theme.colors.compEmphasizeTertiary 10%高亮背景 #190a59f7 #19317af7
theme.colors.compDivider 分割线颜色 #33000000 #33ffffff
theme.colors.compCommonContrary 通用反色 #ffffffff #ff000000
theme.colors.compBackgroundFocus 获焦态背景色 #fff1f3f5 #ff000000
theme.colors.compFocusedPrimary 获焦态一级反色 #e5000000 #e5ffffff
theme.colors.compFocusedSecondary 获焦态二级反色 #99000000 #99ffffff
theme.colors.compFocusedTertiary 获焦态三级反色 #66000000 #66ffffff
theme.colors.interactiveHover 通用悬停交互式颜色 #0c000000 #0cffffff
theme.colors.interactivePressed 通用按压交互式颜色 #19000000 #19ffffff
theme.colors.interactiveFocus 通用获焦交互式颜色 #ff0a59f7 #ff317af7
theme.colors.interactiveActive 通用激活交互式颜色 #ff0a59f7 #ff317af7
theme.colors.interactiveSelect 通用选择交互式颜色 #33000000 #33ffffff
theme.colors.interactiveClick 通用点击交互式颜色 #19000000 #19ffffff

各个token色值可影响的组件可参考Colors接口说明。