1# @ohos.uiAppearance (用户界面外观)(系统接口)
2
3用户界面外观提供管理系统外观的一些基础能力，目前仅包括深浅色模式配置。
4
5> **说明：**
6>
7> 从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8>
9> 本模块接口为系统接口。
10
11
12## 导入模块
13
14```ts
15import { uiAppearance } from '@kit.ArkUI'
16```
17
18
19## DarkMode
20
21深色模式枚举。
22
23
24**系统能力：** SystemCapability.ArkUI.UiAppearance
25
26| 名称 | 值 | 说明 |
27| -- | -- | -- |
28| ALWAYS_DARK | 0 | 系统始终为深色。  |
29| ALWAYS_LIGHT | 1 | 系统始终为浅色。 |
30
31
32## uiAppearance.setDarkMode
33
34setDarkMode(mode: DarkMode, callback: AsyncCallback\<void>): void
35
36设置系统深色模式。
37
38**需要权限：** ohos.permission.UPDATE_CONFIGURATION
39
40**系统能力：** SystemCapability.ArkUI.UiAppearance
41
42**参数：**
43
44| 参数名 | 类型 | 必填 | 说明 |
45| -- | -- | -- | -- |
46| mode | [DarkMode](#darkmode) | 是 | 指定系统的深色模式配置 |
47| callback | AsyncCallback\<void>| 是 | 配置深色模式的异步回调 |
48
49**错误码：**
50
51错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[errcode-uiappearance](errorcode-uiappearance.md)。
52
53| 错误码ID | 错误信息 |
54| -- | -- |
55| 201 | Permission denied. |
56| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.   |
57| 500001 | Internal error. |
58
59**示例：**
60
61  ```ts
62import { uiAppearance } from '@kit.ArkUI'
63import { BusinessError } from '@kit.BasicServicesKit';
64try {
65    uiAppearance.setDarkMode(uiAppearance.DarkMode.ALWAYS_DARK, (error) => {
66      if (error) {
67        console.error('Set dark-mode failed, ' + error.message);
68      } else {
69        console.info('Set dark-mode successfully.');
70      }
71    })
72} catch (error) {
73    let message = (error as BusinessError).message;
74    console.error('Set dark-mode failed, ' + message);
75}
76  ```
77
78
79## uiAppearance.setDarkMode
80
81setDarkMode(mode: DarkMode): Promise\<void>;
82
83设置系统深色模式。
84
85**需要权限：** ohos.permission.UPDATE_CONFIGURATION
86
87**系统能力：** SystemCapability.ArkUI.UiAppearance
88
89**参数：**
90
91| 参数名 | 类型 | 必填 | 说明 |
92| -- | -- | -- | -- |
93| mode | [DarkMode](#darkmode) | 是 | 指定系统深色模式配置 |
94
95**返回值：**
96
97| 类型   | 说明                           |
98| ------ | ------------------------------ |
99| Promise\<void> | Promise对象。无返回结果的Promise对象。|
100
101**错误码：**
102
103错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[errcode-uiappearance](errorcode-uiappearance.md)。
104
105| 错误码ID | 错误信息 |
106| -- | -- |
107| 201 | Permission denied. |
108| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.   |
109| 500001 | Internal error. |
110
111**示例：**
112
113  ```ts
114import { uiAppearance } from '@kit.ArkUI'
115import { BusinessError } from '@kit.BasicServicesKit';
116try {
117    uiAppearance.setDarkMode(uiAppearance.DarkMode.ALWAYS_DARK).then(() => {
118      console.info('Set dark-mode successfully.');
119    }).catch((error:Error) => {
120      console.error('Set dark-mode failed, ' + error.message);
121    });
122} catch (error) {
123    let message = (error as BusinessError).message;
124    console.error('Set dark-mode failed, ' + message);
125}
126  ```
127
128
129## uiAppearance.getDarkMode
130
131getDarkMode(): DarkMode;
132
133获取当前的深色模式配置。
134
135**需要权限：** ohos.permission.UPDATE_CONFIGURATION
136
137**系统能力：** SystemCapability.ArkUI.UiAppearance
138
139**返回值：**
140
141| 类型 | 说明 |
142| -- | -- |
143|[DarkMode](#darkmode) | 系统当前的深色模式配置 |
144
145**错误码：**
146
147错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[errcode-uiappearance](errorcode-uiappearance.md)。
148
149| 错误码ID | 错误信息 |
150| -- | -- |
151| 201 | Permission denied. |
152| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.   |
153| 500001 | Internal error. |
154
155**示例：**
156
157  ```ts
158import { uiAppearance } from '@kit.ArkUI'
159import { BusinessError } from '@kit.BasicServicesKit';
160try {
161    let darkMode = uiAppearance.getDarkMode();
162    console.info('Get dark-mode ' + darkMode);
163} catch (error) {
164    let message = (error as BusinessError).message;
165    console.error('Get dark-mode failed, ' + message);
166}
167  ```
168
169
170## uiAppearance.setFontScale<sup>12+<sup>
171
172setFontScale(fontScale: number): Promise<void>
173
174设置系统字体大小。
175
176**需要权限：** ohos.permission.UPDATE_CONFIGURATION
177
178**系统能力：** SystemCapability.ArkUI.UiAppearance
179
180**系统接口：** 此接口为系统接口。
181
182**参数：**
183
184| 参数名 | 类型 | 必填 | 说明 |
185| -- | -- | -- | -- |
186| fontScale | number | 是 | 需要设置的字体大小。 |
187
188**返回值：**
189
190| 类型 | 说明 |
191| -- | -- |
192| Promise\<void> | Promise对象。无返回结果的Promise对象。|
193
194**错误码：**
195
196错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[errcode-uiappearance](errorcode-uiappearance.md)。
197
198| 错误码ID | 错误信息 |
199| -- | -- |
200| 201 | Permission denied. |
201| 202 | Permission verification failed. A non-system application calls a system API. |
202| 401     | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.   |
203| 500001 | Internal error. |
204
205**示例：**
206
207  ```ts
208import { uiAppearance } from '@kit.ArkUI'
209import { BusinessError } from '@kit.BasicServicesKit';
210
211let fontScale = 10;
212
213try {
214    uiAppearance.setFontScale(fontScale).then(() => {
215      console.info('Set fontScale successfully.');
216    }).catch((error:Error) => {
217      console.error('Set fontScale failed, ' + error.message);
218    });
219} catch (error) {
220    let message = (error as BusinessError).message;
221    console.error('Set fontScale failed, ' + message);
222}
223  ```
224
225
226## uiAppearance.getFontScale<sup>12+<sup>
227
228getFontScale(): number
229
230获取系统字体大小。
231
232**需要权限：** ohos.permission.UPDATE_CONFIGURATION
233
234**系统能力：** SystemCapability.ArkUI.UiAppearance
235
236**系统接口：** 此接口为系统接口。
237
238**返回值：**
239
240| 类型 | 说明 |
241| -- | -- |
242| number | 系统字体大小。 |
243
244**错误码：**
245
246错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[errcode-uiappearance](errorcode-uiappearance.md)。
247
248| 错误码ID | 错误信息 |
249| -- | -- |
250| 201 | Permission denied. |
251| 202 | Permission verification failed. A non-system application calls a system API. |
252| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.   |
253| 500001 | Internal error. |
254
255**示例：**
256
257  ```ts
258import { uiAppearance } from '@kit.ArkUI'
259import { BusinessError } from '@kit.BasicServicesKit';
260try {
261    let fontScale = uiAppearance.getFontScale();
262    console.info('Get fontScale ' + fontScale);
263} catch (error) {
264    let message = (error as BusinessError).message;
265    console.error('Get fontScale failed, ' + message);
266}
267  ```
268
269## uiAppearance.setFontWeightScale<sup>12+<sup>
270
271setFontWeightScale(fontWeightScale: number): Promise<void>
272
273设置系统字体粗细。
274
275**需要权限：** ohos.permission.UPDATE_CONFIGURATION
276
277**系统能力：** SystemCapability.ArkUI.UiAppearance
278
279**系统接口：** 此接口为系统接口。
280
281**参数：**
282
283| 参数名 | 类型 | 必填 | 说明 |
284| -- | -- | -- | -- |
285| fontWeightScale | number | 是 | 需要设置的字体粗细。 |
286
287**返回值：**
288
289| 类型 | 说明 |
290| -- | -- |
291| Promise\<void> | Promise对象。无返回结果的Promise对象。|
292
293**错误码：**
294
295错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[errcode-uiappearance](errorcode-uiappearance.md)。
296
297| 错误码ID | 错误信息 |
298| -- | -- |
299| 201 | Permission denied. |
300| 202 | Permission verification failed. A non-system application calls a system API. |
301| 401     | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.   |
302| 500001 | Internal error. |
303
304**示例：**
305
306  ```ts
307import { uiAppearance } from '@kit.ArkUI'
308import { BusinessError } from '@kit.BasicServicesKit';
309
310let fontWeightScale = 1;
311
312try {
313    uiAppearance.setFontWeightScale(fontWeightScale).then(() => {
314      console.info('Set fontWeightScale successfully.');
315    }).catch((error:Error) => {
316      console.error('Set fontWeightScale failed, ' + error.message);
317    });
318} catch (error) {
319    let message = (error as BusinessError).message;
320    console.error('Set fontWeightScale failed, ' + message);
321}
322  ```
323
324
325## uiAppearance.getFontWeightScale<sup>12+<sup>
326
327getFontWeightScale(): number
328
329获取系统字体大小。
330
331**需要权限：** ohos.permission.UPDATE_CONFIGURATION
332
333**系统能力：** SystemCapability.ArkUI.UiAppearance
334
335**系统接口：** 此接口为系统接口。
336
337**返回值：**
338
339| 类型 | 说明 |
340| -- | -- |
341| number | 系统字体粗细。 |
342
343**错误码：**
344
345错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[errcode-uiappearance](errorcode-uiappearance.md)。
346
347| 错误码ID | 错误信息 |
348| -- | -- |
349| 201 | Permission denied. |
350| 202 | Permission verification failed. A non-system application calls a system API. |
351| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.   |
352| 500001 | Internal error. |
353
354**示例：**
355
356  ```ts
357import { uiAppearance } from '@kit.ArkUI'
358import { BusinessError } from '@kit.BasicServicesKit';
359try {
360    let fontWeightScale = uiAppearance.getFontWeightScale();
361    console.info('Get fontScale ' + fontWeightScale);
362} catch (error) {
363    let message = (error as BusinessError).message;
364    console.error('Get fontWeightScale failed, ' + message);
365}
366  ```