1# Class (UIObserver) 2 3<!--Kit: ArkUI--> 4<!--Subsystem: ArkUI--> 5<!--Owner: @piggyguy; @xiang-shouxing; @yangfan229--> 6<!--Designer: @piggyguy; @xiang-shouxing; @yangfan229--> 7<!--Tester: @fredyuan912--> 8<!--Adviser: @HelloCrease--> 9 10提供UI组件行为变化的无感监听能力。 11 12> **说明：** 13> 14> - 本模块首批接口从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 15> 16> - 本Class首批接口从API version 11开始支持。 17> 18> - 以下API需先使用UIContext中的[getUIObserver()](arkts-apis-uicontext-uicontext.md#getuiobserver11)方法获取到UIObserver对象，再通过该对象调用对应方法。 19> 20> - UIObserver仅能监听到本进程内的相关信息，不支持获取<!--Del-->[UIExtensionComponent](../../reference/apis-arkui/arkui-ts/ts-container-ui-extension-component-sys.md)等<!--DelEnd-->跨进程场景的信息。 21 22## on('navDestinationUpdate')<sup>11+</sup> 23 24on(type: 'navDestinationUpdate', callback: Callback\<observer.NavDestinationInfo\>): void 25 26监听[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化。 27 28**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 29 30**系统能力：** SystemCapability.ArkUI.ArkUI.Full 31 32**参数：** 33 34| 参数名 | 类型 | 必填 | 说明 | 35| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 36| type | string | 是 | 监听事件，固定为'navDestinationUpdate'，即[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化。 | 37| callback | Callback\<observer.[NavDestinationInfo](js-apis-arkui-observer.md#navdestinationinfo)\> | 是 | 回调函数。返回当前的[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件状态。 | 38 39**示例：** 40 41<!--code_no_check--> 42```ts 43// Index.ets 44// 演示uiObserver.on('navDestinationUpdate', callback) 45// uiObserver.off('navDestinationUpdate', callback) 46 47@Component 48struct PageOne { 49 build() { 50 NavDestination() { 51 Text("pageOne") 52 }.title("pageOne") 53 } 54} 55 56@Entry 57@Component 58struct Index { 59 private stack: NavPathStack = new NavPathStack(); 60 61 @Builder 62 PageBuilder(name: string) { 63 PageOne() 64 } 65 66 aboutToAppear() { 67 // 添加监听 68 this.getUIContext().getUIObserver().on('navDestinationUpdate', (info) => { 69 console.info('NavDestination state update', JSON.stringify(info)); 70 }); 71 } 72 73 aboutToDisappear() { 74 // 取消监听，不选择回调时，取消所有监听的回调 75 this.getUIContext().getUIObserver().off('navDestinationUpdate'); 76 } 77 78 build() { 79 Column() { 80 Navigation(this.stack) { 81 Button("push").onClick(() => { 82 // 将PageOne的NavDestination入栈 83 this.stack.pushPath({ name: "pageOne" }); 84 }) 85 } 86 .title("Navigation") 87 .navDestination(this.PageBuilder) 88 } 89 .width('100%') 90 .height('100%') 91 } 92} 93``` 94 95## off('navDestinationUpdate')<sup>11+</sup> 96 97off(type: 'navDestinationUpdate', callback?: Callback\<observer.NavDestinationInfo\>): void 98 99取消监听[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化。 100 101**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 102 103**系统能力：** SystemCapability.ArkUI.ArkUI.Full 104 105**参数：** 106 107| 参数名 | 类型 | 必填 | 说明 | 108| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 109| type | string | 是 | 监听事件，固定为'navDestinationUpdate'，即[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化。 | 110| callback | Callback\<observer.[NavDestinationInfo](js-apis-arkui-observer.md#navdestinationinfo)\> | 否 | 需要取消的监听回调，不传参数时，取消所有的[Navigation](arkui-ts/ts-basic-components-navigation.md)监听回调。 | 111 112**示例：** 113 114参考[on('navDestinationUpdate')](#onnavdestinationupdate11)接口示例。 115 116## on('navDestinationUpdate')<sup>11+</sup> 117 118on(type: 'navDestinationUpdate', options: { navigationId: ResourceStr }, callback: Callback\<observer.NavDestinationInfo\>): void 119 120通过[Navigation](arkui-ts/ts-basic-components-navigation.md)的id监听[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化。 121 122**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 130| type | string | 是 | 监听事件，固定为'navDestinationUpdate'，即[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化。 | 131| options | { navigationId: [ResourceStr](arkui-ts/ts-types.md#resourcestr) } | 是 | 指定监听的[Navigation](arkui-ts/ts-basic-components-navigation.md)的id。 | 132| callback | Callback\<observer.[NavDestinationInfo](js-apis-arkui-observer.md#navdestinationinfo)\> | 是 | 回调函数。返回当前的[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件状态。 | 133 134**示例：** 135 136<!--code_no_check--> 137```ts 138// Index.ets 139// 演示uiObserver.on('navDestinationUpdate', options, callback) 140// uiObserver.off('navDestinationUpdate', options, callback) 141 142@Component 143struct PageOne { 144 build() { 145 NavDestination() { 146 Text("pageOne") 147 }.title("pageOne") 148 } 149} 150 151@Entry 152@Component 153struct Index { 154 private stack: NavPathStack = new NavPathStack(); 155 156 @Builder 157 PageBuilder(name: string) { 158 PageOne() 159 } 160 161 aboutToAppear() { 162 // 添加监听，指定Navigation的id 163 this.getUIContext().getUIObserver().on('navDestinationUpdate', { navigationId: "testId" }, (info) => { 164 console.info('NavDestination state update', JSON.stringify(info)); 165 }); 166 } 167 168 aboutToDisappear() { 169 // 取消监听，不选择回调时，取消所有监听的回调 170 this.getUIContext().getUIObserver().off('navDestinationUpdate', { navigationId: "testId" }); 171 } 172 173 build() { 174 Column() { 175 Navigation(this.stack) { 176 Button("push").onClick(() => { 177 // 将PageOne的NavDestination入栈 178 this.stack.pushPath({ name: "pageOne" }); 179 }) 180 } 181 .id("testId") 182 .title("Navigation") 183 .navDestination(this.PageBuilder) 184 } 185 .width('100%') 186 .height('100%') 187 } 188} 189``` 190 191## off('navDestinationUpdate')<sup>11+</sup> 192 193off(type: 'navDestinationUpdate', options: { navigationId: ResourceStr }, callback?: Callback\<observer.NavDestinationInfo\>): void 194 195取消通过[Navigation](arkui-ts/ts-basic-components-navigation.md)的id监听[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化。 196 197**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 198 199**系统能力：** SystemCapability.ArkUI.ArkUI.Full 200 201**参数：** 202 203| 参数名 | 类型 | 必填 | 说明 | 204| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 205| type | string | 是 | 监听事件，固定为'navDestinationUpdate'，即[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化。 | 206| options | { navigationId: [ResourceStr](arkui-ts/ts-types.md#resourcestr) } | 是 | 指定监听的[Navigation](arkui-ts/ts-basic-components-navigation.md)的id。 | 207| callback | Callback\<observer.[NavDestinationInfo](js-apis-arkui-observer.md#navdestinationinfo)\> | 否 |需要取消的监听回调，不传参数时，取消该[Navigation](arkui-ts/ts-basic-components-navigation.md)上所有的监听回调。 | 208 209**示例：** 210 211参考[on('navDestinationUpdate')](#onnavdestinationupdate11-1)接口示例。 212 213## on('navDestinationUpdateByUniqueId')<sup>20+</sup> 214 215on(type: 'navDestinationUpdateByUniqueId', navigationUniqueId: number, callback: Callback\<observer.NavDestinationInfo\>): void 216 217通过[Navigation](arkui-ts/ts-basic-components-navigation.md)的uniqueId监听[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化，uniqueId可通过[queryNavigationInfo](arkui-ts/ts-custom-component-api.md#querynavigationinfo12)获取。 218 219**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 220 221**系统能力：** SystemCapability.ArkUI.ArkUI.Full 222 223**参数：** 224 225| 参数名 | 类型 | 必填 | 说明 | 226| -------- | -------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------ | 227| type | string | 是 | 监听事件，固定为'navDestinationUpdateByUniqueId'，即[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化。 | 228| navigationUniqueId | number | 是 | 指定监听的[Navigation](arkui-ts/ts-basic-components-navigation.md)的uniqueId，可以通过[queryNavigationInfo](arkui-ts/ts-custom-component-api.md#querynavigationinfo12)获取。 | 229| callback | Callback\<observer.[NavDestinationInfo](js-apis-arkui-observer.md#navdestinationinfo)\> | 是 | 回调函数。返回当前的[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件状态。 | 230 231**示例：** 232 233通过[Navigation](arkui-ts/ts-basic-components-navigation.md)的uniqueId，可以触发[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化。 234 235```ts 236// Index.ets 237// 演示on('navDestinationUpdateByUniqueId', navigationUniqueId, callback) 238// off('navDestinationUpdateByUniqueId', navigationUniqueId, callback) 239 240@Component 241struct PageOne { 242 private text = ''; 243 private uniqueid = -1; 244 aboutToAppear() { 245 // 获取Navigation的uniqueId 246 let navigationUniqueId = this.queryNavigationInfo()?.uniqueId; 247 if (navigationUniqueId) { 248 this.uniqueid = navigationUniqueId.valueOf(); 249 } 250 this.text = JSON.stringify(this.uniqueid); 251 // 添加监听，指定Navigation的uniqueId 252 this.getUIContext().getUIObserver().on('navDestinationUpdateByUniqueId', this.uniqueid, (info) => { 253 console.info('NavDestination state update navigationId', JSON.stringify(info)); 254 }); 255 } 256 aboutToDisappear() { 257 // 取消监听，不选择回调时，取消所有监听的回调 258 this.getUIContext().getUIObserver().off('navDestinationUpdateByUniqueId', this.uniqueid); 259 } 260 build() { 261 NavDestination() { 262 Text("pageOne") 263 Text('navigationUniqueId是:' + this.text) 264 .width('80%') 265 .height(50) 266 .margin(50) 267 .fontSize(20) 268 }.title("pageOne") 269 } 270} 271 272@Entry 273@Component 274struct Index { 275 private stack: NavPathStack = new NavPathStack(); 276 277 @Builder 278 PageBuilder(name: string) { 279 PageOne() 280 } 281 282 build() { 283 Column() { 284 Navigation(this.stack) { 285 Button("push").onClick(() => { 286 // 将PageOne的NavDestination入栈 287 this.stack.pushPath({ name: "pageOne" }); 288 }) 289 } 290 .id("testId") 291 .title("Navigation") 292 .navDestination(this.PageBuilder) 293 } 294 .width('100%') 295 .height('100%') 296 } 297} 298``` 299 300## off('navDestinationUpdateByUniqueId')<sup>20+</sup> 301 302off(type: 'navDestinationUpdateByUniqueId', navigationUniqueId: number, callback?: Callback\<observer.NavDestinationInfo\>): void 303 304取消通过[Navigation](arkui-ts/ts-basic-components-navigation.md)的uniqueId监听[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的变化。 305 306**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 307 308**系统能力：** SystemCapability.ArkUI.ArkUI.Full 309 310**参数：** 311 312| 参数名 | 类型 | 必填 | 说明 | 313| -------- | -------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------ | 314| type | string | 是 | 监听事件，固定为'navDestinationUpdateByUniqueId'，即[NavDestination](arkui-ts/ts-basic-components-navdestination.md)组件的状态变化。 | 315| navigationUniqueId | number | 是 | 指定监听的[Navigation](arkui-ts/ts-basic-components-navigation.md)的uniqueId，可以通过[queryNavigationInfo](arkui-ts/ts-custom-component-api.md#querynavigationinfo12)获取。 | 316| callback | Callback\<observer.[NavDestinationInfo](js-apis-arkui-observer.md#navdestinationinfo)\> | 否 | 需要取消的监听回调，不传参数时，取消该[Navigation](arkui-ts/ts-basic-components-navigation.md)上所有的监听回调。 | 317 318**示例：** 319 320参考[on('navDestinationUpdateByUniqueId')](#onnavdestinationupdatebyuniqueid20)接口示例。 321 322## on('scrollEvent')<sup>12+</sup> 323 324on(type: 'scrollEvent', callback: Callback\<observer.ScrollEventInfo\>): void 325 326监听所有滚动组件滚动事件的开始和结束。滚动组件包括[List](./arkui-ts/ts-container-list.md)、[Grid](./arkui-ts/ts-container-grid.md)、[Scroll](./arkui-ts/ts-container-scroll.md)、[WaterFlow](./arkui-ts/ts-container-waterflow.md)、[ArcList](./arkui-ts/ts-container-arclist.md)。 327 328**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 329 330**系统能力：** SystemCapability.ArkUI.ArkUI.Full 331 332**参数：** 333 334| 参数名 | 类型 | 必填 | 说明 | 335| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 336| type | string | 是 | 监听事件，固定为'scrollEvent'，即滚动事件的开始和结束。 | 337| callback | Callback\<observer.[ScrollEventInfo](js-apis-arkui-observer.md#scrolleventinfo12)\> | 是 | 回调函数。返回滚动事件的信息。 | 338 339**示例：** 340 341```ts 342// Index.ets 343// 演示uiObserver.on('scrollEvent', callback) 344// uiObserver.off('scrollEvent', callback) 345// uiObserver.on('scrollEvent', options, callback) 346// uiObserver.off('scrollEvent', options, callback) 347 348import { UIObserver } from '@kit.ArkUI'; 349 350@Entry 351@Component 352struct Index { 353 scroller: Scroller = new Scroller(); 354 observer: UIObserver = this.getUIContext().getUIObserver(); 355 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7]; 356 357 build() { 358 Column() { 359 Column() { 360 Scroll(this.scroller) { 361 Column() { 362 ForEach(this.arr, (item: number) => { 363 Text(item.toString()) 364 .width('90%') 365 .height(150) 366 .backgroundColor(0xFFFFFF) 367 .borderRadius(15) 368 .fontSize(16) 369 .textAlign(TextAlign.Center) 370 .margin({ top: 10 }) 371 }, (item: string) => item) 372 }.width('100%') 373 } 374 .id('testId') 375 .height('80%') 376 } 377 .width('100%') 378 379 Row() { 380 Button('UIObserver on') 381 .onClick(() => { 382 // 添加监听 383 this.observer.on('scrollEvent', (info) => { 384 console.info('scrollEventInfo', JSON.stringify(info)); 385 }); 386 }) 387 Button('UIObserver off') 388 .onClick(() => { 389 // 取消监听，不选择回调时，取消所有监听的回调 390 this.observer.off('scrollEvent'); 391 }) 392 } 393 394 Row() { 395 Button('UIObserverWithId on') 396 .onClick(() => { 397 // 添加监听，指定滚动组件的id 398 this.observer.on('scrollEvent', { id: 'testId' }, (info) => { 399 console.info('scrollEventInfo', JSON.stringify(info)); 400 }); 401 }) 402 Button('UIObserverWithId off') 403 .onClick(() => { 404 // 取消监听，不选择回调时，取消所有监听的回调 405 this.observer.off('scrollEvent', { id: 'testId' }); 406 }) 407 } 408 } 409 .height('100%') 410 } 411} 412``` 413 414## off('scrollEvent')<sup>12+</sup> 415 416off(type: 'scrollEvent', callback?: Callback\<observer.ScrollEventInfo\>): void 417 418取消监听所有滚动组件滚动事件的开始和结束。滚动组件包括[List](./arkui-ts/ts-container-list.md)、[Grid](./arkui-ts/ts-container-grid.md)、[Scroll](./arkui-ts/ts-container-scroll.md)、[WaterFlow](./arkui-ts/ts-container-waterflow.md)、[ArcList](./arkui-ts/ts-container-arclist.md)。 419 420**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 421 422**系统能力：** SystemCapability.ArkUI.ArkUI.Full 423 424**参数：** 425 426| 参数名 | 类型 | 必填 | 说明 | 427| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 428| type | string | 是 | 监听事件，固定为'scrollEvent'，即滚动事件的开始和结束。 | 429| callback | Callback\<observer.[ScrollEventInfo](js-apis-arkui-observer.md#scrolleventinfo12)\> | 否 | 回调函数。返回滚动事件的信息。不传参数时，取消所有滚动事件的监听回调。 | 430 431**示例：** 432 433参考[on('scrollEvent')](#onscrollevent12)接口示例。 434 435## on('scrollEvent')<sup>12+</sup> 436 437on(type: 'scrollEvent', options: observer.ObserverOptions, callback: Callback\<observer.ScrollEventInfo\>): void 438 439监听指定id的滚动组件滚动事件的开始和结束。滚动组件包括[List](./arkui-ts/ts-container-list.md)、[Grid](./arkui-ts/ts-container-grid.md)、[Scroll](./arkui-ts/ts-container-scroll.md)、[WaterFlow](./arkui-ts/ts-container-waterflow.md)、[ArcList](./arkui-ts/ts-container-arclist.md)。 440 441**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 442 443**系统能力：** SystemCapability.ArkUI.ArkUI.Full 444 445**参数：** 446 447| 参数名 | 类型 | 必填 | 说明 | 448| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 449| type | string | 是 | 监听事件，固定为'scrollEvent'，即滚动事件的开始和结束。 | 450| options | [observer.ObserverOptions](js-apis-arkui-observer.md#observeroptions12) | 是 | Observer选项，包含指定监听的滚动组件的id。 | 451| callback | Callback\<observer.[ScrollEventInfo](js-apis-arkui-observer.md#scrolleventinfo12)\> | 是 | 回调函数。返回滚动事件的信息。 | 452 453**示例：** 454 455参考[on('scrollEvent')](#onscrollevent12)接口示例。 456 457## off('scrollEvent')<sup>12+</sup> 458 459off(type: 'scrollEvent', options: observer.ObserverOptions, callback?: Callback\<observer.ScrollEventInfo\>): void 460 461取消监听指定id的滚动组件滚动事件的开始和结束。滚动组件包括[List](./arkui-ts/ts-container-list.md)、[Grid](./arkui-ts/ts-container-grid.md)、[Scroll](./arkui-ts/ts-container-scroll.md)、[WaterFlow](./arkui-ts/ts-container-waterflow.md)、[ArcList](./arkui-ts/ts-container-arclist.md)。 462 463**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 464 465**系统能力：** SystemCapability.ArkUI.ArkUI.Full 466 467**参数：** 468 469| 参数名 | 类型 | 必填 | 说明 | 470| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 471| type | string | 是 | 监听事件，固定为'scrollEvent'，即滚动事件的开始和结束。 | 472| options | [observer.ObserverOptions](js-apis-arkui-observer.md#observeroptions12) | 是 | Observer选项，包含指定监听的滚动组件的id。 | 473| callback | Callback\<observer.[ScrollEventInfo](js-apis-arkui-observer.md#scrolleventinfo12)\> | 否 | 回调函数。返回滚动事件的信息。不传参数时，取消所有滚动事件的监听回调。 | 474 475**示例：** 476 477参考[on('scrollEvent')](#onscrollevent12)接口示例。 478 479## on('routerPageUpdate')<sup>11+</sup> 480 481on(type: 'routerPageUpdate', callback: Callback\<observer.RouterPageInfo\>): void 482 483监听[Router](arkts-apis-uicontext-router.md)中page页面的状态变化。 484 485**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 486 487**系统能力：** SystemCapability.ArkUI.ArkUI.Full 488 489**参数：** 490 491| 参数名 | 类型 | 必填 | 说明 | 492| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 493| type | string | 是 | 监听事件，固定为'routerPageUpdate'，即[Router](arkts-apis-uicontext-router.md)中page页面的状态变化。 | 494| callback | Callback\<observer.[RouterPageInfo](js-apis-arkui-observer.md#routerpageinfo)\> | 是 | 回调函数。携带[RouterPageInfo](js-apis-arkui-observer.md#routerpageinfo)对象，返回当前的page页面状态。 | 495 496**示例：** 497 498<!--code_no_check--> 499```ts 500// PageOne.ets 501 502@Entry 503@Component 504struct PageOne { 505 build() { 506 Column() { 507 Text("pageOne") 508 } 509 } 510} 511``` 512 513<!--code_no_check--> 514```ts 515// Index.ets 516// 演示uiObserver.on('routerPageUpdate', callback) 517// uiObserver.off('routerPageUpdate', callback) 518 519@Entry 520@Component 521struct Index { 522 aboutToAppear() { 523 // 添加监听 524 this.getUIContext().getUIObserver().on('routerPageUpdate', (info) => { 525 console.info('router page update', JSON.stringify(info)); 526 }); 527 } 528 529 aboutToDisappear() { 530 // 取消监听，不选择回调时，取消所有监听的回调 531 this.getUIContext().getUIObserver().off('routerPageUpdate'); 532 } 533 534 build() { 535 Column() { 536 Button("pushUrl").onClick(() => { 537 // router跳转到PageOne.ets页面 538 this.getUIContext().getRouter().pushUrl({ url: 'pages/PageOne' }) 539 }) 540 } 541 .width('100%') 542 .height('100%') 543 } 544} 545``` 546 547## off('routerPageUpdate')<sup>11+</sup> 548 549off(type: 'routerPageUpdate', callback?: Callback\<observer.RouterPageInfo\>): void 550 551取消监听[Router](arkts-apis-uicontext-router.md)中page页面的状态变化。 552 553**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 554 555**系统能力：** SystemCapability.ArkUI.ArkUI.Full 556 557**参数：** 558 559| 参数名 | 类型 | 必填 | 说明 | 560| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 561| type | string | 是 | 监听事件，固定为'routerPageUpdate'，即[Router](arkts-apis-uicontext-router.md)中page页面的状态变化。 | 562| callback | Callback\<observer.[RouterPageInfo](js-apis-arkui-observer.md#routerpageinfo)\> | 否 | 需要被注销的回调函数。不传参数时，取消所有[Router](arkts-apis-uicontext-router.md)中page页面状态变化的监听回调。 | 563 564**示例：** 565 566参考[on('routerPageUpdate')](#onrouterpageupdate11)接口示例。 567 568## on('densityUpdate')<sup>12+</sup> 569 570on(type: 'densityUpdate', callback: Callback\<observer.DensityInfo\>): void 571 572监听屏幕像素密度变化。 573 574**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 575 576**系统能力：** SystemCapability.ArkUI.ArkUI.Full 577 578**参数：** 579 580| 参数名 | 类型 | 必填 | 说明 | 581| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 582| type | string | 是 | 监听事件，固定为'densityUpdate'，即屏幕像素密度变化。 | 583| callback | Callback\<observer.[DensityInfo](./js-apis-arkui-observer.md#densityinfo12)\> | 是 | 回调函数。携带[DensityInfo](./js-apis-arkui-observer.md#densityinfo12)，返回变化后的屏幕像素密度。 | 584 585**示例：** 586 587```ts 588// Index.ets 589// 演示uiObserver.on('densityUpdate', callback) 590// uiObserver.off('densityUpdate', callback) 591 592import { uiObserver } from '@kit.ArkUI'; 593 594@Entry 595@Component 596struct Index { 597 @State density: number = 0; 598 @State message: string = '未注册监听'; 599 600 // 定义监听回调函数 601 densityUpdateCallback = (info: uiObserver.DensityInfo) => { 602 this.density = info.density; 603 this.message = '变化后的DPI：' + this.density.toString(); 604 } 605 606 build() { 607 Column() { 608 Text(this.message) 609 .fontSize(24) 610 .fontWeight(FontWeight.Bold) 611 Button('注册屏幕像素密度变化监听') 612 .margin({ bottom: 10 }) 613 .onClick(() => { 614 this.message = '已注册监听'; 615 // 添加监听 616 this.getUIContext().getUIObserver().on('densityUpdate', this.densityUpdateCallback); 617 }) 618 Button('解除注册屏幕像素密度变化监听') 619 .onClick(() => { 620 this.message = '未注册监听'; 621 // 取消监听 622 this.getUIContext().getUIObserver().off('densityUpdate', this.densityUpdateCallback); 623 }) 624 } 625 } 626} 627``` 628 629## off('densityUpdate')<sup>12+</sup> 630 631off(type: 'densityUpdate', callback?: Callback\<observer.DensityInfo\>): void 632 633取消监听屏幕像素密度的变化。 634 635**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 636 637**系统能力：** SystemCapability.ArkUI.ArkUI.Full 638 639**参数：** 640 641| 参数名 | 类型 | 必填 | 说明 | 642| -------- | -------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------- | 643| type | string | 是 | 监听事件，固定为'densityUpdate'，即屏幕像素密度变化。 | 644| callback | Callback\<observer.[DensityInfo](./js-apis-arkui-observer.md#densityinfo12)\> | 否 | 需要被注销的回调函数。若不指定具体的回调函数，则注销该[UIContext](arkts-apis-uicontext-uicontext.md)下所有屏幕像素密度变化事件监听。 | 645 646**示例：** 647 648参考[on('densityUpdate')](#ondensityupdate12)接口示例。 649 650## on('willDraw')<sup>12+</sup> 651 652on(type: 'willDraw', callback: Callback\<void\>): void 653 654监听每一帧绘制指令下发情况。 655 656**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 657 658**系统能力：** SystemCapability.ArkUI.ArkUI.Full 659 660**参数：** 661 662| 参数名 | 类型 | 必填 | 说明 | 663| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 664| type | string | 是 | 监听事件，固定为'willDraw'，即是否将要绘制。 | 665| callback | Callback\<void\> | 是 | 回调函数。 | 666 667**示例：** 668 669```ts 670// Index.ets 671// 演示uiObserver.on('willDraw', callback) 672// uiObserver.off('willDraw', callback) 673 674@Entry 675@Component 676struct Index { 677 // 定义监听回调函数 678 willDrawCallback = () => { 679 console.info("willDraw指令下发"); 680 } 681 682 build() { 683 Column() { 684 Button('注册绘制指令下发监听') 685 .margin({ bottom: 10 }) 686 .onClick(() => { 687 // 添加监听 688 this.getUIContext().getUIObserver().on('willDraw', this.willDrawCallback); 689 }) 690 Button('解除注册绘制指令下发监听') 691 .onClick(() => { 692 // 取消监听 693 this.getUIContext().getUIObserver().off('willDraw', this.willDrawCallback); 694 }) 695 } 696 } 697} 698``` 699 700## off('willDraw')<sup>12+</sup> 701 702off(type: 'willDraw', callback?: Callback\<void\>): void 703 704取消监听每一帧绘制指令下发情况。 705 706**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 707 708**系统能力：** SystemCapability.ArkUI.ArkUI.Full 709 710**参数：** 711 712| 参数名 | 类型 | 必填 | 说明 | 713| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 714| type | string | 是 | 监听事件，固定为'willDraw'，即是否将要绘制。 | 715| callback | Callback\<void\> | 否 | 需要被注销的回调函数。不传参数时，取消所有绘制指令下发事件的监听回调。 | 716 717**示例：** 718 719参考[on('willDraw')](#onwilldraw12)接口示例。 720 721## on('didLayout')<sup>12+</sup> 722 723on(type: 'didLayout', callback: Callback\<void\>): void 724 725监听每一帧布局完成情况。 726 727**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 728 729**系统能力：** SystemCapability.ArkUI.ArkUI.Full 730 731**参数：** 732 733| 参数名 | 类型 | 必填 | 说明 | 734| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 735| type | string | 是 | 监听事件，固定为'didLayout'，即是否布局完成。 | 736| callback | Callback\<void\> | 是 | 回调函数。 | 737 738**示例：** 739 740```ts 741// Index.ets 742// 演示uiObserver.on('didLayout', callback) 743// uiObserver.off('didLayout', callback) 744 745@Entry 746@Component 747struct Index { 748 // 定义监听回调函数 749 didLayoutCallback = () => { 750 console.info("layout布局完成"); 751 } 752 753 build() { 754 Column() { 755 Button('注册布局完成监听') 756 .margin({ bottom: 10 }) 757 .onClick(() => { 758 // 添加监听 759 this.getUIContext().getUIObserver().on('didLayout', this.didLayoutCallback); 760 }) 761 Button('解除注册注册布局完成监听') 762 .onClick(() => { 763 // 取消监听 764 this.getUIContext().getUIObserver().off('didLayout', this.didLayoutCallback); 765 }) 766 } 767 } 768} 769``` 770 771## off('didLayout')<sup>12+</sup> 772 773off(type: 'didLayout', callback?: Callback\<void\>): void 774 775取消监听每一帧布局完成情况。 776 777**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 778 779**系统能力：** SystemCapability.ArkUI.ArkUI.Full 780 781**参数：** 782 783| 参数名 | 类型 | 必填 | 说明 | 784| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 785| type | string | 是 | 监听事件，固定为'didLayout'，即是否布局完成。 | 786| callback | Callback\<void\> | 否 | 需要被注销的回调函数。不传参数时，取消所有布局完成的监听回调。 | 787 788 789**示例：** 790 791参考[on('didLayout')](#ondidlayout12)接口示例。 792 793## on('navDestinationSwitch')<sup>12+</sup> 794 795on(type: 'navDestinationSwitch', callback: Callback\<observer.NavDestinationSwitchInfo\>): void 796 797监听[Navigation](arkui-ts/ts-basic-components-navigation.md)的页面切换事件。 798 799**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 800 801**系统能力：** SystemCapability.ArkUI.ArkUI.Full 802 803**参数：** 804 805| 参数名 | 类型 | 必填 | 说明 | 806| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 807| type | string | 是 | 监听事件，固定为'navDestinationSwitch'，即[Navigation](arkui-ts/ts-basic-components-navigation.md)的页面切换事件。 | 808| callback | Callback\<observer.[NavDestinationSwitchInfo](js-apis-arkui-observer.md#navdestinationswitchinfo12)\> | 是 | 回调函数。携带[NavDestinationSwitchInfo](js-apis-arkui-observer.md#navdestinationswitchinfo12)，返回页面切换事件的信息。 | 809 810**示例：** 811 812```ts 813// Index.ets 814// 演示UIObserver.on('navDestinationSwitch', callback) 815// UIObserver.off('navDestinationSwitch', callback) 816 817import { uiObserver } from '@kit.ArkUI'; 818 819@Component 820struct PageOne { 821 build() { 822 NavDestination() { 823 Text("pageOne") 824 }.title("pageOne") 825 } 826} 827 828// 定义监听回调函数 829function callbackFunc(info: uiObserver.NavDestinationSwitchInfo) { 830 console.info(`testTag navDestinationSwitch from: ${JSON.stringify(info.from)} to: ${JSON.stringify(info.to)}`); 831} 832 833@Entry 834@Component 835struct Index { 836 private stack: NavPathStack = new NavPathStack(); 837 838 @Builder 839 PageBuilder(name: string) { 840 PageOne() 841 } 842 843 aboutToAppear() { 844 let obs = this.getUIContext().getUIObserver(); 845 // 添加监听 846 obs.on('navDestinationSwitch', callbackFunc); 847 } 848 849 aboutToDisappear() { 850 let obs = this.getUIContext().getUIObserver(); 851 // 取消监听 852 obs.off('navDestinationSwitch', callbackFunc); 853 } 854 855 build() { 856 Column() { 857 Navigation(this.stack) { 858 Button("push").onClick(() => { 859 // 将PageOne的NavDestination入栈 860 this.stack.pushPath({ name: "pageOne" }); 861 }) 862 } 863 .title("Navigation") 864 .navDestination(this.PageBuilder) 865 } 866 .width('100%') 867 .height('100%') 868 } 869} 870``` 871 872## off('navDestinationSwitch')<sup>12+</sup> 873 874off(type: 'navDestinationSwitch', callback?: Callback\<observer.NavDestinationSwitchInfo\>): void 875 876取消监听[Navigation](arkui-ts/ts-basic-components-navigation.md)的页面切换事件。 877 878**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 879 880**系统能力：** SystemCapability.ArkUI.ArkUI.Full 881 882**参数：** 883 884| 参数名 | 类型 | 必填 | 说明 | 885| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 886| type | string | 是 | 监听事件，固定为'navDestinationSwitch'，即[Navigation](arkui-ts/ts-basic-components-navigation.md)的页面切换事件。 | 887| callback | Callback\<observer.[NavDestinationSwitchInfo](js-apis-arkui-observer.md#navdestinationswitchinfo12)\> | 否 | 需要被注销的回调函数。不传参数时，取消该[Navigation](arkui-ts/ts-basic-components-navigation.md)上所有的监听回调。 | 888 889**示例：** 890 891参考[on('navDestinationSwitch')](#onnavdestinationswitch12)接口示例。 892 893## on('navDestinationSwitch')<sup>12+</sup> 894 895on(type: 'navDestinationSwitch', observerOptions: observer.NavDestinationSwitchObserverOptions, callback: Callback\<observer.NavDestinationSwitchInfo\>): void 896 897通过监听选项监听[Navigation](arkui-ts/ts-basic-components-navigation.md)的页面切换事件。 898 899**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 900 901**系统能力：** SystemCapability.ArkUI.ArkUI.Full 902 903**参数：** 904 905| 参数名 | 类型 | 必填 | 说明 | 906| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 907| type | string | 是 | 监听事件，固定为'navDestinationSwitch'，即[Navigation](arkui-ts/ts-basic-components-navigation.md)的页面切换事件。 | 908| observerOptions | observer.[NavDestinationSwitchObserverOptions](js-apis-arkui-observer.md#navdestinationswitchobserveroptions12) | 是 | 监听选项。 | 909| callback | Callback\<observer.[NavDestinationSwitchInfo](js-apis-arkui-observer.md#navdestinationswitchinfo12)\> | 是 | 回调函数。携带[NavDestinationSwitchInfo](js-apis-arkui-observer.md#navdestinationswitchinfo12)，返回页面切换事件的信息。 | 910 911**示例：** 912 913```ts 914// Index.ets 915// 演示UIObserver.on('navDestinationSwitch', observerOptions, callback) 916// UIObserver.off('navDestinationSwitch', observerOptions, callback) 917 918import { uiObserver } from '@kit.ArkUI'; 919 920@Component 921struct PageOne { 922 build() { 923 NavDestination() { 924 Text("pageOne") 925 }.title("pageOne") 926 } 927} 928 929// 定义监听回调函数 930function callbackFunc(info: uiObserver.NavDestinationSwitchInfo) { 931 console.info(`testTag navDestinationSwitch from: ${JSON.stringify(info.from)} to: ${JSON.stringify(info.to)}`); 932} 933 934@Entry 935@Component 936struct Index { 937 private stack: NavPathStack = new NavPathStack(); 938 939 @Builder 940 PageBuilder(name: string) { 941 PageOne() 942 } 943 944 aboutToAppear() { 945 let obs = this.getUIContext().getUIObserver(); 946 // 添加监听，指定Navigation的id 947 obs.on('navDestinationSwitch', { navigationId: "myNavId" }, callbackFunc); 948 } 949 950 aboutToDisappear() { 951 let obs = this.getUIContext().getUIObserver(); 952 // 取消监听 953 obs.off('navDestinationSwitch', { navigationId: "myNavId" }, callbackFunc); 954 } 955 956 build() { 957 Column() { 958 Navigation(this.stack) { 959 Button("push").onClick(() => { 960 // 将PageOne的NavDestination入栈 961 this.stack.pushPath({ name: "pageOne" }); 962 }) 963 } 964 .id("myNavId") 965 .title("Navigation") 966 .navDestination(this.PageBuilder) 967 } 968 .width('100%') 969 .height('100%') 970 } 971} 972``` 973 974## off('navDestinationSwitch')<sup>12+</sup> 975 976off(type: 'navDestinationSwitch', observerOptions: observer.NavDestinationSwitchObserverOptions, callback?: Callback\<observer.NavDestinationSwitchInfo\>): void 977 978取消通过监听选项监听[Navigation](arkui-ts/ts-basic-components-navigation.md)的页面切换事件。 979 980**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 981 982**系统能力：** SystemCapability.ArkUI.ArkUI.Full 983 984**参数：** 985 986| 参数名 | 类型 | 必填 | 说明 | 987| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 988| type | string | 是 | 监听事件，固定为'navDestinationSwitch'，即[Navigation](arkui-ts/ts-basic-components-navigation.md)的页面切换事件。 | 989| observerOptions | observer.[NavDestinationSwitchObserverOptions](js-apis-arkui-observer.md#navdestinationswitchobserveroptions12) | 是 | 监听选项。 | 990| callback | Callback\<observer.[NavDestinationSwitchInfo](js-apis-arkui-observer.md#navdestinationswitchinfo12)\> | 否 | 需要被注销的回调函数。不传参数时，取消该[Navigation](arkui-ts/ts-basic-components-navigation.md)上所有的监听回调。 | 991 992**示例：** 993 994参考[on('navDestinationSwitch')](#onnavdestinationswitch12-1)接口示例。 995 996## on('willClick')<sup>12+</sup> 997 998on(type: 'willClick', callback: GestureEventListenerCallback): void 999 1000监听点击事件指令下发情况。回调类型为[GestureEventListenerCallback](arkts-apis-uicontext-t.md#gestureeventlistenercallback12)。从API version 20开始支持屏幕朗读触控模式。 1001 1002**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1003 1004**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1005 1006**参数：** 1007 1008| 参数名 | 类型 | 必填 | 说明 | 1009| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1010| type | string | 是 | 监听事件，固定为'willClick'，用于监听点击事件指令下发情况，所注册回调将于点击事件触发前触发。 | 1011| callback | [GestureEventListenerCallback](arkts-apis-uicontext-t.md#gestureeventlistenercallback12) | 是 | 回调函数。可以获得点击事件的[GestureEvent](arkui-ts/ts-gesture-common.md#gestureevent对象说明)和组件的[FrameNode](js-apis-arkui-frameNode.md)。 | 1012 1013**示例：** 1014 1015```ts 1016// Index.ets 1017// 演示uiObserver.on('willClick', callback) 1018// uiObserver.off('willClick', callback) 1019// uiObserver.off('didClick', callback) 1020// uiObserver.off('didClick', callback) 1021 1022// 定义监听回调函数 1023function willClickGestureCallback(event: GestureEvent, node?: FrameNode) { 1024 console.info('Example willClickCallback GestureEvent is called'); 1025} 1026 1027function willClickCallback(event: ClickEvent, node?: FrameNode) { 1028 console.info('Example willClickCallback ClickEvent is called'); 1029} 1030 1031function didClickGestureCallback(event: GestureEvent, node?: FrameNode) { 1032 console.info('Example didClickCallback GestureEvent is called'); 1033} 1034 1035function didClickCallback(event: ClickEvent, node?: FrameNode) { 1036 console.info('Example didClickCallback ClickEvent is called'); 1037} 1038 1039@Entry 1040@Component 1041struct ClickExample { 1042 @State clickCount: number = 0; 1043 @State tapGestureCount: number = 0; 1044 1045 aboutToAppear(): void { 1046 // 添加监听 1047 let observer = this.getUIContext().getUIObserver(); 1048 observer.on('willClick', willClickGestureCallback); 1049 observer.on('willClick', willClickCallback); 1050 observer.on('didClick', didClickGestureCallback); 1051 observer.on('didClick', didClickCallback); 1052 } 1053 1054 aboutToDisappear(): void { 1055 // 取消监听 1056 let observer = this.getUIContext().getUIObserver(); 1057 observer.off('willClick', willClickGestureCallback); 1058 observer.off('willClick', willClickCallback); 1059 // 如果不选择回调，则会取消所有监听的回调 1060 observer.off('didClick'); 1061 } 1062 1063 build() { 1064 Column() { 1065 /** 1066 * onClick和TapGesture在后端的处理是一致的 1067 * 所以无论是触发onClick还是触发TapGesture 1068 * on('willClick')两种类型入参的回调（GestureEvent和ClickEvent）都会被触发 1069 * 同理，on('didClick')的两种回调也会被触发 1070 */ 1071 Column() { 1072 Text('Click Count: ' + this.clickCount) 1073 } 1074 .height(200) 1075 .width(300) 1076 .padding(20) 1077 .border({ width: 3 }) 1078 .margin(50) 1079 .onClick((event: ClickEvent) => { 1080 this.clickCount++; 1081 console.info('Example Click event is called'); 1082 }) 1083 1084 Column() { 1085 Text('TapGesture Count: ' + this.tapGestureCount) 1086 } 1087 .height(200) 1088 .width(300) 1089 .padding(20) 1090 .border({ width: 3 }) 1091 .margin(50) 1092 .gesture(TapGesture({ count: 2 }).onAction((event: TapGestureEvent) => { 1093 this.tapGestureCount++; 1094 console.info('Example Click event is called'); 1095 })) 1096 } 1097 } 1098} 1099``` 1100 1101## off('willClick')<sup>12+</sup> 1102 1103off(type: 'willClick', callback?: GestureEventListenerCallback): void 1104 1105取消监听点击事件指令下发情况。从API version 20开始支持屏幕朗读触控模式。 1106 1107**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1108 1109**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1110 1111**参数：** 1112 1113| 参数名 | 类型 | 必填 | 说明 | 1114| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- | 1115| type | string | 是 | 监听事件，固定为'willClick'，即点击事件指令下发情况。 | 1116| callback | [GestureEventListenerCallback](arkts-apis-uicontext-t.md#gestureeventlistenercallback12) | 否 | 需要被注销的回调函数。不传参数时，取消所有的点击事件指令下发监听回调。 | 1117 1118**示例：** 1119 1120参考[on('willClick')](#onwillclick12)接口示例。 1121 1122## on('didClick')<sup>12+</sup> 1123 1124on(type: 'didClick', callback: GestureEventListenerCallback): void 1125 1126监听点击事件指令下发情况。回调类型为[GestureEventListenerCallback](arkts-apis-uicontext-t.md#gestureeventlistenercallback12)。从API version 20开始支持屏幕朗读触控模式。 1127 1128**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1129 1130**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1131 1132**参数：** 1133 1134| 参数名 | 类型 | 必填 | 说明 | 1135| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1136| type | string | 是 | 监听事件，固定为'didClick'，用于监听点击事件指令下发情况，所注册回调将于点击事件触发后触发。 | 1137| callback | [GestureEventListenerCallback](arkts-apis-uicontext-t.md#gestureeventlistenercallback12) | 是 | 回调函数。可以获得点击事件的[GestureEvent](arkui-ts/ts-gesture-common.md#gestureevent对象说明)和组件的[FrameNode](js-apis-arkui-frameNode.md)。 | 1138 1139**示例：** 1140 1141参考[on('willClick')](#onwillclick12)接口示例。 1142 1143## off('didClick')<sup>12+</sup> 1144 1145off(type: 'didClick', callback?: GestureEventListenerCallback): void 1146 1147取消监听点击事件指令下发情况。从API version 20开始，支持屏幕朗读触控模式。 1148 1149**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1150 1151**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1152 1153**参数：** 1154 1155| 参数名 | 类型 | 必填 | 说明 | 1156| -------- | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | 1157| type | string | 是 | 监听事件，固定为'didClick'，即点击事件指令下发情况。 | 1158| callback | [GestureEventListenerCallback](arkts-apis-uicontext-t.md#gestureeventlistenercallback12) | 否 | 需要被注销的回调函数。不传参数时，取消所有的点击事件指令下发监听回调。 | 1159 1160**示例：** 1161 1162参考[on('willClick')](#onwillclick12)接口示例。 1163 1164## on('willClick')<sup>12+</sup> 1165 1166on(type: 'willClick', callback: ClickEventListenerCallback): void 1167 1168监听点击事件指令下发情况。回调类型为[ClickEventListenerCallback](arkts-apis-uicontext-t.md#clickeventlistenercallback12)。从API version 20开始支持屏幕朗读触控模式。 1169 1170**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1171 1172**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1173 1174**参数：** 1175 1176| 参数名 | 类型 | 必填 | 说明 | 1177| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1178| type | string | 是 | 监听事件，固定为'willClick'，用于监听点击事件指令下发情况，所注册回调将于点击事件触发前触发。 | 1179| callback | [ClickEventListenerCallback](arkts-apis-uicontext-t.md#clickeventlistenercallback12) | 是 | 回调函数。可以获得点击事件的[ClickEvent](arkui-ts/ts-universal-events-click.md#clickevent对象说明)和组件的[FrameNode](js-apis-arkui-frameNode.md)。 | 1180 1181**示例：** 1182 1183参考[on('willClick')](#onwillclick12)接口示例。 1184 1185## off('willClick')<sup>12+</sup> 1186 1187off(type: 'willClick', callback?: ClickEventListenerCallback): void 1188 1189取消监听点击事件指令下发情况。从API version 20开始，支持屏幕朗读触控模式。 1190 1191**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1192 1193**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1194 1195**参数：** 1196 1197| 参数名 | 类型 | 必填 | 说明 | 1198| -------- | ----------------------------------------------------------- | ---- | ----------------------------------------------------- | 1199| type | string | 是 | 监听事件，固定为'willClick'，即点击事件指令下发情况。 | 1200| callback | [ClickEventListenerCallback](arkts-apis-uicontext-t.md#clickeventlistenercallback12) | 否 | 需要被注销的回调函数。不传参数时，取消所有的点击事件指令下发监听回调。 | 1201 1202**示例：** 1203 1204参考[on('willClick')](#onwillclick12)接口示例。 1205 1206## on('didClick')<sup>12+</sup> 1207 1208on(type: 'didClick', callback: ClickEventListenerCallback): void 1209 1210监听点击事件指令下发情况。回调类型为[ClickEventListenerCallback](arkts-apis-uicontext-t.md#clickeventlistenercallback12)。从API version 20开始支持屏幕朗读触控模式。 1211 1212**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1213 1214**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1215 1216**参数：** 1217 1218| 参数名 | 类型 | 必填 | 说明 | 1219| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1220| type | string | 是 | 监听事件，固定为'didClick'，用于监听点击事件指令下发情况，所注册回调将于点击事件触发后触发。 | 1221| callback | [ClickEventListenerCallback](arkts-apis-uicontext-t.md#clickeventlistenercallback12) | 是 | 回调函数。可以获得点击事件的[ClickEvent](arkui-ts/ts-universal-events-click.md#clickevent对象说明)和组件的[FrameNode](js-apis-arkui-frameNode.md)。 | 1222 1223**示例：** 1224 1225参考[on('willClick')](#onwillclick12)接口示例。 1226 1227## off('didClick')<sup>12+</sup> 1228 1229off(type: 'didClick', callback?: ClickEventListenerCallback): void 1230 1231取消监听点击事件指令下发情况。从API version 20开始支持屏幕朗读触控模式。 1232 1233**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1234 1235**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1236 1237**参数：** 1238 1239| 参数名 | 类型 | 必填 | 说明 | 1240| -------- | ----------------------------------------------------------- | ---- | ---------------------------------------------------- | 1241| type | string | 是 | 监听事件，固定为'didClick'，即点击事件指令下发情况。 | 1242| callback | [ClickEventListenerCallback](arkts-apis-uicontext-t.md#clickeventlistenercallback12) | 否 | 需要被注销的回调函数。不传参数时，取消所有的点击事件指令下发监听回调。 | 1243 1244**示例：** 1245 1246参考[on('willClick')](#onwillclick12)接口示例。 1247 1248## on('tabContentUpdate')<sup>12+</sup> 1249 1250on(type: 'tabContentUpdate', callback: Callback\<observer.TabContentInfo\>): void 1251 1252监听[TabContent](arkui-ts/ts-container-tabcontent.md)页面的切换事件。 1253 1254**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1255 1256**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1257 1258**参数：** 1259 1260| 参数名 | 类型 | 必填 | 说明 | 1261| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1262| type | string | 是 | 监听事件，固定为'tabContentUpdate'，即[TabContent](arkui-ts/ts-container-tabcontent.md)页面的切换事件。 | 1263| callback | Callback\<observer.[TabContentInfo](js-apis-arkui-observer.md#tabcontentinfo12)\> | 是 | 回调函数。携带[TabContentInfo](js-apis-arkui-observer.md#tabcontentinfo12)，返回[TabContent](arkui-ts/ts-container-tabcontent.md)页面切换事件的信息。 | 1264 1265**示例：** 1266 1267```ts 1268// Index.ets 1269// 演示uiObserver.on('tabContentUpdate', callback) 1270// uiObserver.off('tabContentUpdate', callback) 1271 1272import { uiObserver } from '@kit.ArkUI'; 1273 1274// 定义监听回调函数 1275function callbackFunc(info: uiObserver.TabContentInfo) { 1276 console.info('tabContentUpdate', JSON.stringify(info)); 1277} 1278 1279@Entry 1280@Component 1281struct TabsExample { 1282 1283 aboutToAppear(): void { 1284 let observer = this.getUIContext().getUIObserver(); 1285 // 添加监听 1286 observer.on('tabContentUpdate', callbackFunc); 1287 } 1288 1289 aboutToDisappear(): void { 1290 let observer = this.getUIContext().getUIObserver(); 1291 // 取消监听 1292 observer.off('tabContentUpdate', callbackFunc); 1293 } 1294 1295 build() { 1296 Column() { 1297 Tabs() { 1298 TabContent() { 1299 Column().width('100%').height('100%').backgroundColor('#00CB87') 1300 }.tabBar('green').id('tabContentId0') 1301 1302 TabContent() { 1303 Column().width('100%').height('100%').backgroundColor('#007DFF') 1304 }.tabBar('blue').id('tabContentId1') 1305 1306 TabContent() { 1307 Column().width('100%').height('100%').backgroundColor('#FFBF00') 1308 }.tabBar('yellow').id('tabContentId2') 1309 1310 TabContent() { 1311 Column().width('100%').height('100%').backgroundColor('#E67C92') 1312 }.tabBar('pink').id('tabContentId3') 1313 } 1314 .width(360) 1315 .height(296) 1316 .backgroundColor('#F1F3F5') 1317 .id('tabsId') 1318 }.width('100%') 1319 } 1320} 1321``` 1322 1323## off('tabContentUpdate')<sup>12+</sup> 1324 1325off(type: 'tabContentUpdate', callback?: Callback\<observer.TabContentInfo\>): void 1326 1327取消监听[TabContent](arkui-ts/ts-container-tabcontent.md)页面的切换事件。 1328 1329**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1330 1331**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1332 1333**参数：** 1334 1335| 参数名 | 类型 | 必填 | 说明 | 1336| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1337| type | string | 是 | 监听事件，固定为'tabContentUpdate'，即[TabContent](arkui-ts/ts-container-tabcontent.md)页面的切换事件。 | 1338| callback | Callback\<observer.[TabContentInfo](js-apis-arkui-observer.md#tabcontentinfo12)\> | 否 | 需要被注销的回调函数。不传参数时，取消该[Tabs](arkui-ts/ts-container-tabs.md)上所有的监听回调。 | 1339 1340**示例：** 1341 1342参考[on('tabContentUpdate')](#ontabcontentupdate12)接口示例。 1343 1344## on('tabContentUpdate')<sup>12+</sup> 1345 1346on(type: 'tabContentUpdate', options: observer.ObserverOptions, callback: Callback\<observer.TabContentInfo\>): void 1347 1348通过[Tabs](arkui-ts/ts-container-tabs.md)组件的id监听[TabContent](arkui-ts/ts-container-tabcontent.md)页面的切换事件。 1349 1350**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1351 1352**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1353 1354**参数：** 1355 1356| 参数名 | 类型 | 必填 | 说明 | 1357| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1358| type | string | 是 | 监听事件，固定为'tabContentUpdate'，即[TabContent](arkui-ts/ts-container-tabcontent.md)页面的切换事件。 | 1359| options | observer.[ObserverOptions](js-apis-arkui-observer.md#observeroptions12) | 是 | 指定监听的[Tabs](arkui-ts/ts-container-tabs.md)组件的id。 | 1360| callback | Callback\<observer.[TabContentInfo](js-apis-arkui-observer.md#tabcontentinfo12)\> | 是 | 回调函数。携带TabContentInfo，返回[TabContent](arkui-ts/ts-container-tabcontent.md)页面切换事件的信息。 | 1361 1362**示例：** 1363 1364```ts 1365// Index.ets 1366// 演示uiObserver.on('tabContentUpdate', options, callback) 1367// uiObserver.off('tabContentUpdate', options, callback) 1368 1369import { uiObserver } from '@kit.ArkUI'; 1370 1371// 定义监听回调函数 1372function callbackFunc(info: uiObserver.TabContentInfo) { 1373 console.info('tabContentUpdate', JSON.stringify(info)); 1374} 1375 1376@Entry 1377@Component 1378struct TabsExample { 1379 1380 aboutToAppear(): void { 1381 let observer = this.getUIContext().getUIObserver(); 1382 // 添加监听，指定Tabs的id 1383 observer.on('tabContentUpdate', { id: 'tabsId' }, callbackFunc); 1384 } 1385 1386 aboutToDisappear(): void { 1387 let observer = this.getUIContext().getUIObserver(); 1388 // 取消监听 1389 observer.off('tabContentUpdate', { id: 'tabsId' }, callbackFunc); 1390 } 1391 1392 build() { 1393 Column() { 1394 Tabs() { 1395 TabContent() { 1396 Column().width('100%').height('100%').backgroundColor('#00CB87') 1397 }.tabBar('green').id('tabContentId0') 1398 1399 TabContent() { 1400 Column().width('100%').height('100%').backgroundColor('#007DFF') 1401 }.tabBar('blue').id('tabContentId1') 1402 1403 TabContent() { 1404 Column().width('100%').height('100%').backgroundColor('#FFBF00') 1405 }.tabBar('yellow').id('tabContentId2') 1406 1407 TabContent() { 1408 Column().width('100%').height('100%').backgroundColor('#E67C92') 1409 }.tabBar('pink').id('tabContentId3') 1410 } 1411 .width(360) 1412 .height(296) 1413 .backgroundColor('#F1F3F5') 1414 .id('tabsId') 1415 }.width('100%') 1416 } 1417} 1418``` 1419 1420## off('tabContentUpdate')<sup>12+</sup> 1421 1422off(type: 'tabContentUpdate', options: observer.ObserverOptions, callback?: Callback\<observer.TabContentInfo\>): void 1423 1424取消通过[Tabs](arkui-ts/ts-container-tabs.md)组件的id监听[TabContent](arkui-ts/ts-container-tabcontent.md)页面的切换事件。 1425 1426**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1427 1428**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1429 1430**参数：** 1431 1432| 参数名 | 类型 | 必填 | 说明 | 1433| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1434| type | string | 是 | 监听事件，固定为'tabContentUpdate'，即[TabContent](arkui-ts/ts-container-tabcontent.md)页面的切换事件。 | 1435| options | observer.[ObserverOptions](js-apis-arkui-observer.md#observeroptions12) | 是 | 指定监听的[Tabs](arkui-ts/ts-container-tabs.md)组件的id。 | 1436| callback | Callback\<observer.[TabContentInfo](js-apis-arkui-observer.md#tabcontentinfo12)\> | 否 | 需要被注销的回调函数。不传参数时，取消该[Tabs](arkui-ts/ts-container-tabs.md)上所有的监听回调。 | 1437 1438**示例：** 1439 1440参考[on('tabContentUpdate')](#ontabcontentupdate12-1)接口示例。 1441 1442## on('beforePanStart')<sup>19+</sup> 1443 1444on(type: 'beforePanStart', callback: PanListenerCallback): void 1445 1446监听Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件，在[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件执行之前执行callback回调。支持手指滑动、鼠标滑动、鼠标滚轮和触摸板拖动，暂不支持屏幕朗读触控模式。 1447 1448**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1449 1450**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1451 1452**参数：** 1453 1454| 参数名 | 类型 | 必填 | 说明 | 1455| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1456| type | string | 是 | 监听事件，固定为'beforePanStart'，用于监听Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件执行前的指令下发情况，所注册回调将于Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件触发前触发。 | 1457| callback | [PanListenerCallback](arkts-apis-uicontext-t.md#panlistenercallback19) | 是 | 回调函数。可以获得Pan手势事件的[GestureEvent](arkui-ts/ts-gesture-common.md#gestureevent对象说明)，[GestureRecognizer](arkui-ts/ts-gesture-common.md#gesturerecognizer12)和组件的[FrameNode](js-apis-arkui-frameNode.md)。 | 1458 1459**示例：** 1460 1461```ts 1462// Index.ets 1463// 演示uiObserver.on('beforePanStart', callback) 1464// uiObserver.off('beforePanStart', callback) 1465// uiObserver.on('afterPanStart', callback) 1466// uiObserver.off('afterPanStart', callback) 1467// uiObserver.on('beforePanEnd', callback) 1468// uiObserver.off('beforePanEnd', callback) 1469// uiObserver.on('afterPanEnd', callback) 1470// uiObserver.off('afterPanEnd', callback) 1471 1472// 在页面Component中使用 1473let TEST_TAG: string = 'node'; 1474 1475// 定义监听回调函数 1476function callbackFunc() { 1477 console.info('on == beforePanStart'); 1478} 1479 1480function afterPanCallBack() { 1481 console.info('on == afterPanStart'); 1482} 1483 1484function beforeEndCallBack() { 1485 console.info('on == beforeEnd'); 1486} 1487 1488function afterEndCallBack() { 1489 console.info('on == afterEnd'); 1490} 1491 1492function beforeStartCallBack() { 1493 console.info('on == beforeStartCallBack'); 1494} 1495 1496function panGestureCallBack(event: GestureEvent, current: GestureRecognizer, node?: FrameNode) { 1497 TEST_TAG = 'panGestureEvent'; 1498 console.info('===' + TEST_TAG + '=== event.repeat is ' + event.repeat); 1499 console.info('===' + TEST_TAG + '=== event target is ' + event.target.id); 1500 TEST_TAG = 'panGestureCurrent'; 1501 console.info('===' + TEST_TAG + '=== current.getTag() is ' + current.getTag()); 1502 TEST_TAG = 'panGestureNode'; 1503 console.info('===' + TEST_TAG + '=== node?.getId() is ' + node?.getId()); 1504} 1505 1506 1507@Entry 1508@Component 1509struct PanExample { 1510 @State offsetX: number = 0; 1511 @State offsetY: number = 0; 1512 @State positionX: number = 0; 1513 @State positionY: number = 0; 1514 private panOption: PanGestureOptions = new PanGestureOptions({direction: PanDirection.All }); 1515 1516 aboutToAppear(): void { 1517 let observer = this.getUIContext().getUIObserver(); 1518 // 添加监听 1519 observer.on('beforePanStart', callbackFunc); 1520 observer.on('beforePanStart', panGestureCallBack); 1521 observer.on('beforePanStart', beforeStartCallBack); 1522 observer.on('afterPanStart', afterPanCallBack); 1523 observer.on('beforePanEnd', beforeEndCallBack); 1524 observer.on('afterPanEnd', afterEndCallBack); 1525 } 1526 1527 aboutToDisappear(): void { 1528 let observer = this.getUIContext().getUIObserver(); 1529 // 取消监听 1530 observer.off('beforePanStart', callbackFunc); 1531 observer.off('beforePanStart'); 1532 observer.off('afterPanStart', afterPanCallBack); 1533 observer.off('beforePanEnd'); 1534 observer.off('afterPanEnd'); 1535 } 1536 1537 build() { 1538 Column(){ 1539 Column(){ 1540 Text('PanGesture :\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY) 1541 } 1542 .height(200) 1543 .width(300) 1544 .padding(20) 1545 .border({ width: 3 }) 1546 .margin(50) 1547 .translate({ x: this.offsetX, y: this.offsetY, z: 0 }) 1548 .id('columnOuter') 1549 .gesture( 1550 PanGesture(this.panOption) 1551 .onActionStart((event: GestureEvent) => { 1552 console.info('Pan start'); 1553 }) 1554 .onActionUpdate((event: GestureEvent) => { 1555 if (event) { 1556 this.offsetX = this.positionX + event.offsetX; 1557 this.offsetY = this.positionY + event.offsetY; 1558 } 1559 }) 1560 .onActionEnd((event: GestureEvent) => { 1561 this.positionX = this.offsetX; 1562 this.positionY = this.offsetY; 1563 console.info('Pan end'); 1564 })) 1565 } 1566 } 1567} 1568``` 1569 1570## off('beforePanStart')<sup>19+</sup> 1571 1572off(type: 'beforePanStart', callback?: PanListenerCallback): void 1573 1574取消[on('beforePanStart')](#onbeforepanstart19)监听Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件执行前的callback回调。 1575 1576**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1577 1578**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1579 1580**参数：** 1581 1582| 参数名 | 类型 | 必填 | 说明 | 1583| -------- | ----------------------------------------------------------- | ---- | ---------------------------------------------------- | 1584| type | string | 是 | 监听事件，固定为'beforePanStart'，即Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件执行前的指令下发情况。 | 1585| callback | [PanListenerCallback](arkts-apis-uicontext-t.md#panlistenercallback19) | 否 | 需要被注销的回调函数。不传参数时，取消所有的Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件执行前的指令下发监听回调。 | 1586 1587**示例：** 1588 1589参考[on('beforePanStart')](#onbeforepanstart19)接口示例。 1590 1591## on('afterPanStart')<sup>19+</sup> 1592 1593on(type: 'afterPanStart', callback: PanListenerCallback): void 1594 1595监听Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件执行后的指令下发情况，在[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件执行之后执行callback回调。支持手指滑动、鼠标滑动、鼠标滚轮和触摸板拖动，暂不支持屏幕朗读触控模式。 1596 1597**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1598 1599**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1600 1601**参数：** 1602 1603| 参数名 | 类型 | 必填 | 说明 | 1604| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1605| type | string | 是 | 监听事件，固定为'afterPanStart'，用于监听Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件执行后的指令下发情况，所注册回调将于Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件触发后触发。 | 1606| callback | [PanListenerCallback](arkts-apis-uicontext-t.md#panlistenercallback19) | 是 | 回调函数。可以获得Pan手势事件的[GestureEvent](arkui-ts/ts-gesture-common.md#gestureevent对象说明)，[GestureRecognizer](arkui-ts/ts-gesture-common.md#gesturerecognizer12)和组件的[FrameNode](js-apis-arkui-frameNode.md)。 | 1607 1608**示例：** 1609 1610参考[on('beforePanStart')](#onbeforepanstart19)接口示例。 1611 1612## off('afterPanStart')<sup>19+</sup> 1613 1614off(type: 'afterPanStart', callback?: PanListenerCallback): void 1615 1616取消[on('afterPanStart')](#onafterpanstart19)监听Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#事件)事件执行后的callback回调。 1617 1618**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1619 1620**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1621 1622**参数：** 1623 1624| 参数名 | 类型 | 必填 | 说明 | 1625| -------- | ----------------------------------------------------------- | ---- | ---------------------------------------------------- | 1626| type | string | 是 | 监听事件，固定为'afterPanStart'，即Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件执行后的指令下发情况。 | 1627| callback | [PanListenerCallback](arkts-apis-uicontext-t.md#panlistenercallback19) | 否 | 需要被注销的回调函数。不传参数时，取消所有的Pan手势[onActionStart](arkui-ts/ts-basic-gestures-pangesture.md#onactionstart)事件执行后的指令下发监听回调。 | 1628 1629**示例：** 1630 1631参考[on('beforePanStart')](#onbeforepanstart19)接口示例。 1632 1633## on('beforePanEnd')<sup>19+</sup> 1634 1635on(type: 'beforePanEnd', callback: PanListenerCallback): void 1636 1637监听Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行前的指令下发情况，在[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行之前执行callback回调。支持手指滑动、鼠标滑动、鼠标滚轮和触摸板拖动，暂不支持屏幕朗读触控模式。 1638 1639**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1640 1641**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1642 1643**参数：** 1644 1645| 参数名 | 类型 | 必填 | 说明 | 1646| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1647| type | string | 是 | 监听事件，固定为'beforePanEnd'，用于监听Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行前的指令下发情况，所注册回调将于Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件触发前触发。 | 1648| callback | [PanListenerCallback](arkts-apis-uicontext-t.md#panlistenercallback19) | 是 | 回调函数。可以获得Pan手势事件的[GestureEvent](arkui-ts/ts-gesture-common.md#gestureevent对象说明)，[GestureRecognizer](arkui-ts/ts-gesture-common.md#gesturerecognizer12)和组件的[FrameNode](js-apis-arkui-frameNode.md)。 | 1649 1650**示例：** 1651 1652参考[on('beforePanStart')](#onbeforepanstart19)接口示例。 1653 1654## off('beforePanEnd')<sup>19+</sup> 1655 1656off(type: 'beforePanEnd', callback?: PanListenerCallback): void 1657 1658取消[on('beforePanEnd')](#onbeforepanend19)监听Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行前的callback回调。 1659 1660**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1661 1662**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1663 1664**参数：** 1665 1666| 参数名 | 类型 | 必填 | 说明 | 1667| -------- | ----------------------------------------------------------- | ---- | ---------------------------------------------------- | 1668| type | string | 是 | 监听事件，固定为'beforePanEnd'，即Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行前的指令下发情况。 | 1669| callback | [PanListenerCallback](arkts-apis-uicontext-t.md#panlistenercallback19) | 否 | 需要被注销的回调函数。不传参数时，取消所有的Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行前的指令下发监听回调。 | 1670 1671**示例：** 1672 1673参考[on('beforePanStart')](#onbeforepanstart19)接口示例。 1674 1675## on('afterPanEnd')<sup>19+</sup> 1676 1677on(type: 'afterPanEnd', callback: PanListenerCallback): void 1678 1679监听Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行后的指令下发情况，在[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行之后执行callback回调。支持手指滑动、鼠标滑动、鼠标滚轮和触摸板拖动，暂不支持屏幕朗读触控模式。 1680 1681**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1682 1683**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1684 1685**参数：** 1686 1687| 参数名 | 类型 | 必填 | 说明 | 1688| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1689| type | string | 是 | 监听事件，固定为'beforePanEnd'，用于监听Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行后的指令下发情况，所注册回调将于Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件触发后触发。 | 1690| callback | [PanListenerCallback](arkts-apis-uicontext-t.md#panlistenercallback19) | 是 | 回调函数。可以获得Pan手势事件的[GestureEvent](arkui-ts/ts-gesture-common.md#gestureevent对象说明)，[GestureRecognizer](arkui-ts/ts-gesture-common.md#gesturerecognizer12)和组件的[FrameNode](js-apis-arkui-frameNode.md)。 | 1691 1692**示例：** 1693 1694参考[on('beforePanStart')](#onbeforepanstart19)接口示例。 1695 1696## off('afterPanEnd')<sup>19+</sup> 1697 1698off(type: 'afterPanEnd', callback?: PanListenerCallback): void 1699 1700取消[on('afterPanEnd')](#onafterpanend19)监听Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行后的callback回调。 1701 1702**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1703 1704**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1705 1706**参数：** 1707 1708| 参数名 | 类型 | 必填 | 说明 | 1709| -------- | ----------------------------------------------------------- | ---- | ---------------------------------------------------- | 1710| type | string | 是 | 监听事件，固定为'afterPanEnd'，即Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行后的指令下发情况。 | 1711| callback | [PanListenerCallback](arkts-apis-uicontext-t.md#panlistenercallback19) | 否 | 需要被注销的回调函数。不传参数时，取消所有的Pan手势[onActionEnd](arkui-ts/ts-basic-gestures-pangesture.md#onactionend)事件执行后的指令下发监听回调。 | 1712 1713**示例：** 1714 1715参考[on('beforePanStart')](#onbeforepanstart19)接口示例。 1716 1717## on('nodeRenderState')<sup>20+</sup> 1718 1719on(type: 'nodeRenderState', nodeIdentity: NodeIdentity, callback: NodeRenderStateChangeCallback): void 1720 1721注册一个回调函数，以便在特定节点的渲染状态发生变化时调用，当注册成功时，此回调将立即执行一次。 1722 1723注意节点数量的限制。出于性能考虑，在单个UI实例中，注册节点太多，将会抛出异常。 1724 1725通常，当组件被移动到屏幕外时，会收到RENDER_OUT的通知。但在某些情况下，即使组件移动到屏幕外也不会触发RENDER_OUT通知。例如，具有缓存功能的组件[Swiper](./arkui-ts/ts-container-swiper.md)，即使[cachedCount](./arkui-ts/ts-container-swiper.md#cachedcount15)属性中的参数isShown配置为true，也不会触发RENDER_OUT通知。 1726 1727**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1728 1729**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1730 1731**参数：** 1732 1733| 参数名 | 类型 | 必填 | 说明 | 1734| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1735| type | string | 是 | 监听事件，固定为'nodeRenderState'，用于监听节点渲染状态发生改变。 | 1736| nodeIdentity | [NodeIdentity](arkts-apis-uicontext-t.md#nodeidentity20) | 是 | 节点标识。 | 1737| callback | [NodeRenderStateChangeCallback](arkts-apis-uicontext-t.md#noderenderstatechangecallback20) | 是 | 回调函数。可以获得节点渲染状态改变事件的[NodeRenderState](arkts-apis-uicontext-e.md#noderenderstate20)和组件的[FrameNode](js-apis-arkui-frameNode.md)。 | 1738 1739**错误码：** 1740 1741以下错误码的详细介绍请参见[注册节点渲染状态监听错误码](errorcode-node-render-monitor.md)。 1742 1743| 错误码ID | 错误信息 | 1744| --------- | ------- | 1745| 161001 | The count of nodes monitoring render state is over the limitation. | 1746 1747**示例：** 1748 1749该示例展示了如何对目标组件添加监听和取消监听。当向左滑动，被监听组件从屏幕消失，会收到RENDER_OUT的通知，然后向右滑动，被监听组件重新出现在屏幕上，会收到RENDER_IN通知。 1750 1751```ts 1752// Index.ets 1753// 演示uiObserver.on('nodeRenderState', nodeIdentity, callback) 1754// uiObserver.off('nodeRenderState', nodeIdentity, callback) 1755 1756// 在页面Component中使用 1757import { NodeRenderState } from '@kit.ArkUI'; 1758 1759@Entry 1760@Component 1761struct Index { 1762 @State fontColor: string = '#182431'; 1763 @State selectedFontColor: string = '#007DFF'; 1764 @State currentIndex: number = 0; 1765 @State selectedIndex: number = 0; 1766 @State notice: string = ""; 1767 private controller: TabsController = new TabsController(); 1768 1769 @Builder 1770 tabBuilder(index: number, name: string) { 1771 Column() { 1772 Text(name) 1773 .fontColor(this.selectedIndex === index ? this.selectedFontColor : this.fontColor) 1774 .fontSize(16) 1775 .fontWeight(this.selectedIndex === index ? 500 : 400) 1776 .lineHeight(22) 1777 .margin({ top: 17, bottom: 7 }) 1778 Divider() 1779 .strokeWidth(2) 1780 .color('#007DFF') 1781 .opacity(this.selectedIndex === index ? 1 : 0) 1782 }.width('100%') 1783 } 1784 1785 build() { 1786 Column() { 1787 Tabs({ barPosition: BarPosition.Start, index: this.currentIndex, controller: this.controller }) { 1788 TabContent() { 1789 Column() { 1790 Column() { 1791 Button("被监听节点").margin({ top: 5 }).id("button_1") 1792 Button("添加监听").margin({ top: 5 }).onClick(() => { 1793 let node: FrameNode | null = this.getUIContext().getFrameNodeById("button_1"); 1794 if (node) { 1795 let observer = this.getUIContext().getUIObserver(); 1796 // 添加监听 1797 observer.on("nodeRenderState", node?.getUniqueId(), (state: NodeRenderState, node?: FrameNode) => { 1798 // 根据节点状态修改通知信息 1799 if (state === 0) { 1800 this.notice = "RENDER_IN"; 1801 } else { 1802 this.notice = "RENDER_OUT"; 1803 } 1804 console.info("节点状态发生改变，当前状态：", state); 1805 }) 1806 } 1807 }) 1808 Button("取消监听").margin({ top: 5 }).onClick(() => { 1809 let node: FrameNode | null = this.getUIContext().getFrameNodeById("button_1"); 1810 if (node) { 1811 let observer = this.getUIContext().getUIObserver(); 1812 // 取消监听，不选择回调时，取消所有监听的回调 1813 observer.off("nodeRenderState", node?.getUniqueId()); 1814 } 1815 this.notice = ""; 1816 }) 1817 } 1818 }.width('100%').height('100%').backgroundColor('#00CB87') 1819 }.tabBar(this.tabBuilder(0, 'green')) 1820 1821 TabContent() { 1822 Column().width('100%').height('100%').backgroundColor('#007DFF') 1823 }.tabBar(this.tabBuilder(1, 'blue')) 1824 1825 TabContent() { 1826 Column().width('100%').height('100%').backgroundColor('#FFBF00') 1827 }.tabBar(this.tabBuilder(2, 'yellow')) 1828 1829 TabContent() { 1830 Column().width('100%').height('100%').backgroundColor('#E67C92') 1831 }.tabBar(this.tabBuilder(3, 'pink')) 1832 } 1833 .vertical(false) 1834 .barMode(BarMode.Fixed) 1835 .barWidth(360) 1836 .barHeight(56) 1837 .animationDuration(400) 1838 .onChange((index: number) => { 1839 this.currentIndex = index; 1840 this.selectedIndex = index; 1841 }) 1842 .onAnimationStart((index: number, targetIndex: number, event: TabsAnimationEvent) => { 1843 if (index === targetIndex) { 1844 return; 1845 } 1846 this.selectedIndex = targetIndex; 1847 }) 1848 .width(360) 1849 .height(296) 1850 .margin({ top: 52 }) 1851 .backgroundColor('#F1F3F5') 1852 1853 Text(`收到的通知: ${this.notice}`) 1854 .fontSize(20) 1855 .margin(10) 1856 }.width('100%') 1857 } 1858} 1859``` 1860 1861 1862## off('nodeRenderState')<sup>20+</sup> 1863 1864off(type: 'nodeRenderState', nodeIdentity: NodeIdentity, callback?: NodeRenderStateChangeCallback): void 1865 1866取消监听节点渲染状态发生变化的callback回调。 1867 1868**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1869 1870**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1871 1872**参数：** 1873 1874| 参数名 | 类型 | 必填 | 说明 | 1875| -------- | ----------------------------------------------------------- | ---- | ---------------------------------------------------- | 1876| type | string | 是 | 监听事件，固定为'nodeRenderState'，即节点渲染状态变化指令下发情况。 | 1877| nodeIdentity | [NodeIdentity](arkts-apis-uicontext-t.md#nodeidentity20) | 是 | 节点标识。 | 1878| callback | [NodeRenderStateChangeCallback](arkts-apis-uicontext-t.md#noderenderstatechangecallback20) | 否 | 需要被注销的回调函数。不传参数时，取消该节点所有的渲染状态变化指令下发监听回调。 | 1879 1880**示例：** 1881 1882参考[on('nodeRenderState')](#onnoderenderstate20)接口示例。 1883 1884## addGlobalGestureListener<sup>20+</sup> 1885 1886addGlobalGestureListener(type: GestureListenerType, option: GestureObserverConfigs, callback: GestureListenerCallback): void 1887 1888注册回调函数以监听手势触发信息。 1889 1890**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1891 1892**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1893 1894**参数：** 1895 1896| 参数名 | 类型 | 必填 | 说明 | 1897| -------- | ----------- | ---- | ----------- | 1898| type | [GestureListenerType](arkts-apis-uicontext-e.md#gesturelistenertype20) | 是 |要监听的手势类型。 | 1899| option | [GestureObserverConfigs](arkts-apis-uicontext-i.md#gestureobserverconfigs20) | 是 | 绑定全局监听器时的配置选项。 | 1900| callback | [GestureListenerCallback](arkts-apis-uicontext-t.md#gesturelistenercallback20) | 是 | 手势状态更新时的回调函数。 | 1901 1902**示例：** 1903 1904该示例使用全局手势监听器实时追踪Tap、Pan和LongPress三个独立区域的触发状态，记录各手势的触发次数和最后操作信息，并在组件生命周期内自动管理监听器的注册与注销。 1905 1906```ts 1907// Index.ets 1908// 演示uiObserver.addGlobalGestureListener(type, option, callback) 1909// uiObserver.removeGlobalGestureListener(type, callback) 1910 1911import { GestureListenerType, GestureActionPhase, GestureTriggerInfo, GestureListenerCallback } from '@kit.ArkUI'; 1912 1913@Entry 1914@Component 1915struct Index { 1916 @State message: string = '全局手势监控'; 1917 @State tapCount: number = 0; 1918 @State panCount: number = 0; 1919 @State longPressCount: number = 0; 1920 @State lastAction: string = '无'; 1921 @State lastArea: string = '无'; 1922 1923 // 存储监听器回调引用 1924 private tapCallback?: GestureListenerCallback; 1925 private panCallback?: GestureListenerCallback; 1926 private longPressCallback?: GestureListenerCallback; 1927 1928 // 启用全局监听 1929 aboutToAppear() { 1930 this.addGlobalListeners(); 1931 } 1932 // 终止全局监听 1933 aboutToDisappear() { 1934 this.removeGlobalListeners(); 1935 } 1936 1937 private addGlobalListeners() { 1938 const observer = this.getUIContext().getUIObserver(); 1939 1940 // Tap监听任务 1941 this.tapCallback = (info: GestureTriggerInfo) => { 1942 if (info.event?.target?.id === 'tap-area') { 1943 this.tapCount++; 1944 this.lastAction = '点击'; 1945 this.lastArea = 'Tap区域'; 1946 } 1947 }; 1948 observer.addGlobalGestureListener( 1949 GestureListenerType.TAP, 1950 { actionPhases: [GestureActionPhase.WILL_START, GestureActionPhase.WILL_END] }, 1951 this.tapCallback 1952 ); 1953 1954 // Pan监听任务 1955 this.panCallback = (info: GestureTriggerInfo) => { 1956 if (info.event?.target?.id === 'pan-area') { 1957 this.panCount++; 1958 this.lastAction = '平移'; 1959 this.lastArea = 'Pan区域'; 1960 } 1961 }; 1962 observer.addGlobalGestureListener( 1963 GestureListenerType.PAN, 1964 { 1965 actionPhases: [GestureActionPhase.WILL_START, GestureActionPhase.WILL_END] 1966 }, 1967 this.panCallback 1968 ); 1969 1970 // LongPress监听任务 1971 this.longPressCallback = (info: GestureTriggerInfo) => { 1972 if (info.event?.target?.id === 'longpress-area') { 1973 this.longPressCount++; 1974 this.lastAction = '长按'; 1975 this.lastArea = 'LongPress区域'; 1976 } 1977 }; 1978 observer.addGlobalGestureListener( 1979 GestureListenerType.LONG_PRESS, 1980 { 1981 actionPhases: [GestureActionPhase.WILL_START, GestureActionPhase.WILL_END] 1982 }, 1983 this.longPressCallback 1984 ); 1985 } 1986 1987 private removeGlobalListeners() { 1988 const observer = this.getUIContext().getUIObserver(); 1989 if (this.tapCallback) { 1990 observer.removeGlobalGestureListener(0, this.tapCallback); 1991 } 1992 if (this.panCallback) { 1993 observer.removeGlobalGestureListener(2, this.panCallback); 1994 } 1995 if (this.longPressCallback) { 1996 observer.removeGlobalGestureListener(1, this.longPressCallback); 1997 } 1998 } 1999 2000 build() { 2001 Column() { 2002 // 手势数据统计面板 2003 Row({ space: 30 }) { 2004 Column() { 2005 Text('点击次数:').fontSize(16) 2006 Text(`${this.tapCount}`).fontSize(24).fontColor('#FF6B81') 2007 } 2008 Column() { 2009 Text('平移次数:').fontSize(16) 2010 Text(`${this.panCount}`).fontSize(24).fontColor('#7BED9F') 2011 } 2012 Column() { 2013 Text('长按次数:').fontSize(16) 2014 Text(`${this.longPressCount}`).fontSize(24).fontColor('#70A1FF') 2015 } 2016 } 2017 .margin(10) 2018 2019 Text(`最后动作: ${this.lastAction} (${this.lastArea})`) 2020 .fontSize(18) 2021 .margin(10) 2022 2023 // 手势区域 2024 Row() { 2025 Text('Tap区域').fontSize(18) 2026 } 2027 .id('tap-area') 2028 .width('90%') 2029 .height(120) 2030 .margin(10) 2031 .border({ width: 2, color: '#FF6B81' }) 2032 .justifyContent(FlexAlign.Center) 2033 .gesture(TapGesture().onAction((event: GestureEvent)=>{ 2034 //具体实现内容 2035 })) 2036 2037 Row() { 2038 Text('Pan区域').fontSize(18) 2039 } 2040 .id('pan-area') 2041 .width('90%') 2042 .height(120) 2043 .margin(10) 2044 .border({ width: 2, color: '#7BED9F' }) 2045 .justifyContent(FlexAlign.Center) 2046 .gesture( 2047 PanGesture() 2048 .onActionStart((event: GestureEvent) => { 2049 //具体实现内容 2050 }) 2051 .onActionEnd((event: GestureEvent) => { 2052 //具体实现内容 2053 }) 2054 ) 2055 2056 Row() { 2057 Text('LongPress区域').fontSize(18) 2058 } 2059 .id('longpress-area') 2060 .width('90%') 2061 .height(120) 2062 .margin(10) 2063 .border({ width: 2, color: '#70A1FF' }) 2064 .justifyContent(FlexAlign.Center) 2065 .gesture( 2066 LongPressGesture() 2067 .onAction((event: GestureEvent)=>{ 2068 //具体实现内容 2069 }) 2070 .onActionEnd((event: GestureEvent) => { 2071 //具体实现内容 2072 }) 2073 ) 2074 } 2075 .width('100%') 2076 .height('100%') 2077 } 2078} 2079``` 2080 2081 2082## removeGlobalGestureListener<sup>20+</sup> 2083 2084removeGlobalGestureListener(type: GestureListenerType, callback?: GestureListenerCallback): void 2085 2086移除某一手势监听器类型的回调函数。 2087 2088**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2089 2090**系统能力：** SystemCapability.ArkUI.ArkUI.Full 2091 2092**参数：** 2093 2094| 参数名 | 类型 | 必填 | 说明 | 2095| -------- | ---------- | ---- | --------- | 2096| type | [GestureListenerType](arkts-apis-uicontext-e.md#gesturelistenertype20) | 是 | 要移除监听器的事件类型。 | 2097| callback | [GestureListenerCallback](arkts-apis-uicontext-t.md#gesturelistenercallback20) | 否 | 待移除的回调函数（未提供时将清除该手势类型的所有回调）。 | 2098 2099**示例：** 2100 2101参考[addGlobalGestureListener](#addglobalgesturelistener20)接口示例。 2102
