HippyRecyclerView

forked from Flipkart/recyclerlistview

如果这个项目对您有帮助，请点击星星🌟支持我们。

这是适用于 Hippy 和 Web 的高性能列表视图，支持复杂布局。仅使用 JS，没有本机依赖项，灵感来自 Android 上的 RecyclerView 和 iOS 上的 UICollectionView。

npm install --save hippy-recycler-view 最新Beta版: npm install --save hippy-recycler-view@beta

• 概述和特点
• 为什么？
• 示例
• Props
• Typescript
• 指南
• License
• 联系我们

注意：文档将很快升级，目前请检查代码注释以了解其清晰度并探索功能。此组件也正在使用 Hippy-Web 进行积极测试。

概述和特点

HippyRecyclerView 使用“单元格回收”来重用不再可见的视图来呈现项目，而不是创建新的视图对象。 创建对象非常昂贵，并且会产生内存开销，这意味着当您滚动列表时，内存占用量会不断增加。 从内存中释放不可见的对象是另一种技术，但这会导致创建更多对象和大量垃圾收集。回收是呈现无限列表的最佳方式，不会影响性能或内存效率。

除了性能优势之外，HippyRecyclerView 还具有以下出色的功能：

• 跨平台，可在 Web 上运行
• 支持交错网格布局
• 即使无法预先确定尺寸，也支持可变高度项目（prop - forceNonDeterministicRendering）
• 即时布局切换，如从 GridView 切换到 ListView 或反之亦然
• 末端到达检测
• 横向模式
• 可见性事件
• 初始渲染偏移/索引支持
• 页脚支持
• 容器尺寸改变时支持重排，并保留第一个可见项目
• 滚动位置保存
• 网页窗口滚动支持
• （新）添加了 ItemAnimator 接口，可根据您的意愿自定义 RLV 处理布局更改的方式。允许您修改移动单元格的动画。您可以执行诸如当某个单元格的高度发生变化时将项目平滑地移动到新位置之类的操作。
• （新）稳定 ID 支持，能够将稳定 ID 与项目关联。将启用漂亮的添加/删除动画，并在 DataProvider 更新时优化重新渲染。
• （新）粘性回收物品，可粘在顶部或底部。

为什么？

HippyRecyclerView 在构建时就考虑到了性能，这意味着快速滚动或掉帧时不会出现空白。 HippyRecyclerView 鼓励您为需要渲染的项目设置确定的高度。 这并不意味着您需要让所有项目具有相同的高度和内容，您所需要的只是一种查看数据并预先计算高度的方法， 以便 HippyRecyclerView 可以一次性计算布局，而不是等待绘制完成。 您仍然可以使用不同类型的项目来制作各种 GridView 和 ListView，这些项目都以最佳方式回收。基于类型的回收非常容易实现，而且开箱即用。

如果您无法提前确定项目的高度，只需在 HippyRecyclerView 上将 forceNonDeterministicRendering prop 设置为 true。 它将把给定的尺寸视为估计值并让项目调整大小。尝试给出好的估计值以改善体验。

示例

Production Flipkart Grocery Demo Video (or try the app): https://youtu.be/6YqEqP3MmoU
Infinite Loading/View Change (Expo): https://snack.expo.io/@naqvitalha/rlv-demo
Mixed ViewTypes: https://snack.expo.io/B1GYad52b
extendedState,stableIDs and ItemAnimator (Expo): https://snack.expo.io/@arunreddy10/19bb8e
Sample project: https://github.com/naqvitalha/travelMate
Web Sample (Using RNW): https://codesandbox.io/s/k54j2zx977, https://jolly-engelbart-8ff0d0.netlify.com/
Context Preservation Sample: https://github.com/naqvitalha/recyclerlistview-context-preservation-demo

Other Video: https://www.youtube.com/watch?v=Tnv4HMmPgMc

Props

