ScrollCoordinator
用于 ReactLynx 的无样式滚动协调组件,支持可折叠头部与嵌套列表、滚动视图、分页内容联动。Info
你可以查看源码来了解它的运行原理,也欢迎大家提 PR 来丰富其能力。
基础用法
协调可折叠头部、常驻工具栏和垂直列表的滚动。
示例
刷新协调
为整个协调器添加下拉刷新,并通过命令开始和结束刷新。
刷新页面
让协调器内每个分页 Feed 拥有独立的下拉刷新生命周期。
ViewPager
让横向分页的多个垂直列表共享可折叠头部和工具栏。
ViewPager 列表
在同一个协调滚动区域内同步标签栏、分页器和嵌套列表。
结构
组件 API
ScrollCoordinator
Coordinates a collapsible header with nested vertical lists or scroll views.
bouncesiOS
Enable bounce on supported platforms. Outer refresh always enables it unless popupOptions disables it.
classNameiOSAndroidHarmony
类名
coordinatorPropsiOSAndroid
Native properties passed explicitly to the coordinator. Managed properties take precedence.
enableScrolliOSAndroid
Enable vertical coordinator scrolling.
granularityiOSAndroid
Offset event granularity as a fraction of the collapse range. Also sets the sticky threshold.
headerOverSlotiOSAndroid
Place the overflowing header above the slot.
headersiOSAndroid
Collapsible header content.
idiOSAndroid
Optional native coordinator ID. Imperative methods use instance-local node refs.
main-thread:gestureiOSAndroid
Native gesture attached to the coordinator.
main-thread:onOffsetChangeiOSAndroid
Header offset callback on the main thread. Pass a function with the 'main thread' directive.
onLeaveStickyiOSAndroid
Called once when the header leaves the sticky threshold.
onOffsetChangeiOSAndroid
Header offset and total collapse range, in px.
onStickyiOSAndroid
Called once when the header reaches the sticky threshold.
popupOptionsiOSAndroid
Native host popup integration for hosts that support half-to-full-screen expansion.
refreshInSlotiOSAndroid
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
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
Show the coordinator scrollbar on supported platforms.
scrollWithNativeAndroid
Participate as a nested scrolling child of a native Android container.
slotiOSAndroid
Content below the header, typically a vertical List, ScrollView, or ViewPager of lists.
styleiOSAndroidHarmony
样式
toolbariOSAndroid
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
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
Scroll to an element inside headers, measured relative to this instance's header.
scrollToiOSAndroid
Set the header offset. The native coordinator clamps it to the scrollable range.
scrollToStickyiOSAndroid
Collapse the header to its sticky position.
scrollToTopiOSAndroid
Expand the header. Does not reset the nested list's own scroll position.
startRefreshiOSAndroid
Start the outer refresh through its native node. Requires enableRefresh.
onStartRefresh reports triggeredBy: 'startRefresh'. Does not control slot refresh instances.
辅助类型
ScrollCoordinatorOffset
heightiOSAndroidHarmony
The absolute value of the scrollable distance (header height - toolbar height), in px
offsetiOSAndroidHarmony
The absolute value of the header scroll offset, in px
ScrollCoordinatorRefreshOptions
Native refresh options with the same callback shapes as FeedList.
enableRefreshiOSAndroid
Allow pull gestures and startRefresh() to start the outer refresh.
Toggle this flag to preserve the mounted content and its scroll position.
headerContentiOSAndroid
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
The native header was released. Reports the latest offset and measured height in px.
onRefreshOffsetChangeiOSAndroid
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
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
Start loading data. Always call ref.finishRefresh() when the request settles.
Returning a Promise does not automatically end the refresh.