1# 组件可见区域变化事件 2 3组件可见区域变化事件是组件在屏幕中的显示区域面积变化时触发的事件，提供了判断组件是否完全或部分显示在屏幕中的能力，适用于广告曝光埋点之类的场景。 4 5> **说明：** 6> 7> 从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## onVisibleAreaChange 10 11onVisibleAreaChange(ratios: Array<number>, event: VisibleAreaChangeCallback): T 12 13组件可见区域变化时触发该回调。 14 15**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 16 17**系统能力：** SystemCapability.ArkUI.ArkUI.Full 18 19**参数：** 20 21| 参数名 | 类型 | 必填 | 说明 | 22| ------ | --------------------------------------------------- | ---- | ------------------------------------------------------------ | 23| ratios | Array<number> | 是 | 阈值数组。其中，每个阈值代表组件可见面积（即组件在屏幕显示区的面积，只计算父组件内的面积，超出父组件部分不会计算）与组件自身面积的比值。当组件可见面积与自身面积的比值接近阈值时，均会触发该回调。每个阈值的取值范围为[0.0, 1.0]，如果开发者设置的阈值超出该范围，则会实际取值0.0或1.0。<br/>**说明：** <br/>当数值接近边界0和1时，将会按照误差不超过0.001的规则进行舍入。例如，0.9997会被近似为1。 | 24| event | [VisibleAreaChangeCallback](ts-types.md#visibleareachangecallback12) | 是 | 组件可见区域变化事件的回调。 | 25 26**返回值：** 27 28| 类型 | 说明 | 29| -------- | -------- | 30| T | 返回当前组件。 | 31 32> **说明：** 33> 34> 35>- 仅提供自身节点相对于所有祖先节点（直到window边界）的相对裁切面积与自身面积的比值及其变化趋势。 36> 37>- 不支持兄弟组件对自身节点的遮挡计算，不支持所有祖先的兄弟节点对自身节点的遮挡计算，如[Stack](ts-container-stack.md)、[Z序控制](ts-universal-attributes-z-order.md)等。 38> 39>- 不支持非挂树节点的可见面积变化计算。例如，预加载的节点、通过[overlay](ts-universal-attributes-overlay.md#overlay)能力挂载的自定义节点。 40 41## onVisibleAreaApproximateChange<sup>17+</sup> 42 43onVisibleAreaApproximateChange(options: VisibleAreaEventOptions, event: VisibleAreaChangeCallback | undefined): void 44 45设置[onVisibleAreaChange](./ts-universal-component-visible-area-change-event.md#onvisibleareachange)事件的回调参数，限制它的执行间隔。 46 47**原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 48 49**系统能力：** SystemCapability.ArkUI.ArkUI.Full 50 51**参数：** 52 53| 参数名 | 类型 | 必填 | 说明 | 54| ------ | ------ | ---- | -------------------------- | 55| options | [VisibleAreaEventOptions](./ts-types.md#visibleareaeventoptions12) | 是 | 可见区域变化相关的参数。 | 56| event | [VisibleAreaChangeCallback](./ts-types.md#visibleareachangecallback12) \| undefined | 是 | onVisibleAreaChange事件的回调函数。当组件可见面积与自身面积的比值接近options中设置的阈值时触发该回调。 | 57 58>**说明：** 59> 60> 非实时回调，实际回调与预期间隔可能存在差别。 61> 62> 两次可见区域回调的时间间隔不小于预期更新间隔。当开发者设置的预期间隔过小时，由系统负载决定实际回调间隔时间。 63> 64> 当前接口的可见区域回调阈值默认包含0。例如，开发者设置回调阈值为[0.5]，实际生效的阈值为[0.0, 0.5]。 65 66## 示例 67 68### 示例1 (使用onVisibleAreaChange来监听区域变化) 69 70该示例对组件设置onVisibleAreaChange事件，当组件完全显示或者完全消失时触发回调。 71 72```ts 73// xxx.ets 74@Entry 75@Component 76struct ScrollExample { 77 scroller: Scroller = new Scroller() 78 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 79 @State testTextStr: string = 'test' 80 @State testRowStr: string = 'test' 81 82 build() { 83 Column() { 84 Column() { 85 Text(this.testTextStr) 86 .fontSize(20) 87 88 Text(this.testRowStr) 89 .fontSize(20) 90 } 91 .height(100) 92 .backgroundColor(Color.Gray) 93 .opacity(0.3) 94 95 Scroll(this.scroller) { 96 Column() { 97 Text("Test Text Visible Change") 98 .fontSize(20) 99 .height(200) 100 .margin({ top: 50, bottom: 20 }) 101 .backgroundColor(Color.Green) 102 // 通过设置ratios为[0.0, 1.0]，实现当组件完全显示或完全消失在屏幕中时触发回调。 103 .onVisibleAreaChange([0.0, 1.0], (isExpanding: boolean, currentRatio: number) => { 104 console.info('Test Text isExpanding: ' + isExpanding + ', currentRatio:' + currentRatio) 105 if (isExpanding && currentRatio >= 1.0) { 106 console.info('Test Text is fully visible. currentRatio:' + currentRatio) 107 this.testTextStr = 'Test Text is fully visible' 108 } 109 110 if (!isExpanding && currentRatio <= 0.0) { 111 console.info('Test Text is completely invisible.') 112 this.testTextStr = 'Test Text is completely invisible' 113 } 114 }) 115 116 Row() { 117 Text('Test Row Visible Change') 118 .fontSize(20) 119 .margin({ bottom: 20 }) 120 121 } 122 .height(200) 123 .backgroundColor(Color.Yellow) 124 .onVisibleAreaChange([0.0, 1.0], (isExpanding: boolean, currentRatio: number) => { 125 console.info('Test Row isExpanding:' + isExpanding + ', currentRatio:' + currentRatio) 126 if (isExpanding && currentRatio >= 1.0) { 127 console.info('Test Row is fully visible.') 128 this.testRowStr = 'Test Row is fully visible' 129 } 130 131 if (!isExpanding && currentRatio <= 0.0) { 132 console.info('Test Row is completely invisible.') 133 this.testRowStr = 'Test Row is completely invisible' 134 } 135 }) 136 137 ForEach(this.arr, (item:number) => { 138 Text(item.toString()) 139 .width('90%') 140 .height(150) 141 .backgroundColor(0xFFFFFF) 142 .borderRadius(15) 143 .fontSize(16) 144 .textAlign(TextAlign.Center) 145 .margin({ top: 10 }) 146 }, (item:number) => (item.toString())) 147 148 }.width('100%') 149 } 150 .backgroundColor(0x317aff) 151 .scrollable(ScrollDirection.Vertical) 152 .scrollBar(BarState.On) 153 .scrollBarColor(Color.Gray) 154 .scrollBarWidth(10) 155 .onWillScroll((xOffset: number, yOffset: number, scrollState: ScrollState) => { 156 console.info(xOffset + ' ' + yOffset) 157 }) 158 .onScrollEdge((side: Edge) => { 159 console.info('To the edge') 160 }) 161 .onScrollStop(() => { 162 console.info('Scroll Stop') 163 }) 164 165 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 166 } 167} 168``` 169 170
