harmony 鸿蒙@ohos.arkui.theme(主题换肤)

2025-06-12
浏览 (392)

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

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

说明：

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

导入模块

import { Theme, ThemeControl, CustomColors, Colors, CustomTheme } 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	否	否	品牌色。
warning	ResourceColor	否	否	一级警示色。
alert	ResourceColor	否	否	二级提示色。
confirm	ResourceColor	否	否	确认色。
fontPrimary	ResourceColor	否	否	一级文本字体颜色。
fontSecondary	ResourceColor	否	否	二级文本字体颜色。
fontTertiary	ResourceColor	否	否	三级文本字体颜色。
fontFourth	ResourceColor	否	否	四级文本字体颜色。
fontEmphasize	ResourceColor	否	否	高亮字体颜色。
fontOnPrimary	ResourceColor	否	否	一级文本反转颜色，用于彩色背景。
fontOnSecondary	ResourceColor	否	否	二级文本反转颜色，用于彩色背景。
fontOnTertiary	ResourceColor	否	否	三级文本反转颜色，用于彩色背景。
fontOnFourth	ResourceColor	否	否	四级文本反转颜色，用于彩色背景。
iconPrimary	ResourceColor	否	否	一级图标颜色。
iconSecondary	ResourceColor	否	否	二级图标颜色。
iconTertiary	ResourceColor	否	否	三级图标颜色。
iconFourth	ResourceColor	否	否	四级图标颜色。
iconEmphasize	ResourceColor	否	否	高亮图标颜色。
iconSubEmphasize	ResourceColor	否	否	高亮辅助图标颜色。
iconOnPrimary	ResourceColor	否	否	一级图标反转颜色，用于彩色背景。
iconOnSecondary	ResourceColor	否	否	二级图标反转颜色，用于彩色背景。
iconOnTertiary	ResourceColor	否	否	三级图标反转颜色，用于彩色背景。
iconOnFourth	ResourceColor	否	否	四级图标反转颜色，用于彩色背景。
backgroundPrimary	ResourceColor	否	否	一级背景颜色（实色，不透明）。
backgroundSecondary	ResourceColor	否	否	二级背景颜色（实色，不透明）。
backgroundTertiary	ResourceColor	否	否	三级背景颜色（实色，不透明）。
backgroundFourth	ResourceColor	否	否	四级背景颜色（实色，不透明）。
backgroundEmphasize	ResourceColor	否	否	高亮背景颜色（实色，不透明）。
compForegroundPrimary	ResourceColor	否	否	前背景。
compBackgroundPrimary	ResourceColor	否	否	白色背景。
compBackgroundPrimaryTran	ResourceColor	否	否	白色透明背景。
compBackgroundPrimaryContrary	ResourceColor	否	否	常亮背景。
compBackgroundGray	ResourceColor	否	否	灰色背景。
compBackgroundSecondary	ResourceColor	否	否	二级背景。
compBackgroundTertiary	ResourceColor	否	否	三级背景。
compBackgroundEmphasize	ResourceColor	否	否	高亮背景。
compBackgroundNeutral	ResourceColor	否	否	黑色中性高亮背景颜色。
compEmphasizeSecondary	ResourceColor	否	否	20%高亮背景颜色。
compEmphasizeTertiary	ResourceColor	否	否	10%高亮背景颜色。
compDivider	ResourceColor	否	否	通用分割线颜色。
compCommonContrary	ResourceColor	否	否	通用反转颜色。
compBackgroundFocus	ResourceColor	否	否	获焦态背景颜色。
compFocusedPrimary	ResourceColor	否	否	获焦态一级反转颜色。
compFocusedSecondary	ResourceColor	否	否	获焦态二级反转颜色。
compFocusedTertiary	ResourceColor	否	否	获焦态三级反转颜色。
interactiveHover	ResourceColor	否	否	通用悬停交互式颜色。
interactivePressed	ResourceColor	否	否	通用按压交互式颜色。
interactiveFocus	ResourceColor	否	否	通用获焦交互式颜色。
interactiveActive	ResourceColor	否	否	通用激活交互式颜色。
interactiveSelect	ResourceColor	否	否	通用选择交互式颜色。
interactiveClick	ResourceColor	否	否	通用点击交互式颜色。

CustomTheme

自定义主题风格对象。

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

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

名称	类型	只读	可选	说明
colors	CustomColors	否	是	自定义主题颜色资源。

CustomColors

type CustomColors = Partial<Colors>

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

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

系统能力： 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切换。

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

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

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

示例

import { CustomTheme, CustomColors, ThemeControl } from '@kit.ArkUI';
// 自定义主题颜色
class BlueColors implements CustomColors {
  fontPrimary = Color.White;
  backgroundPrimary = Color.Blue;
  brand = Color.Blue; //品牌色
}

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);