前言

在HarmonyOS应用开发中，上下文（Context）是访问应用资源和能力的关键对象。@pura/harmony-utils 的 AppUtil 提供了便捷的上下文获取方法，无需手动传递Context参数，即可在任何页面中获取所需的上下文对象。本文将从上下文类型、获取方式、使用场景等多个维度进行全面讲解，帮助开发者深入理解并灵活运用各种上下文对象。

一、上下文类型核心API

HarmonyOS中有多种上下文类型，各自用途不同，理解它们的区别是正确使用的前提：

上下文类型	获取方法	返回类型	适用场景	生命周期
ApplicationContext	AppUtil.getApplicationContext()	ApplicationContext	全局资源访问、系统服务调用	应用级
UIAbilityContext	AppUtil.getContext()	UIAbilityContext	Ability操作、路由跳转、资源获取	Ability级
UIContext	AppUtil.getUIContext()	UIContext	UI操作、弹窗、动画、组件操作	页面级

1.1 核心特性

• 统一管理：无需在各组件间手动传递Context，通过AppUtil全局获取
• 类型安全：每种上下文都有明确的TypeScript类型定义
• 懒加载：UIContext采用懒加载机制，页面渲染后才可获取
• 线程安全：内部做了同步处理，支持多线程环境下的上下文获取

1.2 上下文选择指南

场景	推荐上下文	原因
注册应用级回调	ApplicationContext	生命周期与应用一致
启动另一个Ability	UIAbilityContext	需要Ability级别的连接信息
显示弹窗/Toast	UIContext	需要UI渲染环境
访问资源文件	UIAbilityContext	需要资源路径信息
获取系统服务	ApplicationContext	不依赖特定Ability

二、完整使用步骤

2.1 安装依赖

在项目根目录执行以下命令安装harmony-utils：

ohpm install @pura/harmony-utils

安装完成后，在 oh-package.json5 中确认依赖已添加：

{
  "dependencies": {
    "@pura/harmony-utils": "^1.0.0"
  }
}

2.2 获取ApplicationContext

ApplicationContext 是应用级上下文，用于注册应用级回调、获取应用级信息，生命周期与应用一致：

import { AppUtil } from '@pura/harmony-utils';

Button('获取ApplicationContext')
  .width('100%')
  .onClick(() => {
    try {
      let ctx = AppUtil.getApplicationContext();
      console.info('ApplicationContext获取成功');
      // 可用于注册应用级回调、获取应用信息等
    } catch (e) {
      console.error('获取失败: ' + e);
    }
  })

2.3 获取UIAbilityContext

UIAbilityContext 是Ability级上下文，用于启动Ability、获取资源等操作：

Button('获取UIAbilityContext')
  .width('100%')
  .onClick(() => {
    try {
      let ctx = AppUtil.getContext();
      console.info('UIAbilityContext获取成功');
      // 可用于路由跳转、资源访问等
    } catch (e) {
      console.error('获取失败: ' + e);
    }
  })

2.4 获取UIContext

UIContext 是UI上下文，用于访问UI相关能力，如弹窗、动画等：

Button('获取UIContext')
  .width('100%')
  .onClick(() => {
    try {
      let ctx = AppUtil.getUIContext();
      if (ctx) {
        console.info('UIContext获取成功');
      } else {
        console.warn('UIContext为空，请确认页面已渲染');
      }
    } catch (e) {
      console.error('获取失败: ' + e);
    }
  })

三、完整页面示例

以下是一个完整的页面组件，展示了三种上下文的获取与使用：

import { AppUtil } from '@pura/harmony-utils';

@Entry
@Component
struct ContextDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('获取ApplicationContext').width('100%').onClick(() => {
        try {
          let ctx = AppUtil.getApplicationContext();
          this.result = 'ApplicationContext: ' + (ctx ? '获取成功 ✅' : '获取失败 ❌');
        } catch (e) { this.result = '异常: ' + e; }
      });

      Button('获取UIAbilityContext').width('100%').onClick(() => {
        try {
          let ctx = AppUtil.getContext();
          this.result = 'UIAbilityContext: ' + (ctx ? '获取成功 ✅' : '获取失败 ❌');
        } catch (e) { this.result = '异常: ' + e; }
      });

      Button('获取UIContext').width('100%').onClick(() => {
        try {
          let ctx = AppUtil.getUIContext();
          this.result = 'UIContext: ' + (ctx ? '获取成功 ✅' : '页面未渲染，暂不可用');
        } catch (e) { this.result = '异常: ' + e; }
      });

      Text(this.result)
        .fontSize(14)
        .fontColor('#333333')
        .width('100%')
        .padding(12)
        .backgroundColor('#F5F5F5')
        .borderRadius(8)
    }
    .padding(16)
  }
}

四、进阶用法

4.1 结合其他工具类使用

AppUtil 获取的上下文是harmony-utils其他工具类的基础，它们内部都依赖这些上下文：

import { AppUtil, DeviceUtil, NetworkUtil, ToastUtil } from '@pura/harmony-utils';

// 上下文初始化后，其他工具类才能正常工作
async function initApp() {
  let ctx = AppUtil.getApplicationContext();
  if (ctx) {
    let deviceId = DeviceUtil.getDeviceId();
    let isConnected = await NetworkUtil.isConnected();
    ToastUtil.showToast(`设备: ${deviceId}, 网络: ${isConnected ? '已连接' : '未连接'}`);
  }
}

4.2 上下文空值安全检查

在实际项目中，建议对所有上下文获取进行空值判断：

import { AppUtil } from '@pura/harmony-utils';

function safeGetContext(): UIAbilityContext | null {
  try {
    let ctx = AppUtil.getContext();
    return ctx ?? null;
  } catch (e) {
    console.error('[ContextDemo] 获取上下文失败: ' + e);
    return null;
  }
}

// 使用示例
const ctx = safeGetContext();
if (ctx) {
  // 安全使用上下文
} else {
  console.warn('上下文不可用，请检查初始化状态');
}

五、注意事项

1. 初始化前提：使用前必须调用 AppUtil.init() 完成初始化，否则会抛出异常
2. UIContext获取时机：getUIContext() 需要页面渲染完成后才能获取，在 aboutToAppear 中可能为空
3. 上下文生命周期：不同上下文的生命周期不同，ApplicationContext最长，UIContext最短
4. 多Ability场景：每个Ability有独立的UIAbilityContext，需注意区分
5. 线程限制：上下文管理基于主线程，不建议在Worker线程中直接使用

六、常见问题

Q1: 获取UIContext返回null怎么办？

UIContext 需要页面渲染完成后才可获取。建议在 onPageShow 或按钮点击回调中获取，而不是在 aboutToAppear 中。

Q2: ApplicationContext和UIAbilityContext有什么区别？

ApplicationContext 生命周期与应用一致，适合注册全局回调；UIAbilityContext 生命周期与Ability一致，适合Ability内的操作如路由跳转。

Q3: 能否在工具类中缓存上下文引用？

不建议缓存上下文引用，因为上下文可能因生命周期变化而失效。推荐通过 AppUtil 每次获取最新的上下文对象。

Q4: 多个Ability如何管理上下文？

每个Ability有独立的 UIAbilityContext，需要在各自的 onCreate 中调用 AppUtil.init() 初始化。

总结

AppUtil 的上下文获取方法为HarmonyOS开发者提供了便捷的上下文管理能力，无需手动传递Context参数。本文详细介绍了三种上下文类型的区别、获取方式、使用场景以及常见问题的解决方案。理解不同上下文的特性和适用场景，是构建健壮鸿蒙应用的基础。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。