NavigationContainer

NavigationContainer 负责管理你的应用状态并将你的顶层导航器链接到应用环境。

¥The NavigationContainer is responsible for managing your app state and linking your top-level navigator to the app environment.

该容器负责特定于平台的集成并提供各种有用的功能：

¥The container takes care of platform specific integration and provides various useful functionality:

1. 与 linking 属性的深度链接集成。

   ¥Deep link integration with the linking prop.

2. 通知 屏幕跟踪、状态持续性 等的状态更改。

   ¥Notify state changes for screen tracking, state persistence etc.

3. 使用 React Native 的 BackHandler API 处理 Android 上的系统后退按钮。

   ¥Handle system back button on Android by using the BackHandler API from React Native.

用法：

¥Usage:

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 附加到容器以访问各种辅助程序方法，例如调度导航操作。这应该在极少数情况下使用，当你无权访问 navigation 属性时，例如 Redux 中间件。

¥It's also possible to attach a ref to the container to get access to various helper methods, for example, dispatch navigation actions. This should be used in rare cases when you don't have access to the navigation prop, such as a Redux middleware.

示例：

¥Example:

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。为了确保引用已初始化，你可以使用 onReady 回调在导航容器完成安装时收到通知。

¥If you're using a regular ref object, keep in mind that the ref may be initially null in some situations (such as when linking is enabled). To make sure that the ref is initialized, you can use the onReady callback to get notified when the navigation container finishes mounting.

有关详细信息，请参阅 无需导航属性即可导航 指南。

¥See the Navigating without the navigation prop guide for more details.

参考方法

¥Methods on the ref

ref 对象包括所有常见的导航方法，例如 navigate、goBack 等。有关更多详细信息，请参阅 CommonActions 的文档。

¥The ref object includes all of the common navigation methods such as navigate, goBack etc. See docs for CommonActions for more details.

示例：

¥Example:

navigationRef.navigate(name, params);

所有这些方法的行为就好像它们是在当前聚焦的屏幕内调用的一样。重要的是要注意，必须呈现一个导航器来处理这些操作。

¥All of these methods will act as if they were called inside the currently focused screen. It's important note that there must be a navigator rendered to handle these actions.

除了这些方法之外，ref 对象还包括以下特殊方法：

¥In addition to these methods, the ref object also includes the following special methods:

isReady

isReady 方法返回一个 boolean，指示导航树是否准备好。当 NavigationContainer 包含至少一个导航器并且所有导航器都已完成安装时，导航树已准备就绪。

¥The isReady method returns a boolean indicating whether the navigation tree is ready. The navigation tree is ready when the NavigationContainer contains at least one navigator and all of the navigators have finished mounting.

这可用于确定在不出现错误的情况下分派导航操作是否安全。详细信息请参见 处理初始化。

¥This can be used to determine whether it's safe to dispatch navigation actions without getting an error. See handling initialization for more details.

resetRoot

resetRoot 方法允许你将导航树的状态重置为指定的状态对象：

¥The resetRoot method lets you reset the state of the navigation tree to the specified state object:

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

与 reset 方法不同，此方法作用于根导航器而不是当前聚焦屏幕的导航器。

¥Unlike the reset method, this acts on the root navigator instead of navigator of the currently focused screen.

getRootState

getRootState 方法返回一个 导航状态 对象，其中包含导航树中所有导航器的导航状态：

¥The getRootState method returns a navigation state object containing the navigation states for all navigators in the navigation tree:

const state = navigationRef.getRootState();

请注意，如果当前没有呈现导航器，则返回的 state 对象将为 undefined。

¥Note that the returned state object will be undefined if there are no navigators currently rendered.

getCurrentRoute

getCurrentRoute 方法返回整个导航树中当前焦点屏幕的路由对象：

¥The getCurrentRoute method returns the route object for the currently focused screen in the whole navigation tree:

const route = navigationRef.getCurrentRoute();

请注意，如果当前没有呈现导航器，则返回的 route 对象将为 undefined。

¥Note that the returned route object will be undefined if there are no navigators currently rendered.

getCurrentOptions

getCurrentOptions 方法返回整个导航树中当前聚焦屏幕的选项：

¥The getCurrentOptions method returns the options for the currently focused screen in the whole navigation tree:

const options = navigationRef.getCurrentOptions();

请注意，如果当前没有呈现导航器，则返回的 options 对象将为 undefined。

¥Note that the returned options object will be undefined if there are no navigators currently rendered.

addListener

addListener 方法允许你监听以下事件：

¥The addListener method lets you listen to the following events:

state

每当导航树中任何导航器中的 导航状态 发生变化时，都会触发该事件：

¥The event is triggered whenever the navigation state changes in any navigator in the navigation tree:

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 方法。唯一的区别是 e.data.state 对象可能包含部分状态对象，这与 onStateChange 中的 state 参数不同，后者始终包含完整状态对象。

¥This is analogous to the onStateChange method. The only difference is that the e.data.state object might contain partial state object unlike the state argument in onStateChange which will always contain the full state object.

