js-apis-formprovider.md

FormProvider

The FormProvider module provides APIs related to the widget provider. You can use the APIs to update a widget, set the next refresh time for a widget, obtain widget information, and release a widget release.

NOTE

The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import formProvider from '@ohos.application.formProvider';

Required Permissions

None.

setFormNextRefreshTime

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

Sets the next refresh time for a widget. This API uses an asynchronous callback to return the result.

System capability

SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
formId	string	Yes	ID of a widget.
minute	number	Yes	Refresh interval, in minutes. The value must be greater than or equal to 5.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

var formId = "12400633174999288";
formProvider.setFormNextRefreshTime(formId, 5, (error, data) => {
    if (error.code) {
        console.log('formProvider setFormNextRefreshTime, error:' + JSON.stringify(error));
    }
});

setFormNextRefreshTime

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

Sets the next refresh time for a widget. This API uses a promise to return the result.

System capability

SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
formId	string	Yes	ID of a widget.
minute	number	Yes	Refresh interval, in minutes. The value must be greater than or equal to 5.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Example

var formId = "12400633174999288";
formProvider.setFormNextRefreshTime(formId, 5).then(() => {
    console.log('formProvider setFormNextRefreshTime success');
}).catch((error) => {
    console.log('formProvider setFormNextRefreshTime, error:' + JSON.stringify(error));
});

updateForm

updateForm(formId: string, formBindingData: formBindingData.FormBindingData,callback: AsyncCallback<void>): void;

Updates a widget. This API uses an asynchronous callback to return the result.

System capability

SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
formId	string	Yes	ID of the widget to update.
formBindingData	FormBindingData	Yes	Data to be used for the update.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

import formBindingData from '@ohos.application.formBindingData';
var formId = "12400633174999288";
let obj = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"});
formProvider.updateForm(formId, obj, (error, data) => {
    if (error.code) {
        console.log('formProvider updateForm, error:' + JSON.stringify(error));
    }
});

updateForm

updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise<void>;

Updates a widget. This API uses a promise to return the result.

System capability

SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
formId	string	Yes	ID of the widget to update.
formBindingData	FormBindingData	Yes	Data to be used for the update.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Example

import formBindingData from '@ohos.application.formBindingData';
var formId = "12400633174999288";
let obj = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"});
formProvider.updateForm(formId, obj).then(() => {
    console.log('formProvider updateForm success');
}).catch((error) => {
    console.log('formProvider updateForm, error:' + JSON.stringify(error));
});

getFormsInfo⁹⁺

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

Obtains the application's widget information on the device. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<FormInfo>>	Yes	Callback used to return the widget information.

Example

formProvider.getFormsInfo((error, data) => {
    if (error.code) {
        console.log('formProvider getFormsInfo, error:' + JSON.stringify(error));
    } else {
        console.log('formProvider getFormsInfo, data:' + JSON.stringify(data));
    }
});

getFormsInfo⁹⁺

getFormsInfo(filter: formInfo.FormInfoFilter, callback: AsyncCallback<Array<formInfo.FormInfo>>): void;

Obtains the application's widget information that meets a filter criterion on the device. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
filter	formInfo.FormInfoFilter	Yes	Filter criterion.
callback	AsyncCallback<Array<FormInfo>>	Yes	Callback used to return the widget information.

Example

const filter : formInfo.FormInfoFilter = {
    moduleName : "entry"
};
formProvider.getFormsInfo(filter, (error, data) => {
    if (error.code) {
        console.log('formProvider getFormsInfo, error:' + JSON.stringify(error));
    } else {
        console.log('formProvider getFormsInfo, data:' + JSON.stringify(data));
    }
});

getFormsInfo⁹⁺

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

Obtains the application's widget information on the device. This API uses a promise to return the result.

System capability: SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
filter	formInfo.FormInfoFilter	No	Filter criterion.

Return value

Type	Description
Promise<Array<FormInfo>>	Promise used to return the widget information.

Example

const filter : formInfo.FormInfoFilter = {
    moduleName : "entry"
};
formProvider.getFormsInfo(filter).then((data) => {
    console.log('formProvider getFormsInfo, data:' + JSON.stringify(data));
}).catch((error) => {
    console.log('formProvider getFormsInfo, error:' + JSON.stringify(error));
});

requestPublishForm⁹⁺

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

Requests to publish a widget carrying data to the widget host. This API uses an asynchronous callback to return the result.

System capability

SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Information about the target widget. abilityName: ability of the target widget. parameters: "ohos.extra.param.key.form_dimension" "ohos.extra.param.key.form_name" "ohos.extra.param.key.module_name"
formBindingData	FormBindingData	Yes	Data used for creating the widget.
callback	AsyncCallback<string>	Yes	Callback used to return the widget ID.

Example

import formBindingData from '@ohos.application.formBindingData';
var 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"
    }
};
let obj = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"});
formProvider.requestPublishForm(want, obj, (error, data) => {
    if (error.code) {
        console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error));
    } else {
        console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data));
    }
});

requestPublishForm⁹⁺

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

Requests to publish a widget to the widget host. This API uses an asynchronous callback to return the result.

System capability

SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Information about the target widget. abilityName: ability of the target widget. parameters: "ohos.extra.param.key.form_dimension" "ohos.extra.param.key.form_name" "ohos.extra.param.key.module_name"
callback	AsyncCallback<string>	Yes	Callback used to return the widget ID.

Example

var 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"
    }
};
formProvider.requestPublishForm(want, (error, data) => {
    if (error.code) {
        console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error));
    } else {
        console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data));
    }
});

requestPublishForm⁹⁺

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

Requests to publish a widget to the widget host. This API uses a promise to return the result.

System capability

SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Information about the target widget. abilityName: ability of the target widget. parameters: "ohos.extra.param.key.form_dimension" "ohos.extra.param.key.form_name" "ohos.extra.param.key.module_name"
formBindingData	FormBindingData	No	Data used for creating the widget.

Return value

Type	Description
Promise<string>	Promise used to return the widget ID.

Example

var 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"
    }
};
formProvider.requestPublishForm(want).then((data) => {
    console.log('formProvider requestPublishForm success, form ID is :' + JSON.stringify(data));
}).catch((error) => {
    console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error));
});

isRequestPublishFormSupported⁹⁺

isRequestPublishFormSupported(callback: AsyncCallback<boolean>): void;

Checks whether a widget can be published to the widget host. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<boolean>	Yes	Callback used to return the result.

Example

formProvider.isRequestPublishFormSupported((error, isSupported) => {
  if (error.code) {
    console.log('formProvider isRequestPublishFormSupported, error:' + JSON.stringify(error));
  } else {
    if (isSupported) {
      var 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"
      }
      };
      formProvider.requestPublishForm(want, (error, data) => {
        if (error.code) {
          console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error));
        } else {
          console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data));
        }
      });
    }
  }
});

isRequestPublishFormSupported⁹⁺

isRequestPublishFormSupported(): Promise<boolean>;

Checks whether a widget can be published to the widget host. This API uses a promise to return the result.

System capability: SystemCapability.Ability.Form

Return value

Type	Description
Promise<boolean>	Promise used to return the result.

Example

formProvider.isRequestPublishFormSupported().then((isSupported) => {
  if (isSupported) {
    var 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"
    }
    };
    formProvider.requestPublishForm(want).then((data) => {
      console.log('formProvider requestPublishForm success, form ID is :' + JSON.stringify(data));
    }).catch((error) => {
      console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error));
    });
  }
}).catch((error) => {
  console.log('formProvider isRequestPublishFormSupported, error:' + JSON.stringify(error));
});