鸿蒙 6.0 Ability Kit 使用实战全解析

2026-05-05
北京
本文字数：11367 字
阅读完需：约 37 分钟

引言

Ability Kit 是鸿蒙操作系统（HarmonyOS）应用框架的核心组件，作为应用原子化服务的承载者，它定义了应用的呈现方式、交互逻辑和生命周期管理。在鸿蒙生态中，无论是简单的单页应用还是复杂的多设备协同系统，都离不开 Ability 组件的支撑。

从技术演进角度，鸿蒙应用模型经历了从 FA（Feature Ability）模型 到 Stage 模型 的重大升级。FA 模型诞生于鸿蒙早期阶段，采用等元化的组件设计，所有 Ability 共享同一套生命周期管理机制，缺乏对大型应用的多窗口、多任务场景的有效支持。Stage 模型则在鸿蒙 3.0 版本正式引入，通过将应用组件划分为 UIAbility 和 ExtensionAbility 两大类，配合 AbilityStage 组件容器层，实现了更精细的资源管控和更灵活的业务解耦。

鸿蒙 6.0 版本对 Ability Kit 进行了深度优化，引入了更高效的生命周期调度机制、增强的跨设备流转能力，以及对 HAR/HSP 模块化开发的原生支持。这些改进使得开发者能够构建更加复杂、更具韧性的分布式应用。

一、Ability Kit 核心架构体系

1.1 Stage 模型整体架构

Stage 模型采用了清晰的三层架构设计，从上到下依次为：应用层（Application）、组件容器层（AbilityStage）、组件层（UIAbility/ExtensionAbility）。这种分层设计遵循了关注点分离原则，使得应用的业务逻辑、界面呈现和运行容器得以有效隔离。

在编译期，每个 Module 对应一个 AbilityStage 实例，负责管理该模块下所有 Ability 的生命周期；到了运行期，系统会根据实际需要创建 UIAbility 或 ExtensionAbility 实例。这种编译期与运行期的对应关系，确保了资源的按需分配和高效利用。

Stage 模型的核心优势体现在三个方面：首先是多实例支持，同一 Ability 可以根据配置创建多个实例，适应多窗口场景；其次是资源管控增强，系统可以基于 Ability 的前台/后台状态进行精细化的 CPU 和内存调度；第三是模块化开发友好，通过 HAR 和 HSP 机制实现跨模块的代码和资源共享。

Stage 模型通过 Want 通信机制串联起生命周期、WindowStage、Context 等核心模块。左侧标注的"Stage 模型"链路清晰展示了从生命周期回调到窗口管理再到上下文获取的完整调用链；右侧的"Want 通信机制"则作为消息总线，实现组件间的双向数据传递。相比传统的 FA 模型（右侧虚线框所示），Stage 模型（右侧实线框所示）通过模块化拆分获得了更好的可维护性和扩展性。

1.2 核心概念解析

理解 Ability Kit 需要掌握几个核心概念，它们构成了整个框架的基石。

HAP/HAR/HSP 包类型对比如下表所示：

HAP 是应用的最终交付形式，分为 Entry（入口）和 Feature（特性）两种类型。HAR 用于封装可复用的业务代码或资源，被依赖时其 ArkTS 源码会编译到使用方的 bundle 中。HSP 则是鸿蒙 6.0 主推的动态共享方案，相比 HAR 能够在运行时按需加载，特别适合大型应用的模块化拆分。

Context 上下文体系是访问系统服务和资源的入口。在 Stage 模型中，Context 分为三个层级：

ApplicationContext：应用级别，提供应用生命周期和全局资源访问
AbilityStageContext：模块级别，管理单个 Module 的资源和配置
UIAbilityContext：组件级别，控制单个 Ability 的行为和状态

WindowStage 是 Ability 的窗口管理器，负责创建和管理 Ability 对应的窗口。每个 UIAbility 都有一个对应的 WindowStage 实例，通过它可以加载页面内容、设置窗口属性、获取屏幕信息等。

二、UIAbility 组件深度实践

2.1 UIAbility 生命周期详解

UIAbility 的生命周期由六个核心回调构成，它们共同定义了组件从创建到销毁的完整过程。

