中文网
🌐 Nodejs.cn
首页指南EAS参考学习

This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

堆

了解如何使用 Expo Router 中的 Stack 导航器。

在 Expo 路由中使用堆栈导航器
在 Expo 路由中使用堆栈导航器

在屏幕之间导航，在屏幕之间传递参数，创建动态路由，并配置屏幕标题和动画。

堆栈导航器是应用中在路由之间导航的基础方式。在 Android 上，堆叠路由会在当前屏幕上方进行动画。在 iOS 上，堆叠路由会从右侧进行动画。Expo Router 提供了一个 Stack 导航组件，该组件可以创建导航堆栈，并允许你在应用中添加新的路由。

🌐 A stack navigator is the foundational way of navigating between routes in an app. On Android, a stacked route animates on top of the current screen. On iOS, a stacked route animates from the right. Expo Router provides a Stack navigation component that creates a navigation stack and allows you to add new routes in your app.

本指南提供了有关如何在项目中创建 Stack 导航器以及自定义单个路由的选项和标题的信息。

🌐 This guide provides information on how you can create a Stack navigator in your project and customize an individual route's options and header.

开始使用

🌐 Get started

你可以使用基于文件的路由来创建堆栈导航器。下面是一个示例文件结构：

🌐 You can use file-based routing to create a stack navigator. Here's an example file structure:

src
 app
  _layout.tsx
  index.tsx
  details.tsx

这个文件结构产生的布局是，index 路由是堆栈中的第一个路由，而当导航时，details 路由会被压入 index 路由之上。

🌐 This file structure produces a layout where the index route is the first route in the stack, and the details route is pushed on top of the index route when navigated.

你可以使用 src/app/_layout.tsx 文件来定义你的应用的 Stack 导航器，并包含这两个路由：

🌐 You can use the src/app/_layout.tsx file to define your app's Stack navigator with these two routes:

src/app/_layout.tsx
import { Stack } from 'expo-router';

export default function Layout() {
  return <Stack />;
}

屏幕选项和标题配置

🌐 Screen options and header configuration

从 SDK 55 开始，你可以使用基于选项的 API 或新的组合组件 API 配置屏幕选项和标题。这两种 API 在你的项目中都可以互换使用。

🌐 Starting in SDK 55, you can configure screen options and the header using either the options-based API or the new composition components API. Both APIs can be used interchangeably in your project.

静态配置路由选项

🌐 Statically configure route options

你可以在布局组件路由中使用 <Stack.Screen name={routeName} /> 组件来静态配置路由的选项。

🌐 You can use the <Stack.Screen name={routeName} /> component in the layout component route to statically configure a route's options.

src/app/_layout.tsx
import { Stack } from 'expo-router';

export default function Layout() {
  return (
    <Stack
      screenOptions={{
        headerStyle: {
          backgroundColor: '#f4511e',
        },
        headerTintColor: '#fff',
        headerTitleStyle: {
          fontWeight: 'bold',
        },
      }}>
      {/* Optionally configure static options outside the route.*/}
      <Stack.Screen name="home" options={{}} />
    </Stack>
  );
}

配置标题栏

🌐 Configure header bar

你可以通过使用 screenOptions 属性来为 Stack 导航器中的所有路由配置标题栏。这对于在所有路由中设置统一的标题样式非常有用。

🌐 You can configure the header bar for all routes in a Stack navigator by using the screenOptions prop. This is useful for setting a common header style across all routes.

src/app/_layout.tsx
import { Stack } from 'expo-router';

export default function Layout() {
  return (
    <Stack
      screenOptions={{
        headerStyle: {
          backgroundColor: '#f4511e',
        },
        headerTintColor: '#fff',
        headerTitleStyle: {
          fontWeight: 'bold',
        },
      }}
    />
  );
}

设置原生标题的界面风格

🌐 Set the native header's interface style

信息 此选项仅在 iOS 的 SDK 58 及更高版本 可用。

使用 headerUserInterfaceStyle 可以将屏幕的原生标题设置为 'light' 或 'dark'，而不会改变导航主题。例如，详情屏幕可以使用深色标题，而堆栈的其他屏幕仍保持基于主题的样式：

🌐 Use headerUserInterfaceStyle to set a screen's native header to 'light' or 'dark' without changing the navigation theme. For example, a detail screen can use a dark header while the rest of the stack keeps its theme-based style:

src/app/_layout.tsx
import { Stack } from 'expo-router';

export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" options={{ headerLargeTitleEnabled: true }} />
      <Stack.Screen name="details" options={{ headerUserInterfaceStyle: 'dark' }} />
    </Stack>
  );
}

你也可以在 screenOptions 中为整个堆栈设置这个选项。Stack.Screen 选项会覆盖该屏幕的设置。如果省略该选项，本地标题将遵循导航主题。本地标题在屏幕可见时不支持更改此选项。这个选项仅影响本地标题。如果需要，可以单独设置标题颜色。

🌐 You can also set this option in screenOptions for the whole stack. A Stack.Screen option overrides it for that screen. When the option is omitted, the native header follows the navigation theme. The native header does not support changes to this option while the screen is visible. This option affects the native header only. Set header colors separately if needed.

