# @ohos.arkui.theme(主题换肤)

支持自定义主题风格，实现App组件风格跟随Theme切换。

*   本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
    
*   本模块接口仅可在Stage模型下使用。
    

#### 导入模块

```
import { Theme, ThemeControl, CustomColors, Colors, CustomTheme, CustomDarkColors } from '@kit.ArkUI';
```

#### Theme

当前生效的主题风格对象，可从onWillApplyTheme中获取。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| colors | Colors | 否 | 否 | 主题颜色资源。 |

#### Colors

主题颜色资源。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

颜色对应的组件可参考文本色与图标色。

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| brand | ResourceColor | 否 | 否 | 品牌色。 影响组件： TextInput、Search |
| warning | ResourceColor | 否 | 否 | 一级警示色。 影响组件： TipsDialog、AlertDialog、CustomContentDialog、 Badge、Button |
| alert | ResourceColor | 否 | 否 | 二级提示色。 影响组件： 暂无组件使用。 |
| confirm | ResourceColor | 否 | 否 | 确认色。 影响组件： 暂无组件使用。 |
| fontPrimary | ResourceColor | 否 | 否 | 一级文本字体颜色。 影响组件： EditableTitleBar、LoadingDialog、TipsDialog、 ConfirmDialog、AlertDialog、SelectDialog、 CustomContentDialog、Swiper、Text、 SubHeader、ProgressButton、AlphabetIndexer、 Popup、Select、Chip、 ToolBar、Menu、TextInput、 Search、TimePicker、DatePicker、 TextPicker、ComposeListItem、TreeView。从API版本26.0.0开始，新增CalendarPicker、UIPickerComponent、RichEditor、MenuItem、MenuItemGroup、Counter。 |
| fontSecondary | ResourceColor | 否 | 否 | 二级文本字体颜色。 影响组件： EditableTitleBar、AlertDialog、CustomContentDialog、 SubHeader、AlphabetIndexer、Popup、 TextInput、Search、ComposeListItem、 TreeView、TextClock。从API版本26.0.0开始，新增MenuItem、MenuItemGroup。 |
| fontTertiary | ResourceColor | 否 | 否 | 三级文本字体颜色。 影响组件： ComposeListItem |
| fontFourth | ResourceColor | 否 | 否 | 四级文本字体颜色。 影响组件： 暂无组件使用。 |
| fontEmphasize | ResourceColor | 否 | 否 | 高亮字体颜色。 影响组件： TipsDialog、ConfirmDialog、AlertDialog、 SelectDialog、CustomContentDialog、SubHeader、 AlphabetIndexer、Popup、Button、 Select、ToolBar、Search、 TimePicker、DatePicker、TextPicker。从API版本26.0.0开始，新增RichEditor。 |
| fontOnPrimary | ResourceColor | 否 | 否 | 一级文本反转颜色，用于彩色背景。 影响组件： Badge、Button、Chip |
| fontOnSecondary | ResourceColor | 否 | 否 | 二级文本反转颜色，用于彩色背景。 影响组件： 暂无组件使用。 |
| fontOnTertiary | ResourceColor | 否 | 否 | 三级文本反转颜色，用于彩色背景。 影响组件： 暂无组件使用。 |
| fontOnFourth | ResourceColor | 否 | 否 | 四级文本反转颜色，用于彩色背景。 影响组件： 暂无组件使用。 |
| iconPrimary | ResourceColor | 否 | 否 | 一级图标颜色。 影响组件： EditableTitleBar、Swiper、ToolBar、 TreeView。从API版本26.0.0开始，新增MenuItem。 |
| iconSecondary | ResourceColor | 否 | 否 | 二级图标颜色。 影响组件： LoadingDialog、SubHeader、 Popup、Chip、Search、 TreeView。从API版本26.0.0开始，新增LoadingProgress。 |
| iconTertiary | ResourceColor | 否 | 否 | 三级图标颜色。 影响组件： SubHeader |
| iconFourth | ResourceColor | 否 | 否 | 四级图标颜色。 影响组件： Checkbox、CheckboxGroup、Radio |
| iconEmphasize | ResourceColor | 否 | 否 | 高亮图标颜色。 影响组件： ToolBar |
| iconSubEmphasize | ResourceColor | 否 | 否 | 高亮辅助图标颜色。 影响组件： 暂无组件使用。 |
| iconOnPrimary | ResourceColor | 否 | 否 | 一级图标反转颜色，用于彩色背景。 影响组件： Checkbox、CheckboxGroup、Radio |
| iconOnSecondary | ResourceColor | 否 | 否 | 二级图标反转颜色，用于彩色背景。 影响组件： Chip |
| iconOnTertiary | ResourceColor | 否 | 否 | 三级图标反转颜色，用于彩色背景。 影响组件： 暂无组件使用。 |
| iconOnFourth | ResourceColor | 否 | 否 | 四级图标反转颜色，用于彩色背景。 影响组件： ProgressButton |
| backgroundPrimary | ResourceColor | 否 | 否 | 一级背景颜色（实色，不透明）。 影响组件： TextInput、QRCode |
| backgroundSecondary | ResourceColor | 否 | 否 | 二级背景颜色（实色，不透明）。 影响组件： 暂无组件使用。 |
| backgroundTertiary | ResourceColor | 否 | 否 | 三级背景颜色（实色，不透明）。 影响组件： 暂无组件使用。 |
| backgroundFourth | ResourceColor | 否 | 否 | 四级背景颜色（实色，不透明）。 影响组件： 暂无组件使用。 |
| backgroundEmphasize | ResourceColor | 否 | 否 | 高亮背景颜色（实色，不透明）。 影响组件： Progress、Button、Slider |
| compForegroundPrimary | ResourceColor | 否 | 否 | 前景色。 影响组件： QRCode |
| compBackgroundPrimary | ResourceColor | 否 | 否 | 白色背景。 影响组件： 暂无组件使用。 |
| compBackgroundPrimaryTran | ResourceColor | 否 | 否 | 白色透明背景。 影响组件： 暂无组件使用。 |
| compBackgroundPrimaryContrary | ResourceColor | 否 | 否 | 反转背景。 影响组件： Toggle、Slider |
| compBackgroundGray | ResourceColor | 否 | 否 | 灰色背景。 影响组件： 暂无组件使用。 |
| compBackgroundSecondary | ResourceColor | 否 | 否 | 二级背景。 影响组件： Swiper、Slider |
| compBackgroundTertiary | ResourceColor | 否 | 否 | 三级背景。 影响组件： EditableTitleBar、Progress、AlphabetIndexer、 Button、Select、Toggle、 Chip、TextInput、Search。从API版本26.0.0开始，新增UIPickerComponent、TextPicker。 |
| compBackgroundEmphasize | ResourceColor | 否 | 否 | 高亮背景。 影响组件： Swiper、Toggle、Chip、 Checkbox、CheckboxGroup、Radio |
| compBackgroundNeutral | ResourceColor | 否 | 否 | 黑色中性高亮背景颜色。 影响组件： PatternLock |
| compEmphasizeSecondary | ResourceColor | 否 | 否 | 20%高亮背景颜色。 影响组件： Progress、ProgressButton、AlphabetIndexer、 Select、Toggle |
| compEmphasizeTertiary | ResourceColor | 否 | 否 | 10%高亮背景颜色。 影响组件： 暂无组件使用。 |
| compDivider | ResourceColor | 否 | 否 | 通用分割线颜色。 影响组件： SelectDialog、PatternLock、Divider。从API版本26.0.0开始，新增UIPickerComponent、TextPicker、MenuItem、MenuItemGroup、Select。 |
| compCommonContrary | ResourceColor | 否 | 否 | 通用反转颜色。 影响组件： 暂无组件使用。 |
| compBackgroundFocus | ResourceColor | 否 | 否 | 获焦态背景颜色。 影响组件： 暂无组件使用。 |
| compFocusedPrimary | ResourceColor | 否 | 否 | 获焦态一级反转颜色。 影响组件： 暂无组件使用。 |
| compFocusedSecondary | ResourceColor | 否 | 否 | 获焦态二级反转颜色。 影响组件： 暂无组件使用。 |
| compFocusedTertiary | ResourceColor | 否 | 否 | 获焦态三级反转颜色。 影响组件： Scroll |
| interactiveHover | ResourceColor | 否 | 否 | 通用悬停交互式颜色。 影响组件： EditableTitleBar、Chip、TreeView。从API版本26.0.0开始，新增RichEditor、MenuItem、Select。 |
| interactivePressed | ResourceColor | 否 | 否 | 通用按压交互式颜色。 影响组件： EditableTitleBar、Chip、TreeView。从API版本26.0.0开始，新增RichEditor。 |
| interactiveFocus | ResourceColor | 否 | 否 | 通用获焦交互式颜色。 影响组件： EditableTitleBar、Chip、TreeView |
| interactiveActive | ResourceColor | 否 | 否 | 通用激活交互式颜色。 影响组件： TreeView |
| interactiveSelect | ResourceColor | 否 | 否 | 通用选择交互式颜色。 影响组件： TreeView |
| interactiveClick | ResourceColor | 否 | 否 | 通用点击交互式颜色。 影响组件： 从API版本26.0.0开始，新增MenuItem、Select。 |

