For AI agents: the complete documentation index is available at /next/zh/llms.txt, the full documentation bundle is available at /next/zh/llms-full.txt, and this page is available as Markdown at /next/zh/ui/components/feed-list.md.
lynx-ui logo
lynx-ui
  • 简体中文
  • FeedList

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

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

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

    使用指南
    如何理解`refreshOptions`

    基本用法

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

    示例

    如何管理底部状态

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

    如何主动触发刷新

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

    结构

    <FeedList>
      <list-item />
    </FeedList>

    组件 API

    FeedList

    Properties
    bounceableOptionsiOSAndroid
    类型boolean | BounceableBasicProps·默认值false
    接受true为默认选项。如果需要自定义弹性效果,可以传入bounceableProps。
    bouncesiOS
    类型boolean·默认值true
    启用 iOS 弹性效果。
    childreniOSAndroidHarmony
    类型ReactNode
    列表的子元素。
    classNameiOSAndroidHarmony
    类型string
    类名
    crossAxisGapiOSAndroidHarmony
    类型number·默认值0
    指定列表中组件的交叉轴间距。
    debugLogiOSAndroidHarmony
    类型boolean·默认值false
    是否开启 refresh / bounce 生命周期关键日志。
    enableRTLiOSAndroidHarmony
    类型boolean·默认值false
    是否在 RTL 模式下镜像水平回弹方向。
    enableScrolliOSAndroidHarmony
    类型boolean·默认值true
    启用垂直滚动。
    enableScrollBariOSAndroidHarmony
    类型boolean·默认值false
    启用滚动条。
    enableScrollMonitoriOSAndroidHarmony
    类型boolean·默认值false
    启用滚动监控。
    exposureIDiOSAndroidHarmony
    类型string
    全局曝光的曝光ID
    exposureSceneiOSAndroidHarmony
    类型string
    全局曝光的曝光场景
    initialScrollIndexiOSAndroidHarmony
    类型number·默认值0
    列表在初始加载时自动滚动到的位置。
    iosEnableSimultaneousTouchiOS
    类型boolean·默认值true
    强制触摸事件发送到列表。
    iosScrollsToTopiOS
    类型boolean·默认值true
    点击 iOS 状态栏时是否需要回顶。
    itemSnapiOSAndroidHarmony
    类型{factor: number, offset: number}
    分页滚动
    listIdiOSAndroidHarmony
    类型string
    列表的 ID。
    listMaxSizeiOSAndroidHarmony
    类型number
    单位是 px。设置容器的自适应高度限制。当子内容高度小于此值时,容器高度自动适应内容;当子内容超过此值时,容器高度将固定为该值并显示滚动条。
    listPropsiOSAndroidHarmony
    类型ListProps
    Original list props to spread directly onto the underlying list element. This is an escape hatch for platform or engine attributes that are not yet covered by ListProps.
    listTypeiOSAndroidHarmony
    类型single | flow | waterfall
    列表的布局类型。
    loadMoreFooteriOSAndroid
    类型ReactElement<any, string | JSXElementConstructor<any>>·默认值false
    列表的加载更多区域。
    lowerThresholdItemCountiOSAndroidHarmony
    类型number·默认值0
    下边缘触发 onScrollToLower 事件的条目阈值。
    main-thread:gestureiOSAndroid
    类型BaseGesture<BaseGestureConfig, GestureChangeEvent>
    如果您想使用手势,请在此处传递。
    mainAxisGapiOSAndroidHarmony
    类型number·默认值0
    指定列表中组件的主要轴间距。
    nameiOSAndroidHarmony
    类型string
    列表的名称。
    needLayoutCompleteInfoiOSAndroidHarmony
    类型boolean·默认值false
    输出布局完成的详细信息。
    noMoreDataFooteriOSAndroid
    类型ReactElement<any, string | JSXElementConstructor<any>>·默认值false
    当没有更多数据要插入并且调用hasMoreData方法时,loadMoreFooter将被切换为noMoreDataFooter。
    onUIAppeariOSAndroidHarmony
    类型(e: CommonEvent) => void
    UI 的曝光事件。
    onUIDisappeariOSAndroidHarmony
    类型(e: CommonEvent) => void
    UI 的消失事件。
    preloadBufferCountiOSAndroidHarmony
    类型number·默认值0
    控制列表在屏上节点之外,提前加载节点的个数。在 listType 为 waterfall 时不生效。
    ref
    类型ForwardedRef<FeedListRef>
    refreshOptionsiOSAndroid
    类型boolean | RefreshProps·默认值false
    接受 true 使用默认选项。传入 RefreshProps 可以自定义刷新效果,或通过 mode: 'native' 选择原生刷新实现。
    scrollEventThrottleiOSAndroidHarmony
    类型number·默认值200
    列表触发滚动事件回调的时间间隔(毫秒)。
    scrollMonitorTagiOSAndroidHarmony
    类型string·默认值false
    滚动监控的标签。
    scrollOrientationiOSAndroidHarmony
    类型vertical | horizontal·默认值'vertical'
    设置为 'vertical' 为垂直滚动,设置为 'horizontal' 为水平滚动。
    scrollPropagationBehavioriOSAndroid
    类型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.
    shouldRequestStateRestoreiOSAndroidHarmony
    类型boolean·默认值false
    元素层复用的生命周期。解决 UI 层复用状态混乱的问题。
    showVisibleItemInfoInScrollEventiOSAndroidHarmony
    类型boolean·默认值false
    控制是否在绑定滚动事件中包含附加单元格信息。
    spanCountiOSAndroidHarmony
    类型number·默认值true
    列表的列数。
    stickyOffsetiOSAndroidHarmony
    类型number·默认值0
    粘性位置与列表顶部或底部的偏移量。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    temporaryAndroidEnableOverflowAndroid
    类型boolean·默认值true
    是否开启 android 平台层 list overflow
    temporaryBlockScrollClassiOS
    类型string·默认值'BDXLynxViewPager'
    当 scrollPropagationBehavior 设为 'preventPropagate' 时,被阻止滚动的容器的具体类名。'preventPropagate' 在 iOS 上暂时需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。 此为临时属性,将在新版 Lynx SDK 中废弃。
    temporaryBlockScrollTagiOS
    类型number·默认值0
    用于指定当 scrollPropagationBehavior 设为 'preventPropagate' 时被阻止滚动的原生容器标签(对应 UIView 的 Tag 属性)。该值需由原生容器提供方指定,且 'preventPropagate' 在 iOS 上暂时需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。 此为临时属性,将在新版 Lynx SDK 中废弃。
    upperThresholdItemCountiOSAndroidHarmony
    类型number·默认值0
    上边缘触发 onScrollToUpper 事件的条目阈值。
    useRefactorListiOSAndroidHarmony
    类型boolean·默认值true
    使用重构后的列表。
    Events
    catchLongPressiOSAndroidHarmony
    类型(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    与 onLongPress 相同,但会阻止事件冒泡。
    catchTouchCanceliOSAndroidHarmony
    类型(e: TouchEvent) => void
    与 onTouchCancel 相同,但会阻止事件冒泡。
    catchTouchEndiOSAndroidHarmony
    类型(e: TouchEvent) => void
    与 onTouchEnd 相同,但会阻止事件冒泡。
    catchTouchMoveiOSAndroidHarmony
    类型(e: TouchEvent) => void
    与 onTouchMove 相同,但会阻止事件冒泡。
    catchTouchStartiOSAndroidHarmony
    类型(e: TouchEvent) => void
    与 onTouchStart 相同,但会阻止事件冒泡。
    debugLogLeveliOSAndroidHarmony
    类型0 | 1 | 2 | 3·默认值0
    显示调试日志。0:无,1:错误,2:信息,3:详细
    onLayoutChangeiOSAndroidHarmony
    类型(e: EventHandler<LayoutChangeDetailEvent<Target>> | undefined) => void
    当 UI 视口大小改变时发送。
    onLayoutCompleteiOSAndroidHarmony
    类型(e: {detail: LayoutCompleteEventDetail}) => void
    当列表的条目更新并且此更新过程已完成时发送。
    onLongPressiOSAndroidHarmony
    类型(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    当触摸点在 UI 上按住一段时间后发送。
    onScrolliOSAndroid
    类型(e: ScrollEvent) => void
    滚动时触发。
    onScrollEndiOSAndroid
    类型(e: ScrollEndEvent) => void·默认值undefined
    滚动停止时触发。
    onScrollStateChangeiOSAndroidHarmony
    类型(e: ListScrollStateChangeEvent) => void
    滚动状态变更。
    onScrollToLoweriOSAndroid
    类型(e: ScrollToLowerEvent) => void·默认值undefined
    滚动到底部时触发。
    onScrollToUpperiOSAndroid
    类型(e: ScrollToUpperEvent) => void·默认值undefined
    滚动到顶部时触发。
    onSnapToItemiOSAndroidHarmony
    类型(e: ListSnapEvent) => void
    当列表限位滚动到一个条目时发送。
    onTapiOSAndroidHarmony
    类型(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    当触摸点在 UI 上轻触时发送。
    onTouchCanceliOSAndroidHarmony
    类型(e: TouchEvent) => void
    当触摸事件在完成前被中断或取消时发送。
    onTouchEndiOSAndroidHarmony
    类型(e: TouchEvent) => void
    当触摸点从 UI 上移除时发送。
    onTouchMoveiOSAndroidHarmony
    类型(e: TouchEvent) => void
    当触摸点在 UI 上移动时发送。
    onTouchStartiOSAndroidHarmony
    类型(e: TouchEvent) => void
    当触摸点放置在 UI 上时发送。
    onWheel
    类型(e: CommonEvent) => void
    当列表触发滚轮事件时发送。

    FeedListRef

    autoScrolliOSAndroidHarmony
    类型(rate: px | rpx | ppx | rem | em | vw | vh, start: boolean, autoStop: boolean) => void
    自动滚动列表到指定位置和偏移量。
    changeHasMoreStatusiOSAndroid
    类型(hasMore: boolean) => void
    当没有更多数据要插入时,调用此方法将loadMoreFooter替换为noMoreDataFooter。
    finishRefreshiOSAndroid
    类型() => void
    在startRefresh事件之后,调用此方法将结束刷新状态并使刷新Header进行反弹。
    getVisibleCellsiOSAndroidHarmony
    类型(success?: (res: unknown) => void, fail?: (res: unknown) => void) => void
    将列表滚动到指定位置和偏移量。
    scrollIntoIDiOSAndroidHarmony
    类型(animated: boolean, alignTo: top | bottom | middle | none, listItemID: string, id: string, index: number, offset?: number, success?: (res: unknown) => void, fail?: (res: unknown) => void) => void
    扩展标准列表的 scrollTo 方法。此方法使用 worklet 并支持像 scroll-view 方法的参数 id。由于列表是懒加载的,此方法中需要索引以找到 id 组件的位置。需要 useRefactorList={true}。
    scrollToiOSAndroidHarmony
    类型(animated: boolean, alignTo: top | bottom | middle | none, index?: number, offset?: number, success?: (res: unknown) => void, fail?: (res: unknown) => void) => void
    滚动列表到指定位置和偏移量。
    startRefreshiOSAndroid
    类型() => void
    当enable-refresh为true时,调用此函数会使刷新Header全露并触发startRefresh事件。之后,刷新Header附加到List的顶部。

    辅助类型

    BounceableBasicProps

    alwaysBouncing
    类型boolean
    enableBounceEventInFling
    类型boolean
    enableBounces
    类型boolean
    endBounceTriggerDistance
    类型number
    estimatedHeight
    类型number
    estimatedWidth
    类型number
    lowerBounceItem
    类型ReactElement<any, string | JSXElementConstructor<any>>
    onScrollToBounces
    类型(e: {direction: upper | lower}) => void
    singleSidedBounce
    类型none | upper | lower | both | iOSBounces
    startBounceTriggerDistance
    类型number
    upperBounceItem
    类型ReactElement<any, string | JSXElementConstructor<any>>
    validAnimationVersion
    类型boolean

    RefreshProps

    enableRefresh
    类型boolean
    headerContent
    类型any
    mode
    类型native | hook·默认值'hook'
    Select the pull-to-refresh implementation. hook uses useRefreshAndBounce; native uses the platform <refresh> element. Native mode only supports vertical lists.
    onHeaderReleased
    类型(e: {headerSize: number, offset: number}) => void
    onRefreshOffsetChange
    类型(e: {headerSize: number, isDragging: boolean, offset: number}) => void
    onRefreshStateChange
    类型(e: {state: number}) => void
    onStartRefresh
    类型(e: {triggeredBy: startRefresh | drag}) => void
    validAnimationVersion
    类型boolean

    UseRefreshAndBounceReturn

    finishRefresh
    类型() => void
    main-thread:onLayoutChange
    类型(e: LayoutChangeEvent) => void
    main-thread:onLayoutComplete
    类型() => void
    main-thread:onScroll
    类型(e: ScrollEvent) => void
    onLowerDisexposure
    类型() => void
    onLowerExposure
    类型() => void
    onRefreshHeaderLayoutUpdated
    类型(e: LayoutChangeEvent) => void
    onUpperDisexposure
    类型() => void
    onUpperExposure
    类型() => void
    refreshAndBounceGesture
    类型NativeGesture
    startRefreshMethod
    类型() => void

    如何使用 refreshOptions

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

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

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

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

    事件

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

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

    除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。