动态设置屏幕选项

🌐 Set screen options dynamically

要动态配置路由的选项，你可以使用组合组件或基于选项的 API。

🌐 To configure a route's options dynamically, you can use either the composition components or the options-based API.

src/app/details.tsx
import { Stack, useLocalSearchParams, useRouter } from 'expo-router';
import { View, Text, StyleSheet } from 'react-native';

export default function Details() {
  const router = useRouter();
  const params = useLocalSearchParams();

  return (
    <View style={styles.container}>
      <Stack.Screen
        options={{
          title: params.name,
          headerStyle: { backgroundColor: 'lightblue' },
        }}
      />
      <Text
        onPress={() => {
          router.setParams({ name: 'Updated' });
        }}>
        Update the title
      </Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

可用的标头选项

🌐 Available header options

Stack 导航器支持全面的标题配置选项。以下是所有可用的标题相关选项：

🌐 The Stack navigator supports comprehensive header configuration options. Below are all the header-related options available:

Header options
OptionPlatformDescription
header
Android
iOS

Custom header to use instead of the default header.

This accepts a function that returns a React Element to display as a header. The function receives an object containing the following properties as the argument:

  • navigation - The navigation object for the current screen.
  • route - The route object for the current screen.
  • options - The options for the current screen
  • back - Options for the back button, contains an object with a title property to use for back button label.

To set a custom header for all the screens in the navigator, you can specify this option in the screenOptions prop of the navigator.

Note that if you specify a custom header, the native functionality such as large title, search bar etc. won't work.

headerBackButtonDisplayMode
iOS

How the back button displays icon and title.

Supported values:

  • "default" - Displays one of the following depending on the available space: previous screen's title, generic title (e.g. 'Back') or no title (only icon).
  • "generic" – Displays one of the following depending on the available space: generic title (e.g. 'Back') or no title (only icon).
  • "minimal" – Always displays only the icon without a title.

The space-aware behavior is disabled when:

  • The iOS version is 13 or lower
  • Custom font family or size is set (e.g. with headerBackTitleStyle)
  • Back button menu is disabled (e.g. with headerBackButtonMenuEnabled)

In such cases, a static title and icon are always displayed.

headerBackButtonMenuEnabled
iOS

Boolean indicating whether to show the menu on longPress of iOS >= 14 back button. Defaults to true.

headerBackground
Android
iOS

Function which returns a React Element to render as the background of the header. This is useful for using backgrounds such as an image or a gradient.

headerBackIcon
Android
iOS

Icon to display in the header as the icon in the back button. Defaults to back icon image for the platform:

  • A chevron on iOS
  • An arrow on Android

Currently only supports image sources.

headerBackTitle
iOS

Title string used by the back button on iOS. Defaults to the previous scene's title, "Back" or arrow icon depending on the available space. See headerBackButtonDisplayMode to read about limitations and customize the behavior.

Use headerBackButtonDisplayMode: "minimal" to hide it.

headerBackTitleStyle
iOS

Style object for header back title. Supported properties:

  • fontFamily
  • fontSize
headerBackVisible
Android
iOS

Whether the back button is visible in the header. You can use it to show a back button alongside headerLeft if you have specified it.

This will have no effect on the first screen in the stack.

headerBlurEffect
iOS

Blur effect for the translucent header. The headerTransparent option needs to be set to true for this to work.

Supported values: extraLight, light, regular, prominent, systemUltraThinMaterial, systemThinMaterial, systemMaterial, systemThickMaterial, systemChromeMaterial, systemUltraThinMaterialLight, systemThinMaterialLight, systemMaterialLight, systemThickMaterialLight, systemChromeMaterialLight, dark, systemUltraThinMaterialDark, systemThinMaterialDark, systemMaterialDark, systemThickMaterialDark, systemChromeMaterialDark

Using both headerBlurEffect and scrollEdgeEffects (>= iOS 26) simultaneously may cause overlapping effects.

headerLargeStyle
iOS

Style of the header when a large title is shown. The large title is shown if headerLargeTitleEnabled is true and the edge of any scrollable content reaches the matching edge of the header.

Supported properties:

  • backgroundColor
headerLargeTitleEnabled
iOS

Whether to enable header with large title which collapses to regular header on scroll. Defaults to false.

For large title to collapse on scroll, the content of the screen should be wrapped in a scrollable view such as ScrollView or FlatList. If the scrollable area doesn't fill the screen, the large title won't collapse on scroll. You also need to specify contentInsetAdjustmentBehavior="automatic" in your ScrollView, FlatList etc.

headerLargeTitleShadowVisible
Android
iOS

Whether drop shadow of header is visible when a large title is shown.

headerLargeTitleStyle
iOS

Style object for large title in header. Supported properties:

  • fontFamily
  • fontSize
  • fontWeight
  • color
headerLeft
Android
iOS

Function which returns a React Element to display on the left side of the header. This replaces the back button. See headerBackVisible to show the back button along side left element. It receives the following properties in the arguments:

  • tintColor - The tint color to apply. Defaults to the theme's primary color.
  • canGoBack - Boolean indicating whether there is a screen to go back to.
  • label - Label text for the button. Usually the title of the previous screen.
  • href - The href to use for the anchor tag on web
headerRight
Android
iOS

Function which returns a React Element to display on the right side of the header. It receives the following properties in the arguments:

  • tintColor - The tint color to apply. Defaults to the theme's primary color.
  • canGoBack - Boolean indicating whether there is a screen to go back to.
headerSearchBarOptions
Android
iOS

Options to render a native search bar. Search bars are rarely static so normally it is controlled by passing an object to headerSearchBarOptions navigation option in the component's body.

On iOS, you also need to specify contentInsetAdjustmentBehavior="automatic" in your ScrollView, FlatList etc. If you don't have a ScrollView, specify headerTransparent: false.

Supported properties are:

ref

Ref to manipulate the search input imperatively. It contains the following methods:

  • focus - focuses the search bar
  • blur - removes focus from the search bar
  • setText - sets the search bar's content to given value
  • clearText - removes any text present in the search bar input field
  • cancelSearch - cancel the search and close the search bar
  • toggleCancelButton - depending on passed boolean value, hides or shows cancel button (only supported on iOS)

autoCapitalize

Controls whether the text is automatically auto-capitalized as it is entered by the user. Possible values:

  • systemDefault
  • none
  • words
  • sentences
  • characters

Defaults to systemDefault which is the same as sentences on iOS and none on Android.

autoFocus

Whether to automatically focus search bar when it's shown. Defaults to false.

barTintColor

The search field background color. By default bar tint color is translucent.

tintColor

The color for the cursor caret and cancel button text.

cancelButtonText

The text to be used instead of default Cancel button text.

Deprecated starting from iOS 26.

disableBackButtonOverride

Whether the back button should close search bar's text input or not. Defaults to false.

hideNavigationBar

Boolean indicating whether to hide the navigation bar during searching.

If left unset, system default is used.

hideWhenScrolling

Boolean indicating whether to hide the search bar when scrolling. Defaults to true.

inputType

The type of the input. Defaults to "text".

Supported values: "text", "phone", "number", "email"

obscureBackground

Boolean indicating whether to obscure the underlying content with semi-transparent overlay.

If left unset, system default is used.

placement

Controls preferred placement of the search bar. Defaults to automatic.

Supported values: automatic, stacked, inline, integrated, integratedButton, integratedCentered

allowToolbarIntegration

Boolean indicating whether the system can place the search bar among other toolbar items on iPhone.

Set this prop to false to prevent the search bar from appearing in the toolbar when placement is automatic, integrated, integratedButton or integratedCentered.

Defaults to true. If placement is set to stacked, the value of this prop will be overridden with false.

Only supported on iOS, starting from iOS 26.

placeholder

Text displayed when search field is empty.

textColor

The color of the text in the search field.

hintTextColor

The color of the hint text in the search field.

headerIconColor

The color of the search and close icons shown in the header

shouldShowHintSearchIcon

Whether to show the search hint icon when search bar is focused. Defaults to true.

onBlur

A callback that gets called when search bar has lost focus.

onCancelButtonPress

A callback that gets called when the cancel button is pressed.

onSearchButtonPress

A callback that gets called when the search button is pressed.

const [search, setSearch] = React.useState('');

React.useLayoutEffect(() => {
  navigation.setOptions({
    headerSearchBarOptions: {
      onSearchButtonPress: (event) => setSearch(event?.nativeEvent?.text),
    },
  });
}, [navigation]);

onChangeText

A callback that gets called when the text changes. It receives the current text value of the search bar.

headerShown

Whether to show the header. The header is shown by default. Setting this to false hides the header.

headerShadowVisible
Android
iOS

Whether to hide the elevation shadow (Android) or the bottom border (iOS) on the header.

headerShown
Android
iOS

Whether to show the header. The header is shown by default. Setting this to false hides the header.

headerStyle
Android
iOS

Style object for header. Supported properties:

  • backgroundColor
headerTintColor
Android
iOS

Tint color for the header. Changes the color of back button and title.

headerTitle
Android
iOS

String or a function that returns a React Element to be used by the header. Defaults to title or name of the screen.

When a function is passed, it receives tintColor andchildren in the options object as an argument. The title string is passed in children.

Note that if you render a custom element by passing a function, animations for the title won't work.

headerTitleAlign
Android
iOS

How to align the header title. Possible values:

  • left
  • center

Defaults to left on platforms other than iOS.

Not supported on iOS. It's always center on iOS and cannot be changed.

headerTitleStyle
Android
iOS

Style object for header title. Supported properties:

  • fontFamily
  • fontSize
  • fontWeight
  • color
headerTransparent
Android
iOS

Boolean indicating whether the navigation bar is translucent.

Defaults to false. Setting this to true makes the header absolutely positioned - so that the header floats over the screen so that it overlaps the content underneath, and changes the background color to transparent unless specified in headerStyle.

This is useful if you want to render a semi-transparent header or a blurred background.

Note that if you don't want your content to appear under the header, you need to manually add a top margin to your content. React Navigation won't do it automatically.

To get the height of the header, you can use HeaderHeightContext with React's Context API or useHeaderHeight.

title
Android
iOS

String that can be used as a fallback for headerTitle.

unstable_headerInsets
Android

Which edges of the native header apply window insets (e.g. statusbar inset) on Android.

The native header applies insets to every edge by default. Setting an edge to false removes the inset for that edge:

unstable_headerInsets: {
  top: false,
  bottom: false,
}

Supported edges are top, left, right, and bottom.

Disabling an inset also disables it for nested headers. A nested header cannot re-enable an inset disabled by a parent header.

This API may change in a minor release.

unstable_headerLeftItems
iOS

This option is experimental and may change in a minor release.

Function which returns an array of items to display as on the left side of the header. This will override headerLeft if both are specified. It receives the following properties in the arguments:

  • tintColor - The tint color to apply. Defaults to the theme's primary color.
  • canGoBack - Boolean indicating whether there is a screen to go back to.

See Header items for more information.

unstable_headerRightItems
iOS

This option is experimental and may change in a minor release.

Function which returns an array of items to display as on the right side of the header. This will override headerRight if both are specified. It receives the following properties in the arguments:

  • tintColor - The tint color to apply. Defaults to the theme's primary color.
  • canGoBack - Boolean indicating whether there is a screen to go back to.

See Header items for more information.

标题按钮

🌐 Header buttons

你可以使用 headerLeft 和 headerRight 选项或 <Stack.Toolbar> 组件向头部添加按钮。这些选项接受在头部渲染的 React 组件。

🌐 You can add buttons to the header by using the headerLeft and headerRight options or <Stack.Toolbar> component. These options accept a React component that renders in the header.

堆叠工具栏

配置 iOS 头部工具栏以支持液态玻璃效果。

src/app/index.tsx
import { Stack } from 'expo-router';
import { Button, Text, Image, StyleSheet } from 'react-native';
import { useState } from 'react';

function LogoTitle() {
  return (
    <Image style={styles.image} source={{ uri: 'https://rn.nodejs.cn/img/tiny_logo.png' }} />
  );
}

export default function Home() {
  const [count, setCount] = useState(0);

  return (
    <>
      <Stack.Screen
        options={{
          headerTitle: props => <LogoTitle {...props} />,
          headerRight: () => <Button onPress={() => setCount(c => c + 1)} title="Update count" />,
        }}
      />
      <Text>Count: {count}</Text>
    </>
  );
}

const styles = StyleSheet.create({
  image: {
    width: 50,
    height: 50,
  },
});

其他屏幕选项

🌐 Other screen options

有关所有可用其他屏幕选项（包括动画、手势和其他配置）的完整列表：

🌐 For a complete list of all available other screen options including animations, gestures, and other configurations:

Screen options
OptionPlatformDescription
animation
Android

How the screen should animate when pushed or popped.

Supported values: default, fade, fade_from_bottom, flip, simple_push, slide_from_bottom, slide_from_right, slide_from_left, none

animationDuration
iOS

Changes the duration (in milliseconds) of slide_from_bottom, fade_from_bottom, fade and simple_push transitions on iOS. Defaults to 350.

For screens with default and flip transitions, and, as of now, for screens with presentation set to modal, formSheet, pageSheet (regardless of transition), the duration isn't customizable.

animationMatchesGesture
iOS

Whether the gesture to dismiss should use animation provided to animation prop. Defaults to false.

Doesn't affect the behavior of screens presented modally.

animationTypeForReplace
Android
iOS

The type of animation to use when this screen replaces another screen. Defaults to push.

Supported values: push, pop

This can be useful to provide appropriate animations, such as push for login and pop for logout.

autoHideHomeIndicator
iOS

Boolean indicating whether the home indicator should prefer to stay hidden. Defaults to false.

contentStyle
Android
iOS

Style object for the scene content.

freezeOnBlur
iOS

Boolean indicating whether to prevent inactive screens from re-rendering. Defaults to false. Defaults to true when enableFreeze() from react-native-screens package is run at the top of the application.

Only supported on iOS and Android.

fullScreenGestureEnabled
iOS

Whether the gesture to dismiss should work on the whole screen. Using gesture to dismiss with this option results in the same transition animation as simple_push. This behavior can be changed by setting customAnimationOnGesture prop. Achieving the default iOS animation isn't possible due to platform limitations. Defaults to false.

Doesn't affect the behavior of screens presented modally.

fullScreenGestureShadowEnabled
Android
iOS

Whether the full screen dismiss gesture has shadow under view during transition. Defaults to true.

This does not affect the behavior of transitions that don't use gestures enabled by fullScreenGestureEnabled prop.

gestureDirection
iOS

Sets the direction in which you should swipe to dismiss the screen.

Supported values: vertical, horizontal

When using vertical option, options fullScreenGestureEnabled: true, customAnimationOnGesture: true and animation: 'slide_from_bottom' are set by default.

gestureEnabled
iOS

Whether you can use gestures to dismiss this screen. Defaults to true.

navigationBarColor
Android

This option is deprecated and will be removed in a future release (for apps targeting Android SDK 35 or above edge-to-edge mode is enabled by default and it is expected that the edge-to-edge will be enforced in future SDKs, see here for more information).

Sets the navigation bar color. Defaults to initial status bar color.

navigationBarHidden
Android

Boolean indicating whether the navigation bar should be hidden. Defaults to false.

orientation
Android

The display orientation to use for the screen.

Supported values: default, all, portrait, portrait_up, portrait_down, landscape, landscape_left, landscape_right

presentation
Android

How should the screen be presented.

Supported values: card, modal, containedModal, fullScreenModal, transparentModal, containedTransparentModal, formSheet

scrollEdgeEffects
iOS

Configures the scroll edge effect for the content ScrollView (the ScrollView that is present in first descendants chain of the Screen). Depending on values set, it will blur the scrolling content below certain UI elements (e.g. header items, search bar) for the specified edge of the ScrollView. When set in nested containers, i.e. Native Stack inside Native Bottom Tabs, or the other way around, the ScrollView will use only the innermost one's config.

Edge effects can be configured for each edge separately. The following values are currently supported:

  • automatic - the automatic scroll edge effect style,
  • hard - a scroll edge effect with a hard cutoff and dividing line,
  • soft - a soft-edged scroll edge effect,
  • hidden - no scroll edge effect.

Defaults to automatic for each edge.

Using both blurEffect and scrollEdgeEffects (>= iOS 26) simultaneously may cause overlapping effects.

Only supported on iOS, starting from iOS 26.

sheetAllowedDetents
Android

Describes heights where a sheet can rest.

Supported values: 'fitToContents' or an array of fractions (e.g. [0.25, 0.5, 0.75]). The array must be sorted in ascending order. This invariant is verified only in development mode, where violation results in an error. Android is limited to 3 detents.

Defaults to [1.0].

See Configuring sheet sizes for usage examples.

sheetCornerRadius
Android

The corner radius of the sheet. If set to a non-negative value it will use the provided radius, otherwise the system default is used.

sheetElevation
Android

Integer value describing elevation of the sheet, impacting shadow on the top edge.

Not dynamic - changing it after the component is rendered won't have an effect.

Defaults to 24.

sheetExpandsWhenScrolledToEdge
iOS

Whether the sheet should expand to a larger detent when scrolling.

The ScrollView must be reachable by following the first child view at each level of the view hierarchy from the screen component.

Defaults to true.

See Scroll behavior for more details.

sheetGrabberVisible
iOS

Whether the sheet shows a grabber handle at the top.

Defaults to false.

sheetInitialDetentIndex
Android

Index of the detent the sheet should expand to after being opened. If the specified index is out of bounds of the sheetAllowedDetents array, an error will be thrown in development mode and the value will be reset to the default in production.

Can also be set to 'last' to open at the largest detent.

Defaults to 0.

See Configuring sheet sizes for usage examples.

sheetLargestUndimmedDetentIndex
Android

The largest detent index for which the view underneath won't be dimmed.

Can be set to a number (index into sheetAllowedDetents), 'none' (always dim), or 'last' (never dim).

Defaults to 'none'.

See Controlling dimming for usage examples.

sheetResizeAnimationEnabled
Android

Whether the default native animation should be used when the sheet's content size changes (specifically when using fitToContents).

Set to false to implement custom resizing animations.

Defaults to true.

sheetShouldOverflowTopInset
Android

Whether the sheet content should be rendered behind the status bar or display cutouts.

When true, detent ratios in sheetAllowedDetents are measured relative to the full stack height. When false, they are measured relative to the adjusted height (excluding the top inset).

Defaults to false.

statusBarAnimation
Android

Sets the status bar animation (similar to the StatusBar component). Defaults to fade on iOS and none on Android.

Supported values: "fade", "none", "slide"

On Android, setting either fade or slide will set the transition of status bar color. On iOS, this option applies to the appearance animation of the status bar.

Requires setting View controller-based status bar appearance -> YES (or removing the config) in your Info.plist file.

statusBarBackgroundColor
Android

This option is deprecated and will be removed in a future release (for apps targeting Android SDK 35 or above edge-to-edge mode is enabled by default and it is expected that the edge-to-edge will be enforced in future SDKs, see here for more information).

Sets the background color of the status bar (similar to the StatusBar component).

statusBarHidden
Android

Whether the status bar should be hidden on this screen.

Requires setting View controller-based status bar appearance -> YES (or removing the config) in your Info.plist file.

statusBarStyle
Android

Sets the status bar color (similar to the StatusBar component).

Supported values: "auto", "inverted", "dark", "light"

Defaults to auto on iOS and light on Android.

Requires setting View controller-based status bar appearance -> YES (or removing the config) in your Info.plist file.

statusBarTranslucent
Android

This option is deprecated and will be removed in a future release (for apps targeting Android SDK 35 or above edge-to-edge mode is enabled by default and it is expected that the edge-to-edge will be enforced in future SDKs, see here for more information).

Sets the translucency of the status bar (similar to the StatusBar component). Defaults to false.

tabBarAccessibilityLabel
Android
iOS

Accessibility label for the tab button. This is read by the screen reader when the user taps the tab. It's recommended to set this if you don't have a label for the tab.

tabBarActiveBackgroundColor
Android
iOS

Background color for the active tab.

tabBarActiveTintColor
Android
iOS

Color for the icon and label in the active tab.

tabBarBackground
Android
iOS

Function which returns a React Element to use as background for the tab bar. You could render an image, a gradient, blur view etc.:

import { BlurView } from 'expo-blur';
import { StyleSheet } from 'react-native';
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';

// ...

createBottomTabNavigator({
  screenOptions: {
    tabBarStyle: { position: 'absolute' },
    tabBarBackground: () => (
      <BlurView tint="light" intensity={100} style={StyleSheet.absoluteFill} />
    ),
  },
  screens: {
    // ...
  },
});

import { BlurView } from 'expo-blur';
import { StyleSheet } from 'react-native';

// ...

<Tab.Navigator
  screenOptions={{
    tabBarStyle: { position: 'absolute' },
    tabBarBackground: () => (
      <BlurView tint="light" intensity={100} style={StyleSheet.absoluteFill} />
    ),
  }}
>

When using BlurView, make sure to set position: 'absolute' in tabBarStyle as well. You'd also need to use useBottomTabBarHeight to add bottom padding to your content.

tabBarBadge
Android
iOS

Text to show in a badge on the tab icon. Accepts a string or a number.

tabBarBadgeStyle
Android
iOS

Style for the badge on the tab icon. You can specify a background color or text color here.

tabBarButton
Android
iOS

Function which returns a React element to render as the tab bar button. It wraps the icon and label. Renders PlatformPressable by default.

You can specify a custom implementation here:

tabBarButton: (props) => <TouchableOpacity {...props} />;
tabBarButtonTestID
Android
iOS

ID to locate this tab button in tests.

tabBarHideOnKeyboard
Android
iOS

Whether the tab bar is hidden when the keyboard opens. Defaults to false.

tabBarIcon
Android
iOS

Function that given { focused: boolean, color: string, size: number } returns a React.Node, to display in the tab bar.

tabBarIconStyle
Android
iOS

Style object for the tab icon.

tabBarInactiveBackgroundColor
Android
iOS

Background color for the inactive tabs.

tabBarInactiveTintColor
Android
iOS

Color for the icon and label in the inactive tabs.

tabBarItemStyle
Android
iOS

Style object for the tab item container.

tabBarLabel
Android
iOS

Title string of a tab displayed in the tab bar or a function that given { focused: boolean, color: string } returns a React.Node, to display in tab bar. When undefined, scene title is used. To hide, see tabBarShowLabel.

tabBarLabelPosition
Android
iOS

Whether the label is shown below the icon or beside the icon. By default, the position is chosen automatically based on device width.

  • below-icon

    The label is shown below the icon (typical for devices with smaller widths such as phones)

  • beside-icon

    The label is shown next to the icon (typical for larger devices such as tablets)

tabBarLabelStyle
Android
iOS

Style object for the tab label.

tabBarPosition
Android
iOS

Position of the tab bar. Available values are:

  • bottom (Default)
  • top
  • left
  • right

When the tab bar is positioned on the left or right, it is styled as a sidebar. This can be useful when you want to show a sidebar on larger screens and a bottom tab bar on smaller screens:

You can also render a compact sidebar by placing the label below the icon. This is only supported when the tabBarVariant is set to material:

tabBarShowLabel
Android
iOS

Whether the tab label should be visible. Defaults to true.

tabBarStyle
Android
iOS

Style object for the tab bar. You can configure styles such as background color here.

To show your screen under the tab bar, you can set the position style to absolute:

createBottomTabNavigator({
  screenOptions: {
    tabBarStyle: { position: 'absolute' },
  },
  screens: {
    // ...
  },
});

<Tab.Navigator
  screenOptions={{
    tabBarStyle: { position: 'absolute' },
  }}
>

You also might need to add a bottom margin to your content if you have an absolutely positioned tab bar. React Navigation won't do it automatically. See useBottomTabBarHeight for more details.

tabBarVariant
Android
iOS

Variant of the tab bar. Available values are:

  • uikit (Default) - The tab bar will be styled according to the iOS UIKit guidelines.
  • material - The tab bar will be styled according to the Material Design guidelines.

The material variant is currently only supported when the tabBarPosition is set to left or right.

自定义推送行为

🌐 Custom push behavior

默认情况下，Stack 导航器在推送已存在于堆栈中的路由时会移除重复的页面。例如，如果你重复推送同一个页面，第二次推送将被忽略。你可以通过向 <Stack.Screen> 提供自定义的 getId() 函数来更改这种推送行为。

🌐 By default, the Stack navigator removes duplicate screens when pushing a route that is already in the stack. For example, if you push the same screen twice, the second push will be ignored. You can change this push behavior by providing a custom getId() function to the <Stack.Screen>.

例如，以下布局结构中的 index 路由显示了应用中不同用户资料的列表。我们可以将 [details] 路由设为动态路由，以便应用用户可以导航查看某个资料的详细信息。

🌐 For example, the index route in the following layout structure shows a list of different user profiles in the app. Let's make the [details] route a dynamic route so that the app user can navigate to see a profile's details.

src
 app
  _layout.tsx
  index.tsx
  [details].tsxmatches dynamic paths like '/details1'

Stack 导航器每次应用用户导航到不同的个人资料时都会推送一个新屏幕，但会失败。如果你提供一个每次返回新ID的 getId() 函数，Stack 每次应用用户导航到个人资料时都会推送一个新屏幕。

🌐 The Stack navigator will push a new screen every time the app user navigates to a different profile but will fail. If you provide a getId() function that returns a new ID every time, the Stack will push a new screen every time the app user navigates to a profile.

你可以在布局组件路由中使用 <Stack.Screen name="[profile]" getId={}> 组件来修改推送行为：

🌐 You can use the <Stack.Screen name="[profile]" getId={}> component in the layout component route to modify the push behavior:

src/app/_layout.tsx
import { Stack } from 'expo-router';

export default function Layout() {
  return (
    <Stack>
      <Stack.Screen
        name="[profile]"
        getId={
          ({ params }) => String(Date.now())
        }
      />
    </Stack>
  );
}

删除堆栈屏幕

🌐 Removing stack screens

你可以使用不同的操作来关闭和删除堆栈中的一个或多个路由。

🌐 There are different actions you can use to dismiss and remove one or many routes from a stack.

dismiss 操作

🌐 dismiss action

关闭最近堆栈中的最后一个屏幕。如果当前屏幕是堆栈中唯一的路由，它将关闭整个堆栈。

🌐 Dismisses the last screen in the closest stack. If the current screen is the only route in the stack, it will dismiss the entire stack.

你可以选择传递一个正数来关闭指定数量的屏幕。

🌐 You can optionally pass a positive number to dismiss up to that specified number of screens.

Dismiss 与 back 不同，因为它作用于最接近的堆栈，而不是当前的导航器。如果你有嵌套的导航器，调用 dismiss 将会让你返回多个屏幕。

🌐 Dismiss is different from back as it targets the closest stack and not the current navigator. If you have nested navigators, calling dismiss will take you back multiple screens.

src/app/settings.tsx
import { Button, View } from 'react-native';
import { useRouter } from 'expo-router';

export default function Settings() {
  const router = useRouter();

  const handleDismiss = (count: number) => {
    router.dismiss(count)
  };

  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button title="返回主屏幕" onPress={() => handleDismiss(3)} />
    </View>
  );
}

dismissTo 操作

🌐 dismissTo action

dismissTo 在 Expo Router 4.0.8 中被添加。它的操作方式类似于 Expo Router v3 中的 navigation 函数。

在当前的 <Stack /> 中关闭屏幕，直到达到指定的 Href。如果历史记录中没有 Href，当前屏幕将被指定的 Href 替代。

🌐 Dismisses screens in the current <Stack /> until the specified Href is reached. If the Href is absent in the history, the current screen is replaced with the specified Href instead.

例如，考虑 /one、/two、/three 的历史记录，而 /three 是当前的路由。动作 router.dismissTo('/one') 会让历史记录回退两步，而 router.dismissTo('/four') 会将当前的 /three 路由替换为 /four 路由。

🌐 For example, consider the history of /one, /two, /three routes, where /three is the current route. The action router.dismissTo('/one') will cause the history to go back twice, while router.dismissTo('/four') will replace the current /three route with the /four route.

src/app/settings.tsx
import { Button, View, Text } from 'react-native';
import { useRouter } from 'expo-router';

export default function Settings() {
  const router = useRouter();

  const handleDismissAll = () => {
    router.dismissTo('/')
  };

  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button title="返回主屏幕" onPress={handleDismissAll} />
    </View>
  );
}

