diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_visible_area_change.gif b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_visible_area_change.gif new file mode 100644 index 0000000000000000000000000000000000000000..3b82bc987ff6d8bbe42f00e73148b35c445fa8c8 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/zh-cn_visible_area_change.gif differ diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-component-visible-area-change-event.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-component-visible-area-change-event.md new file mode 100644 index 0000000000000000000000000000000000000000..ab6dbb0ceb179b1752c1d7cc0be4ba573aa2295f --- /dev/null +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-component-visible-area-change-event.md @@ -0,0 +1,119 @@ +# 组件可见区域变化事件 + +组件可见区域变化事件指组件在屏幕中显示的面积变化,提供了判断组件是否完全或部分显示在屏幕中的能力,通常适用于像广告曝光埋点之类的场景。 + +> **说明:**从API Version 9开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。 + +## 权限列表 + +无 + + +## 事件 + +| 名称 | 功能描述 | +| -------- | -------- | +| onVisibleAreaChange(ratios: Array, event: (isVisible: boolean, currentRatio: number) => void) | 组件可见区域变化时触发该回调。
-ratios:阈值数组。其中,每个阈值代表组件可见面积(即组件在屏幕显示区的面积)与组件自身面积的比值。当组件可见面积与自身面积的比值大于或小于阈值时,均会触发该回调。每个阈值的取值范围为[0.0, 1.0],如果开发者设置的阈值超出该范围,则会实际取值0.0或1.0.
-isVisible:表示组件的可见面积与自身面积的比值是否大于阈值,true表示大于,false表示小于。
-currentRatio:触发回调时,组件可见面积与自身面积的比值。 | + + +## 示例 + +```ts +// xxx.ets +@Entry +@Component +struct ScrollExample { + scroller: Scroller = new Scroller() + private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + @State testTextStr: string = "test" + @State testRowStr: string = "test" + + build() { + Column() { + Column() { + Text(this.testTextStr) + .fontSize(20) + + Text(this.testRowStr) + .fontSize(20) + } + .height(100) + .backgroundColor(Color.Gray) + .opacity(0.3) + + Scroll(this.scroller) { + Column() { + Text("Test Text Visible Change") + .fontSize(20) + .height(200) + .margin({ top: 50, bottom: 20 }) + .backgroundColor(Color.Green) + // 通过设置ratios为[0.0, 1.0],实现当组件完全显示或完全消失在屏幕中时触发回调 + .onVisibleAreaChange([0.0, 1.0], (isVisible: boolean, currentRatio: number) => { + console.info("Test Text isVisible: " + isVisible + ", currentRatio:" + currentRatio) + if (isVisible && currentRatio >= 1.0) { + console.info("Test Text is fully visible. currentRatio:" + currentRatio) + this.testTextStr = "Test Text is fully visible" + } + + if (!isVisible && currentRatio <= 0.0) { + console.info("Test Text is completely invisible.") + this.testTextStr = "Test Text is completely invisible" + } + }) + + Row() { + Text("Test Row Visible Change") + .fontSize(20) + .margin({ bottom: 20 }) + + } + .height(200) + .backgroundColor(Color.Yellow) + .onVisibleAreaChange([0.0, 1.0], (isVisible: boolean, currentRatio: number) => { + console.info("Test Row isVisible:" + isVisible + ", currentRatio:" + currentRatio) + if (isVisible && currentRatio >= 1.0) { + console.info("Test Row is fully visible.") + this.testRowStr = "Test Row is fully visible" + } + + if (!isVisible && currentRatio <= 0.0) { + console.info("Test Row is is completely invisible.") + this.testRowStr = "Test Row is is completely invisible" + } + }) + + ForEach(this.arr, (item) => { + Text(item.toString()) + .width('90%') + .height(150) + .backgroundColor(0xFFFFFF) + .borderRadius(15) + .fontSize(16) + .textAlign(TextAlign.Center) + .margin({ top: 10 }) + }, item => item) + + }.width('100%') + } + .backgroundColor(0x317aff) + .scrollable(ScrollDirection.Vertical) + .scrollBar(BarState.On) + .scrollBarColor(Color.Gray) + .scrollBarWidth(30) + .onScroll((xOffset: number, yOffset: number) => { + console.info(xOffset + ' ' + yOffset) + }) + .onScrollEdge((side: Edge) => { + console.info('To the edge') + }) + .onScrollEnd(() => { + console.info('Scroll Stop') + }) + + }.width('100%').height('100%').backgroundColor(0xDCDCDC) + } +} +``` + +![zh-cn_visible_area_change.gif](figures/zh-cn_visible_area_change.gif)