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-view.md.
lynx-ui logo
lynx-ui
  • 简体中文
  • ScrollView

    一个适用于 ReactLynx 的滚动容器组件,提供滚动基础能力和回弹处理。
    • 利用 LazyComponent内置懒加载能力的滚动容器,用于优化首屏耗时;
    • 新版 scroll-view 架构在 Android、iOS 和 Harmony 上提供原生 bounces 能力。
    Info

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

    使用指南
    如何理解 `bounceableOptions`

    基础用法

    使用<ScrollView>提供滚动能力

    结构

    <ScrollView>
      {/* Your content */}
    </ScrollView>

    组件 API

    ScrollView

    Properties
    androidTouchSlopAndroid
    类型default | paging
    Android 触摸识别模式,当处于支持 'paging' 模式的元件中时,需要开启 'paging' 模式。
    bounceableiOSAndroid
    类型boolean
    启用弹性效果
    bounceableOptionsiOSAndroid
    类型boolean | BounceableBasicProps·默认值{ enableBounces: true, singleSidedBounce: "iOSBounces" },
    弹性效果的参数
    childreniOSAndroid
    类型ReactNode
    scroll-view 的子元素。
    classNameiOSAndroidHarmony
    类型string
    类名
    debugLogiOSAndroidHarmony
    类型boolean·默认值false
    显示回弹交互的调试日志。
    enableNewArchiOSAndroidHarmony
    类型boolean·默认值true on Lynx SDK >= 4.3; false otherwise
    启用原生 <scroll-view> 新架构。启用后,bounceableOptions 会在 Android、iOS 和 Harmony 上使用原生回弹。Lynx SDK 4.3 及以上版本默认为 true,更早版本默认为 false。
    enableRTLiOSAndroidHarmony
    类型boolean·默认值false
    是否在 RTL 模式下镜像水平回弹方向。
    enableScrolliOSAndroidHarmony
    类型boolean·默认值true
    启用滚动。
    enableScrollMonitoriOSAndroidHarmony
    类型boolean·默认值false
    启用滚动监控。
    estimatedItemStyleiOSAndroid
    类型CSSProperties
    需要设置 items 的预计高度和宽度。
    experimentalNestedScrollBackwardHarmony
    类型selfOnly | selfFirst | parentFirst | parallel
    适配 Harmony 的嵌套滚动行为。'selfOnly' 表示只自身滚动,不与父组件联动。'selfFirst' 表示自身先滚动,自身滚动到边界以后父组件滚动。'parentFirst' 表示父组件先滚动,父组件滚动到边界以后自身滚动。'parallel' 表示自身和父组件同时滚动。
    experimentalNestedScrollForwardHarmony
    类型selfOnly | selfFirst | parentFirst | parallel
    适配 Harmony 的嵌套滚动行为。'selfOnly' 表示只自身滚动,不与父组件联动。'selfFirst' 表示自身先滚动,自身滚动到边界以后父组件滚动。'parentFirst' 表示父组件先滚动,父组件滚动到边界以后自身滚动。'parallel' 表示自身和父组件同时滚动。
    exposureBottomiOSAndroid
    类型string·默认值'10px'
    曝光屏幕下方边距
    exposureIDiOSAndroidHarmony
    类型string
    用于全局曝光的 exposure-id
    exposureLeftiOSAndroid
    类型string·默认值'10px'
    曝光屏幕左侧边距
    exposureRightiOSAndroid
    类型string·默认值'10px'
    曝光屏幕右侧边距
    exposureSceneiOSAndroidHarmony
    类型string
    用于全局曝光的 exposure-scene
    exposureTopiOSAndroid
    类型string·默认值'10px'
    曝光屏幕上方边距
    firstScreenItemCountiOSAndroid
    类型number·默认值1
    懒加载时预计的第一页项数。剩余的子元素会基于曝光状态完成渲染。当此预估较小时,可能会导致第一屏出现空白现象。
    horizontaliOSAndroid
    类型boolean
    水平滚动。
    iOSBouncesiOSAndroid
    类型boolean·默认值true
    开启iOS上的回弹效果。如果想在安卓上使用,请参考bounceableOption。如果设置了bounceableOption,iOSBounces属性将失效。
    lazyiOSAndroid
    类型boolean·默认值true
    启用懒渲染。只有当用户滚动到可见区域时,才会渲染 items,从而减少初始加载时间和内存使用。
    lazyOptionsiOSAndroid
    类型LazyOptions·默认值true
    启用懒渲染。只有当用户滚动到可见区域时,才会渲染 items,从而减少初始加载时间和内存使用。
    main-thread:gestureiOSAndroid
    类型BaseGesture<BaseGestureConfig, GestureChangeEvent>
    如果想使用 gesture API,请传入该属性。
    onUIAppeariOSAndroidHarmony
    类型(e: CommonEvent) => void
    UI 的曝光事件。
    onUIDisappeariOSAndroidHarmony
    类型(e: CommonEvent) => void
    UI 的消失事件。
    sceneiOSAndroid
    类型string
    用于标记懒加载的曝光时机。请确保页面中唯一。
    scrollMonitorTagiOSAndroidHarmony
    类型string·默认值false
    滚动监控的标签。
    scrollOrientationiOSAndroidHarmony
    类型vertical | horizontal·默认值'vertical'
    设置为 'vertical' 为垂直滚动,设置为 'horizontal' 为水平滚动。
    scrollPropagationBehavioriOSAndroid
    类型ScrollPropagationBehaviorOption·默认值'native'
    控制滚动事件是否向父级容器传递。'preventPropagate' 在 iOS 上暂时需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。 Currently, this property has limitations because its full functionality depends on a higher native SDK version: on iOS, propagate only works if both the parent and this component are set to propagate and useRefactorList={true} does not support 'propagate'. On Android, preventPropagate only functions when the parent is x-swiper or x-viewpager-ng.
    scrollviewIdiOSAndroid
    类型string·默认值"scrollview"
    滚动视图的id。
    stickyiOSAndroid
    类型ReactElement<any, string | JSXElementConstructor<any>>
    粘性元素,设计用于 Tabs。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    temporaryBlockScrollClassiOS
    类型string·默认值'BDXLynxViewPager'
    当 scrollPropagationBehavior 设为 'preventPropagate' 时,被阻止滚动的容器的具体类名。'preventPropagate' 需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。 This is a temporary props and will be deprecated on new Lynx SDK version.
    temporaryBlockScrollTagiOS
    类型number·默认值0
    用于指定当 scrollPropagationBehavior 设为 'preventPropagate' 时被阻止滚动的原生容器标签(对应 UIView 的 Tag 属性)。该值需由原生容器提供方指定,且 'preventPropagate' 必须与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。 This is a temporary props and will be deprecated on new Lynx SDK version.
    temporaryNestedScrollAndroid
    类型boolean
    仅 Android 生效的临时开关,用于控制嵌套滚动冲突;映射到原生属性 'enable-nested-scroll'。Android上默认开启。
    testingiOSAndroid
    类型boolean
    测试模式
    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 相同,但会阻止事件冒泡。
    onContentSizeChangeiOSAndroid
    类型(res: {detail: {scrollHeight: number, scrollWidth: number}}) => void
    滚动内容变化时触发。
    onLayoutChangeiOSAndroidHarmony
    类型(e: EventHandler<LayoutChangeDetailEvent<Target>> | undefined) => void
    当 UI 视口大小改变时发送。
    onLongPressiOSAndroidHarmony
    类型(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    当触摸点在 UI 上按住一段时间后发送。
    onScrolliOSAndroid
    类型(e: ScrollEvent) => void
    滚动时触发。
    onScrollEndiOSAndroid
    类型(e: ScrollEndEvent) => void·默认值undefined
    滚动停止时触发。
    onScrollToLoweriOSAndroid
    类型(e: ScrollToLowerEvent) => void·默认值undefined
    滚动到底部时触发。
    onScrollToUpperiOSAndroid
    类型(e: ScrollToUpperEvent) => void·默认值undefined
    滚动到顶部时触发。
    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
    当 scroll-view 触发滚轮事件时发送。

    辅助类型

    BounceableBasicProps

    Properties
    alwaysBouncingiOSAndroidHarmony
    类型boolean·默认值true
    当可滚动容器的内容区域小于视口区域时,是否允许容器回弹。
    enableBounceEventInFlingiOSAndroidHarmony
    类型boolean·默认值false
    在快速滑动(fling)时触发回弹效果
    enableBouncesiOSAndroidHarmony
    类型boolean
    是否开启回弹效果
    endBounceTriggerDistanceiOSAndroidHarmony
    类型number·默认值0
    触发 scrollToBounces 事件时,下部回弹的阈值距离(单位:px)
    estimatedHeightiOSAndroidHarmony
    类型number
    单位:px。可选的回弹效果尺寸提示。在列表或 <list/> 中使用时推荐设置。
    estimatedWidthiOSAndroidHarmony
    类型number
    单位:px。可选的回弹效果尺寸提示。在列表或 <list/> 中使用时推荐设置。
    lowerBounceItemiOSAndroidHarmony
    类型any
    下部回弹视图的内容,将在下部回弹效果期间显示。
    singleSidedBounceiOSAndroidHarmony
    类型upper | lower | both | iOSBounces | none·默认值'both'
    回弹效果的方向。'both' 表示两端都回弹,'none' 表示禁用回弹,'upper'/'lower' 表示只在上端或下端回弹。
    startBounceTriggerDistanceiOSAndroidHarmony
    类型number·默认值0
    触发 scrollToBounces 事件时,上部回弹的阈值距离(单位:px)
    upperBounceItemiOSAndroidHarmony
    类型any
    上部回弹视图的内容,将在上部回弹效果期间显示。
    validAnimationVersioniOSAndroidHarmony
    类型boolean·默认值false
    requestAnimationFrame 在 lynx 2.15.2 以下版本中不起作用。当版本高于 2.15.2 时,应打开此开关。
    Events
    onScrollToBouncesiOSAndroidHarmony
    类型(e: ScrollToBouncesInfo) => void·默认值0
    当触发回弹效果并且回弹距离在上侧或下侧大于 startBounceDistance 或 endBounceDistance 时,将触发 scrollToBounces 事件。

    ScrollToBouncesInfo

    direction
    类型upper | lower

    BounceHandlers

    main-thread:bindlayoutchange
    类型(event: CommonEvent) => void
    main-thread:bindscroll
    类型(event: ScrollEvent) => void
    main-thread:bindtouchend
    类型() => void
    main-thread:bindtouchmove
    类型(event: TouchEvent) => void
    main-thread:bindtouchstart
    类型(event: TouchEvent) => void
    onLowerDisexposure
    类型(_event: CommonEvent) => void
    onLowerExposure
    类型(_event: CommonEvent) => void
    onUpperDisexposure
    类型(_event: CommonEvent) => void
    onUpperExposure
    类型(_event: CommonEvent) => void

    属性解析

    让我们来看看 useBounces 是如何实现的。这个 hooks 能绑定在任何一个可滚动容器上。

    输入和输出

    首先让我们把这个 hooks 当作一个黑盒,这个盒子会接收组件设置,然后返回一系列能够响应滚动容器事件的操作方法:

    • 输入:options

    • id: 可滚动容器的 id。我们认为这个 id 是必须设置的,这是为了避免同一页面下存在相同的可滚动容器之间的混淆。

    • scrollOrientation: 可滚动容器的方向。可以为横向或纵向。

    • bounceableOptions: 对 hook 的额外设置属性,包括这一些子项:

      • enableBounces: 是否开启弹性效果。
      • startBounceTriggerDistance/endBounceTriggerDistance: onScrollToBounces 的设置,只有当弹性效果超出该阈值,这个事件才会触发。一般用于 ”右滑跳转“ 这种场景。
      • enableBounceEventInFling: 是否在滚动容器的惯性滚动过程中触发弹性效果。
      • upperBounceItem/lowerBounceItem: 出现在弹性区域的内容。
      • alwaysBouncing: 在滚动容器实际不可滚动时是否也能够出现弹性效果。
      • singleSidedBounce: 让弹性效果只在单端生效。
      • onScrollToBounces: 在弹性效果超出指定阈值后触发事件,让小幅度的回弹效果不触发这个事件。
    • 输出:一系列用于绑定在滚动容器上的函数。

      • main-thread:bindtouchstart/main-thread:bindtouchend/main-thread:bindtouchmove: 用于接收滚动容器的触摸事件并进行处理。
      • main-thread:bindlayoutchange: 用于获取滚动容器的实际宽高。
      • main-thread:bindscroll/main-thread:bindscrollend: 用于接收滚动容器的滚动事件并进行处理。
      • onUpperExposure/onUpperDisexposure/onLowerExposure/onLowerDisexposure: 用于处理滚动容器是否处于边界,弹性效果仅出现在滚动容器触边的情况下。

    如何形成滚动

    启用 enableNewArch 后,ScrollView 会在 Android、iOS 和 Harmony 上使用原生回弹,同时保留自定义回弹内容和 onScrollToBounces 阈值回调。

    在旧架构中,非 iOSBounces 模式使用 MTS 调用 transform 来模拟弹性效果。

    1. 使用 id,通过 lynx.querySelector 找到节点。
    lynx.querySelector(`#${containerID}`)
    1. 从滚动曲线函数中获取 touchmove 所对应的滚动曲线,然后进行相应 transform。

    useBounces 将滚动曲线分为了三段:

    1. 响应 touchmove 的橡皮筋效果
    2. 惯性滚动效果
    3. 回弹效果

    bounceableOptions 的各属性如何使用?

    enableNewArch

    Lynx SDK 4.3 及以上版本中,ScrollView 默认启用原生 <scroll-view> 新架构;更早的版本默认保留旧架构。可以显式设置 enableNewArch,覆盖这一基于 SDK 版本的默认行为。

    onScrollToBounces 事件和 startBounceTriggerDistance/endBounceTriggerDistance

    该事件只在完成回弹效果之后触发,这代表着它需要两个前提条件:

    1. touchEnd 时滚动容器处于顶部回弹区域或底部回弹区域,不在正常区域。这保证了回弹可以触发,需要在这个事件里完成的效果都应在真实的回弹效果触发之后。如果用户拖动到回弹区域,又再次拖拽至非回弹区域,这意味着对 onScrollToBounces 事件的取消,这个事件不应被触发。
    2. 当前这个回弹效果已经结束,滚动容器重新处于正常滚动区域边缘。

    为了不让微小的回弹效果也能触发这个事件,导致事件触发过于灵敏,我们为它添加了回弹距离阈值,也就是 startBounceTriggerDistance/endBounceTriggerDistance。 只有当最远的回弹距离超过设定的阈值时,这次回弹结束时才会触发 onScrollToBounces 事件。

    enableBounceEventInFling

    滚动容器在正常滚动区域发生触摸滑动时,如果在触摸结束时滚动容器的速度过大,就会进入惯性滚动阶段。在这个惯性滚动阶段中,滚动容器也可能中途滚动到边缘。这种情况下,我们可以让这个惯性滚动的剩余速度直接触发回弹效果,enableBounceEventInFling属性将为你触发这种回弹模式,这也是默认的回弹模式。考虑到有一些场景可能需求更明确的回弹交互 —— 回弹效果不能发生在一次惯性滚动中,而必须由一次触摸滑动行为触发,我们将这个行为设定成了可配置项。

    upperBounceItem/lowerBounceItem 会出现在哪里?

    它们只会出现在回弹区域。一旦弹性效果触发,用户将能看到你在这里渲染的节点。它们不是必须设置的,在未设置的情况下,回弹区域将展示滚动容器下层渲染的内容,因为滚动容器仍然被 translate,离开了原本的位置。

    alwaysBouncing

    在一些情况下,滚动容器本身可能并不能滚动。开启这个属性能让回弹效果的边缘检测仍然生效,这意味着即使滚动容器无法真正发生滚动行为,它仍然能够出现回弹效果。

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