dismissAll 操作

🌐 dismissAll action

dismissAll 操作会关闭最近堆栈中第一个屏幕之上的所有屏幕，返回到那个第一个屏幕。

🌐 The dismissAll action dismisses every screen above the first screen in the closest stack, returning to that first screen.

例如，home 路由是第一个屏幕，而 settings 是最后一个。要从 settings 路由到 home，你需要返回到 details。然而，使用 dismissAll 操作，你可以从 settings 路由到 home，并关闭中间的任意屏幕。

🌐 For example, the home route is the first screen, and the settings is the last. To go from settings to home route you'll have to go back to details. However, using the dismissAll action, you can go from settings to home and dismiss any screen in between.

src/app/settings.tsx
import { Button, View, Text } from 'react-native';
import { useRouter } from 'expo-router';

export default function Settings() {
  const router = useRouter();

  const handleDismissAll = () => {
    router.dismissAll()
  };

  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button title="返回主屏幕" onPress={handleDismissAll} />
    </View>
  );
}

canDismiss 操作

🌐 canDismiss action

检查是否可以关闭当前屏幕。如果路由位于堆栈中且堆栈历史记录中有多个屏幕，则返回 true。

🌐 To check if it is possible to dismiss the current screen. Returns true if the router is within a stack with more than one screen in the stack's history.