#### CustomTheme

自定义主题风格对象。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| colors | CustomColors | 否 | 是 | 自定义浅色主题颜色资源。 元服务API： 从API version 12开始，该接口支持在元服务中使用。 |
| darkColors20+ | CustomDarkColors | 否 | 是 | 自定义深色主题颜色资源。 说明：如果未设置darkColors，颜色值将与浅色模式下的colors配置相同，并且不会随着颜色模式的变化而变化，除非该颜色是通过dark目录下的资源进行设置的。 元服务API： 从API version 20开始，该接口支持在元服务中使用。 |

#### CustomColors

type CustomColors = Partial<Colors>

自定义主题颜色资源类型。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

| 类型 | 说明 |
| --- | --- |
| Partial<Colors> | 自定义主题颜色资源类型。 |

#### CustomDarkColors20+

type CustomDarkColors = Partial<Colors>

自定义深色主题颜色资源类型。

**元服务API：** 从API version 20开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

| 类型 | 说明 |
| --- | --- |
| Partial<Colors> | 自定义深色主题颜色资源类型。 |

#### ThemeControl

ThemeControl将自定义Theme应用于App组件内，实现App组件风格跟随Theme切换。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

#### setDefaultTheme

setDefaultTheme(theme: CustomTheme): void

将用户自定义Theme设置应用级默认主题，以实现应用风格跟随Theme切换。若在页面中使用此接口设置应用级默认主题，需确保该接口在页面build前执行。若在UIAbility中使用此接口设置应用级默认主题，需确保该接口在onWindowStageCreate阶段里windowStage.loadContent接口调用完成的回调函数中执行。详细代码可参考设置应用内组件自定义主题色。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| theme | CustomTheme | 是 | 表示设置的自定义主题风格。 |

**示例**

```
import { CustomTheme, CustomColors, ThemeControl } from '@kit.ArkUI';
// 自定义主题颜色
class BlueColors implements CustomColors {
  fontPrimary = "#FF707070";
  backgroundPrimary = "#FF2787D9";
  brand = "#FFEEAAFF"; // 品牌色
}

class PageCustomTheme implements CustomTheme {
  colors?: CustomColors;

  constructor(colors: CustomColors) {
    this.colors = colors;
  }
}
// 创建实例
const BlueColorsTheme = new PageCustomTheme(new BlueColors());
// 在页面build之前执行ThemeControl.setDefaultTheme，设置App默认样式风格为BlueColorsTheme。
ThemeControl.setDefaultTheme(BlueColorsTheme);

@Entry
@Component
struct Index {

  build() {
    Row() {
      Column() {
        // 文本颜色应用fontPrimary
        Text('这是一段文本')
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .margin('5%')
        // 二维码背景色应用backgroundPrimary
        QRCode('Hello')
          .width(100)
          .height(100)
        // 输入框光标颜色应用brand
        TextInput({placeholder: 'input your word...'})
          .width('80%')
          .height(40)
          .margin(20)
      }
      .width('100%')
    }
    .height('100%')
  }
}
```