React Native for OpenHarmony 实战：三方库 react-native-parallax-scroll-view 的鸿蒙化适配指南

本文记录把 react-native-parallax-scroll-view 适配到 HarmonyOS 的完整过程。

这个库功能很明确：一个带视差头部的 ScrollView ------向上滚时，头部背景以更慢的速度 上移（视差），前景慢慢淡出，滚过某个阈值后 sticky header 淡入。它是纯 JS 的 class 组件，但有一个运行时依赖 prop-types。

它带来两个值得写下来的问题：

交付包悄悄改了 2 行实现 ------ 而这 2 行是必需的 （不改，库在 RN 0.84.1 上连 import 都会崩 ），可惜零披露，而且替换手法偷懒；
它的视差是"原生驱动"的 （useNativeDriver: true），所以布局 dump 完全读不到效果 ⇒ 必须先解决"用什么当判据"，才能验证。

第 2 条最后拿到了一组很干净的定量结果：三个数据点全部命中（偏差 ≤2px）。

一、先说结论

项	结果
上游最新版	`0.21.3`；`license: ISC`；`gitHead` = `5c3c92f6e32b5e7f0bacd60ea9da198d2ab3cf13`
库类型	纯 JS class 组件（`ParallaxScrollView`），滚动驱动的视差 + sticky header
是否需要原生适配	不需要（无 `harmony/`、无 `NativeModules`）
运行时依赖	⚠️ 有：`prop-types@^15.6.0` ⇒ 用 `file:` 接入时它自己不会被装上，必须显式补装
`prepare` / `prepack`	都没有 ✓ 安装路径干净
`main`	`src/index.js`（源码，不是编译产物）⇒ 不存在"陈旧产物"风险
导出形态	CommonJS （`module.exports = ParallaxScrollView`）⇒ `require()` 直接拿到类
与 npm 上游的差异	2 个文件不同：`src/index.js`（改了 2 行实现）与 `package.json`
★ 那个改动	必需（`ViewPropTypes` 已被 RN 移除）但零披露，且用"恒通过"的校验器替代 ⇒ 见第三节
设备侧断言	39 / 39 通过
★ 定量验证	视差位移在 3 个数据点上全部命中（偏差 ≤2px），含越界延伸（`extrapolateRight:'extend'`）
★ 一个单位陷阱	`onScroll` 的 `contentOffset.y` 是 vp（不是物理像素）------ 我因此先算错过一次

二、判定过程：纯 JS，但有依赖

步	做法	结果
①	`package.json` 里有没有 `harmony.autolinking`	没有
②	仓库里有没有 `harmony/`	没有
③	代码里有没有 `NativeModules` / `requireNativeComponent`	全无

但 dependencies 不是空的：

json 复制代码

"dependencies": { "prop-types": "^15.6.0" }

这一点很关键：用 file:（软链）方式接入时，库自己的 dependencies 不会被安装 。表现是运行到 import { bool, func, number, string } from 'prop-types' 时 Metro 直接报解析失败。

做法：先看 dependencies，不为空就显式补装：

bash 复制代码

npm view react-native-parallax-scroll-view dependencies   # 先看一眼
npm install prop-types --ignore-scripts                    # 再补到宿主

本轮的宿主恰好已经有 prop-types（是先前为别的库补装时留下的），所以这次没被卡住。但换一个干净宿主就会直接崩 ------ 这条要当成固定检查项。

三、交付包改了 2 行实现：必需、但零披露

3.1 差异

把交付包的 src/index.js 与 npm 上游逐行比对 ，只有 2 行不同：

diff 复制代码

- import { Animated, Dimensions, View, ViewPropTypes } from 'react-native'
+ import { Animated, Dimensions, View } from 'react-native'

- 	contentContainerStyle: ViewPropTypes.style,
+ 	contentContainerStyle: () => null,

其余 440 行完全一致。（package.json 另有常规改动：description / repository / homepage / test，并删除了上游的 files 白名单。）

3.2 这个改动是必需的------三条实测证据

