ScrollView

此組件包裝了平台 ScrollView，同時提供與觸控鎖定「響應器」系統的整合。

請記住，ScrollView 必須具有有界的高度才能運作，因為它們將無界高度的子組件放入有界的容器中（透過滾動互動）。為了限制 ScrollView 的高度，可以直接設定視圖的高度（不建議），或確保所有父視圖都具有有界的高度。忘記將 {flex: 1} 向下傳遞到視圖堆疊可能會導致此處發生錯誤，元素檢查器可以快速偵錯這些錯誤。

尚不支援阻止此滾動視圖成為響應器的其他包含響應器。

<ScrollView> vs <FlatList> - 該用哪一個？

ScrollView 會一次渲染其所有 React 子組件，但這會帶來效能上的缺點。

想像一下，您有一個非常長的項目列表要顯示，可能內容會佔據好幾個螢幕。一次為所有內容（其中大部分甚至可能不會顯示）建立 JS 組件和原生視圖，將導致渲染速度變慢和記憶體使用量增加。

這就是 FlatList 發揮作用的地方。FlatList 會延遲渲染項目，在項目即將出現時才渲染，並移除滾動到螢幕外很遠的項目，以節省記憶體和處理時間。

如果您想要在項目之間渲染分隔線、多列、無限滾動載入或它開箱即用的任何其他功能，FlatList 也非常方便。

範例

參考

Props

View Props

繼承 View Props。

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

類型
視圖樣式

`contentInset`
iOS

滾動視圖內容從滾動視圖邊緣插入的量。

類型	預設值
物件：`{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`

用於手動設定起始滾動偏移量。

類型	預設值
點	`{x: 0, y: 0}`

`decelerationRate`

一個浮點數，決定使用者抬起手指後滾動視圖減速的速度。您也可以使用字串快捷方式 "normal" 和 "fast"，它們分別與 UIScrollViewDecelerationRateNormal 和 UIScrollViewDecelerationRateFast 的底層 iOS 設定相符。

'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

有時滾動視圖佔用的空間大於其內容填充的空間。在這種情況下，此 prop 將用顏色填充滾動視圖的其餘部分，以避免設定背景並產生不必要的過度繪製。這是一種進階最佳化，在一般情況下不需要。

類型
color

`fadingEdgeLength`
Android

淡化滾動內容的邊緣。

如果值大於 0，則會根據目前的滾動方向和位置設定淡化邊緣，指示是否還有更多內容要顯示。

類型	預設值
number	`0`

`horizontal`

若為 true，滾動視圖的子組件會水平排列成一行，而不是垂直排列成一列。

類型	預設值
bool	`false`

`indicatorStyle`
iOS

滾動指示器的樣式。

'default' 與 black 相同。
'black'，滾動指示器為 黑色。此樣式適用於淺色背景。
'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 來計算可見性。遮擋、轉換和其他複雜性不會被考慮在內，以判斷內容是否「可見」。

類型
物件：`{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`

在滾動期間，最多每幀觸發一次。事件具有以下形狀（所有值都是數字）

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，滾動視圖在滾動時會在滾動視圖大小的倍數處停止。這可以用於水平分頁。

類型	預設值
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 相同的值。

類型	預設值
物件：`{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`
iOS

當設定 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 屬性。

類型
數字陣列

`snapToStart`

與 snapToOffsets 結合使用。預設情況下，列表的開頭計為貼齊偏移量。將 snapToStart 設定為 false 以停用此行為，並允許列表在其開頭和第一個 snapToOffsets 偏移量之間自由滾動。

類型	預設值
bool	`true`

`stickyHeaderHiddenOnScroll`

設定為 true 時，黏性標頭將在向下滾動列表時隱藏，並在向上滾動時停靠在列表頂部。

類型	預設值
bool	`false`

`stickyHeaderIndices`

一個子索引陣列，決定哪些子組件在滾動時停靠在螢幕頂部。例如，傳遞 stickyHeaderIndices={[0]} 將使第一個子組件固定在滾動視圖的頂部。您也可以像 [x,y,z] 這樣使用，以在多個項目位於頂部時使其具有黏性。此屬性與 horizontal={true} 結合使用時不受支援。

類型
數字陣列

`zoomScale`
iOS

滾動視圖內容的目前比例。

類型	預設值
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})

注意：奇怪的函式簽章是由於歷史原因，該函式也接受單獨的參數作為選項物件的替代方案。由於含糊不清（y 在 x 之前），這已被棄用，且不應使用。

`scrollToEnd()`

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

如果這是垂直 ScrollView，則滾動到底部。如果這是水平 ScrollView，則滾動到右側。

使用 scrollToEnd({animated: true}) 進行平滑動畫滾動，使用 scrollToEnd({animated: false}) 進行立即滾動。如果未傳遞任何選項，則 animated 預設為 true。

範例
Props
方法

範例​

參考

Props​

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 iOS​

snapToEnd​

snapToInterval​

snapToOffsets​

snapToStart​

stickyHeaderHiddenOnScroll​

stickyHeaderIndices​

zoomScale iOS​

方法​

flashScrollIndicators()​

scrollTo()​

scrollToEnd()​

範例