• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Environment: Device Environment Query
2
3
4If you need the environment parameters of the device where the application runs to set different scenarios, such as multi-language support and dark/light color mode, use Environment to query the parameters.
5
6
7Environment is a singleton object created by the ArkUI framework at application startup. It provides a range of application state attributes to AppStorage that describe the device environment in which the application is running. Environment and its attributes are immutable. All property values are of simple types only.
8
9
10Environment provides the capability of reading some environment variables of the system (for details, see [Environment Built-in Parameters](#environment-built-in-parameters)) and writing the values of the variables to AppStorage. Therefore, you can use AppStorage to obtain the values of environment variables.
11
12Before reading this topic, you are advised to read [AppStorage](./arkts-appstorage.md).
13
14## Environment Built-in Parameters
15
16| Key| Data Type| Description                                     |
17| ------------------ | ------------------ | ------------------ |
18| accessibilityEnabled              | boolean                  | Whether to enable accessibility.                |
19| colorMode              | ColorMode                  | Color mode. The options are as follows:<br>- **ColorMode.LIGHT**: light mode.<br>- **ColorMode.DARK**: dark mode.                |
20| fontScale              | number                  | Font scale. To enable the font scale to change with the system, set the [configuration](./app-configuration-file.md#configuration) tag.               |
21| fontWeightScale              | number                  | Font weight.               |
22| layoutDirection              | LayoutDirection                  | Layout direction. The options are as follows:<br>- **LayoutDirection.LTR**: from left to right.<br>- **LayoutDirection.RTL**: from right to left.                |
23| languageCode              | string                  | System language value. The value must be in lowercase, for example, **zh**.                |
24
25
26## Use Scenarios
27
28
29### Accessing Environment Parameters from UI
30
31- Use **Environment.envProp** to save the environment variables of the device to AppStorage.
32
33  ```ts
34  // Save languageCode to AppStorage. The default value is en.
35  Environment.envProp('languageCode', 'en');
36  ```
37
38- Decorate the variables with \@StorageProp to link them with components.
39
40  ```ts
41  @StorageProp('languageCode') lang: string = 'en';
42  ```
43
44The chain of updates is as follows: Environment > AppStorage > Component.
45
46> **NOTE**
47>
48> An \@StorageProp decorated variable can be locally modified, but the change will not be updated to AppStorage. This is because the environment variable parameters are read-only to the application.
49
50
51```ts
52// Save the device language code to AppStorage.
53Environment.envProp('languageCode', 'en');
54
55@Entry
56@Component
57struct Index {
58  @StorageProp('languageCode') languageCode: string = 'en';
59
60  build() {
61    Row() {
62      Column() {
63        // Output the current device language code.
64        Text(this.languageCode)
65      }
66    }
67  }
68}
69```
70
71
72### Using Environment in Application Logic
73
74
75```ts
76// Use Environment.envProp to save the device language code to AppStorage.
77Environment.envProp('languageCode', 'en');
78// Obtain the one-way bound languageCode variable from AppStorage.
79const lang: SubscribedAbstractProperty<string> = AppStorage.prop('languageCode');
80
81if (lang.get() === 'en') {
82  console.info('Hi');
83} else {
84  console.info('Bonjour');
85}
86```
87
88
89## Constraints
90
91
92Environment can be called only when the [UIContext](../reference/apis-arkui/js-apis-arkui-UIContext.md#uicontext) is specified. The UIContext is specified when [runScopedTask](../reference/apis-arkui/js-apis-arkui-UIContext.md#runscopedtask) is called. If Environment is called otherwise, no device environment data can be obtained.
93
94
95```ts
96// EntryAbility.ets
97import { UIAbility } from '@kit.AbilityKit';
98import { window } from '@kit.ArkUI';
99
100export default class EntryAbility extends UIAbility {
101  onWindowStageCreate(windowStage: window.WindowStage) {
102    windowStage.loadContent('pages/Index');
103    let window = windowStage.getMainWindow()
104    window.then(window => {
105      let uicontext = window.getUIContext()
106      uicontext.runScopedTask(() => {
107        Environment.envProp('languageCode', 'en');
108      })
109    })
110  }
111}
112```
113