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&lt;number&gt;                                 | 是   | 阈值数组。其中，每个阈值代表组件可见面积（即组件在屏幕显示区的面积，只计算父组件内的面积，超出父组件部分不会计算）与组件自身面积的比值。当组件可见面积与自身面积的比值接近阈值时，均会触发该回调。每个阈值的取值范围为[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
42## 示例
43
44该示例对组件设置onVisibleAreaChange事件，当组件完全显示或者完全消失时触发回调。
45
46```ts
47// xxx.ets
48@Entry
49@Component
50struct ScrollExample {
51  scroller: Scroller = new Scroller()
52  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
53  @State testTextStr: string = 'test'
54  @State testRowStr: string = 'test'
55
56  build() {
57    Column() {
58      Column() {
59        Text(this.testTextStr)
60          .fontSize(20)
61
62        Text(this.testRowStr)
63          .fontSize(20)
64      }
65      .height(100)
66      .backgroundColor(Color.Gray)
67      .opacity(0.3)
68
69      Scroll(this.scroller) {
70        Column() {
71          Text("Test Text Visible Change")
72            .fontSize(20)
73            .height(200)
74            .margin({ top: 50, bottom: 20 })
75            .backgroundColor(Color.Green)
76              // 通过设置ratios为[0.0, 1.0]，实现当组件完全显示或完全消失在屏幕中时触发回调
77            .onVisibleAreaChange([0.0, 1.0], (isExpanding: boolean, currentRatio: number) => {
78              console.info('Test Text isExpanding: ' + isExpanding + ', currentRatio:' + currentRatio)
79              if (isExpanding && currentRatio >= 1.0) {
80                console.info('Test Text is fully visible. currentRatio:' + currentRatio)
81                this.testTextStr = 'Test Text is fully visible'
82              }
83
84              if (!isExpanding && currentRatio <= 0.0) {
85                console.info('Test Text is completely invisible.')
86                this.testTextStr = 'Test Text is completely invisible'
87              }
88            })
89
90          Row() {
91            Text('Test Row Visible  Change')
92              .fontSize(20)
93              .margin({ bottom: 20 })
94
95          }
96          .height(200)
97          .backgroundColor(Color.Yellow)
98          .onVisibleAreaChange([0.0, 1.0], (isExpanding: boolean, currentRatio: number) => {
99            console.info('Test Row isExpanding:' + isExpanding + ', currentRatio:' + currentRatio)
100            if (isExpanding && currentRatio >= 1.0) {
101              console.info('Test Row is fully visible.')
102              this.testRowStr = 'Test Row is fully visible'
103            }
104
105            if (!isExpanding && currentRatio <= 0.0) {
106              console.info('Test Row is completely invisible.')
107              this.testRowStr = 'Test Row is completely invisible'
108            }
109          })
110
111          ForEach(this.arr, (item:number) => {
112            Text(item.toString())
113              .width('90%')
114              .height(150)
115              .backgroundColor(0xFFFFFF)
116              .borderRadius(15)
117              .fontSize(16)
118              .textAlign(TextAlign.Center)
119              .margin({ top: 10 })
120          }, (item:number) => (item.toString()))
121
122        }.width('100%')
123      }
124      .backgroundColor(0x317aff)
125      .scrollable(ScrollDirection.Vertical)
126      .scrollBar(BarState.On)
127      .scrollBarColor(Color.Gray)
128      .scrollBarWidth(10)
129      .onWillScroll((xOffset: number, yOffset: number, scrollState: ScrollState) => {
130        console.info(xOffset + ' ' + yOffset)
131      })
132      .onScrollEdge((side: Edge) => {
133        console.info('To the edge')
134      })
135      .onScrollStop(() => {
136        console.info('Scroll Stop')
137      })
138
139    }.width('100%').height('100%').backgroundColor(0xDCDCDC)
140  }
141}
142```
143
144![zh-cn_visible_area_change.gif](figures/zh-cn_visible_area_change.gif)
145