openharmony-ability-kit（openharmony 能力套件）

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";
}

快速参考表

UIAbility 生命周期

生命周期状态

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

关键回调

基础 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');
  }
}

启动类型

在 module.json5 中配置:

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

AbilityStage

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

关键回调

基础 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 结构

常用 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 标志

Context 层级

Context 类型

获取 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

ApplicationContext 关键 API

生命周期监听示例

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 类型

BundleManager

查询应用和包信息。

BundleFlags

常用操作

获取自身包信息

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)

Bundle Manager 错误 (17700xxx)

最佳实践

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}`);
  }
}

文档参考