options

每当导航树中当前聚焦屏幕的选项发生更改时，就会触发该事件：

¥The event is triggered whenever the options change for the currently focused screen in the navigation tree:

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

属性

¥Props

initialState

接受导航器初始状态的属性。这对于深度链接、状态持久性等情况非常有用。

¥Prop that accepts initial state for the navigator. This can be useful for cases such as deep linking, state persistence etc.

示例：

¥Example:

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

提供自定义初始状态对象将覆盖通过链接配置或从浏览器 URL 获取的初始状态对象。如果你要提供初始状态对象，请确保不要在网络上传递它，并且没有需要处理的深层链接。

¥Providing a custom initial state object will override the initial state object obtained via linking configuration or from browser's URL. If you're providing an initial state object, make sure that you don't pass it on web and that there's no deep link to handle.

示例：

¥Example:

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
}

有关如何保留和恢复状态的更多详细信息，请参阅 状态持久化指南。

¥See state persistence guide for more details on how to persist and restore state.

onStateChange

警告

将导航器的状态对象视为内部对象，并且可能会在次要版本中发生更改。避免使用除 index 和 routes 之外的 导航状态 状态对象的属性，除非你确实需要它。如果某些功能在不依赖状态对象的结构的情况下无法实现，请提出问题。

¥Consider the navigator's state object to be internal and subject to change in a minor release. Avoid using properties from the navigation state state object except index and routes, unless you really need it. If there is some functionality you cannot achieve without relying on the structure of the state object, please open an issue.

每次 导航状态 更改时都会调用的函数。它接收新的导航状态作为参数。

¥Function that gets called every time navigation state changes. It receives the new navigation state as the argument.

你可以使用它来跟踪聚焦屏幕、保留导航状态等。

¥You can use it to track the focused screen, persist the navigation state etc.

示例：

¥Example:

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

onReady

导航容器及其所有子容器首次完成安装后调用的函数。你可以将其用于：

¥Function which is called after the navigation container and all its children finish mounting for the first time. You can use it for:

• 确保 ref 可用。详细信息请参见 有关 ref 初始化的文档。

  ¥Making sure that the ref is usable. See docs regarding initialization of the ref for more details.

• 隐藏你的原生启动屏幕

  ¥Hiding your native splash screen

示例：

¥Example:

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

onUnhandledAction

当任何导航器未处理导航操作时调用的函数。

¥Function which is called when a navigation action is not handled by any of the navigators.

默认情况下，当未处理操作时，React Navigation 将显示仅开发错误消息。你可以通过提供自定义函数来覆盖默认行为。

¥By default, React Navigation will show a development-only error message when an action was not handled. You can override the default behavior by providing a custom function.

linking

用于深度链接的链接集成配置、浏览器中的 URL 支持等。

¥Configuration for linking integration used for deep linking, URL support in browsers etc.

示例：

¥Example:

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 集成的更多详细信息，请参阅 配置链接指南。

¥See configuring links guide for more details on how to configure deep links and URL integration.

选项

¥Options

linking.prefixes

要处理的 URL 前缀。你可以提供多个前缀来支持自定义方案以及 通用链接。

¥URL prefixes to handle. You can provide multiple prefixes to support custom schemes as well as universal links.

仅处理与这些前缀匹配的 URL。在解析之前，前缀将从 URL 中去除。

¥Only URLs matching these prefixes will be handled. The prefix will be stripped from the URL before parsing.

示例：

¥Example:

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

仅 iOS 和 Android 支持此功能。

¥This is only supported on iOS and Android.

linking.config

配置来微调如何解析路径。配置对象应代表应用中导航器的结构。

¥Config to fine-tune how to parse the path. The config object should represent the structure of the navigators in the app.

例如，如果我们在 Home 屏幕内有 Catalog 屏幕并希望它处理 item/:id 模式：

¥For example, if we have Catalog screen inside Home screen and want it to handle the item/:id pattern:

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

解析的选项可以是对象或字符串：

¥The options for parsing can be an object or a string:

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

当指定字符串时，相当于提供 path 选项。

¥When a string is specified, it's equivalent to providing the path option.

path 选项是与路径匹配的模式。任何以 : 开头的段都被识别为具有相同名称的参数。例如 item/42 将被解析为 { name: 'item', params: { id: '42' } }。

¥The path option is a pattern to match against the path. Any segments starting with : are recognized as a param with the same name. For example item/42 will be parsed to { name: 'item', params: { id: '42' } }.

initialRouteName 选项确保通过的路由名称将出现在导航器的状态中，例如对于配置：

¥The initialRouteName option ensures that the route name passed there will be present in the state for the navigator, e.g. for config:

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

URL：/item/42，状态将如下所示：

¥and URL : /item/42, the state will look like this:

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

parse 选项控制如何解析参数。在这里，你可以提供要解析为键的参数名称，以及一个采用参数的字符串值并返回解析值的函数：

¥The parse option controls how the params are parsed. Here, you can provide the name of the param to parse as a key, and a function which takes the string value for the param and returns a parsed value:

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

