静态配置

大部分静态配置是使用 createXNavigator 函数完成的，例如 createNativeStackNavigator、createBottomTabNavigator、createDrawerNavigator 等。在本指南的其余部分中，我们将这些函数称为 createXNavigator。

¥The bulk of the static configuration is done using the createXNavigator functions, e.g. createNativeStackNavigator, createBottomTabNavigator, createDrawerNavigator etc. We'll refer to these functions as createXNavigator in the rest of this guide.

createXNavigator

createXNavigator 函数接受一个参数，该参数是具有以下属性的对象：

¥The createXNavigator functions take one argument, which is an object with the following properties:

• 与导航器组件相同的 props，例如 id、initialRouteName、screenOptions 等。有关它们接受的属性的更多详细信息，请参阅 航海家 以及每个导航器的文档。

  ¥Same props as the navigator component, e.g. id, initialRouteName, screenOptions etc. See Navigator as well as the docs for each navigator for more details on the props they accept.

• screens - 包含导航器中每个屏幕配置的对象。

  ¥screens - an object containing configuration for each screen in the navigator.

• groups - 包含屏幕组的可选对象（相当于动态 API 中的 Group）。

  ¥groups - an optional object containing groups of screens (equivalent to Group in the dynamic API).

例如：

¥For example:

const RootStack = createNativeStackNavigator({
  initialRouteName: 'Home',
  screenOptions: {
    headerTintColor: 'white',
    headerStyle: {
      backgroundColor: 'tomato',
    },
  },
  screens: {
    Home: HomeScreen,
    Profile: ProfileScreen,
  },
});

screens

screens 对象可以包含键值对，其中键是屏幕的名称，值可以是多种内容：

¥The screens object can contain key value pairs where the key is the name of the screen and the value can be several things:

• 要渲染的组件：

  ¥A component to render:

  const RootStack = createNativeStackNavigator({
    screens: {
      Home: HomeScreen,
    },
  });

• 使用 createXNavigator 配置的导航器用于嵌套导航器：

  ¥A navigator configured using createXNavigator for nested navigators:

  const HomeTabs = createBottomTabNavigator({
    screens: {
      Groups: GroupsScreen,
      Chats: ChatsScreen,
    },
  });
  
  const RootStack = createNativeStackNavigator({
    screens: {
      Home: HomeTabs,
    },
  });

• 包含屏幕配置的对象。此配置包含各种属性：

  ¥An object containing configuration for the screen. This configuration contains the various properties:

  const RootStack = createNativeStackNavigator({
    screens: {
      Home: {
        screen: HomeScreen,
        linking: {
          path: 'home',
        },
      },
    },
  });

  详细信息请参见 屏幕配置。

  ¥See Screen configuration for more details.

groups

groups 对象可以包含键值对，其中键是组的名称，值是组配置。

¥The groups object can contain key-value pairs where the key is the name of the group and the value is the group configuration.

屏幕的配置对象接受 组页面中描述的属性。此外，使用静态配置时，以下属性可用：

¥The configuration object for a screen accepts the properties described in the Group page. In addition, the following properties are available when using static configuration:

• if - 这可用于有条件地渲染组，其工作原理与 屏幕配置中的 if 属性 相同。

  ¥if - this can be used to conditionally render the group and works the same as the if property in the screen configuration.

• screens - 包含组中每个屏幕配置的对象。配置与 导航器配置中的 screens 对象 相同。

  ¥screens - an object containing configuration for each screen in the group. The configuration is the same as the screens object in the navigator configuration.

示例：

¥Example:

const RootStack = createNativeStackNavigator({
  screens: {
    Home: HomeScreen,
    Profile: ProfileScreen,
  },
  groups: {
    Guest: {
      if: useIsGuest,
      screenOptions: {
        headerShown: false,
      },
      screens: {
        // ...
      },
    },
    User: {
      if: useIsUser,
      screens: {
        // ...
      },
    },
  },
});

屏幕配置

¥Screen configuration

屏幕的配置对象接受 屏幕中描述的属性页面。此外，使用静态配置时，以下属性可用：

¥The configuration object for a screen accepts the properties described in the Screen page. In addition, the following properties are available when using static configuration:

linking

屏幕的 链接配置。它可以是路径的字符串，也可以是具有链接配置的对象：

¥Linking configuration for the screen. It can be either a string for a path or an object with the linking configuration:

const RootStack = createNativeStackNavigator({
  screens: {
    Profile: {
      screen: ProfileScreen,
      linking: {
        path: 'u/:userId',
        parse: {
          userId: (id) => id.replace(/^@/, ''),
        },
        stringify: {
          userId: (id) => `@${id}`,
        },
      },
    },
    Chat: {
      screen: ChatScreen,
      linking: 'chat/:chatId',
    },
  },
});

linking 对象支持 配置链接 中描述的相同配置选项，例如 parse、stringify 和 exact。

¥The linking object supports the same configuration options described in Configuring links such as parse, stringify and exact.

要使深层链接在原生应用上工作，你还需要 配置你的应用 并将 prefixes 传递给 createStaticNavigation 返回的导航组件：

