メインコンテンツにスキップ
バージョン: 6.x

ナビゲーションプロップのリファレンス

アプリ内の各screenコンポーネントには、自動的にnavigationプロップが提供されます。このプロップには、ナビゲーションアクションをディスパッチするさまざまな便利な関数が含まれています。以下のような構成になっています。

  • navigation
    • navigate - 指定されたスクリーンに移動します。これはナビゲーターに基づいて異なる動作をします。
    • goBack - 前のスクリーンに戻ります。これはスタックで使用すると現在のスクリーンをポップします。
    • reset - ナビゲーターのナビゲーション状態を指定された状態に置き換えます。
    • setParams - ルートのparamsに新しいparamsをマージします。
    • dispatch - ナビゲーション状態を更新するために、アクションオブジェクトを送信します。
    • setOptions - スクリーンのオプションを更新します。
    • isFocused - スクリーンがフォーカスされているかどうかを確認します。
    • canGoBack - 現在のスクリーンから戻ることが可能かどうかを確認します。
    • getState - ナビゲーターのナビゲーション状態を取得します。
    • getParent - 親スクリーンのナビゲーションオブジェクトを取得します（存在する場合）。
    • addListener - スクリーンのイベントを購読します。
    • removeListener - スクリーンのイベントの購読を解除します。

navigationプロップは、すべてのコンポーネントに渡されるわけではないという点を強調することが重要です。自動的にこのプロップを受け取るのはscreenコンポーネントのみです。React Navigationはここで特別な処理を行っていません。たとえば、MyBackButtonコンポーネントを定義して、それをスクリーンコンポーネントの子としてレンダリングした場合、そのコンポーネントでnavigationプロップにアクセスすることはできません。ただし、コンポーネントのいずれかでnavigationプロップにアクセスしたい場合は、useNavigationフックを使用できます。

setParams/setOptionsなどは、useEffect/useLayoutEffect/componentDidMount/componentDidUpdateなどの内部でのみ呼び出す必要があります。レンダリング中やコンストラクタ内では呼び出さないでください。

現在のナビゲーターの種類に基づいて、navigationプロップにはいくつかの追加の関数が存在します。

ナビゲーターがスタックナビゲーターの場合、navigateとgoBackのいくつかの代替手段が提供されており、どちらか好きな方を使用できます。関数は次のとおりです。

  • navigation
    • replace - 現在のスクリーンを新しいスクリーンに置き換えます。
    • push - 新しいスクリーンをスタックにプッシュします。
    • pop - スタックを戻ります。
    • popToTop - スタックの最上部に戻ります。

これらのメソッドの詳細については、スタックナビゲーターのヘルパーとネイティブスタックナビゲーターのヘルパーを参照してください。

ナビゲーターがタブナビゲーターの場合、以下も利用可能です。

  • navigation
    • jumpTo - タブナビゲーター内の特定のスクリーンに移動します。

これらのメソッドの詳細については、ボトムタブナビゲーターのヘルパー、マテリアルトップタブナビゲーターのヘルパー、およびマテリアルボトムタブナビゲーターのヘルパーを参照してください。

ナビゲーターがドロワーナビゲーターの場合、以下も利用可能です。

  • navigation
    • jumpTo - ドロワーナビゲーター内の特定のスクリーンに移動します。
    • openDrawer - ドロワーを開きます。
    • closeDrawer - ドロワーを閉じます。
    • toggleDrawer - 状態を切り替えます。つまり、閉じた状態から開いた状態に、またはその逆に切り替えます。

これらのメソッドの詳細については、ドロワーナビゲーターのヘルパーを参照してください。

共通APIリファレンス​

navigationプロップとのインタラクションの大部分は、navigate、goBack、setParamsを伴います。

navigateメソッドを使用すると、アプリ内の別のスクリーンに移動できます。次の引数を取ります。

navigation.navigate(name, params)

  • name - どこかで定義されているルートの移動先名。
  • params - 移動先ルートに渡すparams。
function HomeScreen({ navigation: { navigate } }) {
  return (
    <View>
      <Text>This is the home screen of the app</Text>
      <Button
        onPress={() =>
          navigate('Profile', { names: ['Brent', 'Satya', 'Michaś'] })
        }
        title="Go to Brent's profile"
      />
    </View>
  );
}

ネイティブスタックナビゲーターでは、スクリーン名を使用してnavigateを呼び出すと、スクリーンがすでに存在するかどうかによって動作が異なります。スクリーンがスタックの履歴にすでに存在する場合、そのスクリーンに戻り、それ以降のスクリーンを削除します。スクリーンが存在しない場合は、新しいスクリーンをプッシュします。

たとえば、履歴がHome > Profile > Settingsのスタックがあり、navigate(Profile)を呼び出すと、Profileに戻り、Settingsスクリーンを削除するため、結果のスクリーンはHome > Profileになります。

デフォルトでは、スクリーンは名前で識別されます。ただし、getIdプロップを使用すると、paramsを考慮するようにカスタマイズすることもできます。

たとえば、ProfileスクリーンにgetIdプロップを指定したとします。

