訂閱系統(tǒng)環(huán)境變量的變化

系統(tǒng)環(huán)境變量是指：在應(yīng)用程序運(yùn)行期間，終端設(shè)備的系統(tǒng)設(shè)置（例如系統(tǒng)的語言環(huán)境、屏幕方向等）發(fā)生變化。

開發(fā)者通過訂閱系統(tǒng)環(huán)境變化，可以使應(yīng)用程序及時(shí)感知這種變化，并作出相應(yīng)處理，從而提供更好的用戶體驗(yàn)。例如，用戶更改系統(tǒng)語言設(shè)置時(shí)，應(yīng)用程序可以自動(dòng)根據(jù)新的語言設(shè)置更新用戶界面的語言；當(dāng)用戶將設(shè)備旋轉(zhuǎn)到橫屏或者豎屏?xí)r，應(yīng)用程序可以重新布局用戶界面，以適應(yīng)屏幕方向和尺寸。

系統(tǒng)配置的變化通常由“設(shè)置”中的選項(xiàng)或“控制中心”中的圖標(biāo)觸發(fā)。訂閱系統(tǒng)環(huán)境變量變化，可以使應(yīng)用程序更加智能地響應(yīng)系統(tǒng)環(huán)境變化，從而提供更好的用戶體驗(yàn)。查看當(dāng)前支持訂閱變化的系統(tǒng)環(huán)境變量，請(qǐng)參見[Configuration]。

基于當(dāng)前的應(yīng)用模型，可以通過以下幾種方式來實(shí)現(xiàn)訂閱系統(tǒng)環(huán)境變量的變化。

• [使用ApplicationContext訂閱回調(diào)]
• [在AbilityStage組件容器中訂閱回調(diào)]
• [在UIAbility組件中訂閱回調(diào)]
• [在ExtensionAbility組件中訂閱回調(diào)]
• 發(fā)前請(qǐng)熟悉鴻蒙開發(fā)指導(dǎo)文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

使用ApplicationContext訂閱回調(diào)

[ApplicationContext]提供了注冊回調(diào)函數(shù)以訂閱系統(tǒng)環(huán)境變量的變化，并且可以通過調(diào)用相應(yīng)的方法來撤銷該回調(diào)。這有助于在資源不再需要時(shí)釋放相關(guān)資源，從而提高系統(tǒng)的可靠性和性能。

1. 使用ApplicationContext.on(type: 'environment', callback: EnvironmentCallback)方法，應(yīng)用程序可以通過在非應(yīng)用組件模塊中訂閱系統(tǒng)環(huán)境變量的變化來動(dòng)態(tài)響應(yīng)這些變化。例如，使用該方法在頁面中監(jiān)測系統(tǒng)語言的變化。

   import common from '@ohos.app.ability.common';
   import EnvironmentCallback from '@ohos.app.ability.EnvironmentCallback';
   import { BusinessError } from '@ohos.base';
   import hilog from '@ohos.hilog';
   import { Configuration } from '@ohos.app.ability.Configuration';
   
   const TAG: string = '[CollaborateAbility]';
   const DOMAIN_NUMBER: number = 0xFF00;
   
   @Entry
   @Component
   struct Index {
     private context = getContext(this) as common.UIAbilityContext;
     private callbackId: number = 0; // 注冊訂閱系統(tǒng)環(huán)境變化的ID
   
     subscribeConfigurationUpdate(): void {
       let systemLanguage: string | undefined = this.context.config.language; // 獲取系統(tǒng)當(dāng)前語言
   
       // 1.獲取ApplicationContext
       let applicationContext = this.context.getApplicationContext();
   
       // 2.通過applicationContext訂閱環(huán)境變量變化
       let environmentCallback: EnvironmentCallback = {
         onConfigurationUpdated(newConfig: Configuration) {
           hilog.info(DOMAIN_NUMBER, TAG, `onConfigurationUpdated systemLanguage is ${systemLanguage}, newConfig: ${JSON.stringify(newConfig)}`);
           if (this.systemLanguage !== newConfig.language) {
             hilog.info(DOMAIN_NUMBER, TAG, `systemLanguage from ${systemLanguage} changed to ${newConfig.language}`);
             systemLanguage = newConfig.language; // 將變化之后的系統(tǒng)語言保存，作為下一次變化前的系統(tǒng)語言
           }
         },
         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}`);
       };
     }
   
     // 頁面展示
     build() {
       //...
     }
   }
   

2. 在資源使用完成之后，可以通過調(diào)用ApplicationContext.off(type: 'environment', callbackId: number)方法釋放相關(guān)資源。

   import common from '@ohos.app.ability.common';
   import { BusinessError } from '@ohos.base';
   import hilog from '@ohos.hilog';
   
   const TAG: string = '[CollaborateAbility]';
   const DOMAIN_NUMBER: number = 0xFF00;
   
   @Entry
   @Component
   struct Index {
     private context = getContext(this) as common.UIAbilityContext;
     private callbackId: number = 0; // 注冊訂閱系統(tǒng)環(huán)境變化的ID
   
     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}`);
       };
   
     }
   
     // 頁面展示
     build() {
       //...
     }
   }
   

