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

2025-06-12
浏览 (1)

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

formProvider模块提供了获取卡片信息、更新卡片、设置卡片更新时间、请求发布卡片等能力。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。当前页面仅包含本模块的系统接口，其他公共接口参见@ohos.app.form.formProvider (formProvider)。

导入模块

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

requestPublishForm

requestPublishForm(want: Want, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback<string>): void

请求发布一张卡片到使用方。使用方通常为桌面，使用callback异步回调。

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
want	Want	是	发布请求，需包含以下字段。 abilityName: 目标卡片ability parameters: ‘ohos.extra.param.key.form_dimension’ ‘ohos.extra.param.key.form_name’ ‘ohos.extra.param.key.module_name’
formBindingData	formBindingData.FormBindingData	是	创建卡片的数据。
callback	AsyncCallback<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.
16500050	IPC connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

示例：

import { formBindingData, formProvider } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let want: Want = {
  abilityName: 'FormAbility',
  parameters: {
    'ohos.extra.param.key.form_dimension': 2,
    'ohos.extra.param.key.form_name': 'widget',
    'ohos.extra.param.key.module_name': 'entry'
  }
};
try {
  let param: Record<string, string> = {
    'temperature': '22c',
    'time': '22:00'
  }
  let obj: formBindingData.FormBindingData = formBindingData.createFormBindingData(param);
  formProvider.requestPublishForm(want, obj, (error: BusinessError, data: string) => {
    if (error) {
      console.error(`callback error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
      return;
    }
    console.log(`formProvider requestPublishForm, form ID is: ${JSON.stringify(data)}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

requestPublishForm

requestPublishForm(want: Want, callback: AsyncCallback<string>): void

请求发布一张卡片到使用方。使用方通常为桌面，使用callback异步回调。

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
want	Want	是	发布请求，需包含以下字段。 abilityName: 目标卡片ability parameters: ‘ohos.extra.param.key.form_dimension’ ‘ohos.extra.param.key.form_name’ ‘ohos.extra.param.key.module_name’
callback	AsyncCallback<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.
16500050	IPC connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

示例：

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

let want: Want = {
  abilityName: 'FormAbility',
  parameters: {
    'ohos.extra.param.key.form_dimension': 2,
    'ohos.extra.param.key.form_name': 'widget',
    'ohos.extra.param.key.module_name': 'entry'
  }
};
try {
  formProvider.requestPublishForm(want, (error: BusinessError, data: string) => {
    if (error) {
      console.error(`callback error, code: ${error.code}, message: ${error.message})`);
      return;
    }
    console.log(`formProvider requestPublishForm, form ID is: ${JSON.stringify(data)}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

requestPublishForm

requestPublishForm(want: Want, formBindingData?: formBindingData.FormBindingData): Promise<string>

请求发布一张卡片到使用方。使用方通常为桌面，使用Promise异步回调。

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
want	Want	是	发布请求，需包含以下字段。 abilityName: 目标卡片ability parameters: ‘ohos.extra.param.key.form_dimension’ ‘ohos.extra.param.key.form_name’ ‘ohos.extra.param.key.module_name’
formBindingData	formBindingData.FormBindingData	否	创建卡片的数据，默认为空，不提供创建卡片数据。

返回值：

类型	说明
Promise<string>	Promise对象。返回卡片标识。

错误码：

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

错误码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.
16500050	IPC connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

示例：

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

let want: Want = {
  abilityName: 'FormAbility',
  parameters: {
    'ohos.extra.param.key.form_dimension': 2,
    'ohos.extra.param.key.form_name': 'widget',
    'ohos.extra.param.key.module_name': 'entry'
  }
};
try {
  formProvider.requestPublishForm(want).then((data: string) => {
    console.log(`formProvider requestPublishForm success, form ID is : ${JSON.stringify(data)}`);
  }).catch((error: BusinessError) => {
    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

isRequestPublishFormSupported

isRequestPublishFormSupported(callback: AsyncCallback<boolean>): void

查询是否支持发布一张卡片到使用方，使用callback异步回调。

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

系统能力： SystemCapability.Ability.Form

参数：

参数名	类型	必填	说明
callback	AsyncCallback<boolean>	是	回调函数。返回是否支持发布一张卡片到使用方。

错误码：

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

错误码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.
16500050	IPC connection error.
16501000	An internal functional error occurred.

示例：

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

try {
  formProvider.isRequestPublishFormSupported((error: BusinessError, isSupported: boolean) => {
    if (error) {
      console.error(`callback error, code: ${error.code}, message: ${error.message})`);
    } else {
      if (isSupported) {
        let want: Want = {
          abilityName: 'FormAbility',
          parameters: {
            'ohos.extra.param.key.form_dimension': 2,
            'ohos.extra.param.key.form_name': 'widget',
            'ohos.extra.param.key.module_name': 'entry'
          }
        };
        try {
          formProvider.requestPublishForm(want, (error: BusinessError, data: string) => {
            if (error) {
              console.error(`callback error, code: ${error.code}, message: ${error.message})`);
              return;
            }
            console.log(`formProvider requestPublishForm, form ID is: ${JSON.stringify(data)}`);
          });
        } catch (error) {
          console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
        }
      }
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

isRequestPublishFormSupported

isRequestPublishFormSupported(): Promise<boolean>

查询是否支持发布一张卡片到使用方，使用Promise异步回调。

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

系统能力： SystemCapability.Ability.Form

返回值：

类型	说明
Promise<boolean>	Promise对象。返回是否支持发布一张卡片到使用方。

错误码：

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

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

示例：

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

try {
  formProvider.isRequestPublishFormSupported().then((isSupported: boolean) => {
    if (isSupported) {
      let want: Want = {
        abilityName: 'FormAbility',
        parameters: {
          'ohos.extra.param.key.form_dimension': 2,
          'ohos.extra.param.key.form_name': 'widget',
          'ohos.extra.param.key.module_name': 'entry'
        }
      };
      try {
        formProvider.requestPublishForm(want).then((data: string) => {
          console.log(`formProvider requestPublishForm success, form ID is : ${JSON.stringify(data)}`);
        }).catch((error: BusinessError) => {
          console.error(`promise error, code: ${error.code}, message: ${error.message})`);
        });
      } catch (error) {
        console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
      }
    }
  }).catch((error: BusinessError) => {
    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

activateSceneAnimation²⁰⁺

activateSceneAnimation(formId: string): Promise<void>

互动卡片请求状态切换到激活态，只针对场景动效类型互动卡片生效，使用Promise异步回调。互动卡片状态分为激活态和非激活态，非激活态下，互动卡片同普通卡片一致；激活态下，互动卡片支持拉起卡片提供方所开发的LiveFormExtensionAbility进程，实现互动卡片动效。

系统能力： SystemCapability.Ability.Form

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

参数：

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

返回值：

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

错误码：

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

错误码ID	错误信息
202	The application is not a system application.
801	Capability not supported.function activateSceneAnimation can not work correctly due to limited device capabilities.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
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.
16501011	The form can not support this operation, please check your fom_config’s sceneAnimationParams configuration infomation is correct or not.

示例：

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

let formId: string = '12400633174999288';

try {
  formProvider.activateSceneAnimation(formId).then(() => {
    console.info('activateSceneAnimation succeed.');
  }).catch((error: BusinessError) => {
    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

deactivateSceneAnimation²⁰⁺

deactivateSceneAnimation(formId: string): Promise<void>

互动卡片请求切换到非激活态，只针对场景动效类型互动卡片生效，使用Promise异步回调。互动卡片状态分为激活态和非激活态，非激活态下，互动卡片同普通卡片一致；激活态下，互动卡片支持拉起卡片提供方所开发的LiveFormExtensionAbility进程，实现互动卡片动效。

系统能力： SystemCapability.Ability.Form

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

参数：

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

返回值：

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

错误码：

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

错误码ID	错误信息
202	The application is not a system application.
801	Capability not supported.function deactivateSceneAnimation can not work correctly due to limited device capabilities.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
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.
16501011	The form can not support this operation, please check your fom_config’s sceneAnimationParams configuration infomation is correct or not.

示例：

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

let formId: string = '12400633174999288';

try {
  formProvider.deactivateSceneAnimation(formId).then(() => {
    console.info('deactivateSceneAnimation succeed.');
  }).catch((error: BusinessError) => {
    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}