跳到主要内容

ScrollView

包装平台 ScrollView 的组件,同时提供与触摸锁定“响应者”系统的集成。

请记住,ScrollView 必须具有限定的高度才能工作,因为它们将高度不限的子组件包含在限定的容器中(通过滚动交互)。为了限定 ScrollView 的高度,可以直接设置视图的高度(不推荐)或确保所有父视图都具有限定的高度。忘记在视图堆栈中传递 {flex: 1} 可能会导致此处出现错误,元素检查器可以快速调试。

尚不支持其他包含的响应者阻止此滚动视图成为响应者。

<ScrollView><FlatList> - 哪个更适合使用?

ScrollView 会一次性渲染所有 React 子组件,但这会带来性能上的缺点。

想象一下,您有一个非常长的项目列表要显示,内容可能多达几屏。同时创建所有 JS 组件和原生视图,其中大部分可能甚至不会显示,这将导致渲染缓慢和内存使用增加。

这就是 FlatList 发挥作用的地方。FlatList 在项目即将出现时惰性渲染它们,并移除滚动到屏幕外的项目以节省内存和处理时间。

如果您想在项目之间渲染分隔符、多列、无限滚动加载或它开箱即用的任何其他功能,FlatList 也非常方便。

示例


参考

属性

View 属性

继承 View 属性


StickyHeaderComponent

一个 React 组件,用于渲染粘性标题,应与 stickyHeaderIndices 一起使用。如果您的粘性标题使用自定义转换(例如,您希望列表具有动画和可隐藏的标题),您可能需要设置此组件。如果未提供组件,则将使用默认的 ScrollViewStickyHeader 组件。

类型
component, element

alwaysBounceHorizontal
iOS

当为 true 时,即使内容小于滚动视图本身,滚动视图在到达末尾时也会水平方向上回弹。

类型默认值
boolhorizontal={true} 时为 true
否则为 false

alwaysBounceVertical
iOS

当为 true 时,即使内容小于滚动视图本身,滚动视图在到达末尾时也会垂直方向上回弹。

类型默认值
boolvertical={true} 时为 false
否则为 true

automaticallyAdjustContentInsets
iOS

控制 iOS 是否应自动调整放置在导航栏或标签栏/工具栏后面的滚动视图的内容边距。

类型默认值
booltrue

automaticallyAdjustKeyboardInsets
iOS

控制键盘大小改变时 ScrollView 是否应自动调整其 contentInsetscrollViewInsets

类型默认值
boolfalse

automaticallyAdjustsScrollIndicatorInsets
iOS

控制 iOS 是否应自动调整滚动指示器边距。请参阅 Apple 关于此属性的文档

类型默认值
booltrue

bounces
iOS

当为 true 时,如果内容在滚动方向轴上大于滚动视图,则滚动视图在到达内容末尾时回弹。当为 false 时,即使 alwaysBounce* 属性为 true,也会禁用所有回弹。

类型默认值
booltrue

bouncesZoom
iOS

当为 true 时,手势可以驱动缩放超出最小/最大范围,并且缩放将在手势结束时动画到最小/最大值,否则缩放将不超过限制。

类型默认值
booltrue

canCancelContentTouches
iOS

当为 false 时,一旦跟踪开始,如果触摸移动,将不会尝试拖动。

类型默认值
booltrue

centerContent
iOS

当为 true 时,当内容小于滚动视图边界时,滚动视图会自动居中内容;当内容大于滚动视图时,此属性无效。

类型默认值
boolfalse

contentContainerStyle

这些样式将应用于包装所有子视图的滚动视图内容容器。示例

return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
类型
View Style

contentInset
iOS

滚动视图内容从滚动视图边缘内嵌的量。

类型默认值
object: {top: number, left: number, bottom: number, right: number}{top: 0, left: 0, bottom: 0, right: 0}

contentInsetAdjustmentBehavior
iOS

此属性指定安全区域边距如何用于修改滚动视图的内容区域。在 iOS 11 及更高版本上可用。

类型默认值
enum('automatic', 'scrollableAxes', 'never', 'always')'never'

contentOffset

