メインコンテンツへスキップ

ScrollView

プラットフォームのScrollViewをラップし、タッチロック「レスポンダー」システムとの統合を提供するコンポーネントです。

ScrollViewは、無制限の高さの子要素を、スクロール操作によって制限されたコンテナに収めるため、機能するためには、高さが制限されている必要があることに注意してください。ScrollViewの高さを制限するには、ビューの高さを直接設定する（非推奨）か、すべての親ビューの高さが制限されていることを確認してください。{flex: 1}をビュー階層に伝達し忘れると、ここでエラーが発生する可能性があり、要素インスペクターを使用すると迅速にデバッグできます。

このスクロールビューがレスポンダーになるのをブロックする、他のコンテナ内のレスポンダーはまだサポートされていません。

<ScrollView> と <FlatList> - どちらを使うべきか？

ScrollView は、すべてのReact子コンポーネントを一度にレンダリングしますが、これにはパフォーマンス上の欠点があります。

表示したい非常に長いアイテムのリスト、おそらく数画面分のコンテンツがあると想像してみてください。JSコンポーネントとネイティブビューをすべて一度に作成すると、その多くは表示されない可能性さえあり、レンダリングの遅延とメモリ使用量の増加につながります。

ここで FlatList が登場します。FlatList は、アイテムが表示されそうになったときに遅延レンダリングし、画面外にスクロールされたアイテムを削除して、メモリと処理時間を節約します。

FlatList は、アイテム間に区切り、複数列、無限スクロールローディング、またはすぐに利用できるその他の多くの機能をレンダリングしたい場合にも便利です。

例​

リファレンス

Props​

View Props​

ViewのPropsを継承します。

StickyHeaderComponent​

スティッキーヘッダーのレンダリングに使用されるReactコンポーネントで、stickyHeaderIndices と一緒に使用する必要があります。例えば、リストにアニメーション付きで非表示可能なヘッダーを持たせたい場合など、スティッキーヘッダーがカスタム変換を使用する場合は、このコンポーネントを設定する必要があるかもしれません。コンポーネントが提供されていない場合は、デフォルトの ScrollViewStickyHeader コンポーネントが使用されます。

型
component, element

alwaysBounceHorizontal
iOS
​

trueの場合、コンテンツがスクロールビュー自体よりも小さい場合でも、スクロールビューが端に達したときに水平方向にバウンスします。

型デフォルト
boolhorizontal={true} の場合は true
それ以外の場合は false

alwaysBounceVertical
iOS
​

trueの場合、コンテンツがスクロールビュー自体よりも小さい場合でも、スクロールビューが端に達したときに垂直方向にバウンスします。

型デフォルト
boolhorizontal={true} の場合は false
それ以外の場合は true

automaticallyAdjustContentInsets
iOS
​

iOSがナビゲーションバーまたはタブバー/ツールバーの後ろに配置されたスクロールビューのコンテンツインセットを自動的に調整するかどうかを制御します。

型デフォルト
booltrue

automaticallyAdjustKeyboardInsets
iOS
​

キーボードのサイズが変更されたときに、ScrollViewがその contentInset と scrollViewInsets を自動的に調整するかどうかを制御します。

型デフォルト
boolfalse

automaticallyAdjustsScrollIndicatorInsets
iOS
​

iOSがスクロールインジケーターのインセットを自動的に調整するかどうかを制御します。Appleのプロパティに関するドキュメントを参照してください。

型デフォルト
booltrue

bounces
iOS
​

trueの場合、コンテンツがスクロール方向の軸に沿ってスクロールビューよりも大きい場合、スクロールビューがコンテンツの端に達したときにバウンスします。falseの場合、alwaysBounce*プロパティがtrueであっても、すべてのバウンスを無効にします。

型デフォルト
booltrue

bouncesZoom
iOS
​

true の場合、ジェスチャーによってズームが最小/最大を超えても、ジェスチャー終了時にズームが最小/最大値にアニメーションで戻ります。それ以外の場合、ズームは制限を超えません。

型デフォルト
booltrue

canCancelContentTouches
iOS
​

falseの場合、トラッキングが開始されると、タッチが移動してもドラッグを試みません。

型デフォルト
booltrue

centerContent
iOS
​

true の場合、コンテンツがスクロールビューの境界よりも小さい場合、スクロールビューはコンテンツを自動的に中央に配置します。コンテンツがスクロールビューよりも大きい場合、このプロパティは効果がありません。

型デフォルト
boolfalse

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" の文字列ショートカットも使用できます。これらはそれぞれ UIScrollViewDecelerationRateNormal および UIScrollViewDecelerationRateFast の基となるiOS設定に一致します。

  • iOSでは 'normal' 0.998、Androidでは 0.985。
  • iOSでは 'fast' 0.99、Androidでは 0.9。
