OpenHarmony Ability Kit 快速参考

概述

Ability Kit 是 OpenHarmony Stage 模型中管理应用组件的核心框架。它提供:

• UIAbility: 带生命周期的 UI 应用组件
• AbilityStage: 模块级组件管理器,用于初始化
• Want: 组件间通信的数据载体
• Context: 应用/组件上下文,用于资源访问和操作
• ExtensionAbility: 扩展能力(Form、Service 等)
• BundleManager: 包和应用信息查询

官方文档: docs-OpenHarmony-v6.0-Release/zh-cn/application-dev/reference/apis-ability-kit/

决策流程

digraph ability_decision {
  "需要?" [shape=diamond];
  "创建 UI 应用" [shape=box];
  "后台任务" [shape=box];
  "跨应用通信" [shape=box];
  "查询应用信息" [shape=box];

  "使用 UIAbility" [shape=ellipse];
  "使用 ExtensionAbility" [shape=ellipse];
  "使用 Want + Context" [shape=ellipse];
  "使用 BundleManager" [shape=ellipse];

  "需要?" -> "创建 UI 应用" [label="UI"];
  "需要?" -> "后台任务" [label="后台"];
  "需要?" -> "跨应用通信" [label="通信"];
  "需要?" -> "查询应用信息" [label="信息"];

  "创建 UI 应用" -> "使用 UIAbility";
  "后台任务" -> "使用 ExtensionAbility";
  "跨应用通信" -> "使用 Want + Context";
  "查询应用信息" -> "使用 BundleManager";
}

快速参考表

| 模块 | API 版本 | 用途 | 导入语句 | |--------|-------------|---------|--------| | UIAbility | 9+ | UI 应用组件 | import { UIAbility } from '@kit.AbilityKit' | | AbilityStage | 9+ | 模块级管理器 | import { AbilityStage } from '@kit.AbilityKit' | | Want | 9+ | 组件通信 | import { Want } from '@kit.AbilityKit' | | common (Context) | 9+ | Context API | import { common } from '@kit.AbilityKit' | | bundleManager | 9+ | 包查询 | import { bundleManager } from '@kit.AbilityKit' | | wantAgent | 9+ | Want 封装 | import { wantAgent } from '@kit.AbilityKit' | | appManager | 9+ | 应用生命周期管理 | import { appManager } from '@kit.AbilityKit' | | AbilityConstant | 9+ | Ability 常量 | import { AbilityConstant } from '@kit.AbilityKit' | | Configuration | 9+ | 系统配置 | import { Configuration } from '@kit.AbilityKit' |

UIAbility 生命周期

生命周期状态

Create -> WindowStageCreate -> Foreground <-> Background -> WindowStageDestroy -> Destroy

关键回调

| 回调 | 调用时机 | 使用场景 | |----------|-------------|----------| | onCreate(want, launchParam) | Ability 创建时 | 初始化非 UI 资源 | | onWindowStageCreate(windowStage) | 窗口就绪时 | 加载 UI 内容,设置窗口属性 | | onForeground() | 进入前台时 | 恢复操作,刷新数据 | | onBackground() | 进入后台时 | 保存状态,释放资源 | | onWindowStageDestroy() | 窗口销毁时 | 清理窗口资源 | | onDestroy() | Ability 销毁时 | 最终清理 | | onNewWant(want, launchParam) | 重新激活(单例模式) | 处理新的意图 |

基础 UIAbility 模板

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

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'testTag', 'Ability onCreate');
    // 初始化非 UI 资源
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    hilog.info(0x0000, 'testTag', 'Ability onWindowStageCreate');

    // 加载主页面
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load content: %{public}s', JSON.stringify(err));
        return;
      }
      hilog.info(0x0000, 'testTag', 'Succeeded in loading content');
    });
  }

  onForeground(): void {
    hilog.info(0x0000, 'testTag', 'Ability onForeground');
  }

  onBackground(): void {
    hilog.info(0x0000, 'testTag', 'Ability onBackground');
  }

  onDestroy(): void {
    hilog.info(0x0000, 'testTag', 'Ability onDestroy');
  }
}

启动类型

