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

  • 2025-06-12
  • 浏览 (1)

@ohos.app.form.formProvider (formProvider)

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

说明：

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

导入模块

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

formProvider.setFormNextRefreshTime

setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void

设置指定卡片的下一次更新时间，使用callback异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

参数：

参数名 类型 必填 说明
formId string 是 卡片标识。
minute number 是 指定卡片多久之后更新，取值范围：大于等于5，单位：min。
callback AsyncCallback<void> 是 回调函数。

错误码：

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

错误码ID 错误信息
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.
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 { formProvider } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formId: string = '12400633174999288';
try {
  formProvider.setFormNextRefreshTime(formId, 5, (error: BusinessError) => {
    if (error) {
      console.error(`callback error, code: ${error.code}, message: ${error.message})`);
      return;
    }
    console.log(`formProvider setFormNextRefreshTime success`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

formProvider.setFormNextRefreshTime

setFormNextRefreshTime(formId: string, minute: number): Promise<void>

设置指定卡片的下一次更新时间，使用Promise异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

参数：

参数名 类型 必填 说明
formId string 是 卡片标识。
minute number 是 指定卡片多久之后更新，取值范围：大于等于5，单位：min。

返回值：

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

错误码：

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

错误码ID 错误信息
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.
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 { formProvider } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formId: string = '12400633174999288';
try {
  formProvider.setFormNextRefreshTime(formId, 5).then(() => {
    console.log(`formProvider setFormNextRefreshTime success`);
  }).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})`);
}

formProvider.updateForm

updateForm(formId: string, formBindingData: formBindingData.FormBindingData,callback: AsyncCallback&lt;void&gt;): void

更新指定的卡片，使用callback异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

参数：

参数名 类型 必填 说明
formId string 是 请求更新的卡片标识。
formBindingData formBindingData.FormBindingData 是 用于更新的数据。
callback AsyncCallback&lt;void&gt; 是 回调函数。

错误码：

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

错误码ID 错误信息
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.
16501001 The ID of the form to be operated does not exist.
16501003 The form cannot be operated by the current application.

示例：

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

let formId: string = '12400633174999288';
try {
  let param: Record<string, string> = {
    'temperature': '22c',
    'time': '22:00'
  }
  let obj: formBindingData.FormBindingData = formBindingData.createFormBindingData(param);
  formProvider.updateForm(formId, obj, (error: BusinessError) => {
    if (error) {
      console.error(`callback error, code: ${error.code}, message: ${error.message})`);
      return;
    }
    console.log(`formProvider updateForm success`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

formProvider.updateForm

updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise&lt;void&gt;

更新指定的卡片，使用Promise异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

参数：

参数名 类型 必填 说明
formId string 是 请求更新的卡片标识。
formBindingData formBindingData.FormBindingData 是 用于更新的数据。

返回值：

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

错误码：

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

错误码ID 错误信息
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.
16501001 The ID of the form to be operated does not exist.
16501003 The form cannot be operated by the current application.

示例：

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

let formId: string = '12400633174999288';
let param: Record<string, string> = {
  'temperature': '22c',
  'time': '22:00'
}
let obj: formBindingData.FormBindingData = formBindingData.createFormBindingData(param);
try {
  formProvider.updateForm(formId, obj).then(() => {
    console.log(`formProvider updateForm success`);
  }).catch((error: BusinessError) => {
    console.error(`promise 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})`);
}

formProvider.getFormsInfo

getFormsInfo(callback: AsyncCallback&lt;Array&lt;formInfo.FormInfo&gt;&gt;): void

获取设备上当前应用程序的卡片信息，使用callback异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

参数：

参数名 类型 必填 说明
callback AsyncCallback&lt;Array&lt;formInfo.FormInfo&gt;&gt; 是 回调函数。返回查询到的卡片信息。

错误码：

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

错误码ID 错误信息
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 { BusinessError } from '@kit.BasicServicesKit';

try {
  formProvider.getFormsInfo((error, data) => {
    if (error) {
      console.error(`callback error, code: ${error.code}, message: ${error.message})`);
      return;
    }
    console.log(`formProvider getFormsInfo, data: ${JSON.stringify(data)}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

