@ohos.app.ability.Configuration (Environment Variables)

The module defines the environment variables for the application runtime, including language, dark/light color mode, screen orientation, and font size. You can subscribe to these environment variables to adapt to different user preferences and enhance the interaction experience.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { Configuration } from '@kit.AbilityKit';

Configuration

System capability: SystemCapability.Ability.AbilityBase

Name	Type	Read-only	Optional	Description
language	string	No	Yes	Current language of the application, for example, zh (Chinese) or en (English). You can set the application language. For details about the value range, see getSystemLanguages. Atomic service API: This API can be used in atomic services since API version 11.
colorMode	ConfigurationConstant.ColorMode	No	Yes	Dark/Light color mode of the application. The light color mode is used by default. You can set the dark/light color mode for an application or a component. The options are as follows: - COLOR_MODE_NOT_SET: The color mode is not set. - COLOR_MODE_LIGHT: light mode. - COLOR_MODE_DARK: dark mode. Atomic service API: This API can be used in atomic services since API version 11.
direction	ConfigurationConstant.Direction	No	Yes	Screen orientation of the application. The options are as follows: - DIRECTION_NOT_SET: The screen orientation is not set. - DIRECTION_HORIZONTAL: horizontal direction. - DIRECTION_VERTICAL: vertical direction. You can subscribe to changes to this environment variable in the UIAbility and UIExtensionAbility, but not in the ApplicationContext or AbilityStage. Atomic service API: This API can be used in atomic services since API version 11.
screenDensity	ConfigurationConstant.ScreenDensity	No	Yes	Screen density. The options are as follows: - SCREEN_DENSITY_NOT_SET: The pixel density is not set. - SCREEN_DENSITY_SDPI: 120. - SCREEN_DENSITY_MDPI: 160. - SCREEN_DENSITY_LDPI: 240. - SCREEN_DENSITY_XLDPI: 320. - SCREEN_DENSITY_XXLDPI: 480. - SCREEN_DENSITY_XXXLDPI: 640. The font size is positively correlated with the screen pixel density. By monitoring changes in the screen pixel density, you can detect adjustments in the font size. Typically, for the same physical size, the higher the screen pixel density, the larger the font display effect. You can subscribe to changes to this environment variable in the UIAbility and UIExtensionAbility, but not in the ApplicationContext or AbilityStage. Atomic service API: This API can be used in atomic services since API version 11.
displayId	number	No	Yes	ID of the display where the application is located. You can subscribe to changes to this environment variable in the UIAbility and UIExtensionAbility, but not in the ApplicationContext or AbilityStage. Atomic service API: This API can be used in atomic services since API version 11.
hasPointerDevice	boolean	No	Yes	Whether a pointer device, such as a keyboard, mouse, or touchpad, is connected. true if connected, false otherwise. Atomic service API: This API can be used in atomic services since API version 11.
fontId14+	string	No	Yes	Unique ID of the font. Atomic service API: This API can be used in atomic services since API version 14.
fontSizeScale12+	number	No	Yes	Font size scale ratio. The value is a non-negative number. The default value is 1. You can set the font size for an application. Atomic service API: This API can be used in atomic services since API version 12.
fontWeightScale12+	number	No	Yes	Font weight scale ratio. The value is a non-negative number. The default value is 1. Atomic service API: This API can be used in atomic services since API version 12.
mcc12+	string	No	Yes	Mobile country code. Atomic service API: This API can be used in atomic services since API version 12.
mnc12+	string	No	Yes	Mobile network code. Atomic service API: This API can be used in atomic services since API version 12.
locale20+	Intl.Locale	No	Yes	Locale. The application automatically adjusts its behavior based on the current locale to meet the localization requirements of users. This property can be set by configuring the system language, system region, and application preferred language. Atomic service API: This API can be used in atomic services since API version 20.

Example

import { UIAbility, AbilityConstant, EnvironmentCallback, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    let envCallback: EnvironmentCallback = {
      onConfigurationUpdated(config) {
        console.info(`envCallback onConfigurationUpdated success: ${JSON.stringify(config)}`);
        let language = config.language;
        let colorMode = config.colorMode;
        let direction = config.direction;
        let screenDensity = config.screenDensity;
        let displayId = config.displayId;
        let hasPointerDevice = config.hasPointerDevice;
        let fontId = config.fontId;
        let fontSizeScale = config.fontSizeScale;
        let fontWeightScale = config.fontWeightScale;
        let mcc = config.mcc;
        let mnc = config.mnc;
        let locale = config.locale;
      },
      onMemoryLevel(level) {
        console.info(`onMemoryLevel level: ${level}`);
      }
    };
    try {
      let applicationContext = this.context.getApplicationContext();
      let callbackId = applicationContext.on('environment', envCallback);
      console.info(`callbackId: ${callbackId}`);
    } catch (paramError) {
      console.error(`error: ${(paramError as BusinessError).code}, ${(paramError as BusinessError).message}`);
    }
  }
}