核查	方法	结果
① RN 0.84.1 里还有没有 `ViewPropTypes`	在 `node_modules/react-native` 全库（JS 源码与 `index.d.ts`）里搜	一处都没有 ⇒ 已被移除
② 上游原句会发生什么	在 Node 上直接求值 `undefined.style`	`TypeError: Cannot read properties of undefined (reading 'style')` ⇒ 模块加载阶段就崩
③ 交付包替换后的副作用	用 `prop-types` 实际调用那个自定义校验器	返回值 `null` ⇒ 恒通过 ⇒ 这条类型校验被静默关掉

⇒ 不改这一行，这个库在 RN 0.84.1 上连 require 都会抛错。 所以交付包做了一件必须做的事。

3.3 问题在哪

零披露。 两个 README.OpenHarmony* 与 CHANGELOG.md 都没有提到改过实现 （搜"修改/改动/修复/差异"零命中）。⇒ 读者会以为拿到的是原版实现，一旦上游升级、自己 merge，就会莫名其妙地重新崩掉。
替换手法偷懒。 () => null 是一个恒通过 的自定义校验器，等于把这条类型校验删掉 。更合适的写法是给一个真实的校验（比如 PropTypes.oneOfType([PropTypes.object, PropTypes.array, PropTypes.number])）------contentContainerStyle 本来就允许传数组。

结论一句话 ：必需 ≠ 可以不说；能跑 ≠ 改得对。

3.4 其它交付包情况

spec.json：无 upstreamCommit ，而 npm 明确有 gitHead （5c3c92f6...）⇒ 属应修项 ；validation 仍是裸字符串 "pass"；
契约测试仍是包级 smoke test（包名 / 版本 / 主入口 / 中文 README），一次组件都没渲染过。

四、接入方式

4.1 装包（记得补依赖）

bash 复制代码

# 从适配仓库安装
npm install "git+https://atomgit.com/oh-react-native/react-native-parallax-scroll-view.git#0.21.3-ohos-1.0.0" --ignore-scripts

# ⚠️ 它自己带一个运行时依赖，file: / 软链方式不会自动装
npm install prop-types --ignore-scripts

4.2 `watchFolders`

file: 装进来的是软链，Metro 需要知道库的真实目录：

js 复制代码

// metro.config.js
watchFolders: [
  path.resolve(__dirname, '../react-native-parallax-scroll-view'),
],

4.3 注册测试页

js 复制代码

import ParallaxTestApp from './ParallaxTestApp';
AppRegistry.registerComponent('ParallaxTestApp', () => ParallaxTestApp);

bash 复制代码

hdc shell aa force-stop com.rnoh084.demo
hdc shell aa start -b com.rnoh084.demo -a EntryAbility --ps rnAppKey ParallaxTestApp

不需要 HAR、权限、ohpm、link-harmony。

五、视差是怎么算的（源码真值）

先读源码，把可精确预言的量找出来，再谈验证。

js 复制代码

const pivotPoint = (a, b) => a - b
p = parallaxHeaderHeight − stickyHeaderHeight            // 视差头高 − sticky 头高

// ① 背景：绝对定位在 ScrollView **之外**，只靠 translateY 移动
translateY: interpolate(scrollY, {
  inputRange: [0, p],
  outputRange: [0, -(p / backgroundScrollSpeed)],        // backgroundScrollSpeed 默认 5
  extrapolateRight: 'extend', extrapolateLeft: 'clamp'
})
// ② 背景下拉放大
scale: interpolate(scrollY, {inputRange: [-viewHeight, 0], outputRange: [outputScaleValue * 1.5, 1]})

// ③ 前景淡出（默认开启）
opacity: interpolate(scrollY, {inputRange: [0, p/2, p*3/4, p], outputRange: [1, 0.3, 0.1, 0]})

// ④ sticky header 淡入 + 上移
opacity:    [0 → 1] over [0, p]
translateY: [stickyHeaderHeight → 0] over [0, p]

