Skip to main content
Version: 6.x

屏幕

Screen 组件用于配置导航器内屏幕的各个方面。

¥Screen components are used to configure various aspects of screens inside a navigator.

Screen 从 createXNavigator 函数返回：

¥A Screen is returned from a createXNavigator function:

const Stack = createNativeStackNavigator(); // Stack contains Screen & Navigator properties

创建导航器后，它可以用作 Navigator 组件的子组件：

¥After creating the navigator, it can be used as children of the Navigator component:

<Stack.Navigator>
  <Stack.Screen name="Home" component={HomeScreen} />
  <Stack.Screen name="Profile" component={ProfileScreen} />
</Stack.Navigator>

你至少需要提供一个名称和一个要为每个屏幕呈现的组件。

¥You need to provide at least a name and a component to render for each screen.

属性​

¥Props

name​

用于屏幕的名称。它接受一个字符串：

¥The name to use for the screen. It accepts a string:

<Stack.Screen name="Profile" component={ProfileScreen} />

该名称用于导航到屏幕：

¥This name is used to navigate to the screen:

navigation.navigate('Profile');

它还用于 route 中的 name 属性。

¥It is also used for the name property in the route.

虽然受支持，但我们建议避免屏幕名称中出现空格或特殊字符并保持简单。

¥While it is supported, we recommend to avoid spaces or special characters in screen names and keep them simple.

options​

用于配置屏幕在导航器中呈现方式的选项。它接受一个对象或返回一个对象的函数：

¥Options to configure how the screen gets presented in the navigator. It accepts either an object or a function returning an object:

<Stack.Screen
  name="Profile"
  component={ProfileScreen}
  options={{
    title: 'Awesome app',
  }}
/>

当你传递一个函数时，它将收到 route 和 navigation：

¥When you pass a function, it'll receive the route and navigation:

<Stack.Screen
  name="Profile"
  component={ProfileScreen}
  options={({ route, navigation }) => ({
    title: route.params.userId,
  })}
/>

有关更多详细信息和示例，请参阅 屏幕选项。

¥See Options for screens for more details and examples.

initialParams​

用于屏幕的初始参数。如果屏幕用作 initialRouteName，它将包含 initialParams 的参数。如果你导航到新屏幕，传递的参数将与初始参数浅层合并。

¥Initial params to use for the screen. If a screen is used as initialRouteName, it'll contain the params from initialParams. If you navigate to a new screen, the params passed are shallow merged with the initial params.

<Stack.Screen
  name="Details"
  component={DetailsScreen}
  initialParams={{ itemId: 42 }}
/>

getId​

返回用于屏幕的唯一 ID 的回调。它接收一个带有路由参数的对象：

¥Callback to return an unique ID to use for the screen. It receives an object with the route params:

<Stack.Screen
  name="Profile"
  component={ProfileScreen}
  getId={({ params }) => params.userId}
/>

默认情况下，navigate('ScreenName', params) 通过名称来标识屏幕。因此，如果你在 ScreenName 上并再次导航到 ScreenName，即使参数不同，它也不会添加新屏幕 - 它将使用新参数更新当前屏幕：

¥By default, navigate('ScreenName', params) identifies the screen by its name. So if you're on ScreenName and navigate to ScreenName again, it won't add a new screen even if the params are different - it'll update the current screen with the new params instead:

// Let's say you're on `Home` screen
// Then you navigate to `Profile` screen with `userId: 1`
navigation.navigate('Profile', { userId: 1 });

// Now the stack will have: `Home` -> `Profile` with `userId: 1`

// Then you navigate to `Profile` screen again with `userId: 2`
navigation.navigate('Profile', { userId: 2 });

// The stack will now have: `Home` -> `Profile` with `userId: 2`

如果指定 getId 并且不返回 undefined，则屏幕由屏幕名称和返回的 ID 来标识。这意味着如果你在 ScreenName 上并使用不同的参数再次导航到 ScreenName - 并从 getId 回调返回不同的 ID，它将向堆栈添加一个新屏幕：

¥If you specify getId and it doesn't return undefined, the screen is identified by both the screen name and the returned ID. Which means that if you're on ScreenName and navigate to ScreenName again with different params - and return a different ID from the getId callback, it'll add a new screen to the stack:

