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 result. 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> | Yes| Callback used to return **RunningFormInfo** of the widget.| 32 33**Example** 34 35```ts 36import formObserver from '@ohos.app.form.formObserver'; 37import formInfo from '@ohos.app.form.formInfo'; 38 39formObserver.on('formAdd', (data: formInfo.RunningFormInfo) => { 40 console.log(`a new form added, data: ${JSON.stringify(data)}`); 41}); 42``` 43 44## on('formAdd') 45 46 on(type: 'formAdd', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void 47 48Subscribes to widget addition events for a given bundle that functions as the widget host. This API uses an asynchronous callback to return the result. 49 50**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 51 52**System capability**: SystemCapability.Ability.Form 53 54**Parameters** 55 56| Name| Type | Mandatory| Description | 57| ------ | ------ | ---- | ------- | 58| type | string | Yes | Event type. The value **'formAdd'** indicates a widget addition event.| 59| 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.| 60| observerCallback | Callback<formInfo.RunningFormInfo> | Yes| Callback used to return **RunningFormInfo** of the widget.| 61 62 63**Example** 64 65```ts 66import formObserver from '@ohos.app.form.formObserver'; 67import formInfo from '@ohos.app.form.formInfo'; 68 69let bundleName: string = 'ohos.samples.FormApplication'; 70 71formObserver.on('formAdd', bundleName, (data: formInfo.RunningFormInfo) => { 72 console.log(`a new form added, data: ${JSON.stringify(data)}`); 73}); 74``` 75 76## off('formAdd') 77 78 off(type: "formAdd", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void 79 80Unsubscribes from widget addition events. This API uses an asynchronous callback to return the result. 81 82**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 83 84**System capability**: SystemCapability.Ability.Form 85 86**Parameters** 87 88| Name| Type | Mandatory| Description | 89| ------ | ------ | ---- | ------- | 90| type | string | Yes | Event type. The value **'formAdd'** indicates a widget addition event.| 91| 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.| 92| observerCallback | Callback<formInfo.RunningFormInfo> | No| Callback used to return **RunningFormInfo** of the widget. If no value is passed in, all the subscriptions to the specified event are canceled.<br>To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('formAdd')**.| 93 94 95**Example** 96 97```ts 98import formObserver from '@ohos.app.form.formObserver'; 99import formInfo from '@ohos.app.form.formInfo'; 100 101let bundleName: string = 'ohos.samples.FormApplication'; 102formObserver.off('formAdd', bundleName, (data: formInfo.RunningFormInfo) => { 103 console.log(`a new form added, data: ${JSON.stringify(data)}`); 104}); 105 106``` 107> **NOTE** 108> **on('formAdd', callback)** and **off('formAdd', callback)** must be used in pairs. 109> **on('formAdd', bundleName, callback)** and **off('formAdd', bundleName, callback)** must be used in pairs. 110> 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()**. 111 112## on('formRemove') 113 114 on(type: 'formRemove', observerCallback: Callback<formInfo.RunningFormInfo>): void 115 116Subscribes to widget removal events. This API uses an asynchronous callback to return the result. 117 118**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 119 120**System capability**: SystemCapability.Ability.Form 121 122**Parameters** 123 124| Name| Type | Mandatory| Description | 125| ------ | ------ | ---- | ------- | 126| type | string | Yes | Event type. The value **'formRemove'** indicates a widget removal event.| 127| observerCallback | Callback<formInfo.RunningFormInfo> | Yes| Callback used to return **RunningFormInfo** of the widget.| 128 129**Example** 130 131```ts 132import formObserver from '@ohos.app.form.formObserver'; 133import formInfo from '@ohos.app.form.formInfo'; 134 135formObserver.on('formRemove', (data: formInfo.RunningFormInfo) => { 136 console.log(`form deleted, data: ${JSON.stringify(data)}`); 137}); 138``` 139 140## on('formRemove') 141 142 on(type: 'formRemove', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void 143 144Subscribes to widget removal events for a given bundle, which functions as the widget host. This API uses an asynchronous callback to return the result. 145 146**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 147 148**System capability**: SystemCapability.Ability.Form 149 150**Parameters** 151 152| Name| Type | Mandatory| Description | 153| ------ | ------ | ---- | ------- | 154| type | string | Yes | Event type. The value **'formRemove'** indicates a widget removal event.| 155| 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.| 156| observerCallback | Callback<formInfo.RunningFormInfo> | Yes| Callback used to return **RunningFormInfo** of the widget.| 157 158 159**Example** 160 161```ts 162import formObserver from '@ohos.app.form.formObserver'; 163import formInfo from '@ohos.app.form.formInfo'; 164 165let bundleName: string = 'ohos.samples.FormApplication'; 166formObserver.on('formRemove', bundleName, (data: formInfo.RunningFormInfo) => { 167 console.log(`form deleted, data: ${JSON.stringify(data)}`); 168}); 169``` 170 171## off('formRemove') 172 173off(type: "formRemove", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void 174 175Unsubscribes from widget removal events. This API uses an asynchronous callback to return the result. 176 177**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 178 179**System capability**: SystemCapability.Ability.Form 180 181**Parameters** 182 183| Name| Type | Mandatory| Description | 184| ------ | ------ | ---- | ------- | 185| type | string | Yes | Event type. The value **'formRemove'** indicates a widget removal event.| 186| 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.| 187| observerCallback | Callback<formInfo.RunningFormInfo> | No| Callback used to return **RunningFormInfo** of the widget. If no value is passed in, all the subscriptions to the specified event are canceled.<br>To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('formRemove')**.| 188 189**Example** 190 191```ts 192import formObserver from '@ohos.app.form.formObserver'; 193import formInfo from '@ohos.app.form.formInfo'; 194 195let bundleName: string = 'ohos.samples.FormApplication'; 196formObserver.off('formRemove', bundleName, (data: formInfo.RunningFormInfo) => { 197 console.log(`a new form added, data: ${JSON.stringify(data)}`); 198}); 199``` 200> **NOTE** 201> **on('formRemove', callback)** and **off('formRemove', callback)** must be used in pairs. 202> **on('formRemove', bundleName, callback)** and **off('formRemove', bundleName, callback)** must be used in pairs. 203> 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()**. 204 205## on('notifyVisible') 206 207 on(type: 'notifyVisible', observerCallback: Callback<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>>): void 208 209Subscribes to events indicating that a widget becomes visible. 210 211This event is triggered when **notifyVisibleForms** is called to make a widget visible. 212 213**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 214 215**System capability**: SystemCapability.Ability.Form 216 217**Parameters** 218 219| Name | Type | Mandatory| Description | 220| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 221| type | string | Yes | Event type. This value **'notifyVisible'** indicates a widget visibility event. | 222| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes | Callback used to return **RunningFormInfo** of the widget. | 223 224**Example** 225 226```ts 227import formObserver from '@ohos.app.form.formObserver'; 228import formInfo from '@ohos.app.form.formInfo'; 229 230formObserver.on('notifyVisible', (data: formInfo.RunningFormInfo[]) => { 231 console.log(`form change visibility, data: ${JSON.stringify(data)}`); 232}); 233 234``` 235 236## on('notifyVisible') 237 238 on(type: 'notifyVisible', hostBundleName: string, observerCallback: Callback<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>>): void 239 240Subscribes to events indicating that a widget becomes visible for a given bundle, which functions as the widget host. 241 242This event is triggered when **notifyVisibleForms** is called to make a widget visible. 243 244**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 245 246**System capability**: SystemCapability.Ability.Form 247 248**Parameters** 249 250| Name | Type | Mandatory| Description | 251| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 252| type | string | Yes | Event type. This value **'notifyVisible'** indicates a widget visibility event. | 253| hostBundleName | string | Yes | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.| 254| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes | Callback used to return **RunningFormInfo** of the widget. | 255 256 257**Example** 258 259```ts 260import formObserver from '@ohos.app.form.formObserver'; 261import formInfo from '@ohos.app.form.formInfo'; 262 263let bundleName: string = 'ohos.samples.FormApplication'; 264formObserver.on('notifyVisible', bundleName, (data: formInfo.RunningFormInfo[]) => { 265 console.log(`form change visibility, data: ${JSON.stringify(data)}`); 266}); 267``` 268 269## off('notifyVisible') 270 271 off(type: "notifyVisible", hostBundleName?: string, observerCallback?: Callback<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>>): void 272 273Unsubscribes from events indicating that a 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| 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')**.| 285| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | No | Callback registered during the subscription. If no value is passed in, all the subscriptions to the specified event are canceled.<br>To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('notifyVisible')**.| 286 287 288**Example** 289 290```ts 291import formObserver from '@ohos.app.form.formObserver'; 292import formInfo from '@ohos.app.form.formInfo'; 293 294let bundleName: string = 'ohos.samples.FormApplication'; 295formObserver.off('notifyVisible', bundleName, (data: formInfo.RunningFormInfo[]) => { 296 console.log(`form change visibility, data: ${JSON.stringify(data)}`); 297}); 298``` 299 300> **NOTE** 301> **on('notifyVisible', callback)** and **off('notifyVisible', callback)** must be used in pairs. 302> **on('notifyVisible', bundleName, callback)** and **off('notifyVisible', bundleName, callback)** must be used in pairs. 303> 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()**. 304 305## on('notifyInvisible') 306 307 on(type: 'notifyInvisible', observerCallback: Callback<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>>): void 308 309Subscribes to events indicating that a widget becomes invisible. 310 311This event is triggered when **notifyInvisibleForms** is called to make a widget invisible. 312 313**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 314 315**System capability**: SystemCapability.Ability.Form 316 317**Parameters** 318 319| Name | Type | Mandatory| Description | 320| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 321| type | string | Yes | Event type. This value **'notifyInvisible'** indicates a widget invisibility event. | 322| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes | Callback used to return **RunningFormInfo** of the widget. | 323 324**Example** 325 326```ts 327import formObserver from '@ohos.app.form.formObserver'; 328import formInfo from '@ohos.app.form.formInfo'; 329 330formObserver.on('notifyInvisible', (data: formInfo.RunningFormInfo[]) => { 331 console.log(`form change invisibility, data: ${JSON.stringify(data)}`); 332}); 333``` 334 335 336## on('notifyInvisible') 337 338 on(type: 'notifyInvisible', hostBundleName: string, observerCallback: Callback<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>>,): void 339 340Subscribes to events indicating that a widget becomes invisible for a given bundle, which functions as the widget host. 341 342This event is triggered when **notifyInvisibleForms** is called to make a widget invisible. 343 344**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 345 346**System capability**: SystemCapability.Ability.Form 347 348**Parameters** 349 350| Name | Type | Mandatory| Description | 351| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 352| type | string | Yes | Event type. This value **'notifyInvisible'** indicates a widget invisibility event. | 353| hostBundleName | string | Yes | Name of the bundle that functions as the widget host, on which the widget visibility state changes are subscribed.| 354| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes | Callback used to return **RunningFormInfo** of the widget. | 355 356**Example** 357 358```ts 359import formObserver from '@ohos.app.form.formObserver'; 360import formInfo from '@ohos.app.form.formInfo'; 361 362let bundleName: string = 'ohos.samples.FormApplication'; 363formObserver.on('notifyInvisible', bundleName, (data: formInfo.RunningFormInfo[]) => { 364 console.log(`form change invisibility, data: ${JSON.stringify(data)}`); 365}); 366``` 367 368## off('notifyInvisible') 369 370 off(type: "notifyInvisible", hostBundleName?: string, observerCallback?: Callback<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>>): void 371 372Unsubscribes from events indicating that a widget becomes invisible. 373 374**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 375 376**System capability**: SystemCapability.Ability.Form 377 378**Parameters** 379 380| Name | Type | Mandatory| Description | 381| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 382| type | string | Yes | Event type. This value **'notifyInvisible'** indicates a widget invisibility event. | 383| 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('notifyInvisible')**. | 384| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | No | Callback registered during the subscription. If no value is passed in, all the subscriptions to the specified event are canceled.<br>To cancel the subscription with a given callback, this parameter must be set to the same value as **callback** in **on('notifyInvisible')**.| 385 386**Example** 387 388```ts 389import formObserver from '@ohos.app.form.formObserver'; 390import formInfo from '@ohos.app.form.formInfo'; 391 392let bundleName: string = 'ohos.samples.FormApplication'; 393formObserver.off('notifyInvisible', bundleName, (data: formInfo.RunningFormInfo[]) => { 394 console.log(`form change invisibility, data: ${JSON.stringify(data)}`); 395}); 396``` 397 398> **NOTE** 399> **on('notifyInvisible', callback)** and **off('notifyInvisible', callback)** must be used in pairs. 400> **on('notifyInvisible', bundleName, callback)** and **off('notifyInvisible', bundleName, callback)** must be used in pairs. 401> 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()**. 402 403 404## getRunningFormInfos 405 406getRunningFormInfos(callback: AsyncCallback<Array<formInfo.RunningFormInfo>>, hostBundleName?: string): void 407 408Obtains information about all non-temporary widgets running on the device. This API uses an asynchronous callback to return the result. 409 410**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 411 412**System capability**: SystemCapability.Ability.Form 413 414**Parameters** 415 416| Name| Type | Mandatory| Description | 417| ------ | ------ | ---- | ------- | 418| callback | AsyncCallback<Array<formInfo.RunningFormInfo>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained.| 419| 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.| 420 421**Error codes** 422For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 423 424| ID| Error Message| 425| -------- | -------- | 426| 16500050 | An IPC connection error happened. | 427| 16500060 | A service connection error happened, please try again later. | 428 429**Example** 430 431```ts 432import formObserver from '@ohos.app.form.formObserver'; 433import formInfo from '@ohos.app.form.formInfo'; 434import Base from '@ohos.base'; 435 436try { 437 formObserver.getRunningFormInfos((error: Base.BusinessError, data: formInfo.RunningFormInfo[]) => { 438 if (error) { 439 console.error(`error, code: ${error.code}, message: ${error.message}`); 440 } else { 441 console.log(`formObserver getRunningFormInfos, data: ${JSON.stringify(data)}`); 442 } 443 }, 'com.example.ohos.formjsdemo'); 444} catch(error) { 445 console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`); 446} 447``` 448 449## getRunningFormInfos 450 451getRunningFormInfos(hostBundleName?: string): Promise<Array<formInfo.RunningFormInfo>> 452 453Obtains information about all non-temporary widgets running on the device. This API uses a promise to return the result. 454 455**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 456 457**System capability**: SystemCapability.Ability.Form 458 459**Parameters** 460 461| Name| Type | Mandatory| Description | 462| ------ | ------ | ---- | ------- | 463| 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.| 464 465**Return value** 466 467| Type | Description | 468| :----------------------------------------------------------- | :---------------------------------- | 469| Promise<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained.| 470 471**Error codes** 472For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 473 474| ID| Error Message| 475| -------- | -------- | 476| 16500050 | An IPC connection error happened. | 477| 16500060 | A service connection error happened, please try again later. | 478 479**Example** 480 481```ts 482import formObserver from '@ohos.app.form.formObserver'; 483import formInfo from '@ohos.app.form.formInfo'; 484import Base from '@ohos.base'; 485 486try { 487 formObserver.getRunningFormInfos('com.example.ohos.formjsdemo').then((data: formInfo.RunningFormInfo[]) => { 488 console.log(`formObserver getRunningFormInfos, data: ${JSON.stringify(data)}`); 489 }).catch((error: Base.BusinessError) => { 490 console.error(`error, code: ${error.code}, message: ${error.message}`); 491 }); 492} catch(error) { 493 console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`); 494} 495``` 496 497## getRunningFormInfosByFilter 498 499getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter): Promise<Array<formInfo.RunningFormInfo>> 500 501Obtains the information about widget hosts based on the widget provider information. This API uses a promise to return the result. 502 503**Model restriction**: This API can be used only in the stage model. 504 505**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 506 507**System capability**: SystemCapability.Ability.Form 508 509**Parameters** 510 511| Name | Type | Mandatory| Description | 512| ----------- | --------------- | ---- | -------------------------------- | 513| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo.md#formProviderFilter) | Yes | Information about the widget provider.| 514 515**Return value** 516 517| Type | Description | 518| ------------------- | ------------------------- | 519| Promise<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md#RunningFormInfo)>> | Promise used to return the widget host information obtained.| 520 521**Error codes** 522 523For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 524 525| ID| Error Message| 526| -------- | -------- | 527| 201 | Permissions denied. | 528| 202 | The application is not a system application. | 529| 401 | If the input parameter is not valid parameter. | 530| 16500050 | An IPC connection error happened. | 531| 16500100 | Failed to obtain the configuration information. | 532| 16501000 | An internal functional error occurred. | 533 534 535```ts 536import formObserver from '@ohos.app.form.formObserver'; 537import formInfo from '@ohos.app.form.formInfo'; 538import Base from '@ohos.base'; 539 540let formInstanceFilter: formInfo.FormProviderFilter = { 541 bundleName: "com.example.formprovide", 542 abilityName: "EntryFormAbility", 543 formName: "widget", 544 moduleName: "entry" 545} 546try { 547 formObserver.getRunningFormInfosByFilter(formInstanceFilter).then((data: formInfo.RunningFormInfo[]) => { 548 console.info('formObserver getRunningFormInfosByFilter success, data:' + JSON.stringify(data)); 549 }).catch((error: Base.BusinessError) => { 550 console.error(`error, code: ${error.code}, message: ${error.message}`); 551 }); 552} catch(error) { 553 console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`); 554} 555``` 556 557## getRunningFormInfosByFilter 558 559getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter, callback: AsyncCallback<Array<formInfo.RunningFormInfo>>): void 560 561Obtains the information about widget hosts based on the widget provider information. This API uses an asynchronous callback to return the result. 562 563**Model restriction**: This API can be used only in the stage model. 564 565**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 566 567**System capability**: SystemCapability.Ability.Form 568 569**Parameters** 570 571| Name | Type | Mandatory| Description | 572| ----------- | --------------- | ---- | -------------------------------- | 573| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo.md#formProviderFilter) | Yes | Information about the widget provider.| 574| callback | AsyncCallback<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget host information is obtained, **error** is **undefined** and **data** is the information obtained; otherwise, **error** is an error object.| 575 576**Error codes** 577 578For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 579 580| ID| Error Message| 581| -------- | -------- | 582| 201 | Permissions denied. | 583| 202 | The application is not a system application. | 584| 401 | If the input parameter is not valid parameter. | 585| 16500050 | An IPC connection error happened. | 586| 16500100 | Failed to obtain the configuration information. | 587| 16501000 | An internal functional error occurred. | 588 589 590```ts 591import formObserver from '@ohos.app.form.formObserver'; 592import formInfo from '@ohos.app.form.formInfo'; 593import Base from '@ohos.base'; 594 595let formInstanceFilter: formInfo.FormProviderFilter = { 596 bundleName: "com.example.formprovide", 597 abilityName: "EntryFormAbility", 598 formName: "widget", 599 moduleName: "entry" 600} 601try { 602 formObserver.getRunningFormInfosByFilter(formInstanceFilter,(error: Base.BusinessError, data: formInfo.RunningFormInfo[]) => { 603 if (error) { 604 console.error(`error, code: ${error.code}, message: ${error.message}`); 605 } else { 606 console.log(`formObserver getRunningFormInfosByFilter, data: ${JSON.stringify(data)}`); 607 } 608 }); 609} catch(error) { 610 console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`); 611} 612``` 613 614## getRunningFormInfoById 615 616getRunningFormInfoById(formId: string): Promise<formInfo.RunningFormInfo> 617 618 619Obtains the information about widget hosts based on the widget ID. This API uses a promise to return the result. 620 621**Model restriction**: This API can be used only in the stage model. 622 623**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 624 625**System capability**: SystemCapability.Ability.Form 626 627**Parameters** 628 629| Name | Type | Mandatory| Description | 630| ----------- | --------------- | ---- | -------------------------------- | 631| formId | string | Yes | Widget ID.| 632 633**Return value** 634 635| Type | Description | 636| ------------------- | ------------------------- | 637| Promise<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)> | Promise used to return the widget host information obtained.| 638 639**Error codes** 640 641For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 642 643| ID| Error Message| 644| -------- | -------- | 645| 201 | Permissions denied. | 646| 202 | The application is not a system application. | 647| 401 | If the input parameter is not valid parameter. | 648| 16500050 | An IPC connection error happened. | 649| 16500100 | Failed to obtain the configuration information. | 650| 16501000 | An internal functional error occurred. | 651 652 653```ts 654import formObserver from '@ohos.app.form.formObserver'; 655import formInfo from '@ohos.app.form.formInfo'; 656import Base from '@ohos.base'; 657 658let formId: string = '12400633174999288'; 659try { 660 formObserver.getRunningFormInfoById(formId).then((data: formInfo.RunningFormInfo) => { 661 console.info('formObserver getRunningFormInfoById success, data:' + JSON.stringify(data)); 662 }).catch((error: Base.BusinessError) => { 663 console.error(`error, code: ${error.code}, message: ${error.message}`); 664 }); 665} catch(error) { 666 console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`); 667} 668``` 669 670## getRunningFormInfoById 671 672getRunningFormInfoById(formId: string, callback: AsyncCallback<formInfo.RunningFormInfo>): void 673 674Obtains the information about widget hosts based on the widget provider information. This API uses an asynchronous callback to return the result. 675 676**Model restriction**: This API can be used only in the stage model. 677 678**Required permissions**: ohos.permission.OBSERVE_FORM_RUNNING 679 680**System capability**: SystemCapability.Ability.Form 681 682**Parameters** 683 684| Name | Type | Mandatory| Description | 685| ----------- | --------------- | ---- | -------------------------------- | 686| formId | string | Yes | Widget ID.| 687| callback | AsyncCallback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md)> | Yes| Callback used to return the result. If the widget host information is obtained, **error** is **undefined** and **data** is the information obtained; otherwise, **error** is an error object.| 688 689**Error codes** 690 691For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 692 693| ID| Error Message| 694| -------- | -------- | 695| 201 | Permissions denied. | 696| 202 | The application is not a system application. | 697| 401 | If the input parameter is not valid parameter. | 698| 16500050 | An IPC connection error happened. | 699| 16500100 | Failed to obtain the configuration information. | 700| 16501000 | An internal functional error occurred. | 701 702```ts 703import formObserver from '@ohos.app.form.formObserver'; 704import formInfo from '@ohos.app.form.formInfo'; 705import Base from '@ohos.base'; 706 707let formId: string = '12400633174999288'; 708try { 709 formObserver.getRunningFormInfoById(formId,(error: Base.BusinessError, data: formInfo.RunningFormInfo) => { 710 if (error) { 711 console.error(`error, code: ${error.code}, message: ${error.message}`); 712 } else { 713 console.log(`formObserver getRunningFormInfoById, data: ${JSON.stringify(data)}`); 714 } 715 }); 716} catch(error) { 717 console.error(`catch error, code: ${(error as Base.BusinessError).code}, message: ${(error as Base.BusinessError).message}`); 718} 719``` 720