ネイティブスタックナビゲーター

ネイティブスタックナビゲーターは、新しい画面がスタックの一番上に配置される画面間遷移をアプリで実現する方法を提供します。

このナビゲーターは、iOSではネイティブAPIの`UINavigationController`、Androidでは`Fragment`を使用するため、`createNativeStackNavigator`で構築されたナビゲーションは、これらのAPI上にネイティブに構築されたアプリと全く同じ動作とパフォーマンス特性を持ちます。また、`react-native-web` を使用して、基本的なWebサポートも提供します。

`@react-navigation/native-stack`はネイティブのパフォーマンスを提供し、iOSの大規模タイトルなどのネイティブ機能を公開しますが、ニーズによっては`@react-navigation/stack`ほどカスタマイズできない場合があります。そのため、このナビゲーターでは不可能なカスタマイズが必要な場合は、よりカスタマイズ可能なJavaScriptベースの実装である`@react-navigation/stack`の使用を検討してください。

インストール

このナビゲーターを使用するには、`@react-navigation/native`とその依存関係（このガイドに従ってください）がインストールされていることを確認し、次に`@react-navigation/native-stack`をインストールします。

npm

npm install @react-navigation/native-stack

Yarn

yarn add @react-navigation/native-stack

pnpm

pnpm add @react-navigation/native-stack

API定義

💡 `createNativeStackNavigator`の使用中にバグが発生した場合は、`react-navigation`リポジトリではなく、`react-native-screens`で問題を報告してください！

このナビゲーターを使用するには、`@react-navigation/native-stack`からインポートします。

import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function MyStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={Home} />
      <Stack.Screen name="Notifications" component={Notifications} />
      <Stack.Screen name="Profile" component={Profile} />
      <Stack.Screen name="Settings" component={Settings} />
    </Stack.Navigator>
  );
}

プロパティ

`Stack.Navigator`コンポーネントは、次のプロパティを受け付けます。

`id`

ナビゲーターの一意のID（オプション）。子ナビゲーターでこのナビゲーターを参照するために、`navigation.getParent`と共に使用できます。

`initialRouteName`

ナビゲーターの初回読み込み時にレンダリングするルートの名前。

`screenOptions`

ナビゲーター内の画面に使用するデフォルトのオプション。

オプション

次のオプションを使用して、ナビゲーター内の画面を構成できます。

`title`

`headerTitle`のフォールバックとして使用できる文字列。

`headerBackButtonMenuEnabled`

iOS >= 14の戻るボタンを長押ししたときにメニューを表示するかどうかを示すブール値。デフォルトは`true`。

`react-native-screens`バージョン>=3.3.0が必要です。

iOSでのみサポートされています。

`headerBackVisible`

ヘッダーで戻るボタンを表示するかどうか。`headerLeft`を指定している場合、これを使用して`headerLeft`と共に戻るボタンを表示できます。

スタックの最初の画面では効果がありません。

`headerBackTitle`

iOSの戻るボタンで使用されるタイトル文字列。前のシーンのタイトル、または十分なスペースがない場合は「戻る」がデフォルトです。非表示にするには`headerBackTitleVisible: false`を使用します。

iOSでのみサポートされています。

`headerBackTitleVisible`

戻るボタンのタイトルを表示するかどうか。

iOSでのみサポートされています。

`headerBackTitleStyle`

ヘッダーの戻るボタンのタイトルのスタイルオブジェクト。サポートされているプロパティ

• fontFamily
• fontSize

iOSでのみサポートされています。

`headerBackImageSource`

ヘッダーに戻るボタンのアイコンとして表示する画像。プラットフォームの戻るボタンのアイコン画像がデフォルトです。

• iOSでは山かっこ
• Androidでは矢印

`headerLargeStyle`

大規模タイトルが表示されている場合のヘッダーのスタイル。`headerLargeTitle`が`true`で、スクロール可能なコンテンツのエッジがヘッダーの対応するエッジに達した場合に、大規模タイトルが表示されます。

サポートされているプロパティ

• backgroundColor

iOSでのみサポートされています。

`headerLargeTitle`

スクロール時に通常のヘッダーに折り畳まれる大規模タイトル付きのヘッダーを有効にするかどうか。

