1# @ohos.app.form.formObserver (formObserver) (System API) 2 3The **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. 4 5> **NOTE** 6> 7> 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. 8> The APIs provided by this module are system APIs. 9 10## Modules to Import 11 12```ts 13import { formObserver } from '@kit.FormKit'; 14``` 15 16## on('formAdd') 17 18 on(type: 'formAdd', observerCallback: Callback<formInfo.RunningFormInfo>): void 19 20Subscribes to widget addition events. This API uses an asynchronous callback to return the information about the new widget. 21 22**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 23 24**System capability**: SystemCapability.Ability.Form 25 26**Parameters** 27 28| Name| Type | Mandatory| Description | 29| ------ | ------ | ---- | ------- | 30| type | string | Yes | Event type. The value **'formAdd'** indicates a widget addition event.| 31| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes| Callback used to return the information about the new widget.| 32 33**Error codes** 34 35For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 36 37| ID| Error Message | 38| -------- | ------------------------------------------------------------ | 39| 202 | The application is not a system application. | 40| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 41 42**Example** 43 44```ts 45import { formInfo, formObserver } from '@kit.FormKit'; 46 47let callback = (data: formInfo.RunningFormInfo) => { 48 console.log(`a new form added, data: ${JSON.stringify(data)}`); 49} 50 51formObserver.on('formAdd', callback); 52``` 53 54## on('formAdd') 55 56 on(type: 'formAdd', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void 57 58Subscribes to widget addition events. This API uses an asynchronous callback to return the information about the new widget. 59 60**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 61 62**System capability**: SystemCapability.Ability.Form 63 64**Parameters** 65 66| Name| Type | Mandatory| Description | 67| ------ | ------ | ---- | ------- | 68| type | string | Yes | Event type. The value **'formAdd'** indicates a widget addition event.| 69| hostBundleName | 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.| 70| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes| Callback used to return the information about the new widget.| 71 72**Error codes** 73 74For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 75 76| ID| Error Message | 77| -------- | ------------------------------------------------------------ | 78| 202 | The application is not a system application. | 79| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 80 81**Example** 82 83```ts 84import { formInfo, formObserver } from '@kit.FormKit'; 85 86let bundleName: string = 'ohos.samples.FormApplication'; 87 88let callback = (data: formInfo.RunningFormInfo) => { 89 console.log(`a new form added, data: ${JSON.stringify(data)}`); 90} 91 92formObserver.on('formAdd', bundleName, callback); 93``` 94 95## off('formAdd') 96 97 off(type: "formAdd", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void 98 99Unsubscribes from widget addition events. This API uses an asynchronous callback to return the information about the new widget. 100 101**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 102 103**System capability**: SystemCapability.Ability.Form 104 105**Parameters** 106 107| Name| Type | Mandatory| Description | 108| ------ | ------ | ---- | ------- | 109| type | string | Yes | Event type. The value **'formAdd'** indicates a widget addition event.| 110| hostBundleName | 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.| 111| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | No| Callback used to return the information about the new 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')**.| 112 113**Error codes** 114 115For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 116 117| ID| Error Message | 118| -------- | ------------------------------------------------------------ | 119| 202 | The application is not a system application. | 120| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 121 122**Example** 123 124```ts 125import { formInfo, formObserver } from '@kit.FormKit'; 126 127let bundleName: string = 'ohos.samples.FormApplication'; 128 129let callback = (data: formInfo.RunningFormInfo) => { 130 console.log(`a new form added, data: ${JSON.stringify(data)}`); 131} 132 133formObserver.off('formAdd', bundleName, callback); 134 135``` 136> **NOTE** 137> 138> **on('formAdd', callback)** and **off('formAdd', callback)** must be used in pairs. 139> **on('formAdd', bundleName, callback)** and **off('formAdd', bundleName, callback)** must be used in pairs. 140> 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()**. 141 142## on('formRemove') 143 144 on(type: 'formRemove', observerCallback: Callback<formInfo.RunningFormInfo>): void 145 146Subscribes to widget removal events. This API uses an asynchronous callback to return the information about the widget removed. 147 148**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 149 150**System capability**: SystemCapability.Ability.Form 151 152**Parameters** 153 154| Name| Type | Mandatory| Description | 155| ------ | ------ | ---- | ------- | 156| type | string | Yes | Event type. The value **'formRemove'** indicates a widget removal event.| 157| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes| Callback used to return the information about the widget removed.| 158 159**Error codes** 160 161For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 162 163| ID| Error Message | 164| -------- | ------------------------------------------------------------ | 165| 202 | The application is not a system application. | 166| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 167 168**Example** 169 170```ts 171import { formInfo, formObserver } from '@kit.FormKit'; 172 173let callback = (data: formInfo.RunningFormInfo) => { 174 console.log(`form deleted, data: ${JSON.stringify(data)}`); 175} 176 177formObserver.on('formRemove', callback); 178``` 179 180## on('formRemove') 181 182 on(type: 'formRemove', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void 183 184Subscribes to widget addition events. This API uses an asynchronous callback to return the information about the widget removed. 185 186**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 187 188**System capability**: SystemCapability.Ability.Form 189 190**Parameters** 191 192| Name| Type | Mandatory| Description | 193| ------ | ------ | ---- | ------- | 194| type | string | Yes | Event type. The value **'formRemove'** indicates a widget removal event.| 195| hostBundleName | 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.| 196| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes| Callback used to return the information about the widget removed.| 197 198**Error codes** 199 200For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 201 202| ID| Error Message | 203| -------- | ------------------------------------------------------------ | 204| 202 | The application is not a system application. | 205| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 206 207**Example** 208 209```ts 210import { formInfo, formObserver } from '@kit.FormKit'; 211 212let bundleName: string = 'ohos.samples.FormApplication'; 213 214let callback = (data: formInfo.RunningFormInfo) => { 215 console.log(`form deleted, data: ${JSON.stringify(data)}`); 216} 217 218formObserver.on('formRemove', bundleName, callback); 219``` 220 221## off('formRemove') 222 223off(type: "formRemove", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void 224 225Unsubscribes from widget removal events. This API uses an asynchronous callback to return the information about the widget removed. 226 227**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 228 229**System capability**: SystemCapability.Ability.Form 230 231**Parameters** 232 233| Name| Type | Mandatory| Description | 234| ------ | ------ | ---- | ------- | 235| type | string | Yes | Event type. The value **'formRemove'** indicates a widget removal event.| 236| hostBundleName | 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.| 237| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | No| Callback used to return the information about the widget removed. 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')**.| 238 239**Error codes** 240 241For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 242 243| ID| Error Message | 244| -------- | ------------------------------------------------------------ | 245| 202 | The application is not a system application. | 246| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 247 248**Example** 249 250```ts 251import { formInfo, formObserver } from '@kit.FormKit'; 252 253let bundleName: string = 'ohos.samples.FormApplication'; 254 255let callback = (data: formInfo.RunningFormInfo) => { 256 console.log(`a new form added, data: ${JSON.stringify(data)}`); 257} 258 259formObserver.off('formRemove', bundleName, callback); 260``` 261> **NOTE** 262> 263> **on('formRemove', callback)** and **off('formRemove', callback)** must be used in pairs. 264> **on('formRemove', bundleName, callback)** and **off('formRemove', bundleName, callback)** must be used in pairs. 265> 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()**. 266 267## on('notifyVisible') 268 269 on(type: 'notifyVisible', observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void 270 271Subscribes to events indicating that a widget becomes visible. This API uses an asynchronous callback to return the result. 272 273The event is triggered when [notifyVisibleForms](js-apis-app-form-formHost-sys.md#notifyvisibleforms) is called to notify that the widget becomes visible. 274 275**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 276 277**System capability**: SystemCapability.Ability.Form 278 279**Parameters** 280 281| Name | Type | Mandatory| Description | 282| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 283| type | string | Yes | Event type. This value **'notifyVisible'** indicates a widget visibility event. | 284| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Yes | Callback used to return an array of widgets that have subscribed to the event. | 285 286**Error codes** 287 288For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 289 290| ID| Error Message | 291| -------- | ------------------------------------------------------------ | 292| 202 | The application is not a system application. | 293| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 294 295**Example** 296 297```ts 298import { formInfo, formObserver } from '@kit.FormKit'; 299 300let callback = (data: formInfo.RunningFormInfo[]) => { 301 console.log(`form change visibility, data: ${JSON.stringify(data)}`); 302} 303 304formObserver.on('notifyVisible', callback); 305 306``` 307 308## on('notifyVisible') 309 310 on(type: 'notifyVisible', hostBundleName: string, observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void 311 312Subscribes to events indicating that a widget becomes visible for a given bundle that functions as the widget host. This API uses an asynchronous callback to return the result. 313 314The event is triggered when [notifyVisibleForms](js-apis-app-form-formHost-sys.md#notifyvisibleforms) is called to notify that the widget becomes visible. 315 316**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 317 318**System capability**: SystemCapability.Ability.Form 319 320**Parameters** 321 322| Name | Type | Mandatory| Description | 323| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 324| type | string | Yes | Event type. This value **'notifyVisible'** indicates a widget visibility event. | 325| hostBundleName | string | Yes | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.| 326| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Yes | Callback used to return an array of widgets that have subscribed to the event. | 327 328**Error codes** 329 330For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 331 332| ID| Error Message | 333| -------- | ------------------------------------------------------------ | 334| 202 | The application is not a system application. | 335| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 336 337 338**Example** 339 340```ts 341import { formInfo, formObserver } from '@kit.FormKit'; 342 343let bundleName: string = 'ohos.samples.FormApplication'; 344 345let callback = (data: formInfo.RunningFormInfo[]) => { 346 console.log(`form change visibility, data: ${JSON.stringify(data)}`); 347} 348 349formObserver.on('notifyVisible', bundleName, callback); 350``` 351 352## off('notifyVisible') 353 354 off(type: "notifyVisible", hostBundleName?: string, observerCallback?: Callback<Array<formInfo.RunningFormInfo>>): void 355 356Unsubscribes from events indicating that a widget becomes visible. This API uses an asynchronous callback to return the result. 357 358**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 359 360**System capability**: SystemCapability.Ability.Form 361 362**Parameters** 363 364| Name | Type | Mandatory| Description | 365| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 366| type | string | Yes | Event type. This value **'notifyVisible'** indicates a widget visibility event.| 367| hostBundleName | 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')**.| 368| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | No | Callback used to return an array of widgets that have unsubscribed from the event. 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')**.| 369 370**Error codes** 371 372For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 373 374| ID| Error Message | 375| -------- | ------------------------------------------------------------ | 376| 202 | The application is not a system application. | 377| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 378 379**Example** 380 381```ts 382import { formInfo, formObserver } from '@kit.FormKit'; 383 384let bundleName: string = 'ohos.samples.FormApplication'; 385 386let callback = (data: formInfo.RunningFormInfo[]) => { 387 console.log(`form change visibility, data: ${JSON.stringify(data)}`); 388} 389 390formObserver.off('notifyVisible', bundleName, callback); 391``` 392 393> **NOTE** 394> 395> **on('notifyVisible', callback)** and **off('notifyVisible', callback)** must be used in pairs. 396> **on('notifyVisible', bundleName, callback)** and **off('notifyVisible', bundleName, callback)** must be used in pairs. 397> 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()**. 398 399## on('notifyInvisible') 400 401 on(type: 'notifyInvisible', observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void 402 403Subscribes to events indicating that a widget becomes invisible. This API uses an asynchronous callback to return the result. 404 405The event is triggered when [notifyInvisibleForms](js-apis-app-form-formHost-sys.md#notifyinvisibleforms) is called to notify that the widget becomes invisible. 406 407**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 408 409**System capability**: SystemCapability.Ability.Form 410 411**Parameters** 412 413| Name | Type | Mandatory| Description | 414| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 415| type | string | Yes | Event type. This value **'notifyInvisible'** indicates a widget invisibility event. | 416| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Yes | Callback used to return an array of widgets that have subscribed to the event. | 417 418**Error codes** 419 420For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 421 422| ID| Error Message | 423| -------- | ------------------------------------------------------------ | 424| 202 | The application is not a system application. | 425| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 426 427**Example** 428 429```ts 430import { formInfo, formObserver } from '@kit.FormKit'; 431 432let callback = (data: formInfo.RunningFormInfo[]) => { 433 console.log(`form change invisibility, data: ${JSON.stringify(data)}`); 434} 435 436formObserver.on('notifyInvisible', callback); 437``` 438 439 440## on('notifyInvisible') 441 442 on(type: 'notifyInvisible', hostBundleName: string, observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void 443 444Subscribes to events indicating that a widget becomes invisible for a given bundle, which functions as the widget host. This API uses an asynchronous callback to return the result. 445 446The event is triggered when [notifyInvisibleForms](js-apis-app-form-formHost-sys.md#notifyinvisibleforms) is called to notify that the widget becomes invisible. 447 448**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 449 450**System capability**: SystemCapability.Ability.Form 451 452**Parameters** 453 454| Name | Type | Mandatory| Description | 455| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 456| type | string | Yes | Event type. This value **'notifyInvisible'** indicates a widget invisibility event. | 457| hostBundleName | string | Yes | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.| 458| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Yes | Callback used to return an array of widgets that have subscribed to the event. | 459 460**Error codes** 461 462For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 463 464| ID| Error Message | 465| -------- | ------------------------------------------------------------ | 466| 202 | The application is not a system application. | 467| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 468 469**Example** 470 471```ts 472import { formInfo, formObserver } from '@kit.FormKit'; 473 474let bundleName: string = 'ohos.samples.FormApplication'; 475 476let callback = (data: formInfo.RunningFormInfo[]) => { 477 console.log(`form change invisibility, data: ${JSON.stringify(data)}`); 478} 479 480formObserver.on('notifyInvisible', bundleName, callback); 481``` 482 483## off('notifyInvisible') 484 485 off(type: "notifyInvisible", hostBundleName?: string, observerCallback?: Callback<Array<formInfo.RunningFormInfo>>): void 486 487Unsubscribes from events indicating that a widget becomes invisible. This API uses an asynchronous callback to return the result. 488 489**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 490 491**System capability**: SystemCapability.Ability.Form 492 493**Parameters** 494 495| Name | Type | Mandatory| Description | 496| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 497| type | string | Yes | Event type. This value **'notifyInvisible'** indicates a widget invisibility event. | 498| hostBundleName | 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')**.<br> | 499| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | No | Callback used to return an array of widgets that have unsubscribed from the event. 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')**.| 500 501**Error codes** 502 503For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 504 505| ID| Error Message | 506| -------- | ------------------------------------------------------------ | 507| 202 | The application is not a system application. | 508| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 509 510**Example** 511 512```ts 513import { formInfo, formObserver } from '@kit.FormKit'; 514 515let bundleName: string = 'ohos.samples.FormApplication'; 516 517let callback = (data: formInfo.RunningFormInfo[]) => { 518 console.log(`form change invisibility, data: ${JSON.stringify(data)}`); 519} 520 521formObserver.off('notifyInvisible', bundleName, callback); 522``` 523 524> **NOTE** 525> 526> **on('notifyInvisible', callback)** and **off('notifyInvisible', callback)** must be used in pairs. 527> **on('notifyInvisible', bundleName, callback)** and **off('notifyInvisible', bundleName, callback)** must be used in pairs. 528> 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()**. 529 530 531## getRunningFormInfos 532 533getRunningFormInfos(callback: AsyncCallback<Array<formInfo.RunningFormInfo>>, hostBundleName?: string): void 534 535Obtains the information about all non-temporary widgets running on the device. This API uses an asynchronous callback to return the result. 536 537**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 538 539**System capability**: SystemCapability.Ability.Form 540 541**Parameters** 542 543| Name| Type | Mandatory| Description | 544| ------ | ------ | ---- | ------- | 545| callback | AsyncCallback<Array<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Yes| Callback used to return the information about all non-temporary widgets. If the widget information is obtained, **error** is **undefined**, and **data** is the information obtained.| 546| 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.| 547 548**Error codes** 549 550For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 551 552| ID| Error Message| 553| -------- | -------- | 554| 201 | Permissions denied. | 555| 202 | The application is not a system application. | 556| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 557| 16500050 | IPC connection error. | 558| 16500060 | Service connection error. | 559 560**Example** 561 562```ts 563import { formInfo, formObserver } from '@kit.FormKit'; 564import { BusinessError } from '@kit.BasicServicesKit'; 565 566try { 567 formObserver.getRunningFormInfos((error: BusinessError, data: formInfo.RunningFormInfo[]) => { 568 if (error) { 569 console.error(`error, code: ${error.code}, message: ${error.message}`); 570 } else { 571 console.log(`formObserver getRunningFormInfos, data: ${JSON.stringify(data)}`); 572 } 573 }, 'com.example.ohos.formjsdemo'); 574} catch(error) { 575 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 576} 577``` 578 579## getRunningFormInfos<sup>11+</sup> 580 581getRunningFormInfos(callback: AsyncCallback<Array<formInfo.RunningFormInfo>>, isUnusedIncluded: boolean, hostBundleName?: string): void 582 583Obtains the information about all non-temporary widgets running on the device. This API uses an asynchronous callback to return the result. 584 585**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 586 587**System capability**: SystemCapability.Ability.Form 588 589**Parameters** 590 591| Name| Type | Mandatory| Description | 592| ------ | ------ | ---- | ------- | 593| callback | AsyncCallback<Array<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Yes| Callback used to return the information about all non-temporary widgets. If the widget information is obtained, **error** is **undefined**, and **data** is the information obtained.| 594| isUnusedIncluded | boolean | Yes| Whether an unused widget is included.| 595| 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.| 596 597**Error codes** 598 599For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 600 601| ID| Error Message| 602| -------- | -------- | 603| 201 | Permissions denied. | 604| 202 | The application is not a system application. | 605| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 606| 16500050 | IPC connection error. | 607| 16500060 | Service connection error. | 608 609**Example** 610 611```ts 612import { formInfo, formObserver } from '@kit.FormKit'; 613import { BusinessError } from '@kit.BasicServicesKit'; 614 615try { 616 formObserver.getRunningFormInfos((error: BusinessError, data: formInfo.RunningFormInfo[]) => { 617 if (error) { 618 console.error(`error, code: ${error.code}, message: ${error.message}`); 619 } else { 620 console.log(`formObserver getRunningFormInfos, data: ${JSON.stringify(data)}`); 621 } 622 }, true, 'com.example.ohos.formjsdemo'); 623} catch(error) { 624 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 625} 626``` 627 628## getRunningFormInfos 629 630getRunningFormInfos(hostBundleName?: string): Promise<Array<formInfo.RunningFormInfo>> 631 632Obtains the information about all non-temporary widgets running on the device. This API uses a promise to return the result. 633 634**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 635 636**System capability**: SystemCapability.Ability.Form 637 638**Parameters** 639 640| Name| Type | Mandatory| Description | 641| ------ | ------ | ---- | ------- | 642| 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.| 643 644**Return value** 645 646| Type | Description | 647| :----------------------------------------------------------- | :---------------------------------- | 648| Promise<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Promise used to return the information about all non-temporary widgets.| 649 650**Error codes** 651 652For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 653 654| ID| Error Message| 655| -------- | -------- | 656| 201 | Permissions denied. | 657| 202 | The application is not a system application. | 658| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 659| 16500050 | IPC connection error. | 660| 16500060 | Service connection error. | 661 662**Example** 663 664```ts 665import { formInfo, formObserver } from '@kit.FormKit'; 666import { BusinessError } from '@kit.BasicServicesKit'; 667 668try { 669 formObserver.getRunningFormInfos('com.example.ohos.formjsdemo').then((data: formInfo.RunningFormInfo[]) => { 670 console.log(`formObserver getRunningFormInfos, data: ${JSON.stringify(data)}`); 671 }).catch((error: BusinessError) => { 672 console.error(`error, code: ${error.code}, message: ${error.message}`); 673 }); 674} catch(error) { 675 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 676} 677``` 678 679## getRunningFormInfos<sup>11+</sup> 680 681getRunningFormInfos(isUnusedIncluded: boolean, hostBundleName?: string): Promise<Array<formInfo.RunningFormInfo>> 682 683Obtains the information about all non-temporary widgets running on the device. This API uses a promise to return the result. 684 685**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 686 687**System capability**: SystemCapability.Ability.Form 688 689**Parameters** 690 691| Name| Type | Mandatory| Description | 692| ------ | ------ | ---- | ------- | 693| isUnusedIncluded | boolean | Yes| Whether an unused widget is included.| 694| 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.| 695 696**Return value** 697 698| Type | Description | 699| :----------------------------------------------------------- | :---------------------------------- | 700| Promise<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Promise used to return the information about all non-temporary widgets.| 701 702**Error codes** 703 704For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 705 706| ID| Error Message| 707| -------- | -------- | 708| 201 | Permissions denied. | 709| 202 | The application is not a system application. | 710| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 711| 16500050 | IPC connection error. | 712| 16500060 | Service connection error. | 713 714**Example** 715 716```ts 717import { formInfo, formObserver } from '@kit.FormKit'; 718import { BusinessError } from '@kit.BasicServicesKit'; 719 720try { 721 formObserver.getRunningFormInfos(true, 'com.example.ohos.formjsdemo').then((data: formInfo.RunningFormInfo[]) => { 722 console.log(`formObserver getRunningFormInfos, data: ${JSON.stringify(data)}`); 723 }).catch((error: BusinessError) => { 724 console.error(`error, code: ${error.code}, message: ${error.message}`); 725 }); 726} catch(error) { 727 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 728} 729``` 730 731## getRunningFormInfosByFilter 732 733getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter): Promise<Array<formInfo.RunningFormInfo>> 734 735Obtains the information about widgets based on the widget provider. This API uses a promise to return the result. 736 737**Model restriction**: This API can be used only in the stage model. 738 739**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 740 741**System capability**: SystemCapability.Ability.Form 742 743**Parameters** 744 745| Name | Type | Mandatory| Description | 746| ----------- | --------------- | ---- | -------------------------------- | 747| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo-sys.md#formproviderfilter10) | Yes | Information about the widget provider.| 748 749**Return value** 750 751| Type | Description | 752| ------------------- | ------------------------- | 753| Promise<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Promise used to return an array of the widgets.| 754 755**Error codes** 756 757For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 758 759| ID| Error Message| 760| -------- | -------- | 761| 201 | Permissions denied. | 762| 202 | The application is not a system application. | 763| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 764| 16500050 | IPC connection error. | 765| 16500100 | Failed to obtain the configuration information. | 766| 16501000 | An internal functional error occurred. | 767 768 769```ts 770import { formInfo, formObserver } from '@kit.FormKit'; 771import { BusinessError } from '@kit.BasicServicesKit'; 772 773let formInstanceFilter: formInfo.FormProviderFilter = { 774 bundleName: "com.example.formprovide", 775 abilityName: "EntryFormAbility", 776 formName: "widget", 777 moduleName: "entry" 778} 779try { 780 formObserver.getRunningFormInfosByFilter(formInstanceFilter).then((data: formInfo.RunningFormInfo[]) => { 781 console.info('formObserver getRunningFormInfosByFilter success, data:' + JSON.stringify(data)); 782 }).catch((error: BusinessError) => { 783 console.error(`error, code: ${error.code}, message: ${error.message}`); 784 }); 785} catch(error) { 786 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 787} 788``` 789 790## getRunningFormInfosByFilter 791 792getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter, callback: AsyncCallback<Array<formInfo.RunningFormInfo>>): void 793 794Obtains the information about widgets based on the widget provider. This API uses an asynchronous callback to return the result. 795 796**Model restriction**: This API can be used only in the stage model. 797 798**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 799 800**System capability**: SystemCapability.Ability.Form 801 802**Parameters** 803 804| Name | Type | Mandatory| Description | 805| ----------- | --------------- | ---- | -------------------------------- | 806| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo-sys.md#formproviderfilter10) | Yes | Information about the widget provider.| 807| callback | AsyncCallback<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Yes| Callback used to used to return an array of the widgets. If the widget information is obtained, **error** is **undefined**, and **data** is the information obtained. Otherwise, **error** is an error object.| 808 809**Error codes** 810 811For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 812 813| ID| Error Message| 814| -------- | -------- | 815| 201 | Permissions denied. | 816| 202 | The application is not a system application. | 817| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 818| 16500050 | IPC connection error. | 819| 16500100 | Failed to obtain the configuration information. | 820| 16501000 | An internal functional error occurred. | 821 822**Example** 823 824```ts 825import { formInfo, formObserver } from '@kit.FormKit'; 826import { BusinessError } from '@kit.BasicServicesKit'; 827 828let formInstanceFilter: formInfo.FormProviderFilter = { 829 bundleName: "com.example.formprovide", 830 abilityName: "EntryFormAbility", 831 formName: "widget", 832 moduleName: "entry" 833} 834try { 835 formObserver.getRunningFormInfosByFilter(formInstanceFilter,(error: BusinessError, data: formInfo.RunningFormInfo[]) => { 836 if (error) { 837 console.error(`error, code: ${error.code}, message: ${error.message}`); 838 } else { 839 console.log(`formObserver getRunningFormInfosByFilter, data: ${JSON.stringify(data)}`); 840 } 841 }); 842} catch(error) { 843 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 844} 845``` 846 847## getRunningFormInfoById 848 849getRunningFormInfoById(formId: string): Promise<formInfo.RunningFormInfo> 850 851Obtains the information about the widget based on the widget ID. This API uses a promise to return the result. 852 853**Model restriction**: This API can be used only in the stage model. 854 855**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 856 857**System capability**: SystemCapability.Ability.Form 858 859**Parameters** 860 861| Name | Type | Mandatory| Description | 862| ----------- | --------------- | ---- | -------------------------------- | 863| formId | string | Yes | Widget ID.| 864 865**Return value** 866 867| Type | Description | 868| ------------------- | ------------------------- | 869| Promise<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Promise used to return the widget information.| 870 871**Error codes** 872 873For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 874 875| ID| Error Message| 876| -------- | -------- | 877| 201 | Permissions denied. | 878| 202 | The application is not a system application. | 879| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 880| 16500050 | IPC connection error. | 881| 16500100 | Failed to obtain the configuration information. | 882| 16501000 | An internal functional error occurred. | 883 884**Example** 885 886```ts 887import { formInfo, formObserver } from '@kit.FormKit'; 888import { BusinessError } from '@kit.BasicServicesKit'; 889 890let formId: string = '12400633174999288'; 891try { 892 formObserver.getRunningFormInfoById(formId).then((data: formInfo.RunningFormInfo) => { 893 console.info('formObserver getRunningFormInfoById success, data:' + JSON.stringify(data)); 894 }).catch((error: BusinessError) => { 895 console.error(`error, code: ${error.code}, message: ${error.message}`); 896 }); 897} catch(error) { 898 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 899} 900``` 901 902## getRunningFormInfoById<sup>11+</sup> 903 904getRunningFormInfoById(formId: string, isUnusedIncluded: boolean): Promise<formInfo.RunningFormInfo> 905 906Obtains the information about the widget based on the widget ID. This API uses a promise to return the result. 907 908**Model restriction**: This API can be used only in the stage model. 909 910**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 911 912**System capability**: SystemCapability.Ability.Form 913 914**Parameters** 915 916| Name | Type | Mandatory| Description | 917| ----------- | --------------- | ---- | -------------------------------- | 918| formId | string | Yes | Widget ID.| 919| isUnusedIncluded | boolean | Yes | Whether an unused widget is included.| 920 921**Return value** 922 923| Type | Description | 924| ------------------- | ------------------------- | 925| Promise<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Promise used to return the widget information.| 926 927**Error codes** 928 929For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 930 931| ID| Error Message| 932| -------- | -------- | 933| 201 | Permissions denied. | 934| 202 | The application is not a system application. | 935| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 936| 16500050 | IPC connection error. | 937| 16500100 | Failed to obtain the configuration information. | 938| 16501000 | An internal functional error occurred. | 939 940**Example** 941 942```ts 943import { formInfo, formObserver } from '@kit.FormKit'; 944import { BusinessError } from '@kit.BasicServicesKit'; 945 946let formId: string = '12400633174999288'; 947try { 948 formObserver.getRunningFormInfoById(formId, true).then((data: formInfo.RunningFormInfo) => { 949 console.info('formObserver getRunningFormInfoById success, data:' + JSON.stringify(data)); 950 }).catch((error: BusinessError) => { 951 console.error(`error, code: ${error.code}, message: ${error.message}`); 952 }); 953} catch(error) { 954 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 955} 956``` 957 958## getRunningFormInfoById 959 960getRunningFormInfoById(formId: string, callback: AsyncCallback<formInfo.RunningFormInfo>): void 961 962Obtains the information about the widget based on the widget ID. This API uses an asynchronous callback to return the result. 963 964**Model restriction**: This API can be used only in the stage model. 965 966**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 967 968**System capability**: SystemCapability.Ability.Form 969 970**Parameters** 971 972| Name | Type | Mandatory| Description | 973| ----------- | --------------- | ---- | -------------------------------- | 974| formId | string | Yes | Widget ID.| 975| callback | AsyncCallback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes| Callback used to used to return the widget information. If the widget information is obtained, **error** is **undefined**, and **data** is the information obtained. Otherwise, **error** is an error object.| 976 977**Error codes** 978 979For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 980 981| ID| Error Message| 982| -------- | -------- | 983| 201 | Permissions denied. | 984| 202 | The application is not a system application. | 985| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 986| 16500050 | IPC connection error. | 987| 16500100 | Failed to obtain the configuration information. | 988| 16501000 | An internal functional error occurred. | 989 990**Example** 991 992```ts 993import { formInfo, formObserver } from '@kit.FormKit'; 994import { BusinessError } from '@kit.BasicServicesKit'; 995 996let formId: string = '12400633174999288'; 997try { 998 formObserver.getRunningFormInfoById(formId,(error: BusinessError, data: formInfo.RunningFormInfo) => { 999 if (error) { 1000 console.error(`error, code: ${error.code}, message: ${error.message}`); 1001 } else { 1002 console.log(`formObserver getRunningFormInfoById, data: ${JSON.stringify(data)}`); 1003 } 1004 }); 1005} catch(error) { 1006 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1007} 1008``` 1009 1010## getRunningFormInfoById<sup>11+</sup> 1011 1012getRunningFormInfoById(formId: string, isUnusedIncluded: boolean, callback: AsyncCallback<formInfo.RunningFormInfo>): void 1013 1014Obtains the information about the widget based on the widget ID. This API uses an asynchronous callback to return the result. 1015 1016**Model restriction**: This API can be used only in the stage model. 1017 1018**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 1019 1020**System capability**: SystemCapability.Ability.Form 1021 1022**Parameters** 1023 1024| Name | Type | Mandatory| Description | 1025| ----------- | --------------- | ---- | -------------------------------- | 1026| formId | string | Yes | Widget ID.| 1027| isUnusedIncluded | boolean | Yes | Whether an unused widget is included.| 1028| callback | AsyncCallback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes| Callback used to used to return the widget information. If the widget information is obtained, **error** is **undefined**, and **data** is the information obtained. Otherwise, **error** is an error object.| 1029 1030**Error codes** 1031 1032For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1033 1034| ID| Error Message| 1035| -------- | -------- | 1036| 201 | Permissions denied. | 1037| 202 | The application is not a system application. | 1038| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1039| 16500050 | IPC connection error. | 1040| 16500100 | Failed to obtain the configuration information. | 1041| 16501000 | An internal functional error occurred. | 1042 1043**Example** 1044 1045```ts 1046import { formInfo, formObserver } from '@kit.FormKit'; 1047import { BusinessError } from '@kit.BasicServicesKit'; 1048 1049let formId: string = '12400633174999288'; 1050try { 1051 formObserver.getRunningFormInfoById(formId, true, (error: BusinessError, data: formInfo.RunningFormInfo) => { 1052 if (error) { 1053 console.error(`error, code: ${error.code}, message: ${error.message}`); 1054 } else { 1055 console.log(`formObserver getRunningFormInfoById, data: ${JSON.stringify(data)}`); 1056 } 1057 }); 1058} catch(error) { 1059 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1060} 1061``` 1062 1063## on('router')<sup>11+</sup> 1064 1065 on(type: 'router', observerCallback: Callback<formInfo.RunningFormInfo>): void 1066 1067Subscribes to widget router events. This API uses an asynchronous callback to return the information of the widget that triggers the router event. 1068 1069**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 1070 1071**System capability**: SystemCapability.Ability.Form 1072 1073**Parameters** 1074 1075| Name | Type | Mandatory| Description | 1076| ---------------- | ---------------------------------------- | ---- | ----------------------------------------- | 1077| type | string | Yes | Event type. The value **'router'** indicates a widget router event. | 1078| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes | Callback used to return the widget information.| 1079 1080**Error codes** 1081 1082For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1083 1084| ID| Error Message| 1085| -------- | -------- | 1086| 202 | The application is not a system application. | 1087| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1088 1089**Example** 1090 1091```ts 1092import { formInfo, formObserver } from '@kit.FormKit'; 1093 1094let callback = (data: formInfo.RunningFormInfo) => { 1095 console.log('Router event listening in registered form.' + JSON.stringify(data)); 1096}; 1097formObserver.on('router', callback); 1098``` 1099 1100## on('router')<sup>11+</sup> 1101 1102 on(type: 'router', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void 1103 1104Subscribes to widget router events for a given bundle that functions as the widget host. This API uses an asynchronous callback to return the information of the widget that triggers the router event. 1105 1106**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 1107 1108**System capability**: SystemCapability.Ability.Form 1109 1110**Parameters** 1111 1112| Name | Type | Mandatory| Description | 1113| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1114| type | string | Yes | Event type. The value **'router'** indicates a widget router event. | 1115| hostBundleName | string | Yes | Name of the bundle that functions as the widget host. If no value is passed in, widget router events of all widget hosts are subscribed to.| 1116| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes | Callback used to return the widget information. | 1117 1118**Error codes** 1119 1120For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1121 1122| ID| Error Message| 1123| -------- | -------- | 1124| 202 | The application is not a system application. | 1125| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1126 1127**Example** 1128 1129```ts 1130import { formInfo, formObserver } from '@kit.FormKit'; 1131 1132let hostBundleName: string = 'ohos.samples.FormApplication'; 1133let callback = (data: formInfo.RunningFormInfo) => { 1134 console.log('Router event listening in registered form.' + JSON.stringify(data)); 1135}; 1136formObserver.on('router', hostBundleName, callback); 1137``` 1138 1139## off('router')<sup>11+</sup> 1140 1141 off(type: "router", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void 1142 1143Unsubscribes from widget router events. This API uses an asynchronous callback to return the information of the widget that triggers the router event. 1144 1145**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 1146 1147**System capability**: SystemCapability.Ability.Form 1148 1149**Parameters** 1150 1151| Name | Type | Mandatory| Description | 1152| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1153| type | string | Yes | Event type. The value **'router'** indicates a widget router event. | 1154| hostBundleName | 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('router')**.<br>If no value is passed in, the subscriptions for all the widget hosts are canceled.| 1155| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | No | Callback used to return the widget information. 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('router')**.| 1156 1157**Error codes** 1158 1159For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1160 1161| ID| Error Message| 1162| -------- | -------- | 1163| 202 | The application is not a system application. | 1164| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1165 1166**Example** 1167 1168```ts 1169import { formInfo, formObserver } from '@kit.FormKit'; 1170 1171let hostBundleName: string = 'ohos.samples.FormApplication'; 1172let callback = (data: formInfo.RunningFormInfo) => { 1173 console.log('Unregister form router event Listening.' + JSON.stringify(data)); 1174}; 1175formObserver.off('router', hostBundleName, callback); 1176``` 1177 1178## on('message')<sup>11+</sup> 1179 1180 on(type: 'message', observerCallback: Callback<formInfo.RunningFormInfo>): void 1181 1182Subscribes to widget message events. This API uses an asynchronous callback to return the information of the widget that triggers the message event. 1183 1184**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 1185 1186**System capability**: SystemCapability.Ability.Form 1187 1188**Parameters** 1189 1190| Name | Type | Mandatory| Description | 1191| ---------------- | ---------------------------------------- | ---- | ----------------------------------------- | 1192| type | string | Yes | Event type. This value **'message'** indicates a widget message event. | 1193| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes | Callback used to return the widget information.| 1194 1195**Error codes** 1196 1197For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1198 1199| ID| Error Message| 1200| -------- | -------- | 1201| 202 | The application is not a system application. | 1202| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1203 1204**Example** 1205 1206```ts 1207import { formInfo, formObserver } from '@kit.FormKit'; 1208 1209let callback = (data: formInfo.RunningFormInfo) => { 1210 console.log('Message event listening in registered form.' + JSON.stringify(data)); 1211}; 1212formObserver.on('message', callback); 1213``` 1214 1215## on('message')<sup>11+</sup> 1216 1217 on(type: 'message', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void 1218 1219Subscribes to widget message events for a given bundle that functions as the widget host. This API uses an asynchronous callback to return the information of the widget that triggers the message event. 1220 1221**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 1222 1223**System capability**: SystemCapability.Ability.Form 1224 1225**Parameters** 1226 1227| Name | Type | Mandatory| Description | 1228| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1229| type | string | Yes | Event type. This value **'message'** indicates a widget message event. | 1230| hostBundleName | string | Yes | Name of the bundle that functions as the widget host. If no value is passed in, widget message events of all widget hosts are subscribed to.| 1231| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes | Callback used to return the widget information. | 1232 1233**Error codes** 1234 1235For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1236 1237| ID| Error Message| 1238| -------- | -------- | 1239| 202 | The application is not a system application. | 1240| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1241 1242**Example** 1243 1244```ts 1245import { formInfo, formObserver } from '@kit.FormKit'; 1246 1247let hostBundleName: string = 'ohos.samples.FormApplication'; 1248let callback = (data: formInfo.RunningFormInfo) => { 1249 console.log('Message event listening in registered form.' + JSON.stringify(data)); 1250}; 1251formObserver.on('message', hostBundleName, callback); 1252``` 1253 1254## off('message')<sup>11+</sup> 1255 1256 off(type: "message", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void 1257 1258Unsubscribes from widget message events. This API uses an asynchronous callback to return the information of the widget that triggers the message event. 1259 1260**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 1261 1262**System capability**: SystemCapability.Ability.Form 1263 1264**Parameters** 1265 1266| Name | Type | Mandatory| Description | 1267| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1268| type | string | Yes | Event type. This value **'message'** indicates a widget message event. | 1269| hostBundleName | 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('message')**.<br>If no value is passed in, the subscriptions for all the widget hosts are canceled.| 1270| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | No | Callback used to return the widget information. 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('message')**.| 1271 1272**Error codes** 1273 1274For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1275 1276| ID| Error Message| 1277| -------- | -------- | 1278| 202 | The application is not a system application. | 1279| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1280 1281**Example** 1282 1283```ts 1284import { formInfo, formObserver } from '@kit.FormKit'; 1285 1286let hostBundleName: string = 'ohos.samples.FormApplication'; 1287let callback = (data: formInfo.RunningFormInfo) => { 1288 console.log('Unregister form Message event Listening.' + JSON.stringify(data)); 1289}; 1290formObserver.off('message', hostBundleName, callback); 1291``` 1292 1293## on('call')<sup>11+</sup> 1294 1295 on(type: 'call', observerCallback: Callback<formInfo.RunningFormInfo>): void 1296 1297Subscribes to widget call events. This API uses an asynchronous callback to return the information of the widget that triggers the call event. 1298 1299**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 1300 1301**System capability**: SystemCapability.Ability.Form 1302 1303**Parameters** 1304 1305| Name | Type | Mandatory| Description | 1306| ---------------- | ---------------------------------------- | ---- | ----------------------------------------- | 1307| type | string | Yes | Event type. This value **'call'** indicates a widget call event. | 1308| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes | Callback used to return the widget information.| 1309 1310**Error codes** 1311 1312For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1313 1314| ID| Error Message| 1315| -------- | -------- | 1316| 202 | The application is not a system application. | 1317| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1318 1319**Example** 1320 1321```ts 1322import { formInfo, formObserver } from '@kit.FormKit'; 1323 1324let callback = (data: formInfo.RunningFormInfo) => { 1325 console.log('Call event listening in registered form.' + JSON.stringify(data)); 1326}; 1327formObserver.on('call', callback); 1328``` 1329 1330## on('call')<sup>11+</sup> 1331 1332 on(type: 'call', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void 1333 1334Subscribes to widget call events for a given bundle that functions as the widget host. This API uses an asynchronous callback to return the information of the widget that triggers the call event. 1335 1336**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 1337 1338**System capability**: SystemCapability.Ability.Form 1339 1340**Parameters** 1341 1342| Name | Type | Mandatory| Description | 1343| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1344| type | string | Yes | Event type. This value **'call'** indicates a widget call event. | 1345| hostBundleName | string | Yes | Name of the bundle that functions as the widget host. If no value is passed in, widget call events of all widget hosts are subscribed to.| 1346| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Yes | Callback used to return the widget information. | 1347 1348**Error codes** 1349 1350For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1351 1352| ID| Error Message| 1353| -------- | -------- | 1354| 202 | The application is not a system application. | 1355| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1356 1357**Example** 1358 1359```ts 1360import { formInfo, formObserver } from '@kit.FormKit'; 1361 1362let hostBundleName: string = 'ohos.samples.FormApplication'; 1363let callback = (data: formInfo.RunningFormInfo) => { 1364 console.log('Call event listening in registered form.' + JSON.stringify(data)); 1365}; 1366formObserver.on('call', hostBundleName, callback); 1367``` 1368 1369## off('call')<sup>11+</sup> 1370 1371 off(type: "call", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void 1372 1373Unsubscribes from widget call events. This API uses an asynchronous callback to return the information of the widget that triggers the call event. 1374 1375**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 1376 1377**System capability**: SystemCapability.Ability.Form 1378 1379**Parameters** 1380 1381| Name | Type | Mandatory| Description | 1382| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1383| type | string | Yes | Event type. This value **'call'** indicates a widget call event. | 1384| hostBundleName | 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('message')**.<br>If no value is passed in, the subscriptions for all the widget hosts are canceled.| 1385| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | No | Callback used to return the widget information. 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('call')**.| 1386 1387**Error codes** 1388 1389For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1390 1391| ID| Error Message| 1392| -------- | -------- | 1393| 202 | The application is not a system application. | 1394| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1395 1396**Example** 1397 1398```ts 1399import { formInfo, formObserver } from '@kit.FormKit'; 1400 1401let hostBundleName: string = 'ohos.samples.FormApplication'; 1402let callback = (data: formInfo.RunningFormInfo) => { 1403 console.log('Unregister form Call event Listening.' + JSON.stringify(data)); 1404}; 1405formObserver.off('call', hostBundleName, callback); 1406``` 1407