バージョン: 6.x

ナビゲーション状態のリファレンス

ナビゲーション状態とは、React Navigationがアプリのナビゲーション構造と履歴を格納する状態のことです。状態のリセット、カスタムの初期状態の提供などの高度な操作を行う必要がある場合、ナビゲーション状態の構造を知っておくと役立ちます。

これは次のようなJavaScriptオブジェクトです。

const state = {
  type: 'stack',
  key: 'stack-1',
  routeNames: ['Home', 'Profile', 'Settings'],
  routes: [
    { key: 'home-1', name: 'Home', params: { sortBy: 'latest' } },
    { key: 'settings-1', name: 'Settings' },
  ],
  index: 1,
  stale: false,
};

すべてのナビゲーション状態オブジェクトに存在するいくつかのプロパティがあります。

type - 状態が属するナビゲーターのタイプ（例：stack、tab、drawer）。
key - ナビゲーターを識別する一意のキー。
routeNames - ナビゲーターで定義された画面の名前。これは、各画面の文字列を含む一意の配列です。
routes - ナビゲーターでレンダリングされるルートオブジェクト（画面）のリスト。スタックナビゲーターでは履歴も表します。この配列には少なくとも1つのアイテムが存在する必要があります。
index - routes配列内のフォーカスされているルートオブジェクトのインデックス。
history - 訪問した項目のリスト。これはオプションのプロパティであり、すべてのナビゲーターに存在するわけではありません。たとえば、コアのタブナビゲーターとドロワーナビゲーターにのみ存在します。 history配列内の項目の形状は、ナビゲーターによって異なる場合があります。この配列には少なくとも1つのアイテムが存在する必要があります。
stale - ナビゲーション状態は、staleプロパティが明示的にfalseに設定されていない限り、古くなったものと見なされます。つまり、状態オブジェクトは「再水和」される必要があります。

routes配列の各ルートオブジェクトには、次のプロパティが含まれる場合があります。

key - 画面の一意のキー。この画面にナビゲートするときに自動的に作成または追加されます。
name - 画面の名前。ナビゲーターコンポーネント階層で定義されます。
params - ナビゲート時に定義されるパラメーターを含むオプションのオブジェクト（例：navigate('Home', { sortBy: 'latest' })）。
state - この画面内にネストされた子ナビゲーターのナビゲーション状態を含むオプションのオブジェクト。

たとえば、ホーム画面内にネストされたタブナビゲーターを含むスタックナビゲーターは、次のようなナビゲーション状態オブジェクトを持つ可能性があります。

const state = {
  type: 'stack',
  key: 'stack-1',
  routeNames: ['Home', 'Profile', 'Settings'],
  routes: [
    {
      key: 'home-1',
      name: 'Home',
      state: {
        key: 'tab-1',
        routeNames: ['Feed', 'Library', 'Favorites'],
        routes: [
          { key: 'feed-1', name: 'Feed', params: { sortBy: 'latest' } },
          { key: 'library-1', name: 'Library' },
          { key: 'favorites-1', name: 'Favorites' },
        ],
        index: 0,
      },
    },
    { key: 'settings-1', name: 'Settings' },
  ],
  index: 1,
};

ネストされたナビゲーターがある場合でも、ナビゲーションが発生するまでrouteオブジェクトのstateプロパティは追加されないため、存在が保証されないことに注意することが重要です。

部分的な状態オブジェクト

以前、ナビゲーション状態のstaleプロパティについて言及しました。古いナビゲーション状態とは、状態オブジェクトを使用する前に、不足しているキーの追加、無効な画面の削除など、再水和または修正する必要があることを意味します。ユーザーとして、心配する必要はありません。React Navigationは、staleがfalseに設定されていない限り、状態オブジェクトの問題を自動的に修正します。カスタムルーターを作成している場合、getRehydratedStateメソッドを使用すると、状態オブジェクトを修正するためのカスタム再水和ロジックを作成できます。

これはindexプロパティにも当てはまります。indexはスタック内の最後のルートである必要があり、別の値が指定されている場合は、React Navigationがそれを修正します。たとえば、アプリのナビゲーション状態をProfileルートを表示するようにリセットし、戻ったときにHomeルートを表示したい場合、以下のように行ったとします。

navigation.reset({
  index: 0,
  routes: [{ name: 'Home' }, { name: 'Profile' }],
});

React Navigationはindexを1に修正し、ルートを表示して意図したとおりにナビゲーションを実行します。

この機能は、リセット、初期状態の提供などの操作を行う場合に役立ちます。ナビゲーション状態オブジェクトから多くのプロパティを安全に省略して、React Navigationにこれらのプロパティを追加してもらうことができるため、コードを簡略化できます。たとえば、キーのないroutes配列のみを提供でき、React Navigationが動作に必要なすべてを自動的に追加します。

const state = {
  routes: [{ name: 'Home' }, { name: 'Profile' }],
};

再水和後、次のようになります。

const state = {
  type: 'stack',
  key: 'stack-1',
  routeNames: ['Home', 'Profile', 'Settings'],
  routes: [
    { key: 'home-1', name: 'Home' },
    { key: 'settings-1', name: 'Settings' },
  ],
  index: 1,
  stale: false,
};

ここで、React Navigationはキー、ルート名、インデックスなどの欠落していたビットを埋めました。

存在しない画面などの無効なデータを提供することも可能であり、自動的に修正されます。無効な状態オブジェクトでコードを記述することはお勧めしませんが、状態の永続化などの操作を行う場合は非常に役立ちます。構成済みの画面が更新後に変更され、React Navigationが状態オブジェクトを自動的に修正しないと問題が発生する可能性があります。

ヒント

React Navigationに無効な状態を修正させたい場合は、状態オブジェクトにstale: falseがないことを確認する必要があります。 stale: falseを持つ状態オブジェクトは有効な状態オブジェクトであると見なされ、React Navigationはそれらを修正しようとしません。

initialStateで状態オブジェクトを提供する場合、React Navigationは常にそれが古い状態オブジェクトであると想定します。これにより、状態オブジェクトを余分に操作しなくても、状態の永続化などがスムーズに機能することが保証されます。

部分的な状態オブジェクト​

部分的な状態オブジェクト