スクロール時に大規模タイトルを折り畳むには、画面の内容を`ScrollView`や`FlatList`などのスクロール可能なビューでラップする必要があります。スクロール可能な領域が画面全体を満たしていない場合、大規模タイトルはスクロール時に折り畳まれません。また、`ScrollView`、`FlatList`などで`contentInsetAdjustmentBehavior="automatic"`を指定する必要があります。

iOSでのみサポートされています。

`headerLargeTitleShadowVisible`

大規模タイトルが表示されている場合にヘッダーのドロップシャドウを表示するかどうか。

`headerLargeTitleStyle`

ヘッダーの大規模タイトルのスタイルオブジェクト。サポートされているプロパティ

• fontFamily
• fontSize
• fontWeight
• color

iOSでのみサポートされています。

`headerShown`

ヘッダーを表示するかどうか。ヘッダーはデフォルトで表示されます。これを`false`に設定すると、ヘッダーが非表示になります。

`headerStyle`

ヘッダーのスタイルオブジェクト。サポートされているプロパティ

• backgroundColor

`headerShadowVisible`

ヘッダーの高さの影（Android）または下部の境界線（iOS）を非表示にするかどうか。

`headerTransparent`

ナビゲーションバーが半透明かどうかを示すブール値。

デフォルトは`false`。これを`true`に設定すると、ヘッダーが絶対配置になり、ヘッダーが下にあるコンテンツに重なるように浮き上がり、`headerStyle`で指定しない限り背景色が`transparent`に変更されます。

半透明のヘッダーやぼやけた背景を使用する場合に便利です。

コンテンツをヘッダーの下に表示したくない場合は、コンテンツにトップマージンを手動で追加する必要があります。React Navigationは自動的には行いません。

ヘッダーの高さを取得するには、`HeaderHeightContext`をReactのContext APIまたは`useHeaderHeight`と共に使用できます。

`headerBlurEffect`

半透明ヘッダーのぼかし効果。機能させるには、`headerTransparent`オプションを`true`に設定する必要があります。

サポートされている値

• extraLight
• light
• dark
• regular
• prominent
• systemUltraThinMaterial
• systemThinMaterial
• systemMaterial
• systemThickMaterial
• systemChromeMaterial
• systemUltraThinMaterialLight
• systemThinMaterialLight
• systemMaterialLight
• systemThickMaterialLight
• systemChromeMaterialLight
• systemUltraThinMaterialDark
• systemThinMaterialDark
• systemMaterialDark
• systemThickMaterialDark
• systemChromeMaterialDark

iOSでのみサポートされています。

`headerBackground`

ヘッダーの背景としてレンダリングするReact要素を返す関数。画像やグラデーションなどの背景を使用する場合に便利です。

`headerTintColor`

ヘッダーのティントカラー。戻るボタンとタイトルの色を変更します。

`headerLeft`

ヘッダーの左側に表示するReact要素を返す関数。戻るボタンを置き換えます。左側の要素と共に戻るボタンを表示するには、`headerBackVisible`を参照してください。

`headerRight`

ヘッダーの右側に表示するReact要素を返す関数。

`headerTitle`

ヘッダーで使用される文字列、またはReact要素を返す関数。デフォルトは`title`または画面の名前です。

関数が渡されると、オプションオブジェクト内の`tintColor`と`children`が引数として受け取られます。タイトル文字列は`children`に渡されます。

関数でカスタム要素をレンダリングする場合、タイトルのアニメーションは機能しません。

`headerTitleAlign`

ヘッダータイトルの配置方法。可能な値

• left
• center

iOS以外のプラットフォームではデフォルトで`left`。

iOSではサポートされていません。iOSでは常に`center`で、変更できません。

`headerTitleStyle`

ヘッダータイトルのスタイルオブジェクト。サポートされているプロパティ

• fontFamily
• fontSize
• fontWeight
• color

headerSearchBarOptions

iOSでネイティブの検索バーをレンダリングするためのオプションです。検索バーは静的なことはめったにないので、通常はコンポーネントの本文でheaderSearchBarOptionsナビゲーションオプションにオブジェクトを渡して制御します。また、ScrollView、FlatListなどでcontentInsetAdjustmentBehavior="automatic"を指定する必要があります。ScrollViewがない場合は、headerTransparent: falseを指定してください。

iOSとAndroidでのみサポートされています。

例

React.useLayoutEffect(() => {
  navigation.setOptions({
    headerSearchBarOptions: {
      // search bar options
    },
  });
}, [navigation]);

サポートされているプロパティを以下に説明します。

autoCapitalize