// ⑤ 回调阈值
_onScroll(e) { e.nativeEvent.contentOffset.y >= p ? onChangeHeaderVisibility(false) : onChangeHeaderVisibility(true) }

关键默认值 （源码 defaultProps，实测值）：

字段	默认值
`backgroundScrollSpeed`	5
`outputScaleValue`	5
`fadeOutForeground`	`true` （⇒ 前景滚到 `p` 会完全透明）
`stickyHeaderHeight`	0
`backgroundColor` / `contentBackgroundColor`	`'#000'` / `'#fff'`
`renderForeground` / `contentContainerStyle`	`null`

propTypes 共 16 个键 ，唯一必填的是 parallaxHeaderHeight。

测试页取 ：parallaxHeaderHeight = 240vp、stickyHeaderHeight = 60vp ⇒ p = 180vp

六、验证设计：先解决"用什么当判据"

6.1 为什么布局 dump 不管用

js 复制代码

onScroll: Animated.event([{nativeEvent: {contentOffset: {y: this.scrollY}}}], {
  useNativeDriver: true, listener: this._onScroll.bind(this)
})

useNativeDriver: true ⇒ 动画值在原生侧更新：

JS 侧的 Animated.Value 不反映滚动值；
而 transform 本来就不被布局 dump 反映（dump 给的是 Yoga 布局帧）。

⇒ 布局 dump 读不到视差 ，只能走像素。

6.2 判据设计：让"红色背景的下边界"变成标尺

设计	作用
`backgroundColor = '#ff0000'`	背景 `Animated.View` 是一块红色色块，只受 `translateY` 影响
内容区 `contentBackgroundColor = 'transparent'`	不让内容盖住背景
判据：红色区域的"下边界 Y"	背景色块高 `parallaxHeaderHeight`(240vp=720px)，贴顶 ⇒ 它的下边界就是视差位移的直接读数

基线预言 ：scrollY = 0 时，红色下边界应在 720px。

⚠️ 我原本想用"红蓝交界"（在根节点传 style={``{backgroundColor:'#0000ff'}}），实测失败了 ------ 因为源码里是

style={[style, styles.container]}，而 styles.container 在后 ，它的 backgroundColor:'transparent' 覆盖了我传的蓝色 。

⇒ 改用"红色下边界"这一个判据就够了（它本身就等于背景色块的底边）。

6.3 驱动方式：拖动 + 回读真实偏移

我最初把四个"精确滚动"按钮放在 renderFixedHeader 里，结果它们不可见：

源码里 sticky 容器是 position:'absolute' + overflow:'hidden'，高度 = stickyHeaderHeight(60vp)，而 renderFixedHeader() 排在那个 60vp 高的 sticky 视图之后 ⇒ 一渲染就被裁掉。

规避：改用手指拖动 + 回读真实 contentOffset.y 。只要模型对了，任意偏移量都能算出期望值，反而比"必须精确停在某个值"更稳。

七、实测：三个数据点全部命中（含一次单位纠错）

7.1 我先把单位算错了

第一组数据：实测 contentOffset.y = 220.73，红色下边界 587。

我按"contentOffset.y 是物理像素"去算：

复制代码

p = 540px（180vp × 3）
translateY = −(108px) × (220.73/540) = −44.15px
预期红边 = 720 − 44.15 = 675.85          ← 与实测 587 差了 89px ✗

真相：onScroll 的 contentOffset.y 是 vp，不是物理像素 ；而 p 也是 vp。

所以 scrollY = 220.73 时它已经超过 p = 180 ，走的是 extrapolateRight: 'extend'（线性外推），而我却按"在 0...p 区间内"算的。

修正模型：

复制代码

translateY_vp = −(p / backgroundScrollSpeed) × (scrollY_vp / p) = −0.2 × scrollY_vp
translateY_px = −0.6 × scrollY_vp
红色下边界(px) = 720 − 0.6 × scrollY_vp

7.2 三个数据点

