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

ScrollView

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

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

他の内包されたレスポンダーが、このスクロールビューがレスポンダーになるのを妨げることをまだサポートしていません。

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

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

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

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

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

使用例​

リファレンス

Props​

ViewのProps​

ViewのPropsを継承します。

StickyHeaderComponent​

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

型
component, element

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
  }
});
型
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はドラッグ中に垂直または水平方向のスクロールのみにロックしようとします。

型デフォルト
boolfalse

disableIntervalMomentum​

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

型デフォルト
boolfalse

disableScrollViewPanResponder​

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

型デフォルト
boolfalse

endFillColor
Android
​

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

型
color

fadingEdgeLength
Android
​

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

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

型デフォルト
number0

horizontal​

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

型デフォルト
boolfalse

indicatorStyle
iOS
​

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

  • 'default' blackと同じです。
  • 'black', スクロールインジケーターは黒です。このスタイルは明るい背景に対して適しています。
  • '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のスクロール可能なコンテンツビューが変更されたときに呼び出されます。

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

これは、この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},
    zoomScale
  }
}
型
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​

ScrollViewに「引っぱって更新」機能を提供するために使用されるRefreshControlコンポーネント。垂直ScrollViewでのみ機能します（horizontalプロパティはfalseである必要があります）。

RefreshControlを参照してください。

型
element

removeClippedSubviews​

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

型デフォルト
boolfalse

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

型デフォルト
booltrue

snapToInterval​

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

型
number

snapToOffsets​

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

型
array of number

snapToStart​

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

型デフォルト
booltrue

stickyHeaderHiddenOnScroll​

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

型デフォルト
boolfalse

stickyHeaderIndices​

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

型
array of number

zoomScale
iOS
​

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

型デフォルト
number1.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になります。