`<FeedList>`

一个适用于 ReactLynx 的信息流列表组件，面向复杂布局和无限滚动列表场景。

Info

你可以查看源码来了解它的运行原理，也欢迎大家提 MR 来丰富其能力。

此外，你也可以参考这个实现，利用 MTS 自行实现定制化的列表 refresh / load-more 能力。

使用指南

如何理解`refreshOptions`

基本用法

当页面既需要虚拟列表渲染，又需要下拉刷新、加载更多等 feed 行为时，使用 FeedList。每一行都应作为直接的 list-item 子节点，并提供稳定的 item-key；同时设置 listId 和 listType，让底层列表能正确管理身份和布局。

如何管理底部状态

用 loadMoreFooter 表示加载中状态，用 noMoreDataFooter 表示没有更多数据。通过 changeHasMoreStatus 在两种状态之间切换；这个底部状态独立于刷新状态和列表 diff 结果。

如何主动触发刷新

当刷新由命令触发，而不是由下拉手势触发时，使用 startRefresh，例如重试按钮或外部筛选条件变化。数据请求结束后，调用 finishRefresh 释放刷新头。

FeedListProps

Properties

bounceableOptions

iOS

Android

类型boolean | BounceableBasicProps·默认值false

接受true为默认选项。如果需要自定义弹性效果，可以传入bounceableProps。

bounces

iOS

类型boolean·默认值true

启用 iOS 弹性效果。

children

iOS

Android

Harmony

类型ReactNode

列表的子元素。

className

iOS

Android

Harmony

类型string

类名

crossAxisGap

iOS

Android

Harmony

类型number·默认值0

指定列表中组件的交叉轴间距。

enableScroll

iOS

Android

Harmony

类型boolean·默认值true

启用垂直滚动。

enableScrollBar

iOS

Android

Harmony

类型boolean·默认值false

启用滚动条。

enableScrollMonitor

iOS

Android

Harmony

类型boolean·默认值false

启用滚动监控。

exposureID

iOS

Android

Harmony

类型string

全局曝光的曝光ID

exposureScene

iOS

Android

Harmony

类型string

全局曝光的曝光场景

initialScrollIndex

iOS

Android

Harmony

类型number·默认值0

列表在初始加载时自动滚动到的位置。

iosEnableSimultaneousTouch

iOS

类型boolean·默认值true

强制触摸事件发送到列表。

iosScrollsToTop

iOS

类型boolean·默认值true

点击 iOS 状态栏时是否需要回顶。

itemSnap

iOS

Android

Harmony

类型{factor: number, offset: number}

分页滚动

listId

iOS

Android

Harmony

类型string

列表的 ID。

listMaxSize

iOS

Android

Harmony

类型number

单位是 px。设置容器的自适应高度限制。当子内容高度小于此值时，容器高度自动适应内容；当子内容超过此值时，容器高度将固定为该值并显示滚动条。

listType

iOS

Android

Harmony

类型single | flow | waterfall

列表的布局类型。

loadMoreFooter

iOS

Android

类型ReactElement·默认值false

列表的加载更多区域。

lowerThresholdItemCount

iOS

Android

Harmony

类型number·默认值0

下边缘触发 onScrollToLower 事件的条目阈值。

main-thread:gesture

iOS

Android

类型BaseGesture

如果您想使用手势，请在此处传递。

mainAxisGap

iOS

Android

Harmony

类型number·默认值0

指定列表中组件的主要轴间距。

name

iOS

Android

Harmony

类型string

列表的名称。

needLayoutCompleteInfo

iOS

Android

Harmony

类型boolean·默认值false

输出布局完成的详细信息。

noMoreDataFooter

iOS

Android

类型ReactElement·默认值false

当没有更多数据要插入并且调用hasMoreData方法时，loadMoreFooter将被切换为noMoreDataFooter。

onUIAppear

iOS

Android

Harmony

类型(e: CommonEvent) => void

UI 的曝光事件。

onUIDisappear

iOS

Android

Harmony

类型(e: CommonEvent) => void

UI 的消失事件。

preloadBufferCount

iOS

Android

Harmony

类型number·默认值0

控制列表在屏上节点之外，提前加载节点的个数。在 listType 为 waterfall 时不生效。

ref

类型ForwardedRef

refreshOptions

iOS

Android

类型boolean | RefreshProps·默认值false

接受true为默认选项。如果需要自定义刷新效果，可以传入RefreshProps。

scrollEventThrottle

iOS

Android

Harmony

类型number·默认值200