在AbilityStage組件容器中訂閱回調(diào)

使用[AbilityStage.onConfigurationUpdate()]回調(diào)方法訂閱系統(tǒng)環(huán)境變量的變化。當(dāng)系統(tǒng)環(huán)境變量發(fā)生變化時(shí)，會(huì)調(diào)用該回調(diào)方法。在該方法中，通過[Configuration]對(duì)象獲取最新的系統(tǒng)環(huán)境配置信息。可以進(jìn)行相應(yīng)的界面適配等操作，從而提高系統(tǒng)的靈活性和可維護(hù)性。

說明：

• DevEco Studio默認(rèn)工程中未自動(dòng)生成AbilityStage，AbilityStage文件的創(chuàng)建請(qǐng)參見[AbilityStage組件容器]。
• 當(dāng)使用回調(diào)方法訂閱系統(tǒng)環(huán)境變量的變化時(shí)，該回調(diào)方法會(huì)隨著[AbilityStage]的生命周期而存在，在Module銷毀時(shí)一并銷毀。

例如，在[AbilityStage.onConfigurationUpdate()]回調(diào)方法中實(shí)現(xiàn)監(jiān)測系統(tǒng)語言的變化。

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

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

let systemLanguage: string | undefined; // 系統(tǒng)當(dāng)前語言

export default class MyAbilityStage extends AbilityStage {
  onCreate(): void {
    systemLanguage = this.context.config.language; // Module首次加載時(shí)，獲取系統(tǒng)當(dāng)前語言
    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; // 將變化之后的系統(tǒng)語言保存，作為下一次變化前的系統(tǒng)語言
    }
  }
}

在UIAbility組件中訂閱回調(diào)

UIAbility組件提供了UIAbility.onConfigurationUpdate()回調(diào)方法用于訂閱系統(tǒng)環(huán)境變量的變化。當(dāng)系統(tǒng)環(huán)境變量發(fā)生變化時(shí)，會(huì)調(diào)用該回調(diào)方法。在該方法中，通過[Configuration]對(duì)象獲取最新的系統(tǒng)環(huán)境配置信息，而無需重啟UIAbility。

說明：

當(dāng)使用回調(diào)方法訂閱系統(tǒng)環(huán)境變量的變化時(shí)，該回調(diào)方法會(huì)隨著UIAbility的生命周期而存在，在UIAbility銷毀時(shí)一并銷毀。

例如，在onConfigurationUpdate()回調(diào)方法中實(shí)現(xiàn)監(jiān)測系統(tǒng)語言的變化。

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

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

let systemLanguage: string | undefined; // 系統(tǒng)當(dāng)前語言

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    systemLanguage = this.context.config.language; // UIAbility實(shí)例首次加載時(shí)，獲取系統(tǒng)當(dāng)前語言
    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; // 將變化之后的系統(tǒng)語言保存，作為下一次變化前的系統(tǒng)語言
    }
  }
  // ...
}

在ExtensionAbility組件中訂閱回調(diào)

ExtensionAbility組件提供了onConfigurationUpdate()回調(diào)方法用于訂閱系統(tǒng)環(huán)境變量的變化。當(dāng)系統(tǒng)環(huán)境變量發(fā)生變化時(shí)，會(huì)調(diào)用該回調(diào)方法。在該方法中，通過[Configuration]對(duì)象獲取最新的系統(tǒng)環(huán)境配置信息。

說明：
HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿
當(dāng)使用回調(diào)方法訂閱系統(tǒng)環(huán)境變量的變化時(shí)，該回調(diào)方法會(huì)隨著ExtensionAbility的生命周期而存在，在ExtensionAbility銷毀時(shí)一并銷毀。

以FormExtensionAbility為例說明。例如，在onConfigurationUpdate()回調(diào)方法中實(shí)現(xiàn)系統(tǒng)環(huán)境變量的變化。

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

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

export default class EntryFormAbility extends FormExtensionAbility {
  onConfigurationUpdate(config: Configuration) {
    hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onConfigurationUpdate:' + JSON.stringify(config));
  }

  // ...
}

審核編輯 黃宇