# @ohos.arkui.theme(主题换肤)
支持自定义主题风格,实现App组件风格跟随Theme切换。
> **说明:**
>
> 本模块首批接口从API version 12开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
## 导入模块
```ts
import { Theme, ThemeControl, CustomColors, Colors, CustomTheme, CustomDarkColors } from '@kit.ArkUI';
```
## Theme
当前生效的主题风格对象,可从[onWillApplyTheme](arkui-ts/ts-custom-component-lifecycle.md#onwillapplytheme12)中获取。
**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
**系统能力:** SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
| ------ |-------------------|-----|-----|----------|
| colors | [Colors](#colors) | 否 | 否 | 主题颜色资源。 |
## Colors
主题颜色资源。
**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
**系统能力:** SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|-------------------------------|-----------------------------------------------------|-----|-----|------------------|
| brand | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 品牌色。**影响组件:** [TextInput](./arkui-ts/ts-basic-components-textinput.md)、[Search](./arkui-ts/ts-basic-components-search.md) |
| warning | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 一级警示色。**影响组件:** [TipsDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#tipsdialog)、[AlertDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#alertdialog)、[CustomContentDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#customcontentdialog12)、[Badge](./arkui-ts/ts-container-badge.md)、[Button](./arkui-ts/ts-basic-components-button.md) |
| alert | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 二级提示色。**影响组件:** 暂无组件使用。 |
| confirm | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 确认色。**影响组件:** 暂无组件使用。 |
| fontPrimary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 一级文本字体颜色。**影响组件:** [EditableTitleBar](./arkui-ts/ohos-arkui-advanced-EditableTitleBar.md)、[LoadingDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#loadingdialog)、[TipsDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#tipsdialog)、[ConfirmDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#confirmdialog)、[AlertDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#alertdialog)、[SelectDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#selectdialog)、[CustomContentDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#customcontentdialog12)、[Swiper](./arkui-ts/ts-container-swiper.md)、[Text](./arkui-ts/ts-basic-components-text.md)、[SubHeader](./arkui-ts/ohos-arkui-advanced-SubHeader.md)、[ProgressButton](./arkui-ts/ohos-arkui-advanced-ProgressButton.md)、[AlphabetIndexer](./arkui-ts/ts-container-alphabet-indexer.md)、[Popup](./arkui-ts/ohos-arkui-advanced-Popup.md)、[Select](./arkui-ts/ts-basic-components-select.md)、[Chip](./arkui-ts/ohos-arkui-advanced-Chip.md)、[ToolBar](./arkui-ts/ohos-arkui-advanced-ToolBar.md)、[Menu](./arkui-ts/ts-basic-components-menu.md)、[TextInput](./arkui-ts/ts-basic-components-textinput.md)、[Search](./arkui-ts/ts-basic-components-search.md)、[Counter](./arkui-ts/ts-container-counter.md)、[TimePicker](./arkui-ts/ts-basic-components-timepicker.md)、[DatePicker](./arkui-ts/ts-basic-components-datepicker.md)、[TextPicker](./arkui-ts/ts-basic-components-textpicker.md)、[ComposeListItem](./arkui-ts/ohos-arkui-advanced-ComposeListItem.md)、[TreeView](./arkui-ts/ohos-arkui-advanced-TreeView.md) |
| fontSecondary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 二级文本字体颜色。**影响组件:** [EditableTitleBar](./arkui-ts/ohos-arkui-advanced-EditableTitleBar.md)、[AlertDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#alertdialog)、[CustomContentDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#customcontentdialog12)、[SubHeader](./arkui-ts/ohos-arkui-advanced-SubHeader.md)、[AlphabetIndexer](./arkui-ts/ts-container-alphabet-indexer.md)、[Popup](./arkui-ts/ohos-arkui-advanced-Popup.md)、[TextInput](./arkui-ts/ts-basic-components-textinput.md)、[Search](./arkui-ts/ts-basic-components-search.md)、[ComposeListItem](./arkui-ts/ohos-arkui-advanced-ComposeListItem.md)、[TreeView](./arkui-ts/ohos-arkui-advanced-TreeView.md) |
| fontTertiary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 三级文本字体颜色。**影响组件:** [ComposeListItem](./arkui-ts/ohos-arkui-advanced-ComposeListItem.md) |
| fontFourth | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 四级文本字体颜色。**影响组件:** 暂无组件使用。 |
| fontEmphasize | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 高亮字体颜色。**影响组件:** [TipsDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#tipsdialog)、[ConfirmDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#confirmdialog)、[AlertDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#alertdialog)、[SelectDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#selectdialog)、[CustomContentDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#customcontentdialog12)、[SubHeader](./arkui-ts/ohos-arkui-advanced-SubHeader.md)、[AlphabetIndexer](./arkui-ts/ts-container-alphabet-indexer.md)、[Popup](./arkui-ts/ohos-arkui-advanced-Popup.md)、[Button](./arkui-ts/ts-basic-components-button.md)、[Select](./arkui-ts/ts-basic-components-select.md)、[ToolBar](./arkui-ts/ohos-arkui-advanced-ToolBar.md)、[Search](./arkui-ts/ts-basic-components-search.md)、[TimePicker](./arkui-ts/ts-basic-components-timepicker.md)、[DatePicker](./arkui-ts/ts-basic-components-datepicker.md)、[TextPicker](./arkui-ts/ts-basic-components-textpicker.md) |
| fontOnPrimary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 一级文本反转颜色,用于彩色背景。**影响组件:** [Badge](./arkui-ts/ts-container-badge.md)、[Button](./arkui-ts/ts-basic-components-button.md)、[Chip](./arkui-ts/ohos-arkui-advanced-Chip.md) |
| fontOnSecondary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 二级文本反转颜色,用于彩色背景。**影响组件:** 暂无组件使用。 |
| fontOnTertiary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 三级文本反转颜色,用于彩色背景。**影响组件:** 暂无组件使用。 |
| fontOnFourth | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 四级文本反转颜色,用于彩色背景。**影响组件:** 暂无组件使用。 |
| iconPrimary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 一级图标颜色。**影响组件:** [EditableTitleBar](./arkui-ts/ohos-arkui-advanced-EditableTitleBar.md)、[Swiper](./arkui-ts/ts-container-swiper.md)、[ToolBar](./arkui-ts/ohos-arkui-advanced-ToolBar.md)、[TreeView](./arkui-ts/ohos-arkui-advanced-TreeView.md) |
| iconSecondary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 二级图标颜色。**影响组件:** [LoadingDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#loadingdialog)、[SubHeader](./arkui-ts/ohos-arkui-advanced-SubHeader.md)、[LoadingProgress](./arkui-ts/ts-basic-components-loadingprogress.md)、[Popup](./arkui-ts/ohos-arkui-advanced-Popup.md)、[Chip](./arkui-ts/ohos-arkui-advanced-Chip.md)、[Search](./arkui-ts/ts-basic-components-search.md)、[TreeView](./arkui-ts/ohos-arkui-advanced-TreeView.md) |
| iconTertiary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 三级图标颜色。**影响组件:** [SubHeader](./arkui-ts/ohos-arkui-advanced-SubHeader.md) |
| iconFourth | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 四级图标颜色。**影响组件:** [Checkbox](./arkui-ts/ts-basic-components-checkbox.md)、[CheckboxGroup](arkui-ts/ts-basic-components-checkboxgroup.md)、[Radio](./arkui-ts/ts-basic-components-radio.md) |
| iconEmphasize | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 高亮图标颜色。**影响组件:** [ToolBar](./arkui-ts/ohos-arkui-advanced-ToolBar.md) |
| iconSubEmphasize | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 高亮辅助图标颜色。**影响组件:** 暂无组件使用。 |
| iconOnPrimary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 一级图标反转颜色,用于彩色背景。**影响组件:** [Checkbox](./arkui-ts/ts-basic-components-checkbox.md)、[CheckboxGroup](arkui-ts/ts-basic-components-checkboxgroup.md)、[Radio](./arkui-ts/ts-basic-components-radio.md) |
| iconOnSecondary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 二级图标反转颜色,用于彩色背景。**影响组件:** [Chip](./arkui-ts/ohos-arkui-advanced-Chip.md) |
| iconOnTertiary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 三级图标反转颜色,用于彩色背景。**影响组件:** 暂无组件使用。 |
| iconOnFourth | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 四级图标反转颜色,用于彩色背景。**影响组件:** [ProgressButton](./arkui-ts/ohos-arkui-advanced-ProgressButton.md) |
| backgroundPrimary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 一级背景颜色(实色,不透明)。**影响组件:** [TextInput](./arkui-ts/ts-basic-components-textinput.md)、[QRCode](./arkui-ts/ts-basic-components-qrcode.md) |
| backgroundSecondary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 二级背景颜色(实色,不透明)。**影响组件:** 暂无组件使用。 |
| backgroundTertiary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 三级背景颜色(实色,不透明)。**影响组件:** 暂无组件使用。 |
| backgroundFourth | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 四级背景颜色(实色,不透明)。**影响组件:** 暂无组件使用。 |
| backgroundEmphasize | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 高亮背景颜色(实色,不透明)。**影响组件:** [Progress](./arkui-ts/ts-basic-components-progress.md)、[Button](./arkui-ts/ts-basic-components-button.md)、[Slider](./arkui-ts/ts-basic-components-slider.md) |
| compForegroundPrimary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 前背景。**影响组件:** [QRCode](./arkui-ts/ts-basic-components-qrcode.md) |
| compBackgroundPrimary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 白色背景。**影响组件:** 暂无组件使用。 |
| compBackgroundPrimaryTran | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 白色透明背景。**影响组件:** 暂无组件使用。 |
| compBackgroundPrimaryContrary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 常亮背景。**影响组件:** [Toggle](./arkui-ts/ts-basic-components-toggle.md)、[Slider](./arkui-ts/ts-basic-components-slider.md) |
| compBackgroundGray | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 灰色背景。**影响组件:** 暂无组件使用。 |
| compBackgroundSecondary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 二级背景。**影响组件:** [Swiper](./arkui-ts/ts-container-swiper.md)、[Slider](./arkui-ts/ts-basic-components-slider.md) |
| compBackgroundTertiary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 三级背景。**影响组件:** [EditableTitleBar](./arkui-ts/ohos-arkui-advanced-EditableTitleBar.md)、[Progress](./arkui-ts/ts-basic-components-progress.md)、[AlphabetIndexer](./arkui-ts/ts-container-alphabet-indexer.md)、[Button](./arkui-ts/ts-basic-components-button.md)、[Select](./arkui-ts/ts-basic-components-select.md)、[Toggle](./arkui-ts/ts-basic-components-toggle.md)、[Chip](./arkui-ts/ohos-arkui-advanced-Chip.md)、[TextInput](./arkui-ts/ts-basic-components-textinput.md)、[Search](./arkui-ts/ts-basic-components-search.md) |
| compBackgroundEmphasize | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 高亮背景。**影响组件:** [Swiper](./arkui-ts/ts-container-swiper.md)、[Toggle](./arkui-ts/ts-basic-components-toggle.md)、[Chip](./arkui-ts/ohos-arkui-advanced-Chip.md)、[Checkbox](./arkui-ts/ts-basic-components-checkbox.md)、[CheckboxGroup](arkui-ts/ts-basic-components-checkboxgroup.md)、[Radio](./arkui-ts/ts-basic-components-radio.md) |
| compBackgroundNeutral | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 黑色中性高亮背景颜色。**影响组件:** [PatternLock](./arkui-ts/ts-basic-components-patternlock.md) |
| compEmphasizeSecondary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 20%高亮背景颜色。**影响组件:** [Progress](./arkui-ts/ts-basic-components-progress.md)、[ProgressButton](./arkui-ts/ohos-arkui-advanced-ProgressButton.md)、[AlphabetIndexer](./arkui-ts/ts-container-alphabet-indexer.md)、[Select](./arkui-ts/ts-basic-components-select.md)、[Toggle](./arkui-ts/ts-basic-components-toggle.md) |
| compEmphasizeTertiary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 10%高亮背景颜色。**影响组件:** 暂无组件使用。 |
| compDivider | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 通用分割线颜色。**影响组件:** [SelectDialog](./arkui-ts/ohos-arkui-advanced-Dialog.md#selectdialog)、[PatternLock](./arkui-ts/ts-basic-components-patternlock.md)、[Divider](./arkui-ts/ts-basic-components-divider.md) |
| compCommonContrary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 通用反转颜色。**影响组件:** 暂无组件使用。 |
| compBackgroundFocus | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 获焦态背景颜色。**影响组件:** 暂无组件使用。 |
| compFocusedPrimary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 获焦态一级反转颜色。**影响组件:** 暂无组件使用。 |
| compFocusedSecondary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 获焦态二级反转颜色。**影响组件:** 暂无组件使用。 |
| compFocusedTertiary | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 获焦态三级反转颜色。**影响组件:** [Scroll](arkui-ts/ts-container-scroll.md) |
| interactiveHover | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 通用悬停交互式颜色。**影响组件:** [EditableTitleBar](./arkui-ts/ohos-arkui-advanced-EditableTitleBar.md)、[Chip](./arkui-ts/ohos-arkui-advanced-Chip.md)、[TreeView](./arkui-ts/ohos-arkui-advanced-TreeView.md) |
| interactivePressed | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 通用按压交互式颜色。**影响组件:** [EditableTitleBar](./arkui-ts/ohos-arkui-advanced-EditableTitleBar.md)、[Chip](./arkui-ts/ohos-arkui-advanced-Chip.md)、[TreeView](./arkui-ts/ohos-arkui-advanced-TreeView.md) |
| interactiveFocus | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 通用获焦交互式颜色。**影响组件:** [EditableTitleBar](./arkui-ts/ohos-arkui-advanced-EditableTitleBar.md)、[Chip](./arkui-ts/ohos-arkui-advanced-Chip.md)、[TreeView](./arkui-ts/ohos-arkui-advanced-TreeView.md) |
| interactiveActive | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 通用激活交互式颜色。**影响组件:** [TreeView](./arkui-ts/ohos-arkui-advanced-TreeView.md) |
| interactiveSelect | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 通用选择交互式颜色。**影响组件:** [TreeView](./arkui-ts/ohos-arkui-advanced-TreeView.md) |
| interactiveClick | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 否 | 通用点击交互式颜色。**影响组件:** 暂无组件使用。 |
## CustomTheme
自定义主题风格对象。
**系统能力:** SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|-------------------------------|-----------------------------------------------------|-----|-----|------------|
| colors | [CustomColors](#customcolors) | 否 | 是 | 自定义主题颜色资源。**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
| darkColors20+ | [CustomDarkColors](#customdarkcolors20) | 否 | 是 | 自定义深色主题颜色资源。**说明:** 如果未设置darkColors,颜色值将与浅色模式下的colors配置相同,并且不会随着颜色模式的变化而变化,除非该颜色是通过dark目录下的资源进行设置的。**原子化服务API:** 从API version 20开始,该接口支持在原子化服务中使用。 |
## CustomColors
type CustomColors = Partial\
自定义主题颜色资源类型。
**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
**系统能力:** SystemCapability.ArkUI.ArkUI.Full
| 类型 | 说明 |
|-----|--------------|
| Partial<[Colors](#colors)> | 自定义主题颜色资源类型。 |
## CustomDarkColors20+
type CustomDarkColors = Partial\
自定义深色主题颜色资源类型。
**原子化服务API:** 从API version 20开始,该接口支持在原子化服务中使用。
**系统能力:** SystemCapability.ArkUI.ArkUI.Full
| 类型 | 说明 |
|-----|--------------|
| Partial<[Colors](#colors)> | 自定义深色主题颜色资源类型。 |
## ThemeControl
ThemeControl将自定义Theme应用于App组件内,实现App组件风格跟随Theme切换。
**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
**系统能力:** SystemCapability.ArkUI.ArkUI.Full
### setDefaultTheme
setDefaultTheme(theme: [CustomTheme](#customtheme)): void
将用户自定义Theme设置应用级默认主题,实现应用风格跟随Theme切换。建议在onWindowStageCreate阶段里windowStage.loadContent的完成时回调中使用,详细代码可参考[设置应用内组件自定义主题色](../../ui/theme_skinning.md#设置应用内组件自定义主题色)。
**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
**系统能力:** SystemCapability.ArkUI.ArkUI.Full
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
|--------------|------------------------------|------|----------------|
| theme | [CustomTheme](#customtheme) | 是 | 表示设置的自定义主题风格。 |
**示例**
```ts
import { CustomTheme, CustomColors, ThemeControl } from '@kit.ArkUI';
// 自定义主题颜色
class BlueColors implements CustomColors {
fontPrimary = Color.Red;
backgroundPrimary = Color.Blue;
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%')
}
}
```