跳至主要内容

ScrollView

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

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

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

<ScrollView> 与 <FlatList> - 使用哪一个？

ScrollView 同时渲染其所有 React 子组件，但这会带来性能方面的缺点。

假设您有一个非常长的项目列表要显示，可能包含几个屏幕的内容。同时创建所有 JS 组件和原生视图（其中许多可能甚至不会显示）会导致渲染缓慢并增加内存使用量。

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

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

示例​

参考

属性​

View 属性​

继承 View 属性。

StickyHeaderComponent​

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

类型
组件，元素

alwaysBounceHorizontal
iOS
​

如果为真，则即使内容小于滚动视图本身，滚动视图在到达末尾时也会水平反弹。

类型默认值
布尔值当 horizontal={true} 时为 true
否则为 false

alwaysBounceVertical
iOS
​

如果为真，则即使内容小于滚动视图本身，滚动视图在到达末尾时也会垂直反弹。

类型默认值
布尔值当 vertical={true} 时为 false
否则为 true

automaticallyAdjustContentInsets
iOS
​

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

类型默认值
布尔值true

automaticallyAdjustKeyboardInsets
iOS
​

控制 ScrollView 在键盘更改大小时是否应自动调整其 contentInset 和 scrollViewInsets。

类型默认值
布尔值false

automaticallyAdjustsScrollIndicatorInsets
iOS
​

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

类型默认值
布尔值true

bounces
iOS
​

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

类型默认值
布尔值true

bouncesZoom
iOS
​

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

类型默认值
布尔值true

canCancelContentTouches
iOS
​

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

类型默认值
布尔值true

centerContent
iOS
​

如果为 true，则当内容小于滚动视图边界时，滚动视图会自动居中内容；当内容大于滚动视图时，此属性无效。

类型默认值
布尔值false

contentContainerStyle​

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

return (
  <ScrollView contentContainerStyle={styles.contentContainer}>
  </ScrollView>
);
...
const styles = StyleSheet.create({
  contentContainer: {
    paddingVertical: 20
  }
});
类型
视图样式

contentInset
iOS
​

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

类型默认值
对象：{top: number, left: number, bottom: number, right: number}{top: 0, left: 0, bottom: 0, right: 0}

contentInsetAdjustmentBehavior
iOS
​

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

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

contentOffset​

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

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

decelerationRate​

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

  • 'normal' 在 iOS 上为 0.998，在 Android 上为 0.985。
  • 'fast'，在 iOS 上为 0.99，在 Android 上为 0.9。
类型默认值
枚举('fast', 'normal'), 数字'normal'

directionalLockEnabled
iOS
​

如果为真，则 ScrollView 会尝试在拖动时锁定为仅垂直或水平滚动。

类型默认值
布尔值false

disableIntervalMomentum​

如果为真，则无论手势有多快，滚动视图都会停止在下一个索引（相对于释放时的滚动位置）。当页面小于水平 ScrollView 的宽度或垂直 ScrollView 的高度时，这可用于分页。

类型默认值
布尔值false

disableScrollViewPanResponder​

如果为真，则 ScrollView 上的默认 JS 平移响应者将被禁用，并且 ScrollView 内部的触摸的完全控制权将留给其子组件。如果启用了 snapToInterval，这尤其有用，因为它不遵循典型的触摸模式。在没有 snapToInterval 的常规 ScrollView 使用场景中不要使用此属性，因为它可能会导致在滚动时出现意外触摸。

类型默认值
布尔值false

endFillColor
Android
​

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

类型
颜色

fadingEdgeLength
Android
​

淡出滚动内容的边缘。

如果该值大于 0，则将根据当前滚动方向和位置相应地设置渐变边缘，指示是否有更多内容要显示。

类型默认值
数字0

horizontal​

如果为 true，则滚动视图的子元素将水平排列在一行中，而不是垂直排列在一列中。

类型默认值
布尔值false

indicatorStyle
iOS
​

滚动指示器的样式。

  • 'default' 与 black 相同。
  • 'black'，滚动指示器为 black。此样式适用于浅色背景。
  • 'white'，滚动指示器为 white。此样式适用于深色背景。
类型默认值
枚举('default', 'black', 'white')'default'

invertStickyHeaders​

如果粘性标题应粘在 ScrollView 的底部而不是顶部。这通常与倒置的 ScrollView 一起使用。

类型默认值
布尔值false

keyboardDismissMode​

确定键盘是否会响应拖动而被关闭。

  • 'none'，拖动不会关闭键盘。
  • 'on-drag'，拖动开始时键盘会被关闭。

仅限 iOS

  • 'interactive'，键盘会随着拖动交互式地关闭并与触摸同步移动，向上拖动会取消关闭。在 Android 上，此功能不受支持，并且行为与 'none' 相同。
类型默认值
枚举('none', 'on-drag')
Android
枚举('none', 'on-drag', 'interactive')
iOS
'none'

keyboardShouldPersistTaps​

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

  • 'never' 当键盘处于打开状态时，轻触聚焦文本输入框外部会关闭键盘。发生这种情况时，子元素将不会收到轻触。
  • 'always'，键盘不会自动关闭，并且滚动视图不会捕获轻触，但滚动视图的子元素可以捕获轻触。
  • 'handled'，当滚动视图的子元素处理（或被祖先捕获）轻触时，键盘不会自动关闭。
  • false，已弃用，请使用'never'替代
  • true，已弃用，请使用'always'替代