formProvider.getFormsInfo

getFormsInfo(filter: formInfo.FormInfoFilter, callback: AsyncCallback&lt;Array&lt;formInfo.FormInfo&gt;&gt;): void

获取设备上当前应用程序的卡片信息，并筛选符合条件的信息，使用callback异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

参数：

参数名 类型 必填 说明
filter formInfo.FormInfoFilter 是 卡片信息过滤器。
callback AsyncCallback&lt;Array&lt;formInfo.FormInfo&gt;&gt; 是 回调函数。返回查询到符合条件的卡片信息。

错误码：

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

错误码ID 错误信息
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 { formInfo, formProvider } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

const filter: formInfo.FormInfoFilter = {
  // get info of forms belong to module entry.
  moduleName: 'entry'
};
try {
  formProvider.getFormsInfo(filter, (error, data) => {
    if (error) {
      console.error(`callback error, code: ${error.code}, message: ${error.message})`);
      return;
    }
    console.log(`formProvider getFormsInfo, data: ${JSON.stringify(data)}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

formProvider.getFormsInfo

getFormsInfo(filter?: formInfo.FormInfoFilter): Promise&lt;Array&lt;formInfo.FormInfo&gt;&gt;

获取设备上当前应用程序的卡片信息，使用Promise异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

参数：

参数名 类型 必填 说明
filter formInfo.FormInfoFilter 否 卡片信息过滤器, 默认为空，不进行过滤。

返回值：

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

错误码：

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

错误码ID 错误信息
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 { formInfo, formProvider } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

const filter: formInfo.FormInfoFilter = {
  // get info of forms belong to module entry.
  moduleName: 'entry'
};
try {
  formProvider.getFormsInfo(filter).then((data: formInfo.FormInfo[]) => {
    console.log(`formProvider getFormsInfo, data: ${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})`);
}

formProvider.openFormEditAbility18+

openFormEditAbility(abilityName: string, formId: string, isMainPage?: boolean): void

打开卡片编辑页。

系统能力： SystemCapability.Ability.Form

参数：

参数名 类型 必填 说明
abilityName string 是 编辑页的ability名称。
formId string 是 卡片标识。
isMainPage boolean 否 是否为主编辑页，true表示是主编辑页，false表示不是主编辑页。
默认值：true。

错误码：

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

错误码ID 错误信息
801 Capability not supported.function openFormEditAbility can not work correctly due to limited device capabilities.
16500050 IPC connection error.
16500100 Failed to obtain the configuration information.
16501000 An internal functional error occurred.
16501003 The form cannot be operated by the current application.
16501007 Form is not trust.

示例：

import { router } from '@kit.ArkUI';

const TAG: string = 'FormEditDemo-Page] -->';

@Entry
@Component
struct Page {
  @State message: string = 'Hello World';

  aboutToAppear(): void {
    console.log(`${TAG} aboutToAppear.....`);
  }

  build() {
    RelativeContainer() {
      Text(this.message)
        .id('PageHelloWorld')
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
        .alignRules({
          center: { anchor: '__container__', align: VerticalAlign.Top },
          middle: { anchor: '__container__', align: HorizontalAlign.Center }
        })
        .onClick(() => {
          console.log(`${TAG} onClick.....`);
          formProvider.openFormEditAbility('ability://EntryFormEditAbility', '1386529921');
        })
    }
    .height('100%')
    .width('100%')
  }
}

formProvider.openFormManager18+

openFormManager(want: Want): void

打开卡片管理页面。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

参数：

参数名 类型 必填 说明
want Want 是 打开卡片管理页面的请求中的want参数，需包含以下字段。
bundleName: 卡片所属应用的包名。
abilityName: 卡片所属的ability名称。
parameters:
- ohos.extra.param.key.form_dimension: 卡片尺寸。
- ohos.extra.param.key.form_name: 卡片名称。
- ohos.extra.param.key.module_name: 卡片所属的模块名称。

错误码：

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

错误码ID 错误信息
16500050 IPC connection error.
16500100 Failed to obtain the configuration information.
16501000 An internal functional error occurred.

示例：

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

const want: Want = {
  bundleName: 'com.example.formbutton',
  abilityName: 'EntryFormAbility',
  parameters: {
    'ohos.extra.param.key.form_dimension': 2,
    'ohos.extra.param.key.form_name': 'widget',
    'ohos.extra.param.key.module_name': 'entry'
  },
};
try {
  formProvider.openFormManager(want);
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

formProvider.getPublishedFormInfoById18+

getPublishedFormInfoById(formId: string): Promise&lt;formInfo.FormInfo&gt;

获取设备上当前应用程序已经加桌的指定卡片信息，使用Promise异步回调。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

参数：

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

返回值：

类型 说明
Promise&lt;formInfo.FormInfo&gt; Promise对象。返回查询到符合条件的卡片信息。

错误码：

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

错误码ID 错误信息
16500050 IPC connection error.
16500100 Failed to obtain the configuration information.
16501000 An internal functional error occurred.

示例：

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

const formId: string = '388344236';
try {
  formProvider.getPublishedFormInfoById(formId).then((data: formInfo.FormInfo) => {
    console.log(`formProvider getPublishedFormInfoById, data: ${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})`);
}

formProvider.getPublishedFormInfos18+

getPublishedFormInfos(): Promise&lt;Array&lt;formInfo.FormInfo&gt;&gt;

获取设备上当前应用程序所有已经加桌的卡片信息，使用Promise异步回调。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

返回值：

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

错误码：

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

错误码ID 错误信息
16500050 IPC connection error.
16500100 Failed to obtain the configuration information.
16501000 An internal functional error occurred.

示例：

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

try {
  formProvider.getPublishedFormInfos().then((data: formInfo.FormInfo[]) => {
    console.log(`formProvider getPublishedFormInfos, data: ${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})`);
}

formProvider.requestOverflow20+

requestOverflow(formId: string, overflowInfo: formInfo.OverflowInfo): Promise&lt;void&gt;

卡片提供方发起互动卡片动效请求，只针对场景动效类型互动卡片生效，使用Promise异步回调。

系统能力： SystemCapability.Ability.Form

参数：

参数名 类型 必填 说明
formId string 是 卡片id标识。
overflowInfo formInfo.OverflowInfo 是 动效请求参数信息。

返回值：

类型 说明
Promise&lt;void&gt; 无返回结果的Promise对象。

错误码：

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

错误码ID 错误信息
801 Capability not supported.function requestOverflow 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 { formInfo, formProvider } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formId: string = '12400633174999288';
let overflowInfo: formInfo.OverflowInfo = {
  area: {
    left: -10,
    top: -10,
    width: 180,
    height: 180
  },
  duration: 1000,
};

try {
  formProvider.requestOverflow(formId, overflowInfo).then(() => {
    console.info('requestOverflow 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})`);
}

formProvider.cancelOverflow20+

cancelOverflow(formId: string): Promise&lt;void&gt;

卡片提供方发起取消互动卡片动效请求，只针对场景动效类型互动卡片生效，使用Promise异步回调。

系统能力： SystemCapability.Ability.Form

参数：

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

返回值：

类型 说明
Promise&lt;void&gt; 无返回结果的Promise对象。

错误码：

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

错误码ID 错误信息
801 Capability not supported.function cancelOverflow 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.cancelOverflow(formId).then(() => {
    console.info('cancelOverflow 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})`);
}

你可能感兴趣的鸿蒙文章

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

harmony 鸿蒙卡片错误码

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

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

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

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

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

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

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

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

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/nnSSVK
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录