src/app/settings.tsx
import { Button, View } from 'react-native';
import { useRouter } from 'expo-router';

export default function Settings() {
  const router = useRouter();

  const handleDismiss = (count: number) => {
    if (router.canDismiss()) {
      router.dismiss(count)
    }
  };

  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Button title="也许忽略" onPress={() => handleDismiss()} />
    </View>
  );
}

iOS 26 液态玻璃标题

🌐 iOS 26 Liquid Glass headers

从 iOS 26 开始，导航栏标题默认采用系统的“液态玻璃”效果。无法针对单个页面禁用，因此需要通过全局配置来选择退出。

🌐 Starting from iOS 26, navigation headers adopt the system's "Liquid Glass" effect by default. It cannot be disabled per screen, so you need to opt out using a global configuration.

方法1：使用 UIDesignRequiresCompatibility

🌐 Method 1: Use UIDesignRequiresCompatibility

注意：在 Expo Go 中不支持。此方法是一个临时解决方案。从 iOS 27 开始，此选项将被苹果移除，你无法选择退出液态玻璃效果。

创建一个 开发版本 并在 应用配置 中将 UIDesignRequiresCompatibility 属性设置为 true：

🌐 Create a development build and set the UIDesignRequiresCompatibility property to true in app config:

app.json
{
  "ios": {
    "infoPlist": {
      "UIDesignRequiresCompatibility": true
    }
  }
}

