Environment: Querying the Device Environment

You 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.

The Environment API is a singleton object created by the ArkUI framework at application startup, providing AppStorage with immutable primitive-type properties reflecting the application's runtime state.

The 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.

Before reading this topic, you are advised to read AppStorage.

Environment Built-in Parameters

Constraints

Environment can be called only when UIContext is specified. You call this API inside runScopedTask to make context explicit. If the call is not made in a location where the UI context is explicit, no device environment data can be obtained.

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index');
    let window = windowStage.getMainWindow();
    window.then(window => {
      let uiContext = window.getUIContext();
      uiContext.runScopedTask(() => {
        Environment.envProp('languageCode', 'en');
      });
    });
  }
}

Use Scenarios

Accessing Environment Parameters from the UI

• Use Environment.envProp to store device environment variables in AppStorage.

  // Store languageCode to AppStorage. The default value is en.
  Environment.envProp('languageCode', 'en');
  

  ShowDetails.ets

• Obtain the value of languageCode through @StorageProp in the custom component.

  @StorageProp('languageCode') lang: string = 'en';
  

  ShowDetails.ets

The chain of updates is as follows: Environment > AppStorage > Component.

NOTE

The application cannot modify environment variables. Therefore, @StorageProp is used to obtain them. In this way, even if environment variables are modified in the component, the modification is not synchronized back to AppStorage, affecting the result of obtaining the environment variables in other components.

// Store languageCode to AppStorage.
Environment.envProp('languageCode', 'en');

@Entry
@Component
struct UiEnvironment {
  @StorageProp('languageCode') languageCode: string = 'en';

  build() {
    Row() {
      Column() {
        // Obtain the current device language code.
        Text(this.languageCode)
      }
    }
  }
}

Using Environment in Application Logic

import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN = 0x0001;
const TAG = 'environmentalProject';

// Store languageCode to AppStorage.
Environment.envProp('languageCode', 'en');
// Obtain the one-way bound languageCode variable from AppStorage.
const lang: SubscribedAbstractProperty<string> = AppStorage.prop('languageCode');

if (lang.get() === 'en') {
  // Replace $r('app.string.AppliedLogic_Hello') with the actual resource file. In this example, the value in the resource file is 'Hello!'.
  hilog.info(DOMAIN, TAG, `${$r('app.string.AppliedLogic_Hello')}`);
} else {
  hilog.info(DOMAIN, TAG, 'Hello!');
}