• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Environment: Querying the Device Environment
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @zzq212050299-->
5<!--Designer: @s10021109-->
6<!--Tester: @TerryTsao-->
7<!--Adviser: @zhang_yixin13-->
8
9You may want your application to behave differently based on the device environment where the application is running, for example, switching to dark mode or a specific language. In this case, you need the **Environment** API for device environment query.
10
11**Environment** is a singleton object created by the ArkUI framework during application launch, providing AppStorage with immutable primitive-type properties reflecting the application's runtime state.
12
13The **Environment** API enables reading system environment variables and writing their values to AppStorage. You must access these values through AppStorage. For details, see [Environment Built-in Parameters](#environment-built-in-parameters).
14
15Before reading this topic, you are advised to read [AppStorage](./arkts-appstorage.md).
16
17## Environment Built-in Parameters
18
19| Key| Data Type| Description                                     |
20| ------------------ | ------------------ | ------------------ |
21| accessibilityEnabled              | boolean                  | Whether to enable screen reader accessibility. The value **true** means to enable screen reader accessibility, and **false** means the opposite.|
22| colorMode              | ColorMode                  | Color mode.<br>- **ColorMode.LIGHT**: light color mode.<br>- **ColorMode.DARK**: dark color mode.                |
23| fontScale              | number                  | Font scale. To enable the font scale to change with the system, set the [configuration](../../quick-start/app-configuration-file.md#configuration) tag.<br>The default value follows the default system settings.               |
24| fontWeightScale              | number                  | Font weight. The value range varies by system or device model.<br>The default value follows the default system settings.               |
25| layoutDirection              | LayoutDirection                  | Layout direction.<br>**LayoutDirection.LTR**: from left to right.<br>**LayoutDirection.RTL**: from right to left.                |
26| languageCode              | string                  | System language code. The value must be in lowercase, for example, **zh**.<br>The default value follows the default system settings.                |
27
28## Use Scenarios
29
30### Accessing Environment Parameters from the UI
31
32- Use Environment.[envProp](../../reference/apis-arkui/arkui-ts/ts-state-management.md#envprop10) to store device environment variables in AppStorage.
33
34  ```ts
35  // Store languageCode (default value: en) to AppStorage.
36  Environment.envProp('languageCode', 'en');
37  ```
38
39- Decorate the variables with \@StorageProp to link them with components.
40
41  ```ts
42  @StorageProp('languageCode') lang: string = 'en';
43  ```
44
45The chain of updates is as follows: Environment > AppStorage > Component.
46
47> **NOTE**
48>
49> An \@StorageProp decorated variable can be locally modified, but the change will not be updated to AppStorage. This is because environment variables are read-only.
50
51```ts
52// Store languageCode 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        // Obtain the current device language code.
64        Text(this.languageCode)
65      }
66    }
67  }
68}
69```
70
71### Using Environment in Application Logic
72
73```ts
74// Store languageCode to AppStorage.
75Environment.envProp('languageCode', 'en');
76// Obtain the one-way bound languageCode variable from AppStorage.
77const lang: SubscribedAbstractProperty<string> = AppStorage.prop('languageCode');
78
79if (lang.get() === 'en') {
80  console.info('Hi');
81} else {
82  console.info('Bonjour');
83}
84```
85
86## Constraints
87
88**Environment** can be called only when the [UIContext](../../reference/apis-arkui/arkts-apis-uicontext-uicontext.md) is specified. You can specify the context in [runScopedTask](../../reference/apis-arkui/arkts-apis-uicontext-uicontext.md#runscopedtask). If **Environment** is called without explicit **UIContext**, no device environment data can be obtained.
89
90```ts
91// EntryAbility.ets
92import { UIAbility } from '@kit.AbilityKit';
93import { window } from '@kit.ArkUI';
94
95export default class EntryAbility extends UIAbility {
96  onWindowStageCreate(windowStage: window.WindowStage) {
97    windowStage.loadContent('pages/Index');
98    let window = windowStage.getMainWindow();
99    window.then(window => {
100      let uiContext = window.getUIContext();
101      uiContext.runScopedTask(() => {
102        Environment.envProp('languageCode', 'en');
103      });
104    });
105  }
106}
107```
108