Obtaining/Setting Environment Variables

Environment variables encompass all configuration information that may affect the runtime environment of an application, including internal environment variables that the application can specify (such as font size, appearance, and language) and external environment variables that the application can detect (such as screen orientation).

Under normal circumstances, environment variables change with system settings.

When to Use

Obtaining Environment Variables

You can use getConfigurationSync to obtain the current environment variables, including the dark/light color mode, screen orientation, locale, screen density, and device type. The information helps your application react instantly and deliver a better user experience.

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN_NUMBER = 0xF811;
const TAG = '[EnvAbility0]';

export default class EnvAbility0 extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    try {
      let value = this.context.resourceManager.getConfigurationSync();
      // Screen orientation.
      let direction = value.direction;
      // Locale.
      let locale = value.locale;
    } catch (error) {
      hilog.error(DOMAIN_NUMBER, TAG, 'getConfigurationSync error is ' + error);
    }
  }
}

Setting Environment Variables

The following environment variables can be customized: font size, dark/light color mode, and application language. Other environment variables (such as the screen orientation) are read-only.

Setting Font Size

By default, your application's font size does not change with the system. You can set fontSizeScale in configuration to followSystem to enable it to follow the system setting.

You can use setFontSizeScale to set the font size for the application. After the setting, the application's font size will not change with the system, and you will no longer be able to subscribe to system font size changes.

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

export default class EnvAbility1 extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        return;
      }
    });
    let applicationContext = this.context.getApplicationContext();
    applicationContext.setFontSizeScale(2);
  }
}

Setting Dark/Light Color Mode

By default, your application's dark/light color mode follows the system. You can set the dark/light color modes of your application or components. After the setting, you will no longer be able to subscribe to system dark/light color mode changes.

The configuration takes effect in the following priority: UIAbility's or UIExtensionAbility's dark/light color mode > Application's dark/light color mode > System's dark/light color mode.

• Application's dark/light color mode: Use setColorMode of ApplicationContext to set the dark/light color mode of the application.

  import { UIAbility, ConfigurationConstant } from '@kit.AbilityKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';
  import { window } from '@kit.ArkUI';
  
  export default class EnvAbility2 extends UIAbility {
    onWindowStageCreate(windowStage: window.WindowStage) {
      windowStage.loadContent('pages/Index', (err, data) => {
        if (err.code) {
          hilog.error(0x0000, 'testTag', 'Failed to load the content.');
          return;
        }
        let applicationContext = this.context.getApplicationContext();
        applicationContext.setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK);
      });
    }
  }
  

  EnvAbility2.ets

• UIAbility's dark/light color mode: Use setColorMode of UIAbilityContext to set the dark/light color mode of the UIAbility.

  import { UIAbility, ConfigurationConstant } from '@kit.AbilityKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';
  import { window } from '@kit.ArkUI';
  
  export default class EnvAbility3 extends UIAbility {
    onWindowStageCreate(windowStage: window.WindowStage) {
      windowStage.loadContent('pages/Index', (err, data) => {
        if (err.code) {
          hilog.error(0x0000, 'testTag', 'Failed to load the content.');
          return;
        }
        let uiAbilityContext = this.context;
        uiAbilityContext.setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK);
      });
    }
  }
  

  EnvAbility3.ets

• UIExtensionAbility's dark/light color mode: Use setColorMode of UIExtensionContext to set the dark/light color mode of the UIExtensionAbility.

  // The UIExtensionAbility class does not allow direct inheritance by third-party applications. The child class ShareExtensionAbility is used here as an example.
  import { ShareExtensionAbility, ConfigurationConstant } from '@kit.AbilityKit';
  
  export default class EnvAbility4 extends ShareExtensionAbility {
    onForeground() {
      let uiExtensionContext = this.context;
      uiExtensionContext.setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK);
    }
  }
  

  EnvAbility4.ets

Setting Application Language

By default, the application language changes with the system language. You can use setLanguage to set the application language. After the setting, you will no longer be able to subscribe to system language changes.

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

export default class EnvAbility5 extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load the content.');
        return;
      }
      let applicationContext = this.context.getApplicationContext();
      applicationContext.setLanguage('zh-cn');
    });
  }
}

Subscribing to Environment Variables

System configuration changes are usually triggered by options in Settings or icons in Control Panel. Subscribing to environment variable changes enables applications to respond to system environment changes more intelligently, providing better user experience. For details about the environment variables that support subscription, see Configuration.

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

• Using ApplicationContext for Subscription
• Using AbilityStage for Subscription
• Using UIAbility for Subscription
• Using ExtensionAbility for Subscription

Using ApplicationContext for Subscription

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

