CommonActions リファレンス
ナビゲーションアクションは、少なくとも `type` プロパティを含むオブジェクトです。内部的には、アクションは `getStateForAction` メソッドを持つルーターによって処理され、既存のナビゲーション状態から新しい状態を返します。
各ナビゲーションアクションには、少なくとも以下のプロパティを含めることができます。
- `type` (必須) - アクションの名前を表す文字列。
- `payload` (オプション) - アクションに関する追加情報を含むオブジェクト。たとえば、`navigate` の場合は `name` と `params` が含まれます。
- `source` (オプション) - アクションのソースと見なされるべきルートのキー。これは、一部のアクションで、どのルートにアクションを適用するかを決定するために使用されます。デフォルトでは、`navigation.dispatch` はアクションをディスパッチしたルートのキーを追加します。
- `target` (オプション) - アクションが適用されるべきナビゲーション状態のキー。
ナビゲーションアクションのディスパッチは、アクションが処理されない場合でもエラーをスローしないことは重要です (redux で reducer によって処理されないアクションをディスパッチしても何も起こらないのと同様です)。
共通アクション
ライブラリは `CommonActions` 名前空間の下に複数のアクションクリエイターをエクスポートします。アクションオブジェクトを手動で記述する代わりに、これらのアクションクリエイターを使用する必要があります。
navigate
`navigate` アクションは、特定のルートに移動することを可能にします。以下の引数を取ります。
- `name` - *string* - どこかで登録されているルートの宛先名。
- `key` - *string* - 移動先のルートの識別子。既に存在する場合は、このルートに戻ります。
- `params` - *object* - 宛先ルートにマージするパラメータ。
渡されるオプションオブジェクトには、少なくとも `key` または `name` プロパティ、およびオプションで `params` が含まれている必要があります。 `key` と `name` の両方が渡された場合、スタックナビゲーターは一致するものが見つからない場合、指定されたキーで新しいルートを作成します。
import { CommonActions } from '@react-navigation/native';
navigation.dispatch(
CommonActions.navigate({
name: 'Profile',
params: {
user: 'jane',
},
})
);
スタックナビゲーターでは、画面名で `navigate` を呼び出すと、画面が既に存在するかどうかによって異なる動作になります。画面がスタックの履歴に既に存在する場合、その画面に戻り、その後の画面をすべて削除します。画面が存在しない場合は、新しい画面をプッシュします。
デフォルトでは、画面はその名前で識別されます。しかし、`getId` prop を使用することで、パラメータを考慮に入れるようにカスタマイズすることもできます。
reset
`reset` アクションは、ナビゲーション状態を指定された状態にリセットすることを可能にします。以下の引数を取ります。
- `state` - *object* - 使用する新しいナビゲーション状態オブジェクト。
import { CommonActions } from '@react-navigation/native';
navigation.dispatch(
CommonActions.reset({
index: 1,
routes: [
{ name: 'Home' },
{
name: 'Profile',
params: { user: 'jane' },
},
],
})
);
`reset` で指定された状態オブジェクトは、既存のナビゲーション状態を新しいものに置き換えます。これは、キーのない新しいルートオブジェクト、または異なるキーを持つルートオブジェクトを提供すると、それらのルートの既存の画面が削除され、新しい画面が追加されることを意味します。
既存の画面を保持したまま状態を変更したい場合は、既存の状態を取得できる関数を `dispatch` に渡すことができます。そして、好きなように変更することができます（既存の状態を変更しないように、変更のために新しい状態オブジェクトを作成してください）。そして、目的の状態を持つ `reset` アクションを返します。
import { CommonActions } from '@react-navigation/native';
navigation.dispatch((state) => {
// Remove all the screens after `Profile`
const index = state.routes.findIndex((r) => r.name === 'Profile');
const routes = state.routes.slice(0, index + 1);
return CommonActions.reset({
...state,
routes,
index: routes.length - 1,
});
});
ナビゲーターの状態オブジェクトは内部的なものであり、マイナーリリースで変更される可能性があると考えてください。本当に必要な場合を除き、`index` と `routes` 以外のナビゲーション状態状態オブジェクトのプロパティを使用しないでください。状態オブジェクトの構造に依存しなければ実現できない機能がある場合は、 issue を開いてください。
`reset` で履歴を書き換える
`reset` アクションはナビゲーション状態を新しい状態オブジェクトで更新できるため、ナビゲーション履歴を書き換えるために使用できます。ただし、ほとんどの場合、戻るスタックを変更するために履歴を書き換えることはお勧めできません。
- ユーザーは以前の画面に戻ることができることを期待しているため、混乱を招くユーザーエクスペリエンスにつながる可能性があります。
- Web プラットフォームをサポートする場合、ブラウザの履歴には古いナビゲーション状態が反映されるため、ユーザーがブラウザの戻るボタンを使用すると古い画面が表示されます。そのため、ユーザーがどの戻るボタンを押すかによって 2 つの異なるエクスペリエンスが発生します。
そのため、このようなユースケースがある場合は、別の方法を検討してください。たとえば、ユーザーが変更された画面に戻ったときに履歴を更新します。
goBack
`goBack` アクションクリエイターは、履歴の前のルートに戻ることを可能にします。引数を取りません。
import { CommonActions } from '@react-navigation/native';
navigation.dispatch(CommonActions.goBack());
特定のルートから戻りたい場合は、ルートキーを参照する `source` プロパティと、ルートを含むナビゲーターの `key` を参照する `target` プロパティを追加できます。
import { CommonActions } from '@react-navigation/native';
navigation.dispatch({
...CommonActions.goBack(),
source: route.key,
target: state.key,
});
デフォルトでは、アクションをディスパッチしたルートのキーが `source` プロパティとして渡され、`target` プロパティは `undefined` です。
setParams
`setParams` アクションは、特定のルートのパラメータを更新することを可能にします。以下の引数を取ります。
- `params` - *object* - 必須 - 既存のルートパラメータにマージされる新しいパラメータ。
import { CommonActions } from '@react-navigation/native';
navigation.dispatch(CommonActions.setParams({ user: 'Wojtek' }));
特定のルートにパラメータを設定したい場合は、ルートキーを参照する `source` プロパティを追加できます。
import { CommonActions } from '@react-navigation/native';
navigation.dispatch({
...CommonActions.setParams({ user: 'Wojtek' }),
source: route.key,
});
`source` プロパティが明示的に `undefined` に設定されている場合、フォーカスされているルートのパラメータが設定されます。