方法二：使用基于 JavaScript 的导航栈

🌐 Method 2: Use JavaScript-based navigation stack

将本地堆栈替换为在 expo-router/js-stack 提供的由 JavaScript 驱动的堆栈。这可以让你完全控制头部 UI，但会牺牲经过高度优化的 iOS 导航视图和控制器的性能优势：

🌐 Swap the native stack for the JavaScript-driven stack shipped at expo-router/js-stack. This gives you full control over the header UI, at the cost of the performance benefits of the highly optimized iOS navigation views and controllers:

src/app/_layout.tsx
import { Stack as JsStack } from 'expo-router/js-stack';

export default function Layout() {
  return <JsStack />;
}

expo-router/js-stack 入口点是 SDK 56 替代 @react-navigation/stack 库的方式。有关更多信息，请参阅 SDK 55 到 56 迁移指南。

🌐 The expo-router/js-stack entry point is the SDK 56 replacement for the @react-navigation/stack library. See the SDK 55 to 56 migration guide for more information.

常见问题

🌐 Common problems

大标题在滚动时不会收缩

当使用 headerLargeTitle: true（或 <Stack.Title large>）与 ScrollView 或 FlatList 时，大标题在滚动时可能不会收起。发生这种情况是因为可滚动视图不是屏幕组件的直接第一个子组件。

