NavigationContainer

NavigationContainer は、アプリの状態を管理し、最上位のナビゲーターをアプリ環境にリンクする役割を担います。

コンテナはプラットフォーム固有の統合を処理し、さまざまな便利な機能を提供します。

1. linking プロパティによるディープリンク統合。
2. 画面トラッキング、状態の永続化など、状態の変化を通知します。
3. React NativeのBackHandler APIを使用して、Androidでのシステム戻るボタンを処理します。

使用方法

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

const Stack = createNativeStackNavigator();

export default function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator>{/* ... */}</Stack.Navigator>
    </NavigationContainer>
  );
}

Ref

コンテナにref をアタッチして、さまざまなヘルパーメソッド（例：ナビゲーションアクションのディスパッチ）にアクセスすることもできます。これは、Reduxミドルウェアなど、navigation プロパティにアクセスできないまれな場合に使用してください。

例

import {
  NavigationContainer,
  useNavigationContainerRef,
} from '@react-navigation/native';

function App() {
  const navigationRef = useNavigationContainerRef(); // You can also use a regular ref with `React.useRef()`

  return (
    <View style={{ flex: 1 }}>
      <Button onPress={() => navigationRef.navigate('Home')}>Go home</Button>
      <NavigationContainer ref={navigationRef}>{/* ... */}</NavigationContainer>
    </View>
  );
}

Try this example on Snack

通常のrefオブジェクトを使用する場合は、リンクが有効になっている場合など、一部の状況ではrefが最初はnullになる可能性があることに注意してください。refが初期化されていることを確認するには、onReady コールバックを使用して、ナビゲーションコンテナのマウントが完了したときに通知を受けることができます。

navigationプロパティを使用せずにナビゲートするガイドで詳細をご覧ください。

refのメソッド

refオブジェクトには、navigate、goBackなど、一般的なナビゲーションメソッドが含まれています。詳細については、CommonActionsのドキュメントを参照してください。

例

navigationRef.navigate(name, params);

これらのメソッドはすべて、現在フォーカスされている画面内で呼び出されたかのように動作します。これらのアクションを処理するナビゲーターがレンダリングされている必要があることに注意することが重要です。

これらのメソッドに加えて、refオブジェクトには次の特別なメソッドも含まれています。

isReady

isReadyメソッドは、ナビゲーションツリーの準備が完了しているかどうかを示すboolean値を返します。ナビゲーションツリーは、NavigationContainerに少なくとも1つのナビゲーターが含まれ、すべてのナビゲーターのマウントが完了したときに準備完了となります。

これは、エラーが発生することなくナビゲーションアクションをディスパッチできるかどうかを判断するために使用できます。初期化の処理で詳細をご覧ください。

resetRoot

resetRootメソッドを使用すると、ナビゲーションツリーの状態を指定された状態オブジェクトにリセットできます。

navigationRef.resetRoot({
  index: 0,
  routes: [{ name: 'Profile' }],
});

resetメソッドとは異なり、これは現在フォーカスされている画面のナビゲーターではなく、ルートナビゲーターに対して作用します。

getRootState

getRootStateメソッドは、ナビゲーションツリー内のすべてのナビゲーターのナビゲーション状態を含むナビゲーション状態オブジェクトを返します。

const state = navigationRef.getRootState();

現在レンダリングされているナビゲーターがない場合、返されるstateオブジェクトはundefinedになります。

getCurrentRoute

getCurrentRouteメソッドは、ナビゲーションツリー全体で現在フォーカスされている画面のルートオブジェクトを返します。

const route = navigationRef.getCurrentRoute();

現在レンダリングされているナビゲーターがない場合、返されるrouteオブジェクトはundefinedになります。

getCurrentOptions

getCurrentOptionsメソッドは、ナビゲーションツリー全体で現在フォーカスされている画面のオプションを返します。

const options = navigationRef.getCurrentOptions();

現在レンダリングされているナビゲーターがない場合、返されるoptionsオブジェクトはundefinedになります。

addListener

addListenerメソッドを使用すると、次のイベントをリスンできます。