| 类型 | 值 | 说明 | 使用场景 | |------|-------|-------------|----------| | SINGLETON | 0 | 单实例 | 主入口、设置页 | | MULTITON | 1 | 多实例 | 文档编辑器 | | SPECIFIED | 2 | 开发者控制 | 自定义实例管理 |

在 module.json5 中配置:

{
  "abilities": [{
    "name": "EntryAbility",
    "launchType": "singleton"
  }]
}

AbilityStage

模块级组件管理器,在模块中的任何 Ability 之前创建。

关键回调

| 回调 | 调用时机 | 使用场景 | |----------|-------------|----------| | onCreate() | 模块首次加载时 | 资源预加载、线程创建 | | onDestroy() | 最后一个 ability 退出时 (API 12+) | 模块清理 | | onAcceptWant(want) | 指定启动模式 | 返回唯一 ability 键 | | onConfigurationUpdate(config) | 系统配置变化时 | 处理语言/主题变化 | | onMemoryLevel(level) | 内存压力时 | 释放非必要资源 |

基础 AbilityStage 模板

import { AbilityStage, Want, Configuration, AbilityConstant } from '@kit.AbilityKit';

export default class MyAbilityStage extends AbilityStage {
  onCreate(): void {
    console.log('MyAbilityStage onCreate');
    // 模块初始化
  }

  onAcceptWant(want: Want): string {
    // 对于指定启动模式,返回唯一键
    if (want.abilityName === 'DocumentAbility') {
      return want.parameters?.docId as string || 'default';
    }
    return '';
  }

  onConfigurationUpdate(config: Configuration): void {
    console.log(`Config updated: ${JSON.stringify(config)}`);
  }

  onMemoryLevel(level: AbilityConstant.MemoryLevel): void {
    console.log(`Memory level: ${level}`);
    // 内存低时释放缓存
  }
}

Want 对象

组件通信的数据载体。

Want 结构

| 字段 | 类型 | 说明 | |-------|------|-------------| | bundleName | string | 目标包名 | | abilityName | string | 目标 ability 名称 | | moduleName | string | 目标模块名(可选) | | action | string | 要执行的操作 | | entities | string[] | 实体类别 | | uri | string | 数据 URI | | type | string | MIME 类型 | | parameters | Record<string, Object> | 自定义参数 | | flags | number | Want 标志 |

常用 Want 模式

显式启动(同一应用)

let want: Want = {
  bundleName: 'com.example.myapp',
  abilityName: 'SecondAbility',
  parameters: {
    key1: 'value1',
    key2: 123
  }
};
this.context.startAbility(want);

显式启动(跨应用) - API 11+ 限制

// API 11+ 要求第三方应用使用隐式启动
// 使用 openLink 代替:
this.context.openLink('https://example.com/path');

隐式启动

let want: Want = {
  action: 'ohos.want.action.viewData',
  entities: ['entity.system.browsable'],
  uri: 'https://example.com'
};
this.context.startAbility(want);

带结果启动

let want: Want = {
  bundleName: 'com.example.myapp',
  abilityName: 'SelectAbility'
};

this.context.startAbilityForResult(want).then((result) => {
  console.log(`Result code: ${result.resultCode}`);
  console.log(`Result data: ${JSON.stringify(result.want?.parameters)}`);
});

返回结果

// 在目标 ability 中
let resultWant: Want = {
  parameters: {
    selectedItem: 'item1'
  }
};
this.context.terminateSelfWithResult({
  resultCode: 0,
  want: resultWant
});

Want 标志

| 标志 | 值 | 说明 | |------|-------|-------------| | FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | 授予读取 URI 权限 | | FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | 授予写入 URI 权限 | | FLAG_INSTALL_ON_DEMAND | 0x00000800 | 按需安装 |

Context 层级

Context 类型

| Context | 作用域 | 关键 API | |---------|-------|----------| | ApplicationContext | 应用级 | on/off('abilityLifecycle'), killAllProcesses(), setColorMode() | | UIAbilityContext | UIAbility | startAbility(), terminateSelf(), requestPermissions() | | AbilityStageContext | AbilityStage | 模块级资源访问 | | ExtensionContext | ExtensionAbility | Extension 特定操作 |

