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

  • 2022-12-05
  • 浏览 (507)

@ohos.app.form.formProvider (formProvider)

FormProvider模块提供了卡片提供方相关接口的能力,开发者在开发卡片时,可通过该模块提供接口实现更新卡片、设置卡片更新时间、获取卡片信息、请求发布卡片等。

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

导入模块

import formProvider from '@ohos.app.form.formProvider';

setFormNextRefreshTime

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

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

系统能力: SystemCapability.Ability.Form

参数:

参数名 类型 必填 说明
formId string 卡片标识。
minute number 指定多久之后更新,单位分钟,大于等于5。
callback AsyncCallback<void> 回调函数。

错误码:

错误码ID 错误信息
401 If the input parameter is not valid parameter.
16500050 An IPC connection error happened.
16500060 A service connection error happened, please try again later.
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 upper bound.
16501003 The form can not be operated by the current application.

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

示例:

import Base from '@ohos.base';

let formId: string = '12400633174999288';
try {
  formProvider.setFormNextRefreshTime(formId, 5, (error: Base.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 Base.BusinessError).code}, message: ${(error as Base.BusinessError).message})`);
}

setFormNextRefreshTime

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

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

系统能力: SystemCapability.Ability.Form

参数:

参数名 类型 必填 说明
formId string 卡片标识。
minute number 指定多久之后更新,单位分钟,大于等于5。

返回值:

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

错误码:

错误码ID 错误信息
401 If the input parameter is not valid parameter.
16500050 An IPC connection error happened.
16500060 A service connection error happened, please try again later.
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 upper bound.
16501003 The form can not be operated by the current application.

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

示例:

import Base from '@ohos.base';

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

updateForm

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

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

系统能力: SystemCapability.Ability.Form

参数:

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

错误码:

错误码ID 错误信息
401 If the input parameter is not valid parameter.
16500050 An IPC connection error happened.
16500060 A service connection error happened, please try again later.
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 can not be operated by the current application.

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

示例:

import formBindingData from '@ohos.app.form.formBindingData';
import Base from '@ohos.base';

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

updateForm

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

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

系统能力: SystemCapability.Ability.Form

参数:

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

返回值:

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

错误码:

错误码ID 错误信息
401 If the input parameter is not valid parameter.
16500050 An IPC connection error happened.
16500060 A service connection error happened, please try again later.
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 can not be operated by the current application.

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

示例:

import formBindingData from '@ohos.app.form.formBindingData';
import Base from '@ohos.base';

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: Base.BusinessError) => {
    console.error(`promise error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message})`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message})`);
}

getFormsInfo

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

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

系统能力: SystemCapability.Ability.Form

参数:

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

错误码: |错误码ID|错误信息| |——–|——–| |401|If the input parameter is not valid parameter.| |16500050|An IPC connection error happened.| |16500100|Failed to obtain the configuration information.| |16501000|An internal functional error occurred.|

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

示例:

import Base from '@ohos.base';

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

getFormsInfo

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

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

系统能力: SystemCapability.Ability.Form

参数:

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

错误码:

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

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

示例:

import Base from '@ohos.base';
import formInfo from '@ohos.app.form.formInfo';

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

getFormsInfo

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

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

系统能力: SystemCapability.Ability.Form

参数:

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

返回值:

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

错误码:

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

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

示例:

import formInfo from '@ohos.app.form.formInfo';
import Base from '@ohos.base';

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: Base.BusinessError) => {
    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message})`);
}

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&lt;string&gt; 回调函数。返回卡片标识。

错误码:

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

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

示例:

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

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: Base.BusinessError, data: string) => {
    if (error) {
      console.error(`callback error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message})`);
      return;
    }
    console.log('formProvider requestPublishForm, form ID is: ${JSON.stringify(data)}');
  });
} catch (error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message})`);
}

requestPublishForm

requestPublishForm(want: Want, callback: AsyncCallback&lt;string&gt;): 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&lt;string&gt; 回调函数。返回卡片标识。

错误码:

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

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

示例:

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

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

requestPublishForm

requestPublishForm(want: Want, formBindingData?: formBindingData.FormBindingData): Promise&lt;string&gt;

请求发布一张卡片到使用方。使用方通常为桌面,使用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&lt;string&gt; Promise对象。返回卡片标识。

错误码:

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

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

示例:

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

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: Base.BusinessError) => {
    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message})`);
}

isRequestPublishFormSupported

isRequestPublishFormSupported(callback: AsyncCallback&lt;boolean&gt;): void

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

系统接口: 此接口为系统接口。

系统能力: SystemCapability.Ability.Form

参数:

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

错误码:

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

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

示例:

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

try {
  formProvider.isRequestPublishFormSupported((error: Base.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: Base.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 Base.BusinessError).code}, message: ${(error as Base.BusinessError).message})`);
        }
      }
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message})`);
}

isRequestPublishFormSupported

isRequestPublishFormSupported(): Promise&lt;boolean&gt;

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

系统接口: 此接口为系统接口。

系统能力: SystemCapability.Ability.Form

返回值:

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

错误码:

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

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

示例:

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

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: Base.BusinessError) => {
          console.error(`promise error, code: ${error.code}, message: ${error.message})`);
        });
      } catch (error) {
        console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message})`);
      }
    }
  }).catch((error: Base.BusinessError) => {
    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message})`);
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙接口

harmony 鸿蒙系统公共事件定义(待停用)

harmony 鸿蒙系统公共事件定义

harmony 鸿蒙开发说明

harmony 鸿蒙企业设备管理概述(仅对系统应用开放)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)

harmony 鸿蒙@ohos.distributedBundle (分布式包管理)

harmony 鸿蒙@ohos.bundle (Bundle模块)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)

0  赞