This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 56).

Expo 路由器实验性堆栈

基于 react-native-screens 实验性 gamma 堆栈构建的、可选择启用的 Stack 同级组件。仅供测试使用。

Android

iOS

GitHub

npm

更新日志

重要 ExperimentalStack 是一个 alpha API，适用于 Expo SDK 56 及更高版本。它仅用于测试——在准备好用于生产之前，API 和功能集都可能发生变化。

ExperimentalStack 是 Stack 的同级组件，由新的 react-native-screens/experimental 栈提供支持。它是按每个导航器单独启用的：在你想迁移的特定布局中，将 <Stack /> 替换为 <ExperimentalStack />，而在其他所有地方继续使用 <Stack />。

我们提前分享它，是为了让你可以在应用中试用并告诉我们缺少什么。当前支持的选项范围是有意保持较小的，并会随着时间逐步扩展。

有关适用于原生和 Web 应用的基于文件的路由库的更多信息，请参阅 Expo Router 参考文档。

支持的功能

支持的屏幕选项：

title
headerShown
headerTransparent
headerBackVisible

在 Android 上，ExperimentalStack 自带预测性返回手势支持。你仍然需要通过在 app 配置中将 android.predictiveBackGestureEnabled 设置为 true 来为你的应用启用它。

平台支持

ExperimentalStack 仅支持原生平台。在 Web 上，它会回退到标准 Stack，因此同一个布局无需条件代码即可跨平台工作。

基本用法

app/_layout.tsx

import { ExperimentalStack as Stack } from 'expo-router';

export default function Layout() {
  return (
    <Stack screenOptions={{ headerShown: true }}>
      <Stack.Screen name="index" options={{ title: '主页' }} />
      <Stack.Screen name="details" options={{ title: '详情' }} />
    </Stack>
  );
}

你可以像使用 Stack 一样组合使用 ExperimentalStack.Screen 和 ExperimentalStack.Protected。

已知限制

受限的屏幕选项

ExperimentalStack 仅支持 title、headerShown、headerTransparent 和 headerBackVisible。传入任何其他选项（例如 headerLeft、headerRight、headerTitle、headerStyle、headerTintColor、动画覆盖、状态栏选项）都会在开发环境中输出警告，并且不会生效。对于需要这些选项的屏幕，请继续使用 <Stack />。

目前还不支持展示模式

ExperimentalStack 目前还不支持 presentation: 'modal' 或 transparentModal。屏幕始终会压入栈中。

目前还不支持 sheet

ExperimentalStack 目前还不支持 formSheet 或相关的 sheet 尺寸/detent 选项。

目前还不支持动画或状态栏自定义

ExperimentalStack 目前还不会遵循按屏幕覆盖的动画设置（animation、animationDuration）或状态栏选项。

在 Android 上不能与 Stack 混用

在 Android 上，ExperimentalStack 和标准 Stack 不能在同一个应用中共存——请为你的原生栈选择一种导航器类型。我们希望在未来的版本中取消这一限制，这样你就可以一次迁移一个导航器。

Web 会回退到标准 Stack

在 Web 上，<ExperimentalStack /> 会渲染 expo-router 中的标准 Stack。仅适用于原生的平台选项在 Web 上不会生效。

信息我们正在积极开发 ExperimentalStack，并希望获得反馈。你可以在 Discord 上分享你的想法，在 GitHub 上提交 issue，或者使用本页底部的反馈按钮。

安装

ExperimentalStack 作为 expo-router 的一部分提供。如果你的项目中还没有它，请按照 Expo Router 安装指南进行安装：

安装 Expo Router

了解如何在你的项目中安装 Expo Router。

API

import { ExperimentalStack } from 'expo-router';

Components

`ExperimentalStack`

Experimental

•

Android

iOS