列表触发滚动事件回调的时间间隔（毫秒）。

scrollMonitorTag

iOS

Android

Harmony

类型string·默认值false

滚动监控的标签。

scrollOrientation

iOS

Android

Harmony

类型vertical | horizontal·默认值'vertical'

设置为 'vertical' 为垂直滚动，设置为 'horizontal' 为水平滚动。

scrollPropagationBehavior

iOS

Android

类型ScrollPropagationBehavior·默认值'native'

控制滚动事件是否向父级容器传递。'preventPropagate' 在 iOS 上暂时需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。 Currently, this property has its limits because the full ability has dependency on higher native SDK version. On iOS the 'propagate' only works when the both parent component and this component are set to 'propagate'. And useRefactorList={true} don't support 'propagate'. On Android, the 'preventPropagate' can only works when its parent element is x-swiper and x-viewpager-ng.

shouldRequestStateRestore

iOS

Android

Harmony

类型boolean·默认值false

元素层复用的生命周期。解决 UI 层复用状态混乱的问题。

showVisibleItemInfoInScrollEvent

iOS

Android

Harmony

类型boolean·默认值false

控制是否在绑定滚动事件中包含附加单元格信息。

spanCount

iOS

Android

Harmony

类型number·默认值true

列表的列数。

stickyOffset

iOS

Android

Harmony

类型number·默认值0

粘性位置与列表顶部或底部的偏移量。

style

iOS

Android

Harmony

类型CSSProperties

样式

temporaryAndroidEnableOverflow

Android

类型boolean·默认值true

是否开启 android 平台层 list overflow

temporaryBlockScrollClass

iOS

类型string·默认值'BDXLynxViewPager'

当 scrollPropagationBehavior 设为 'preventPropagate' 时，被阻止滚动的容器的具体类名。'preventPropagate' 在 iOS 上暂时需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。此为临时属性，将在新版 Lynx SDK 中废弃。

temporaryBlockScrollTag

iOS

类型number·默认值0

用于指定当 scrollPropagationBehavior 设为 'preventPropagate' 时被阻止滚动的原生容器标签（对应 UIView 的 Tag 属性）。该值需由原生容器提供方指定，且 'preventPropagate' 在 iOS 上暂时需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。此为临时属性，将在新版 Lynx SDK 中废弃。

upperThresholdItemCount

iOS

Android

Harmony

类型number·默认值0

上边缘触发 onScrollToUpper 事件的条目阈值。

useRefactorList

iOS

Android

Harmony

类型boolean·默认值true

使用重构后的列表。

Events

catchLongPress

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

与 onLongPress 相同，但会阻止事件冒泡。

catchTouchCancel

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

与 onTouchCancel 相同，但会阻止事件冒泡。

catchTouchEnd

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

与 onTouchEnd 相同，但会阻止事件冒泡。

catchTouchMove

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

与 onTouchMove 相同，但会阻止事件冒泡。

catchTouchStart

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

与 onTouchStart 相同，但会阻止事件冒泡。

debugLogLevel

iOS

Android

Harmony

类型0 | 1 | 2 | 3·默认值0

显示调试日志。0：无，1：错误，2：信息，3：详细

onLayoutChange

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

当 UI 视口大小改变时发送。

onLayoutComplete

iOS

Android

Harmony

类型

(e: {detail: {diffResult?: {insertions: number[], move_from: number[], move_to: number[], removals: number[], update_from: number[], update_to: number[]}, layout-id: number, visibleCellsAfterLayout?: ListItemInfo[], visibleCellsBeforeLayout?: ListItemInfo[]}}) => void

当列表的条目更新并且此更新过程已完成时发送。

onLongPress

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

当触摸点在 UI 上按住一段时间后发送。

onScroll

iOS

Android

类型(e: ScrollEvent) => void

滚动时触发。

onScrollEnd

iOS

Android

类型(e: [object Object] | undefined) => void·默认值undefined

滚动停止时触发。

onScrollStateChange

iOS

Android

Harmony

类型(e: ListScrollStateChangeEvent) => void

滚动状态变更。

onScrollToLower

iOS

Android

类型(e: [object Object] | undefined) => void·默认值undefined

滚动到底部时触发。

onScrollToUpper

iOS

Android

类型(e: [object Object] | undefined) => void·默认值undefined

滚动到顶部时触发。

onSnapToItem

iOS

Android

Harmony

类型(e: ListSnapEvent) => void

当列表限位滚动到一个条目时发送。

onTap

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