类型默认值
枚举('always', 'never', 'handled', false, true)'never'

maintainVisibleContentPosition​

启用此选项后，滚动视图将调整滚动位置，以便当前可见且位于 minIndexForVisible 或其后的第一个子元素的位置不会改变。这对于在两个方向加载内容的列表（例如聊天线程）很有用，因为新消息的到来可能会导致滚动位置跳动。值 0 比较常见，但其他值（如 1）可用于跳过加载微调器或不应保持位置的其他内容。

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

警告 1：启用此功能后，对滚动视图中的元素进行重新排序可能会导致跳动和卡顿。这个问题可以解决，但目前还没有计划这样做。目前，请勿重新排序使用此功能的任何 ScrollView 或 List 的内容。

警告 2：这在原生代码中使用 contentOffset 和 frame.origin 来计算可见性。遮挡、变换和其他复杂性不会被考虑在内，以确定内容是否“可见”。

类型
对象：{minIndexForVisible: number, autoscrollToTopThreshold: number}

maximumZoomScale
iOS
​

允许的最大缩放比例。

类型默认值
数字1.0

minimumZoomScale
iOS
​

允许的最小缩放比例。

类型默认值
数字1.0

nestedScrollEnabled
Android
​

为 Android API 级别 21 及以上版本启用嵌套滚动。

类型默认值
布尔值false

onContentSizeChange​

当 ScrollView 的可滚动内容视图发生变化时调用。

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

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

类型
函数

onMomentumScrollBegin​

当动量滚动开始时调用（ScrollView 开始滑动时发生的滚动）。

类型
函数

onMomentumScrollEnd​

当动量滚动结束时调用（ScrollView 滑动到停止时发生的滚动）。

类型
函数

onScroll​

在滚动期间每帧最多触发一次。事件具有以下形状（所有值均为数字）

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

onScrollBeginDrag​

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

类型
函数

onScrollEndDrag​

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

类型
函数

onScrollToTop
iOS
​

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

类型
函数

overScrollMode
Android
​

用于覆盖 overScroll 模式默认值。

可能的值

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

pagingEnabled​

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

类型默认值
布尔值false

persistentScrollbar
Android
​

导致滚动条在不使用时不变得透明。

类型默认值
布尔值false

pinchGestureEnabled
iOS
​

设置为 true 时，ScrollView 允许使用捏合手势放大和缩小。

类型默认值
布尔值true

refreshControl​

RefreshControl 组件，用于为 ScrollView 提供下拉刷新功能。仅适用于垂直 ScrollView（horizontal 属性必须为 false）。

参见 RefreshControl。

类型
元素

removeClippedSubviews​

实验性：当 true 时，屏幕外的子视图（其 overflow 值为 hidden）将在屏幕外时从其原生后备父视图中移除。这可以提高长列表的滚动性能。

类型默认值
布尔值false

scrollEnabled​

设置为 false 时，无法通过触摸交互滚动视图。

请注意，始终可以通过调用 scrollTo 来滚动视图。

类型默认值
布尔值true

scrollEventThrottle​

限制滚动时触发滚动事件的频率，以毫秒为单位指定时间间隔。当响应滚动执行昂贵的操作时，这可能很有用。值≤16 将禁用节流，而不管设备的刷新率如何。

类型默认值
数字0

scrollIndicatorInsets
iOS
​

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

类型默认值
对象：{top: number, left: number, bottom: number, right: number}{top: 0, left: 0, bottom: 0, right: 0}

scrollPerfTag
Android
​

用于记录此滚动视图上的滚动性能的标签。将强制打开动量事件（请参阅 sendMomentumEvents）。这在开箱即用时不会执行任何操作，并且您需要实现自定义原生 FpsListener 才能使其发挥作用。

类型
字符串

scrollToOverflowEnabled
iOS
​

设置为 true 时，可以以编程方式将滚动视图滚动到其内容大小之外。

类型默认值
布尔值false

scrollsToTop
iOS
​

设置为 true 时，状态栏被点击时滚动视图将滚动到顶部。

类型默认值
布尔值true

showsHorizontalScrollIndicator​

设置为 true 时，显示水平滚动指示器。

类型默认值
布尔值true

showsVerticalScrollIndicator​

设置为 true 时，显示垂直滚动指示器。

类型默认值
布尔值true

snapToAlignment
iOS
​

当设置 snapToInterval 时，snapToAlignment 将定义对齐滚动视图的捕捉关系。

可能的值

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

snapToEnd​

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

类型默认值
布尔值true

snapToInterval​

设置后，会导致滚动视图在 snapToInterval 值的倍数处停止。这可用于对长度小于滚动视图的子元素进行分页。通常与 snapToAlignment 和 decelerationRate="fast" 结合使用。覆盖配置较少的 pagingEnabled 属性。

类型
数字

snapToOffsets​

设置后，会导致滚动视图在定义的偏移量处停止。这可用于对长度小于滚动视图的各种大小的子元素进行分页。通常与 decelerationRate="fast" 结合使用。覆盖配置较少的 pagingEnabled 和 snapToInterval 属性。

类型
数字数组

snapToStart​

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

类型默认值
布尔值true

stickyHeaderHiddenOnScroll​

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

类型默认值
布尔值false

stickyHeaderIndices​

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

类型
数字数组

zoomScale
iOS
​

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

类型默认值
数字1.0

方法​

flashScrollIndicators()​

flashScrollIndicators();

短暂显示滚动指示器。

scrollTo()​

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()​

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

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

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