1# @ohos.app.form.formObserver (formObserver)(系统接口) 2 3formObserver模块提供了卡片监听方相关接口的能力，包括对同一用户下安装的卡片新增、删除、可见性变化事件的订阅和取消订阅，获取正在运行的卡片信息等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 本模块接口均为系统接口。 9 10## 导入模块 11 12```ts 13import { formObserver } from '@kit.FormKit'; 14``` 15 16## on('formAdd') 17 18 on(type: 'formAdd', observerCallback: Callback<formInfo.RunningFormInfo>): void 19 20订阅卡片新增事件。使用callback异步回调，返回当前新增卡片的信息。 21 22**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 23 24**系统能力：** SystemCapability.Ability.Form 25 26**参数：** 27 28| 参数名 | 类型 | 必填 | 说明 | 29| ------ | ------ | ---- | ------- | 30| type | string | 是 | 填写'formAdd'，表示卡片新增事件。 | 31| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回当前新增卡片的信息。 | 32 33**错误码：** 34 35| 错误码ID | 错误信息 | 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 40以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 41 42**示例：** 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 58订阅卡片新增事件。使用callback异步回调，返回指定卡片使用方应用新增卡片的信息。 59 60**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 61 62**系统能力：** SystemCapability.Ability.Form 63 64**参数：** 65 66| 参数名 | 类型 | 必填 | 说明 | 67| ------ | ------ | ---- | ------- | 68| type | string | 是 | 填写'formAdd'，表示卡片新增事件。 | 69| hostBundleName | string | 是 | 指定订阅卡片使用方包的bundleName。缺省则订阅所有卡片使用方的卡片新增事件。 | 70| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回指定卡片使用方应用新增卡片的信息。 | 71 72**错误码：** 73 74| 错误码ID | 错误信息 | 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**示例：** 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 97取消订阅卡片新增事件。使用callback异步回调，返回当前新增卡片的信息。 98 99**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 100 101**系统能力：** SystemCapability.Ability.Form 102 103**参数：** 104 105| 参数名 | 类型 | 必填 | 说明 | 106| ------ | ------ | ---- | ------- | 107| type | string | 是 | 填写'formAdd'，表示卡片新增事件。 | 108| hostBundleName | string | 否 | 指定订阅卡片使用方包的bundleName。<br> 填写该参数时，与注册时填写bundleName的on接口对应。<br> 缺省则订阅所有卡片使用方的卡片删除事件，与注册时未填写bundleName的on接口相对应。 | 109| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 否 | 回调函数。返回当前新增卡片信息。缺省时，表示注销对应已注册事件回调。<br> 需与对应on('formAdd')的callback一致。| 110 111**错误码：** 112 113| 错误码ID | 错误信息 | 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**示例：** 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> **说明：** 133> 134> on('formAdd', callback)与off('formAdd', callback)相对应； 135> on('formAdd', bundleName, callback)与off('formAdd', bundleName, callback)相对应； 136> 订阅（on）只能由自己对应的取消订阅接口（off）取消。 137 138## on('formRemove') 139 140 on(type: 'formRemove', observerCallback: Callback<formInfo.RunningFormInfo>): void 141 142订阅卡片删除事件。使用callback异步回调，返回当前删除卡片的信息。 143 144**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 145 146**系统能力：** SystemCapability.Ability.Form 147 148**参数：** 149 150| 参数名 | 类型 | 必填 | 说明 | 151| ------ | ------ | ---- | ------- | 152| type | string | 是 | 填写'formRemove'，表示卡片删除事件。 | 153| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回当前删除卡片的信息。 | 154 155**错误码：** 156 157| 错误码ID | 错误信息 | 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**示例：** 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 178订阅卡片删除事件。使用callback异步回调，返回指定卡片使用方应用被删除卡片的信息。 179 180**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 181 182**系统能力：** SystemCapability.Ability.Form 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| ------ | ------ | ---- | ------- | 188| type | string | 是 | 填写'formRemove'，表示卡片删除事件。 | 189| hostBundleName | string | 是 | 指定订阅卡片使用方包的bundleName。缺省则订阅所有卡片使用方的卡片删除事件。 | 190| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回指定卡片使用方应用被删除卡片的信息。 | 191 192**错误码：** 193 194| 错误码ID | 错误信息 | 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**示例：** 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 217取消订阅卡片删除事件。使用callback异步回调，返回当前删除卡片的信息。 218 219**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 220 221**系统能力：** SystemCapability.Ability.Form 222 223**参数：** 224 225| 参数名 | 类型 | 必填 | 说明 | 226| ------ | ------ | ---- | ------- | 227| type | string | 是 | 填写'formRemove'，表示卡片删除事件。 | 228| hostBundleName | string | 否 | 指定订阅卡片使用方包的bundleName。<br> 填写该参数时，与注册时填写bundleName的on接口对应。<br> 缺省则订阅所有卡片使用方的卡片删除事件，与注册时未填写bundleName的on接口相对应。 | 229| observerCallback | Callback<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 否 | 回调函数。返回当前删除卡片的信息。缺省时，表示注销对应已注册事件回调。<br> 需与对应on('formRemove')的callback一致。| 230 231**错误码：** 232 233| 错误码ID | 错误信息 | 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**示例：** 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> **说明：** 252> 253> on('formRemove', callback)与off('formRemove', callback)相对应； 254> on('formRemove', bundleName, callback)与off('formRemove', bundleName, callback)相对应； 255> 订阅（on）只能由自己对应的取消订阅接口（off）取消。 256 257## on('notifyVisible') 258 259 on(type: 'notifyVisible', observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void 260 261订阅通知卡片可见的事件。使用callback异步回调。 262 263触发通知卡片可见场景为：调用[notifyVisibleForms](js-apis-app-form-formHost-sys.md#notifyvisibleforms)接口通知对应卡片可见性变更为可见状态。 264 265**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 266 267**系统能力：** SystemCapability.Ability.Form 268 269**参数：** 270 271| 参数名 | 类型 | 必填 | 说明 | 272| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 273| type | string | 是 | 仅允许填写'notifyVisible'，表示订阅通知卡片可见的事件。 | 274| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | 是 | 回调函数。返回订阅该事件的卡片信息列表。 | 275 276**错误码：** 277 278| 错误码ID | 错误信息 | 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**示例：** 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 300订阅通知卡片可见的事件。使用callback异步回调。 301 302触发通知卡片可见场景为：调用[notifyVisibleForms](js-apis-app-form-formHost-sys.md#notifyvisibleforms)接口通知对应卡片可见性变更为可见状态。 303 304**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 305 306**系统能力：** SystemCapability.Ability.Form 307 308**参数：** 309 310| 参数名 | 类型 | 必填 | 说明 | 311| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 312| type | string | 是 | 仅允许填写'notifyVisible'，表示订阅通知卡片可见的事件。 | 313| hostBundleName | string | 是 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。 | 314| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | 是 | 回调函数。返回订阅该事件的卡片信息列表。 | 315 316**错误码：** 317 318| 错误码ID | 错误信息 | 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**示例：** 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 342取消订阅通知卡片可见的事件。使用callback异步回调。 343 344**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 345 346**系统能力：** SystemCapability.Ability.Form 347 348**参数：** 349 350| 参数名 | 类型 | 必填 | 说明 | 351| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 352| type | string | 是 | 仅允许填写'notifyVisible'，表示取消订阅通知卡片为可见的事件。 | 353| hostBundleName | string | 否 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。<br> 填写该参数时，与注册时填写bundleName的on接口对应。 | 354| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | 否 | 回调函数。返回取消订阅该事件的卡片信息列表。缺省时，表示注销对应已注册订阅的回调。<br> 需与对应on('notifyVisible')的callback一致。 | 355 356**错误码：** 357 358| 错误码ID | 错误信息 | 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**示例：** 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> **说明：** 378> 379> on('notifyVisible', callback)与off('notifyVisible', callback)相对应； 380> on('notifyVisible', bundleName, callback)与off('notifyVisible', bundleName, callback)相对应； 381> 订阅（on）只能由自己对应的取消订阅接口（off）取消。 382 383## on('notifyInvisible') 384 385 on(type: 'notifyInvisible', observerCallback: Callback<Array<formInfo.RunningFormInfo>>): void 386 387订阅通知卡片不可见的事件。使用callback异步回调。 388 389触发通知卡片不可见场景为：调用[notifyInvisibleForms](js-apis-app-form-formHost-sys.md#notifyinvisibleforms)接口通知对应卡片可见性变更为不可见状态。 390 391**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 392 393**系统能力：** SystemCapability.Ability.Form 394 395**参数：** 396 397| 参数名 | 类型 | 必填 | 说明 | 398| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 399| type | string | 是 | 仅允许填写'notifyInvisible'，表示订阅卡片不可见的事件。 | 400| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | 是 | 回调函数。返回订阅通知卡片不可见的卡片信息列表。 | 401 402**错误码：** 403 404| 错误码ID | 错误信息 | 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**示例：** 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 426订阅通知卡片不可见的事件。使用callback异步回调。 427 428触发通知卡片不可见场景为：调用[notifyInvisibleForms](js-apis-app-form-formHost-sys.md#notifyinvisibleforms)接口通知对应卡片可见性变更为不可见状态。 429 430**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 431 432**系统能力：** SystemCapability.Ability.Form 433 434**参数：** 435 436| 参数名 | 类型 | 必填 | 说明 | 437| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 438| type | string | 是 | 仅允许填写'notifyInvisible'，表示订阅卡片不可见的事件。 | 439| hostBundleName | string | 是 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。 | 440| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | 是 | 回调函数。返回订阅通知卡片不可见的卡片信息列表。 | 441 442**错误码：** 443 444| 错误码ID | 错误信息 | 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**示例：** 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 467取消订阅通知卡片不可见事件。使用callback异步回调。 468 469**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 470 471**系统能力：** SystemCapability.Ability.Form 472 473**参数：** 474 475| 参数名 | 类型 | 必填 | 说明 | 476| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 477| type | string | 是 | 仅允许填写'notifyInvisible'，表示卡片可见性变更为不可见。 | 478| hostBundleName | string | 否 | 指定卡片使用方的bundleName，用于订阅卡片在该使用方的可见状态变更事件。<br> 填写该参数时，与注册时填写bundleName的on接口对应。<br> | 479| observerCallback | Callback <Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | 否 | 回调函数。返回取消订阅通知卡片不可见的卡片信息列表。缺省时，表示注销对应已注册事件回调。<br/> 需与对应on('notifyInvisible')的callback一致。 | 480 481**错误码：** 482 483| 错误码ID | 错误信息 | 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**示例：** 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> **说明：** 503> 504> on('notifyInvisible', callback)与off('notifyInvisible', callback)相对应； 505> on('notifyInvisible', bundleName, callback)与off('notifyInvisible', bundleName, callback)相对应； 506> 订阅（on）只能由自己对应的取消订阅接口（off）取消。 507 508 509## getRunningFormInfos 510 511getRunningFormInfos(callback: AsyncCallback<Array<formInfo.RunningFormInfo>>, hostBundleName?: string): void 512 513获取设备上正在运行的所有非临时卡片信息。使用callback异步回调。 514 515**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 516 517**系统能力：** SystemCapability.Ability.Form 518 519**参数：** 520 521| 参数名 | 类型 | 必填 | 说明 | 522| ------ | ------ | ---- | ------- | 523| callback | AsyncCallback<Array<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | 是 | 回调函数。获取设备上正在运行的所有非临时卡片信息。当前卡片信息成功，error为undefined，data为查询到的卡片信息。| 524| hostBundleName | string | 否 | 指定要查询的卡片使用方名称，指定后会仅返回该卡片使用方下正在运行的非临时卡片信息。 <br> 缺省时，返回设备上所有正在运行的非临时卡片信息。 | 525 526**错误码：** 527以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 528 529| 错误码ID | 错误信息 | 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**示例：** 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 560获取设备上正在运行的所有非临时卡片信息。使用callback异步回调。 561 562**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 563 564**系统能力：** SystemCapability.Ability.Form 565 566**参数：** 567 568| 参数名 | 类型 | 必填 | 说明 | 569| ------ | ------ | ---- | ------- | 570| callback | AsyncCallback<Array<formInfo.[RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | 是 | 回调函数。获取设备上正在运行的所有非临时卡片信息。当获取成功时，回调中的error为undefined，data为查询到的卡片信息。| 571| isUnusedIncluded | boolean | 是 | 是否包含未使用的卡片。 | 572| hostBundleName | string | 否 | 指定要查询的卡片使用方名称，指定后会仅返回该卡片使用方下正在运行的非临时卡片信息。 <br> 缺省时，返回设备上所有正在运行的非临时卡片信息。 | 573 574**错误码：** 575以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 576 577| 错误码ID | 错误信息 | 578| -------- | -------- | 579| 201 | Permissions denied. | 580| 202 | The application is not a system application. | 581| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 582| 16500050 | IPC connection error. | 583| 16500060 | Service connection error. | 584 585**示例：** 586 587```ts 588import { formInfo, formObserver } from '@kit.FormKit'; 589import { BusinessError } from '@kit.BasicServicesKit'; 590 591try { 592 formObserver.getRunningFormInfos((error: BusinessError, data: formInfo.RunningFormInfo[]) => { 593 if (error) { 594 console.error(`error, code: ${error.code}, message: ${error.message}`); 595 } else { 596 console.log(`formObserver getRunningFormInfos, data: ${JSON.stringify(data)}`); 597 } 598 }, true, 'com.example.ohos.formjsdemo'); 599} catch(error) { 600 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 601} 602``` 603 604## getRunningFormInfos 605 606getRunningFormInfos(hostBundleName?: string): Promise<Array<formInfo.RunningFormInfo>> 607 608获取设备上正在运行的所有非临时卡片信息。使用Promise异步回调。 609 610**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 611 612**系统能力：** SystemCapability.Ability.Form 613 614**参数：** 615 616| 参数名 | 类型 | 必填 | 说明 | 617| ------ | ------ | ---- | ------- | 618| hostBundleName | string | 否 | 指定要查询的卡片使用方名称，指定后会仅返回该卡片使用方下正在运行的非临时卡片信息。 <br> 缺省时，返回设备上所有正在运行的非临时卡片信息。 | 619 620**返回值：** 621 622| 类型 | 说明 | 623| :----------------------------------------------------------- | :---------------------------------- | 624| Promise<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Promise对象。返回设备上正在运行的所有非临时卡片信息。 | 625 626**错误码：** 627 628以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 629 630| 错误码ID | 错误信息 | 631| -------- | -------- | 632| 201 | Permissions denied. | 633| 202 | The application is not a system application. | 634| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 635| 16500050 | IPC connection error. | 636| 16500060 | Service connection error. | 637 638**示例：** 639 640```ts 641import { formInfo, formObserver } from '@kit.FormKit'; 642import { BusinessError } from '@kit.BasicServicesKit'; 643 644try { 645 formObserver.getRunningFormInfos('com.example.ohos.formjsdemo').then((data: formInfo.RunningFormInfo[]) => { 646 console.log(`formObserver getRunningFormInfos, data: ${JSON.stringify(data)}`); 647 }).catch((error: BusinessError) => { 648 console.error(`error, code: ${error.code}, message: ${error.message}`); 649 }); 650} catch(error) { 651 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 652} 653``` 654 655## getRunningFormInfos<sup>11+</sup> 656 657getRunningFormInfos(isUnusedIncluded: boolean, hostBundleName?: string): Promise<Array<formInfo.RunningFormInfo>> 658 659获取设备上正在运行的所有非临时卡片信息。使用Promise异步回调。 660 661**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 662 663**系统能力：** SystemCapability.Ability.Form 664 665**参数：** 666 667| 参数名 | 类型 | 必填 | 说明 | 668| ------ | ------ | ---- | ------- | 669| isUnusedIncluded | boolean | 是 | 是否包含未使用的卡片。 | 670| hostBundleName | string | 否 | 指定要查询的卡片使用方名称，指定后会仅返回该卡片使用方下正在运行的非临时卡片信息。 <br> 缺省时，返回设备上所有正在运行的非临时卡片信息。 | 671 672**返回值：** 673 674| 类型 | 说明 | 675| :----------------------------------------------------------- | :---------------------------------- | 676| Promise<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Promise对象。返回设备上正在运行的所有非临时卡片信息。 | 677 678**错误码：** 679 680以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 681 682| 错误码ID | 错误信息 | 683| -------- | -------- | 684| 201 | Permissions denied. | 685| 202 | The application is not a system application. | 686| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 687| 16500050 | IPC connection error. | 688| 16500060 | Service connection error. | 689 690**示例：** 691 692```ts 693import { formInfo, formObserver } from '@kit.FormKit'; 694import { BusinessError } from '@kit.BasicServicesKit'; 695 696try { 697 formObserver.getRunningFormInfos(true, 'com.example.ohos.formjsdemo').then((data: formInfo.RunningFormInfo[]) => { 698 console.log(`formObserver getRunningFormInfos, data: ${JSON.stringify(data)}`); 699 }).catch((error: BusinessError) => { 700 console.error(`error, code: ${error.code}, message: ${error.message}`); 701 }); 702} catch(error) { 703 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 704} 705``` 706 707## getRunningFormInfosByFilter 708 709getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter): Promise<Array<formInfo.RunningFormInfo>> 710 711根据提供方信息查询已添加的卡片信息列表。使用Promise异步回调。 712 713**模型约束：** 此接口仅可在Stage模型下使用。 714 715**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 716 717**系统能力：** SystemCapability.Ability.Form 718 719**参数：** 720 721| 参数名 | 类型 | 必填 | 说明 | 722| ----------- | --------------- | ---- | -------------------------------- | 723| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo-sys.md#formproviderfilter10) | 是 | 卡片提供方应用信息。 | 724 725**返回值：** 726 727| 类型 | 说明 | 728| ------------------- | ------------------------- | 729| Promise<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | Promise对象。返回已添加的卡片信息列表。 | 730 731**错误码：** 732 733以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 734 735| 错误码ID | 错误信息 | 736| -------- | -------- | 737| 201 | Permissions denied. | 738| 202 | The application is not a system application. | 739| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 740| 16500050 | IPC connection error. | 741| 16500100 | Failed to obtain the configuration information. | 742| 16501000 | An internal functional error occurred. | 743 744 745```ts 746import { formInfo, formObserver } from '@kit.FormKit'; 747import { BusinessError } from '@kit.BasicServicesKit'; 748 749let formInstanceFilter: formInfo.FormProviderFilter = { 750 bundleName: "com.example.formprovide", 751 abilityName: "EntryFormAbility", 752 formName: "widget", 753 moduleName: "entry" 754} 755try { 756 formObserver.getRunningFormInfosByFilter(formInstanceFilter).then((data: formInfo.RunningFormInfo[]) => { 757 console.info('formObserver getRunningFormInfosByFilter success, data:' + JSON.stringify(data)); 758 }).catch((error: BusinessError) => { 759 console.error(`error, code: ${error.code}, message: ${error.message}`); 760 }); 761} catch(error) { 762 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 763} 764``` 765 766## getRunningFormInfosByFilter 767 768getRunningFormInfosByFilter(formProviderFilter: formInfo.FormProviderFilter, callback: AsyncCallback<Array<formInfo.RunningFormInfo>>): void 769 770根据提供方信息查询已添加的卡片信息列表。使用callback异步回调。 771 772**模型约束：** 此接口仅可在Stage模型下使用。 773 774**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 775 776**系统能力：** SystemCapability.Ability.Form 777 778**参数：** 779 780| 参数名 | 类型 | 必填 | 说明 | 781| ----------- | --------------- | ---- | -------------------------------- | 782| formProviderFilter | [formInfo.FormProviderFilter](js-apis-app-form-formInfo-sys.md#formproviderfilter10) | 是 | 卡片提供方应用信息。 | 783| callback | AsyncCallback<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)>> | 是 | 回调函数。返回已添加的卡片信息列表。error为undefined，data为查询到的使用方列表信息；否则为错误对象。 | 784 785**错误码：** 786 787以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 788 789| 错误码ID | 错误信息 | 790| -------- | -------- | 791| 201 | Permissions denied. | 792| 202 | The application is not a system application. | 793| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 794| 16500050 | IPC connection error. | 795| 16500100 | Failed to obtain the configuration information. | 796| 16501000 | An internal functional error occurred. | 797 798**示例：** 799 800```ts 801import { formInfo, formObserver } from '@kit.FormKit'; 802import { BusinessError } from '@kit.BasicServicesKit'; 803 804let formInstanceFilter: formInfo.FormProviderFilter = { 805 bundleName: "com.example.formprovide", 806 abilityName: "EntryFormAbility", 807 formName: "widget", 808 moduleName: "entry" 809} 810try { 811 formObserver.getRunningFormInfosByFilter(formInstanceFilter,(error: BusinessError, data: formInfo.RunningFormInfo[]) => { 812 if (error) { 813 console.error(`error, code: ${error.code}, message: ${error.message}`); 814 } else { 815 console.log(`formObserver getRunningFormInfosByFilter, data: ${JSON.stringify(data)}`); 816 } 817 }); 818} catch(error) { 819 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 820} 821``` 822 823## getRunningFormInfoById 824 825getRunningFormInfoById(formId: string): Promise<formInfo.RunningFormInfo> 826 827根据formId查询已添加的卡片信息。使用Promise异步回调。 828 829**模型约束：** 此接口仅可在Stage模型下使用。 830 831**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 832 833**系统能力：** SystemCapability.Ability.Form 834 835**参数：** 836 837| 参数名 | 类型 | 必填 | 说明 | 838| ----------- | --------------- | ---- | -------------------------------- | 839| formId | string | 是 | 卡片标识。 | 840 841**返回值：** 842 843| 类型 | 说明 | 844| ------------------- | ------------------------- | 845| Promise<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Promise对象。返回已添加的卡片信息。 | 846 847**错误码：** 848 849以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 850 851| 错误码ID | 错误信息 | 852| -------- | -------- | 853| 201 | Permissions denied. | 854| 202 | The application is not a system application. | 855| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 856| 16500050 | IPC connection error. | 857| 16500100 | Failed to obtain the configuration information. | 858| 16501000 | An internal functional error occurred. | 859 860**示例：** 861 862```ts 863import { formInfo, formObserver } from '@kit.FormKit'; 864import { BusinessError } from '@kit.BasicServicesKit'; 865 866let formId: string = '12400633174999288'; 867try { 868 formObserver.getRunningFormInfoById(formId).then((data: formInfo.RunningFormInfo) => { 869 console.info('formObserver getRunningFormInfoById success, data:' + JSON.stringify(data)); 870 }).catch((error: BusinessError) => { 871 console.error(`error, code: ${error.code}, message: ${error.message}`); 872 }); 873} catch(error) { 874 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 875} 876``` 877 878## getRunningFormInfoById<sup>11+</sup> 879 880getRunningFormInfoById(formId: string, isUnusedIncluded: boolean): Promise<formInfo.RunningFormInfo> 881 882根据formId查询卡片已添加的卡片信息。使用Promise异步回调。 883 884**模型约束：** 此接口仅可在Stage模型下使用。 885 886**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 887 888**系统能力：** SystemCapability.Ability.Form 889 890**参数：** 891 892| 参数名 | 类型 | 必填 | 说明 | 893| ----------- | --------------- | ---- | -------------------------------- | 894| formId | string | 是 | 卡片标识。 | 895| isUnusedIncluded | boolean | 是 | 是否包含未使用的卡片。 | 896 897**返回值：** 898 899| 类型 | 说明 | 900| ------------------- | ------------------------- | 901| Promise<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | Promise对象。返回已添加的卡片信息。 | 902 903**错误码：** 904 905以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 906 907| 错误码ID | 错误信息 | 908| -------- | -------- | 909| 201 | Permissions denied. | 910| 202 | The application is not a system application. | 911| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 912| 16500050 | IPC connection error. | 913| 16500100 | Failed to obtain the configuration information. | 914| 16501000 | An internal functional error occurred. | 915 916**示例：** 917 918```ts 919import { formInfo, formObserver } from '@kit.FormKit'; 920import { BusinessError } from '@kit.BasicServicesKit'; 921 922let formId: string = '12400633174999288'; 923try { 924 formObserver.getRunningFormInfoById(formId, true).then((data: formInfo.RunningFormInfo) => { 925 console.info('formObserver getRunningFormInfoById success, data:' + JSON.stringify(data)); 926 }).catch((error: BusinessError) => { 927 console.error(`error, code: ${error.code}, message: ${error.message}`); 928 }); 929} catch(error) { 930 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 931} 932``` 933 934## getRunningFormInfoById 935 936getRunningFormInfoById(formId: string, callback: AsyncCallback<formInfo.RunningFormInfo>): void 937 938根据提供方信息查询已添加的卡片信息。使用callback异步回调。 939 940**模型约束：** 此接口仅可在Stage模型下使用。 941 942**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 943 944**系统能力：** SystemCapability.Ability.Form 945 946**参数：** 947 948| 参数名 | 类型 | 必填 | 说明 | 949| ----------- | --------------- | ---- | -------------------------------- | 950| formId | string | 是 | 卡片标识。 | 951| callback | AsyncCallback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回已添加的卡片信息。error为undefined，data为查询到的使用方列表信息；否则为错误对象。 | 952 953**错误码：** 954 955以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 956 957| 错误码ID | 错误信息 | 958| -------- | -------- | 959| 201 | Permissions denied. | 960| 202 | The application is not a system application. | 961| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 962| 16500050 | IPC connection error. | 963| 16500100 | Failed to obtain the configuration information. | 964| 16501000 | An internal functional error occurred. | 965 966**示例：** 967 968```ts 969import { formInfo, formObserver } from '@kit.FormKit'; 970import { BusinessError } from '@kit.BasicServicesKit'; 971 972let formId: string = '12400633174999288'; 973try { 974 formObserver.getRunningFormInfoById(formId,(error: BusinessError, data: formInfo.RunningFormInfo) => { 975 if (error) { 976 console.error(`error, code: ${error.code}, message: ${error.message}`); 977 } else { 978 console.log(`formObserver getRunningFormInfoById, data: ${JSON.stringify(data)}`); 979 } 980 }); 981} catch(error) { 982 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 983} 984``` 985 986## getRunningFormInfoById<sup>11+</sup> 987 988getRunningFormInfoById(formId: string, isUnusedIncluded: boolean, callback: AsyncCallback<formInfo.RunningFormInfo>): void 989 990根据卡片标识formId，查询已添加的卡片信息。使用callback异步回调。 991 992**模型约束：** 此接口仅可在Stage模型下使用。 993 994**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 995 996**系统能力：** SystemCapability.Ability.Form 997 998**参数：** 999 1000| 参数名 | 类型 | 必填 | 说明 | 1001| ----------- | --------------- | ---- | -------------------------------- | 1002| formId | string | 是 | 卡片标识。 | 1003| isUnusedIncluded | boolean | 是 | 是否包含未使用的卡片。 | 1004| callback | AsyncCallback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回已添加的卡片信息。error为undefined，data为查询到的使用方列表信息；否则为错误对象。 | 1005 1006**错误码：** 1007 1008以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1009 1010| 错误码ID | 错误信息 | 1011| -------- | -------- | 1012| 201 | Permissions denied. | 1013| 202 | The application is not a system application. | 1014| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1015| 16500050 | IPC connection error. | 1016| 16500100 | Failed to obtain the configuration information. | 1017| 16501000 | An internal functional error occurred. | 1018 1019**示例：** 1020 1021```ts 1022import { formInfo, formObserver } from '@kit.FormKit'; 1023import { BusinessError } from '@kit.BasicServicesKit'; 1024 1025let formId: string = '12400633174999288'; 1026try { 1027 formObserver.getRunningFormInfoById(formId, true, (error: BusinessError, data: formInfo.RunningFormInfo) => { 1028 if (error) { 1029 console.error(`error, code: ${error.code}, message: ${error.message}`); 1030 } else { 1031 console.log(`formObserver getRunningFormInfoById, data: ${JSON.stringify(data)}`); 1032 } 1033 }); 1034} catch(error) { 1035 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1036} 1037``` 1038 1039## on('router')<sup>11+</sup> 1040 1041 on(type: 'router', observerCallback: Callback<formInfo.RunningFormInfo>): void 1042 1043订阅卡片router事件。使用callback异步回调，返回触发router事件的卡片信息。 1044 1045**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 1046 1047**系统能力：** SystemCapability.Ability.Form 1048 1049**参数：** 1050 1051| 参数名 | 类型 | 必填 | 说明 | 1052| ---------------- | ---------------------------------------- | ---- | ----------------------------------------- | 1053| type | string | 是 | 填写'router'，表示订阅卡片的router事件。 | 1054| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回触发router事件的卡片信息。 | 1055 1056**错误码：** 1057 1058以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1059 1060| 错误码ID | 错误信息 | 1061| -------- | -------- | 1062| 202 | The application is not a system application. | 1063| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1064 1065**示例：** 1066 1067```ts 1068import { formInfo, formObserver } from '@kit.FormKit'; 1069 1070let callback = (data: formInfo.RunningFormInfo) => { 1071 console.log('Router event listening in registered form.' + JSON.stringify(data)); 1072}; 1073formObserver.on('router', callback); 1074``` 1075 1076## on('router')<sup>11+</sup> 1077 1078 on(type: 'router', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void 1079 1080订阅指定卡片使用方的卡片router事件。使用callback异步回调，返回触发router事件的卡片信息。 1081 1082**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 1083 1084**系统能力：** SystemCapability.Ability.Form 1085 1086**参数：** 1087 1088| 参数名 | 类型 | 必填 | 说明 | 1089| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1090| type | string | 是 | 填写'router'，表示订阅卡片的router事件。 | 1091| hostBundleName | string | 是 | 指定卡片使用方的bundleName。缺省则订阅所有卡片使用方的卡片的router事件。 | 1092| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回触发router事件的卡片信息。 | 1093 1094**错误码：** 1095 1096以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1097 1098| 错误码ID | 错误信息 | 1099| -------- | -------- | 1100| 202 | The application is not a system application. | 1101| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1102 1103**示例：** 1104 1105```ts 1106import { formInfo, formObserver } from '@kit.FormKit'; 1107 1108let hostBundleName: string = 'ohos.samples.FormApplication'; 1109let callback = (data: formInfo.RunningFormInfo) => { 1110 console.log('Router event listening in registered form.' + JSON.stringify(data)); 1111}; 1112formObserver.on('router', hostBundleName, callback); 1113``` 1114 1115## off('router')<sup>11+</sup> 1116 1117 off(type: "router", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void 1118 1119取消订阅卡片router事件。使用callback异步回调，返回触发router事件的卡片信息。 1120 1121**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 1122 1123**系统能力：** SystemCapability.Ability.Form 1124 1125**参数：** 1126 1127| 参数名 | 类型 | 必填 | 说明 | 1128| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1129| type | string | 是 | 填写'router'，表示取消订阅卡片的router事件。 | 1130| hostBundleName | string | 否 | 指定订阅卡片使用方包的bundleName。<br>填写该参数时，与注册时填写bundleName的on接口对应。<br>缺省则订阅所有卡片使用方点击router类型卡片的事件，与注册时未填写bundleName的on接口相对应。 | 1131| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 否 | 回调函数。返回触发router事件的卡片信息。缺省时，表示注销对应bundleName下已注册事件回调。<br>需与对应on('router')的callback一致。 | 1132 1133**错误码：** 1134 1135以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1136 1137| 错误码ID | 错误信息 | 1138| -------- | -------- | 1139| 202 | The application is not a system application. | 1140| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1141 1142**示例：** 1143 1144```ts 1145import { formInfo, formObserver } from '@kit.FormKit'; 1146 1147let hostBundleName: string = 'ohos.samples.FormApplication'; 1148let callback = (data: formInfo.RunningFormInfo) => { 1149 console.log('Unregister form router event Listening.' + JSON.stringify(data)); 1150}; 1151formObserver.off('router', hostBundleName, callback); 1152``` 1153 1154## on('message')<sup>11+</sup> 1155 1156 on(type: 'message', observerCallback: Callback<formInfo.RunningFormInfo>): void 1157 1158订阅卡片message事件。使用callback异步回调，返回触发message事件的卡片信息。 1159 1160**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 1161 1162**系统能力：** SystemCapability.Ability.Form 1163 1164**参数：** 1165 1166| 参数名 | 类型 | 必填 | 说明 | 1167| ---------------- | ---------------------------------------- | ---- | ----------------------------------------- | 1168| type | string | 是 | 填写'message'，表示订阅卡片的message事件。 | 1169| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回触发message事件的卡片信息。 | 1170 1171**错误码：** 1172 1173以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1174 1175| 错误码ID | 错误信息 | 1176| -------- | -------- | 1177| 202 | The application is not a system application. | 1178| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1179 1180**示例：** 1181 1182```ts 1183import { formInfo, formObserver } from '@kit.FormKit'; 1184 1185let callback = (data: formInfo.RunningFormInfo) => { 1186 console.log('Message event listening in registered form.' + JSON.stringify(data)); 1187}; 1188formObserver.on('message', callback); 1189``` 1190 1191## on('message')<sup>11+</sup> 1192 1193 on(type: 'message', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void 1194 1195订阅指定卡片使用方的卡片message事件。使用callback异步回调，返回触发message事件的卡片信息。 1196 1197**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 1198 1199**系统能力：** SystemCapability.Ability.Form 1200 1201**参数：** 1202 1203| 参数名 | 类型 | 必填 | 说明 | 1204| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1205| type | string | 是 | 填写'message'，表示订阅卡片的message事件。 | 1206| hostBundleName | string | 是 | 指定卡片使用方的bundleName。缺省则订阅所有卡片使用方的卡片的message事件。 | 1207| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回触发message事件的卡片的信息。 | 1208 1209**错误码：** 1210 1211以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1212 1213| 错误码ID | 错误信息 | 1214| -------- | -------- | 1215| 202 | The application is not a system application. | 1216| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1217 1218**示例：** 1219 1220```ts 1221import { formInfo, formObserver } from '@kit.FormKit'; 1222 1223let hostBundleName: string = 'ohos.samples.FormApplication'; 1224let callback = (data: formInfo.RunningFormInfo) => { 1225 console.log('Message event listening in registered form.' + JSON.stringify(data)); 1226}; 1227formObserver.on('message', hostBundleName, callback); 1228``` 1229 1230## off('message')<sup>11+</sup> 1231 1232 off(type: "message", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void 1233 1234取消订阅卡片message事件。使用callback异步回调，返回触发message事件的卡片的信息。 1235 1236**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 1237 1238**系统能力：** SystemCapability.Ability.Form 1239 1240**参数：** 1241 1242| 参数名 | 类型 | 必填 | 说明 | 1243| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1244| type | string | 是 | 填写'message'，表示取消订阅卡片的message事件。 | 1245| hostBundleName | string | 否 | 指定订阅卡片使用方包的bundleName。<br>填写该参数时，与注册时填写bundleName的on接口对应。<br>缺省则取消订阅所有卡片使用方的点击事件，与注册时未填写bundleName的on接口相对应。 | 1246| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 否 | 回调函数。返回触发message事件的卡片的信息。缺省时，表示注销对应已注册事件回调。<br>需与对应on('message')的callback一致。 | 1247 1248**错误码：** 1249 1250以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1251 1252| 错误码ID | 错误信息 | 1253| -------- | -------- | 1254| 202 | The application is not a system application. | 1255| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1256 1257**示例：** 1258 1259```ts 1260import { formInfo, formObserver } from '@kit.FormKit'; 1261 1262let hostBundleName: string = 'ohos.samples.FormApplication'; 1263let callback = (data: formInfo.RunningFormInfo) => { 1264 console.log('Unregister form Message event Listening.' + JSON.stringify(data)); 1265}; 1266formObserver.off('message', hostBundleName, callback); 1267``` 1268 1269## on('call')<sup>11+</sup> 1270 1271 on(type: 'call', observerCallback: Callback<formInfo.RunningFormInfo>): void 1272 1273订阅卡片call事件。使用callback异步回调，返回触发call事件的卡片信息。 1274 1275**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 1276 1277**系统能力：** SystemCapability.Ability.Form 1278 1279**参数：** 1280 1281| 参数名 | 类型 | 必填 | 说明 | 1282| ---------------- | ---------------------------------------- | ---- | ----------------------------------------- | 1283| type | string | 是 | 填写'call'，表示订阅卡片的call事件。 | 1284| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回触发call事件的卡片信息。 | 1285 1286**错误码：** 1287 1288以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1289 1290| 错误码ID | 错误信息 | 1291| -------- | -------- | 1292| 202 | The application is not a system application. | 1293| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1294 1295**示例：** 1296 1297```ts 1298import { formInfo, formObserver } from '@kit.FormKit'; 1299 1300let callback = (data: formInfo.RunningFormInfo) => { 1301 console.log('Call event listening in registered form.' + JSON.stringify(data)); 1302}; 1303formObserver.on('call', callback); 1304``` 1305 1306## on('call')<sup>11+</sup> 1307 1308 on(type: 'call', hostBundleName: string, observerCallback: Callback<formInfo.RunningFormInfo>): void 1309 1310订阅指定卡片使用方的卡片call事件。使用callback异步回调，返回触发call事件的卡片信息。 1311 1312**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 1313 1314**系统能力：** SystemCapability.Ability.Form 1315 1316**参数：** 1317 1318| 参数名 | 类型 | 必填 | 说明 | 1319| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1320| type | string | 是 | 填写'call'，表示订阅卡片的call事件。 | 1321| hostBundleName | string | 是 | 指定卡片使用方的bundleName。缺省则订阅所有卡片使用方的卡片的call事件。 | 1322| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 是 | 回调函数。返回触发call事件的卡片信息。 | 1323 1324**错误码：** 1325 1326以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1327 1328| 错误码ID | 错误信息 | 1329| -------- | -------- | 1330| 202 | The application is not a system application. | 1331| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1332 1333**示例：** 1334 1335```ts 1336import { formInfo, formObserver } from '@kit.FormKit'; 1337 1338let hostBundleName: string = 'ohos.samples.FormApplication'; 1339let callback = (data: formInfo.RunningFormInfo) => { 1340 console.log('Call event listening in registered form.' + JSON.stringify(data)); 1341}; 1342formObserver.on('call', hostBundleName, callback); 1343``` 1344 1345## off('call')<sup>11+</sup> 1346 1347 off(type: "call", hostBundleName?: string, observerCallback?: Callback<formInfo.RunningFormInfo>): void 1348 1349取消订阅卡片call事件。使用callback异步回调，返回触发call事件的卡片信息。 1350 1351**需要权限：** ohos.permission.OBSERVE_FORM_RUNNING 1352 1353**系统能力：** SystemCapability.Ability.Form 1354 1355**参数：** 1356 1357| 参数名 | 类型 | 必填 | 说明 | 1358| ---------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 1359| type | string | 是 | 填写'call'，表示取消订阅卡片的call事件。 | 1360| hostBundleName | string | 否 | 指定订阅卡片使用方包的bundleName。<br>填写该参数时，与注册时填写bundleName的on接口对应。<br>缺省则取消订阅所有卡片使用方的点击事件，与注册时未填写bundleName的on接口相对应。 | 1361| observerCallback | Callback<[formInfo.RunningFormInfo](js-apis-app-form-formInfo-sys.md#runningforminfo10)> | 否 | 回调函数。返回触发call事件的卡片信息。缺省时，表示注销对应已注册事件回调。<br>需与对应on('call')的callback一致。 | 1362 1363**错误码：** 1364 1365以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1366 1367| 错误码ID | 错误信息 | 1368| -------- | -------- | 1369| 202 | The application is not a system application. | 1370| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1371 1372**示例：** 1373 1374```ts 1375import { formInfo, formObserver } from '@kit.FormKit'; 1376 1377let hostBundleName: string = 'ohos.samples.FormApplication'; 1378let callback = (data: formInfo.RunningFormInfo) => { 1379 console.log('Unregister form Call event Listening.' + JSON.stringify(data)); 1380}; 1381formObserver.off('call', hostBundleName, callback); 1382```