state

このイベントは、ナビゲーションツリー内の任意のナビゲーターでナビゲーション状態が変更されるたびにトリガーされます。

const unsubscribe = navigationRef.addListener('state', (e) => {
  // You can get the raw navigation state (partial state object of the root navigator)
  console.log(e.data.state);

  // Or get the full state object with `getRootState()`
  console.log(navigationRef.getRootState());
});

これはonStateChangeメソッドと類似しています。唯一の違いは、onStateChangeのstate引数には常に完全な状態オブジェクトが含まれるのに対し、e.data.stateオブジェクトには部分的な状態オブジェクトが含まれる可能性があることです。

options

このイベントは、ナビゲーションツリー内の現在フォーカスされている画面のオプションが変更されるたびにトリガーされます。

const unsubscribe = navigationRef.addListener('options', (e) => {
  // You can get the new options for the currently focused screen
  console.log(e.data.options);
});

プロパティ

initialState

ナビゲーターの初期状態を受け取るプロパティ。ディープリンク、状態の永続化などの場合に役立ちます。

例

<NavigationContainer initialState={initialState}>
  {/* ... */}
</NavigationContainer>

カスタムの初期状態オブジェクトを提供すると、リンク設定またはブラウザのURLから取得された初期状態オブジェクトが上書きされます。初期状態オブジェクトを提供する場合は、Webでは渡さないようにし、処理するディープリンクがないことを確認してください。

例

const initialUrl = await Linking.getInitialURL();

if (Platform.OS !== 'web' && initialUrl == null) {
  // Only restore state if there's no deep link and we're not on web
}

状態の永続化ガイドで、状態の永続化と復元の詳細をご覧ください。

onStateChange

警告

ナビゲーターの状態オブジェクトは内部的なものであり、マイナーリリースで変更される可能性があることを考慮してください。本当に必要な場合を除き、ナビゲーション状態状態オブジェクトのプロパティ（indexとroutesを除く）を使用しないでください。状態オブジェクトの構造に依存せずに達成できない機能がある場合は、問題を提起してください。

ナビゲーション状態が変更されるたびに呼び出される関数。引数として新しいナビゲーション状態を受け取ります。

フォーカスされている画面の追跡、ナビゲーション状態の永続化などに使用できます。

例

<NavigationContainer
  onStateChange={(state) => console.log('New state is', state)}
>
  {/* ... */}
</NavigationContainer>

onReady

ナビゲーションコンテナとそのすべての子が初めてマウントされた後に呼び出される関数。次のような場合に使用できます。

• refが使用可能であることを確認します。refの初期化に関するドキュメントで詳細をご覧ください。
• ネイティブのスプラッシュスクリーンを非表示にする

例

<NavigationContainer
  onReady={() => console.log('Navigation container is ready')}
>
  {/* ... */}
</NavigationContainer>

onUnhandledAction

ナビゲーションアクションがナビゲーターによって処理されなかった場合に呼び出される関数。

デフォルトでは、React Navigationは、アクションが処理されなかった場合に開発時のみのエラーメッセージを表示します。カスタム関数を提供することで、デフォルトの動作を上書きできます。

linking

ディープリンク、ブラウザでのURLサポートなどに使用されるリンク統合の設定。

例

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

function App() {
  const linking = {
    prefixes: ['https://mychat.com', 'mychat://'],
    config: {
      screens: {
        Home: 'feed/:sort',
      },
    },
  };

  return (
    <NavigationContainer linking={linking} fallback={<Text>Loading...</Text>}>
      {/* content */}
    </NavigationContainer>
  );
}

リンク設定ガイドで、ディープリンクとURL統合の設定方法の詳細をご覧ください。

オプション

linking.prefixes

処理するURLプレフィックス。カスタムスキームとユニバーサルリンクの両方をサポートするために、複数のプレフィックスを提供できます。

これらのプレフィックスと一致するURLのみが処理されます。解析前にプレフィックスはURLから削除されます。

例

<NavigationContainer
  linking={{
    prefixes: ['https://mychat.com', 'mychat://'],
    config: {
      screens: {
        Chat: 'feed/:sort',
      },
    },
  }}
