模板版本：v0.4.0

本项目基于 react-native-intersection-observer 开发。

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-intersection-observer 版本所属关系如下： | 三方库名称 | 三方库版本 | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | npm地址 | | ------------ | ------------ | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- | | @react-native-ohos/react-native-intersection-observer | ~ 0.4.0 | Gitcode Releases | 0.82.* | 否 | API12+ | 0.3.1 | Npm Address | | @react-native-ohos/react-native-intersection-observer | ~ 0.3.0 | Gitcode Releases | 0.77.* | 否 | API12+ | 0.2.1 | Npm Address | | @react-native-ohos/react-native-intersection-observer | ~ 0.2.1 | Gitcode Releases | 0.72.* | 否 | API12+ | 0.2.0 | Npm Address | | @react-native-oh-tpl/react-native-intersection-observer | <=0.2.0-0.0.1@deprecated | Github Releases(deprecated) | 0.72.* | 否 | API12+ | 0.2.0 | Npm Address |

对于未发布到npm的旧版本，请参考安装指南安装tgz包。

安装与使用

进入到工程目录并输入以下命令：

npm

npm install @react-native-ohos/react-native-intersection-observer

yarn

yarn add @react-native-ohos/react-native-intersection-observer

下面的代码展示了这个库的基本使用场景：

[!WARNING] 使用时 import 的库名不变。

import React, { useRef } from "react";
import { Text } from "react-native";
import {
  IOScrollView,
  IOScrollViewController,
  InView,
} from "react-native-intersection-observer";

function App() {
  const scrollViewRef = useRef<IOScrollViewController>(null);
  return (
    <IOScrollView ref={scrollViewRef}>
      <Text
        onPress={() => {
          scrollViewRef.current?.scrollToEnd();
        }}
      >
        Scroll to bottom
      </Text>
      <InView onChange={(inView: boolean) => console.log("Inview:", inView)}>
        <Text>
          Plain children are always rendered. Use onChange to monitor state.
        </Text>
      </InView>
    </IOScrollView>
  );
}

export default App;

约束与限制

兼容性

本文档内容基于以下环境验证通过：

1. RNOH: 0.72.33; SDK：OpenHarmony 5.0.0.71(API Version 12 Release); IDE：DevEco Studio 5.0.3.900; ROM：NEXT.0.0.71;
2. RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.868; ROM: 6.0.0.112;
3. RNOH: 0.82.22; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.878; ROM: 6.0.0.130;

属性

[!TIP] "Platform"列表示该属性在原三方库上支持的平台。

