• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.uiAppearance (UI Appearance)
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 '@ohos.uiAppearance'
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 [UI Appearance Error Codes](../errorcodes/errorcode-uiappearance.md).
52
53| ID| Error Message|
54| -- | -- |
55| 500001 | Internal error. |
56
57**Example**
58
59  ```ts
60import uiAppearance from '@ohos.uiAppearance'
61import { BusinessError } from '@ohos.base';
62try {
63    uiAppearance.setDarkMode(uiAppearance.DarkMode.ALWAYS_DARK, (error) => {
64      if (error) {
65        console.error('Set dark-mode failed, ' + error.message);
66      } else {
67        console.info('Set dark-mode successfully.');
68      }
69    })
70} catch (error) {
71    let message = (error as BusinessError).message;
72    console.error('Set dark-mode failed, ' + message);
73}
74  ```
75
76
77## uiAppearance.setDarkMode
78
79setDarkMode(mode: DarkMode): Promise\<void>;
80
81Sets the system color mode. This API uses a promise to return the result.
82
83**Permission required**: ohos.permission.UPDATE_CONFIGURATION
84
85**System capability**: SystemCapability.ArkUI.UiAppearance
86
87**Parameters**
88
89| Name| Type| Mandatory| Description|
90| -- | -- | -- | -- |
91| mode | [DarkMode](#darkmode) | Yes| Color mode to set.|
92
93**Return value**
94
95| Type  | Description                          |
96| ------ | ------------------------------ |
97| Promise\<void> | Promise that returns no value.|
98
99**Error codes**
100
101For details about the error codes, see [UI Appearance Error Codes](../errorcodes/errorcode-uiappearance.md).
102
103| ID| Error Message|
104| -- | -- |
105| 500001 | Internal error. |
106
107**Example**
108
109  ```ts
110import uiAppearance from '@ohos.uiAppearance'
111import { BusinessError } from '@ohos.base';
112try {
113    uiAppearance.setDarkMode(uiAppearance.DarkMode.ALWAYS_DARK).then(() => {
114      console.info('Set dark-mode successfully.');
115    }).catch((error:Error) => {
116      console.error('Set dark-mode failed, ' + error.message);
117    });
118} catch (error) {
119    let message = (error as BusinessError).message;
120    console.error('Set dark-mode failed, ' + message);
121}
122  ```
123
124
125## uiAppearance.getDarkMode
126
127getDarkMode(): DarkMode;
128
129Obtains the system color mode.
130
131**Permission required**: ohos.permission.UPDATE_CONFIGURATION
132
133**System capability**: SystemCapability.ArkUI.UiAppearance
134
135**Return value**
136
137| Type| Description|
138| -- | -- |
139|[DarkMode](#darkmode) | Color mode obtained.|
140
141**Error codes**
142
143For details about the error codes, see [UI Appearance Error Codes](../errorcodes/errorcode-uiappearance.md).
144
145| ID| Error Message|
146| -- | -- |
147| 500001 | Internal error. |
148
149**Example**
150
151  ```ts
152import uiAppearance from '@ohos.uiAppearance'
153import { BusinessError } from '@ohos.base';
154try {
155    let darkMode = uiAppearance.getDarkMode();
156    console.info('Get dark-mode ' + darkMode);
157} catch (error) {
158    let message = (error as BusinessError).message;
159    console.error('Get dark-mode failed, ' + message);
160}
161  ```
162