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