• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# WithTheme
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @lushi871202-->
5<!--Designer: @lushi871202-->
6<!--Tester: @sally__-->
7<!--Adviser: @HelloCrease-->
8
9WithTheme组件用于设置应用局部页面自定义主题风格，可设置子组件深浅色模式和自定义配色。
10
11> **说明：**
12>
13> 该组件从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
14>
15> WithTheme支持的系统组件如下：[TextInput](./ts-basic-components-textinput.md)、[Search](./ts-basic-components-search.md)、[Button](./ts-basic-components-button.md)、[Badge](./ts-container-badge.md)、[Swiper](./ts-container-swiper.md)、[Text](./ts-basic-components-text.md)、[Select](./ts-basic-components-select.md)、[Menu](./ts-basic-components-menu.md)、[Counter](./ts-container-counter.md)、[TimePicker](./ts-basic-components-timepicker.md)、[DatePicker](./ts-basic-components-datepicker.md)、[TextPicker](./ts-basic-components-textpicker.md)、[Checkbox](./ts-basic-components-checkbox.md)、[CheckboxGroup](./ts-basic-components-checkboxgroup.md)、[Radio](./ts-basic-components-radio.md)、[Slider](./ts-basic-components-slider.md)、[Progress](./ts-basic-components-progress.md)、[QRCode](./ts-basic-components-qrcode.md)、[Toggle](./ts-basic-components-toggle.md)、[PatternLock](./ts-basic-components-patternlock.md)、[Divider](./ts-basic-components-divider.md)
16
17## 子组件
18
19支持单个子组件。
20
21## 接口
22
23WithTheme(options: WithThemeOptions)
24
25**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
26
27**系统能力：** SystemCapability.ArkUI.ArkUI.Full
28
29**参数：**
30
31| 参数名                            | 类型                                  | 必填  | 说明     |
32|--------------------------------|---------------------------------------|-----|---------------|
33| options | [WithThemeOptions](#withthemeoptions) | 是   | 设置作用域内组件配色。 |
34
35## 属性
36
37不支持[通用属性](ts-component-general-attributes.md)。
38
39## 事件
40
41不支持[通用事件](ts-component-general-events.md)。
42
43## WithThemeOptions
44
45设置WithTheme作用域内组件缺省样式及深浅色模式。
46
47**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
48
49**系统能力：** SystemCapability.ArkUI.ArkUI.Full
50
51| 名称        | 类型                               | 必填 | 说明                |
52|------------------------|---------------------------------------------------------| ---- |------------------------------------------------------------------|
53| theme     | [CustomTheme](#customtheme)    | 否   | 用于自定义WithTheme作用域内组件缺省配色。 <br/> 默认值：undefined，缺省样式跟随系统token默认样式。 |
54| colorMode | [ThemeColorMode](ts-universal-attributes-foreground-blur-style.md#themecolormode枚举说明) | 否   | 用于指定WithTheme作用域内组件配色深浅色模式。<br/>默认值：ThemeColorMode.System       |
55
56## CustomTheme
57
58type CustomTheme = CustomTheme
59
60自定义配色。
61
62**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
63
64**系统能力：** SystemCapability.ArkUI.ArkUI.Full
65
66| 类型     | 说明       |
67| ------ | ---------- |
68| [CustomTheme](../js-apis-arkui-theme.md#customtheme)  | 自定义WithTheme作用域内组件缺省配色。 |
69
70## 示例
71
72设置局部深浅色时，需要添加dark.json资源文件，深浅色模式才会生效。
73
74![resources_dark](figures/resources_dark.png)
75
76dark.json数据示例：
77  ```ts
78    {
79      "color": [
80        {
81          "name": "start_window_background",
82          "value": "#FFFFFF"
83        }
84      ]
85    }
86  ```
87
88```ts
89// 指定局部深浅色模式
90@Entry
91@Component
92struct Index {
93  build() {
94    Column() {
95    // 系统默认
96      Column() {
97        Text('无WithTheme')
98          .fontSize(40)
99          .fontWeight(FontWeight.Bold)
100      }
101      .justifyContent(FlexAlign.Center)
102      .width('100%')
103      .height('33%')
104      .backgroundColor($r('sys.color.background_primary'))
105      // 设置组件为深色模式
106      WithTheme({ colorMode: ThemeColorMode.DARK }) {
107        Column() {
108          Text('WithTheme')
109            .fontSize(40)
110            .fontWeight(FontWeight.Bold)
111          Text('DARK')
112            .fontSize(40)
113            .fontWeight(FontWeight.Bold)
114        }
115        .justifyContent(FlexAlign.Center)
116        .width('100%')
117        .height('33%')
118        .backgroundColor($r('sys.color.background_primary'))
119      }
120      // 设置组件为浅色模式
121      WithTheme({ colorMode: ThemeColorMode.LIGHT }) {
122        Column() {
123          Text('WithTheme')
124            .fontSize(40)
125            .fontWeight(FontWeight.Bold)
126          Text('LIGHT')
127            .fontSize(40)
128            .fontWeight(FontWeight.Bold)
129        }
130        .justifyContent(FlexAlign.Center)
131        .width('100%')
132        .height('33%')
133        .backgroundColor($r('sys.color.background_primary'))
134      }
135    }
136    .height('100%')
137    .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.END, SafeAreaEdge.BOTTOM, SafeAreaEdge.START])
138  }
139}
140```
141![withThemeColorMode](figures/witheThemeColorMode.png)
142
143```ts
144// 自定义WithTheme作用域内组件缺省配色
145import { CustomTheme, CustomColors } from '@kit.ArkUI';
146
147class GreenColors implements CustomColors {
148  fontPrimary = '#ff049404';
149  fontEmphasize = '#FF00541F';
150  fontOnPrimary = '#FFFFFFFF';
151  compBackgroundTertiary = '#1111FF11';
152  backgroundEmphasize = '#FF00541F';
153  compEmphasizeSecondary = '#3322FF22';
154}
155
156class RedColors implements CustomColors {
157  fontPrimary = '#fff32b3c';
158  fontEmphasize = '#FFD53032';
159  fontOnPrimary = '#FFFFFFFF';
160  compBackgroundTertiary = '#44FF2222';
161  backgroundEmphasize = '#FFD00000';
162  compEmphasizeSecondary = '#33FF1111';
163}
164
165class PageCustomTheme implements CustomTheme {
166  colors?: CustomColors
167
168  constructor(colors: CustomColors) {
169    this.colors = colors
170  }
171}
172
173@Entry
174@Component
175struct IndexPage {
176  static readonly themeCount = 3;
177  themeNames: string[] = ['System', 'Custom (green)', 'Custom (red)'];
178  themeArray: (CustomTheme | undefined)[] = [
179    undefined, // System
180    new PageCustomTheme(new GreenColors()),
181    new PageCustomTheme(new RedColors())
182  ]
183  @State themeIndex: number = 0;
184
185  build() {
186    Column() {
187      Column({ space: '8vp' }) {
188        Text(`未使用WithTheme`)
189        // 点击按钮切换局部换肤
190        Button(`切换theme配色：${this.themeNames[this.themeIndex]}`)
191          .onClick(() => {
192            this.themeIndex = (this.themeIndex + 1) % IndexPage.themeCount;
193          })
194
195        // 系统默认按钮配色
196        Button('Button.style(NORMAL) with System Theme')
197          .buttonStyle(ButtonStyleMode.NORMAL)
198        Button('Button.style(EMP..ED) with System Theme')
199          .buttonStyle(ButtonStyleMode.EMPHASIZED)
200        Button('Button.style(TEXTUAL) with System Theme')
201          .buttonStyle(ButtonStyleMode.TEXTUAL)
202      }
203      .margin({
204        top: '50vp'
205      })
206
207      WithTheme({ theme: this.themeArray[this.themeIndex] }) {
208        // WithTheme作用域
209        Column({ space: '8vp' }) {
210          Text(`使用WithTheme`)
211          Button('Button.style(NORMAL) with Custom Theme')
212            .buttonStyle(ButtonStyleMode.NORMAL)
213          Button('Button.style(EMP..ED) with Custom Theme')
214            .buttonStyle(ButtonStyleMode.EMPHASIZED)
215          Button('Button.style(TEXTUAL) with Custom Theme')
216            .buttonStyle(ButtonStyleMode.TEXTUAL)
217        }
218        .width('100%')
219      }
220    }
221  }
222}
223```
224![withThemeSystem](figures/withThemeChangeTheme.gif)
225