>
  {/* content */}
</NavigationContainer>

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

linking.config

パスの解析方法を微調整するための設定。configオブジェクトは、アプリ内のナビゲーターの構造を表す必要があります。

たとえば、Home画面内にCatalog画面があり、item/:idパターンを処理したい場合

{
  screens: {
    Home: {
      screens: {
        Catalog: {
          path: 'item/:id',
          parse: {
            id: Number,
          },
        },
      },
    },
  }
}

解析のオプションはオブジェクトまたは文字列にすることができます。

{
  screens: {
    Catalog: 'item/:id',
  }
}

文字列を指定すると、pathオプションを提供することと同じです。

pathオプションは、パスと照合するパターンです。:で始まるセグメントは、同じ名前のパラメーターとして認識されます。たとえば、item/42は{ name: 'item', params: { id: '42' } }として解析されます。

initialRouteNameオプションは、そこに渡されたルート名がナビゲーターの状態に存在することを保証します。例：config

{
  screens: {
    Home: {
      initialRouteName: 'Feed',
      screens: {
        Catalog: {
          path: 'item/:id',
          parse: {
            id: Number,
          },
        },
        Feed: 'feed',
      },
    },
  }
}

およびURL：/item/42の場合、状態は次のようになります。

{
  routes: [
    {
      name: 'Home',
      state: {
        index: 1,
        routes: [
          {
            name: 'Feed'
          },
          {
            name: 'Catalog',
            params: { id: 42 },
          },
        ],
      },
    },
  ],
}

parseオプションは、パラメーターの解析方法を制御します。ここでは、キーとして解析するパラメーターの名前と、パラメーターの文字列値を受け取って解析された値を返す関数を指定できます。

{
  screens: {
    Catalog: {
      path: 'item/:id',
      parse: {
        id: id => parseInt(id, 10),
      },
    },
  }
}

パラメーターの解析にカスタム関数が提供されていない場合、文字列として解析されます。

linking.enabled

リンク統合を有効または無効にするためのオプションのブール値。linkingプロパティが指定されている場合はtrueがデフォルトです。

linking.getInitialURL

デフォルトでは、linkingはReact NativeのLinking APIと統合し、Linking.getInitialURL()を使用してディープリンクの組み込みサポートを提供します。ただし、Branchのような他のソースからのリンク、またはFirebaseなどを使ったプッシュ通知を処理することも必要になる場合があります。

初期URLとして使用するリンクを返すカスタムgetInitialURL関数を指定できます。getInitialURL関数は、処理するURLがある場合はstringを、そうでない場合はundefinedを返す必要があります。

たとえば、ディープリンクとFirebase通知の両方を処理するために、次のようなことができます。

import messaging from '@react-native-firebase/messaging';

<NavigationContainer
  linking={{
    prefixes: ['https://mychat.com', 'mychat://'],
    config: {
      screens: {
        Chat: 'feed/:sort',
      },
    },
    async getInitialURL() {
      // Check if app was opened from a deep link
      const url = await Linking.getInitialURL();

      if (url != null) {
        return url;
      }

      // Check if there is an initial firebase notification
      const message = await messaging().getInitialNotification();

      // Get the `url` property from the notification which corresponds to a screen
      // This property needs to be set on the notification payload when sending it
      return message?.data?.url;
    },
  }}
>
  {/* content */}
</NavigationContainer>;

このオプションはWebでは使用できません。

linking.subscribe

getInitialURLと同様に、デフォルトのディープリンク処理の代わりに、着信リンクを処理するカスタムsubscribe関数を指定できます。subscribe関数はリスナーを引数として受け取り、処理する新しいURLがあるたびにURL文字列で呼び出すことができます。設定したイベントリスナーの登録を解除できるクリーンアップ関数を返す必要があります。

たとえば、ディープリンクとFirebase通知の両方を処理するために、次のようなことができます。

import messaging from '@react-native-firebase/messaging';