<Tab.Screen
  name={Profile}
  component={ProfileScreen}
  getId={({ params }) => params.userId}
/>

ここで、履歴がHome > Profile (userId: bob) > Settingsのスタックがあり、navigate(Profile, { userId: 'alice' })を呼び出すと、一致するスクリーンが見つからなかったため、新しいProfileスクリーンを追加するため、結果のスクリーンはHome > Profile (userId: bob) > Settings > Profile (userId: alice)になります。

goBack​

goBackメソッドを使用すると、ナビゲーター内の前のスクリーンに戻ることができます。

デフォルトでは、goBackは呼び出し元のスクリーンから戻ります。

function ProfileScreen({ navigation: { goBack } }) {
  return (
    <View>
      <Button onPress={() => goBack()} title="Go back from ProfileScreen" />
    </View>
  );
}

特定のスクリーンからの戻り​

次のナビゲーションスタック履歴を考えてください。

navigation.navigate({ name: SCREEN, key: SCREEN_KEY_A });
navigation.navigate({ name: SCREEN, key: SCREEN_KEY_B });
navigation.navigate({ name: SCREEN, key: SCREEN_KEY_C });
navigation.navigate({ name: SCREEN, key: SCREEN_KEY_D });

ここでスクリーン Dにいて、スクリーン Aに戻りたい場合（D、C、Bをポップ）、navigateを使用できます。

navigation.navigate({ key: SCREEN_KEY_A }); // will go to screen A FROM screen D

あるいは、スクリーン Aはスタックの最上部にあるため、navigation.popToTop()を使用できます。

reset​

resetメソッドを使用すると、ナビゲーターの状態を新しい状態に置き換えることができます。

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

resetで指定された状態オブジェクトは、既存のナビゲーション状態を新しい状態に置き換えます。つまり、既存のスクリーンを削除して新しいスクリーンを追加します。状態を変更する際に既存のスクリーンを保持したい場合は、代わりにdispatchを使用してCommonActions.resetを使用できます。

警告

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

setParams​

setParamsメソッドを使用すると、現在のスクリーンのparams（route.params）を更新できます。setParamsはReactのsetStateのように機能します。指定されたparamsオブジェクトを現在のparamsと浅くマージします。

function ProfileScreen({ navigation: { setParams } }) {
  return (
    <Button
      onPress={() =>
        setParams({
          friends:
            route.params.friends[0] === 'Brent'
              ? ['Wojciech', 'Szymon', 'Jakub']
              : ['Brent', 'Satya', 'Michaś'],
          title:
            route.params.title === "Brent's Profile"
              ? "Lucy's Profile"
              : "Brent's Profile",
        })
      }
      title="Swap title and friends"
    />
  );
}

setOptions​

setOptionsメソッドを使用すると、コンポーネント内からスクリーンオプションを設定できます。これは、コンポーネントのprops、state、またはコンテキストを使用してスクリーンを構成する必要がある場合に役立ちます。

function ProfileScreen({ navigation, route }) {
  const [value, onChangeText] = React.useState(route.params.title);

  React.useEffect(() => {
    navigation.setOptions({
      title: value === '' ? 'No title' : value,
    });
  }, [navigation, value]);

  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <TextInput
        style={{ height: 40, borderColor: 'gray', borderWidth: 1 }}
        onChangeText={onChangeText}
        value={value}
      />
      <Button title="Go back" onPress={() => navigation.goBack()} />
    </View>
  );
}

ここで指定されたオプションは、スクリーンを定義するときに指定されたオプションと浅くマージされます。

navigation.setOptionsを使用する場合は、スクリーンのoptionsプロップにプレースホルダーを指定し、navigation.setOptionsを使用して更新することをお勧めします。これにより、オプションの更新の遅延がユーザーに目立たないようにします。また、遅延ロードされたスクリーンでも機能するようにします。

React.useLayoutEffectを使用して、オプションの更新の遅延を減らすこともできます。ただし、Webをサポートし、サーバーサイドレンダリングを行っている場合は、これを行わないことをお勧めします。

注意

navigation.setOptions は、必要に応じて既存のオプションを更新する機能を提供することを目的としています。画面の options プロパティの代替ではありません。navigation.setOptions は、絶対に必要な場合にのみ、控えめに使用するようにしてください。

画面は、addListener メソッドを使用して navigation プロパティにリスナーを追加できます。たとえば、focus イベントをリッスンするには、次のようになります。

function Profile({ navigation }) {
  React.useEffect(() => {
    const unsubscribe = navigation.addListener('focus', () => {
      // do something
    });

    return unsubscribe;
  }, [navigation]);

  return <ProfileContent />;
}

利用可能なイベントと API の使用方法の詳細については、ナビゲーションイベント を参照してください。

isFocused​

このメソッドを使用すると、画面が現在フォーカスされているかどうかを確認できます。画面がフォーカスされている場合は true を返し、そうでない場合は false を返します。

const isFocused = navigation.isFocused();

このメソッドは、値が変更されたときに画面を再レンダリングせず、主にコールバックで役立ちます。これを直接使用する代わりに、useIsFocused を使用することをお勧めします。これにより、画面がフォーカスされているかどうかを示すブール値のプロパティが返されます。