获取 Context

在 UIAbility 中:

import { UIAbility, common } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onCreate(): void {
    // UIAbilityContext
    let uiAbilityContext: common.UIAbilityContext = this.context;

    // ApplicationContext
    let appContext: common.ApplicationContext = this.context.getApplicationContext();
  }
}

在组件(页面)中:

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

@Entry
@Component
struct Index {
  build() {
    Button('Start')
      .onClick(() => {
        let context = getContext(this) as common.UIAbilityContext;
        context.startAbility({ /* want */ });
      })
  }
}

UIAbilityContext 关键 API

| API | 说明 | |-----|-------------| | startAbility(want) | 启动另一个 ability | | startAbilityForResult(want) | 启动并获取结果 | | terminateSelf() | 关闭当前 ability | | terminateSelfWithResult(result) | 带结果关闭 | | connectServiceExtensionAbility(want, options) | 连接到服务 | | disconnectServiceExtensionAbility(connection) | 断开服务连接 | | requestPermissionsFromUser(permissions) | 请求权限 | | setMissionLabel(label) | 设置最近任务标签 | | setMissionIcon(icon) | 设置最近任务图标 |

ApplicationContext 关键 API

| API | 说明 | |-----|-------------| | on('abilityLifecycle', callback) | 监听 ability 生命周期 | | on('environment', callback) | 监听环境变化 | | on('applicationStateChange', callback) | 监听应用状态 | | getRunningProcessInformation() | 获取进程信息 | | killAllProcesses() | 强制退出所有进程 | | setColorMode(mode) | 设置深色/浅色模式 | | setLanguage(language) | 设置应用语言 | | restartApp(want) | 重启应用 (API 12+) |

生命周期监听示例

import { UIAbility, AbilityLifecycleCallback } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  private lifecycleId: number = -1;

  onCreate(): void {
    let callback: AbilityLifecycleCallback = {
      onAbilityCreate(ability) {
        console.log(`Ability created: ${ability.context.abilityInfo.name}`);
      },
      onAbilityForeground(ability) {
        console.log(`Ability foreground: ${ability.context.abilityInfo.name}`);
      },
      onAbilityBackground(ability) {
        console.log(`Ability background: ${ability.context.abilityInfo.name}`);
      },
      onAbilityDestroy(ability) {
        console.log(`Ability destroyed: ${ability.context.abilityInfo.name}`);
      },
      onWindowStageCreate(ability, windowStage) {},
      onWindowStageActive(ability, windowStage) {},
      onWindowStageInactive(ability, windowStage) {},
      onWindowStageDestroy(ability, windowStage) {},
      onAbilityContinue(ability) {}
    };

    let appContext = this.context.getApplicationContext();
    this.lifecycleId = appContext.on('abilityLifecycle', callback);
  }

  onDestroy(): void {
    let appContext = this.context.getApplicationContext();
    appContext.off('abilityLifecycle', this.lifecycleId);
  }
}

ExtensionAbility 类型

| 类型 | 值 | 说明 | 使用场景 | |------|-------|-------------|----------| | FORM | 0 | FormExtensionAbility | 卡片开发 | | WORK_SCHEDULER | 1 | WorkSchedulerExtensionAbility | 后台任务 | | INPUT_METHOD | 2 | InputMethodExtensionAbility | 输入法 | | ACCESSIBILITY | 4 | AccessibilityExtensionAbility | 辅助功能服务 | | BACKUP | 9 | BackupExtensionAbility | 数据备份/恢复 | | ENTERPRISE_ADMIN | 11 | EnterpriseAdminExtensionAbility | 企业设备管理 | | SHARE | 16 | ShareExtensionAbility | 分享功能 | | DRIVER | 18 | DriverExtensionAbility | 设备驱动 | | ACTION | 19 | ActionExtensionAbility | 自定义操作 | | EMBEDDED_UI | 21 | EmbeddedUIExtensionAbility | 跨进程 UI 嵌入 |

BundleManager

查询应用和包信息。

BundleFlags

