openharmony 鸿蒙 js-apis-inner-application-formExtensionContext-sys

2025-06-12 浏览 (1)

FormExtensionContext (系统接口)

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

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

说明：

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

导入模块

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

FormExtensionContext.startAbility

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

拉起一个应用的Ability。使用callback异步回调。

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

系统能力： SystemCapability.Ability.Form

错误码：

以下错误码的详细介绍请参见通用错误码和卡片错误码。

错误码ID错误信息
202The application is not a system application.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050IPC connection error.
16500100Failed to obtain the configuration information.
16501000An internal functional error occurred.

参数：

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

示例：

import { FormExtensionAbility } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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: 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

参数：

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

返回值：

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

错误码：

以下错误码的详细介绍请参见通用错误码和卡片错误码。

错误码ID错误信息
202The application is not a system application.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050IPC connection error.
16500100Failed to obtain the configuration information.
16501000An internal functional error occurred.

示例：

import { FormExtensionAbility } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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: 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

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

参数：

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

返回值：

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

错误码：

以下错误码的详细介绍请参见通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permissions denied.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Cannot start an invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16000011The context does not exist.
16000050Internal error.

示例：

import { rpc } from '@kit.IPCKit';
import { FormExtensionAbility } from '@kit.FormKit';
import { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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 BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
};

FormExtensionContext.disconnectServiceExtensionAbility10+

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

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

系统能力： SystemCapability.Ability.Form

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

参数：

参数名类型必填说明
connectionnumber是在connectServiceExtensionAbility中返回的number。
callbackAsyncCallback<void>是回调函数。当Ability与绑定的服务类型的Ability解绑成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码和元能力子系统错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16000011The context does not exist.
16000050Internal error.

示例：

import { FormExtensionAbility } from '@kit.FormKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 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: 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 BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
};

FormExtensionContext.disconnectServiceExtensionAbility10+

disconnectServiceExtensionAbility(connection: number): Promise<void>

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

系统能力： SystemCapability.Ability.Form

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

参数：

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

返回值：

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

错误码：

以下错误码的详细介绍请参见通用错误码和元能力子系统错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16000011The context does not exist.
16000050Internal error.

示例：

import { FormExtensionAbility } from '@kit.FormKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 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: 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 BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
};

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Form Kit（卡片开发服务）

harmony 鸿蒙卡片错误码

harmony 鸿蒙@ohos.app.form.LiveFormExtensionAbility (LiveFormExtensionAbility)

harmony 鸿蒙@ohos.app.form.formAgent (FormAgent)(系统接口)

harmony 鸿蒙@ohos.app.form.formBindingData (卡片数据绑定类)

harmony 鸿蒙@ohos.app.form.FormEditExtensionAbility (FormEditExtensionAbility)

harmony 鸿蒙@ohos.app.form.FormExtensionAbility (FormExtensionAbility)(系统接口)

harmony 鸿蒙@ohos.app.form.FormExtensionAbility (FormExtensionAbility)

harmony 鸿蒙@ohos.app.form.formHost (formHost)(系统接口)

harmony 鸿蒙@ohos.app.form.formInfo (formInfo)(系统接口)

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/D98nKl