Subscribing to System Environment Variable Changes

System environment variables are system settings (for example, the system language or screen orientation) of a device that may change during the running of an application.

By subscribing to the changes of system environment variables, the application can detect the changes in a timely manner and process the changes accordingly, providing better user experience. For example, when the system language changes, the application can display the UI in the new language; when the user rotates the device to landscape or portrait mode, the application can re-arrange the UI to adapt to the new screen orientation and size.

The system environment variable changes are usually triggered by options in Settings or icons in Control Panel. For details about the system environment variables that support subscription, see Configuration.

You can subscribe to system environment variable changes in the following ways:

Using ApplicationContext for Subscription

ApplicationContext provides an API for registering a callback function to subscribe to the system environment variable changes. It also provides an API for deregistration so you can release related resources when they are no longer needed.

  1. Call ApplicationContext.on(type: 'environment', callback: EnvironmentCallback) to subscribe to changes in system environment variables. The code snippet below is used to subscribe to system language changes on a page.

    import common from '@ohos.app.ability.common';
import { Configuration } from '@ohos.app.ability.Configuration';
import EnvironmentCallback from '@ohos.app.ability.EnvironmentCallback';

@Entry
@Component
struct Index {
  private context = getContext(this) as common.UIAbilityContext;
  private callbackId: number = 0; // ID of the subscription for system environment variable changes.

  subscribeConfigurationUpdate() {
    let systemLanguage: string | undefined = this.context.config.language; // Obtain the system language in use.

    // 1. Obtain an ApplicationContext object.
    let applicationContext = this.context.getApplicationContext();

    // 2. Subscribe to system environment variable changes through ApplicationContext.
    let environmentCallback: EnvironmentCallback = {
      onConfigurationUpdated(newConfig: Configuration) {
        console.info(`onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);

        if (this.systemLanguage !== newConfig.language) {
          console.info(`systemLanguage from ${systemLanguage} changed to ${newConfig.language}`);
          systemLanguage = newConfig.language; // Save the new system language as the system language in use, which will be used for comparison.
        }
      },
      onMemoryLevel(level) {
        console.info(`onMemoryLevel level: ${level}`);
      }
    }

    this.callbackId = applicationContext.on('environment', environmentCallback);
  }

  // Page display.
  build() {
    ...
  }
}

  2. Call ApplicationContext.off(type: 'environment', callbackId: number) to release the resources.

    import common from '@ohos.app.ability.common';

@Entry
@Component
struct Index {
  private context = getContext(this) as common.UIAbilityContext;
  private callbackId: number = 0; // ID of the subscription for system environment variable changes.

  unsubscribeConfigurationUpdate() {
    let applicationContext = this.context.getApplicationContext();
    applicationContext.off('environment', this.callbackId);
  }

  // Page display.
  build() {
    ...
  }
}

Using AbilityStage for Subscription

The AbilityStage component provides the AbilityStage.onConfigurationUpdate() callback for subscribing to system environment variable changes. This callback is invoked when a system environment variable changes. In this callback, the latest system environment configuration is obtained through the Configuration object.

NOTE

  • AbilityStage is not automatically generated in the default project of DevEco Studio. For details about how to create an AbilityStage file, see AbilityStage Component Container.
  • The callback used to subscribe to system environment variable changes has the same lifecycle as the AbilityStage instance and will be destroyed when the instance is destroyed.

The code snippet below uses the AbilityStage.onConfigurationUpdate() callback to subscribe to the system language changes.

import AbilityStage from '@ohos.app.ability.AbilityStage';
import { Configuration } from '@ohos.app.ability.Configuration';

let systemLanguage: string | undefined; // System language in use.

export default class MyAbilityStage extends AbilityStage {
  onCreate() {
    systemLanguage = this.context.config.language; // Obtain the system language in use when the AbilityStage instance is loaded for the first time.
    console.info(`systemLanguage is ${systemLanguage} `);
  }

  onConfigurationUpdate(newConfig: Configuration) {
    console.info(`onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);

    if (systemLanguage !== newConfig.language) {
      console.info(`systemLanguage from ${systemLanguage} changed to ${newConfig.language}`);
      systemLanguage = newConfig.language; // Save the new system language as the system language in use, which will be used for comparison.
    }
  }
}

Using UIAbility for Subscription

The UIAbility component provides the UIAbility.onConfigurationUpdate() callback for subscribing to system environment variable changes. This callback is invoked when a system environment variable changes. In this callback, the latest system environment configuration is obtained through the Configuration object, without restarting the UIAbility.

NOTE

The callback used to subscribe to system environment variable changes has the same lifecycle as the UIAbility instance and will be destroyed when the instance is destroyed.

The code snippet below uses the onConfigurationUpdate() callback to subscribe to the system language changes.

import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import Want from '@ohos.app.ability.Want';
import { Configuration } from '@ohos.app.ability.Configuration';

let systemLanguage: string | undefined; // System language in use.

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    systemLanguage = this.context.config.language; // Obtain the system language in use when the UIAbility instance is loaded for the first time.
    console.info(`systemLanguage is ${systemLanguage} `);
  }

  onConfigurationUpdate(newConfig: Configuration) {
    console.info(`onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);

    if (systemLanguage !== newConfig.language) {
      console.info(`systemLanguage from ${systemLanguage} changed to ${newConfig.language}`);
      systemLanguage = newConfig.language; // Save the new system language as the system language in use, which will be used for comparison.
    }
  }

  // ...
}

Using ExtensionAbility for Subscription

The ExtensionAbility component provides the onConfigurationUpdate() callback for subscribing system environment variable changes. This callback is invoked when a system environment variable changes. In this callback, the latest system environment configuration is obtained through the Configuration object.

NOTE

The callback used to subscribe to system environment variable changes has the same lifecycle as the ExtensionAbility instance and will be destroyed when the instance is destroyed.

The code snippet below uses FormExtensionAbility as an example to describe how to use the onConfigurationUpdate() callback to subscribe to system environment variable changes.

import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
import { Configuration } from '@ohos.app.ability.Configuration';

export default class EntryFormAbility extends FormExtensionAbility {
  onConfigurationUpdate(newConfig: Configuration) {
    console.info(`newConfig is ${JSON.stringify(newConfig)}`);
  }

  // ...
}