型デフォルト
enum('fast', 'normal'), number'normal'

directionalLockEnabled
iOS
​

trueの場合、ドラッグ中にScrollViewは垂直方向または水平方向のスクロールのみにロックしようとします。

型デフォルト
boolfalse

disableIntervalMomentum​

trueの場合、ジェスチャーの速さに関係なく、スクロールビューは次のインデックス（リリース時のスクロール位置に関連して）で停止します。これは、ページが水平Scrollviewの幅または垂直Scrollviewの高さよりも小さい場合のページネーションに使用できます。

型デフォルト
boolfalse

disableScrollViewPanResponder​

trueの場合、ScrollViewのデフォルトのJSパンレスポンダーは無効になり、ScrollView内のタッチの完全な制御は子コンポーネントに任されます。これは、snapToInterval が有効な場合に特に便利です。これは、典型的なタッチパターンに従わないためです。snapToInterval を使用しない通常のScrollViewのユースケースではこれを使用しないでください。スクロール中に予期しないタッチが発生する可能性があります。

型デフォルト
boolfalse

endFillColor
Android
​

スクロールビューがコンテンツが満たすよりも多くのスペースを占める場合があります。この場合、このプロパティはスクロールビューの残りの部分を色で埋め、背景を設定したり不要なオーバードローを作成したりするのを避けます。これは一般的なケースでは不要な高度な最適化です。

型
color

fadingEdgeLength
Android
​

スクロールコンテンツの端をフェードアウトさせます。

値が 0 より大きい場合、フェードエッジは現在のスクロール方向と位置に応じて設定され、表示するコンテンツがまだあるかどうかを示します。

型デフォルト
number
object: {start: number, end: number}		0

horizontal​

true の場合、スクロールビューの子要素は垂直方向の列ではなく、水平方向の行に配置されます。

型デフォルト
boolfalse

indicatorStyle
iOS
​

スクロールインジケーターのスタイルです。

  • 'default' は black と同じです。
  • 'black'、スクロールインジケーターは black です。このスタイルは明るい背景に適しています。
  • 'white'、スクロールインジケーターは white です。このスタイルは暗い背景に適しています。
型デフォルト
enum('default', 'black', 'white')'default'

invertStickyHeaders​

スティッキーヘッダーがScrollViewの上部ではなく下部に固定されるべきかどうか。これは通常、反転されたScrollViewと共に使用されます。

型デフォルト
boolfalse

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
​

許可される最大ズームスケール。

型デフォルト
number1.0

minimumZoomScale
iOS
​

許可される最小ズームスケール。

型デフォルト
number1.0

nestedScrollEnabled
Android
​

Android APIレベル21以降でネストされたスクロールを有効にします。

型デフォルト
boolfalse

onContentSizeChange​

ScrollViewのスクロール可能なコンテンツビューが変更されたときに呼び出されます。

ハンドラ関数は、コンテンツの幅と高さ (contentWidth, contentHeight) の2つのパラメータを受け取ります。

このScrollViewがレンダリングするコンテンツコンテナにアタッチされたonLayoutハンドラを使用して実装されています。

型
function

onMomentumScrollBegin​

慣性スクロールが開始されたときに呼び出されます (ScrollViewが滑り始めることで発生するスクロール)。

型
function

onMomentumScrollEnd​

慣性スクロールが終了したときに呼び出されます (ScrollViewが滑って停止するときに発生するスクロール)。

型
function

onScroll​

スクロール中にフレームごとに最大1回発生します。イベントは次の形式を持ちます (指定されていない型を持つ値はすべて数値です)

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}
  }
}
型
function

onScrollBeginDrag​

ユーザーがスクロールビューのドラッグを開始したときに呼び出されます。

型
function

onScrollEndDrag​

ユーザーがスクロールビューのドラッグを停止し、スクロールビューが停止するか滑り始めたときに呼び出されます。

型
function

onScrollToTop
iOS
​

ステータスバーがタップされた後、スクロールビューが一番上にスクロールしたときに発生します。

型
function

overScrollMode
Android
​

overScrollモードのデフォルト値を上書きするために使用されます。

可能な値

  • 'auto' - コンテンツが十分に大きく、意味のあるスクロールができる場合にのみ、ユーザーがこのビューをオーバースクロールできるようにします。
  • 'always' - ユーザーが常にこのビューをオーバースクロールできるようにします。
  • 'never' - ユーザーがこのビューをオーバースクロールできないようにします。
型デフォルト
enum('auto', 'always', 'never')'auto'

pagingEnabled​