`contentOffset.y`（vp，实测）	预言 `720 − 0.6y`	实测红边（x=100 与 x=1250 两点一致）	偏差
0	720	719	1px
220.73	587.6	587	0.6px
538.29 （越过 `p=180`，走 `extend`）	397.0	395	2px

⇒ 三个点全部命中 （偏差 ≤2px，属 JPEG 取整误差）；第三个点还验证了越界延伸也是线性的。

7.3 其它实测

观测	结果
`props.onScroll` 透传有效	✅ 实测触发 73 次，页面能读到真实 `contentOffset.y`（源码在 `listener` 里会调 `this.props.onScroll(e)`）
`onChangeHeaderVisibility` 阈值	✅ 记录形如 `headerVisible=false @y=179`、`headerVisible=true @y=0` ⇒ 与 `offsetY >= p ⇒ false` 一致
内容区起点	✅ `MARK-BODY-START` 实测 y = 720 = `240vp × 3` ⇒ "内容从头部下方开始"这个布局契约成立
`scrollTo(...)`	✅ ref 上确有 `function`（本轮改用拖动驱动，原因见 6.3）

八、附加：本轮踩到的一个宿主级构建问题（与本库无关）

这一轮适配时，assembleHap 连续三次失败（每次约 45 秒）：

复制代码

> hvigor ERROR: Failed :entry:default@BuildNativeWithNinja...
> hvigor ERROR: Error Code: 00308018 Unknown Error

hvigor 只说"Unknown Error"并让你去看 .hvigor > outputs > build-logs ------ 但真正的错误不在这里。 它其实在：

复制代码

harmony/entry/.cxx/<cfg>/<abi>/output.log        ← ninja 的原始输出

原文是：

复制代码

[1/18] Linking CXX shared library ...\obj\arm64-v8a\libjsi.so
FAILED: [code=1] .../libjsi.so
C:\windows\system32\cmd.exe /C "cd . && clang++.exe --target=aarch64-linux-ohos ...
命令行太长。

⇒ 链接 libjsi.so 的命令行超过了 Windows cmd.exe 的长度上限（约 32767 字符）。

为什么会突然撞上（三条证据）：

这个隐患一直在 ：前一次"成功"的构建日志里 libjsi / Linking CXX 命中数为 0 ⇒ 那次原生是 up-to-date ，根本没走到链接；
触发点是 CMake 重新 configure ：autolinking.cmake 每次构建都会被重新生成，带动 CMake 重新配置，重新生成 build.ninja 后 ninja 决定重链 libjsi.so；
与本次新加的库无关 ：autolinking.cmake 里的原生库清单没变（一直是那 10 个），而新加的库是纯 JS。

修法（已生效） ：在 harmony/entry/build-profile.json5 的 externalNativeOptions.arguments（官方留的参数入口，原本是空串）填三行 CMake 标准变量：

json5 复制代码

"externalNativeOptions": {
  "path": "./src/main/cpp/CMakeLists.txt",
  "arguments": "-DCMAKE_CXX_USE_RESPONSE_FILE_FOR_OBJECTS=ON -DCMAKE_CXX_USE_RESPONSE_FILE_FOR_LIBRARIES=ON -DCMAKE_CXX_USE_RESPONSE_FILE_FOR_INCLUDES=ON",
  "abiFilters": ["arm64-v8a", "x86_64"]
}

让 CMake 把目标文件 / 库列表 / 头文件路径 写进 .rsp 响应文件 ⇒ 命令行变短。

实测结果 ：BUILD SUCCESSFUL in 4 min 15 s，output.log 里 18 个原生任务全部完成 （含之前失败的各个 Linking CXX shared library）✓

给在 Windows 上做 RNOH 的人两条经验 ：

① hvigor 报 Unknown Error 时，去 .cxx/<abi>/output.log 找真因 ；

② 连续几轮只改 JS 时，"构建成功"可能只是原生被跳过了 ------ 建议隔一段时间主动确认一次"原生真的能重链"。

九、已知限制与本次验证边界

9.1 用这个库要知道的

