@ohos.app.form.formHost (formHost) (System API)

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 '@kit.FormKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

requestFormWithParams¹²⁺

requestFormWithParams(formId: string, wantParams?: Record): Promise<void>

Carries parameters to request 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.
wantParams	Record	No	Parameters used for the update.

Return value

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

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formId: string = '12400633174999288';
  let params: Record<string, Object> = {
    'ohos.extra.param.key.host_bg_inverse_color': '#ff000000' as Object
  };
  formHost.requestFormWithParams(formId, params).then(() => {
    console.log('formHost requestFormWithParams success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as 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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501002	The number of forms exceeds the maximum allowed.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501002	The number of forms exceeds the maximum allowed.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

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

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

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

try {
  formHost.getAllFormsInfo((error: 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 BusinessError).code}, message: ${(error as 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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

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

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

Example

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

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', (error: 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 BusinessError).code}, message: ${(error as 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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

Example

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

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry', (error: 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 BusinessError).code}, message: ${(error as 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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

Example

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

try {
  formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data: formInfo.FormInfo[]) => {
    console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`);
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

getFormsInfo¹²⁺

getFormsInfo(filter: formInfo.FormInfoFilter): 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
filter	formInfo.FormInfoFilter	Yes	Filter criterion.

Return value

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

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

Example

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

const filter: formInfo.FormInfoFilter = {
  bundleName: 'ohos.samples.FormApplication',
  moduleName: 'entry',
  supportedDimensions: [FormDimension.Dimension_1_2, FormDimension.Dimension_2_2, FormDimension.Dimension_2_4]
};
try {
  formHost.getFormsInfo(filter).then((data: formInfo.FormInfo[]) => {
    console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`);
  }).catch((error: BusinessError) => {
    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = new Array('12400633174999288', '12400633174999289');
  formHost.deleteInvalidForms(formIds, (error: 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 BusinessError).code}, message: ${(error as 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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

Example

import { formHost, formInfo } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

Example

import { formHost, formInfo } from '@kit.FormKit';
import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

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

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

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

Error Code ID	Error Message
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.

Example

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

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formIds: string[] = new Array('12400633174999288', '12400633174999289');
try {
  formHost.notifyFormsPrivacyProtected(formIds, true).then(() => {
    console.log('formHost notifyFormsPrivacyProtected success');
  }).catch((error: BusinessError) => {
    console.error(`error, code: ${error.code}, message: ${error.message}`);
  });
} catch(error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

acquireFormData¹⁰⁺

acquireFormData(formId: string, callback: AsyncCallback<Record<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<Record<string, Object>	Yes	Callback used to return the API call result and the shared data.

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

acquireFormData¹⁰⁺

acquireFormData(formId: string): Promise<Record<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<Record<string, Object>>	Promise used to return the API call result and the shared data.

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16500100	Failed to obtain the configuration information.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

setRouterProxy¹¹⁺

setRouterProxy(formIds: Array&lt;string&gt;, proxy: Callback&lt;Want&gt;, callback: AsyncCallback&lt;void&gt;): void

Sets a router proxy for widgets and obtains the Want information required for redirection. This API uses an asynchronous callback to return the result.

NOTE

• Generally, for a widget added to the home screen, in the case of router-based redirection, the widget framework checks whether the destination is proper and whether the widget has the redirection permission, and then triggers redirection accordingly. For a widget that is added to a widget host and has a router proxy configured, in the case of router-based redirection, the widget framework does not trigger redirection for the widget. Instead, it returns the want parameter containing the destination to the widget host. Therefore, if the widget host wants to use the Want information for redirection, it must have the application redirection permission. For details, see UIAbilityContext.startAbility().

• Only one router proxy can be set for a widget. If multiple proxies are set, only the last proxy takes effect.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
formIds	Array<string>	Yes	Array of widget IDs.
proxy	Callback<Want>	Yes	Callback used to return the Want information required for redirection.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the router proxy is set, error is undefined; otherwise, an exception is thrown.

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

Example

import { common, Want } from '@kit.AbilityKit';
import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct CardExample {
  private context = getContext(this) as common.UIAbilityContext;
  @State formId: number = 0;
  @State fwidth: number = 420;
  @State fheight: number = 280;

  build() {
    Column() {
      FormComponent({
        id: this.formId,
        name: "widget",
        bundle: "com.example.cardprovider",
        ability: "EntryFormAbility",
        module: "entry",
        dimension: FormDimension.Dimension_2_2,
        temporary: false,
      })
        .allowUpdate(true)
        .size({ width: this.fwidth, height: this.fheight })
        .visibility(Visibility.Visible)
        .onAcquired((form) => {
          console.log(`testTag form info : ${JSON.stringify(form)}`);
          this.formId = form.id;
          try {
            let formIds: string[] = [this.formId.toString()];
            formHost.setRouterProxy(formIds, (want: Want) => {
              console.info(`formHost recv router event, want: ${JSON.stringify(want)}`);
              // The widget host processes the redirection.
              this.context.startAbility(want, (err: BusinessError) => {
                console.info(`formHost startAbility error, code: ${err.code}, message: ${err.message}`);
              });
            }, (err: BusinessError) => {
              console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`);
            })
          } catch (e) {
            console.log('formHost setRouterProxy catch exception: ' + JSON.stringify(e));
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

setRouterProxy¹¹⁺

setRouterProxy(formIds: Array&lt;string&gt;, proxy: Callback&lt;Want&gt;): Promise&lt;void&gt;

Sets a router proxy for widgets and obtains the Want information required for redirection. This API uses a promise to return the result.

NOTE

• Generally, for a widget added to the home screen, in the case of router-based redirection, the widget framework checks whether the destination is proper and whether the widget has the redirection permission, and then triggers redirection accordingly. For a widget that is added to a widget host and has a router proxy configured, in the case of router-based redirection, the widget framework does not trigger redirection for the widget. Instead, it returns the want parameter containing the destination to the widget host. Therefore, if the widget host wants to use the Want information for redirection, it must have the application redirection permission. For details, see UIAbilityContext.startAbility().

• Only one router proxy can be set for a widget. If multiple proxies are set, only the last proxy takes effect.

Required permissions: ohos.permission.REQUIRE_FORM

System capability: SystemCapability.Ability.Form

Parameters

Name	Type	Mandatory	Description
formIds	Array<string>	Yes	Array of widget IDs.
proxy	Callback<Want>	Yes	Callback used to return the Want information required for redirection.

Return value

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

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct CardExample {
  private context = getContext(this) as common.UIAbilityContext;
  @State formId: number = 0;
  @State fwidth: number = 420;
  @State fheight: number = 280;

  build() {
    Column() {
      FormComponent({
        id: this.formId,
        name: "widget",
        bundle: "com.example.cardprovider",
        ability: "EntryFormAbility",
        module: "entry",
        dimension: FormDimension.Dimension_2_2,
        temporary: false,
      })
        .allowUpdate(true)
        .size({ width: this.fwidth, height: this.fheight })
        .visibility(Visibility.Visible)
        .onAcquired((form) => {
          console.log(`testTag form info : ${JSON.stringify(form)}`);
          this.formId = form.id;
          try {
            let formIds: string[] = [this.formId.toString()];
            formHost.setRouterProxy(formIds, (want: Want) => {
              console.info(`formHost recv router event, want: ${JSON.stringify(want)}`);
              // The widget host processes the redirection.
              this.context.startAbility(want, (err: BusinessError) => {
                console.info(`formHost startAbility error, code: ${err.code}, message: ${err.message}`);
              });
            }).then(() => {
              console.info('formHost set router proxy success');
            }).catch((err: BusinessError) => {
              console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`);
            })
          } catch (e) {
            console.log('formHost setRouterProxy catch exception: ' + JSON.stringify(e));
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

clearRouterProxy¹¹⁺

clearRouterProxy(formIds:Array&lt;string&gt;, callback: AsyncCallback&lt;void&gt;): void

Clears the router proxy set for widgets. 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	Array of widget IDs.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the router proxy is cleared, error is undefined; otherwise, an exception is thrown.

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.clearRouterProxy(formIds, (err: BusinessError) => {
    if (err) {
      console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

clearRouterProxy¹¹⁺

clearRouterProxy(formIds:Array&lt;string&gt;): Promise&lt;void&gt;

Clears the router proxy set for widgets. 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	Array of widget IDs.

Return value

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

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.clearRouterProxy(formIds).then(() => {
    console.log('formHost clear rourter proxy success');
  }).catch((err: BusinessError) => {
    console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

setFormsRecyclable¹¹⁺

setFormsRecyclable(formIds:Array&lt;string&gt;, callback: AsyncCallback&lt;void&gt;): void

Sets widgets to be recyclable. 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
formIds	Array<string>;	Yes	Array of widget IDs.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the widgets are set to be recyclable, error is undefined; otherwise, an exception is thrown.

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.setFormsRecyclable(formIds, (err: BusinessError) => {
    if (err) {
      console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

setFormsRecyclable¹¹⁺

setFormsRecyclable(formIds:Array&lt;string&gt;): Promise&lt;void&gt;

Sets widgets to be recyclable. 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
formIds	Array<string>	Yes	Array of widget IDs.

Return value

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

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.setFormsRecyclable(formIds).then(() => {
    console.log('setFormsRecyclable success');
  }).catch((err: BusinessError) => {
    console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

recoverForms¹¹⁺

recoverForms(formIds:Array&lt;string&gt;, callback: AsyncCallback&lt;void&gt;): void

Recovers widgets. 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
formIds	Array<string>;	Yes	Array of widget IDs.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the widgets are recovered, error is undefined; otherwise, an exception is thrown.

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.recoverForms(formIds, (err: BusinessError) => {
    if (err) {
      console.error(`recoverForms error, code: ${err.code}, message: ${err.message}`);
    }
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

recoverForms¹¹⁺

recoverForms(formIds: Array&lt;string&gt;): Promise&lt;void&gt;

Recovers recycled widgets and updates their status to non-recyclable, or updates the status of widgets to non-recyclable if the widgets are not recycled. 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
formIds	Array<string>	Yes	Array of widget IDs.

Return value

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

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.recoverForms(formIds).then(() => {
    console.info('recover forms success');
  }).catch((err: BusinessError) => {
    console.error(`formHost recover forms error, code: ${err.code}, message: ${err.message}`);
  });
} catch (e) {
  console.info(`catch error, code: ${e.code}, message: ${e.message}`);
}

recycleForms¹²⁺

recycleForms(formIds: Array&lt;string&gt;): Promise&lt;void&gt;

Recycles widgets, that is, reclaims their memory. 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
formIds	Array<string>	Yes	Array of widget IDs.

Return value

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

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let formIds: string[] = ['12400633174999288'];
  formHost.recycleForms(formIds).then(() => {
    console.info('recycle forms success');
  }).catch((err: BusinessError) => {
    console.error(`formHost recycle forms error, code: ${err.code}, message: ${err.message}`);
  });
} catch (e) {
  console.error(`catch error, code: ${e.code}, message: ${e.message}`);
}

updateFormLocation¹²⁺

updateFormLocation(formId: string, location: formInfo.FormLocation): void;

Updates the widget location.

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.
location	formInfo.FormLocation	Yes	Widget location.

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

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

try {
  let formId: string = '12400633174999288';
  formHost.updateFormLocation(formId, formInfo.FormLocation.SCREEN_LOCK);
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

setPublishFormResult¹²⁺

setPublishFormResult(formId: string, result: formInfo.PublishFormResult): void;

Sets the result for the operation of adding a widget to the home screen.

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.
result	PublishFormResult	Yes	Result of the operation.

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	The application is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.

Example

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

try {
  let formId: string = '12400633174999288';
  let res: formInfo.PublishFormResult = {code: formInfo.PublishFormErrorCode.SUCCESS, message: ''};
  formHost.setPublishFormResult(formId, res);
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

updateFormLockedState¹⁸⁺

updateFormLockedState(formId: string, isLocked: boolean): Promise&lt;void&gt;

Notifies the update of the widget lock state.

If an application is locked, its widget will also be locked and masked in a locked style. To use the widget, you need to enter the password set for the widget.

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.
isLocked	boolean	Yes	A Boolean value indicates whether a widget is in the locked state. The value true indicates that the widget is in the locked state, and the value false indicates the opposite.

Return value |Type |Description | |——————-|————————-| |Promise&lt;void&gt;|Promise that returns no value.|

Error codes

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

Error Code ID	Error Message
201	Permissions denied.
202	caller is not a system app.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16500050	IPC connection error.
16500060	Service connection error.
16501000	An internal functional error occurred.
16501001	The ID of the form to be operated does not exist.
16501003	The form cannot be operated by the current application.

Example

import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';

let formId: string = '12400633174999288';
let isLocked: boolean = true;

try {
  formHost.updateFormLockedState(this.formId, this.isLocked).then(() => {
    console.log(`formHost updateFormLockedState success`);
  });
} catch (error) {
  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Form Kit

harmony 鸿蒙Form Error Codes

harmony 鸿蒙@ohos.app.form.formAgent (FormAgent) (System API)

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

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

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

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

harmony 鸿蒙@ohos.app.form.formInfo (formInfo) (System API)

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

harmony 鸿蒙@ohos.app.form.formObserver (formObserver) (System API)