高度な API リファレンス​

dispatch 関数はあまり使用されませんが、navigate、goBack などの利用可能なメソッドで必要なことができない場合の優れたエスケープハッチです。絶対に必要な場合を除き、dispatch メソッドを頻繁に使用することは避けることをお勧めします。

dispatch​

dispatch メソッドを使用すると、ナビゲーション状態がどのように更新されるかを決定するナビゲーションアクションオブジェクトを送信できます。navigate のようなすべてのナビゲーション関数は、内部で dispatch を使用します。

アクションをディスパッチする場合は、アクションオブジェクトを直接記述する代わりに、このライブラリで提供されるアクションクリエーターを使用する必要があることに注意してください。

利用可能なアクションの完全なリストについては、ナビゲーションアクションドキュメントを参照してください。

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

navigation.dispatch(
  CommonActions.navigate({
    name: 'Profile',
    params: {},
  })
);

アクションオブジェクトをディスパッチするときに、いくつかの追加プロパティを指定することもできます。

  • source - アクションのソースと見なされるルートのキー。たとえば、replace アクションは、指定されたキーを持つルートを置き換えます。デフォルトでは、アクションをディスパッチしたルートのキーを使用します。この動作をオーバーライドするために、明示的に undefined を渡すことができます。
  • target - アクションを適用する必要があるナビゲーション状態のキー。デフォルトでは、アクションはナビゲーターによって処理されない場合、他のナビゲーターにバブリングします。target が指定されている場合、同じキーを持つナビゲーターがそれを処理しなかった場合、アクションはバブリングしません。

例

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

navigation.dispatch({
  ...CommonActions.navigate('Profile'),
  source: 'someRoutekey',
  target: 'someStatekey',
});

カスタムアクションクリエーター​

dispatch にアクションクリエーター関数を渡すことも可能です。関数は現在の状態を受け取り、使用するナビゲーションアクションオブジェクトを返す必要があります。

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

navigation.dispatch((state) => {
  // Add the home route to the start of the stack
  const routes = [{ name: 'Home' }, ...state.routes];

  return CommonActions.reset({
    ...state,
    routes,
    index: routes.length - 1,
  });
});

この機能を使用して、アプリで利用できる独自のヘルパーを作成できます。以下は、最後の画面の直前に画面を挿入する例です。

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

const insertBeforeLast = (routeName, params) => (state) => {
  const routes = [
    ...state.routes.slice(0, -1),
    { name: routeName, params },
    state.routes[state.routes.length - 1],
  ];

  return CommonActions.reset({
    ...state,
    routes,
    index: routes.length - 1,
  });
};

次に、次のように使用します。

navigation.dispatch(insertBeforeLast('Home'));

canGoBack​

このメソッドは、現在のナビゲーターまたは親ナビゲーターにナビゲーション履歴があるかどうかを示すブール値を返します。これを使用して、navigation.goBack() を呼び出すことができるかどうかを確認できます。

if (navigation.canGoBack()) {
  navigation.goBack();
}

このメソッドは、再レンダリングをトリガーしないため、コンテンツのレンダリングには使用しないでください。これは、コールバック、イベントリスナーなどで使用することのみを目的としています。

getParent​

このメソッドは、現在のナビゲーターがネストされている親ナビゲーターからナビゲーションプロパティを返します。たとえば、スタックナビゲーターとスタック内にネストされたタブナビゲーターがある場合、タブナビゲーターの画面内で getParent を使用して、スタックナビゲーターから渡されたナビゲーションプロパティを取得できます。

オプションの ID パラメーターを受け入れて、特定の親ナビゲーターを参照できます。たとえば、画面が id プロパティとして "LeftDrawer" を持つドロワーナビゲーターの下の複数のレベルのネストでネストされている場合、getParent を複数回呼び出すことなく、直接それを参照できます。

ナビゲーターに ID を使用するには、最初に一意の id プロパティを渡します。

<Drawer.Navigator id="LeftDrawer">{/* .. */}</Drawer.Navigator>

次に、getParent を使用するときは、次のようにする代わりに

// Avoid this
const drawerNavigation = navigation.getParent().getParent();

// ...

drawerNavigation?.openDrawer();

次のようにできます。

// Do this
const drawerNavigation = navigation.getParent('LeftDrawer');

// ...

drawerNavigation?.openDrawer();

このアプローチにより、コンポーネントはナビゲーターのネスト構造を知る必要がなくなります。したがって、getParent を使用する場合は、id を使用することを強くお勧めします。

一致する親ナビゲーターがない場合、このメソッドは undefined を返します。このメソッドを使用する場合は、必ず undefined をチェックしてください。

getState​

警告

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

このメソッドは、画面を含むナビゲーターの状態オブジェクトを返します。ナビゲーターの状態を取得することは、非常にまれな状況で役立つ可能性があります。このメソッドを使用する必要はおそらくないでしょう。使用する場合は、十分な理由があることを確認してください。

コンテンツのレンダリングに状態が必要な場合は、このメソッドの代わりに useNavigationState を使用する必要があります。