Skip to main content
Version: 6.x

常见操作参考

导航操作是至少包含 type 属性的对象。在内部，该操作可以由 routers 使用 getStateForAction 方法处理，以从现有 导航状态 返回新状态。

¥A navigation action is an object containing at least a type property. Internally, the action can be handled by routers with the getStateForAction method to return a new state from an existing navigation state.

每个导航操作至少可以包含以下属性：

¥Each navigation actions can contain at least the following properties:

  • type（必需的） - 表示操作名称的字符串。

    ¥type (required) - A string which represents the name of the action.

  • payload（选项） - 包含有关操作的附加信息的对象。例如，对于 navigate，它将包含 name 和 params。

    ¥payload (options) - An object containing additional information about the action. For example, it will contain name and params for navigate.

  • source（可选） - 应被视为操作源的路由的键。这用于某些操作以确定要应用该操作的路由。默认情况下，navigation.dispatch 添加调度操作的路由的键。

    ¥source (optional) - The key of the route which should be considered as the source of the action. This is used for some actions to determine which route to apply the action on. By default, navigation.dispatch adds the key of the route that dispatched the action.

  • target（可选） - 应应用操作的 导航状态 的键。

    ¥target (optional) - The key of the navigation state the action should be applied on.

需要强调的是，当操作未处理时，分派导航操作不会引发任何错误（类似于当你分派未由 redux 中的 reducer 处理的操作并且什么也没有发生时）。

