Expo Router Experimental Stack

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

Android

iOS

GitHub

npm

更新日志

Recommended version:

~57.0.0

重要 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 目前尚不支持自定义标题栏组件或标题栏着色/样式设置。只有上面列出的四个标题栏选项会生效。

尚不支持动画或状态栏自定义

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

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`

Type: React.Element<StackScreenProps>

`ExperimentalStack.Screen.BackButton`

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`

Type: React.Element<StackTitleProps>

Props

`navigation`

Type: ExperimentalStackNavigationProp<ParamList, RouteName, NavigatorID>

`route`

Type: RouteProp<ParamList, RouteName>

Types

`ExperimentalStackNavigationEventMap`

Experimental

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`

Type: NavigationHelpers<ParamListBase, ExperimentalStackNavigationEventMap>

`ExperimentalStackNavigationOptions`

Experimental

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`

Literal type: union

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