文档开发者中心
我的
|

HarmonyOS

鸿蒙应用订阅系统环境变量变化有哪几种途径?

已解决
哪些系统环境变量支持订阅变化?
点赞
收藏
回复
7
分享
举报
浏览87 发布于2026-08-23 08:14江苏
全部评论
最多点赞
最新发布
最早发布
|
采纳答复

可以分成 4 种使用层级:

1. UIAbility / UIExtensionAbility:覆盖 onConfigurationUpdate(newConfig),适合处理当前组件的配置变化。direction、screenDensity、displayId 这 3 项只能在这一层订阅。

2. AbilityStage:覆盖 onConfigurationUpdate(newConfig),适合模块级统一处理;不能订阅 direction、screenDensity、displayId。

3. ApplicationContext:调用 on('environment', EnvironmentCallback),在 onConfigurationUpdated(config) 中处理;保存返回的 callbackId,不需要时调用 off('environment', callbackId)。这种方式可在组件或页面动态注册,但同样不能订阅 direction、screenDensity、displayId;EnvironmentCallback 还会收到 onMemoryLevel。

4. ArkUI 页面响应式订阅:先用 Environment.envProp() / envProps() 把内置环境变量写入 AppStorage,再用 @StorageProp 或 AppStorage.prop() 做单向订阅。系统环境是只读来源,通常不建议用 @StorageLink 反向修改。

Ability Configuration 中可返回的字段包括:language、colorMode、direction、screenDensity、displayId、hasPointerDevice、fontId、fontSizeScale、fontWeightScale、mcc、mnc、locale。具体字段是否触发还受 API 版本、设备形态和注册层级限制。

ArkUI Environment 支持的内置 key 只有:accessibilityEnabled、colorMode、fontScale、fontWeightScale、layoutDirection、languageCode。它和 Ability Configuration 不是同一组 key,不能把 direction、screenDensity、displayId 直接传给 Environment.envProp()。

还要注意:如果应用调用 ApplicationContext.setLanguage() 固定了应用语言,之后系统语言变化不会触发对应的配置更新回调。

1楼回复于2026-08-23 08:22 来自北京

常用有三种,但 UI 场景优先用 @Env,不要同时混用。

  • Env(SystemProperties.xxx):组件内直接订阅,系统值变化会自动更新并刷新 UI(API 22+)。
  • Environment.envProp() + AppStorage:旧状态管理写法,将环境值映射到 AppStorage,再由 @StorageProp/@StorageLink 响应。
  • applicationContext.on('environment', EnvironmentCallback):适合 AbilityStage/UIAbility 做应用级处理,可收到语言、深浅色、屏幕方向、字体缩放/字重等配置变化。

@Env/Environment 固定支持的环境键为:accessibilityEnabled、colorMode、fontScale、fontWeightScale、layoutDirection、languageCode。

注意:不能订阅任意系统设置。网络、定位、电量等需分别使用对应 Kit 的监听 API。

官方资料:

8楼回复于2026-08-24 03:27 来自广东
1
7楼回复于2026-08-24 02:13 来自北京
先按变量类型选监听入口:语言、深浅色和字体缩放这类配置变化走 Ability/Configuration 更新;窗口尺寸、横竖屏走 WindowSizeChange;网络、充电等系统状态用各自 Kit 的事件接口。不是所有环境变量都支持统一订阅,没事件的项只能在页面恢复前台时重新读取并做差异更新。 
6楼回复于2026-08-24 01:41 来自四川
伙伴您好!有三种订阅途径

 途径一:UIAbility 组件中订阅回调

UIAbility 提供 `onConfigurationUpdate()` 回调方法,系统环境变量变化时触发,通过 `Configuration` 对象获取最新配置:

收起
自动换行
深色代码主题
复制
import { Configuration } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {

  onConfigurationUpdate(newConfig: Configuration): void {

    console.info(`language: ${newConfig.language}`);

    if (this.systemLanguage !== newConfig.language) {

      this.systemLanguage = newConfig.language; // 处理系统语言变化

    }

  }

}