用于手动设置起始滚动偏移量。

类型默认值
Point{x: 0, y: 0}

decelerationRate

一个浮点数,它决定了用户抬起手指后滚动视图的减速速度。您还可以使用字符串快捷方式 "normal""fast",它们分别与底层 iOS 设置中的 UIScrollViewDecelerationRateNormalUIScrollViewDecelerationRateFast 相匹配。

  • 'normal' iOS 上为 0.998,Android 上为 0.985。
  • 'fast', iOS 上为 0.99,Android 上为 0.9。
类型默认值
enum('fast', 'normal'), number'normal'

directionalLockEnabled
iOS

当为 true 时,ScrollView 在拖动时将尝试仅锁定垂直或水平滚动。

类型默认值
boolfalse

disableIntervalMomentum

当为 true 时,无论手势速度多快,滚动视图都会停止在下一个索引(相对于释放时的滚动位置)。这可用于当页面小于水平 ScrollView 的宽度或垂直 ScrollView 的高度时进行分页。

类型默认值
boolfalse

disableScrollViewPanResponder

当为 true 时,ScrollView 上的默认 JS 平移响应器被禁用,并且对 ScrollView 内触摸的完全控制权留给其子组件。如果启用了 snapToInterval,这尤其有用,因为它不遵循典型的触摸模式。在没有 snapToInterval 的常规 ScrollView 用例中不要使用此功能,因为它可能导致滚动时发生意外触摸。

类型默认值
boolfalse

endFillColor
Android

有时滚动视图占用的空间超出其内容所填充的空间。在这种情况下,此属性将用颜色填充滚动视图的其余部分,以避免设置背景和创建不必要的过度绘制。这是一种高级优化,在一般情况下不需要。

类型
color

fadingEdgeLength
Android

淡出滚动内容的边缘。

如果值大于 0,淡出边缘将根据当前的滚动方向和位置进行设置,指示是否有更多内容可显示。

类型默认值
number0

horizontal

当为 true 时,滚动视图的子组件水平排列成一行,而不是垂直排列成一列。

类型默认值
boolfalse

indicatorStyle
iOS

滚动指示器的样式。

  • 'default'black 相同。
  • 'black',滚动指示器为 black。此样式适合浅色背景。
  • 'white',滚动指示器为 white。此样式适合深色背景。
类型默认值
enum('default', 'black', 'white')'default'

invertStickyHeaders

粘性标题是否应粘在 ScrollView 的底部而不是顶部。这通常与反转的 ScrollView 一起使用。

类型默认值
boolfalse

keyboardDismissMode

确定键盘是否响应拖动而隐藏。

  • 'none',拖动不会隐藏键盘。
  • 'on-drag',拖动开始时键盘隐藏。

仅限 iOS

  • 'interactive',键盘随着拖动交互式隐藏,并与触摸同步移动,向上拖动会取消隐藏。在 Android 上不支持此功能,其行为与 'none' 相同。
类型默认值
enum('none', 'on-drag')
Android

enum('none', 'on-drag', 'interactive')
iOS
'none'

keyboardShouldPersistTaps

确定轻触后键盘应何时保持可见。

  • 'never' 当键盘弹出时,在聚焦文本输入框之外轻触会隐藏键盘。发生这种情况时,子组件将不会收到轻触事件。
  • 'always',键盘不会自动隐藏,滚动视图也不会捕获轻触事件,但滚动视图的子组件可以捕获轻触事件。
  • 'handled',当轻触事件由滚动视图的子组件处理(或被祖先捕获)时,键盘不会自动隐藏。
  • false, 已弃用, 请改用 'never'
  • true, 已弃用, 请改用 'always'
类型默认值
enum('always', 'never', 'handled', false, true)'never'

maintainVisibleContentPosition

设置后,滚动视图将调整滚动位置,以便当前可见且位于或超出 minIndexForVisible 的第一个子组件不会改变位置。这对于双向加载内容的列表(例如聊天线程)很有用,因为新消息的传入可能会导致滚动位置跳动。0 是一个常见值,但也可以使用其他值(例如 1)来跳过加载指示器或其他不应保持位置的内容。

