expo-router

Expo Router 模式

Stack 导航器配置

根布局设置

在 Stack 组件上使用 screenOptions 为所有屏幕设置默认选项。不要显式列出每个屏幕——路由会根据文件结构自动发现。

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

export default function RootLayout() {
  return (
    <Stack screenOptions={{ headerShown: false }} />
  );
}

单个屏幕配置

各个屏幕可在组件文件中使用 <Stack.Screen> 配置自己的选项：

// app/lesson/[id].tsx
import { Stack } from 'expo-router';

export default function LessonScreen() {
  return (
    <View>
      <Stack.Screen
        options={{
          title: 'Lesson',
          headerShown: true,
          headerBackTitle: 'Back',
        }}
      />
      {/* Screen content */}
    </View>
  );
}

动态配置标题栏

使用 useNavigation 和 setOptions 设置按钮等动态标题栏内容：

import { useNavigation } from 'expo-router';
import { useLayoutEffect } from 'react';

export default function Screen() {
  const navigation = useNavigation();

  useLayoutEffect(() => {
    navigation.setOptions({
      headerRight: () => (
        <Pressable onPress={handlePress}>
          <Ionicons name="add" size={28} />
        </Pressable>
      ),
    });
  }, [navigation]);

  return <View>{/* content */}</View>;
}

原生标签页（expo-router/unstable-native-tabs）

原生标签页提供平台原生的标签栏，并在 iOS 上使用 SF Symbols：

// app/(tabs)/_layout.tsx
import { Icon, Label, NativeTabs } from 'expo-router/unstable-native-tabs';

export default function TabLayout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="index" options={{ title: 'Home' }}>
        <Icon sf="house.fill" drawable="custom_android_drawable" />
        <Label>Home</Label>
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}

关键原则

1. 基于文件的路由：路由会根据 app/ 目录结构自动发现
2. 最简配置：只配置需要覆盖的选项
3. 屏幕级选项：屏幕在组件中使用 <Stack.Screen> 配置自己的标题栏和选项
4. 布局文件：_layout.tsx 文件定义其所在目录的导航结构
5. 路由组：圆括号（例如 (tabs)）会创建路由组，但不会影响 URL 路径

应避免的常见错误

• 不要在 Stack 中显式列出每个屏幕——它们会自动发现
• 不要使用 screenOptions 设置特定路由的选项——应在路由文件中使用 <Stack.Screen>
• 不要深度嵌套导航器——使用基于文件的路由可让结构更清晰