@ohos.app.form.formProvider (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 request a widget release.

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

Modules to Import

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

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	Widget ID.
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.

Error codes

Error Code ID	Error Message
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.

For details about the error codes, see Form Error Codes.

Example

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>

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	Widget ID.
minute	number	Yes	Refresh interval, in minutes. The value must be greater than or equal to 5.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

Error Code ID	Error Message
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.

For details about the error codes, see Form Error Codes.

Example

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<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	FormBindingData	Yes	Data to be used for the update.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

Error Code ID	Error Message
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.

For details about the error codes, see Form Error Codes.

Example

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<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	FormBindingData	Yes	Data to be used for the update.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

Error Code ID	Error Message
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.

For details about the error codes, see Form Error Codes.

Example

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<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.FormInfo>>	Yes	Callback used to return the information obtained.

Error codes

Error Code ID	Error Message
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.

For details about the error codes, see Form Error Codes.

Example

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<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.FormInfo>>	Yes	Callback used to return the information obtained.

Error codes

Error Code ID	Error Message
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.

For details about the error codes, see Form Error Codes.

Example

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<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. By default, no value is passed, indicating that no filtering is performed.

Return value

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

Error codes

Error Code ID	Error Message
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.

For details about the error codes, see Form Error Codes.

Example

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

Requests to publish a widget carrying data to the widget host (usually the home screen). This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.Form

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Request used for publishing. The following fields must be included: 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.FormBindingData	Yes	Data used for creating the widget.
callback	AsyncCallback<string>	Yes	Callback used to return the widget ID.

Error codes

Error Code ID	Error Message
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.

For details about the error codes, see Form Error Codes.

Example

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<string>): void

Requests to publish a widget to the widget host (usually the home screen). This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.Form

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Request used for publishing. The following fields must be included: 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.

Error codes

Error Code ID	Error Message
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.

For details about the error codes, see Form Error Codes.

Example

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<string>

Requests to publish a widget to the widget host (usually the home screen). This API uses a promise to return the result.

System capability: SystemCapability.Ability.Form

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Request used for publishing. The following fields must be included: 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.FormBindingData	No	Data used for creating the widget. By default, no value is passed, indicating that no data is provided.

Return value

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

Error codes

Error Code ID	Error Message
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.

For details about the error codes, see Form Error Codes.

Example

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<boolean>): void

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

System API: This is a system API.

System capability: SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<boolean>	Yes	Callback used to return whether the widget can be published to the widget host.

Error codes

Error Code ID	Error Message
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.

For details about the error codes, see Form Error Codes.

Example

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<boolean>

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

System API: This is a system API.

System capability: SystemCapability.Ability.Form

Return value

Type	Description
Promise<boolean>	Promise used to return whether the widget can be published to the widget host.

Error codes

Error Code ID	Error Message
202	If the application is not a system application.
16500050	An IPC connection error happened.
16501000	An internal functional error occurred.

For details about the error codes, see Form Error Codes.

Example

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})`);
}