事项	说明
装包要补依赖	`dependencies` 里有 `prop-types`，`file:` / 软链接入不会自动装
`fadeOutForeground` 默认 `true`	前景滚到 `p` 时完全透明；想保留内容要显式关掉
`scrollY` 单位是 vp	自算插值期望值时别当像素（见第七节）
`renderFixedHeader` 会被裁	sticky 容器 `overflow:'hidden'` 且高度 = `stickyHeaderHeight` ⇒ 超出部分看不见
`renderStickyHeader` 必须配 `stickyHeaderHeight`	否则构造函数会 `console.warn`
`renderParallaxHeader` 已废弃	用它且不传 `renderForeground` 会告警
导出是 CommonJS	`require()` 直接拿到类，没有 `.default`

9.2 本次验证的边界

只在一台模拟器上验证 （Pura X View，density 3，1320×2232），没有真机。
只验证了"向上滚动"方向的视差 ；下拉放大 （scale，需要 overscroll，inputRange: [-viewHeight, 0]）未测。
前景淡出与 sticky 淡入没有做像素定量 ：断言只覆盖了回调与几何；fadeOutForeground / renderStickyHeader 的透明度曲线未逐点核对。
scrollTo() 未实际调用 （本轮用拖动驱动；只确认了它是 function）。
renderFixedHeader 的正常用法未测（本轮只发现"放在默认 sticky 容器里会被裁"这一个现象）。
renderScrollComponent 自定义未测 ；contentContainerStyle、fadeOutBackground、backgroundColor / contentBackgroundColor 的组合效果未测。
多个元素/长内容的滚动性能与边界（滚动到底、footer spacer 自动高度）未测。
没有跨平台对照（未在 iOS/Android 上跑同一套用例）。

未改动库代码。

十、常见问题

Q1：装完跑起来报 Unable to resolve module prop-types，怎么办？

因为库自带一个运行时依赖 ，而用 file: / 软链方式接入时，库自己的 dependencies 不会被安装。补装即可：

bash 复制代码

npm install prop-types --ignore-scripts

建议每次接新库都先跑一遍 npm view <包名> dependencies。

Q2：为什么我传了 style={``{backgroundColor: ...}} 却不生效？

因为源码里是 style={[style, styles.container]} ------ styles.container 在后面 ，它自带的 backgroundColor: 'transparent' 会覆盖你传的同名属性 。要改底色请用 backgroundColor / contentBackgroundColor 这两个 prop。

Q3：parallaxHeaderHeight 和 p 是什么关系？

js 复制代码

p = parallaxHeaderHeight − stickyHeaderHeight

p 是"视差完整走完"的滚动距离，也是所有插值曲线的关键节点（背景位移、前景淡出、sticky 淡入、onChangeHeaderVisibility 的阈值都用它）。

Q4：视差位移具体是多少？

背景的 translateY 是：

复制代码

outputRange: [0, -(p / backgroundScrollSpeed)]

backgroundScrollSpeed 默认 5 ⇒ 滚完 p 的距离，背景只上移 p/5（这就是视差的来源：背景比内容慢 5 倍 ）。超过 p 之后按 extrapolateRight: 'extend' 线性继续。

Q5：为什么我用布局 dump 看不到任何变化？

因为 Animated.event(..., { useNativeDriver: true }) ⇒ 动画由原生驱动 ，JS 侧的 Animated.Value 不反映滚动值；而 transform 本来就不体现在 Yoga 布局帧里。⇒ 要验证这类效果必须用像素 （或用 onScroll / onChangeHeaderVisibility 这类回调当观测通道）。

Q6：onScroll 里拿到的 contentOffset.y 是像素还是 vp？

vp。 我一开始当像素算，结果期望值与实测差了 89px（因为 p 也是 vp，算出来会误判成"还在 0...p 区间内"，实际早已越过、走的是线性外推）。⇒ 自己算插值期望值时要统一单位。

Q7：我把按钮放在 renderFixedHeader 里，为什么看不见？

