版本：0.78

ScrollView

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

封装平台原生 ScrollView 的组件，同时提供与触摸锁定"响应者"系统的集成能力。

请注意：ScrollView 必须具有限定高度才能正常工作，因为它会将无限高度的子元素装入有限高度的容器（通过滚动交互实现）。要限定 ScrollView 的高度，可直接设置视图高度（不推荐）或确保所有父视图都有固定高度。忘记沿视图栈向下传递 {flex: 1} 会导致布局错误，使用元素检查器可以快速调试这类问题。

暂不支持防止其他容器内响应者阻止本滚动视图成为响应者。

<ScrollView> 与 <FlatList> 如何选择？

ScrollView 会立即渲染所有 React 子组件，但这会带来性能问题。

假设需要展示超长列表（可能包含多屏内容）。一次性创建所有 JS 组件和原生视图（即使多数内容不可见）会导致渲染缓慢和内存占用增加。

这正是 FlatList 的用武之地。FlatList 采用惰性渲染策略：仅在条目即将出现时渲染，并移除滚动出屏幕的条目以节省内存和处理时间。

若需渲染条目分隔线、多列布局、无限滚动加载或其他开箱即用的功能，FlatList 同样非常便捷。

示例

参考

属性

View 属性

继承 View 组件的属性。

`StickyHeaderComponent`

用于渲染粘性标题的 React 组件，需与 stickyHeaderIndices 配合使用。当粘性标题需要自定义变换（例如实现可动画隐藏的列表标题）时需设置此组件。若未提供，将使用默认的 ScrollViewStickyHeader 组件。

Type
component, element

`alwaysBounceHorizontal`
iOS

为 true 时，即使内容宽度小于滚动视图，滚动到水平边界时仍会触发回弹效果。

Type	Default
bool	`true` when `horizontal={true}` `false` otherwise

`alwaysBounceVertical`
iOS

为 true 时，即使内容高度小于滚动视图，滚动到垂直边界时仍会触发回弹效果。

Type	Default
bool	`false` when `horizontal={true}` `true` otherwise

`automaticallyAdjustContentInsets`
iOS

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

Type	Default
bool	`true`

`automaticallyAdjustKeyboardInsets`
iOS

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

Type	Default
bool	`false`

`automaticallyAdjustsScrollIndicatorInsets`
iOS

控制 iOS 是否自动调整滚动指示器内边距。详见苹果官方属性文档。

Type	Default
bool	`true`

`bounces`
iOS

为 true 时，当内容尺寸大于滚动视图沿滚动方向尺寸时，滚动到内容边界会触发回弹效果。为 false 时，即使 alwaysBounce* 属性为 true 也会禁用所有回弹效果。

Type	Default
bool	`true`

`bouncesZoom`
iOS

为 true 时，手势操作可驱动缩放超出最小/最大值限制，并在手势结束时以动画形式回归限制值；否则缩放不会超出限制范围。

Type	Default
bool	`true`

`canCancelContentTouches`
iOS

为 false 时，一旦开始跟踪触摸，即使触摸点移动也不会尝试拖动。

Type	Default
bool	`true`

`centerContent`
iOS

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

Type	Default
bool	`false`

`contentContainerStyle`

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

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

Type
View Style

`contentInset`
iOS

滚动视图内容从滚动视图边缘向内缩进的距离。

Type	Default
object: `{top: number, left: number, bottom: number, right: number}`	`{top: 0, left: 0, bottom: 0, right: 0}`

`contentInsetAdjustmentBehavior`
iOS

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

Type	Default
enum(`'automatic'`, `'scrollableAxes'`, `'never'`, `'always'`)	`'never'`

`contentOffset`

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

Type	Default
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

Type	Default
enum(`'fast'`, `'normal'`), number	`'normal'`

`directionalLockEnabled`
iOS

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

Type	Default
bool	`false`

`disableIntervalMomentum`

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

Type	Default
bool	`false`

`disableScrollViewPanResponder`

当为 true 时，将禁用 ScrollView 上默认的 JS 拖拽响应器，滚动视图内部触摸事件的完全控制权将交给其子组件。这在启用 snapToInterval 时特别有用（因其不符合常规触摸模式）。不要在未使用 snapToInterval 的常规 ScrollView 中使用此属性，否则可能导致滚动时出现意外触摸事件。

Type	Default
bool	`false`

`endFillColor`
Android

当滚动视图占用空间大于其内容区域时，此属性会使用指定颜色填充剩余空间，避免设置背景造成不必要的过度绘制。这是一种高级优化技术，通常无需使用。