可选的 autoscrollToTopThreshold 可用于在调整后,如果用户在调整前位于顶部的阈值范围内,则自动将内容滚动到顶部。这对于聊天类应用程序也很有用,您希望看到新消息滚动到位,但如果用户已向上滚动一段距离并且大量滚动会造成干扰,则不应如此。

注意事项 1:在此功能启用时重新排序滚动视图中的元素可能会导致跳动和卡顿。它可以修复,但目前没有计划这样做。目前,请勿重新排序使用此功能的任何 ScrollView 或 List 的内容。

注意事项 2:这在原生代码中使用 contentOffsetframe.origin 来计算可见性。遮挡、转换和其他复杂性将不被考虑在内,无论内容是否“可见”。

类型
object: {minIndexForVisible: number, autoscrollToTopThreshold: number}

maximumZoomScale
iOS

允许的最大缩放比例。

类型默认值
number1.0

minimumZoomScale
iOS

允许的最小缩放比例。

类型默认值
number1.0

nestedScrollEnabled
Android

为 Android API level 21+ 启用嵌套滚动。

类型默认值
boolfalse

onContentSizeChange

当 ScrollView 的可滚动内容视图更改时调用。

处理函数将接收两个参数:内容宽度和内容高度 (contentWidth, contentHeight)

它通过附加到此 ScrollView 渲染的内容容器的 onLayout 处理程序实现。

类型
function

onMomentumScrollBegin

当惯性滚动开始时(ScrollView 开始滑行时发生的滚动)调用。

类型
function

onMomentumScrollEnd

当惯性滚动结束时(ScrollView 滑行停止时发生的滚动)调用。

类型
function

onScroll

滚动时每帧最多触发一次。事件具有以下形状(所有值均为数字)

js
{
nativeEvent: {
contentInset: {bottom, left, right, top},
contentOffset: {x, y},
contentSize: {height, width},
layoutMeasurement: {height, width},
zoomScale
}
}
类型
function

onScrollBeginDrag

当用户开始拖动滚动视图时调用。

类型
function

onScrollEndDrag

当用户停止拖动滚动视图并且它停止或开始滑行时调用。

类型
function

onScrollToTop
iOS

当状态栏被轻触后滚动视图滚动到顶部时触发。

类型
function

overScrollMode
Android

用于覆盖 overScroll 模式的默认值。

可能的值

  • 'auto' - 仅当内容足够大以有意义地滚动时,才允许用户过度滚动此视图。
  • 'always' - 始终允许用户过度滚动此视图。
  • 'never' - 永不允许用户过度滚动此视图。
类型默认值
enum('auto', 'always', 'never')'auto'

pagingEnabled

当为 true 时,滚动视图在滚动时会停止在滚动视图大小的倍数位置。这可用于水平分页。

类型默认值
boolfalse

persistentScrollbar
Android

使滚动条在不使用时不会变成透明。

类型默认值
boolfalse

pinchGestureEnabled
iOS

当为 true 时,ScrollView 允许使用捏合手势进行放大和缩小。

类型默认值
booltrue

refreshControl

一个 RefreshControl 组件,用于为 ScrollView 提供下拉刷新功能。仅适用于垂直 ScrollView(horizontal 属性必须为 false)。

请参阅 RefreshControl

类型
element

removeClippedSubviews

实验性:当为 true 时,屏幕外的子视图(其 overflow 值为 hidden)在屏幕外时会从其原生支持的父视图中移除。这可以提高长列表的滚动性能。

类型默认值
boolfalse

scrollEnabled

当为 false 时,视图无法通过触摸交互滚动。

请注意,视图始终可以通过调用 scrollTo 进行滚动。

类型默认值
booltrue

scrollEventThrottle

限制滚动时滚动事件的触发频率,指定为时间间隔(毫秒)。当响应滚动执行昂贵的工作时,这可能很有用。小于等于 16 的值将禁用节流,无论设备的刷新率如何。

类型默认值
number0

scrollIndicatorInsets
iOS

