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