HarmonyOS实战开发：FormExtensionContext

FormExtensionContext模块是FormExtensionAbility的上下文环境，继承自ExtensionContext。

FormExtensionContext模块提供FormExtensionAbility具有的接口和能力。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 本模块接口仅可在Stage模型下使用。

导入模块

import common from '@ohos.app.ability.common';

FormExtensionContext.startAbility

startAbility(want: Want, callback: AsyncCallback<void>): void

拉起一个卡片所属应用的Ability。使用callback异步回调。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Ability.Form

错误码：

错误码ID	错误信息
202	The application is not a system application.
401	If the input parameter is not valid parameter.
16500050	An IPC connection error happened.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

以上错误码的详细介绍请参见卡片错误码。

参数：

参数名	类型	必填	说明
want	Want	是	包含bundleName，abilityName以及用户自定参数用于拉起Ability。
callback	AsyncCallback<void>	是	回调函数。当拉起一个卡片所属应用的Ability成功，err为undefined，否则为错误对象。

示例：

import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
import Want from '@ohos.app.ability.Want';
import Base from '@ohos.base';

export default class MyFormExtensionAbility extends FormExtensionAbility {
  onFormEvent(formId: string, message: string) {
    // 当触发卡片message事件时，执行startAbility
    console.log(`FormExtensionAbility onFormEvent, formId: ${formId}, message:${message}`);
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.formstartability',
      abilityName: 'EntryAbility',
      parameters: {
        'message': message
      }
    };
    this.context.startAbility(want, (error: Base.BusinessError) => {
      if (error) {
        console.error(`FormExtensionContext startAbility, error:${JSON.stringify(error)}`);
      } else {
        console.log('FormExtensionContext startAbility success');
      }
    });
  }
};

FormExtensionContext.startAbility

startAbility(want: Want): Promise<void>

拉起一个卡片所属应用的Ability。使用Promise异步回调。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
want	Want	是	包含bundleName，abilityName以及用户自定参数用于拉起Ability。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

错误码ID	错误信息
202	The application is not a system application.
401	If the input parameter is not valid parameter.
16500050	An IPC connection error happened.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

以上错误码的详细介绍请参见卡片错误码。

示例：

import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
import Want from '@ohos.app.ability.Want';
import Base from '@ohos.base';

export default class MyFormExtensionAbility extends FormExtensionAbility {
  onFormEvent(formId: string, message: string) {
    // 当触发卡片message事件时，执行startAbility
    console.log(`FormExtensionAbility onFormEvent, formId:${formId}, message:${message}`);
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.formstartability',
      abilityName: 'EntryAbility',
      parameters: {
        'message': message
      }
    };
    this.context.startAbility(want).then(() => {
      console.info('StartAbility Success');
    }).catch((error: Base.BusinessError) => {
      console.error('StartAbility failed, error.code: ${error.code}, error.message: ${error.message}');
    });
  }
};

FormExtensionContext.connectServiceExtensionAbility10+

connectServiceExtensionAbility(want: Want, options: ConnectOptions): number

将一个Ability与服务类型的Ability绑定。

系统能力：SystemCapability.Ability.Form

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名	类型	必填	说明
want	Want	是	Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。
options	ConnectOptions	是	ConnectOptions类型的回调函数，返回服务连接成功、断开或连接失败后的信息。

返回值：

类型	说明
number	返回一个connectId，后续根据此connectId断开连接。

错误码：

错误码ID	错误信息
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Can not start invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000011	The context does not exist.
16000050	Internal error.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
import Want from '@ohos.app.ability.Want';
import rpc from '@ohos.rpc';
import Base from '@ohos.base';

let commRemote: rpc.IRemoteObject | null = null;
export default class MyFormExtensionAbility extends FormExtensionAbility {
  onFormEvent(formId: string, message: string) {
    // 当触发卡片message事件时，执行connectServiceExtensionAbility
    console.log(`FormExtensionAbility onFormEvent, formId:${formId}, message:${message}`);
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.formstartability',
      abilityName: 'EntryAbility',
      parameters: {
        'message': message
      }
    };
    let options: common.ConnectOptions = {
      onConnect(elementName, remote) { 
        commRemote = remote; // remote 用于与ServiceExtensionAbility进行通信
        console.log('----------- onConnect -----------'); 
      },
      onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
      onFailed(code) { console.error('----------- onFailed -----------') }
    };

    let connection: number | null = null;
    try {
      connection = this.context.connectServiceExtensionAbility(want, options);
    } catch (paramError) {
      // 处理入参错误异常
      console.error(`error.code: ${(paramError as Base.BusinessError).code}, error.message: ${(paramError as Base.BusinessError).message}`);
    }
  }
};

FormExtensionContext.disconnectServiceExtensionAbility10+

disconnectServiceExtensionAbility(connection: number, callback: AsyncCallback<void>): void

将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空。

系统能力：SystemCapability.Ability.Form

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名	类型	必填	说明
connection	number	是	在connectServiceExtensionAbility中返回的number。
callback	AsyncCallback<void>	是	回调函数，返回接口调用是否成功的结果。

错误码：

错误码ID	错误信息
16000011	The context does not exist.
16000050	Internal error.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
import rpc from '@ohos.rpc';
import common from '@ohos.app.ability.common';
import Base from '@ohos.base';

