1# @ohos.uiAppearance (UI Appearance) (System API)
2
3The **uiAppearance** module provides basic capabilities for managing the system appearance. It allows for color mode configuration currently, and will introduce more features over time.
4
5> **NOTE**
6>
7> The APIs of this module are supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version.
8>
9> The APIs provided by this module are system APIs.
10
11
12## Modules to Import
13
14```ts
15import { uiAppearance } from '@kit.ArkUI'
16```
17
18
19## DarkMode
20
21Enumerates the color modes.
22
23
24**System capability**: SystemCapability.ArkUI.UiAppearance
25
26| Name| Value| Description|
27| -- | -- | -- |
28| ALWAYS_DARK | 0 | The system is always in dark mode. |
29| ALWAYS_LIGHT | 1 | The system is always in light mode.|
30
31
32## uiAppearance.setDarkMode
33
34setDarkMode(mode: DarkMode, callback: AsyncCallback\<void>): void
35
36Sets the system color mode. This API uses an asynchronous callback to return the result.
37
38**Permission required**: ohos.permission.UPDATE_CONFIGURATION
39
40**System capability**: SystemCapability.ArkUI.UiAppearance
41
42**Parameters**
43
44| Name| Type| Mandatory| Description|
45| -- | -- | -- | -- |
46| mode | [DarkMode](#darkmode) | Yes| Color mode to set.|
47| callback | AsyncCallback\<void>| Yes| Callback used to return the result.|
48
49**Error codes**
50
51For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [UI Appearance Error Codes](errorcode-uiappearance.md).
52
53| ID| Error Message|
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**Example**
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
83Sets the system color mode. This API uses a promise to return the result.
84
85**Permission required**: ohos.permission.UPDATE_CONFIGURATION
86
87**System capability**: SystemCapability.ArkUI.UiAppearance
88
89**Parameters**
90
91| Name| Type| Mandatory| Description|
92| -- | -- | -- | -- |
93| mode | [DarkMode](#darkmode) | Yes| Color mode to set.|
94
95**Return value**
96
97| Type  | Description                          |
98| ------ | ------------------------------ |
99| Promise\<void> | Promise that returns no value.|
100
101**Error codes**
102
103For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [UI Appearance Error Codes](errorcode-uiappearance.md).
104
105| ID| Error Message|
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**Example**
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
133Obtains the system color mode.
134
135**Permission required**: ohos.permission.UPDATE_CONFIGURATION
136
137**System capability**: SystemCapability.ArkUI.UiAppearance
138
139**Return value**
140
141| Type| Description|
142| -- | -- |
143|[DarkMode](#darkmode) | Color mode obtained.|
144
145**Error codes**
146
147For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [UI Appearance Error Codes](errorcode-uiappearance.md).
148
149| ID| Error Message|
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**Example**
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
174Sets the system font scale.
175
176**Permission required**: ohos.permission.UPDATE_CONFIGURATION
177
178**System capability**: SystemCapability.ArkUI.UiAppearance
179
180**System API**: This is a system API.
181
182**Parameters**
183
184| Name| Type| Mandatory| Description|
185| -- | -- | -- | -- |
186| fontScale | number | Yes| Font scale to be set.|
187
188**Return value**
189
190| Type| Description|
191| -- | -- |
192| Promise\<void> | Promise that returns no value.|
193
194**Error codes**
195
196For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [UI Appearance Error Codes](errorcode-uiappearance.md).
197
198| ID| Error Message|
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**Example**
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
230Obtains the system font scale.
231
232**Permission required**: ohos.permission.UPDATE_CONFIGURATION
233
234**System capability**: SystemCapability.ArkUI.UiAppearance
235
236**System API**: This is a system API.
237
238**Return value**
239
240| Type| Description|
241| -- | -- |
242| number | System font scale.|
243
244**Error codes**
245
246For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [UI Appearance Error Codes](errorcode-uiappearance.md).
247
248| ID| Error Message|
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**Example**
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
273Sets the system font weight scale.
274
275**Permission required**: ohos.permission.UPDATE_CONFIGURATION
276
277**System capability**: SystemCapability.ArkUI.UiAppearance
278
279**System API**: This is a system API.
280
281**Parameters**
282
283| Name| Type| Mandatory| Description|
284| -- | -- | -- | -- |
285| fontWeightScale | number | Yes| Font weight scale to set.|
286
287**Return value**
288
289| Type| Description|
290| -- | -- |
291| Promise\<void> | Promise that returns no value.|
292
293**Error codes**
294
295For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [UI Appearance Error Codes](errorcode-uiappearance.md).
296
297| ID| Error Message|
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**Example**
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
329Obtains the system font weight scale.
330
331**Permission required**: ohos.permission.UPDATE_CONFIGURATION
332
333**System capability**: SystemCapability.ArkUI.UiAppearance
334
335**System API**: This is a system API.
336
337**Return value**
338
339| Type| Description|
340| -- | -- |
341| number | System font weight scale.|
342
343**Error codes**
344
345For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [UI Appearance Error Codes](errorcode-uiappearance.md).
346
347| ID| Error Message|
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**Example**
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  ```
367