# @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
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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.
**true**: Release the cache.
**false**: Not 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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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**.
**true**: Release the cache.
**false**: Not release the cache. |
**Return value**
| Type| Description|
| -------- | -------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## requestFormWithParams12+
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
let formId: string = '12400633174999288';
let params: Record = {
'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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md).
| 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**
```ts
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](../errorcode-universal.md).
| Error Code ID| Error Message|
| -------- | -------- |
| 202 | The application is not a system application. |
**Example**
```ts
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](js-apis-app-form-formInfo.md#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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](js-apis-app-form-formInfo.md#forminfo)>> | Promise used to return the information obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](js-apis-app-form-formInfo.md#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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](js-apis-app-form-formInfo.md#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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](js-apis-app-form-formInfo.md#forminfo)>> | Promise used to return the information obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## getFormsInfo12+
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](js-apis-app-form-formInfo.md#forminfofilter) | Yes| Filter criterion.|
**Return value**
| Type | Description |
| :------------ | :---------------------------------- |
| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../apis-ability-kit/js-apis-app-ability-want.md) | 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](js-apis-app-form-formInfo.md#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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../apis-ability-kit/js-apis-app-ability-want.md) | 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](js-apis-app-form-formInfo.md#formstateinfo)> | Promise used to return the widget state obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md).
| 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**
```ts
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](../errorcode-universal.md).
| 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**
```ts
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 the widget is visible.
**true**: The widget is visible.
**false**: The widget is invisible.|
| 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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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 the widget is visible.
**true**: The widget is visible.
**false**: The widget is invisible.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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 the widget can be updated.
**true**: The widget can be updated. **false**: The widget cannot be updated.|
| 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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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 the widget can be updated.
**true**: The widget can be updated.
**false**: The widget cannot be updated.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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\, isProtected: boolean, callback: AsyncCallback\): 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\ | Yes | ID of the widgets.|
| isProtected | boolean | Yes | Whether a widget requires privacy protection.
**true**: The widget requires privacy protection.
**false**: The widget does not require privacy protection.|
| callback | AsyncCallback\ | 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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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\, isProtected: boolean): Promise\
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\ | Yes | ID of the widgets.|
| isProtected | boolean | Yes | Whether a widget requires privacy protection.
**true**: The widget requires privacy protection.
**false**: The widget does not require privacy protection.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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. |
```ts
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}`);
}
```
## acquireFormData10+
acquireFormData(formId: string, callback: AsyncCallback\>): 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\ | 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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## acquireFormData10+
acquireFormData(formId: string): Promise\>
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\>| Promise used to return the API call result and the shared data.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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 (e) {
console.error(`catch error, code: ${e.code}, message: ${e.message}`);
}
```
## setRouterProxy11+
setRouterProxy(formIds: Array<string>, proxy: Callback<Want>, callback: AsyncCallback<void>): 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()](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
import { common, Want } from '@kit.AbilityKit';
import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct CardExample {
private context = this.getUIContext().getHostContext() 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%')
}
}
```
## setRouterProxy11+
setRouterProxy(formIds: Array<string>, proxy: Callback<Want>): Promise<void>
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()](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
import { formHost } from '@kit.FormKit';
import { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct CardExample {
private context = this.getUIContext().getHostContext() 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%')
}
}
```
## clearRouterProxy11+
clearRouterProxy(formIds:Array<string>, callback: AsyncCallback<void>): 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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## clearRouterProxy11+
clearRouterProxy(formIds:Array<string>): Promise<void>
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## setFormsRecyclable11+
setFormsRecyclable(formIds:Array<string>, callback: AsyncCallback<void>): 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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## setFormsRecyclable11+
setFormsRecyclable(formIds:Array<string>): Promise<void>
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## recoverForms11+
recoverForms(formIds:Array<string>, callback: AsyncCallback<void>): 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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## recoverForms11+
recoverForms(formIds: Array<string>): Promise<void>
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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## recycleForms12+
recycleForms(formIds: Array<string>): Promise<void>
Recycles widgets, that is, reclaiming widget 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](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## updateFormLocation12+
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](js-apis-app-form-formInfo-sys.md#formlocation12) | Yes| Widget location.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## setPublishFormResult12+
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 | [formInfo.PublishFormResult](js-apis-app-form-formInfo-sys.md#publishformresult12) | Yes | Result of the operation.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## updateFormLockedState18+
updateFormLockedState(formId: string, isLocked: boolean): Promise<void>
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<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| 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**
```ts
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}`);
}
```
## formHost.on('formOverflow')20+
on(type: 'formOverflow', callback: Callback<formInfo.OverflowRequest>): void
Subscribes to the interactive widget animation request event.
**System capability**: SystemCapability.Ability.Form
**System API**: This is a system API.
**Parameters**
| Name| Type | Mandatory| Description|
|----------|--------|---|---------------------------------------|
| type | string | Yes| Event type. Only **'formOverflow'** is supported, indicating the interactive widget animation request.|
| callback | Callback<[formInfo.OverflowRequest](js-apis-app-form-formInfo-sys.md#overflowrequest20)> | Yes| Callback used by the widget host to process the animation request.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| Error Code ID| Error Message |
|-------|-----------------------------------------------------------------------------------------------------------|
| 202 | The application is not a system application. |
**Example**
```ts
import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
formHost.on('formOverflow', (request: formInfo.OverflowRequest) => {
console.log(`formHost on formOverflow, formId is ${request.formId}`);
});
} catch (error) {
console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}
```
## formHost.off('formOverflow')20+
off(type: 'formOverflow', callback?: Callback<formInfo.OverflowRequest>): void
Unsubscribes from the interactive widget animation request event.
**System capability**: SystemCapability.Ability.Form
**System API**: This is a system API.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ |----|----------------------------------------|
| type | string | Yes | Event type. Only **'formOverflow'** is supported, indicating the interactive widget animation request.|
| callback |Callback<[formInfo.OverflowRequest](js-apis-app-form-formInfo-sys.md#overflowrequest20)> | No | Callback function, which corresponds to the subscribed interactive widget animation request. By default, all registered interactive widget animation request events are deregistered.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| Error Code ID| Error Message |
| --- |-----------------------------------------------------------------------------------------------------------|
| 202 | The application is not a system application. |
**Example**
```ts
import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
formHost.off('formOverflow', (request: formInfo.OverflowRequest) => {
console.log(`formHost off formOverflow, formId is ${request.formId}`);
});
} catch (error) {
console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}
```
## formHost.on('changeSceneAnimationState')20+
on(type: 'changeSceneAnimationState', callback: Callback<formInfo.ChangeSceneAnimationStateRequest>): void
Subscribes to the event of switching the interactive widget state. An interactive widget can be in the active or inactive state. In the inactive state, the interactive widget is the same as a common widget. In the active state, the interactive widget can start the **LiveFormExtensionAbility** process developed by the widget host to implement interactive widget animations.
**System capability**: SystemCapability.Ability.Form
**System API**: This is a system API.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- |------------------------------------------------------|
| type | string | Yes | Event type. The event **'changeSceneAnimationState'** is triggered when the interactive widget state is switched.|
| callback |Callback<[formInfo.ChangeSceneAnimationStateRequest](js-apis-app-form-formInfo-sys.md#changesceneanimationstaterequest20)> | Yes| Callback function, which is used by the widget host to process the state switching request.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| Error Code ID| Error Message |
|-------|-----------------------------------------------------------------------------------------------------------|
| 202 | The application is not a system application. |
**Example**
```ts
import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
formHost.on('changeSceneAnimationState', (request: formInfo.ChangeSceneAnimationStateRequest): void => {
console.log(`formHost on changeSceneAnimationState, formId is ${request.formId}`);
});
} catch (error) {
console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}
```
## formHost.off('changeSceneAnimationState')20+
off(type: 'changeSceneAnimationState', callback: Callback<formInfo.changeSceneAnimationState>): void
Unsubscribes from the event of switching the interactive widget state. An interactive widget can be in the active or inactive state. In the inactive state, the interactive widget is the same as a common widget. In the active state, the interactive widget can start the **LiveFormExtensionAbility** process developed by the widget host to implement interactive widget animations.
**System capability**: SystemCapability.Ability.Form
**System API**: This is a system API.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ |----| ------- |
| type | string | Yes | Event type. The event **'changeSceneAnimationState'** is triggered when the interactive widget state is switched.|
| callback |Callback<[formInfo.ChangeSceneAnimationStateRequest](js-apis-app-form-formInfo-sys.md#changesceneanimationstaterequest20)> | No | Callback function, which corresponds to the request for switching the state of a subscribed interactive widget. By default, all registered interactive widget state switching events are deregistered.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| Error Code ID| Error Message|
| -------- | -------- |
| 202 | The application is not a system application. |
**Example**
```ts
import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
formHost.off('changeSceneAnimationState', (request: formInfo.ChangeSceneAnimationStateRequest): void => {
console.log(`formHost off changeSceneAnimationState, formId is ${request.formId}`);
});
} catch (error) {
console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}
```
## formHost.on('getFormRect')20+
on(type: 'getFormRect', callback: formInfo.GetFormRectInfoCallback): void
Subscribes to the event of requesting widget position and dimension.
**System capability**: SystemCapability.Ability.Form
**System API**: This is a system API.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- |------------------------------------------------------|
| type | string | Yes | Event callback type. The supported event is **'getFormRect'**, indicating requesting widget position and dimension.|
| callback |[formInfo.GetFormRectInfoCallback](js-apis-app-form-formInfo-sys.md#getformrectinfocallback20) | Yes| Callback function used by the widget host to process the request and return the position and dimension of the widget relative to the upper left corner of the screen. The unit is vp.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| Error Code ID| Error Message |
|-------|-----------------------------------------------------------------------------------------------------------|
| 202 | The application is not a system application. |
**Example**
```ts
import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
formHost.on('getFormRect', (formId: string): Promise => {
// The widget host needs to process the request, and calculate and return the widget dimension and position information.
return new Promise((resolve: Function) => {
console.log(`formHost on getFormRect, formId is ${formId}`);
let formRect: formInfo.Rect = {left: 0, top: 0, width: 0, height: 0};
resolve(formRect);
})
});
} catch (error) {
console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}
```
## formHost.off('getFormRect')20+
off(type: 'getFormRect', callback?: formInfo.GetFormRectInfoCallback): void
Unsubscribes from the event of requesting widget position and dimension.
**System capability**: SystemCapability.Ability.Form
**System API**: This is a system API.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ |----| ------- |
| type | string | Yes | Event callback type. The supported event is **'getFormRect'**, indicating requesting widget position and dimension.|
| callback |[formInfo.GetFormRectInfoCallback](js-apis-app-form-formInfo-sys.md#getformrectinfocallback20) | No | Callback function, corresponding to the subscribed widget position and dimension request. By default, all registered widget position and dimension request event callbacks are deregistered.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| Error Code ID| Error Message|
| -------- | -------- |
| 202 | The application is not a system application. |
**Example**
```ts
import { formHost } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
formHost.off('getFormRect');
} catch (error) {
console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}
```
## formHost.updateFormSize20+
updateFormSize(formId: string, newDimension: formInfo.FormDimension, newRect: formInfo.Rect): void
Updates the size of the widget.
**Required permissions**: ohos.permission.REQUIRE_FORM
**System capability**: SystemCapability.Ability.Form
**System API**: This is a system API.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------- |
| formId | string | Yes | Widget ID.|
| newDimension | [formInfo.FormDimension](js-apis-app-form-formInfo.md#formdimension) | Yes| Widget dimension. For example, **Dimension_1_2** indicates a 1 x 2 widget.|
| newRect | [formInfo.Rect](js-apis-app-form-formInfo.md#rect20) | Yes| Widget position information, including the X and Y coordinates of the widget's top-left corner, as well as its width and height.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
| Error Code ID| Error Message|
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | Permissions denied.Called by non-system application. |
| 16501000 | An internal functional error occurred. |
| 16501001 | The ID of the form to be operated does not exist. |
| 16501012 | The dimension parameter is incorrect. |
**Example**
```ts
import { formHost, formInfo } from '@kit.FormKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
let formId: string = '12400633174999288';
let newDimension = formInfo.FormDimension.Dimension_1_2;
let newRect: formInfo.Rect = {left: 1, top: 2, width: 100, height: 100};
formHost.updateFormSize(formId, newDimension, newRect);
} catch (error) {
console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}
```