sticky 容器是 position:'absolute' + overflow:'hidden'，高度等于 stickyHeaderHeight，而 renderFixedHeader() 排在那个高度受限的 sticky 视图之后 ⇒ 超出部分被裁掉。⇒ 固定头部只能在 stickyHeaderHeight 这个高度内放内容。

Q8：renderStickyHeader 没效果？

它必须同时传 stickyHeaderHeight ，否则构造函数会 console.warn('Property \stickyHeaderHeight` must be set if `renderStickyHeader` is used.')`，而且高度为 0 时也看不见。

Q9：import ParallaxScrollView from '...' 和 require 有区别吗？

这个库是 module.exports = ParallaxScrollView（CommonJS），所以 require('react-native-parallax-scroll-view') 直接拿到类本身 （没有 .default）。用 ESM 的 import X from '...' 也能拿到（Metro 会做 interop），但如果你在断言里检查 .default，会得到 undefined。

Q10：它支持哪些回调？

onScroll（透传，页内可用来观测真实偏移）、onChangeHeaderVisibility(bool)（滚过 p 时为 false）、onLayout、scrollEvent 等。注意 onScroll 是"包在内部 Animated.event 的 listener 里被调用"，所以传它不会破坏原生驱动。

小结

react-native-parallax-scroll-view 是一个纯 JS 的 class 组件：propTypes 16 键、defaultProps 13 键、CommonJS 导出 ，main 直接指向源码。设备侧 39 / 39 断言通过，并且视差位移在三个数据点上定量成立（偏差 ≤2px），包括越界后的线性外推。

值得记下来的是这几条：

交付包改了实现就必须披露；必需 ≠ 可以不说。 这次交付包把 ViewPropTypes.style 换成了 () => null ------ 改动本身是必需的 （RN 0.84.1 已移除 ViewPropTypes，不改则连 import 都崩 ，已用 Node 实测复现 TypeError），但两个 README 与 CHANGELOG 零披露 ，而且替换成的校验器恒通过 、等于悄悄删掉了那条类型校验。⇒ 逐文件 diff 一定要包含源码，别只比 package.json。
先确认"用什么当判据"，再谈验证。 这个库的 useNativeDriver: true 让布局 dump 彻底失效。⇒ 先做正对照/找可观测通道（这里是"红色背景的下边界"），否则会把"生效了"写成"没生效"。
单位必须统一。 onScroll 的 contentOffset.y 是 vp ，我按像素算时期望值差了 89px，还差点误判成"库算错了"。⇒ 算插值期望值前先把单位对齐（输出范围也是 vp）。
"构建成功"可能只是原生被跳过了。 前几轮一直是纯 JS 库，构建都"成功"，其实原生一步都没跑 ；这次 CMake 重新 configure 触发重链，才暴露出链接命令行超过 Windows 上限 这个潜伏问题。⇒ 连续只改 JS 时，要隔一段时间主动验证"原生真的能重链" ；遇到 hvigor 报 Unknown Error，去 .cxx/<abi>/output.log 找真因。
依赖非空的库要显式补装。 这个库带 prop-types，而软链接入不会装它自己的依赖 ------ 这条已经踩过不止一次，应该固化成开场检查。

本篇用到的库

项	内容
三方库	`react-native-parallax-scroll-view`（上游 `0.21.3` 的鸿蒙适配版）
适配仓库	https://atomgit.com/oh-react-native/react-native-parallax-scroll-view
适配 TAG	`0.21.3-ohos-1.0.0`
需要 HAR / 权限 / ohpm	都不需要（纯 JS）
库类型	纯 JS class 组件：带视差头部与 sticky header 的 ScrollView
运行时依赖	⚠️ `prop-types@^15.6.0` ⇒ `file:` / 软链接入必须显式补装
许可证	ISC
上游仓库	`https://github.com/jaysoo/react-native-parallax-scroll-view`
上游基线	npm `gitHead` = `5c3c92f6e32b5e7f0bacd60ea9da198d2ab3cf13`
宿主工程	`RNOH084Demo`（测试页 `rnAppKey = ParallaxTestApp`）

bash 复制代码