trueの場合、スクロールビューはスクロール時にスクロールビューのサイズの倍数で停止します。これは水平ページネーションに使用できます。

型デフォルト
boolfalse

persistentScrollbar
Android
​

スクロールバーが使用されていないときに透明にならないようにします。

型デフォルト
boolfalse

pinchGestureEnabled
iOS
​

trueの場合、ScrollViewはピンチジェスチャーを使用してズームイン/ズームアウトを許可します。

型デフォルト
booltrue

refreshControl​

RefreshControlコンポーネントは、ScrollViewにプル・トゥ・リフレッシュ機能を提供するために使用されます。垂直方向のScrollView（horizontalプロパティがfalseである必要がある）でのみ機能します。

RefreshControl を参照してください。

型
element

removeClippedSubviews​

警告

このプロパティを使用すると、状況によってはバグ（コンテンツの欠落）が発生する可能性があります。自己責任でご使用ください。

true の場合、画面外の子ビューは、画面外になったときにネイティブのバックアップスーパービューから削除されます。これにより、大きなリストのスクロールパフォーマンスが向上する可能性があります。Androidではデフォルト値は true です。

型
boolean

scrollEnabled​

falseの場合、ビューはタッチ操作でスクロールできません。

scrollTo を呼び出すことで、ビューは常にスクロールできることに注意してください。

型デフォルト
booltrue

scrollEventThrottle​

スクロール中にスクロールイベントが発火する頻度を、ミリ秒単位の時間間隔で制限します。これは、スクロールに応じて高価な処理が実行される場合に役立つことがあります。デバイスのリフレッシュレートに関係なく、16 以下の値はスロットリングを無効にします。

型デフォルト
number0

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 の場合、スクロールビューはそのコンテンツサイズを超えてプログラム的にスクロールできます。

型デフォルト
boolfalse

scrollsToTop
iOS
​

trueの場合、ステータスバーがタップされると、スクロールビューは上部にスクロールします。

型デフォルト
booltrue

showsHorizontalScrollIndicator​

true の場合、水平スクロールインジケーターを表示します。

型デフォルト
booltrue

showsVerticalScrollIndicator​

true の場合、垂直スクロールインジケーターを表示します。

型デフォルト
booltrue

snapToAlignment​

snapToInterval が設定されている場合、snapToAlignment はスナップとスクロールビューの関係を定義します。

可能な値

  • 'start' は、スナップを左（水平）または上（垂直）に合わせます。
  • 'center' は、スナップを中央に合わせます。
  • 'end' は、スナップを右（水平）または下（垂直）に合わせます。
型デフォルト
enum('start', 'center', 'end')'start'

snapToEnd​

snapToOffsets と組み合わせて使用します。デフォルトでは、リストの末尾がスナップオフセットとしてカウントされます。この動作を無効にし、リストが末尾と最後の snapToOffsets オフセットの間で自由にスクロールできるようにするには、snapToEnd を false に設定します。

型デフォルト
booltrue

snapToInterval​

設定されている場合、スクロールビューは snapToInterval の値の倍数で停止します。これは、スクロールビューより長さが小さい子要素をページネーションするために使用できます。通常は snapToAlignment と decelerationRate="fast" と組み合わせて使用されます。設定の自由度が低い pagingEnabled プロパティを上書きします。

型
number

snapToOffsets​

設定されている場合、スクロールビューは定義されたオフセットで停止します。これは、スクロールビューよりも長さが小さい様々なサイズの子要素をページネーションするために使用できます。通常は decelerationRate="fast" と組み合わせて使用されます。設定の自由度が低い pagingEnabled および snapToInterval プロパティを上書きします。

型
array of number

snapToStart​

snapToOffsets と組み合わせて使用します。デフォルトでは、リストの先頭がスナップオフセットとしてカウントされます。この動作を無効にし、リストが先頭と最初の snapToOffsets オフセットの間で自由にスクロールできるようにするには、snapToStart を false に設定します。

型デフォルト
booltrue

stickyHeaderHiddenOnScroll​

true に設定すると、スティッキーヘッダーはリストを下にスクロールすると非表示になり、上にスクロールするとリストの上部に固定されます。

型デフォルト
boolfalse

stickyHeaderIndices​

スクロール時にどの子供を画面上部に固定するかを決定する子のインデックスの配列です。例えば、stickyHeaderIndices={[0]} を渡すと、最初の子供がスクロールビューの上部に固定されます。また、[x,y,z] のように使用して、複数のアイテムが上部にあるときに固定することもできます。このプロパティは horizontal={true} とは併用できません。

型
array of number

zoomScale
iOS
​

スクロールビューコンテンツの現在のスケール。

型デフォルト
number1.0

Methods​

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 になります。