1. Non-application components can call on to subscribe to changes in environment variables. The code snippet below is used to subscribe to system language changes on a page.

   import { common, EnvironmentCallback, Configuration } from '@kit.AbilityKit';
   import { hilog } from '@kit.PerformanceAnalysisKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   
   const TAG: string = '[EnvAbilityPage6]';
   const DOMAIN_NUMBER: number = 0xFF00;
   
   @Entry
   @Component
   struct EnvAbilityPage6 {
     private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
     private callbackId: number = 0; // ID of the subscription for system environment variable changes.
   
     subscribeConfigurationUpdate(): void {
       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 environment variable changes through ApplicationContext.
       let environmentCallback: EnvironmentCallback = {
         onConfigurationUpdated(newConfig: Configuration) {
           hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);
           if (systemLanguage !== newConfig.language) {
             hilog.info(DOMAIN_NUMBER, TAG, `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) {
           hilog.info(DOMAIN_NUMBER, TAG, `onMemoryLevel level: ${level}`);
         }
       }
       try {
         this.callbackId = applicationContext.on('environment', environmentCallback);
       } catch (err) {
         let code = (err as BusinessError).code;
         let message = (err as BusinessError).message;
         hilog.error(DOMAIN_NUMBER, TAG, `Failed to register applicationContext. Code is ${code}, message is ${message}`);
       }
     }
   
     // Page display.
     build() {
       // ...
     }
   }
   

   EnvAbilityPage6.ets

2. They can call off to release the resources.

   import { common } from '@kit.AbilityKit';
   import { hilog } from '@kit.PerformanceAnalysisKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   
   const TAG: string = '[EnvAbilityPage7]';
   const DOMAIN_NUMBER: number = 0xFF00;
   
   @Entry
   @Component
   struct EnvAbilityPage7 {
     private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
     private callbackId: number = 0; // ID of the subscription for system environment variable changes.
   
     unsubscribeConfigurationUpdate() {
       let applicationContext = this.context.getApplicationContext();
       try {
         applicationContext.off('environment', this.callbackId);
       } catch (err) {
         let code = (err as BusinessError).code;
         let message = (err as BusinessError).message;
         hilog.error(DOMAIN_NUMBER, TAG, `Failed to unregister applicationContext. Code is ${code}, message is ${message}`);
       }
     }
   
     // Page display.
     build() {
       // ...
     }
   }
   

   EnvAbilityPage7.ets

Using AbilityStage for Subscription

The AbilityStage component provides the AbilityStage.onConfigurationUpdate() callback for subscribing to environment variable changes. This callback is invoked when an environment variable changes. In this callback, the latest environment variable information is obtained through a Configuration object. You can perform operations such as UI adaptation to improve system flexibility and maintainability.

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 module is destroyed.

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

import { AbilityStage, Configuration } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[EnvAbilityStage]';
const DOMAIN_NUMBER: number = 0xFF00;

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

export default class EnvAbilityStage extends AbilityStage {
  onCreate(): void {
    systemLanguage = this.context.config.language; // Obtain the system language in use when the module is loaded for the first time.
    hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage is ${systemLanguage}`);
  }

  onConfigurationUpdate(newConfig: Configuration): void {
    hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdate, language: ${newConfig.language}`);
    hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);

    if (systemLanguage !== newConfig.language) {
      hilog.info(DOMAIN_NUMBER, TAG, `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 provides the UIAbility.onConfigurationUpdate() callback for subscribing to environment variable changes. This callback is invoked when an environment variable changes. In this callback, the latest environment variable information is obtained through the Configuration object, without restarting the UIAbility.

NOTE

• When an application subscribes to environment variable changes through a callback, the subscription remains valid throughout the lifecycle of the hosting UIAbility. Once the UIAbility is destroyed, all previously registered callback subscriptions become invalid, and the application will no longer receive any callback notifications.
• If this API is used to listen for screen orientation changes, you need to set orientation to auto_rotation in abilities of the module.json5 file.

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

import { AbilityConstant, Configuration, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[EnvAbility9]';
const DOMAIN_NUMBER: number = 0xFF00;

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

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

  onConfigurationUpdate(newConfig: Configuration): void {
    hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);

    if (systemLanguage !== newConfig.language) {
      hilog.info(DOMAIN_NUMBER, TAG, `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 provides the onConfigurationUpdate() callback for subscribing to environment variable changes. This callback is invoked when an environment variable changes. In this callback, the latest environment variable information is obtained through a Configuration object.

NOTE

When an application subscribes to environment variable changes through a callback, the subscription remains valid throughout the lifecycle of the hosting ExtensionAbility. Once the ExtensionAbility is destroyed, all previously registered callback subscriptions become invalid, and the application will no longer receive any callback notifications.

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

import { FormExtensionAbility } from '@kit.FormKit';
import { Configuration } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[EnvFormExtensionAbility]';
const DOMAIN_NUMBER: number = 0xFF00;

export default class EnvFormExtensionAbility extends FormExtensionAbility {
  onConfigurationUpdate(newConfig: Configuration) {
    hilog.info(DOMAIN_NUMBER, TAG, 'onConfigurationUpdate: ' + JSON.stringify(newConfig));
  }
}