<NavigationContainer
  linking={{
    prefixes: ['https://mychat.com', 'mychat://'],
    config: {
      screens: {
        Chat: 'feed/:sort',
      },
    },
    subscribe(listener) {
      const onReceiveURL = ({ url }: { url: string }) => listener(url);

      // Listen to incoming links from deep linking
      const subscription = Linking.addEventListener('url', onReceiveURL);

      // Listen to firebase push notifications
      const unsubscribeNotification = messaging().onNotificationOpenedApp(
        (message) => {
          const url = message.data?.url;

          if (url) {
            // Any custom logic to check whether the URL needs to be handled
            //...

            // Call the listener to let React Navigation handle the URL
            listener(url);
          }
        }
      );

      return () => {
        // Clean up the event listeners
        subscription.remove();
        unsubscribeNotification();
      };
    },
  }}
>
  {/* content */}
</NavigationContainer>

このオプションはWebでは使用できません。

linking.getStateFromPath

独自のインプリメンテーションを提供することで、React Navigationがリンクを状態オブジェクトにパースする方法をオプションでオーバーライドできます。

例

<NavigationContainer
  linking={{
    prefixes: ['https://mychat.com', 'mychat://'],
    config: {
      screens: {
        Chat: 'feed/:sort',
      },
    },
    getStateFromPath(path, config) {
      // Return a state object here
      // You can also reuse the default logic by importing `getStateFromPath` from `@react-navigation/native`
    },
  }}
>
  {/* content */}
</NavigationContainer>

linking.getPathFromState

独自のインプリメンテーションを提供することで、React Navigationが状態オブジェクトをリンクにシリアライズする方法をオプションでオーバーライドできます。getStateFromPathを指定した場合、適切なWebサポートにはこれが必要です。

例

<NavigationContainer
  linking={{
    prefixes: ['https://mychat.com', 'mychat://'],
    config: {
      screens: {
        Chat: 'feed/:sort',
      },
    },
    getPathFromState(state, config) {
      // Return a path string here
      // You can also reuse the default logic by importing `getPathFromState` from `@react-navigation/native`
    },
  }}
>
  {/* content */}
</NavigationContainer>

fallback

ディープリンクを解決している間のフォールバックとして使用するReact要素。デフォルトはnullです。

ネイティブのスプラッシュスクリーンがある場合は、fallbackプロップの代わりにonReadyを使用してください。

documentTitle

デフォルトでは、React NavigationはWebでドキュメントタイトルを自動的に更新して、フォーカスされている画面のtitleオプションに合わせます。このプロップを使用して、無効化したり、カスタマイズしたりできます。次のオプションを持つ構成オブジェクトを受け入れます。

documentTitle.enabled

ドキュメントタイトルの処理を有効にするかどうか。デフォルトはtrueです。

documentTitle.formatter

タイトルテキストをカスタマイズする場合に使用するカスタムフォーマッタ。デフォルトは…

(options, route) => options?.title ?? route?.name;

例

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

function App() {
  return (
    <NavigationContainer
      documentTitle={{
        formatter: (options, route) =>
          `${options?.title ?? route?.name} - My Cool App`,
      }}
    >
      {/* content */}
    </NavigationContainer>
  );
}

theme

ヘッダー、タブバーなどのナビゲーションコンポーネントに使用するカスタムテーマ。詳細と使用方法については、テーマガイドを参照してください。

independent

警告

これは高度なユースケースです。本当に必要であると100％確信していない限り、使用しないでください。

このナビゲーションコンテナが親コンテナから独立しているかどうか。これをtrueに設定すると、このコンテナは別のコンテナ内にネストできません。trueに設定すると、子ナビゲータは親コンテナから切断され、それらの間でのナビゲーションは許可されなくなります。

一般的なReact Nativeアプリでは、これをtrueに設定したくないでしょう。これは、独自のミニアプリのように動作し、外部の画面に移動する必要がないナビゲーションツリーがある場合にのみ役立ちます。

モーダルやボトムシートなどのサードパーティのコンポーネントと統合する必要がある場合は、これを使用しないでください。カスタムナビゲータの使用を検討してください。