🌐 When using headerLargeTitle: true (or <Stack.Title large>) with a ScrollView or FlatList, the large title may not collapse on scroll. This happens when the scrollable view is not the direct first child of the screen component.

为了解决此问题，请确保 ScrollView 或 FlatList 是你的屏幕组件渲染的第一个子元素。如果需要一个封装器，请在其上设置 collapsable={false}：

🌐 To fix this, ensure ScrollView or FlatList is the first child rendered by your screen component. If you need a wrapper, set collapsable={false} on it:

src/app/index.tsx
import { Stack } from 'expo-router';
import { ScrollView, View, Text } from 'react-native';

export default function Home() {
  return (
    <ScrollView>
      <Stack.Title large>Home</Stack.Title>
      <Text>Content here</Text>
    </ScrollView>
  );
}

如果你需要封装 ScrollView，请在封装器上设置 collapsable={false}：

🌐 If you need to wrap the ScrollView, set collapsable={false} on the wrapper:

src/app/index.tsx
import { Stack } from 'expo-router';
import { ScrollView, View, Text } from 'react-native';

export default function Home() {
  return (
    <View collapsable={false}>
      <ScrollView>
        <Stack.Title large>Home</Stack.Title>
        <Text>Content here</Text>
      </ScrollView>
    </View>
  );
}
在屏幕之间切换时背景会闪白

屏幕切换之间出现的白色闪光通常意味着导航堆栈使用了浅色背景，而你的应用使用的是深色主题。

🌐 A white flash between screen transitions usually means the navigation stack is using a light background while your app uses a dark theme.

要解决此问题，请用 Expo Router 的 <ThemeProvider> 封装你的根布局，并传递适当的主题：

🌐 To fix this, wrap your root layout with Expo Router's <ThemeProvider> and pass the appropriate theme:

src/app/_layout.tsx
import { ThemeProvider, DarkTheme, DefaultTheme, Stack } from 'expo-router';
import { useColorScheme } from 'react-native';

export default function RootLayout() {
  const colorScheme = useColorScheme();

  return (
    <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
      <Stack />
    </ThemeProvider>
  );
}

对于始终使用深色主题的应用：

🌐 For apps that are always dark-themed:

src/app/_layout.tsx
import { ThemeProvider, DarkTheme, Stack } from 'expo-router';

export default function RootLayout() {
  return (
    <ThemeProvider value={DarkTheme}>
      <Stack />
    </ThemeProvider>
  );
}