ユーザーが入力する際にテキストが自動的に大文字化されるかどうかを制御します。可能な値

• none
• words
• sentences
• characters

デフォルトはsentencesです。

autoFocus

表示時に検索バーに自動的にフォーカスするかどうか。デフォルトはfalseです。

Androidでのみサポートされています。

barTintColor

検索フィールドの背景色。デフォルトでは、バーのティントカラーは半透明です。

iOSでのみサポートされています。

tintColor

カーソルのキャレットとキャンセルボタンのテキストの色。

iOSでのみサポートされています。

cancelButtonText

デフォルトのCancelボタンテキストの代わりに使用するテキスト。

iOSでのみサポートされています。

disableBackButtonOverride

戻るボタンで検索バーのテキスト入力を閉じるかどうか。デフォルトはfalseです。

Androidでのみサポートされています。

hideNavigationBar

検索中にナビゲーションバーを非表示にするかどうかを示すブール値。デフォルトはtrueです。

iOSでのみサポートされています。

hideWhenScrolling

スクロール時に検索バーを非表示にするかどうかを示すブール値。デフォルトはtrueです。

iOSでのみサポートされています。

inputType

入力の種類。デフォルトは"text"です。

サポートされている値

• "text"
• "phone"
• "number"
• "email"

Androidでのみサポートされています。

obscureBackground

半透明のオーバーレイで基になるコンテンツを隠すかどうかを示すブール値。デフォルトはtrueです。

placeholder

検索フィールドが空の場合に表示されるテキスト。

textColor

検索フィールド内のテキストの色。

hintTextColor

検索フィールド内のヒントテキストの色。

Androidでのみサポートされています。

headerIconColor

ヘッダーに表示される検索アイコンと閉じるアイコンの色。

Androidでのみサポートされています。

shouldShowHintSearchIcon

検索バーにフォーカスがあるときに検索ヒントアイコンを表示するかどうか。デフォルトはtrueです。

Androidでのみサポートされています。

onBlur

検索バーがフォーカスを失ったときに呼び出されるコールバック。

onCancelButtonPress

キャンセルボタンが押されたときに呼び出されるコールバック。

onChangeText

テキストが変更されたときに呼び出されるコールバック。検索バーの現在のテキスト値を受け取ります。

例

const [search, setSearch] = React.useState('');

React.useLayoutEffect(() => {
  navigation.setOptions({
    headerSearchBarOptions: {
      onChangeText: (event) => setSearch(event.nativeEvent.text),
    },
  });
}, [navigation]);

header

デフォルトのヘッダーの代わりに使用するカスタムヘッダー。

ヘッダーとして表示するReact要素を返す関数を指定します。この関数は、以下のプロパティを含むオブジェクトを引数として受け取ります。

• navigation - 現在の画面のナビゲーションオブジェクト。
• route - 現在の画面のルートオブジェクト。
• options - 現在の画面のオプション。
• back - 戻るボタンのオプション。戻るボタンのラベルに使用できるtitleプロパティを含むオブジェクトが含まれています。

例

import { getHeaderTitle } from '@react-navigation/elements';

// ..

header: ({ navigation, route, options, back }) => {
  const title = getHeaderTitle(options, route.name);

  return (
    <MyHeader
      title={title}
      leftButton={
        back ? <MyBackButton onPress={navigation.goBack} /> : undefined
      }
      style={options.headerStyle}
    />
  );
};

ナビゲーター内のすべての画面にカスタムヘッダーを設定するには、ナビゲーターのscreenOptionsプロップでこのオプションを指定できます。

カスタムヘッダーを指定した場合、大きなタイトル、検索バーなどのネイティブ機能は動作しません。

statusBarAnimation

ステータスバーのアニメーションを設定します（StatusBarコンポーネントと同様）。iOSではfade、Androidではnoneがデフォルトです。

サポートされている値

• "fade"
• "none"
• "slide"

Androidでは、fadeまたはslideのいずれかを設定すると、ステータスバーの色が遷移します。iOSでは、このオプションはステータスバーの表示アニメーションに適用されます。

Info.plistファイルでView controller-based status bar appearance -> YESを設定する（または設定を削除する）必要があります。

AndroidとiOSでのみサポートされています。

statusBarHidden

この画面でステータスバーを非表示にするかどうか。

Info.plistファイルでView controller-based status bar appearance -> YESを設定する（または設定を削除する）必要があります。