Type
color

`fadingEdgeLength`
Android

淡出滚动内容的边缘。

若值大于 0，会根据当前滚动方向和位置设置淡出边缘，提示用户还有更多内容可滚动查看。

Type	Default
number	`0`

`horizontal`

当为 true 时，滚动视图的子元素将水平排列成行而非垂直排列成列。

Type	Default
bool	`false`

`indicatorStyle`
iOS

滚动指示器的样式。

'default' 等同于 black。
'black'，滚动指示器为 black。这种样式在浅色背景下效果很好。
'white'，滚动指示器为 white。这种样式在深色背景下效果良好。

Type	Default
enum(`'default'`, `'black'`, `'white'`)	`'default'`

`invertStickyHeaders`

是否将粘性标题固定在 ScrollView 底部而非顶部。通常与反向滚动的 ScrollView 配合使用。

Type	Default
bool	`false`

`keyboardDismissMode`

控制拖拽时是否关闭键盘：

'none'：拖拽不会收起键盘。
'on-drag'：拖拽开始时键盘会收起。

仅 iOS

'interactive'：键盘会随拖拽手势同步移动并交互式收起，向上拖拽可取消收起操作。在 Android 上不支持此行为，效果等同于 'none'。

Type	Default
enum(`'none'`, `'on-drag'`) Android enum(`'none'`, `'on-drag'`, `'interactive'`) iOS	`'none'`

`keyboardShouldPersistTaps`

决定点击后键盘是否保持可见。

'never'：键盘弹出时，点击非文本输入区域会收起键盘，此时子组件无法接收到点击事件。
'always'：键盘不会自动收起，滚动视图不会拦截点击事件，其子组件可响应点击。
'handled'：当点击事件被子组件（或被父组件捕获）处理时，键盘不会自动收起。
false：已废弃，请改用 'never'
true：已废弃，请改用 'always'

Type	Default
enum(`'always'`, `'never'`, `'handled'`, `false`, `true`)	`'never'`

`maintainVisibleContentPosition`

启用后，滚动视图会调整位置以确保当前可见且索引≥minIndexForVisible的首个子组件保持原位。适用于双向加载内容的场景（如聊天线程），避免新消息导致滚动位置跳动。通常设为 0，也可设为 1 来跳过加载指示器等无需固定的内容。

可选参数 autoscrollToTopThreshold 可在调整位置后自动滚动至顶部（前提是用户原本位于顶部阈值范围内）。这在类聊天应用中很有用：既能让新消息平滑进入视图，又避免用户滚动浏览时产生干扰性跳转。

注意点 1：在启用此功能时重新排序滚动视图内容可能导致跳动问题。虽可修复但目前暂无计划支持。请勿对使用此功能的 ScrollView 或列表进行内容重排。

注意点 2：底层通过 contentOffset 和 frame.origin 计算可见性，不考虑元素遮挡、变换等复杂因素。

Type
object: `{minIndexForVisible: number, autoscrollToTopThreshold: number}`

`maximumZoomScale`
iOS

允许的最大缩放比例。

Type	Default
number	`1.0`

`minimumZoomScale`
iOS

允许的最小缩放比例。

Type	Default
number	`1.0`

`nestedScrollEnabled`
Android

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

Type	Default
bool	`false`

`onContentSizeChange`

当 ScrollView 的可滚动内容尺寸变化时触发。

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

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

Type
function

`onMomentumScrollBegin`

当动量滚动开始时触发（即 ScrollView 开始滑行的瞬间）。

Type
function

`onMomentumScrollEnd`

当动量滚动结束时触发（即 ScrollView 滑行停止的瞬间）。

Type
function

