| callback | AsyncCallback<Array<formInfo.RunningFormInfo>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained.|
| hostBundleName | string | No| Name of the bundle that functions as the widget host. If this parameter is specified, only the information about the non-temporary widgets that are running under the widget host is returned.<br>By default, information about all running non-temporary widgets on the device is returned.|
**Error codes**
For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).
| Error Code ID| Error Message|
| -------- | -------- |
| 16500050 | An IPC connection error happened. |
| 16500060 | A service connection error happened, please try again later. |
| hostBundleName | string | No| Name of the bundle that functions as the widget host. If this parameter is specified, only the information about the non-temporary widgets that are running under the widget host is returned.<br>By default, information about all running non-temporary widgets on the device is returned.|
| type | string | Yes | Event type. The value **'formAdd'** indicates a widget addition event.|
| callback | Callback<formInfo.RunningFormInfo> | Yes| Callback used to return **RunningFormInfo** of the new widget.|
| bundleName | string | No| Name of the bundle that functions as the widget host. By default, widget addition events of all widget hosts are subscribed to.|
**Example**
```ts
importformHostfrom'@ohos.app.form.formHost';
letbundleName='ohos.samples.FormApplication';
letcallback=function(data){
console.log('a new form added, data: ${JSON.stringify(data)');
| type | string | Yes | Event type. The value **'formAdd'** indicates a widget addition event.|
| callback | Callback<formInfo.RunningFormInfo> | No| Callback used to return **RunningFormInfo**. By default, all the subscriptions to the specified event are canceled.<br>To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('formAdd')**.|
| bundleName | string | No| Name of the bundle that functions as the widget host.<br>To cancel the subscription for a given bundle name, this parameter must be set to the same value as **bundleName** in **on('formAdd')**.<br>By default, the subscriptions for all the widget hosts are canceled.|
**Example**
```ts
importformHostfrom'@ohos.app.form.formHost';
letbundleName='ohos.samples.FormApplication';
letcallback=function(data){
console.log('a new form added, data: ${JSON.stringify(data)');
}
formHost.off('formAdd',callback);
formHost.off('formAdd',callback,bundleName);
```
> **NOTE**
>
> - **on('formAdd', callback)** and **off('formAdd', callback)** must be used in pairs.
> - **on('formAdd', callback, bundleName)** and **off('formAdd', callback, bundleName)** must be used in pairs.
> - To cancel the subscription with a given callback or for a given bundle name, the **callback** or **bundleName** parameter in **off()** must be set to the same value as that in **on()**.
| type | string | Yes | Event type. The value **'formRemove'** indicates a widget removal event.|
| callback | Callback<formInfo.RunningFormInfo> | Yes| Callback used to return **RunningFormInfo** of the removed widget.|
| bundleName | string | No| Name of the bundle that functions as the widget host. By default, widget removal events of all widget hosts are subscribed to.|
**Example**
```ts
importformHostfrom'@ohos.app.form.formHost';
letbundleName='ohos.samples.FormApplication';
letcallback=function(data){
console.log('a new form added, data: ${JSON.stringify(data)');
| type | string | Yes | Event type. The value **'formRemove'** indicates a widget removal event.|
| callback | Callback<formInfo.RunningFormInfo> | No| Callback used to return **RunningFormInfo**. By default, all the subscriptions to the specified event are canceled.<br>To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('formRemove')**.|
| bundleName | string | No| Name of the bundle that functions as the widget host.<br>To cancel the subscription for a given bundle name, this parameter must be set to the same value as **bundleName** in **on('formRemove')**.<br>By default, the subscriptions for all the widget hosts are canceled.|
**Example**
```ts
importformHostfrom'@ohos.app.form.formHost';
letbundleName='ohos.samples.FormApplication';
letcallback=function(data){
console.log('a new form added, data: ${JSON.stringify(data)');
}
formHost.off('formRemove',callback);
formHost.off('formRemove',callback,bundleName);
```
> **NOTE**
>
> - **on('formRemove', callback)** and **off('formRemove', callback)** must be used in pairs.
> - **on('formRemove', callback, bundleName)** and **off('formRemove', callback, bundleName)** must be used in pairs.
> - To cancel the subscription with a given callback or for a given bundle name, the **callback** or **bundleName** parameter in **off()** must be set to the same value as that in **on()**.
| Promise<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md#RunningFormInfo)>> | Promise used to return the widget host information obtained.|
**Error codes**
For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).
| Error Code ID| Error Message|
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo.md#formProviderFilter) | Yes | Information about the widget provider.|
| callback | AsyncCallback<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget host 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 [Form Error Codes](../errorcodes/errorcode-form.md).
| Error Code ID| Error Message|
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
| callback | AsyncCallback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)> | Yes| Callback used to return the result. If the widget host 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 [Form Error Codes](../errorcodes/errorcode-form.md).
| Error Code ID| Error Message|
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
| type | string | Yes | Event type. This value **'notifyVisible'** indicates a widget visibility event. |
| callback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes | Callback used to return **RunningFormInfo** of the widget. |
| bundleName | string | No | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.|
| type | string | Yes | Event type. This value **'notifyVisible'** indicates a widget visibility event.|
| callback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | No | Callback registered during the subscription. By default, all the subscriptions to the specified event are canceled.<br> To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('notifyVisible')**.|
| bundleName | string | No | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.<br>To cancel the subscription for a given bundle name, this parameter must be set to the same value as **bundleName** in **on('notifyVisible')**.|
> - **on('notifyVisible', callback)** and **off('notifyVisible', callback)** must be used in pairs.
> - **on('notifyVisible', callback, bundleName)** and **off('notifyVisible', callback, bundleName)** must be used in pairs.
> - To cancel the subscription with a given callback or for a given bundle name, the **callback** or **bundleName** parameter in **off()** must be set to the same value as that in **on()**.
| type | string | Yes | Event type. This value **'notifyInvisible'** indicates a widget invisibility event. |
| callback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes | Callback used to return **RunningFormInfo** of the widget. |
| bundleName | string | No | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.|
| type | string | Yes | Event type. This value **'notifyInvisible'** indicates a widget invisibility event. |
| callback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | No | Callback registered during the subscription. By default, all the subscriptions to the specified event are canceled.<br> To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('notifyInvisible')**.|
| bundleName | string | No | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.<br>To cancel the subscription for a given bundle name, this parameter must be set to the same value as **bundleName** in **on('notifyInvisible')**. |
> - **on('notifyInvisible', callback)** and **off('notifyInvisible', callback)** must be used in pairs.
> - **on('notifyInvisible', callback, bundleName)** and **off('notifyInvisible', callback, bundleName)** must be used in pairs.
> - To cancel the subscription with a given callback or for a given bundle name, the **callback** or **bundleName** parameter in **off()** must be set to the same value as that in **on()**.
The **formObserver** module provides APIs related to widget listeners. You can use the APIs to subscribe to and unsubscribe from widget addition, removal, and visibility change events, and obtain information about running widgets.
> **NOTE**
>
> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs provided by this module are system APIs.
Subscribes to widget addition events for a given bundle that functions as the widget host. This API uses an asynchronous callback to return the result.
| type | string | Yes | Event type. The value **'formAdd'** indicates a widget addition event.|
| bundleName | string | Yes| Name of the bundle that functions as the widget host. If no value is passed in, widget addition events of all widget hosts are subscribed to.|
| callback | Callback<formInfo.RunningFormInfo> | Yes| Callback used to return **RunningFormInfo** of the widget.|
| type | string | Yes | Event type. The value **'formAdd'** indicates a widget addition event.|
| bundleName | string | No| Name of the bundle that functions as the widget host.<br>To cancel the subscription for a given bundle name, this parameter must be set to the same value as **bundleName** in **on('formAdd')**.<br>If no value is passed in, the subscriptions for all the widget hosts are canceled. |
| callback | Callback<formInfo.RunningFormInfo> | No| Callback used to return **RunningFormInfo** of the widget. If no value is passed in, all the subscriptions to the specified event are canceled.<br>To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('formAdd')**. |
console.log('a new form added, data: ${JSON.stringify(data)');
}
formObserver.off('formAdd',callback);
formObserver.off('formAdd',bundleName,callback);
```
> **NOTE**
> **on('formAdd', callback)** and **off('formAdd', callback)** must be used in pairs.
> **on('formAdd', bundleName, callback)** and **off('formAdd', bundleName, callback)** must be used in pairs.
> To cancel the subscription with a given callback or for a given bundle name, the **callback** or **bundleName** parameter in **off()** must be set to the same value as that in **on()**.
Subscribes to widget removal events for a given bundle, which functions as the widget host. This API uses an asynchronous callback to return the result.
| type | string | Yes | Event type. The value **'formRemove'** indicates a widget removal event.|
| bundleName | string | Yes| Name of the bundle that functions as the widget host. If no value is passed in, widget removal events of all widget hosts are subscribed to.|
| callback | Callback<formInfo.RunningFormInfo> | Yes| Callback used to return **RunningFormInfo** of the widget.|
| type | string | Yes | Event type. The value **'formRemove'** indicates a widget removal event.|
| bundleName | string | No| Name of the bundle that functions as the widget host.<br>To cancel the subscription for a given bundle name, this parameter must be set to the same value as **bundleName** in **on('formRemove')**.<br>If no value is passed in, the subscriptions for all the widget hosts are canceled. |
| callback | Callback<formInfo.RunningFormInfo> | No| Callback used to return **RunningFormInfo** of the widget. If no value is passed in, all the subscriptions to the specified event are canceled.<br>To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('formRemove')**. |
> **on('formRemove', callback)** and **off('formRemove', callback)** must be used in pairs.
> **on('formRemove', bundleName, callback)** and **off('formRemove', bundleName, callback)** must be used in pairs.
> To cancel the subscription with a given callback or for a given bundle name, the **callback** or **bundleName** parameter in **off()** must be set to the same value as that in **on()**.
| type | string | Yes | Event type. This value **'notifyVisible'** indicates a widget visibility event. |
| callback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes | Callback used to return **RunningFormInfo** of the widget. |
| type | string | Yes | Event type. This value **'notifyVisible'** indicates a widget visibility event. |
| bundleName | string | Yes | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.|
| callback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes | Callback used to return **RunningFormInfo** of the widget. |
| type | string | Yes | Event type. This value **'notifyVisible'** indicates a widget visibility event.|
| bundleName | string | No | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.<br>To cancel the subscription for a given bundle name, this parameter must be set to the same value as **bundleName** in **on('notifyVisible')**. |
| callback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | No | Callback registered during the subscription. If no value is passed in, all the subscriptions to the specified event are canceled.<br>To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('notifyVisible')**. |
> **on('notifyVisible', callback)** and **off('notifyVisible', callback)** must be used in pairs.
> **on('notifyVisible', bundleName, callback)** and **off('notifyVisible', bundleName, callback)** must be used in pairs.
> To cancel the subscription with a given callback or for a given bundle name, the **callback** or **bundleName** parameter in **off()** must be set to the same value as that in **on()**.
| type | string | Yes | Event type. This value **'notifyInvisible'** indicates a widget invisibility event. |
| callback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes | Callback used to return **RunningFormInfo** of the widget. |
| type | string | Yes | Event type. This value **'notifyInvisible'** indicates a widget invisibility event. |
| bundleName | string | Yes | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.|
| callback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes | Callback used to return **RunningFormInfo** of the widget. |
| type | string | Yes | Event type. This value **'notifyInvisible'** indicates a widget invisibility event. |
| bundleName | string | No | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.<br>To cancel the subscription for a given bundle name, this parameter must be set to the same value as **bundleName** in **on('notifyInvisible')**. |
| callback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | No | Callback registered during the subscription. If no value is passed in, all the subscriptions to the specified event are canceled.<br>To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('notifyInvisible')**. |
> **on('notifyInvisible', callback)** and **off('notifyInvisible', callback)** must be used in pairs.
> **on('notifyInvisible', bundleName, callback)** and **off('notifyInvisible', bundleName, callback)** must be used in pairs.
> To cancel the subscription with a given callback or for a given bundle name, the **callback** or **bundleName** parameter in **off()** must be set to the same value as that in **on()**.
| callback | AsyncCallback<Array<formInfo.RunningFormInfo>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained.|
| hostBundleName | string | No| Name of the bundle that functions as the widget host. If a value is passed in, only the information about the non-temporary widgets that are running under the widget host is returned.<br>If no value is passed in, information about all running non-temporary widgets on the device is returned. |
**Error codes**
For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).
| ID| Error Message|
| -------- | -------- |
| 16500050 | An IPC connection error happened. |
| 16500060 | A service connection error happened, please try again later. |
| hostBundleName | string | No| Name of the bundle that functions as the widget host. If a value is passed in, only the information about the non-temporary widgets that are running under the widget host is returned.<br>If no value is passed in, information about all running non-temporary widgets on the device is returned. |
| Promise<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md#RunningFormInfo)>> | Promise used to return the widget host information obtained.|
**Error codes**
For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).
| ID| Error Message|
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo.md#formProviderFilter) | Yes | Information about the widget provider.|
| callback | AsyncCallback<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget host 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 [Form Error Codes](../errorcodes/errorcode-form.md).
| ID| Error Message|
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
| callback | AsyncCallback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)> | Yes| Callback used to return the result. If the widget host 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 [Form Error Codes](../errorcodes/errorcode-form.md).
| ID| Error Message|
| -------- | -------- |
| 201 | Permissions denied. |
| 202 | The application is not a system application. |
| 401 | If the input parameter is not valid parameter. |
| 16500050 | An IPC connection error happened. |
| 16500100 | Failed to obtain the configuration information. |
| 16501000 | An internal functional error occurred. |