¥To make deep links work on native apps, you also need to configure your app and pass prefixes to the navigation component returned by createStaticNavigation:

const Navigation = createStaticNavigation(RootStack);

const linking = {
  prefixes: ['https://example.com', 'example://'],
};

function App() {
  return <Navigation linking={linking} />;
}

if

用于确定是否应渲染屏幕的回调。它不接收任何参数。这对于屏幕的条件渲染很有用，例如 - 如果你想为登录用户渲染不同的屏幕。

¥Callback to determine whether the screen should be rendered or not. It doesn't receive any arguments. This can be useful for conditional rendering of screens, e.g. - if you want to render a different screen for logged in users.

你可以使用自定义钩子来使用自定义逻辑来确定返回值：

¥You can use a custom hook to use custom logic to determine the return value:

const useIsLoggedIn = () => {
  const { isLoggedIn } = React.useContext(AuthContext);

  return isLoggedIn;
};

const RootStack = createNativeStackNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      if: useIsLoggedIn,
    },
  },
});

上述示例仅在用户登录时渲染 HomeScreen。

¥The above example will only render the HomeScreen if the user is logged in.

有关更多详细信息，请参阅 身份验证流程。

¥For more details, see Authentication flow.

createStaticNavigation

createStaticNavigation 函数采用 createXNavigator 函数返回的静态配置并返回要渲染的 React 组件：

¥The createStaticNavigation function takes the static config returned by createXNavigator functions and returns a React component to render:

const Navigation = createStaticNavigation(RootStack);

function App() {
  return <Navigation />;
}

此组件是 NavigationContainer 组件的封装器，并接受 与 NavigationContainer 相同的 props 和 ref 组件。它旨在在应用的根目录下渲染一次，类似于你使用 NavigationContainer 组件的方式。

¥This component is a wrapper around the NavigationContainer component and accepts the same props and ref as the NavigationContainer component. It is intended to be rendered once at the root of your app similar to how you'd use NavigationContainer component.

linking prop 中的差异

¥Differences in the linking prop

与 NavigationContainer 类似，createStaticNavigation 返回的组件也接受 linking prop。但是，有一些关键的区别：

¥Similar to NavigationContainer, the component returned by createStaticNavigation also accepts a linking prop. However, there are some key differences:

1. 无法将完整的 config 对象传递给 linking prop。它只能接受 path 和 根导航器的 initialRouteName。

   ¥It's not possible to pass a full config object to the linking prop. It can only accept path and an initialRouteName for the root navigator.

2. 链接配置是从屏幕配置中指定的 linking 属性中收集的。

   ¥The linking config is collected from the linking properties specified in the screen configuration.

3. 可以传递 enabled: 'auto' 以自动生成所有叶屏幕的路径：

   ¥It's possible to pass enabled: 'auto' to automatically generate paths for all leaf screens:

   const Navigation = createStaticNavigation(RootStack);
   
   const linking = {
     enabled: 'auto',
     prefixes: ['https://example.com', 'example://'],
   };
   
   function App() {
     return <Navigation linking={linking} />;
   }

   详细信息请参见 自动路径生成如何工作。

   ¥See How does automatic path generation work for more details.

createComponentForStaticNavigation

createComponentForStaticNavigation 函数采用 createXNavigator 函数返回的静态配置并返回要渲染的 React 组件。第二个参数是 React DevTools 中使用的组件的名称：

¥The createComponentForStaticNavigation function takes the static config returned by createXNavigator functions and returns a React component to render. The second argument is a name for the component that'd be used in React DevTools:

const RootStackNavigator = createComponentForStaticNavigation(
  RootStack,
  'RootNavigator'
);

返回的组件不接受任何属性。所有配置都是从静态配置推断出来的。它本质上与使用动态 API 定义组件相同。

¥The returned component doesn't take any props. All of the configuration is inferred from the static config. It's essentially the same as defining a component using the dynamic API.

这看起来与 createStaticNavigation 相似，但它们非常不同。使用静态配置时，你永远不会直接使用此功能。你唯一需要使用它的情况是，如果你要从静态配置迁移，并希望重用你编写的现有代码，而不是将其重写为动态 API。详细信息请参见 结合静态和动态 API。

¥This looks similar to createStaticNavigation however they are very different. When using static configuration, you'd never use this function directly. The only time you'd use this is if you're migrating away from static configuration and want to reuse existing code you wrote instead of rewriting it to the dynamic API. See Combining static and dynamic APIs for more details.

createPathConfigForStaticNavigation

createPathConfigForStaticNavigation 函数采用 createXNavigator 函数返回的静态配置并返回可在链接配置中使用的路径配置对象。

¥The createPathConfigForStaticNavigation function takes the static config returned by createXNavigator functions and returns a path config object that can be used within the linking config.

const config = {
  screens: {
    Home: {
      screens: createPathConfigForStaticNavigation(HomeTabs),
    },
  },
};

与 createComponentForStaticNavigation 类似，这旨在用于从静态配置迁移时。详细信息请参见 结合静态和动态 API。

¥Similar to createComponentForStaticNavigation, this is intended to be used when migrating away from static configuration. See Combining static and dynamic APIs for more details.