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

ScrollView

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

ScrollViewは、 unbounded-heightの子要素をboundedコンテナに含める（スクロールインタラクションを介して）ため、機能するには制限された高さが必要であることに注意してください。 ScrollViewの高さを制限するには、ビューの高さを直接設定する（推奨されない）か、すべての親ビューの高さに制限があることを確認してください。ビュー階層に{flex: 1}を転送し忘れると、ここでエラーが発生する可能性があり、要素インスペクターで簡単にデバッグできます。

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

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

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

表示したいアイテムのリストが非常に長く、画面数個分のコンテンツがあるとします。すべてを一度にJSコンポーネントとネイティブビューを作成すると、表示されないものも多く、レンダリングの速度低下とメモリ使用量の増加につながります。

ここでFlatListが登場します。 FlatListは、アイテムが表示されようとしているときに遅延レンダリングし、画面から大きくスクロールアウトしたアイテムを削除して、メモリと処理時間を節約します。

FlatListは、アイテム間にセパレータをレンダリングしたり、複数の列、無限スクロール読み込み、またはその他の標準でサポートされている機能を使用したい場合にも便利です。

例​

リファレンス

Props​

View Props​

View Propsを継承します。

StickyHeaderComponent​

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

タイプ
コンポーネント、要素

alwaysBounceHorizontal
iOS
​

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

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

alwaysBounceVertical
iOS
​

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

タイプデフォルト
boolvertical={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
  }
});
タイプ
ビュースタイル

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')、数値'normal'

directionalLockEnabled
iOS
​

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

タイプデフォルト
boolfalse

disableIntervalMomentum​

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

タイプデフォルト
boolfalse

disableScrollViewPanResponder​

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

タイプデフォルト
boolfalse

endFillColor
Android
​

スクロールビューがコンテンツの塗りつぶしよりも多くのスペースを占める場合があります。この場合、このpropはスクロールビューの残りの部分を色で塗りつぶし、背景を設定して不要なオーバードローを作成することを回避します。これは、一般的なケースでは必要のない高度な最適化です。

タイプ
色

fadingEdgeLength
Android
​

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

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

タイプデフォルト
数値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を使用すると、調整が行われる前にユーザーが上部のしきい値内にいた場合、調整後、コンテンツが自動的に上部にスクロールするようにできます。これは、チャットのようなアプリケーションで、新しいメッセージがスクロールして表示されるようにしたいが、ユーザーが上にスクロールしていて、大きくスクロールすると disruptive な場合はそうしたくない場合にも役立ちます。

注意点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+でネストされたスクロールを有効にします。

タイプデフォルト
boolfalse

onContentSizeChange​

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

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

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

タイプ
function（関数）

onMomentumScrollBegin​

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

タイプ
function（関数）

onMomentumScrollEnd​

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

タイプ
function（関数）

onScroll​

スクロール中にフレームあたり最大1回発生します。イベントは次の形状を持ちます（すべての値は数値です）

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

オーバースクロールモードのデフォルト値をオーバーライドするために使用されます。

可能な値

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

pagingEnabled​

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

タイプデフォルト
boolfalse

persistentScrollbar（永続スクロールバー）
Android
​

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

タイプデフォルト
boolfalse

pinchGestureEnabled（ピンチジェスチャ有効）
iOS
​

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

タイプデフォルト
booltrue

refreshControl​

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

RefreshControlを参照してください。

タイプ
element（要素）

removeClippedSubviews​

実験的：trueの場合、オフスクリーンの子ビュー（overflow値がhidden）は、オフスクリーンになるとネイティブバッキングスーパービューから削除されます。これは、長いリストのスクロールパフォーマンスを向上させることができます。

タイプデフォルト
boolfalse

scrollEnabled​

falseの場合、ビューはタッチインタラクションによってスクロールできません。

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

タイプデフォルト
booltrue

scrollEventThrottle​

スクロール中にスクロールイベントが発生する頻度を制限します。ミリ秒単位の時間間隔として指定します。スクロールに応じて負荷の高い作業が実行される場合に役立ちます。値が≤ 16の場合、デバイスのリフレッシュレートに関係なく、スロットリングは無効になります。

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

タイプデフォルト
boolfalse

scrollsToTop (トップへのスクロール)
iOS
​

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

タイプデフォルト
booltrue

showsHorizontalScrollIndicator​

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

タイプデフォルト
booltrue

showsVerticalScrollIndicator​

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

タイプデフォルト
booltrue

snapToAlignment (スナップアラインメント)
iOS
​

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

可能な値

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

snapToEnd​

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

タイプデフォルト
booltrue

snapToInterval​

設定すると、スクロールビューはsnapToIntervalの値の倍数で停止します。これは、スクロールビューよりも短い長さを持つ子をページングするために使用できます。通常、snapToAlignmentおよびdecelerationRate="fast"と組み合わせて使用​​されます。設定が簡単なpagingEnabledプロパティよりも優先されます。

タイプ
数値

snapToOffsets​

設定すると、スクロールビューは定義されたオフセットで停止します。これは、スクロールビューよりも短い長さのさまざまなサイズの子をページングするために使用できます。通常、decelerationRate="fast"と組み合わせて使用​​されます。設定が簡単なpagingEnabledおよびsnapToIntervalプロパティよりも優先されます。

タイプ
数値の配列

snapToStart​

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

タイプデフォルト
booltrue

stickyHeaderHiddenOnScroll​

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

タイプデフォルト
boolfalse

stickyHeaderIndices​

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

タイプ
数値の配列

zoomScale（ズームスケール）
iOS
​

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

タイプデフォルト
数値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})

注: この奇妙な関数シグネチャは、歴史的な理由により、オプションオブジェクトの代わりに個別の引数も受け入れるためです。これは、あいまいさ（x の前に y が来る）があるため非推奨となっており、使用しないでください。

scrollToEnd()​

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

垂直方向の ScrollView の場合は、一番下までスクロールします。水平方向の ScrollView の場合は、右端までスクロールします。

スムーズなアニメーションスクロールには scrollToEnd({animated: true}) を、即時スクロールには scrollToEnd({animated: false}) を使用します。オプションが渡されない場合、animated はデフォルトで true になります。