| 标志 | 值 | 说明 | |------|-------|-------------| | GET_BUNDLE_INFO_DEFAULT | 0x00000000 | 仅默认信息 | | GET_BUNDLE_INFO_WITH_APPLICATION | 0x00000001 | 包含 applicationInfo | | GET_BUNDLE_INFO_WITH_HAP_MODULE | 0x00000002 | 包含 hapModuleInfo | | GET_BUNDLE_INFO_WITH_ABILITY | 0x00000004 | 包含 ability 信息(需 HAP_MODULE) | | GET_BUNDLE_INFO_WITH_EXTENSION_ABILITY | 0x00000008 | 包含 extension 信息(需 HAP_MODULE) | | GET_BUNDLE_INFO_WITH_REQUESTED_PERMISSION | 0x00000010 | 包含权限 | | GET_BUNDLE_INFO_WITH_METADATA | 0x00000020 | 包含元数据 | | GET_BUNDLE_INFO_WITH_SIGNATURE_INFO | 0x00000080 | 包含签名信息 |

常用操作

获取自身包信息

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

let bundleFlags = bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION |
                  bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_HAP_MODULE |
                  bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_ABILITY;

try {
  let bundleInfo = bundleManager.getBundleInfoForSelfSync(bundleFlags);
  console.log(`Bundle name: ${bundleInfo.name}`);
  console.log(`Version: ${bundleInfo.versionName}`);

  // 遍历 abilities
  bundleInfo.hapModulesInfo?.forEach((hapInfo) => {
    hapInfo.abilitiesInfo?.forEach((abilityInfo) => {
      console.log(`Ability: ${abilityInfo.name}`);
    });
  });
} catch (err) {
  console.error(`Failed: ${err.message}`);
}

获取配置文件

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

let moduleName = 'entry';
let abilityName = 'EntryAbility';
let metadataName = 'ability_metadata';

try {
  let profiles = bundleManager.getProfileByAbilitySync(moduleName, abilityName, metadataName);
  console.log(`Profile: ${JSON.stringify(profiles)}`);
} catch (err) {
  console.error(`Failed: ${err.message}`);
}

Caller/Callee (后台通信)

用于后台 ability 间通信。

Callee 端(接收)

import { UIAbility, Caller, Callee } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';

const MSG_SEND_METHOD: string = 'CallSendMsg';

class MyParcelable implements rpc.Parcelable {
  num: number = 0;
  str: string = '';

  marshalling(messageSequence: rpc.MessageSequence): boolean {
    messageSequence.writeInt(this.num);
    messageSequence.writeString(this.str);
    return true;
  }

  unmarshalling(messageSequence: rpc.MessageSequence): boolean {
    this.num = messageSequence.readInt();
    this.str = messageSequence.readString();
    return true;
  }
}

function sendMsgCallback(data: rpc.MessageSequence): rpc.Parcelable {
  let receivedData = new MyParcelable();
  data.readParcelable(receivedData);
  console.log(`Received: ${receivedData.str}`);

  // 返回结果
  let reply = new MyParcelable();
  reply.num = receivedData.num + 1;
  reply.str = 'reply';
  return reply;
}

export default class CalleeAbility extends UIAbility {
  onCreate(): void {
    this.callee.on(MSG_SEND_METHOD, sendMsgCallback);
  }

  onDestroy(): void {
    this.callee.off(MSG_SEND_METHOD);
  }
}

Caller 端(发送)

import { UIAbility, Caller, Want } from '@kit.AbilityKit';

export default class CallerAbility extends UIAbility {
  private caller: Caller | undefined;

  async callRemoteAbility(): Promise<void> {
    let want: Want = {
      bundleName: 'com.example.myapp',
      abilityName: 'CalleeAbility'
    };

    try {
      this.caller = await this.context.startAbilityByCall(want);

      let data = new MyParcelable();
      data.num = 1;
      data.str = 'hello';

      let reply = await this.caller.call('CallSendMsg', data);
      let result = new MyParcelable();
      reply.readParcelable(result);
      console.log(`Reply: ${result.str}`);
    } catch (err) {
      console.error(`Call failed: ${err.message}`);
    }
  }

