@ohos.app.form.formHost (formHost)

The formHost module provides APIs related to the widget host, which is an application that displays the widget content and controls the position where the widget is displayed. You can use the APIs to delete, release, and update widgets installed by the same user, and obtain widget information and status.

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.

The APIs provided by this module are system APIs.

Modules to Import

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

deleteForm

deleteForm(formId: string, callback: AsyncCallback<void>): void

Deletes a widget. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.
callback AsyncCallback<void> Yes Callback used to return the result. If the widget is deleted, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.deleteForm(formId, (error: Base.BusinessError) => {
  if (error) {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  } else {
    console.log('formHost deleteForm success');
  }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

deleteForm

deleteForm(formId: string): Promise<void>

Deletes a widget. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
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.

Parameters

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

try {
  let formId: string = '12400633174999288';
  formHost.deleteForm(formId).then(() => {
    console.log('formHost deleteForm success');
  }).catch((error: Base.BusinessError) => {
    console.error(`formHost deleteForm, error: ${JSON.stringify(error)}`);
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

releaseForm

releaseForm(formId: string, callback: AsyncCallback<void>): void

Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager still retains the widget cache and storage information. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.
callback AsyncCallback<void> Yes Callback used to return the result. If the widget is released, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.releaseForm(formId, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

releaseForm

releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void

Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.
isReleaseCache boolean Yes Whether to release the cache.
callback AsyncCallback<void> Yes Callback used to return the result. If the widget is released, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.releaseForm(formId, true, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

releaseForm

releaseForm(formId: string, isReleaseCache?: boolean): Promise<void>

Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.
isReleaseCache boolean No Whether to release the cache. The default value is false.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.releaseForm(formId, true).then(() => {
    console.log('formHost releaseForm success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

requestForm

requestForm(formId: string, callback: AsyncCallback<void>): void

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

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.
callback AsyncCallback<void> Yes Callback used to return the result. If the widget is updated, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.requestForm(formId, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

requestForm

requestForm(formId: string): Promise<void>

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

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.requestForm(formId).then(() => {
    console.log('formHost requestForm success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

castToNormalForm

castToNormalForm(formId: string, callback: AsyncCallback<void>): void

Converts a temporary widget to a normal one. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.
callback AsyncCallback<void> Yes Callback used to return the result. If the widget is converted to a normal one, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.castToNormalForm(formId, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

castToNormalForm

castToNormalForm(formId: string): Promise<void>

Converts a temporary widget to a normal one. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

try {
  let formId: string = '12400633174999288';
  formHost.castToNormalForm(formId).then(() => {
    console.log('formHost castTempForm success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

notifyVisibleForms

notifyVisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void

Instructs the widget framework to make a widget visible. After this API is called, onVisibilityChange is invoked to notify the widget provider. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.
callback AsyncCallback<void> Yes Callback used to return the result. If a notification is sent to the widget framework to make the widget visible, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.

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

Example

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

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyVisibleForms(formId, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

notifyVisibleForms

notifyVisibleForms(formIds: Array<string>): Promise<void>

Instructs the widget framework to make a widget visible. After this API is called, onVisibilityChange is invoked to notify the widget provider. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.

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

Example

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

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyVisibleForms(formId).then(() => {
    console.log('formHost notifyVisibleForms success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

notifyInvisibleForms

notifyInvisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void

Instructs the widget framework to make a widget invisible. After this API is called, onVisibilityChange is invoked to notify the widget provider. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.
callback AsyncCallback<void> Yes Callback used to return the result. If a notification is sent to the widget framework to make the widget invisible, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.

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

Example

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

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyInvisibleForms(formId, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

notifyInvisibleForms

notifyInvisibleForms(formIds: Array<string>): Promise<void>

Instructs the widget framework to make a widget invisible. After this API is called, onVisibilityChange is invoked to notify the widget provider. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.

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

Example

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

try {
  let formId: string[] = ['12400633174999288'];
  formHost.notifyInvisibleForms(formId).then(() => {
    console.log('formHost notifyInvisibleForms success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

enableFormsUpdate

enableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void

Instructs the widget framework to make a widget updatable. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.
callback AsyncCallback<void> Yes Callback used to return the result. If a notification is sent to the widget framework to make the widget updatable, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.
16501003 The form can not be operated by the current application.

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

Example

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

try {
  let formId: string[] = ['12400633174999288'];
  formHost.enableFormsUpdate(formId, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

enableFormsUpdate

enableFormsUpdate(formIds: Array<string>): Promise<void>

Instructs the widget framework to make a widget updatable. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.
16501003 The form can not be operated by the current application.

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

Example

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

try {
  let formId: string[] = ['12400633174999288'];
  formHost.enableFormsUpdate(formId).then(() => {
    console.log('formHost enableFormsUpdate success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

disableFormsUpdate

disableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void

Instructs the widget framework to make a widget not updatable. After this API is called, the widget cannot receive updates from the widget provider. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.
callback AsyncCallback<void> Yes Callback used to return the result. If a notification is sent to the widget framework to make the widget not updatable, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.disableFormsUpdate(formId, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

disableFormsUpdate

disableFormsUpdate(formIds: Array<string>): Promise<void>

Instructs the widget framework to make a widget not updatable. After this API is called, the widget cannot receive updates from the widget provider. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

try {
  let formId: string[] = ['12400633174999288'];
  formHost.disableFormsUpdate(formId).then(() => {
    console.log('formHost disableFormsUpdate success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

isSystemReady

isSystemReady(callback: AsyncCallback<void>): void

Checks whether the system is ready. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result. If the check is successful, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
202 The application is not a system application.
401 If the input parameter is not valid parameter.

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

Example

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

try {
  formHost.isSystemReady((error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

isSystemReady

isSystemReady(): Promise<void>

Checks whether the system is ready. This API uses a promise to return the result.

System capability: SystemCapability.Ability.Form

Return value

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

Error codes

Error Code ID Error Message
202 The application is not a system application.

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

Example

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

try {
  formHost.isSystemReady().then(() => {
    console.log('formHost isSystemReady success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

getAllFormsInfo

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

Obtains the widget information provided by all applications on the device. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
callback AsyncCallback<Array<formInfo.FormInfo>> Yes Callback used to return the result. If the widget information is obtained, error is undefined and data is the information obtained; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.

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

Example

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

try {
  formHost.getAllFormsInfo((error: Base.BusinessError, data: formInfo.FormInfo[]) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log(`formHost getAllFormsInfo, data: ${JSON.stringify(data)}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

getAllFormsInfo

getAllFormsInfo(): Promise<Array<formInfo.FormInfo>>

Obtains the widget information provided by all applications on the device. This API uses a promise to return the result.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System capability: SystemCapability.Ability.Form

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
16500050 An IPC connection error happened.
16500060 A service connection error happened, please try again later.
16501000 An internal functional error occurred.

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

Example

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

try {
  formHost.getAllFormsInfo().then((data: formInfo.FormInfo[]) => {
    console.log(`formHost getAllFormsInfo data: ${JSON.stringify(data)}`);
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

getFormsInfo

getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void

Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
bundleName string Yes Bundle name of the application.
callback AsyncCallback<Array<formInfo.FormInfo>> Yes Callback used to return the result. If the widget information is obtained, error is undefined and data is the information obtained; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.

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

Example

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

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', (error: Base.BusinessError, data: formInfo.FormInfo[]) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log(`formHost 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(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void

Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
bundleName string Yes Bundle name of the application.
moduleName string Yes Module name.
callback AsyncCallback<Array<formInfo.FormInfo>> Yes Callback used to return the result. If the widget information is obtained, error is undefined and data is the information obtained; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.

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

Example

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

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry', (error: Base.BusinessError, data: formInfo.FormInfo[]) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log('formHost 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(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>>

Obtains the widget information provided by a given application on the device. This API uses a promise to return the result.

Required permissions: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
bundleName string Yes Bundle name of the application.
moduleName string No Module name. By default, no value is passed.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.

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

Example

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

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data: formInfo.FormInfo[]) => {
    console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`);
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

deleteInvalidForms

deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void

Deletes invalid widgets from the list. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of valid widget IDs.
callback AsyncCallback<number> Yes Callback used to return the result. If the invalid widgets are deleted, error is undefined and data is the number of widgets deleted; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.

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

Example

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

try {
  let formIds: string[] = new Array('12400633174999288', '12400633174999289');
  formHost.deleteInvalidForms(formIds, (error: Base.BusinessError, data: number) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log(`formHost deleteInvalidForms, data: ${JSON.stringify(data)}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

deleteInvalidForms

deleteInvalidForms(formIds: Array<string>): Promise<number>

Deletes invalid widgets from the list. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of valid widget IDs.

Return value

Type Description
Promise<number> Promise used to return the number of widgets deleted.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.

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

Example

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

try {
  let formIds: string[] = new Array('12400633174999288', '12400633174999289');
  formHost.deleteInvalidForms(formIds).then((data: number) => {
    console.log(`formHost deleteInvalidForms, data: ${JSON.stringify(data)}`);
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

acquireFormState

acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void

Obtains the widget state. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
want Want Yes Want information carried to query the widget state. The information must contain the bundle name, ability name, module name, widget name, and widget dimensions.
callback AsyncCallback<formInfo.FormStateInfo> Yes Callback used to return the result. If the widget state is obtained, error is undefined and data is the widget state obtained; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.

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

Example

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

let want: Want = {
  'deviceId': '',
  'bundleName': 'ohos.samples.FormApplication',
  'abilityName': 'FormAbility',
  'parameters': {
    'ohos.extra.param.key.module_name': 'entry',
    'ohos.extra.param.key.form_name': 'widget',
    'ohos.extra.param.key.form_dimension': 2
  }
};
try {
  formHost.acquireFormState(want, (error:Base.BusinessError, data: formInfo.FormStateInfo) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log(`formHost acquireFormState, data: ${JSON.stringify(data)}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

acquireFormState

acquireFormState(want: Want): Promise<formInfo.FormStateInfo>

Obtains the widget state. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
want Want Yes Want information carried to query the widget state. The information must contain the bundle name, ability name, module name, widget name, and widget dimensions.

Return value

Type Description
Promise<formInfo.FormStateInfo> Promise used to return the widget state obtained.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.

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

Example

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

let want: Want = {
  'deviceId': '',
  'bundleName': 'ohos.samples.FormApplication',
  'abilityName': 'FormAbility',
  'parameters': {
    'ohos.extra.param.key.module_name': 'entry',
    'ohos.extra.param.key.form_name': 'widget',
    'ohos.extra.param.key.form_dimension': 2
  }
};
try {
  formHost.acquireFormState(want).then((data: formInfo.FormStateInfo) => {
    console.log(`formHost acquireFormState, data: ${JSON.stringify(data)}`);
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

on('formUninstall')

on(type: 'formUninstall', callback: Callback<string>): void

Subscribes to widget uninstall events. This API uses an asynchronous callback to return the result.

NOTE

Widget uninstall is different from widget removal. When an application is uninstalled, the corresponding widget is automatically uninstalled.

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
type string Yes Event type. The value 'formUninstall' indicates a widget uninstall event.
callback Callback<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.

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

Example

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

formHost.on('formUninstall', (formId: string) => {
  console.log(`formHost on formUninstall, formId: ${formId}`);
});

off('formUninstall')

off(type: 'formUninstall', callback?: Callback<string>): void

Unsubscribes from widget uninstall events. This API uses an asynchronous callback to return the result.

NOTE

Widget uninstall is different from widget removal. When an application is uninstalled, the corresponding widget is automatically uninstalled.

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
type string Yes Event type. The value 'formUninstall' indicates a widget uninstall event.
callback Callback<string> No Callback used to return the widget ID. If it is left unspecified, it indicates the callback for all the events that have been subscribed.
To cancel the subscription with a given callback, this parameter must be set to the same value as callback in on('formUninstall').

Error codes

Error Code ID Error Message
202 The application is not a system application.
401 If the input parameter is not valid parameter.

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

Example

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

formHost.off('formUninstall', (formId: string) => {
  console.log(`formHost on formUninstall, formId: ${formId}`);
});

notifyFormsVisible

notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void

Instructs the widgets to make themselves visible. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.
isVisible boolean Yes Whether to make the widgets visible.
callback AsyncCallback<void> Yes Callback used to return the result. If the notification is sent, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.
16501003 The form can not be operated by the current application.

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

Example

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

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsVisible(formIds, true, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

notifyFormsVisible

notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void>

Instructs the widgets to make themselves visible. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.
isVisible boolean Yes Whether to make the widgets visible.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.
16501003 The form can not be operated by the current application.

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

Example

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

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsVisible(formIds, true).then(() => {
    console.log('formHost notifyFormsVisible success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

notifyFormsEnableUpdate

notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void

Instructs the widgets to enable or disable updates. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.
isEnableUpdate boolean Yes Whether to make the widgets updatable.
callback AsyncCallback<void> Yes Callback used to return the result. If the notification is sent, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.
16501003 The form can not be operated by the current application.

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

Example

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

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsEnableUpdate(formIds, true, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

notifyFormsEnableUpdate

notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void>

Instructs the widgets to enable or disable updates. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes List of widget IDs.
isEnableUpdate boolean Yes Whether to make the widgets updatable.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.
16501003 The form can not be operated by the current application.

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

Example

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

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsEnableUpdate(formIds, true).then(() => {
    console.log('formHost notifyFormsEnableUpdate success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

shareForm

shareForm(formId: string, deviceId: string, callback: AsyncCallback<void>): void

Shares a specified widget with a remote device. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM and ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.
deviceId string Yes Remote device ID.
callback AsyncCallback<void> Yes Callback used to return the result. If the widget is shared, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

let formId: string = '12400633174999288';
let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2';
try {
  formHost.shareForm(formId, deviceId, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

shareForm

shareForm(formId: string, deviceId: string): Promise<void>

Shares a specified widget with a remote device. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM and ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.
deviceId string Yes Remote device ID.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 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.
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 formHost from '@ohos.app.form.formHost';
import Base from '@ohos.base';

let formId: string = '12400633174999288';
let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2';
try {
  formHost.shareForm(formId, deviceId).then(() => {
    console.log('formHost shareForm success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

notifyFormsPrivacyProtected

notifyFormsPrivacyProtected(formIds: Array<string>, isProtected: boolean, callback: AsyncCallback<void>): void

Notifies that the privacy protection status of the specified widgets changes. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes ID of the widgets.
isProtected boolean Yes Whether privacy protection is enabled.
callback AsyncCallback<void> Yes Callback used to return the result. If privacy protection is set successfully, error is undefined; otherwise, error is an error object.

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.

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

Example

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

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsPrivacyProtected(formIds, true, (error: Base.BusinessError) => {
    if (error) {
      console.error(`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}`);
}

notifyFormsPrivacyProtected

notifyFormsPrivacyProtected(formIds: Array<string>, isProtected: boolean): Promise<void>

Notifies that the privacy protection status of the specified widgets changes. This API uses a promise to return the result.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formIds Array<string> Yes ID of the widgets.
isProtected boolean Yes Whether privacy protection is enabled.

Return value

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

Error codes

Error Code ID Error Message
201 Permissions denied.
202 The application is not a system application.
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.
16501000 An internal functional error occurred.

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

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

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsPrivacyProtected(formIds, true).then(() => {
    console.log('formHost notifyFormsPrivacyProtected success');
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}

acquireFormData10+

acquireFormData(formId: string, callback: AsyncCallback<{[key: string]: Object}>): void

Requests data from the widget provider. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.
callback AsyncCallback<{[key: string]: Object} Yes Callback used to return the API call result and the shared data.

Error codes

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

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

Example

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

let formId: string = '12400633174999288';
try {
  formHost.acquireFormData(formId, (error, data) => {
    if (error) {
      console.error(`error, code: ${error.code}, message: ${error.message}`);
    } else {
      console.log(`formHost acquireFormData, data: ${JSON.stringify(data)}`);
    }
  });
} catch(error) {
  console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`);
}

acquireFormData10+

acquireFormData(formId: string): Promise<{[key: string]: Object}>

Requests data from the widget provider. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name Type Mandatory Description
formId string Yes Widget ID.

Return value

Type Description
Promise<{[key: string]: Object}> Promise used to return the API call result and the shared data.

Error codes

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

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

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

let formId: string = '12400633174999288';
try {
  formHost.acquireFormData(formId).then((data) => {
    console.log('formHost acquireFormData success' + data);
  }).catch((error: Base.BusinessError) => {
    console.error(`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}`);
}