ScrollView

包装了平台 ScrollView 组件，并提供了与触摸锁定“responder”系统的集成。

请注意，ScrollView 必须具有固定的高度才能正常工作，因为它会将高度不固定的子组件（通过滚动交互）包含在一个固定高度的容器中。要固定 ScrollView 的高度，请直接设置视图的高度（不推荐）或确保所有父视图都具有固定高度。忘记将 {flex: 1} 传递给视图堆栈的下一层可能会导致此处出错，元素检查器可以帮助快速调试。

尚不支持其他包含的响应器阻止此 ScrollView 成为响应器。

<ScrollView> vs <FlatList> - 哪个更好？

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

想象一下您有一个非常长的项目列表要显示，可能包含好几个屏幕的内容。一次性创建所有 JS 组件和原生视图，其中很多可能甚至没有显示出来，这会拖慢渲染速度并增加内存使用。

这就是 FlatList 发挥作用的地方。FlatList 会在项目即将显示时惰性渲染它们，并移除滚动到屏幕外太远的那些项目，以节省内存和处理时间。

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

示例

参考

属性

View Props

继承自 View Props。

`StickyHeaderComponent`

一个用于渲染固定（sticky）头部的 React 组件，应与 stickyHeaderIndices 一起使用。如果您的固定头部使用了自定义变换，例如，当您希望列表有一个可动画且可隐藏的头部时，您可能需要设置此组件。如果未提供组件，则会使用默认的 ScrollViewStickyHeader 组件。

类型
组件，元素

`alwaysBounceHorizontal`
iOS

当为 true 时，即使内容小于 ScrollView 本身，滚动视图在到达末尾时也会水平弹跳。

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

`alwaysBounceVertical`
iOS

当为 true 时，即使内容小于 ScrollView 本身，滚动视图在到达末尾时也会垂直弹跳。

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

`automaticallyAdjustContentInsets`
iOS

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

类型	默认
布尔值	`true`

`automaticallyAdjustKeyboardInsets`
iOS

控制 ScrollView 在键盘尺寸改变时是否自动调整其 contentInset 和 scrollViewInsets。

类型	默认
布尔值	`false`

`automaticallyAdjustsScrollIndicatorInsets`
iOS

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

类型	默认
布尔值	`true`

`bounces`
iOS

当为 true 时，如果内容尺寸大于滚动视图沿滚动方向的轴，则滚动视图在到达内容末尾时会弹跳。当为 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
  }
});

类型
View 样式

`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 底层的 UIScrollViewDecelerationRateNormal 和 UIScrollViewDecelerationRateFast 设置。

'normal' 在 iOS 上为 0.998，在 Android 上为 0.985。
'fast' 在 iOS 上为 0.99，在 Android 上为 0.9。

类型	默认
enum(`'fast'`, `'normal'`), number	`'normal'`

`directionalLockEnabled`
iOS

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

类型	默认
布尔值	`false`

`disableIntervalMomentum`

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

类型	默认
布尔值	`false`

`disableScrollViewPanResponder`

当为 true 时，ScrollView 上的默认 JS pan responder 将被禁用，并将触摸控制完全留给其子组件。当启用了 snapToInterval 时，这特别有用，因为它不遵循典型的触摸模式。在没有 snapToInterval 的常规 ScrollView 用例中请勿使用此选项，因为它可能会导致滚动时出现意外的触摸。

类型	默认
布尔值	`false`

`endFillColor`
Android

有时 ScrollView 占用的空间会大于其内容所填满的空间。在这种情况下，此属性会将 ScrollView 的剩余部分填充为一种颜色，以避免设置背景并造成不必要的过度绘制。这是一个高级优化，在一般情况下不需要。

类型
颜色

`fadingEdgeLength`
Android

使滚动内容边缘逐渐消失。

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

类型	默认
数字 object: `{start: number, end: number}`	`0`

`horizontal`

当为 true 时，ScrollView 的子组件将水平排列成一行，而不是垂直排列成一列。

类型	默认
布尔值	`false`

`indicatorStyle`
iOS

滚动指示器的样式。

'default' 与 black 相同。
'black'，滚动指示器为 black。这种样式在浅色背景上效果很好。
'white'，滚动指示器为 white。这种样式在深色背景上效果很好。

类型	默认
enum(`'default'`, `'black'`, `'white'`)	`'default'`

`invertStickyHeaders`

如果固定头部应固定在 ScrollView 的底部而不是顶部。这通常与反向的 ScrollView 一起使用。

类型	默认
布尔值	`false`

`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：这在原生代码中使用 contentOffset 和 frame.origin 来计算可见性。遮挡、变换和其他复杂性不会被考虑在内容是否“可见”之内。

类型
object: `{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`

滚动期间每帧最多触发一次。事件具有以下形状（所有类型未指定的属性都是数字）