# 装库（注意 --ignore-scripts 是本系列惯例）
npm install "git+https://atomgit.com/oh-react-native/react-native-parallax-scroll-view.git#0.21.3-ohos-1.0.0" --ignore-scripts

# ⚠️ 补装它自带的运行时依赖（软链接入不会自动装）
npm install prop-types --ignore-scripts

js 复制代码

// metro.config.js
watchFolders: [ path.resolve(__dirname, '../react-native-parallax-scroll-view') ],

tsx 复制代码

import ParallaxScrollView from 'react-native-parallax-scroll-view';

<ParallaxScrollView
  parallaxHeaderHeight={240}
  stickyHeaderHeight={60}
  backgroundColor="#ff0000"
  contentBackgroundColor="#fff"
  fadeOutForeground={false}          // 默认 true ⇒ 滚到头时前景会完全透明
  renderBackground={() => <View style={{flex: 1}} />}
  renderForeground={() => (
    <View style={{flex: 1, alignItems: 'center', justifyContent: 'center'}}>
      <Text>头部前景</Text>
    </View>
  )}
  renderStickyHeader={() => <Text>吸顶标题</Text>}
  onScroll={(e) => console.log(e.nativeEvent.contentOffset.y)}   // 单位是 vp
  onChangeHeaderVisibility={(v) => console.log('headerVisible', v)}
>
  {/* 可滚动内容 */}
</ParallaxScrollView>;

bash 复制代码

# 换页启动测试页（force-stop 不能省，换页参数只在冷启动生效）
hdc shell aa force-stop com.rnoh084.demo
hdc shell aa start -b com.rnoh084.demo -a EntryAbility --ps rnAppKey ParallaxTestApp

验证环境

项	版本
React Native	`0.84.1`
React	`19.2.3`
RNOH（npm / ohpm）	`@react-native-oh/react-native-harmony` / `@rnoh/react-native-openharmony` `0.84.3`
Node.js / npm	`v24.14.0` / `11.9.0`
DevEco Studio	`26.0.0.621`
HarmonyOS SDK	API 26（`26.0.0.32`）
设备	HarmonyOS 7.0.0(26.0.0) Beta2 模拟器 `Pura X View`（ohos-x64），1320×2232，density 3
宿主 HAP 产物	`entry-default-signed.hap`
本次构建	`assembleHap` 4 分 15 秒（含 18 个原生任务的重新链接）
验证规模	设备侧 39 / 39 断言；像素判据 3 个滚动位置（红边 719 / 587 / 395）+ 基线几何 1 处（内容起点 720）；上游 442 行逐行比对

欢迎加入 CPF-RN 鸿蒙社区：https://atomgit.com/CPF-RN

React Native for OpenHarmony 组织：https://atomgit.com/oh-react-native

RN 三方库鸿蒙适配清单：https://atomgit.com/oh-react-native/rn-ohos-adaptation-overview

React Native for OpenHarmony 实战：三方库 react-native-parallax-scroll-view 的鸿蒙化适配指南

一、先说结论

二、判定过程：纯 JS，但有依赖

三、交付包改了 2 行实现：必需、但零披露

3.1 差异

3.2 这个改动是必需的------三条实测证据

3.3 问题在哪

3.4 其它交付包情况

四、接入方式

4.1 装包（记得补依赖）

4.2 watchFolders

4.3 注册测试页

五、视差是怎么算的（源码真值）

六、验证设计：先解决"用什么当判据"

6.1 为什么布局 dump 不管用

6.2 判据设计：让"红色背景的下边界"变成标尺

6.3 驱动方式：拖动 + 回读真实偏移

七、实测：三个数据点全部命中（含一次单位纠错）

7.1 我先把单位算错了

7.2 三个数据点

7.3 其它实测

八、附加：本轮踩到的一个宿主级构建问题（与本库无关）

九、已知限制与本次验证边界

9.1 用这个库要知道的

9.2 本次验证的边界

十、常见问题

小结

本篇用到的库

验证环境

4.2 `watchFolders`