// commRemote为onConnect回调内返回的remote对象，此处定义为null无任何实际意义，仅作示例
let commRemote: rpc.IRemoteObject | null = null;
export default class MyFormExtensionAbility extends FormExtensionAbility {
  onFormEvent(formId: string, message: string) {
    // 实际使用时，connection为connectServiceExtensionAbility中的返回值，此处定义为1无任何实际意义，仅作示例
    let connection: number = 1;

    try {
      this.context.disconnectServiceExtensionAbility(connection, (error: Base.BusinessError) => {
        commRemote = null;
        if (error.code) {
          // 处理业务逻辑错误
          console.error(`disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
          return;
        }
        // 执行正常业务
        console.log('disconnectServiceExtensionAbility succeed');
      });
    } catch (paramError) {
      commRemote = null;
      // 处理入参错误异常
      console.error(`error.code: ${(paramError as Base.BusinessError).code}, error.message: ${(paramError as Base.BusinessError).message}`);
    }
  }
};

FormExtensionContext.disconnectServiceExtensionAbility10+

disconnectServiceExtensionAbility(connection: number): Promise<void>

将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空(Promise形式返回结果)。

系统能力：SystemCapability.Ability.Form

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名	类型	必填	说明
connection	number	是	在connectServiceExtensionAbility中返回的number。

返回值：

类型	说明
Promise<void>	返回一个Promise，包含接口的结果。

错误码：

错误码ID	错误信息
16000011	The context does not exist.
16000050	Internal error.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
import rpc from '@ohos.rpc';
import common from '@ohos.app.ability.common';
import Base from '@ohos.base';

// commRemote为onConnect回调内返回的remote对象，此处定义为null无任何实际意义，仅作示例
let commRemote: rpc.IRemoteObject | null = null;
export default class MyFormExtensionAbility extends FormExtensionAbility {
  onFormEvent(formId: string, message: string) {
    // 实际使用时，connection为connectServiceExtensionAbility中的返回值，此处定义为1无任何实际意义，仅作示例
    let connection: number = 1;

    try {
      this.context.disconnectServiceExtensionAbility(connection)
        .then(() => {
          commRemote = null;
          // 执行正常业务
          console.log('disconnectServiceExtensionAbility succeed');
        })
        .catch((error: Base.BusinessError) => {
          commRemote = null;
          // 处理业务逻辑错误
          console.error(`disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
        });
    } catch (paramError) {
      commRemote = null;
      // 处理入参错误异常
      console.error(`error.code: ${(paramError as Base.BusinessError).code}, error.message: ${(paramError as Base.BusinessError).message}`);
    }
  }
};

最后

有很多小伙伴不知道学习哪些鸿蒙开发技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？而且学习时频繁踩坑，最终浪费大量时间。所以有一份实用的鸿蒙（HarmonyOS NEXT）资料用来跟着学习是非常有必要的。 

这份鸿蒙（HarmonyOS NEXT）资料包含了鸿蒙开发必掌握的核心知识要点，内容包含了（ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、Harmony南向开发、鸿蒙项目实战等等）鸿蒙（HarmonyOS NEXT）技术知识点。

希望这一份鸿蒙学习资料能够给大家带来帮助，有需要的小伙伴自行领取，限时开源，先到先得~无套路领取！！

获取这份完整版高清学习路线，请点击→纯血版全套鸿蒙HarmonyOS学习资料

鸿蒙（HarmonyOS NEXT）最新学习路线

•  HarmonOS基础技能

• HarmonOS就业必备技能 
•  HarmonOS多媒体技术

• 鸿蒙NaPi组件进阶

• HarmonOS高级技能

• 初识HarmonOS内核 
• 实战就业级设备开发

有了路线图，怎么能没有学习资料呢，小编也准备了一份联合鸿蒙官方发布笔记整理收纳的一套系统性的鸿蒙（OpenHarmony ）学习手册（共计1236页）与鸿蒙（OpenHarmony ）开发入门教学视频，内容包含：ArkTS、ArkUI、Web开发、应用模型、资源分类…等知识点。

获取以上完整版高清学习路线，请点击→纯血版全套鸿蒙HarmonyOS学习资料

《鸿蒙 (OpenHarmony)开发入门教学视频》

《鸿蒙生态应用开发V2.0白皮书》

《鸿蒙 (OpenHarmony)开发基础到实战手册》

OpenHarmony北向、南向开发环境搭建

 《鸿蒙开发基础》

• ArkTS语言
• 安装DevEco Studio
• 运用你的第一个ArkTS应用
• ArkUI声明式UI开发
• .……

 《鸿蒙开发进阶》

• Stage模型入门
• 网络管理
• 数据管理
• 电话服务
• 分布式应用开发
• 通知与窗口管理
• 多媒体技术
• 安全技能
• 任务管理
• WebGL
• 国际化开发
• 应用测试
• DFX面向未来设计
• 鸿蒙系统移植和裁剪定制
• ……

《鸿蒙进阶实战》

• ArkTS实践
• UIAbility应用
• 网络案例
• ……

 获取以上完整鸿蒙HarmonyOS学习资料，请点击→纯血版全套鸿蒙HarmonyOS学习资料

总结

总的来说，华为鸿蒙不再兼容安卓，对中年程序员来说是一个挑战，也是一个机会。只有积极应对变化，不断学习和提升自己，他们才能在这个变革的时代中立于不败之地。