[!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

详情请查看react-native-intersection-observer

IOScrollView 组件

属性: 继承自 ScrollView Props

| Name | Description | Type | Required | HarmonyOS Support | | ---------- | ------------- | ------------------------------------------------------------ | -------- | ----------------- | | rootMargin | 根元素边距 | { top: number; left: number; right: number; bottom: number } | false | yes | | threshold | 可见比例阈值，取值 0~1，表示目标元素进入/离开根容器多少比例时触发回调。默认为 0，即元素任意部分进入即视为可见 | number | false | yes |

方法：继承自 ScrollView Methods

IOFlatList 组件

属性: 继承自 FlatList Props

| Name | Description | Type | Required | HarmonyOS Support | | ---------- | ------------- | ------------------------------------------------------------ | -------- | ----------------- | | rootMargin | 根元素边距 | { top: number; left: number; right: number; bottom: number } | false | yes | | threshold | 可见比例阈值，取值 0~1，表示目标元素进入/离开根容器多少比例时触发回调。默认为 0，即元素任意部分进入即视为可见 | number | false | yes |

方法：继承自 FlatList Methods

InView 组件

| Name | Description | Type | Required | HarmonyOS Support | | ----------- | ------------------------------------------------------------ | --------------------------- | -------- | ----------------- | | as | 指定组件渲染的包装元素类型。默认为 View | ComponentType | false | yes | | children | 子元素期望一个普通子元素，由 <InView /> 处理包装元素 | ReactNode | true | yes | | triggerOnce | 仅触发此方法一次 | boolean | false | yes | | onChange | 每当可视状态发生变化时调用此函数。它将接收 inView 布尔值，以及当前的IntersectionObserverEntry | (inView: boolean) => void | false | yes | | onLayout | 当元素布局发生变化时触发 | (event: LayoutChangeEvent) => void | false | yes |

InView ref 方法

| Name | Description | Type | Required | HarmonyOS Support | | ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ----------------- | | measureInWindow | 测量元素在屏幕中的绝对位置和大小，结果通过 callback 异步返回 | (callback: (x: number, y: number, width: number, height: number) => void) => void | false | yes | | measureLayout | 测量元素相对于另一元素的位置。relativeTo 为参照节点的 ref；onSuccess 接收相对偏移；onFail 在测量失败时调用 | (relativeTo: ref, onSuccess: (x: number, y: number, width: number, height: number) => void, onFail: () => void) => void | false | yes | | setNativeProps | 直接修改原生视图属性，不经过 React 渲染流程 | (props: object) => void | false | yes | | focus | 让视图获得焦点 | () => void | false | yes | | blur | 让视图失去焦点 | () => void | false | yes |

withIO 高阶函数

| Name | Description | Type | Required | HarmonyOS Support | | ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ----------------- | | withIO | 把任意滚动组件包装为带检测能力的版本。参数 Component 为要包装的滚动组件；methodNames 为需要透传的 ref 方法名数组，返回值是一个新组件，支持 rootMargin 和 threshold prop | (Component: ComponentType, methodNames: string[]) => ComponentType | false | yes |

IOContext

| Name | Description | Type | Required | HarmonyOS Support | | ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ----------------- | | IOContext.Consumer | 获取内部 IOManager 实例用于调试。manager 为 null 表示尚未创建滚动容器；manager.observerId 为累计注册的观察实例数；manager.instanceMap 为当前正在观察的元素 Map（.size 为活跃观察数） | React Context | false | yes |

IntersectionObserver 类

| Name | Description | Type | Required | HarmonyOS Support | | --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ----------------- | | new IntersectionObserver(callback, options) | 构造函数。callback 在任意被观察元素的可见状态变化时调用，接收 IntersectionObserverEntry[]；options 包含 { root, rootMargin?, threshold? }，其中 threshold 为可见比例阈值（0~1），内部会裁剪到 [0,1] 范围 | (callback: (entries: IntersectionObserverEntry[]) => void, options: { root: object; rootMargin?: RootMargin; threshold?: number }) => IntersectionObserver | false | yes | | observe(element) | 注册目标元素，将其加入观察列表。重复注册同一元素不会重复添加 | (element: Element) => void | false | yes | | unobserve(element) | 取消观察目标元素，将其从观察列表中移除 | (element: Element) => void | false | yes |

defaultRootMargin

[!NOTE] 该常量未从包根导出，需从内部路径导入：import { defaultRootMargin } from 'react-native-intersection-observer/lib/commonjs/IntersectionObserver'

| Name | Description | Type | Required | HarmonyOS Support | | ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ----------------- | | defaultRootMargin | 默认的 rootMargin 常量，值为 { top: 0, right: 0, bottom: 0, left: 0 }，表示不扩展判断区域。可用于显式传入默认值或作为模板构造自定义值 | RootMargin | false | yes |

defaultThreshold

[!NOTE] 该常量未从包根导出，需从内部路径导入：import { defaultThreshold } from 'react-native-intersection-observer/lib/commonjs/IntersectionObserver'

| Name | Description | Type | Required | HarmonyOS Support | | ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ----------------- | | defaultThreshold | 默认的 threshold 常量，值为 0，表示目标元素任意部分进入根容器即视为可见。可显式传入以重置阈值行为 | number | false | yes |

遗留问题

其他

开源协议

本项目基于 MIT License ，请自由地享受和参与开源。