Type: React.Element<Omit<Omit<ExperimentalStackNavigatorProps, 'children' | 'initialRouteName' | 'layout' | 'screenListeners' | 'screenOptions' | 'screenLayout' | 'UNSTABLE_router' | 'UNSTABLE_routeNamesChangeBehavior' | 'id'> & DefaultRouterOptions<string> & { children: ReactNode; layout?: ((props: { state: StackNavigationState<ParamListBase>; navigation: NavigationHelpers<ParamListBase, {}>; descriptors: Record<...>; children: ReactNode; }) => ReactElement<...>) | undefined; ... 4 more ...; UNSTABLE_routeNamesChangeBehavior?: "firstMatch" | ... 1 more ... | undefined; ..., 'children'> & Partial<Pick<Omit<ExperimentalStackNavigatorProps, 'children' | 'initialRouteName' | 'layout' | 'screenListeners' | 'screenOptions' | 'screenLayout' | 'UNSTABLE_router' | 'UNSTABLE_routeNamesChangeBehavior' | 'id'> & DefaultRouterOptions<string> & { children: ReactNode; layout?: ((props: { state: StackNavigationState<ParamListBase>; navigation: NavigationHelpers<ParamListBase, {}>; descriptors: Record<...>; children: ReactNode; }) => ReactElement<...>) | undefined; ... 4 more ...; UNSTABLE_routeNamesChangeBehavior?: "firstMatch" | ... 1 more ... | undefined; ..., 'children'>>>

Renders the new react-native-screens/experimental native stack.

Sibling to Stack. Native-only — on web it falls back to the standard Stack. Opt-in per navigator: replace <Stack /> with <ExperimentalStack /> in the specific layout you want to migrate.

`ExperimentalStack.Screen`

Android

iOS

Type: React.Element<StackScreenProps>

`ExperimentalStack.Screen.BackButton`

Android

iOS

Type: React.Element<StackScreenBackButtonProps>

Component to configure the back button.

Can be used inside Stack.Screen in a layout or directly inside a screen component.

Example

import { Stack } from 'expo-router';

export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="detail">
        <Stack.Screen.BackButton displayMode="minimal">Back</Stack.Screen.BackButton>
      </Stack.Screen>
    </Stack>
  );
}

Example

import { Stack } from 'expo-router';

export default function Page() {
  return (
    <>
      <Stack.Screen.BackButton hidden />
      <ScreenContent />
    </>
  );
}

Note: If multiple instances of this component are rendered for the same screen, the last one rendered in the component tree takes precedence.

Deprecated: Use Stack.Title instead.

`ExperimentalStack.Screen.Title`

Android

iOS

Type: React.Element<StackTitleProps>

Props

`navigation`

Android

iOS

Type: ExperimentalStackNavigationProp<ParamList, RouteName, NavigatorID>

`route`

Android

iOS

Type: RouteProp<ParamList, RouteName>

Types

`ExperimentalStackNavigationEventMap`

Experimental

•

Android

iOS

Navigator-level events emitted by ExperimentalStack. Mirrors the subset of NativeStackNavigationEventMap that the gamma Stack.Screen lifecycle callbacks can drive.

Property	Type	Description
gestureCancel	`{ data: undefined }`	-
transitionEnd	`{ data: { closing: boolean } }`	-
transitionStart	`{ data: { closing: boolean } }`	-

`ExperimentalStackNavigationHelpers`

Android

iOS

Type: NavigationHelpers<ParamListBase, ExperimentalStackNavigationEventMap>

`ExperimentalStackNavigationOptions`

Experimental

•

Android

iOS

Options accepted by ExperimentalStack screens. Mirrors the narrow option surface of the gamma <Stack.HeaderConfig> component from react-native-screens/experimental. Anything outside this shape is dropped with a __DEV__ warning at runtime.

Property	Type	Description
headerBackVisible(optional)	`boolean`	-
headerShown(optional)	`boolean`	-
headerTransparent(optional)	`boolean`	-
title(optional)	`string`	-

`ExperimentalStackNavigationProp`

Android

iOS

Literal Type: union

Acceptable values are: NavigationProp<ParamList, RouteName, NavigatorID, StackNavigationState<ParamList>, ExperimentalStackNavigationOptions, ExperimentalStackNavigationEventMap> | StackActionHelpers<ParamList>