AndroidとiOSでのみサポートされています。

statusBarStyle

ステータスバーの色を設定します（StatusBarコンポーネントと同様）。デフォルトはautoです。

サポートされている値

• "auto"
• "inverted"（iOSのみ）
• "dark"
• "light"

Info.plistファイルでView controller-based status bar appearance -> YESを設定する（または設定を削除する）必要があります。

AndroidとiOSでのみサポートされています。

statusBarColor

ステータスバーの色を設定します（StatusBarコンポーネントと同様）。デフォルトは初期のステータスバーの色です。

Androidでのみサポートされています。

statusBarTranslucent

ステータスバーの半透明度を設定します（StatusBarコンポーネントと同様）。デフォルトはfalseです。

Androidでのみサポートされています。

contentStyle

シーンコンテンツのスタイルオブジェクト。

customAnimationOnGesture

閉じるためのジェスチャーで、animationプロップに指定されたアニメーションを使用するかどうか。デフォルトはfalseです。

モーダルで表示される画面の動作には影響しません。

iOSでのみサポートされています。

fullScreenGestureEnabled

画面全体で閉じるためのジェスチャーを使用できるかどうか。このオプションで閉じるためのジェスチャーを使用すると、simple_pushと同じ遷移アニメーションになります。この動作は、customAnimationOnGestureプロップを設定することで変更できます。プラットフォームの制限により、デフォルトのiOSアニメーションを実現することはできません。デフォルトはfalseです。

モーダルで表示される画面の動作には影響しません。

iOSでのみサポートされています。

gestureEnabled

ジェスチャーを使用してこの画面を閉じることができるかどうか。デフォルトはtrueです。iOSでのみサポートされています。

animationTypeForReplace

この画面が別の画面を置き換えるときに使用するアニメーションの種類。デフォルトはpopです。

サポートされている値

• push: 新しい画面はpushアニメーションを実行します。
• pop: 新しい画面はpopアニメーションを実行します。

animation

画面をpushまたはpopするときのアニメーション方法。

サポートされている値

• default: プラットフォームのデフォルトアニメーションを使用します。
• fade: 画面をフェードインまたはフェードアウトします。
• fade_from_bottom: 新しい画面を下からフェードインします。
• flip: 画面を反転します。presentation: "modal"が必要です（iOSのみ）。
• simple_push: デフォルトアニメーションですが、シャドウとネイティブヘッダーの遷移はありません（iOSのみ、Androidではデフォルトアニメーションを使用）。
• slide_from_bottom: 新しい画面を下からスライドインします。
• slide_from_right: 新しい画面を右からスライドインします（Androidのみ、iOSではデフォルトアニメーションを使用）。
• slide_from_left: 新しい画面を左からスライドインします（Androidのみ、iOSではデフォルトアニメーションを使用）。
• none: 画面をアニメーションしません。

AndroidとiOSでのみサポートされています。

presentation

画面をどのように表示するか。

サポートされている値

• card: 新しい画面はスタックにpushされます。つまり、iOSではデフォルトのアニメーションは横からスライドインし、AndroidではOSのバージョンとテーマによってアニメーションが異なります。
• modal: 新しい画面はモーダルで表示されます。これにより、画面内にネストされたスタックをレンダリングすることもできます。
• transparentModal: 新しい画面はモーダルで表示されますが、さらに、前の画面が残るので、画面の背景が半透明の場合でも下のコンテンツを見ることができます。
• containedModal: iOSでは"UIModalPresentationCurrentContext"モーダルスタイルを使用し、Androidでは"modal"にフォールバックします。
• containedTransparentModal: iOSでは"UIModalPresentationOverCurrentContext"モーダルスタイルを使用し、Androidでは"transparentModal"にフォールバックします。
• fullScreenModal: iOSでは"UIModalPresentationFullScreen"モーダルスタイルを使用し、Androidでは"modal"にフォールバックします。この表示スタイルを使用する画面は、ジェスチャーで閉じることができません。
• formSheet: iOSでは"UIModalPresentationFormSheet"モーダルスタイルを使用し、Androidでは"modal"にフォールバックします。

AndroidとiOSでのみサポートされています。

orientation

画面で使用するディスプレイの向き。

サポートされている値

