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

formHost模块提供了卡片使用方相关接口的能力，包括对使用方同一用户下安装的卡片进行删除、释放、请求更新、获取卡片信息、状态等操作。

说明：

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

导入模块

import { formHost } from '@kit.FormKit';

deleteForm

deleteForm(formId: string, callback: AsyncCallback<void>): void

删除指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务不再保留有关该卡片的信息。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
callback	AsyncCallback<void>	是	回调函数。当删除指定的卡片成功，error为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  formHost.deleteForm(formId, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.info('formHost deleteForm success');
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

deleteForm

deleteForm(formId: string): Promise<void>

删除指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务不再保留有关该卡片的信息。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';

try {
  let formId: string = '12400633174999288';
  formHost.deleteForm(formId).then(() => {
    console.info('formHost deleteForm success');
  }).catch((error: BusinessError) => {
    console.error(`formHost deleteForm, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

releaseForm

releaseForm(formId: string, callback: AsyncCallback<void>): void

释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，但卡片管理器服务仍然保留有关该卡片的缓存信息和存储信息。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
callback	AsyncCallback<void>	是	回调函数。当释放指定的卡片成功，error为undefined；否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  formHost.releaseForm(formId, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

releaseForm

releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void

释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务保留有关该卡片的存储信息，可以选择是否保留缓存信息。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
isReleaseCache	boolean	是	表示是否释放缓存。 true: 表示释放缓存。 false: 表示不释放缓存。
callback	AsyncCallback<void>	是	回调函数。当释放指定的卡片成功，error为undefined；否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  formHost.releaseForm(formId, true, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

releaseForm

releaseForm(formId: string, isReleaseCache?: boolean): Promise<void>

释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务保留有关该卡片的存储信息，可以选择是否保留缓存信息。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
isReleaseCache	boolean	否	表示是否释放缓存，默认为false。 true: 表示释放缓存。 false: 表示不释放缓存。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  formHost.releaseForm(formId, true).then(() => {
    console.info('formHost releaseForm success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

requestForm

requestForm(formId: string, callback: AsyncCallback<void>): void

请求卡片更新。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
callback	AsyncCallback<void>	是	回调函数。当请求卡片更新成功，error为undefined；否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  formHost.requestForm(formId, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

requestForm

requestForm(formId: string): Promise<void>

请求卡片更新。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  formHost.requestForm(formId).then(() => {
    console.info('formHost requestForm success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

requestFormWithParams¹²⁺

requestFormWithParams(formId: string, wantParams?: Record<string, Object>): Promise<void>

携带参数请求卡片更新。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
wantParams	Record<string, Object>	否	更新参数。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  let params: Record<string, Object> = {
    'ohos.extra.param.key.host_bg_inverse_color': '#ff000000' as Object
  };
  formHost.requestFormWithParams(formId, params).then(() => {
    console.info('formHost requestFormWithParams success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

castToNormalForm

castToNormalForm(formId: string, callback: AsyncCallback<void>): void

将指定的临时卡片转换为普通卡片。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
callback	AsyncCallback<void>	是	回调函数。当将指定的临时卡片转换为普通卡片成功，error为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501002	The number of forms exceeds the maximum allowed.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  formHost.castToNormalForm(formId, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

castToNormalForm

castToNormalForm(formId: string): Promise<void>

将指定的临时卡片转换为普通卡片。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501002	The number of forms exceeds the maximum allowed.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  formHost.castToNormalForm(formId).then(() => {
    console.info('formHost castTempForm success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

notifyVisibleForms

notifyVisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void

向卡片框架发送通知以使指定的卡片可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
callback	AsyncCallback<void>	是	回调函数。当向卡片框架发送通知以使指定的卡片可见成功，error为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyVisibleForms(formId, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

notifyVisibleForms

notifyVisibleForms(formIds: Array<string>): Promise<void>

向卡片框架发送通知以使指定的卡片可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyVisibleForms(formId).then(() => {
    console.info('formHost notifyVisibleForms success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

notifyInvisibleForms

notifyInvisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void

向卡片框架发送通知以使指定的卡片不可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
callback	AsyncCallback<void>	是	回调函数。当向卡片框架发送通知以使指定的卡片不可见成功，error为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyInvisibleForms(formId, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

notifyInvisibleForms

notifyInvisibleForms(formIds: Array<string>): Promise<void>

向卡片框架发送通知以使指定的卡片不可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyInvisibleForms(formId).then(() => {
    console.info('formHost notifyInvisibleForms success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

enableFormsUpdate

enableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void

向卡片框架发送通知以使指定的卡片可以更新。该方法调用成功后，卡片刷新状态设置为使能，卡片可以接收来自卡片提供方的更新。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
callback	AsyncCallback<void>	是	回调函数。当向卡片框架发送通知以使指定的卡片可以更新成功，error为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.enableFormsUpdate(formId, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

enableFormsUpdate

enableFormsUpdate(formIds: Array<string>): Promise<void>

向卡片框架发送通知以使指定的卡片可以更新。该方法调用成功后，卡片刷新状态设置为使能，卡片可以接收来自卡片提供方的更新。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.enableFormsUpdate(formId).then(() => {
    console.info('formHost enableFormsUpdate success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

disableFormsUpdate

disableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void

向卡片框架发送通知以使指定的卡片不可以更新。该方法调用成功后，卡片刷新状态设置为去使能，卡片不可以接收来自卡片提供方的更新。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
callback	AsyncCallback<void>	是	回调函数。当向卡片框架发送通知以使指定的卡片不可以更新成功，error为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.disableFormsUpdate(formId, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

disableFormsUpdate

disableFormsUpdate(formIds: Array<string>): Promise<void>

向卡片框架发送通知以使指定的卡片不可以更新。该方法调用成功后，卡片刷新状态设置为去使能，卡片不可以接收来自卡片提供方的更新。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.disableFormsUpdate(formId).then(() => {
    console.info('formHost disableFormsUpdate success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

isSystemReady

isSystemReady(callback: AsyncCallback<void>): void

检查系统是否准备好。使用callback异步回调。

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调函数。当检查系统是否准备好成功，error为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.isSystemReady((error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

isSystemReady

isSystemReady(): Promise<void>

检查系统是否准备好。使用Promise异步回调。

系统能力： SystemCapability.Ability.Form

返回值：

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

错误码：

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

错误码ID	错误信息
202	The application is not a system application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.isSystemReady().then(() => {
    console.info('formHost isSystemReady success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

getAllFormsInfo

getAllFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void

获取设备上所有应用提供的卡片信息（不包含模板卡片）。使用callback异步回调。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Array<formInfo.FormInfo>>	是	回调函数。当获取设备上所有应用提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost, formInfo } from '@kit.FormKit';

try {
  formHost.getAllFormsInfo((error: BusinessError, data: formInfo.FormInfo[]) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.info('formHost getAllFormsInfo success.');
    }
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

getAllFormsInfo

getAllFormsInfo(): Promise<Array<formInfo.FormInfo>>

获取设备上所有应用提供的卡片信息（不包含模板卡片）。使用Promise异步回调。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

返回值：

类型	说明
Promise<Array<formInfo.FormInfo>>	Promise对象。返回查询到的卡片信息。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost, formInfo } from '@kit.FormKit';

try {
  formHost.getAllFormsInfo().then((data: formInfo.FormInfo[]) => {
    console.info('formHost getAllFormsInfo success.');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

getFormsInfo

getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void

获取设备上指定应用程序提供的卡片信息（不包含模板卡片）。使用callback异步回调。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
bundleName	string	是	要查询的应用Bundle名称。
callback	AsyncCallback<Array<formInfo.FormInfo>>	是	回调函数。当获取设备上指定应用程序提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。

错误码：

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

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

示例：

import { formHost, formInfo } from '@kit.FormKit';

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', (error: BusinessError, data: formInfo.FormInfo[]) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.info('formHost getFormsInfo success.');
    }
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

getFormsInfo

getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void

获取设备上指定应用程序提供的卡片信息（不包含模板卡片）。使用callback异步回调。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
bundleName	string	是	要查询的应用Bundle名称。
moduleName	string	是	要查询的模块名称。
callback	AsyncCallback<Array<formInfo.FormInfo>>	是	回调函数。当获取设备上指定应用程序提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。

错误码：

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

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

示例：

import { formHost, formInfo } from '@kit.FormKit';

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry', (error: BusinessError, data: formInfo.FormInfo[]) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.info('formHost getFormsInfo success.');
    }
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

getFormsInfo

getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>>

获取设备上指定应用程序提供的卡片信息（不包含模板卡片）。使用Promise异步回调。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
bundleName	string	是	要查询的应用Bundle名称。
moduleName	string	否	要查询的模块名称，缺省默认为空。

返回值：

类型	说明
Promise<Array<formInfo.FormInfo>>	Promise对象。返回查询到的卡片信息。

错误码：

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

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

示例：

import { formHost, formInfo } from '@kit.FormKit';

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data: formInfo.FormInfo[]) => {
    console.info('formHost getFormsInfo success.');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

getFormsInfo¹²⁺

getFormsInfo(filter: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>>

获取设备上指定应用程序提供的卡片信息（不包含模板卡片）。使用Promise异步回调。

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
filter	formInfo.FormInfoFilter	是	卡片信息过滤器。

返回值：

类型	说明
Promise<Array<formInfo.FormInfo>>	Promise对象。返回查询到符合条件的卡片信息。

错误码：

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

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

示例：

import { formHost, formInfo } from '@kit.FormKit';

const filter: formInfo.FormInfoFilter = {
  bundleName: 'ohos.samples.FormApplication',
  moduleName: 'entry',
  supportedDimensions: [FormDimension.Dimension_1_2, FormDimension.Dimension_2_2, FormDimension.Dimension_2_4]
};
try {
  formHost.getFormsInfo(filter).then((data: formInfo.FormInfo[]) => {
    console.info('formHost getFormsInfo success.');
  }).catch((error: BusinessError) => {
    console.error(`promise error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

deleteInvalidForms

deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void

根据列表删除应用程序的无效卡片。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	有效卡片标识列表。
callback	AsyncCallback<number>	是	回调函数。当根据列表删除应用程序的无效卡片成功，error为undefined，data为删除的卡片个数；否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';

try {
  let formIds: string[] = new Array('12400633174999288', '12400633174999289');
  formHost.deleteInvalidForms(formIds, (error: BusinessError, data: number) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.info(`formHost deleteInvalidForms, data: ${data}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

deleteInvalidForms

deleteInvalidForms(formIds: Array<string>): Promise<number>

根据列表删除应用程序的无效卡片。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	有效卡片标识列表。

返回值：

类型	说明
Promise<number>	Promise对象。返回删除的卡片个数。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';

try {
  let formIds: string[] = new Array('12400633174999288', '12400633174999289');
  formHost.deleteInvalidForms(formIds).then((data: number) => {
    console.info(`formHost deleteInvalidForms, data: ${data}`);
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

acquireFormState

acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void

获取卡片状态。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
want	Want	是	查询卡片状态时携带的want信息。需要包含bundle名、ability名、module名、卡片名、卡片规格等。
callback	AsyncCallback<formInfo.FormStateInfo>	是	回调函数。当获取卡片状态成功，error为undefined，data为获取到的卡片状态；否则为错误对象。

错误码：

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

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

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let want: Want = {
  'deviceId': '',
  'bundleName': 'ohos.samples.FormApplication',
  'abilityName': 'FormAbility',
  'parameters': {
    'ohos.extra.param.key.module_name': 'entry',
    'ohos.extra.param.key.form_name': 'widget',
    'ohos.extra.param.key.form_dimension': 2
  }
};
try {
  formHost.acquireFormState(want, (error: BusinessError, data: formInfo.FormStateInfo) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.info(`formHost acquireFormState, data: ${data.formState}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

acquireFormState

acquireFormState(want: Want): Promise<formInfo.FormStateInfo>

获取卡片状态。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
want	Want	是	查询卡片状态时携带的want信息。需要包含bundle名、ability名、module名、卡片名、卡片规格等。

返回值：

类型	说明
Promise<formInfo.FormStateInfo>	Promise对象。返回卡片状态。

错误码：

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

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

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let want: Want = {
  'deviceId': '',
  'bundleName': 'ohos.samples.FormApplication',
  'abilityName': 'FormAbility',
  'parameters': {
    'ohos.extra.param.key.module_name': 'entry',
    'ohos.extra.param.key.form_name': 'widget',
    'ohos.extra.param.key.form_dimension': 2
  }
};
try {
  formHost.acquireFormState(want).then((data: formInfo.FormStateInfo) => {
    console.info(`formHost acquireFormState, data: ${data.formState}`);
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

on('formUninstall')

on(type: 'formUninstall', callback: Callback<string>): void

订阅卡片卸载事件。使用callback异步回调。

说明：

卡片卸载与卡片移除不同。当应用卸载时，对应的卡片会自动卸载。

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
type	string	是	填写'formUninstall'，表示卡片卸载事件。
callback	Callback<string>	是	回调函数，返回卡片标识。

错误码：

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

错误码ID	错误信息
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

示例：

import { formHost } from '@kit.FormKit';

formHost.on('formUninstall', (formId: string) => {
  console.info(`formHost on formUninstall, formId: ${formId}`);
});

off('formUninstall')

off(type: 'formUninstall', callback?: Callback<string>): void

取消订阅卡片卸载事件。使用callback异步回调。

说明：

卡片卸载与卡片移除不同。当应用卸载时，对应的卡片会自动卸载。

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
type	string	是	填写'formUninstall'，表示卡片卸载事件。
callback	Callback<string>	否	回调函数，返回卡片标识。缺省时，表示注销所有已注册事件回调。 需与对应on('formUninstall')的callback一致。

错误码：

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

错误码ID	错误信息
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

示例：

import { formHost } from '@kit.FormKit';

formHost.off('formUninstall', (formId: string) => {
  console.info(`formHost on formUninstall, formId: ${formId}`);
});

notifyFormsVisible

notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void

通知卡片是否可见。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
isVisible	boolean	是	表示卡片是否可见。 true: 表示卡片可见。 false: 表示卡片不可见。
callback	AsyncCallback<void>	是	回调函数。当通知卡片是否可见成功，error为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsVisible(formIds, true, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

notifyFormsVisible

notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void>

通知卡片是否可见。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
isVisible	boolean	是	表示卡片是否可见。 true: 表示卡片可见。 false: 表示卡片不可见。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsVisible(formIds, true).then(() => {
    console.info('formHost notifyFormsVisible success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

notifyFormsEnableUpdate

notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void

通知卡片是否启用更新状态。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
isEnableUpdate	boolean	是	表示卡片是否使能更新状态。 true: 表示卡片使能更新状态。false: 表示卡片没有使能更新状态。
callback	AsyncCallback<void>	是	回调函数。当通知卡片是否启用更新状态成功，error为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsEnableUpdate(formIds, true, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

notifyFormsEnableUpdate

notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void>

通知卡片是否启用更新状态。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识列表。
isEnableUpdate	boolean	是	表示卡片是否使能更新状态。 true: 表示卡片使能更新状态。 false: 表示卡片没有使能更新状态。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsEnableUpdate(formIds, true).then(() => {
    console.info('formHost notifyFormsEnableUpdate success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

shareForm

shareForm(formId: string, deviceId: string, callback: AsyncCallback<void>): void

指定formId和远程设备Id进行卡片分享。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM 和 ohos.permission.DISTRIBUTED_DATASYNC

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
deviceId	string	是	远程设备标识。
callback	AsyncCallback<void>	是	回调函数。当指定formId和远程设备Id进行卡片分享成功，error为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formId: string = '12400633174999288';
let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2';
try {
  formHost.shareForm(formId, deviceId, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

shareForm

shareForm(formId: string, deviceId: string): Promise<void>

指定formId和远程设备Id进行卡片分享。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM 和 ohos.permission.DISTRIBUTED_DATASYNC

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
deviceId	string	是	远程设备标识。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formId: string = '12400633174999288';
let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2';
try {
  formHost.shareForm(formId, deviceId).then(() => {
    console.info('formHost shareForm success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

notifyFormsPrivacyProtected

notifyFormsPrivacyProtected(formIds: Array<string>, isProtected: boolean, callback: AsyncCallback<void>): void

通知指定卡片隐私保护状态改变。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	需要修改隐私保护的卡片标识列表。
isProtected	boolean	是	表示卡片是否进行隐私保护状态。 true: 表示卡片要进行隐私保护状态。 false: 表示卡片不需要进行隐私保护状态。
callback	AsyncCallback<void>	是	回调函数。当指定卡片设置隐私保护属性成功，error为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsPrivacyProtected(formIds, true, (error: BusinessError) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

notifyFormsPrivacyProtected

notifyFormsPrivacyProtected(formIds: Array<string>, isProtected: boolean): Promise<void>

通知指定卡片隐私保护状态改变。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	需要修改隐私保护的卡片标识列表。
isProtected	boolean	是	表示卡片是否进行隐私保护状态。 true: 表示卡片要进行隐私保护状态。 false: 表示卡片不需要进行隐私保护状态。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsPrivacyProtected(formIds, true).then(() => {
    console.info('formHost notifyFormsPrivacyProtected success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

acquireFormData¹⁰⁺

acquireFormData(formId: string, callback: AsyncCallback<Record<string, Object>>): void

请求卡片提供方数据。使用callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
callback	AsyncCallback<Record<string, Object>	是	以callback方式返回接口运行结果及分享数据。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred. invalid input parameter during form operation.

示例：

import { formHost } from '@kit.FormKit';

let formId: string = '12400633174999288';
try {
  formHost.acquireFormData(formId, (error, data) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.info('formHost acquireFormData success.');
    }
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

acquireFormData¹⁰⁺

acquireFormData(formId: string): Promise<Record<string, Object>>

请求卡片提供方数据。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。

返回值：

类型	说明
Promise<Record<string, Object>>	以Promise方式返回接口运行结果及分享数据。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred. invalid input parameter during form operation.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formId: string = '12400633174999288';
try {
  formHost.acquireFormData(formId).then((data) => {
    console.info('formHost acquireFormData success' + data);
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (e) {
  console.error(`catch error, code: ${e.code}, message: ${e.message}`);
}

setRouterProxy¹¹⁺

setRouterProxy(formIds: Array<string>, proxy: Callback<Want>, callback: AsyncCallback<void>): void

设置卡片跳转代理。使用callback异步回调，返回卡片跳转所需要Want信息。

说明：

• 一般情况下，对于桌面添加的卡片，当卡片触发router跳转时，卡片框架会检测其跳转目的地是否合理，是否有跳转权限，然后进行应用跳转。如果卡片使用方添加了卡片，并设置了卡片跳转代理，那么卡片触发router跳转时，卡片框架不会再为其进行跳转操作，会把包含跳转目的地的want参数返回给卡片使用方。因此如果卡片使用方希望使用该want信息进行应用跳转，需要确保自身拥有应用跳转的权限，参考 UIAbilityContext.startAbility()接口。

• 一个formId最多只能设置一个跳转代理，多次设置后，最后设置的proxy生效。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识数组。
proxy	Callback<Want>	是	回调函数。返回跳转所需要的Want信息。
callback	AsyncCallback<void>	是	回调函数，当指定卡片设置router跳转代理成功时，error为undefined；否则抛出异常。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

示例：

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

@Entry
@Component
struct CardExample {
  @State formId: number = 0;
  @State fwidth: number = 420;
  @State fheight: number = 280;
  private context = this.getUIContext().getHostContext() as common.UIAbilityContext;

  build() {
    Column() {
      FormComponent({
        id: this.formId,
        name: "widget",
        bundle: "com.example.cardprovider",
        ability: "EntryFormAbility",
        module: "entry",
        dimension: FormDimension.Dimension_2_2,
        temporary: false,
      })
        .allowUpdate(true)
        .size({ width: this.fwidth, height: this.fheight })
        .visibility(Visibility.Visible)
        .onAcquired((form) => {
          console.info('testTag onAcquired.');
          this.formId = form.id;
          try {
            let formIds: string[] = [this.formId.toString()];
            formHost.setRouterProxy(formIds, (want: Want) => {
              console.info('formHost recv router event.');
              // 卡片使用方自己处理跳转
              this.context.startAbility(want, (err: BusinessError) => {
                console.error(`formHost startAbility error, code: ${err.code}, message: ${err.message}`);
              });
            }, (err: BusinessError) => {
              console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`);
            })
          } catch (e) {
            console.error(`formHost setRouterProxy, code: ${e.code}, message: ${e.message}`);
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

setRouterProxy¹¹⁺

setRouterProxy(formIds: Array<string>, proxy: Callback<Want>): Promise<void>

设置卡片跳转代理。使用Promise异步回调，返回卡片跳转所需要Want信息。使用Promise异步回调。

说明：

• 一般情况下，对于桌面添加的卡片，当卡片触发router跳转时，卡片框架会检测其跳转目的地是否合理，是否有跳转权限，然后进行应用跳转。如果卡片使用方添加了卡片，并设置了卡片跳转代理，那么卡片触发router跳转时，卡片框架不会再为其进行跳转操作，会把包含跳转目的地的want参数返回给卡片使用方。因此如果卡片使用方希望使用该want信息进行应用跳转，需要确保自身拥有应用跳转的权限，参考UIAbilityContext.startAbility()接口。

• 一个formId最多只能设置一个跳转代理，多次设置后，最后设置的proxy生效。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识数组。
proxy	Callback<Want>	是	回调函数。返回跳转所需要的Want信息。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

示例：

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

@Entry
@Component
struct CardExample {
  @State formId: number = 0;
  @State fwidth: number = 420;
  @State fheight: number = 280;
  private context = this.getUIContext().getHostContext() as common.UIAbilityContext;

  build() {
    Column() {
      FormComponent({
        id: this.formId,
        name: "widget",
        bundle: "com.example.cardprovider",
        ability: "EntryFormAbility",
        module: "entry",
        dimension: FormDimension.Dimension_2_2,
        temporary: false,
      })
        .allowUpdate(true)
        .size({ width: this.fwidth, height: this.fheight })
        .visibility(Visibility.Visible)
        .onAcquired((form) => {
          console.info('testTag onAcquired.');
          this.formId = form.id;
          try {
            let formIds: string[] = [this.formId.toString()];
            formHost.setRouterProxy(formIds, (want: Want) => {
              console.info('formHost recv router event.');
              // 卡片使用方自己处理跳转
              this.context.startAbility(want, (err: BusinessError) => {
                console.info(`formHost startAbility error, code: ${err.code}, message: ${err.message}`);
              });
            }).then(() => {
              console.info('formHost set router proxy success');
            }).catch((err: BusinessError) => {
              console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`);
            })
          } catch (e) {
            console.error(`formHost setRouterProxy, code: ${e.code}, message: ${e.message}`);
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

clearRouterProxy¹¹⁺

clearRouterProxy(formIds: Array<string>, callback: AsyncCallback<void>): void

清除卡片跳转代理。使用callback异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识数组。
callback	AsyncCallback<void>	是	回调函数，当指定卡片取消router跳转代理成功时，error为undefined；否则抛出异常。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.clearRouterProxy(formIds, (err: BusinessError) => {
    if (err) {
      console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

clearRouterProxy¹¹⁺

clearRouterProxy(formIds: Array<string>): Promise<void>

清除卡片跳转代理。使用Promise异步回调。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识数组。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.clearRouterProxy(formIds).then(() => {
    console.info('formHost clear router proxy success');
  }).catch((err: BusinessError) => {
    console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

setFormsRecyclable¹¹⁺

setFormsRecyclable(formIds: Array<string>, callback: AsyncCallback<void>): void

设置卡片可回收。使用callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识数组。
callback	AsyncCallback<void>	是	回调函数，当设置卡片可回收成功时，error为undefined；否则抛出异常。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	caller is not system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.setFormsRecyclable(formIds, (err: BusinessError) => {
    if (err) {
      console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

setFormsRecyclable¹¹⁺

setFormsRecyclable(formIds: Array<string>): Promise<void>

设置卡片可回收。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识数组。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	caller is not system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.setFormsRecyclable(formIds).then(() => {
    console.info('setFormsRecyclable success');
  }).catch((err: BusinessError) => {
    console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

recoverForms¹¹⁺

recoverForms(formIds: Array<string>, callback: AsyncCallback<void>): void

恢复卡片。使用callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识数组。
callback	AsyncCallback<void>	是	回调函数，当恢复卡片成功时，error为undefined；否则抛出异常。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	caller is not system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.recoverForms(formIds, (err: BusinessError) => {
    if (err) {
      console.error(`recoverForms error, code: ${err.code}, message: ${err.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

recoverForms¹¹⁺

recoverForms(formIds: Array<string>): Promise<void>

恢复被回收的卡片，并将它的状态更新为不可回收，如果卡片未被回收则只更新状态为不可回收。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识数组。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	caller is not system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.recoverForms(formIds).then(() => {
    console.info('recover forms success');
  }).catch((err: BusinessError) => {
    console.error(`formHost recover forms error, code: ${err.code}, message: ${err.message}`);
  });
} catch (e) {
  console.error(`catch error, code: ${e.code}, message: ${e.message}`);
}

recycleForms¹²⁺

recycleForms(formIds: Array<string>): Promise<void>

立即回收卡片内存。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限： ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formIds	Array<string>	是	卡片标识数组。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.recycleForms(formIds).then(() => {
    console.info('recycle forms success');
  }).catch((err: BusinessError) => {
    console.error(`formHost recycle forms error, code: ${err.code}, message: ${err.message}`);
  });
} catch (e) {
  console.error(`catch error, code: ${e.code}, message: ${e.message}`);
}

updateFormLocation¹²⁺

updateFormLocation(formId: string, location: formInfo.FormLocation): void;

更新卡片位置。

模型约束: 此接口仅可在Stage模型下使用。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
location	formInfo.FormLocation	是	卡片位置。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	caller is not system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  formHost.updateFormLocation(formId, formInfo.FormLocation.SCREEN_LOCK);
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

setPublishFormResult¹²⁺

setPublishFormResult(formId: string, result: formInfo.PublishFormResult): void;

设置卡片加桌结果。

模型约束: 此接口仅可在Stage模型下使用。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
result	formInfo.PublishFormResult	是	发布卡片加桌结果。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  let res: formInfo.PublishFormResult = { code: formInfo.PublishFormErrorCode.SUCCESS, message: '' };
  formHost.setPublishFormResult(formId, res);
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

updateFormLockedState²²⁺

updateFormLockedState(formId: string, isLocked: boolean): Promise<void>

通知卡片管控状态更新。使用Promise异步回调。

卡片管控状态是指，应用使能了应用锁管控，对应应用的卡片也会跟随使能应用锁管控，此时卡片页面会使用加锁的蒙板样式遮罩卡片。在管控状态下，操作和使用卡片需要输入加锁时设置的密码。

需要权限：ohos.permission.REQUIRE_FORM

系统能力：SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
isLocked	boolean	是	标识卡片是否为管控状态，true表示管控状态，false表示非管控状态。

返回值：

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

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	caller is not a system app.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formId: string = '12400633174999288';
let isLocked: boolean = true;

try {
  formHost.updateFormLockedState(formId, isLocked).then(() => {
    console.info(`formHost updateFormLockedState success`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

formHost.on('formOverflow')²⁰⁺

on(type: 'formOverflow', callback: Callback<formInfo.OverflowRequest>): void

订阅互动卡片动效请求事件。使用callback异步回调。

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
type	string	是	事件回调类型，支持的事件为'formOverflow'，表示互动卡片动效请求。
callback	Callback<formInfo.OverflowRequest>	是	回调函数，用于卡片使用方对动效请求进行处理。

错误码：

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

错误码ID	错误信息
202	The application is not a system application.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.on('formOverflow', (request: formInfo.OverflowRequest) => {
    console.info(`formHost on formOverflow, formId is ${request.formId}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

formHost.off('formOverflow')²⁰⁺

off(type: 'formOverflow', callback?: Callback<formInfo.OverflowRequest>): void

取消订阅互动卡片动效请求事件。使用callback异步回调。

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
type	string	是	事件回调类型，支持的事件为'formOverflow'，表示互动卡片动效请求。
callback	Callback<formInfo.OverflowRequest>	否	回调函数，对应已订阅互动卡片动效请求。缺省时，表示注销所有已注册互动卡片动效请求事件回调。

错误码：

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

错误码ID	错误信息
202	The application is not a system application.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.off('formOverflow', (request: formInfo.OverflowRequest) => {
    console.info(`formHost off formOverflow, formId is ${request.formId}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}   

formHost.on('changeSceneAnimationState')²⁰⁺

on(type: 'changeSceneAnimationState', callback: Callback<formInfo.ChangeSceneAnimationStateRequest>): void

订阅互动卡片状态切换请求事件。互动卡片状态分为激活态和非激活态，非激活态下，互动卡片同普通卡片一致；激活态下，互动卡片支持拉起卡片提供方所开发的LiveFormExtensionAbility进程，实现互动卡片动效。使用callback异步回调。

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
type	string	是	事件回调类型，支持的事件为'changeSceneAnimationState'，表示互动卡片状态切换。
callback	Callback<formInfo.ChangeSceneAnimationStateRequest>	是	回调函数，用于卡片使用方处理状态切换请求。

错误码：

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

错误码ID	错误信息
202	The application is not a system application.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.on('changeSceneAnimationState', (request: formInfo.ChangeSceneAnimationStateRequest): void => {
    console.info(`formHost on changeSceneAnimationState, formId is ${request.formId}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

formHost.off('changeSceneAnimationState')²⁰⁺

off(type: 'changeSceneAnimationState', callback?: Callback<formInfo.ChangeSceneAnimationStateRequest>): void

取消订阅互动卡片状态切换请求事件。互动卡片状态分为激活态和非激活态，非激活态下，互动卡片同普通卡片一致；激活态下，互动卡片支持拉起卡片提供方所开发的LiveFormExtensionAbility进程，实现互动卡片动效。使用callback异步回调。

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
type	string	是	事件回调类型，支持的事件为'changeSceneAnimationState'，表示互动卡片状态切换。
callback	Callback<formInfo.ChangeSceneAnimationStateRequest>	否	回调函数，对应已订阅互动卡片状态切换请求。缺省时，表示注销所有已注册互动卡片状态切换事件回调。

错误码：

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

错误码ID	错误信息
202	The application is not a system application.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.off('changeSceneAnimationState', (request: formInfo.ChangeSceneAnimationStateRequest): void => {
    console.info(`formHost off changeSceneAnimationState, formId is ${request.formId}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

formHost.on('getFormRect')²⁰⁺

on(type: 'getFormRect', callback: formInfo.GetFormRectInfoCallback): void

订阅卡片位置尺寸查询请求事件。使用callback异步回调。

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
type	string	是	事件回调类型，支持的事件为'getFormRect'，表示卡片位置尺寸查询。
callback	formInfo.GetFormRectInfoCallback	是	回调函数，卡片使用方对查询请求进行处理，返回卡片相对屏幕左上角的位置信息和卡片尺寸信息。

错误码：

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

错误码ID	错误信息
202	The application is not a system application.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.on('getFormRect', (formId: string): Promise<formInfo.Rect> => {
    // 卡片使用方需要对查询请求进行处理，计算并返回卡片尺寸、位置信息
    return new Promise<formInfo.Rect>((resolve: Function) => {
      console.info(`formHost on getFormRect, formId is ${formId}`);
      let formRect: formInfo.Rect = {
        left: 0,
        top: 0,
        width: 0,
        height: 0
      };
      resolve(formRect);
    })
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

formHost.off('getFormRect')²⁰⁺

off(type: 'getFormRect', callback?: formInfo.GetFormRectInfoCallback): void

取消订阅卡片位置尺寸查询请求事件。使用callback异步回调。

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
type	string	是	事件回调类型，支持的事件为'getFormRect'，表示卡片位置尺寸查询。
callback	formInfo.GetFormRectInfoCallback	否	回调函数，对应已订阅卡片位置尺寸查询请求。缺省时，表示注销所有已注册卡片位置、尺寸查询事件回调。

错误码：

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

错误码ID	错误信息
202	The application is not a system application.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.off('getFormRect');
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

formHost.updateFormSize²⁰⁺

updateFormSize(formId: string, newDimension: formInfo.FormDimension, newRect: formInfo.Rect): void

调整卡片尺寸。

需要权限：ohos.permission.REQUIRE_FORM

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
formId	string	是	卡片标识。
newDimension	formInfo.FormDimension	是	卡片尺寸，例如 Dimension_1_2，表示 1 x 2 卡片。
newRect	formInfo.Rect	是	卡片位置信息，包括卡片左上角顶点的xy坐标和卡片的宽高。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	caller is not system app.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501012	The dimension parameter is incorrect.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  let newDimension = formInfo.FormDimension.Dimension_1_2;
  let newRect: formInfo.Rect = {
    left: 1,
    top: 2,
    width: 100,
    height: 100
  };
  formHost.updateFormSize(formId, newDimension, newRect);
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

getAllTemplateFormsInfo²³⁺

getAllTemplateFormsInfo(): Promise<Array<formInfo.FormInfo>>

获取设备上所有应用提供的模板卡片信息。使用Promise异步回调。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

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

返回值：

类型	说明
Promise<Array<formInfo.FormInfo>>	Promise对象。返回查询到的卡片信息。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
16500050	IPC connection error.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.getAllTemplateFormsInfo().then((data: formInfo.FormInfo[]) => {
    for (let formInfo of data) {
      console.info(`getAllTemplateFormsInfo bundleName: ${formInfo.bundleName}, moduleName: ${formInfo.moduleName}, name: ${formInfo.name}`);
    }
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

getTemplateFormsInfo²³⁺

getTemplateFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>>

获取设备上指定应用程序提供的模板卡片信息。使用Promise异步回调。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
bundleName	string	是	要查询的应用Bundle名称。
moduleName	string	否	要查询的模块名称，缺省默认为空。

返回值：

类型	说明
Promise<Array<formInfo.FormInfo>>	Promise对象。返回查询到的卡片信息。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
16500050	IPC connection error.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.getTemplateFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data: formInfo.FormInfo[]) => {
    for (let formInfo of data) {
      console.info(`getTemplateFormsInfo bundleName: ${formInfo.bundleName}, moduleName: ${formInfo.moduleName}, name: ${formInfo.name}`);
    }
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

formHost.onTemplateFormDetailInfoChange²³⁺

onTemplateFormDetailInfoChange(callback: formInfo.TemplateFormDetailInfoCallback): void

订阅模板卡片静态配置信息变化。使用callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
callback	formInfo.TemplateFormDetailInfoCallback	是	回调函数，监控模板卡片静态配置信息变化。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	Permissions denied.Called by non-system application.
16500050	IPC connection error.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  const callback: formInfo.TemplateFormDetailInfoCallback = (info: formInfo.TemplateFormDetailInfo[]) => {
    for (let templateFormDetailInfo of info) {
      console.info(`TemplateFormDetailInfoCallback bundleName: ${templateFormDetailInfo.bundleName}, moduleName: ${templateFormDetailInfo.moduleName}, formName: ${templateFormDetailInfo.formName}`);
    }
  };
  formHost.onTemplateFormDetailInfoChange(callback);
  console.info(`onTemplateFormDetailInfoChange success`);
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

formHost.offTemplateFormDetailInfoChange²³⁺

offTemplateFormDetailInfoChange(callback?: formInfo.TemplateFormDetailInfoCallback): void

取消订阅模板卡片静态配置信息变化。使用callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
callback	formInfo.TemplateFormDetailInfoCallback	否	回调函数，监控模板卡片静态配置信息变化。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	Permissions denied.Called by non-system application.
16500050	IPC connection error.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.offTemplateFormDetailInfoChange();
  console.info(`offTemplateFormDetailInfoChange success`);
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

formHost.getFormIdsByFormLocation²⁴⁺

getFormIdsByFormLocation(location: formInfo.FormLocation): Promise<Array<string>>

获取设备上指定卡片位置的卡片标识列表。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
location	formInfo.FormLocation	是	卡片位置。

返回值：

类型	说明
Promise<Array<string>>	Promise对象。返回查询到的卡片标识列表。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
16500050	IPC connection error.
16501016	The location of the widget is invalid.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.getFormIdsByFormLocation(formInfo.FormLocation.DESKTOP).then((formIds: Array<string>) => {
    console.info('formHost getFormIdsByFormLocation success.');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${error.code}, message: ${error.message}`);
}

formHost.onGetWantParamsCallback

onGetWantParamsCallback(callback: formInfo.GetWantParamsCallback): void

订阅获取卡片参数事件。使用callback异步回调。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
callback	formInfo.GetWantParamsCallback	是	回调函数，返回卡片参数信息。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
16500050	IPC connection error.

示例：

import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  const callback = (formInfos: formInfo.FormInfo[]): Array<Record<string, Object>> => {
    console.info(`onGetWantParamsCallback formInfos length: ${formInfos.length}`);
    let wantParamsList: Array<Record<string, Object>> = [];
    for (let formInfoItem of formInfos) {
      let wantParams: Record<string, Object> = {};
      wantParams['key'] = 'value';
      wantParamsList.push(wantParams);
    }
    return wantParamsList;
  };
  formHost.onGetWantParamsCallback(callback);
  console.info(`onGetWantParamsCallback success`);
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

formHost.offGetWantParamsCallback

offGetWantParamsCallback(callback?: formInfo.GetWantParamsCallback): void

取消订阅获取卡片参数事件。使用callback异步回调。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
callback	formInfo.GetWantParamsCallback	否	回调函数，返回卡片参数信息。

错误码：

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

错误码ID	错误信息
201	Permissions denied.
202	The application is not a system application.
16500050	IPC connection error.

示例：

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  formHost.offGetWantParamsCallback();
  console.info(`offGetWantParamsCallback success`);
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}