// Let's say you're on `Home` screen
// Then you navigate to `Profile` screen with `userId: 1`
navigation.navigate('Profile', { userId: 1 });

// Now the stack will have: `Home` -> `Profile` with `userId: 1`

// Then you navigate to `Profile` screen again with `userId: 2`
navigation.navigate('Profile', { userId: 2 });

// The stack will now have: `Home` -> `Profile` with `userId: 1` -> `Profile` with `userId: 2`

getId 回调还可用于确保具有相同 ID 的屏幕不会在堆栈中多次出现：

¥The getId callback can also be used to ensure that the screen with the same ID doesn't appear multiple times in the stack:

// Let's say you have a stack with the screens: `Home` -> `Profile` with `userId: 1` -> `Settings`
// Then you navigate to `Profile` screen with `userId: 1` again
navigation.navigate('Profile', { userId: 1 });

// Now the stack will have: `Home` -> `Profile` with `userId: 1`

在上面的示例中，params.userId 用作 ID，后续导航到具有相同 userId 的屏幕时将导航到现有屏幕，而不是向堆栈添加新屏幕。如果导航使用不同的 userId，那么它将添加一个新屏幕。

¥In the above examples, params.userId is used as an ID, subsequent navigation to the screen with the same userId will navigate to the existing screen instead of adding a new one to the stack. If the navigation was with a different userId, then it'll add a new screen.

如果在选项卡或抽屉式导航器中指定了 getId，则当 ID 更改时屏幕将重新安装。

¥If getId is specified in a tab or drawer navigator, the screen will remount if the ID changes.

component​

要呈现在屏幕上的 React 组件：

¥The React Component to render for the screen:

<Stack.Screen name="Profile" component={ProfileScreen} />

getComponent​

返回要在屏幕上呈现的 React 组件的回调：

¥Callback to return the React Component to render for the screen:

<Stack.Screen
  name="Profile"
  getComponent={() => require('./ProfileScreen').default}
/>

如果你希望在需要时延迟评估 ProfileScreen 模块，你可以使用此方法而不是 component 属性。当使用 内存束 来提高初始负载时，这尤其有用。

¥You can use this approach instead of the component prop if you want the ProfileScreen module to be lazily evaluated when needed. This is especially useful when using ram bundles to improve initial load.

children​

渲染回调以返回用于屏幕的 React 元素：

¥Render callback to return React Element to use for the screen:

<Stack.Screen name="Profile">
  {(props) => <ProfileScreen {...props} />}
</Stack.Screen>

如果你需要传递其他属性，可以使用此方法代替 component 属性。尽管我们建议使用 React 上下文 来传递数据。

¥You can use this approach instead of the component prop if you need to pass additional props. Though we recommend using React context for passing data instead.

警告

默认情况下，React Navigation 会对屏幕组件进行优化，以防止不必要的渲染。使用渲染回调可以消除这些优化。因此，如果你使用渲染回调，则需要确保对屏幕组件使用 React.memo 或 React.PureComponent 以避免出现性能问题。

¥By default, React Navigation applies optimizations to screen components to prevent unnecessary renders. Using a render callback removes those optimizations. So if you use a render callback, you'll need to ensure that you use React.memo or React.PureComponent for your screen components to avoid performance issues.

此屏幕的可选键。这不需要是唯一的。如果键发生更改，则具有此名称的现有屏幕将被删除（如果在堆栈导航器中使用）或重置（如果在选项卡或抽屉导航器中使用）。

¥Optional key for this screen. This doesn't need to be unique. If the key changes, existing screens with this name will be removed (if used in a stack navigator) or reset (if used in a tab or drawer navigator).

当我们想要在条件发生变化时删除或重置某些屏幕时，这会很有用：

¥This can be useful when we have some screens which we want to be removed or reset when the condition changes:

<Stack.Screen
  navigationKey={isSignedIn ? 'user' : 'guest'}
  name="Profile"
  component={ProfileScreen}
/>

listeners​

要订阅的事件监听器。详细信息请参见 Screen 上的 listeners 属性。

¥Event listeners to subscribe to. See listeners prop on Screen for more details.