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