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 时,即使内容小于滚动视图本身,滚动视图在到达末尾时也会水平方向上回弹。
类型 | 默认值 |
---|---|
bool | 当 horizontal={true} 时为 true 否则为 false |
alwaysBounceVertical
iOS
当为 true 时,即使内容小于滚动视图本身,滚动视图在到达末尾时也会垂直方向上回弹。
类型 | 默认值 |
---|---|
bool | 当 vertical={true} 时为 false 否则为 true |
automaticallyAdjustContentInsets
iOS
控制 iOS 是否应自动调整放置在导航栏或标签栏/工具栏后面的滚动视图的内容边距。
类型 | 默认值 |
---|---|
bool | true |
automaticallyAdjustKeyboardInsets
iOS
控制键盘大小改变时 ScrollView 是否应自动调整其 contentInset
和 scrollViewInsets
。
类型 | 默认值 |
---|---|
bool | false |
automaticallyAdjustsScrollIndicatorInsets
iOS
控制 iOS 是否应自动调整滚动指示器边距。请参阅 Apple 关于此属性的文档。
类型 | 默认值 |
---|---|
bool | true |
bounces
iOS
当为 true 时,如果内容在滚动方向轴上大于滚动视图,则滚动视图在到达内容末尾时回弹。当为 false
时,即使 alwaysBounce*
属性为 true
,也会禁用所有回弹。
类型 | 默认值 |
---|---|
bool | true |
bouncesZoom
iOS
当为 true
时,手势可以驱动缩放超出最小/最大范围,并且缩放将在手势结束时动画到最小/最大值,否则缩放将不超过限制。
类型 | 默认值 |
---|---|
bool | true |
canCancelContentTouches
iOS
当为 false
时,一旦跟踪开始,如果触摸移动,将不会尝试拖动。
类型 | 默认值 |
---|---|
bool | true |
centerContent
iOS
当为 true
时,当内容小于滚动视图边界时,滚动视图会自动居中内容;当内容大于滚动视图时,此属性无效。
类型 | 默认值 |
---|---|
bool | false |
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 设置中的 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 在拖动时将尝试仅锁定垂直或水平滚动。
类型 | 默认值 |
---|---|
bool | false |
disableIntervalMomentum
当为 true 时,无论手势速度多快,滚动视图都会停止在下一个索引(相对于释放时的滚动位置)。这可用于当页面小于水平 ScrollView 的宽度或垂直 ScrollView 的高度时进行分页。
类型 | 默认值 |
---|---|
bool | false |
disableScrollViewPanResponder
当为 true 时,ScrollView 上的默认 JS 平移响应器被禁用,并且对 ScrollView 内触摸的完全控制权留给其子组件。如果启用了 snapToInterval
,这尤其有用,因为它不遵循典型的触摸模式。在没有 snapToInterval
的常规 ScrollView 用例中不要使用此功能,因为它可能导致滚动时发生意外触摸。
类型 | 默认值 |
---|---|
bool | false |
endFillColor
Android
有时滚动视图占用的空间超出其内容所填充的空间。在这种情况下,此属性将用颜色填充滚动视图的其余部分,以避免设置背景和创建不必要的过度绘制。这是一种高级优化,在一般情况下不需要。
类型 |
---|
color |
fadingEdgeLength
Android
淡出滚动内容的边缘。
如果值大于 0
,淡出边缘将根据当前的滚动方向和位置进行设置,指示是否有更多内容可显示。
类型 | 默认值 |
---|---|
number | 0 |
horizontal
当为 true
时,滚动视图的子组件水平排列成一行,而不是垂直排列成一列。
类型 | 默认值 |
---|---|
bool | false |
indicatorStyle
iOS
滚动指示器的样式。
'default'
与black
相同。'black'
,滚动指示器为black
。此样式适合浅色背景。'white'
,滚动指示器为white
。此样式适合深色背景。
类型 | 默认值 |
---|---|
enum('default' , 'black' , 'white' ) | 'default' |
invertStickyHeaders
粘性标题是否应粘在 ScrollView 的底部而不是顶部。这通常与反转的 ScrollView 一起使用。
类型 | 默认值 |
---|---|
bool | 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
允许的最大缩放比例。
类型 | 默认值 |
---|---|
number | 1.0 |
minimumZoomScale
iOS
允许的最小缩放比例。
类型 | 默认值 |
---|---|
number | 1.0 |
nestedScrollEnabled
Android
为 Android API level 21+ 启用嵌套滚动。
类型 | 默认值 |
---|---|
bool | false |
onContentSizeChange
当 ScrollView 的可滚动内容视图更改时调用。
处理函数将接收两个参数:内容宽度和内容高度 (contentWidth, contentHeight)
。
它通过附加到此 ScrollView 渲染的内容容器的 onLayout 处理程序实现。
类型 |
---|
function |
onMomentumScrollBegin
当惯性滚动开始时(ScrollView 开始滑行时发生的滚动)调用。
类型 |
---|
function |
onMomentumScrollEnd
当惯性滚动结束时(ScrollView 滑行停止时发生的滚动)调用。
类型 |
---|
function |
onScroll
滚动时每帧最多触发一次。事件具有以下形状(所有值均为数字)
{
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 时,滚动视图在滚动时会停止在滚动视图大小的倍数位置。这可用于水平分页。
类型 | 默认值 |
---|---|
bool | false |
persistentScrollbar
Android
使滚动条在不使用时不会变成透明。
类型 | 默认值 |
---|---|
bool | false |
pinchGestureEnabled
iOS
当为 true 时,ScrollView 允许使用捏合手势进行放大和缩小。
类型 | 默认值 |
---|---|
bool | true |
refreshControl
一个 RefreshControl 组件,用于为 ScrollView 提供下拉刷新功能。仅适用于垂直 ScrollView(horizontal
属性必须为 false
)。
请参阅 RefreshControl。
类型 |
---|
element |
removeClippedSubviews
实验性:当为 true
时,屏幕外的子视图(其 overflow
值为 hidden
)在屏幕外时会从其原生支持的父视图中移除。这可以提高长列表的滚动性能。
类型 | 默认值 |
---|---|
bool | false |
scrollEnabled
当为 false 时,视图无法通过触摸交互滚动。
请注意,视图始终可以通过调用 scrollTo
进行滚动。
类型 | 默认值 |
---|---|
bool | true |
scrollEventThrottle
限制滚动时滚动事件的触发频率,指定为时间间隔(毫秒)。当响应滚动执行昂贵的工作时,这可能很有用。小于等于 16
的值将禁用节流,无论设备的刷新率如何。
类型 | 默认值 |
---|---|
number | 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 才能使其有用。
类型 |
---|
string |
scrollToOverflowEnabled
iOS
当为 true
时,滚动视图可以编程方式滚动超出其内容大小。
类型 | 默认值 |
---|---|
bool | false |
scrollsToTop
iOS
当为 true
时,当状态栏被轻触时,滚动视图会滚动到顶部。
类型 | 默认值 |
---|---|
bool | true |
showsHorizontalScrollIndicator
当为 true
时,显示水平滚动指示器。
类型 | 默认值 |
---|---|
bool | true |
showsVerticalScrollIndicator
当为 true
时,显示垂直滚动指示器。
类型 | 默认值 |
---|---|
bool | true |
snapToAlignment
当设置 snapToInterval
时,snapToAlignment
将定义对齐与滚动视图的关系。
可能的值
'start'
将在左侧(水平)或顶部(垂直)对齐。'center'
将在中心对齐。'end'
将在右侧(水平)或底部(垂直)对齐。
类型 | 默认值 |
---|---|
enum('start' , 'center' , 'end' ) | 'start' |
snapToEnd
与 snapToOffsets
结合使用。默认情况下,列表的末尾算作一个对齐偏移量。将 snapToEnd
设置为 false 以禁用此行为,并允许列表在其末尾和最后一个 snapToOffsets
偏移量之间自由滚动。
类型 | 默认值 |
---|---|
bool | true |
snapToInterval
设置后,导致滚动视图在 snapToInterval
值的倍数位置停止。这可用于分页通过长度小于滚动视图的子组件。通常与 snapToAlignment
和 decelerationRate="fast"
结合使用。覆盖可配置性较低的 pagingEnabled
属性。
类型 |
---|
number |
snapToOffsets
设置后,导致滚动视图在定义的偏移量处停止。这可用于分页通过长度小于滚动视图的各种大小的子组件。通常与 decelerationRate="fast"
结合使用。覆盖可配置性较低的 pagingEnabled
和 snapToInterval
属性。
类型 |
---|
array of number |
snapToStart
与 snapToOffsets
结合使用。默认情况下,列表的开头算作一个对齐偏移量。将 snapToStart
设置为 false
以禁用此行为,并允许列表在其开头和第一个 snapToOffsets
偏移量之间自由滚动。
类型 | 默认值 |
---|---|
bool | true |
stickyHeaderHiddenOnScroll
当设置为 true
时,向下滚动列表时,粘性标题将隐藏;向上滚动时,它将停靠在列表顶部。
类型 | 默认值 |
---|---|
bool | false |
stickyHeaderIndices
一个子索引数组,用于确定哪些子组件在滚动时停靠在屏幕顶部。例如,传递 stickyHeaderIndices={[0]}
将导致第一个子组件固定在滚动视图的顶部。您也可以使用 [x,y,z] 使多个项目在顶部时保持粘性。此属性不支持与 horizontal={true}
结合使用。
类型 |
---|
array of number |
zoomScale
iOS
滚动视图内容的当前缩放比例。
类型 | 默认值 |
---|---|
number | 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
。