滚动视图指示器从滚动视图边缘内嵌的量。这通常应设置为与 contentInset 相同的值。

类型默认值
object: {top: number, left: number, bottom: number, right: number}{top: 0, left: 0, bottom: 0, right: 0}

scrollPerfTag
Android

用于在此滚动视图上记录滚动性能的标签。将强制开启惯性事件(请参阅 sendMomentumEvents)。这本身不会执行任何操作,您需要实现自定义原生 FpsListener 才能使其有用。

类型
string

scrollToOverflowEnabled
iOS

当为 true 时,滚动视图可以编程方式滚动超出其内容大小。

类型默认值
boolfalse

scrollsToTop
iOS

当为 true 时,当状态栏被轻触时,滚动视图会滚动到顶部。

类型默认值
booltrue

showsHorizontalScrollIndicator

当为 true 时,显示水平滚动指示器。

类型默认值
booltrue

showsVerticalScrollIndicator

当为 true 时,显示垂直滚动指示器。

类型默认值
booltrue

snapToAlignment

当设置 snapToInterval 时,snapToAlignment 将定义对齐与滚动视图的关系。

可能的值

  • 'start' 将在左侧(水平)或顶部(垂直)对齐。
  • 'center' 将在中心对齐。
  • 'end' 将在右侧(水平)或底部(垂直)对齐。
类型默认值
enum('start', 'center', 'end')'start'

snapToEnd

snapToOffsets 结合使用。默认情况下,列表的末尾算作一个对齐偏移量。将 snapToEnd 设置为 false 以禁用此行为,并允许列表在其末尾和最后一个 snapToOffsets 偏移量之间自由滚动。

类型默认值
booltrue

snapToInterval

设置后,导致滚动视图在 snapToInterval 值的倍数位置停止。这可用于分页通过长度小于滚动视图的子组件。通常与 snapToAlignmentdecelerationRate="fast" 结合使用。覆盖可配置性较低的 pagingEnabled 属性。

类型
number

snapToOffsets

设置后,导致滚动视图在定义的偏移量处停止。这可用于分页通过长度小于滚动视图的各种大小的子组件。通常与 decelerationRate="fast" 结合使用。覆盖可配置性较低的 pagingEnabledsnapToInterval 属性。

类型
array of number

snapToStart

snapToOffsets 结合使用。默认情况下,列表的开头算作一个对齐偏移量。将 snapToStart 设置为 false 以禁用此行为,并允许列表在其开头和第一个 snapToOffsets 偏移量之间自由滚动。

类型默认值
booltrue

stickyHeaderHiddenOnScroll

当设置为 true 时,向下滚动列表时,粘性标题将隐藏;向上滚动时,它将停靠在列表顶部。

类型默认值
boolfalse

stickyHeaderIndices

一个子索引数组,用于确定哪些子组件在滚动时停靠在屏幕顶部。例如,传递 stickyHeaderIndices={[0]} 将导致第一个子组件固定在滚动视图的顶部。您也可以使用 [x,y,z] 使多个项目在顶部时保持粘性。此属性不支持与 horizontal={true} 结合使用。

类型
array of number

zoomScale
iOS

滚动视图内容的当前缩放比例。

类型默认值
number1.0

方法

flashScrollIndicators()

tsx
flashScrollIndicators();

暂时显示滚动指示器。


scrollTo()

tsx
scrollTo(
options?: {x?: number, y?: number, animated?: boolean} | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);

立即或通过平滑动画滚动到给定的 x, y 偏移量。

示例

scrollTo({x: 0, y: 0, animated: true})

注意:这种奇怪的函数签名是由于历史原因,该函数还接受单独的参数作为选项对象的替代方案。由于歧义(y 在 x 之前),此功能已弃用,不应使用。


scrollToEnd()

tsx
scrollToEnd(options?: {animated?: boolean});

如果这是一个垂直 ScrollView,则滚动到底部。如果这是一个水平 ScrollView,则滚动到右侧。

使用 scrollToEnd({animated: true}) 进行平滑动画滚动,使用 scrollToEnd({animated: false}) 进行立即滚动。如果未传递任何选项,animated 默认为 true