NavigationContainer
NavigationContainer
は、アプリの状態を管理し、最上位のナビゲーターをアプリ環境にリンクする役割を担います。
コンテナはプラットフォーム固有の統合を処理し、さまざまな便利な機能を提供します。
linking
プロパティによるディープリンク統合。- 画面トラッキング、状態の永続化など、状態の変化を通知します。
- 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>
);
}
通常の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
に設定したくないでしょう。これは、独自のミニアプリのように動作し、外部の画面に移動する必要がないナビゲーションツリーがある場合にのみ役立ちます。
モーダルやボトムシートなどのサードパーティのコンポーネントと統合する必要がある場合は、これを使用しないでください。カスタムナビゲータの使用を検討してください。