  releaseCall(): void {
    if (this.caller) {
      this.caller.release();
      this.caller = undefined;
    }
  }
}

常见错误码

Ability 系统错误 (16000xxx)

| 错误码 | 消息 | 原因 | 解决方案 | |------|---------|-------|----------| | 16000001 | 指定的 ability 不存在 | Ability 未找到 | 检查 bundleName、moduleName、abilityName;确认应用已安装 | | 16000002 | Ability 类型不正确 | API 的 ability 类型错误 | 匹配 API 与 ability 类型 | | 16000004 | 无法启动不可见组件 | 目标 exported=false | 设置 exported=true 或请求 START_INVISIBLE_ABILITY 权限 | | 16000005 | 进程权限失败 | 权限不足 | 检查所需权限 | | 16000011 | Context 不存在 | Context 不可用 | 验证 context 有效性 | | 16000015 | 服务超时 | 请求超时 | 稍后重试 | | 16000018 | 禁止第三方重定向 | API 11+ 禁止显式启动 | 使用隐式启动或 openLink() | | 16000019 | 未找到匹配的 ability | 隐式启动无匹配 | 检查 action/entities/uri 配置 | | 16000050 | 内部错误 | 系统错误 | 检查日志,重试 | | 16000053 | Ability 未置顶 | restartApp 需要焦点 | 确保应用获得焦点 | | 16000063 | 重启目标无效 | 非同一应用或非 UIAbility | 检查重启目标 | | 16000064 | 重启过于频繁 | 重启间隔 < 3 秒 | 至少等待 3 秒 |

Bundle Manager 错误 (17700xxx)

| 错误码 | 消息 | 原因 | 解决方案 | |------|---------|-------|----------| | 17700001 | Bundle 未找到 | 应用未安装 | 验证安装 | | 17700002 | Module 未找到 | Module 未安装 | 检查 moduleName | | 17700003 | Ability 未找到 | Ability 不存在 | 检查 abilityName | | 17700024 | HAP 中无配置文件 | 缺少配置文件 | 将配置添加到 metadata | | 17700026 | 指定的 bundle 被禁用 | Bundle 被禁用 | 启用该 bundle | | 17700029 | Ability 被禁用 | Ability 被禁用 | 启用该 ability |

最佳实践

1. 使用正确的 Context

// 对于 UI 操作 - 使用 UIAbilityContext
let uiContext = this.context; // 在 UIAbility 中

// 对于应用级操作 - 使用 ApplicationContext
let appContext = this.context.getApplicationContext();

2. 正确处理生命周期

onForeground(): void {
  // 恢复:刷新数据、重新启动动画
}

onBackground(): void {
  // 暂停:保存状态、释放重量级资源
  // 不要依赖此方法进行关键保存
}

3. 对跨应用使用隐式启动 (API 11+)

// 不要这样做: 显式启动第三方应用
let want = { bundleName: 'com.other.app', abilityName: 'Main' };

// 应该这样做: 使用 openLink 或隐式启动
this.context.openLink('https://example.com');
// 或者
let want = { action: 'ohos.want.action.viewData', uri: 'https://...' };

4. 清理资源

onDestroy(): void {
  // 取消注册回调
  appContext.off('abilityLifecycle', this.lifecycleId);

  // 释放连接
  if (this.caller) {
    this.caller.release();
  }
}

5. 优雅地处理错误

try {
  await this.context.startAbility(want);
} catch (err) {
  if (err.code === 16000001) {
    console.error('Ability not found');
  } else if (err.code === 16000004) {
    console.error('Target is not exported');
  } else {
    console.error(`Error: ${err.code} - ${err.message}`);
  }
}

文档参考

| 主题 | 文件路径 | |-------|-----------| | UIAbility | js-apis-app-ability-uiAbility.md | | AbilityStage | js-apis-app-ability-abilityStage.md | | Want | js-apis-app-ability-want.md | | UIAbilityContext | js-apis-inner-application-uiAbilityContext.md | | ApplicationContext | js-apis-inner-application-applicationContext.md | | bundleManager | js-apis-bundleManager.md | | Ability 错误码 | errorcode-ability.md | | Bundle 错误码 | errorcode-bundle.md |