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/scroll-coordinator.md.
lynx-ui logo
lynx-ui
  • 简体中文
  • ScrollCoordinator

    用于 ReactLynx 的无样式滚动协调组件,支持可折叠头部与嵌套列表、滚动视图、分页内容联动。
    Info

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

    基础用法

    协调可折叠头部、常驻工具栏和垂直列表的滚动。

    示例

    刷新协调

    为整个协调器添加下拉刷新,并通过命令开始和结束刷新。

    刷新页面

    让协调器内每个分页 Feed 拥有独立的下拉刷新生命周期。

    ViewPager

    让横向分页的多个垂直列表共享可折叠头部和工具栏。

    ViewPager 列表

    在同一个协调滚动区域内同步标签栏、分页器和嵌套列表。

    结构

    <ScrollCoordinator headers={<Header />} slot={<Content />} />

    组件 API

    ScrollCoordinator

    Coordinates a collapsible header with nested vertical lists or scroll views.

    bouncesiOS
    类型boolean·默认值false
    Enable bounce on supported platforms. Outer refresh always enables it unless popupOptions disables it.
    classNameiOSAndroidHarmony
    类型string
    类名
    coordinatorPropsiOSAndroid
    类型Omit<ScrollCoordinatorProps, ref | children | id | style | className>
    Native properties passed explicitly to the coordinator. Managed properties take precedence.
    enableScrolliOSAndroid
    类型boolean·默认值true
    Enable vertical coordinator scrolling.
    granularityiOSAndroid
    类型number·默认值0.01
    Offset event granularity as a fraction of the collapse range. Also sets the sticky threshold.
    headerOverSlotiOSAndroid
    类型boolean·默认值false
    Place the overflowing header above the slot.
    headersiOSAndroid
    类型ReactNode
    Collapsible header content.
    idiOSAndroid
    类型string
    Optional native coordinator ID. Imperative methods use instance-local node refs.
    main-thread:gestureiOSAndroid
    类型BaseGesture<BaseGestureConfig, GestureChangeEvent>
    Native gesture attached to the coordinator.
    main-thread:onOffsetChangeiOSAndroid
    类型(event: ScrollCoordinatorOffset) => void
    Header offset callback on the main thread. Pass a function with the 'main thread' directive.
    onLeaveStickyiOSAndroid
    类型() => void
    Called once when the header leaves the sticky threshold.
    onOffsetChangeiOSAndroid
    类型(event: ScrollCoordinatorOffset) => void
    Header offset and total collapse range, in px.
    onStickyiOSAndroid
    类型() => void
    Called once when the header reaches the sticky threshold.
    popupOptionsiOSAndroid
    类型{enableHalfToFullScreen: boolean, name: string}
    Native host popup integration for hosts that support half-to-full-screen expansion.
    refreshInSlotiOSAndroid
    类型boolean·默认值false
    Use independent refresh elements inside the slot. Each nested refresh must finish its own refresh through its ref; finishRefresh only affects the outer wrapper.
    refreshOptionsiOSAndroid
    类型false | ScrollCoordinatorRefreshOptions·默认值false
    Configure outer native refresh. Enabled outer refresh takes precedence over refreshInSlot. Providing an options object mounts the refresh wrapper, even while enableRefresh is false. className and style apply to this wrapper; otherwise they apply to the native coordinator. No implementation mode is required.
    scrollBarEnableiOSAndroid
    类型boolean·默认值false
    Show the coordinator scrollbar on supported platforms.
    scrollWithNativeAndroid
    类型boolean·默认值false
    Participate as a nested scrolling child of a native Android container.
    slotiOSAndroid
    类型ReactNode
    Content below the header, typically a vertical List, ScrollView, or ViewPager of lists.
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    toolbariOSAndroid
    类型ReactNode
    Persistent toolbar. Its height is subtracted from the header's collapse range.

    基于状态的样式与渲染

    该组件通过以下一种或两种方式暴露运行时状态。下表仅展示每个状态实际支持的方式:

    • UI variant class:支持时,对应组件节点会动态加上 ui-<state> 形式的类名,可用 .ui-<state> { ... } 选择器定制样式;
    • Render-prop 字段:支持时,当 children 传入函数,状态会以 children({ <state>: boolean, ... }) 的形式作为参数传入,便于在运行时做条件渲染。

    UI variants applied by ScrollCoordinator.

    类名说明
    ui-sticky头部折叠时,应用于协调器和外层刷新容器。

    ScrollCoordinatorRef

    finishRefreshiOSAndroid
    类型() => void
    End the outer refresh, including after a failed request. An existing refresh can still finish after enableRefresh becomes false. Does not reset list offsets.
    scrollIntoViewiOSAndroid
    类型(id: string, animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void
    Scroll to an element inside headers, measured relative to this instance's header.
    scrollToiOSAndroid
    类型(offset: px | rpx, animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void
    Set the header offset. The native coordinator clamps it to the scrollable range.
    scrollToStickyiOSAndroid
    类型(animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void
    Collapse the header to its sticky position.
    scrollToTopiOSAndroid
    类型(animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void
    Expand the header. Does not reset the nested list's own scroll position.
    startRefreshiOSAndroid
    类型() => void
    Start the outer refresh through its native node. Requires enableRefresh. onStartRefresh reports triggeredBy: 'startRefresh'. Does not control slot refresh instances.

    辅助类型

    ScrollCoordinatorOffset

    heightiOSAndroidHarmony
    类型number
    The absolute value of the scrollable distance (header height - toolbar height), in px
    offsetiOSAndroidHarmony
    类型number
    The absolute value of the header scroll offset, in px

    ScrollCoordinatorRefreshOptions

    Native refresh options with the same callback shapes as FeedList.

    enableRefreshiOSAndroid
    类型boolean
    Allow pull gestures and startRefresh() to start the outer refresh. Toggle this flag to preserve the mounted content and its scroll position.
    headerContentiOSAndroid
    类型ReactNode
    Refresh header content. Give it a nonzero height to define the pull threshold. Keep its dimensions stable while refreshing to avoid resetting the native header position.
    onHeaderReleasediOSAndroid
    类型(event: {headerSize: number, offset: number}) => void
    The native header was released. Reports the latest offset and measured height in px.
    onRefreshOffsetChangeiOSAndroid
    类型(event: {headerSize: number, isDragging: boolean, offset: number}) => void
    Pull offset and measured header height in px. The height is zero until layout. Progress is offset / headerSize when headerSize > 0, and may exceed 1.
    onRefreshStateChangeiOSAndroid
    类型(event: {state: number}) => void
    Native state: 0 idle, 1 released past the threshold, 2 refreshing. Event order is platform-dependent. Use isDragging from the offset event for drag state.
    onStartRefreshiOSAndroid
    类型(event: {triggeredBy: startRefresh | drag}) => void
    Start loading data. Always call ref.finishRefresh() when the request settles. Returning a Promise does not automatically end the refresh.
    除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。