`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}
  }
}

Type
function

`onScrollBeginDrag`

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

Type
function

`onScrollEndDrag`

当用户停止拖动滚动视图（滚动停止或开始惯性滑动时）调用

Type
function

`onScrollToTop`
iOS

点击状态栏后滚动至顶部时触发

Type
function

`overScrollMode`
Android

用于覆盖默认的过卷动模式

可选值：

'auto' - 仅当内容足够大时才允许过卷动
'always' - 始终允许过卷动
'never' - 禁止过卷动

Type	Default
enum(`'auto'`, `'always'`, `'never'`)	`'auto'`

`pagingEnabled`

设为 true 时，滚动视图会按自身尺寸倍数分页停顿，适用于水平分页场景

Type	Default
bool	`false`

`persistentScrollbar`
Android

禁止滚动条在非活跃状态时变为透明

Type	Default
bool	`false`

`pinchGestureEnabled`
iOS

设为 true 时允许双指缩放操作

Type	Default
bool	`true`

`refreshControl`

用于实现下拉刷新的 RefreshControl 组件（仅垂直 ScrollView 有效，即 horizontal 属性必须为 false）

参见 RefreshControl

Type
element

`removeClippedSubviews`

实验功能：设为 true 时，会自动移除屏幕外子视图（其 overflow 需为 hidden），可提升长列表滚动性能

Type	Default
bool	`false`

`scrollEnabled`

设为 false 时禁止触摸滚动

注意：仍可通过 scrollTo 方法进行程序化滚动

Type	Default
bool	`true`

`scrollEventThrottle`

限制滚动事件触发频率（单位毫秒）。当滚动事件处理逻辑较重时建议调整该值。≤ 16 时将禁用节流

Type	Default
number	`0`

`scrollIndicatorInsets`
iOS

滚动指示器相对于滚动视图边缘的内边距，通常应与 contentInset 保持一致

Type	Default
object: `{top: number, left: number, bottom: number, right: number}`	`{top: 0, left: 0, bottom: 0, right: 0}`

`scrollPerfTag`
Android

用于记录滚动性能的标记，将强制启用动量事件（参见 sendMomentumEvents）。需配合自定义原生 FpsListener 使用

Type
string

`scrollToOverflowEnabled`
iOS

设为 true 时允许程序化滚动超出内容尺寸

Type	Default
bool	`false`

`scrollsToTop`
iOS

设为 true 时，点击状态栏会自动滚动至顶部

Type	Default
bool	`true`

`showsHorizontalScrollIndicator`

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

Type	Default
bool	`true`

`showsVerticalScrollIndicator`

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

Type	Default
bool	`true`

`snapToAlignment`

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

可选值：

'start'：在水平方向左侧或垂直方向顶部对齐吸附点。
'center'：在中心位置对齐吸附点。
'end'：在水平方向右侧或垂直方向底部对齐吸附点。

Type	Default
enum(`'start'`, `'center'`, `'end'`)	`'start'`

`snapToEnd`

需与 snapToOffsets 配合使用。默认情况下，列表末端会作为吸附点。将 snapToEnd 设为 false 可禁用此行为，允许列表在末端与最后一个 snapToOffsets 吸附点之间自由滚动。

Type	Default
bool	`true`

`snapToInterval`

设置后会使滚动视图在 snapToInterval 值的整数倍位置停顿。适用于子项尺寸小于滚动视图的分页场景，通常需配合 snapToAlignment 和 decelerationRate="fast" 使用。此属性将覆盖功能较简单的 pagingEnabled 属性。

Type
number

`snapToOffsets`

设置后会使滚动视图在指定偏移量位置停顿。适用于不同尺寸子项的分页场景（子项尺寸小于滚动视图），通常需配合 decelerationRate="fast" 使用。此属性将覆盖 pagingEnabled 和 snapToInterval 属性。

Type
array of number

`snapToStart`

需与 snapToOffsets 配合使用。默认情况下，列表起始位置会作为吸附点。将 snapToStart 设为 false 可禁用此行为，允许列表在起始位置与第一个 snapToOffsets 吸附点之间自由滚动。

Type	Default
bool	`true`

`stickyHeaderHiddenOnScroll`

设为 true 时，粘性标题会在向下滚动时隐藏，向上滚动时固定在列表顶部。

Type	Default
bool	`false`

`stickyHeaderIndices`

指定子元素索引的数组，当滚动时这些子元素会固定在屏幕顶部。例如设置 stickyHeaderIndices={[0]} 会使第一个子元素固定在滚动视图顶部。也可使用 [x,y,z] 格式使多个元素在顶部时保持粘性。此属性不支持与 horizontal={true} 同时使用。

Type
array of number

`zoomScale`
iOS

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

Type	Default
number	`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})

注意：由于历史原因，该函数也支持独立参数（与 options 对象二选一），但因参数顺序歧义（y 在 x 前）已被弃用，应避免使用。

`scrollToEnd()`

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

垂直滚动视图将滚动到底部，水平滚动视图将滚动到最右侧。

使用 scrollToEnd({animated: true}) 可实现平滑的滚动动画，使用 scrollToEnd({animated: false}) 则可立即滚动。若不传递任何选项，animated 参数默认值为 true。

示例
属性
方法

示例​

参考

属性​

View 属性​

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

示例

属性