Prop	必填	参数类型	描述
layoutProvider	Yes	BaseLayoutProvider	定义每个元素的布局（高度/宽度）的构造函数
dataProvider	Yes	DataProvider	构造函数定义每个元素的数据
contextProvider	No	ContextProvider	用于在视图被破坏的情况下维持滚动位置，这通常发生在后退导航中
rowRenderer	Yes	(type: string / number, data: any, index: number) => JSX.Element / JSX.Element[] / null	返回要渲染的 React 组件的方法。回调中会获取视图的类型、数据、索引和扩展状态
initialOffset	No	number	您想要开始渲染的初始偏移量；如果您想跨页面维护滚动上下文，这非常有用。
renderAheadOffset	No	number	指定您希望视图提前渲染多少像素。增加此值有助于减少空白（如果有）。但是，保持尽可能低的值才是目的。更高的值也会增加重新渲染计算
isHorizontal	No	boolean	如果为 true，列表将水平运行，而不是垂直运行
onScroll	No	(rawEvent: ScrollEvent, offsetX: number, offsetY: number) => void	当用户滚动时执行的滚动回调函数
onRecreate	No	(params: OnRecreateParams) => void	从上下文提供程序重新创建回收站视图时执行的回调函数
externalScrollView	No	{ new (props: ScrollViewDefaultProps): BaseScrollView }	使用它来传递 BaseScrollView 的实现
onEndReached	No	() => void	当视图触底时执行的回调函数
onEndReachedThreshold	No	number	指定 onEndReached 回调的提前像素数
onEndReachedThresholdRelative	No	number	指定列表底部边缘必须距离内容末尾多远（以列表可见长度为单位）才能触发 onEndReached 回调
onVisibleIndicesChanged	No	TOnItemStatusChanged	提供可见索引；有助于发送展示事件
onVisibleIndexesChanged	No	TOnItemStatusChanged	（2.0 beta 版已弃用）提供可见索引；有助于发送展示事件
renderFooter	No	() => JSX.Element / JSX.Element[] / null	如果要呈现页脚，请提供此方法。有助于在进行增量加载时显示加载器
initialRenderIndex	No	number	指定要从其开始渲染的初始项目索引。如果同时指定，则优先于 initialOffset
scrollThrottle	No	number	滚动节流时间
canChangeSize	No	boolean	指定尺寸是否可以改变
distanceFromWindow	No	number	(已弃用) 使用 applyWindowCorrection() API 的 windowShift. 用法?
applyWindowCorrection	No	(offset: number, windowCorrection: WindowCorrection) => void	(API 增强/替换 distanceFromWindow) 允许根据传递的校正值更新可见的 windowBounds。用户可以指定 windowShift；如果整个 RecyclerListWindow 需要向下/向上移动，startCorrection；如果顶部窗口边界需要移动，例如要向下移动的顶部窗口边界是与 RecyclerListView 顶部边缘重叠的内容， endCorrection：用于更改底部窗口边界以用于类似用例。用法?
useWindowScroll	No	boolean	仅限 Web；在窗口中布局元素，而不是可滚动的 div
disableRecycling	No	boolean	关闭回收功能
forceNonDeterministicRendering	No	boolean	默认值为 false；如果启用，布局提供程序中提供的尺寸将不会严格执行。如果无法准确确定项目尺寸，请使用此选项
extendedState	No	object	在某些情况下，在行级别传递的数据可能不包含该项目所依赖的所有信息，您可以将所有其他信息保留在外部并通过此属性向下传递。更改此对象将导致所有内容重新渲染。请确保不要经常更改它以确保性能。重新渲染很繁重。
itemAnimator	No	ItemAnimator	启用 HippyRecyclerView 项目单元格动画（移动、添加、删除等）
style	No	object	将样式传递给内部 ScrollView
scrollViewProps	No	object	对于所有需要代理到内部/外部滚动视图的 props。将它们放在一个对象中，它们将被传播并传递下去。
layoutSize	No	Dimension	将防止计算列表视图的大小所需的初始空渲染，并使用这些尺寸在第一次渲染时渲染列表项。这对于服务器端渲染等情况很有用。如果渲染后可以更改大小，则必须将 prop canChangeSize 设置为 true。请注意，这不是滚动视图大小，仅用于布局。
onItemLayout	No	number	当 HippyRecyclerView 中的某项（位于索引处）布局完毕后执行的回调函数。这也可以用作 itemsRendered 类回调的代理。
windowCorrectionConfig	No	object	用于指定窗口校正配置以及是否应将其应用于某些滚动事件

要查看完整功能集，请查看HippyRecyclerView的 prop 定义 （文件底部）。所有ScrollView功能如RefreshControl均可立即使用。

applyWindowCorrection usage

applyWindowCorrection 用于动态更改 HippyRecyclerView 的可见窗口边界。HippyRecyclerView 的 windowCorrection 以及当前滚动偏移量均会显示给用户。该windowCorrection对象由 3 个数值组成：

• windowShift - 直接替换distanceFromWindow参数。窗口偏移是 HippyRecyclerView 整体在 StickyContainer 内偏移的偏移值，使用此参数指定第一个列表项距离窗口顶部有多远。此值可校正 StickyObjects 和 HippyRecyclerView 的滚动偏移。
• startCorrection - startCorrection 用于指定顶部可见窗口边界的偏移，这样即使有外部因素（如 CoordinatorLayout 工具栏）用户也可以接收到正确的 Sticky 标头实例。
• endCorrection - endCorrection 用于指定底部可见窗口边界的偏移，当外部因素（如底部应用栏）改变可见视图边界时，用户可以接收正确的 Sticky Footer 实例。

如下例所示：

Typescript

Typescript 开箱即用。唯一的例外是继承的 Scrollview 属性。 为了让 Typescript 能够使用继承的 Scrollview 属性，您必须将所述继承的 Scrollview 属性放置在 scrollViewProps 属性内。

<RecyclerListView
  rowRenderer={this.rowRenderer}
  dataProvider={queue}
  layoutProvider={this.layoutProvider}
  onScroll={this.checkRefetch}
  renderFooter={this.renderFooter}
  scrollViewProps={{
    refreshControl: (
      <RefreshControl
        refreshing={loading}
        onRefresh={async () => {
          this.setState({ loading: true });
          analytics.logEvent('Event_Stagg_pull_to_refresh');
          await refetchQueue();
          this.setState({ loading: false });
        }}
      />
    )
  }}
/>

指南

• Sample Code
• Performance
• Sticky Guide
• Web 支持： 开箱即用，可与 React Native Web 配合使用。要与 ReactJS 配合使用，请从 recyclerlistview/web 导入，例如 import { RecyclerListView } from "recyclerlistview/web"。 。如果要保留导入路径，请使用别名。只有平台特定的代码才是构建的一部分，因此您的应用不会附带不必要的代码。
• Polyfills Needed: requestAnimationFrame, ResizeObserver

License

Apache v2.0

联系我们

如果您遇到任何问题，请新建 issue 描述。