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