¥It's important to highlight that dispatching a navigation action doesn't throw any error when the action is unhandled (similar to when you dispatch an action that isn't handled by a reducer in redux and nothing happens).

常见动作​

¥Common actions

该库在 CommonActions 命名空间下导出多个动作创建器。你应该使用这些操作创建器，而不是手动编写操作对象。

¥The library exports several action creators under the CommonActions namespace. You should use these action creators instead of writing action objects manually.

navigate 操作允许导航到特定路由。它需要以下参数：

¥The navigate action allows to navigate to a specific route. It takes the following arguments:

  • name - string - 已在某处注册的路由的目的地名称。

    ¥name - string - A destination name of the route that has been registered somewhere..

  • key - string - 要导航到的路由的标识符。如果该路由已经存在，则导航回该路由。

    ¥key - string - The identifier for the route to navigate to. Navigate back to this route if it already exists..

  • params - object - 要合并到目标路由的参数..

    ¥params - object - Params to merge into the destination route..

传递的选项对象至少应包含 key 或 name 属性，也可以包含 params。如果 key 和 name 都被传递，如果没有找到匹配项，堆栈导航器将使用指定的键创建一个新路由。

¥The options object passed should at least contain a key or name property, and optionally params. If both key and name are passed, stack navigator will create a new route with the specified key if no matches were found.

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

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

在 堆栈导航器 中，使用屏幕名称调用 navigate 将根据屏幕是否已存在而导致不同的行为。如果该屏幕已存在于堆栈历史记录中，它将返回到该屏幕并删除此后的所有屏幕。如果屏幕不存在，它将推送一个新屏幕。

¥In a stack navigator, calling navigate with a screen name will result in different behavior based on if the screen is already present or not. If the screen is already present in the stack's history, it'll go back to that screen and remove any screens after that. If the screen is not present, it'll push a new screen.

默认情况下，屏幕通过其名称进行标识。但你也可以使用 getId 属性对其进行自定义以将参数考虑在内。

¥By default, the screen is identified by its name. But you can also customize it to take the params into account by using the getId prop.

reset​

reset 操作允许将 导航状态 重置为给定状态。它需要以下参数：

¥The reset action allows to reset the navigation state to the given state. It takes the following arguments:

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

navigation.dispatch(
  CommonActions.reset({
    index: 1,
    routes: [
      { name: 'Home' },
      {
        name: 'Profile',
        params: { user: 'jane' },
      },
    ],
  })
);

reset 中指定的状态对象用新的状态对象替换现有的 导航状态。这意味着，如果你提供不带键的新路由对象，或使用不同键的路由对象，它将删除这些路由的现有屏幕并添加新屏幕。

¥The state object specified in reset replaces the existing navigation state with the new one. This means that if you provide new route objects without a key, or route objects with a different key, it'll remove the existing screens for those routes and add new screens.

如果你想保留现有屏幕但只想修改状态，你可以将一个函数传递给 dispatch，你可以在其中获取现有状态。然后你可以根据需要更改它（确保不要改变现有状态，而是为你的更改创建新的状态对象）。并返回具有所需状态的 reset 操作：

¥If you want to preserve the existing screens but only want to modify the state, you can pass a function to dispatch where you can get the existing state. Then you can change it as you like (make sure not to mutate the existing state, but create new state object for your changes). and return a reset action with the desired state:

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 之外的 导航状态 状态对象的属性，除非你确实需要它。如果某些功能在不依赖状态对象的结构的情况下无法实现，请提出问题。

¥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.

用 reset 改写历史​

¥Rewriting the history with reset

由于 reset 操作可以使用新的状态对象更新导航状态，因此它可以用于重写导航历史记录。但是，在大多数情况下，不建议重写历史记录来更改返回堆栈：

¥Since the reset action can update the navigation state with a new state object, it can be used to rewrite the navigation history. However, rewriting the history to alter the back stack is not recommended in most cases:

  • 它可能会导致令人困惑的用户体验，因为用户希望能够返回到之前所在的屏幕。

    ¥It can lead to a confusing user experience, as users expect to be able to go back to the screen they were on before.

  • 当支持 Web 平台时，浏览器的历史记录仍然会反映旧的导航状态，因此如果用户使用浏览器的后退按钮，他们将看到旧的屏幕 - 根据用户按下的后退按钮，会产生两种不同的体验。

    ¥When supporting the Web platform, the browser's history will still reflect the old navigation state, so users will see the old screen if they use the browser's back button - resulting in 2 different experiences depending on which back button the user presses.

因此，如果你有这样的用例，请考虑采用不同的方法 - 例如一旦用户导航回已更改的屏幕，就会更新历史记录。

¥So if you have such a use case, consider a different approach - e.g. updating the history once the user navigates back to the screen that has changed.

goBack​

goBack 动作创建器允许返回到历史上的上一条路由。它不需要任何争论。

¥The goBack action creator allows to go back to the previous route in history. It doesn't take any arguments.

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

navigation.dispatch(CommonActions.goBack());

如果你想从特定路由返回，你可以添加一个引用路由键的 source 属性和一个引用包含该路由的导航器的 key 的 target 属性：

¥If you want to go back from a particular route, you can add a source property referring to the route key and a target property referring to the key of the navigator which contains the route:

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

navigation.dispatch({
  ...CommonActions.goBack(),
  source: route.key,
  target: state.key,
});

默认情况下，调度操作的路由的键作为 source 属性传递，target 属性为 undefined。

¥By default, the key of the route which dispatched the action is passed as the source property and the target property is undefined.

setParams​

setParams 操作允许更新特定路由的参数。它需要以下参数：

¥The setParams action allows to update params for a certain route. It takes the following arguments:

  • params - object - required - 新参数将合并到现有的路由参数中。

    ¥params - object - required - New params to be merged into existing route params.

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

navigation.dispatch(CommonActions.setParams({ user: 'Wojtek' }));

如果要为特定路由设置参数，可以添加引用路由键的 source 属性：

¥If you want to set params for a particular route, you can add a source property referring to the route key:

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

navigation.dispatch({
  ...CommonActions.setParams({ user: 'Wojtek' }),
  source: route.key,
});

如果 source 属性显式设置为 undefined，它将设置焦点路由的参数。

¥If the source property is explicitly set to undefined, it'll set the params for the focused route.