{"_id":"@bingtang-rn/react-native-big-list","_rev":"2-7d789e7b237d090842b8120056dd15f9","name":"@bingtang-rn/react-native-big-list","dist-tags":{"latest":"1.6.5"},"versions":{"1.6.4":{"name":"@bingtang-rn/react-native-big-list","version":"1.6.4","keywords":["react-native","react-native-big-list","harmony","harmonyos"],"license":"Apache-2.0","_id":"@bingtang-rn/react-native-big-list@1.6.4","maintainers":[{"name":"luyizouyuan","email":"189605613@qq.com"}],"homepage":"https://gitcode.com/rn_ohos_plugin/react_native_big_list","dist":{"shasum":"71f4d5115d2eafdf8e56fb1a47600bf75f8539fa","tarball":"https://registry.npmjs.org/@bingtang-rn/react-native-big-list/-/react-native-big-list-1.6.4.tgz","fileCount":15,"integrity":"sha512-JGJElHUcuFwue7NNRMJoB3NGmkO/2KUx/+pItZci4kXXO8WkeHq4VtCm7y9LSZo3ZI/U0fly71izZIvMBzd68Q==","signatures":[{"sig":"MEYCIQDgiwwt11LrTabC0+7V+vY5g+AgV/YP9ue+rkVYFX7I1AIhAJfbawIxq/oit5BcTRgzFcdpDZH33ojKCU/WFQOSBP1j","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":109778},"main":"./src/index.js","types":"./src/index.d.ts","module":"./src/index.js","engines":{"node":">=18"},"gitHead":"dd96a5fdf3a1821a4aac7bcc029e7e5d751e83c6","harmony":{"alias":"react-native-big-list"},"private":false,"scripts":{"prepare":"echo skip"},"_npmUser":{"name":"luyizouyuan","email":"189605613@qq.com"},"repository":{"url":"https://gitcode.com/rn_ohos_plugin/react_native_big_list","type":"git"},"_npmVersion":"11.12.1","description":"适配鸿蒙版本，提供react_native_big_list组件。","directories":{},"_nodeVersion":"24.15.0","react-native":"./src/index.js","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.6.3","metro":"^0.81.0","react":"18.2.0","typescript":"5.0.4","@types/react":"18.2.79","react-native":"0.72.5","@react-native/typescript-config":"0.79.5","@react-native-oh/react-native-harmony-cli":"^0.77.50"},"peerDependencies":{"react-native":">=0.72"},"_npmOperationalInternal":{"tmp":"tmp/react-native-big-list_1.6.4_1785402565038_0.011162399996529127","host":"s3://npm-registry-packages-npm-production"}},"1.6.5":{"_id":"@bingtang-rn/react-native-big-list@1.6.5","dist":{"shasum":"51097a1ac578f5bc8a1ef6e76a1cce99ab4d6e3f","tarball":"https://registry.npmjs.org/@bingtang-rn/react-native-big-list/-/react-native-big-list-1.6.5.tgz","fileCount":15,"integrity":"sha512-DK1fR51ewn07J7vNYUYg/5TAkwcDihnza6K2Fvp2Y1WCeE8AgOQ2K3ndRseTzfgok68UBD6ollcAZLDkB+PDaA==","signatures":[{"sig":"MEYCIQCr1fbPIb/dhvEh/rC5LHlCAtsAj9pf9/PiXBcsOhq9ogIhANGi2p61t22hIO278eWkDk4u6Ju0PIUqhYcMYzNS96f0","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHv40PjacvM/4JjJbPjamJCS2OB6YmkS/UJ+5uGJfioTAiEA93PqId881MEV5j7AZYuzFFeqU7iGsxIuEZGLEoz82Yg="}],"unpackedSize":110115},"main":"./src/index.js","name":"@bingtang-rn/react-native-big-list","_from":"file:bingtang-rn-react-native-big-list-1.6.5.tgz","types":"./src/index.d.ts","module":"./src/index.js","engines":{"node":">=18"},"harmony":{"alias":"react-native-big-list"},"license":"Apache-2.0","private":false,"scripts":{"prepare":"echo skip"},"version":"1.6.5","_npmUser":{"name":"luyizouyuan","email":"189605613@qq.com"},"homepage":"https://gitcode.com/rn_ohos_plugin/react_native_big_list","keywords":["react-native","react-native-big-list","harmony","harmonyos"],"_resolved":"D:\\code\\rn\\npm\\batch\\react_native_big_list\\bingtang-rn-react-native-big-list-1.6.5.tgz","_integrity":"sha512-DK1fR51ewn07J7vNYUYg/5TAkwcDihnza6K2Fvp2Y1WCeE8AgOQ2K3ndRseTzfgok68UBD6ollcAZLDkB+PDaA==","repository":{"url":"https://gitcode.com/rn_ohos_plugin/react_native_big_list","type":"git"},"_npmVersion":"11.12.1","description":"适配鸿蒙版本，提供react_native_big_list组件。","directories":{},"maintainers":[{"name":"luyizouyuan","email":"189605613@qq.com"}],"_nodeVersion":"24.15.0","react-native":"./src/index.js","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.6.3","metro":"^0.81.0","react":"18.2.0","typescript":"5.0.4","@types/react":"18.2.79","react-native":"0.72.5","@react-native/typescript-config":"0.79.5","@react-native-oh/react-native-harmony-cli":"^0.77.50"},"peerDependencies":{"react-native":">=0.72"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/react-native-big-list_1.6.5_1790566218869_0.4254158866910078"}}},"time":{"created":"2026-07-30T09:09:24.820Z","modified":"2026-09-28T03:30:19.134Z","1.6.4":"2026-07-30T09:09:25.197Z","1.6.5":"2026-09-28T03:30:18.958Z"},"license":"Apache-2.0","homepage":"https://gitcode.com/rn_ohos_plugin/react_native_big_list","keywords":["react-native","react-native-big-list","harmony","harmonyos"],"repository":{"url":"https://gitcode.com/rn_ohos_plugin/react_native_big_list","type":"git"},"description":"适配鸿蒙版本，提供react_native_big_list组件。","maintainers":[{"name":"luyizouyuan","email":"189605613@qq.com"}],"readme":"# @bingtang-rn/react-native-big-list for HarmonyOS\r\n\r\n本项目基于 [react-native-big-list](https://marcocesarato.github.io/react-native-big-list-docs/) 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：[issues](https://gitcode.com/rn_ohos_plugin/react_native_big_list/issues)。\r\n\r\n## 版本对应关系\r\n\r\n| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 |\r\n| ------------ | ---------- | ------------ | -------- | ------------- |\r\n| 1.6.4 | 1.6.4 | 0.72+ | 是 | API17+ |\r\n\r\n## 安装\r\n\r\n```bash\r\nnpm install @bingtang-rn/react-native-big-list\r\n```\r\n\r\n## 使用\r\n\r\n```tsx\r\nimport BigList, { BigList as RawBigList } from 'react-native-big-list';\r\n\r\n// 基础虚拟化列表\r\n<BigList\r\n  data={items}\r\n  itemHeight={80}\r\n  renderItem={({ item }) => <Row item={item} />}\r\n  headerHeight={80}\r\n  renderHeader={() => <ListHeader />}\r\n  footerHeight={60}\r\n  renderFooter={() => <ListFooter />}\r\n/>;\r\n\r\n// 分区列表 + 吸顶 header\r\n<BigList\r\n  sections={sectionsData}\r\n  itemHeight={80}\r\n  renderItem={({ item }) => <Row item={item} />}\r\n  sectionHeaderHeight={56}\r\n  renderSectionHeader={(section) => <SectionHeader section={section} />}\r\n  stickySectionHeadersEnabled\r\n/>;\r\n\r\n// 编程式滚动（需原始 class ref，用命名导出 RawBigList）\r\nconst ref = useRef<RawBigList<typeof items[0]>>(null);\r\nref.current?.scrollToIndex({ index: 100, animated: true });\r\n```\r\n\r\n> import 时使用原库名 `'react-native-big-list'`，而非鸿蒙包名（RNOH `harmony.alias` 自动映射到 `@bingtang-rn/react-native-big-list`）。\r\n\r\n**平台差异**：\r\n- 本库为纯 JS 虚拟化列表，无原生代码，所有能力通过 RNOH JS 运行时 + RNOH 内置 `ScrollView`/`Animated`/`RefreshControl`/`Image` 实现。\r\n- 吸顶 Section Header（`stickySectionHeadersEnabled`）与 `nativeOffsetValues` 使用 `Animated.attachNativeEvent` 原生驱动（RNOH 已实现并内部使用），同时保留 JS `onScroll` 驱动作为安全兜底。\r\n\r\n**权限要求**：\r\n- 无（纯 JS 列表组件，不涉及任何系统权限）。\r\n\r\n**Manual Link**：\r\n- 本库为纯 JS（`js_only`），无需 C++/ETS 侧 Package 注册。下方 Manual Link 章节为模板脚手架内容，**不适用于本库**；RNOH `harmony.alias` 已完成自动链接。\r\n\r\n## Link\r\n\r\n| 版本 | 是否支持 Autolink |\r\n|------|------------------|\r\n| 当前版本 | 是 |\r\n\r\n如使用版本支持 Autolink 且工程已接入，可跳过手动配置。\r\n\r\n<details>\r\n<summary>Manual Link 配置</summary>\r\n\r\n> **说明**：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。\r\n\r\n### 1. Overrides RN SDK\r\n\r\n在工程根目录 `oh-package.json5` 添加：\r\n\r\n```json\r\n{\r\n  \"overrides\": {\r\n    \"@rnoh/react-native-openharmony\": \"./react_native_openharmony\"\r\n  }\r\n}\r\n```\r\n\r\n### 2. 引入原生端依赖\r\n\r\n打开 `entry/oh-package.json5`，添加：\r\n\r\n```json\r\n\"dependencies\": {\r\n  \"@bingtang-rn/react-native-big-list\": \"file:../../node_modules/@bingtang-rn/react-native-big-list/harmony/big_list.har\"\r\n}\r\n```\r\n\r\n执行 `ohpm install`。\r\n\r\n### 3. 配置 CMakeLists\r\n\r\n打开 `entry/src/main/cpp/CMakeLists.txt`，添加：\r\n\r\n```cmake\r\nset(OH_MODULES \"${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules\")\r\n\r\nadd_subdirectory(\"${OH_MODULES}/@bingtang-rn/react-native-big-list/src/main/cpp\" ./big_list)\r\n\r\ntarget_link_libraries(rnoh_app PUBLIC big_list)\r\n```\r\n\r\n### 4. 注册 Package（C++ 侧）\r\n\r\n打开 `entry/src/main/cpp/PackageProvider.cpp`，添加：\r\n\r\n```cpp\r\n#include \"BigListPackage.h\"\r\n\r\nstd::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {\r\n    return {\r\n        std::make_shared<BigListPackage>(ctx),\r\n    };\r\n}\r\n```\r\n\r\n### 5. 注册 Package（ETS 侧）\r\n\r\n打开 `entry/src/main/ets/RNPackagesFactory.ets`，添加：\r\n\r\n```typescript\r\nimport { BigListPackage } from '@bingtang-rn/react-native-big-list/ts';\r\n\r\nexport function createRNPackages(ctx: RNPackageContext): RNPackage[] {\r\n  return [\r\n    new BigListPackage(ctx),\r\n  ];\r\n}\r\n```\r\n\r\n</details>\r\n\r\n## 属性 / API\r\n\r\n| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 |\r\n|-----|------|------|--------|----------------|\r\n| data + itemHeight + renderItem | 虚拟化长列表渲染 | data: ItemT[], itemHeight: number\\|function, renderItem: (info) => Element | — | ✅ 完全支持 |\r\n| sections + renderSectionHeader/Footer | 分区列表 | sections: ItemT[][], renderSectionHeader/Footer: (section) => Element | — | ✅ 完全支持 |\r\n| stickySectionHeadersEnabled | 吸顶 Section Header | boolean | — | ✅ 完全支持 |\r\n| nativeOffsetValues | 原生偏移跟踪 | { x?: Animated.Value, y?: Animated.Value } | — | ✅ 完全支持 |\r\n| numColumns + columnWrapperStyle | 多列布局 | numColumns: number, columnWrapperStyle: style | — | ✅ 完全支持 |\r\n| horizontal | 水平滚动 | boolean | — | ✅ 完全支持 |\r\n| placeholder + placeholderImage/Component | 占位渲染 | placeholder: boolean, placeholderImage: any, placeholderComponent: ReactNode | — | ✅ 完全支持 |\r\n| onRefresh + refreshing | 下拉刷新 | onRefresh: () => void, refreshing: boolean | — | ✅ 完全支持 |\r\n| onEndReached + onEndReachedThreshold | 触底加载 | onEndReached: ({distanceFromEnd}) => void, onEndReachedThreshold: number | — | ✅ 完全支持 |\r\n| scrollTo / scrollToTop / scrollToEnd / scrollToIndex / scrollToItem / scrollToOffset / scrollToLocation / scrollToSection / flashScrollIndicators / getNativeScrollRef | 编程式滚动控制（via ref） | 各方法参数见类型声明 | void / ScrollView | ✅ 完全支持 |\r\n| getItemOffset / getItem / getItems / isVisible / isEmpty / onViewableItemsChanged | 可见性查询与空状态（via ref） | { index, section? } | number / ItemT / boolean | ✅ 完全支持 |\r\n| inverted | 倒序列表 | boolean | — | ✅ 完全支持 |\r\n| initialScrollIndex | 初始滚动位置 | number | — | ✅ 完全支持 |\r\n| getItemLayout / ListEmptyComponent / ListHeaderComponent / ListFooterComponent / keyExtractor / removeClippedSubviews / refreshing | FlatList 兼容 Props | 各对应 FlatList 同名 prop | — | ✅ 完全支持 |\r\n\r\n### 平台差异\r\n- 无平台差异。本库为纯 JS，所有能力在 HarmonyOS 上与 Android/iOS 行为一致（底层依赖 RNOH `ScrollView` 映射 ArkUI 滚动容器）。\r\n\r\n### 未实现功能\r\n无。\r\n\r\n### 使用限制\r\n- 大数据量（10,000+ 条）在 RNOH `ScrollView` 上的滚动流畅度取决于设备性能；建议 `itemHeight` 用固定数值以走 `getItemLayout` 短路、开启 `removeClippedSubviews` 降低内存。\r\n- 含吸顶 Section Header 的列表在吸顶瞬间可能有轻微停顿（RNOH 性能文档已知项），建议限制吸顶组件复杂度。\r\n- `scrollToItem` 在分区模式下用 `JSON.stringify` + `indexOf` 查找（原库既有逻辑），大数据量下性能较差，属原库限制而非适配问题。\r\n\r\n## 快速验证（运行 Example）\r\n\r\n### 前置条件\r\n\r\n| 依赖 | 版本要求 |\r\n|------|----------|\r\n| Node.js | >= 18 |\r\n| DevEco Studio | 5.0+ / 6.0+ |\r\n| HarmonyOS SDK | API 17+ |\r\n\r\n### 运行步骤\r\n\r\n**1. 克隆仓库**\r\n\r\n```bash\r\ngit clone <仓库地址>\r\ncd <仓库目录>\r\n```\r\n\r\n**2. 安装依赖并构建**\r\n\r\n```bash\r\nnpm install --legacy-peer-deps\r\nnpm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）\r\n```\r\n\r\n**3. 进入 example 目录，安装依赖**\r\n\r\n```bash\r\ncd example\r\nnpm install --legacy-peer-deps\r\n```\r\n\r\n**4. 生成 JS Bundle**\r\n\r\n```bash\r\nnpm run dev\r\n```\r\n\r\n产物：`harmony/entry/src/main/resources/rawfile/bundle.harmony.js`\r\n\r\n**5. 用 DevEco Studio 打开鸿蒙工程**\r\n\r\n- 打开 DevEco Studio\r\n- 选择 `example/harmony` 目录\r\n- 等待 Sync 完成\r\n\r\n**6. 编译并运行 HAP**\r\n\r\n在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。\r\n\r\n> **注意**：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。\r\n\r\n## 约束与限制\r\n\r\n### 兼容性\r\n\r\n- RNOH: 0.72+\r\n- HarmonyOS SDK: API 17+\r\n- DevEco Studio: 5.0+\r\n\r\n## 遗留问题\r\n\r\n无\r\n\r\n## 开源协议\r\n\r\n本项目基于 [Apache License](https://github.com/marcocesarato/react-native-big-list/blob/master/LICENSE)，详见 [LICENSE](./LICENSE) 文件。\r\n","readmeFilename":"README.md"}