当触摸点在 UI 上轻触时发送。

onTouchCancel

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

当触摸事件在完成前被中断或取消时发送。

onTouchEnd

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

当触摸点从 UI 上移除时发送。

onTouchMove

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

当触摸点在 UI 上移动时发送。

onTouchStart

iOS

Android

Harmony

类型(e: EventHandler | undefined) => void

当触摸点放置在 UI 上时发送。

headerReleased

headerSize

类型number

offset

类型number

refreshOffsetEvent

headerSize

类型number

isDragging

类型boolean

offset

类型number

FeedListRef

autoScroll

iOS

Android

Harmony

类型(rate: px | rpx | ppx | rem | em | vw | vh, start: boolean, autoStop: boolean) => void

自动滚动列表到指定位置和偏移量。

changeHasMoreStatus

iOS

Android

类型(hasMore: boolean) => void

当没有更多数据要插入时，调用此方法将loadMoreFooter替换为noMoreDataFooter。

finishRefresh

iOS

Android

类型() => void

在startRefresh事件之后，调用此方法将结束刷新状态并使刷新Header进行反弹。

getVisibleCells

iOS

Android

Harmony

类型(success: (res: unknown) => void, fail: (res: unknown) => void) => void

将列表滚动到指定位置和偏移量。

scrollIntoID

iOS

Android

Harmony

类型

(animated: boolean, alignTo: top | bottom | middle | none, listItemID: string, id: string, index: number, offset: number, success: (res: unknown) => void, fail: (res: unknown) => void) => void

·默认值false

扩展标准列表的 scrollTo 方法。此方法使用 worklet 并支持像 scroll-view 方法的参数 id。由于列表是懒加载的，此方法中需要索引以找到 id 组件的位置。需要 useRefactorList={true}。

scrollTo

iOS

Android

Harmony

类型

(animated: boolean, alignTo: top | bottom | middle | none, index: number, offset: number, success: (res: unknown) => void, fail: (res: unknown) => void) => void

·默认值0

滚动列表到指定位置和偏移量。

startRefresh

iOS

Android

类型() => void

当enable-refresh为true时，调用此函数会使刷新Header全露并触发startRefresh事件。之后，刷新Header附加到List的顶部。

RefreshEvent

triggeredBy

类型startRefresh | drag

RefreshStateChange

state

iOS

Android

Harmony

类型{DRAGGING: [object Object], IDLE: [object Object], OVER_DRAG_RELEASE: [object Object], REFRESHING: [object Object]}

刷新头的状态

如何使用 `refreshOptions`

useRefresh hook 是 useBounces hook 的扩展，它使用了 useBounces 的基础能力，并扩展了几个能力：

支持与 upperBounceItem 相对的 refreshHeader 节点。
支持回弹过程中停留在 refreshHeader 上，模拟上拉加载效果

我们让 useBounce 的回弹曲线能够在 refreshHeader，也即刷新区域的边缘处停止，直到 finishRefresh 方法在刷新结束后被主动调用，再回弹至边缘。

一次完整的刷新分为四个阶段，下面的事件分别对应这些阶段的切换时机。

事件

这四个阶段有各自的事件触发时机：

onStartRefresh：最重要的事件，在阶段三的状态触发，此事件中可以进行数据的更新；
onRefreshOffsetChange：RefreshHeader 露出、处于刷新区域的时候会连续触发，发送当前的 refreshHeader 露出位置；
onHeaderReleased：从阶段二结束拖拽时触发，开始回弹至 refreshHeader；
onRefreshStateChange：不同阶段转移时触发，提供在一个单一事件中掌握所有状态的能力：
- IDLE：refreshHeader 未露出，处于正常滚动区域的状态；
- OVER_DRAG_RELEASE：与 onHeaderReleased 时机相同，阶段二结束拖拽时的状态；
- REFRESHING：与 onStartRefresh 时机相同；
- DRAGGING：拖拽并露出 refreshHeader 的状态下持续触发；

#<FeedList>

#基本用法

#如何管理底部状态

#如何主动触发刷新

#FeedListProps

#Properties

#Events

#headerReleased

#refreshOffsetEvent

#FeedListRef

#RefreshEvent

#RefreshStateChange

#如何使用 refreshOptions

#事件

`<FeedList>`

基本用法

如何管理底部状态

如何主动触发刷新

FeedListProps

Properties

Events

headerReleased

refreshOffsetEvent

FeedListRef

RefreshEvent

RefreshStateChange

如何使用 `refreshOptions`

事件