特点:回调随 UIAbility 生命周期存在,销毁时自动失效。

途径二:ExtensionAbility 组件中订阅回调

ExtensionAbility 组件(如 FormExtensionAbility 服务卡片)同样提供 `onConfigurationUpdate()` 回调,用法与 UIAbility 一致,回调随 ExtensionAbility 生命周期存在。

### 途径三:ApplicationContext 的 on('environment') 订阅

通过应用上下文订阅 EnvironmentCallback,使用场景更灵活,可在 Ability、HAR/HSP 共享包及页面(UI)中使用:

收起
自动换行
深色代码主题
复制
import { common, EnvironmentCallback, Configuration } from '@kit.AbilityKit';

private callbackId: number = 0;

// 订阅

let callback: EnvironmentCallback = {

  onConfigurationUpdated(config: Configuration) {

    console.info(`config: ${JSON.stringify(config)}`);

  }

};

this.callbackId = this.context.getApplicationContext().on('environment', callback);

// 不再需要时取消订阅

this.context.getApplicationContext().off('environment', this.callbackId);

限制说明:

- 不支持订阅 direction(屏幕方向)、screenDensity(屏幕密度)、displayId(显示设备 ID)

- 若通过 setLanguage 等接口设置了应用级配置,系统环境变化时不再触发该回调

- 需手动调用 off() 取消订阅,避免泄漏

三种途径对比

| 对比项 | UIAbility/ExtensionAbility 回调 | ApplicationContext.on('environment') |

|---|---|---|

| 使用位置 | 仅应用组件内 | 应用组件 + 页面均可用 |

| 生命周期 | 随组件生命周期自动销毁 | 需手动 off() 取消订阅 |

| 支持的环境变量 | 全部(含 direction、screenDensity、displayId) | 有差异(不支持 direction 等) |

补充:UI 响应式方案

纯 UI 展示场景(如深浅色跟随系统)可使用 ArkUI 提供的 Environment 单例,通过 `Environment.envProp()` 将环境变量写入 AppStorage,再以 `@StorageProp` 建立单向数据同步,环境变化时 UI 自动刷新:

收起
自动换行
深色代码主题
复制
Environment.envProp('colorMode', ColorMode.LIGHT);

@StorageProp('colorMode') colorMode: ColorMode = ColorMode.LIGHT;

 选型建议

- 在 Ability 生命周期内处理变化 → 途径一/二

- 在页面或 HAR/HSP 共享包中监听 → 途径三

- 纯 UI 展示跟随系统变化 → 优先使用 Environment 响应式方案

 
展开全部
5楼回复于2026-08-24 01:17 来自广东
区分两类——界面相关(深色/语言/方向)用 onConfigurationUpdate;设备状态(电量/存储/网络)用 commonEventManager 订阅系统公共事件。给出官方订阅项清单和自定义变化的替代方案。
4楼回复于2026-08-23 09:12 来自天津
常用是两条:组件级在 UIAbility/ExtensionAbility/AbilityStage 重写 onConfigurationUpdate();需要动态注册、注销时,用 ApplicationContext.on('environment', EnvironmentCallback),回调名注意是 onConfigurationUpdated。Configuration 中可观察的主要字段有 language、colorMode、direction、screenDensity、displayId、hasPointerDevice、fontId、fontSizeScale、fontWeightScale、mcc、mnc 等;字段都是可选的,是否触发还要看 API 版本和设备形态。最小注册方式如下,不用时按 callbackId 注销:
收起
自动换行
深色代码主题
复制
import { EnvironmentCallback } from '@kit.AbilityKit';

const appContext = this.context.getApplicationContext();
const callback: EnvironmentCallback = {
  onConfigurationUpdated(config) {
    console.info(`language=${config.language}, colorMode=${config.colorMode}`);
  },
  onMemoryLevel(level) {}
};
const callbackId = appContext.on('environment', callback);

// 销毁时注销
appContext.off('environment', callbackId);
2楼回复于2026-08-23 08:44 来自四川
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要提问题

了解社区公约,与您携手共创和谐专业的开发者社区。