• default - iOSでは"portrait_down"を除く"all"に解決されます。Androidでは、システムが最適な向きを決定します。
• all: すべての向きが許可されます。
• portrait: ポー トレート向きが許可されます。
• portrait_up: 右向きの縦向き表示が許可されます。
• portrait_down: 上下逆さまの縦向き表示が許可されます。
• landscape: 横向き表示が許可されます。
• landscape_left: 左向きの横向き表示が許可されます。
• landscape_right: 右向きの横向き表示が許可されます。

AndroidとiOSでのみサポートされています。

autoHideHomeIndicator

ホームインジケータを非表示にすることを優先するかどうかを示すブール値です。デフォルトはfalseです。

iOSでのみサポートされています。

gestureDirection

画面を閉じるためにスワイプする方向を設定します。

サポートされている値

• vertical – 画面を縦方向に閉じます
• horizontal – 画面を横方向に閉じます（デフォルト）

verticalオプションを使用する場合、fullScreenGestureEnabled: true、customAnimationOnGesture: true、およびanimation: 'slide_from_bottom'オプションはデフォルトで設定されます。

iOSでのみサポートされています。

animationDuration

iOSでのslide_from_bottom、fade_from_bottom、fade、およびsimple_pushトランジションの持続時間（ミリ秒単位）を変更します。デフォルトは350です。

defaultとflipトランジションの持続時間はカスタマイズできません。

iOSでのみサポートされています。

navigationBarColor

ナビゲーションバーの色を設定します。デフォルトは初期のステータスバーの色です。

Androidでのみサポートされています。

navigationBarHidden

ナビゲーションバーを非表示にするかどうかを示すブール値です。デフォルトはfalseです。

Androidでのみサポートされています。

freezeOnBlur

非アクティブな画面の再レンダリングを防止するかどうかを示すブール値です。デフォルトはfalseです。アプリケーションの先頭でreact-native-screensパッケージのenableFreeze()を実行すると、デフォルトでtrueになります。

react-native-screensバージョン >= 3.16.0が必要です。

iOSとAndroidでのみサポートされています。

イベント

ナビゲータは、特定のアクション時にイベントを送信できます。サポートされているイベントは次のとおりです。

transitionStart

このイベントは、現在の画面のトランジションアニメーションが開始されたときに発生します。

イベントデータ

• e.data.closing - 画面が開かれているか閉じられているかを示すブール値です。

例

React.useEffect(() => {
  const unsubscribe = navigation.addListener('transitionStart', (e) => {
    // Do something
  });

  return unsubscribe;
}, [navigation]);

transitionEnd

このイベントは、現在の画面のトランジションアニメーションが終了したときに発生します。

イベントデータ

• e.data.closing - 画面が開かれたか閉じられたかを示すブール値です。

例

React.useEffect(() => {
  const unsubscribe = navigation.addListener('transitionEnd', (e) => {
    // Do something
  });

  return unsubscribe;
}, [navigation]);

ヘルパー

ネイティブスタックナビゲータは、navigationプロパティに次のメソッドを追加します。

replace

スタック内の現在の画面を新しい画面に置き換えます。このメソッドは次の引数を受け入れます。

• name - 文字列 - スタックにプッシュするルートの名前。
• params - オブジェクト - 宛先ルートに渡す画面パラメータ。

navigation.replace('Profile', { owner: 'Michaś' });

push

新しい画面をスタックの一番上にプッシュし、その画面に移動します。このメソッドは次の引数を受け入れます。

• name - 文字列 - スタックにプッシュするルートの名前。
• params - オブジェクト - 宛先ルートに渡す画面パラメータ。

navigation.push('Profile', { owner: 'Michaś' });

pop

現在の画面をスタックからポップし、前の画面に戻ります。オプションの引数（count）を受け入れ、戻る画面数を指定できます。

navigation.pop();

popToTop

最初の画面を除くスタック内のすべての画面をポップし、最初の画面に移動します。

navigation.popToTop();

例

import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function MyStack() {
  return (
    <Stack.Navigator
      initialRouteName="Home"
      screenOptions={{
        headerTintColor: 'white',
        headerStyle: { backgroundColor: 'tomato' },
      }}
    >
      <Stack.Screen
        name="Home"
        component={Home}
        options={{
          title: 'Awesome app',
        }}
      />
      <Stack.Screen
        name="Profile"
        component={Profile}
        options={{
          title: 'My profile',
        }}
      />
      <Stack.Screen
        name="Settings"
        component={Settings}
        options={{
          gestureEnabled: false,
        }}
      />
    </Stack.Navigator>
  );
}