onCreate() → onWindowStageCreate() → onForeground()                                          ↓                                   onBackground()                                         ↓onWindowStageDestroy() → onDestroy()

复制代码

onCreate() 是组件创建的入口点，此时组件窗口尚未创建，适合执行非 UI 资源的初始化，如建立数据库连接、配置网络请求、加载全局状态等。onWindowStageCreate() 在窗口舞台创建后调用，此时可以通过 WindowStage 加载页面内容。onForeground() 和 onBackground() 分别对应组件进入前台和退到后台的时机，前者适合恢复被暂停的操作（如重启定时器、恢复播放），后者适合保存状态并释放非必要资源。

onWindowStageDestroy() 在窗口舞台销毁时调用，用于清理窗口相关的资源。onDestroy() 是组件销毁前的最后回调，应该在此完成所有资源的最终释放，如关闭数据库连接、断开网络请求等。

2.2 完整可执行代码示例

以下是一个完整的 EntryAbility 实现，展示了每个生命周期回调的标准用法：

// EntryAbility.ets - 入口Ability完整实现import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';import { window } from '@kit.ArkUI';import { hilog } from '@kit.PerformanceAnalysisKit';
// 定义日志域和标签const TAG = 'EntryAbility';const DOMAIN = 0x0001;
export default class EntryAbility extends UIAbility {  /**   * 组件创建时调用 - 执行非UI资源的初始化   * 适合操作：数据库连接、网络配置、全局状态加载   */  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {    hilog.info(DOMAIN, TAG, 'onCreate called, want: %{public}s', JSON.stringify(want));        // 根据启动来源调整行为    if (launchParam.launchReason === AbilityConstant.LaunchReason.APP_START) {      hilog.info(DOMAIN, TAG, '应用冷启动');    } else if (launchParam.launchReason === AbilityConstant.LaunchReason.COLD_START) {      hilog.info(DOMAIN, TAG, '组件冷启动');    }        // 初始化数据库连接    this.initDatabase();  }
  /**   * 窗口舞台创建时调用 - 加载页面内容   * 这是UI初始化的主要入口   */  onWindowStageCreate(windowStage: window.WindowStage): void {    hilog.info(DOMAIN, TAG, 'onWindowStageCreate called');        // 设置窗口属性    windowStage.getMainWindow().then((win) => {      // 设置为沉浸式体验      win.setWindowLayoutFullScreen(true);    });        // 加载主页面 - 支持回调和Promise两种方式    windowStage.loadContent('pages/Index', (err, data) => {      if (err.code) {        hilog.error(DOMAIN, TAG, '页面加载失败: %{public}s', JSON.stringify(err));        return;      }      hilog.info(DOMAIN, TAG, '页面加载成功');    });  }
  /**   * 组件进入前台时调用 - 恢复前台操作   * 适合操作：刷新数据、重启动画、恢复播放   */  onForeground(): void {    hilog.info(DOMAIN, TAG, 'onForeground - 恢复前台操作');        // 通知页面刷新最新数据    AppStorage.setOrCreate('appState', 'foreground');  }
  /**   * 组件退到后台时调用 - 保存状态释放资源   * 适合操作：保存草稿、暂停动画、释放临时资源   */  onBackground(): void {    hilog.info(DOMAIN, TAG, 'onBackground - 进入后台');        // 标记应用状态    AppStorage.setOrCreate('appState', 'background');  }
  /**   * 窗口舞台销毁时调用 - 清理窗口资源   */  onWindowStageDestroy(): void {    hilog.info(DOMAIN, TAG, 'onWindowStageDestroy - 清理窗口');        // 清理定时器、动画等窗口相关资源  }
  /**   * 组件销毁时调用 - 执行最终清理   * 适合操作：关闭数据库、断开连接、保存持久化数据   */  onDestroy(): void {    hilog.info(DOMAIN, TAG, 'onDestroy - 执行最终清理');        // 关闭数据库连接    this.closeDatabase();  }
  /**   * 接收新Want时调用 - 处理多实例场景   */  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {    hilog.info(DOMAIN, TAG, 'onNewWant called');        // 多实例模式下重新初始化    if (launchParam.launchReason === AbilityConstant.LaunchReason.START_ABILITY) {      // 处理新的启动请求    }  }
  // 私有方法示例  private initDatabase(): void {    hilog.info(DOMAIN, TAG, '初始化数据库连接');  }
  private closeDatabase(): void {    hilog.info(DOMAIN, TAG, '关闭数据库连接');  }}

复制代码

2.3 启动模式与配置

UIAbility 支持三种启动模式，通过 module.json5 中的 launchType 字段配置：

module.json5 中 UIAbility 的完整配置示例：

{  "abilities": [    {      "name": "EntryAbility",      "srcEntry": "./ets/entryability/EntryAbility.ets",      "description": "$string:entryability_desc",      "icon": "$media:icon",      "label": "$string:entryability_label",      "startWindowIcon": "$media:icon",      "startWindowBackground": "$color:start_window_background",      "exported": true,      "launchType": "singleton",      "skills": [        {          "entities": ["entity.system.home"],          "actions": ["action.system.home"]        }      ]    }  ]}

复制代码

三、Context 上下文与组件交互

3.1 Context 层级体系

Context 是访问 HarmonyOS 系统能力的中枢，不同层级的 Context 提供了不同的访问权限和作用域。

ApplicationContext 作用于整个应用，提供应用级别的配置信息和全局资源访问。通过 applicationContext 可以注册应用生命周期监听、设置应用级别属性。

AbilityStageContext 作用于单个 Module，是模块级别资源的入口。当需要访问当前模块特有的配置或资源时使用。

UIAbilityContext 作用于单个 Ability 实例，是最常用的 Context 类型。通过它可以启动其他 Ability、获取 Ability 信息、操作当前窗口等。

层级关系遵循包含原则：UIAbilityContext ⊂ AbilityStageContext ⊂ ApplicationContext。子层级可以访问父层级的所有能力，同时拥有父层级不具备的组件特定能力。

3.2 页面获取 Context 并启动 Ability

以下示例展示了在 ArkUI 页面中获取 Context 并执行各种操作：

// ContextDemo.ets - Context使用完整示例import { common, Want } from '@kit.AbilityKit';import { BusinessError } from '@kit.BasicServicesKit';import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG = 'ContextDemo';const DOMAIN = 0x0002;
@Entry@Componentstruct ContextDemo {  // 获取当前Ability的Context  private abilityContext = getContext(this) as common.UIAbilityContext;    // 启动目标Ability  async startTargetAbility(): Promise<void> {    hilog.info(DOMAIN, TAG, '启动目标Ability');        // 构建Want - 显式启动    let want: Want = {      bundleName: this.abilityContext.abilityInfo.bundleName,      abilityName: 'TargetAbility',      moduleName: this.abilityContext.abilityInfo.moduleName,      parameters: {        message: '来自Ability Kit的问候',        timestamp: Date.now(),        userData: {          name: 'HarmonyOS',          version: '6.0'        }      }    };        try {      // 带回调的启动方式      this.abilityContext.startAbility(want, (err: BusinessError) => {        if (err.code) {          hilog.error(DOMAIN, TAG, '启动失败: %{public}s', err.message);          return;        }        hilog.info(DOMAIN, TAG, 'TargetAbility启动成功');      });    } catch (err) {      let error = err as BusinessError;      hilog.error(DOMAIN, TAG, '启动异常: %{public}d %{public}s', error.code, error.message);    }  }    // 隐式启动 - 通过skills匹配  async startByImplicitWant(): Promise<void> {    let want: Want = {      action: 'ohos.want.action.viewData',      entities: ['entity.system.browser'],      uri: 'https://www.example.com'    };        try {      await this.abilityContext.startAbility(want);    } catch (err) {      let error = err as BusinessError;      hilog.error(DOMAIN, TAG, '隐式启动失败: %{public}d', error.code);    }  }    // 获取Ability结果（startAbilityForResult）  async startForResult(): Promise<void> {    let want: Want = {      bundleName: 'com.example.target',      abilityName: 'ResultAbility',      parameters: {        requestCode: 'SELECT_IMAGE'      }    };        this.abilityContext.startAbilityForResult(want).then((result) => {      if (result.resultCode === 0) {        hilog.info(DOMAIN, TAG, '获取结果: %{public}s', JSON.stringify(result.want?.parameters));      }    }).catch((err: BusinessError) => {      hilog.error(DOMAIN, TAG, '获取结果失败: %{public}s', err.message);    });  }    // 终止当前Ability  terminateCurrent(): void {    hilog.info(DOMAIN, TAG, '终止当前Ability');    this.abilityContext.terminateSelf();  }    // 携带结果终止  terminateWithResult(): void {    let want: Want = {      parameters: {        result: '操作完成',        success: true      }    };    this.abilityContext.terminateSelfWithResult(want);  }    // 获取应用级Context  getAppContext(): void {    let appContext = this.abilityContext.getApplicationContext();    hilog.info(DOMAIN, TAG, '应用ID: %{public}s', appContext.info.bundleName);  }    build() {    Column({ space: 16 }) {      Text('Context 操作演示')        .fontSize(24)        .fontWeight(FontWeight.Bold)        .width('100%')        .textAlign(TextAlign.Center);            Divider().color('#E0E0E0');            Column({ space: 12 }) {        Text('启动Ability').fontSize(16).fontWeight(FontWeight.Medium).width('100%');                Button('显式启动目标Ability')          .width('100%')          .height(48)          .onClick(() => this.startTargetAbility());                Button('隐式启动浏览器')          .width('100%')          .height(48)          .onClick(() => this.startByImplicitWant());                Button('启动并获取结果')          .width('100%')          .height(48)          .type(ButtonType.Normal)          .onClick(() => this.startForResult());      }            Divider().color('#E0E0E0').margin({ top: 16, bottom: 16 });            Column({ space: 12 }) {        Text('终止操作').fontSize(16).fontWeight(FontWeight.Medium).width('100%');                Button('终止当前Ability')          .width('100%')          .height(48)          .backgroundColor(Color.Red)          .onClick(() => this.terminateCurrent());                Button('携带结果终止')          .width('100%')          .height(48)          .backgroundColor(Color.Orange)          .onClick(() => this.terminateWithResult());      }            Divider().color('#E0E0E0').margin({ top: 16, bottom: 16 });            Button('获取应用Context')        .width('100%')        .height(48)        .type(ButtonType.Normal)        .onClick(() => this.getAppContext());          }    .padding(20)    .width('100%')    .height('100%');  }}

复制代码

四、Want 通信机制详解

4.1 Want 的核心作用

Want 是 HarmonyOS 组件间通信的核心载体，它定义了启动目标的信息集合。一个完整的 Want 通常包含以下关键字段：

bundleName：目标应用包名
abilityName：目标 Ability 名称
moduleName：目标 Module 名称
uri：资源定位符（用于隐式启动）
action：意图动作
entities：实体类型列表
parameters：自定义参数

Want 分为显式 Want 和隐式 Want 两种类型。显式 Want 明确指定目标组件的包名和能力名，适用于已知目标场景；隐式 Want 则通过 action、entities、uri 等条件让系统自动匹配合适的组件，适用于跨应用调用或灵活分发场景。

4.2 Want 完整数据结构与实战

// Want使用完整示例 - WantStructDemo.etsimport { Want, common } from '@kit.AbilityKit';import { BusinessError } from '@kit.BasicServicesKit';
@Entry@Componentstruct WantStructDemo {  private context = getContext(this) as common.UIAbilityContext;
  /**   * 显式Want - 直接指定目标组件   * 适用于：应用内部跳转、已知目标场景   */  startExplicitAbility(): void {    const want: Want = {      bundleName: 'com.example.myapp',      abilityName: 'DetailAbility',      moduleName: 'entry', // 可选，指定module      parameters: {        // 传递业务数据        id: '12345',        type: 'product',        from: 'list'      }    };        this.context.startAbility(want)      .then(() => console.info('显式启动成功'))      .catch((err: BusinessError) => console.error(`启动失败: ${err.code}`));  }
  /**   * 隐式Want - 通过能力描述启动   * 适用于：分享、打开链接、选择器等场景   */  startImplicitAbility(): void {    const want: Want = {      action: 'ohos.want.action.viewData', // 系统预置动作      entities: ['entity.system.browsable'], // 可浏览实体      uri: 'https://www.harmonyos.com',      type: 'text/plain',      parameters: {        key: 'customValue'      }    };        this.context.startAbility(want)      .then(() => console.info('隐式启动成功'))      .catch((err: BusinessError) => console.error(`隐式启动失败: ${err.code}`));  }
  /**   *Want 参数传递与接收   * 发送方：通过parameters传递数据   * 接收方：在onCreate的want中获取   */    build() {    Column({ space: 20 }) {      Text('Want 通信机制演示')        .fontSize(20).fontWeight(FontWeight.Bold);            Button('显式启动').onClick(() => this.startExplicitAbility());      Button('隐式启动').onClick(() => this.startImplicitAbility());    }    .padding(20);  }}

复制代码

五、ExtensionAbility 扩展能力

5.1 ServiceExtensionAbility 后台服务

ServiceExtensionAbility 用于实现后台计算服务，支持长时间运行的后台任务和跨进程通信。

// MyServiceExtensionAbility.ets - 后台服务Abilityimport { ServiceExtensionAbility, Want, AbilityConstant } from '@kit.AbilityKit';import { rpc } from '@kit.IPCKit';import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG = 'MyServiceExtension';const DOMAIN = 0x0003;
class MyRemoteStub extends rpc.RemoteStub {  // 处理客户端请求  onRemoteRequest(code: number, data: rpc.MessageParcel): boolean {    hilog.info(DOMAIN, TAG, '收到请求: code=%{public}d', code);        switch (code) {      case 1: // 获取数据        let response = data.readString();        hilog.info(DOMAIN, TAG, '客户端数据: %{public}s', response);        break;      default:        return false;    }    return true;  }}
export default class MyServiceExtensionAbility extends ServiceExtensionAbility {  private remote: rpc.RemoteObject | null = null;
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {    hilog.info(DOMAIN, TAG, 'Service onCreate');        // 创建RPC对象用于跨进程通信    this.remote = new MyRemoteStub('service');  }
  onConnect(want: Want): rpc.RemoteObject {    hilog.info(DOMAIN, TAG, 'Service onConnect');    return this.remote!;  }
  onDisconnect(want: Want): void {    hilog.info(DOMAIN, TAG, 'Service onDisconnect');    this.remote = null;  }
  onDestroy(): void {    hilog.info(DOMAIN, TAG, 'Service onDestroy');  }}

复制代码

5.2 常用 ExtensionAbility 类型

六、跨设备流转能力

6.1 分布式能力核心

鸿蒙 6.0 的分布式能力使得应用可以在多个设备间无缝流转。跨端迁移允许将正在进行的任务从一个设备转移到另一个设备继续执行；多端协同则支持多个设备同时参与同一任务的不同环节。

实现跨设备流转的关键在于配置 Want 的分布式参数：

// 跨设备启动AbilitystartRemoteAbility(): void {  let want: Want = {    bundleName: 'com.example.myapp',    abilityName: 'RemoteAbility',    // 分布式参数    deviceId: 'remote_device_id', // 目标设备ID    parameters: {      // 指定迁移的页面状态      pageData: JSON.stringify(this.getCurrentState())    }  };    this.context.startAbility(want)    .then(() => console.info('跨设备启动成功'));}
// 接收迁移数据onRestoreWindowStage(windowStage: window.WindowStage): void {  // 获取迁移时传递的数据  let pageData = this.context.want?.parameters?.pageData;  if (pageData) {    let state = JSON.parse(pageData as string);    // 恢复页面状态    this.restoreState(state);  }}

复制代码

七、实战项目：多 Ability 协作应用

7.1 项目架构设计

以下是一个支持多 Ability 协作的新闻阅读应用架构示例：

com.example.newsapp/├── entry/                    # 主模块│   ├── EntryAbility.ets      # 主入口Ability│   └── pages/│       ├── Index.ets         # 新闻列表页│       └── Settings.ets      # 设置页├── feature/                  # 特性模块│   └── FeatureAbility.ets    # 新闻详情Ability└── service/                  # 服务模块    └── NewsServiceExtension   # 数据服务

复制代码

7.2 完整实现代码

// NewsListAbility.ets - 新闻列表Abilityimport { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit';import { window } from '@kit.ArkUI';import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG = 'NewsListAbility';const DOMAIN = 0x0004;
export default class NewsListAbility extends UIAbility {  private storage: LocalStorage | null = null;
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {    hilog.info(DOMAIN, TAG, 'NewsListAbility onCreate');    this.storage = new LocalStorage();        // 设置模拟数据    this.storage.setOrCreate('newsList', [      { id: '1', title: '鸿蒙6.0正式发布', summary: '全新特性一览', time: '2024-01-01' },      { id: '2', title: 'Ability Kit新特性', summary: '开发实战指南', time: '2024-01-02' },      { id: '3', title: '分布式能力增强', summary: '跨设备协同', time: '2024-01-03' }    ]);  }
  onWindowStageCreate(windowStage: window.WindowStage): void {    hilog.info(DOMAIN, TAG, '加载新闻列表页面');    windowStage.setUIContent(this.context, 'pages/NewsList', this.storage);  }
  onDestroy(): void {    hilog.info(DOMAIN, TAG, 'NewsListAbility onDestroy');    this.storage = null;  }}
// pages/NewsList.ets - 新闻列表页面import { common } from '@kit.AbilityKit';
interface NewsItem {  id: string;  title: string;  summary: string;  time: string;}
@Entry@Componentstruct NewsList {  @LocalStorageProp('newsList') newsList: NewsItem[] = [];  private context = getContext(this) as common.UIAbilityContext;
  openDetail(news: NewsItem): void {    // 启动详情Ability    let want: Want = {      bundleName: this.context.abilityInfo.bundleName,      abilityName: 'NewsDetailAbility',      parameters: {        newsId: news.id,        title: news.title      }    };        this.context.startAbility(want);  }
  build() {    Column() {      Text('新闻列表')        .fontSize(24).fontWeight(FontWeight.Bold)        .width('100%').padding(16);            List() {        ForEach(this.newsList, (news: NewsItem) => {          ListItem() {            Column({ space: 8 }) {              Text(news.title)                .fontSize(18).fontWeight(FontWeight.Medium);              Text(news.summary)                .fontSize(14).fontColor('#666666');              Text(news.time)                .fontSize(12).fontColor('#999999');            }            .width('100%')            .padding(16)            .onClick(() => this.openDetail(news));          }          .border({ width: 1, color: '#EEEEEE', radius: 8 })          .margin({ bottom: 12 });        });      }      .padding(16);    }  }}
// NewsDetailAbility.ets - 新闻详情Abilityimport { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit';import { window } from '@kit.ArkUI';import { hilog } from '@kit.PerformanceAnalysisKit';
export default class NewsDetailAbility extends UIAbility {  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {    hilog.info(0x0005, 'Detail', '接收参数: %{public}s', JSON.stringify(want.parameters));  }
  onWindowStageCreate(windowStage: window.WindowStage): void {    // 通过want传递的数据恢复页面    let newsId = this.context.want?.parameters?.newsId || '';    windowStage.loadContent('pages/NewsDetail', (err) => {      if (!err.code) {        hilog.info(0x0005, 'Detail', '详情页加载成功');      }    });  }}

复制代码

八、最佳实践与常见问题

8.1 性能优化建议

生命周期资源管理的最佳实践：

onCreate 中避免耗时操作：窗口创建前的操作会阻塞 UI 显示
区分临时资源和持久资源：临时资源在 onBackground 释放，持久资源在 onDestroy 释放
使用 AppStorage 共享数据：避免在页面间传递大量数据
及时注销监听器：在 onDestroy 中清理所有定时器和事件监听

避免内存泄漏要点：

// 错误示例 - 未清理定时器onForeground(): void {  this.timer = setInterval(() => { /* 操作 */ }, 1000);}
// 正确示例 - 在对应生命周期清理onBackground(): void {  if (this.timer) {    clearInterval(this.timer);    this.timer = null;  }}