js
{
  nativeEvent: {
    contentInset: {bottom, left, right, top},
    contentOffset: {x, y},
    contentSize: {height, width},
    layoutMeasurement: {height, width},
    velocity: {x, y},
    responderIgnoreScroll: boolean,
    zoomScale,
    // iOS only
    targetContentOffset: {x, y}
  }
}

类型
函数

`onScrollBeginDrag`

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

类型
函数

`onScrollEndDrag`

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

类型
函数

`onScrollToTop`
iOS

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

类型
函数

`overScrollMode`
Android

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

可能的值

'auto' - 仅当内容足够大可以有意义地滚动时，才允许用户过度滚动此视图。
'always' - 始终允许用户过度滚动此视图。
'never' - 绝不允许用户过度滚动此视图。

类型	默认
enum(`'auto'`, `'always'`, `'never'`)	`'auto'`

`pagingEnabled`

当为 true 时，滚动视图在滚动时会在滚动视图尺寸的倍数处停止。这可用于水平分页。

类型	默认
布尔值	`false`

`persistentScrollbar`
Android

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

类型	默认
布尔值	`false`

`pinchGestureEnabled`
iOS

当为 true 时，ScrollView 允许使用捏合手势进行缩放。

类型	默认
布尔值	`true`

`refreshControl`

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

请参阅 RefreshControl。

类型
element

`removeClippedSubviews`

警告

在某些情况下使用此属性可能会导致错误（内容缺失）——请自行承担风险。

当为 true 时，屏幕外的子视图将从其原生支持的父视图中移除。这可能会提高大型列表的滚动性能。在 Android 上，默认值为 true。

类型
布尔值

`scrollEnabled`

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

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

类型	默认
布尔值	`true`

`scrollEventThrottle`

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

类型	默认
数字	`0`

`scrollIndicatorInsets`
iOS

滚动视图指示器与其边缘的插图量。通常应将其设置为与 contentInset 相同的值。

类型	默认
object: `{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`

当设置 snapToInterval 时，snapToAlignment 将定义吸附与滚动视图的关系。

可能的值

'start' 会将吸附对齐到左侧（水平）或顶部（垂直）。
'center' 会将吸附对齐到中心。
'end' 会将吸附对齐到右侧（水平）或底部（垂直）。

类型	默认
enum(`'start'`, `'center'`, `'end'`)	`'start'`

`snapToEnd`

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

类型	默认
布尔值	`true`

`snapToInterval`

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

类型
数字

`snapToOffsets`

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

类型
array of number

`snapToStart`

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

类型	默认
布尔值	`true`

`stickyHeaderHiddenOnScroll`

设置为 true 时，固定头部在向下滚动列表时会被隐藏，在向上滚动列表时会停靠在列表顶部。

类型	默认
布尔值	`false`

`stickyHeaderIndices`

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

类型
array of number

`zoomScale`
iOS

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

类型	默认
数字	`1.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。

示例
属性
方法

示例​

参考

属性​

View Props​

StickyHeaderComponent​

alwaysBounceHorizontal iOS​

alwaysBounceVertical iOS​

automaticallyAdjustContentInsets iOS​

automaticallyAdjustKeyboardInsets iOS​

automaticallyAdjustsScrollIndicatorInsets iOS​

bounces iOS​

bouncesZoom iOS​

canCancelContentTouches iOS​

centerContent iOS​

contentContainerStyle​

contentInset iOS​

contentInsetAdjustmentBehavior iOS​

contentOffset​

decelerationRate​

directionalLockEnabled iOS​

disableIntervalMomentum​

disableScrollViewPanResponder​

endFillColor Android​

fadingEdgeLength Android​

horizontal​

indicatorStyle iOS​

invertStickyHeaders​

keyboardDismissMode​

keyboardShouldPersistTaps​

maintainVisibleContentPosition​

maximumZoomScale iOS​

minimumZoomScale iOS​

nestedScrollEnabled Android​

onContentSizeChange​

onMomentumScrollBegin​

onMomentumScrollEnd​

onScroll​

onScrollBeginDrag​

onScrollEndDrag​

onScrollToTop iOS​

overScrollMode Android​

pagingEnabled​

persistentScrollbar Android​

pinchGestureEnabled iOS​

refreshControl​

removeClippedSubviews​

scrollEnabled​

scrollEventThrottle​

scrollIndicatorInsets iOS​

scrollPerfTag Android​

scrollToOverflowEnabled iOS​

scrollsToTop iOS​

showsHorizontalScrollIndicator​

showsVerticalScrollIndicator​

snapToAlignment​

snapToEnd​

snapToInterval​

snapToOffsets​

snapToStart​

stickyHeaderHiddenOnScroll​

stickyHeaderIndices​

zoomScale iOS​

方法​

flashScrollIndicators()​

scrollTo()​

scrollToEnd()​

示例

属性