如果没有提供自定义函数来解析参数，它将被解析为字符串。

¥If no custom function is provided for parsing a param, it'll be parsed as a string.

linking.enabled

用于启用或禁用链接集成的可选布尔值。如果指定了 linking 属性，则默认为 true。

¥Optional boolean to enable or disable the linking integration. Defaults to true if the linking prop is specified.

linking.getInitialURL

默认情况下，链接与 React Native 的 Linking API 集成，并使用 Linking.getInitialURL() 为深度链接提供内置支持。但是，你可能还想处理来自其他来源的链接，例如 分支，或使用 Firebase 等推送通知。

¥By default, linking integrates with React Native's Linking API and uses Linking.getInitialURL() to provide built-in support for deep linking. However, you might also want to handle links from other sources, such as Branch, or push notifications using Firebase etc.

你可以提供自定义 getInitialURL 函数，你可以在其中返回我们应用作初始 URL 的链接。如果有要处理的 URL，则 getInitialURL 函数应返回 string，否则返回 undefined。

¥You can provide a custom getInitialURL function where you can return the link which we should use as the initial URL. The getInitialURL function should return a string if there's a URL to handle, otherwise undefined.

例如，你可以执行以下操作来处理深度链接和 Firebase 通知：

¥For example, you could do something like following to handle both deep linking and Firebase notifications:

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 上不可用。

¥This option is not available on Web.

linking.subscribe

与 getInitialURL 类似，你可以提供自定义 subscribe 函数来处理任何传入链接，而不是默认的深层链接处理。subscribe 函数将接收一个监听器作为参数，只要有新的 URL 需要处理，你就可以使用 URL 字符串调用它。它应该返回一个清理函数，你可以在其中取消订阅你设置的任何事件监听器。

¥Similar to getInitialURL, you can provide a custom subscribe function to handle any incoming links instead of the default deep link handling. The subscribe function will receive a listener as the argument and you can call it with a URL string whenever there's a new URL to handle. It should return a cleanup function where you can unsubscribe from any event listeners that you have setup.

例如，你可以执行以下操作来处理深度链接和 Firebase 通知：

¥For example, you could do something like following to handle both deep linking and Firebase notifications:

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 上不可用。

¥This option is not available on Web.

linking.getStateFromPath

你可以选择通过提供自己的实现来覆盖 React Navigation 解析状态对象链接的方式。

¥You can optionally override the way React Navigation parses links to a state object by providing your own implementation.

示例：

¥Example:

<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 支持是必要的。

¥You can optionally override the way React Navigation serializes state objects to link by providing your own implementation. This is necessary for proper web support if you have specified getStateFromPath.

示例：

¥Example:

<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 Element 可以用作后备。默认为 null。

¥React Element to use as a fallback while we resolve deep links. Defaults to null.

如果你有原生启动画面，请使用 onReady 而不是 fallback 属性。

¥If you have a native splash screen, please use onReady instead of fallback prop.

documentTitle

默认情况下，React Navigation 会自动更新 Web 上的文档标题以匹配焦点屏幕的 title 选项。你可以使用此属性禁用它或自定义它。它接受具有以下选项的配置对象：

¥By default, React Navigation automatically updates the document title on Web to match the title option of the focused screen. You can disable it or customize it using this prop. It accepts a configuration object with the following options:

documentTitle.enabled

是否应启用文档标题处理。默认为 true。

¥Whether document title handling should be enabled. Defaults to true.

documentTitle.formatter

如果你想自定义标题文本，请使用自定义格式化程序。默认为：

¥Custom formatter to use if you want to customize the title text. Defaults to:

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

示例：

¥Example:

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

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

theme

用于导航组件（如标题、选项卡栏等）的自定义主题。有关更多详细信息和使用指南，请参阅 主题指南。

¥Custom theme to use for the navigation components such as the header, tab bar etc. See theming guide for more details and usage guide.

independent

警告

这是一个高级用例。除非你 100% 确定需要它，否则不要使用它。

¥This is an advanced use case. Don't use this unless you are 100% sure that you need it.

此导航容器是否应独立于父容器。如果设置为 true，则该容器不能嵌套在另一个容器内。将其设置为 true 会断开所有子导航器与父容器的连接，并且不允许在它们之间进行导航。

¥Whether this navigation container should be independent of parent containers. If this is set to true, this container cannot be nested inside another container. Setting it to true disconnects any children navigators from the parent container and doesn't allow navigation between them.

你可能不想在典型的 React Native 应用中将其设置为 true。仅当你的导航树像自己的迷你应用一样工作并且不需要导航到其外部的屏幕时，这才有用。

¥You probably don't want to set this to true in a typical React Native app. This is only useful if you have navigation trees that work like their own mini-apps and don't need to navigate to the screens outside of them.

如果你需要与第三方组件（例如模式或底部表单）集成，请避免使用此选项。考虑使用 自定义导航器 代替。

¥Avoid using this if you need to integrate with third-party components such as modals or bottom sheets. Consider using a custom navigator instead.