堆叠工具栏

学习如何在使用 Expo Router 的堆栈导航中使用 iOS 工具栏。

重要 Stack.Toolbar 是一个仅在 iOS 上可用的 alpha API，自 Expo SDK 55 及更高版本支持。该 API 可能会有重大修改。

Stack.Toolbar 允许你在 Stack 屏幕上添加原生 iOS 工具栏项目。你可以在顶部栏（左侧或右侧）或底部工具栏区域放置按钮、菜单和自定义视图。

添加头部按钮

🌐 Adding header buttons

在 Stack.Toolbar 中使用 Stack.Toolbar.Button 并搭配 placement="right" 或 placement="left"，即可在导航头添加按钮。这对于执行收藏、分享或编辑内容的操作非常有用。

🌐 Use Stack.Toolbar.Button within Stack.Toolbar with placement="right" or placement="left" to add buttons to the navigation header. This is useful for actions like favoriting, sharing, or editing content.

import { useState } from 'react';
import { Stack } from 'expo-router';
import { View, Text, Alert } from 'react-native';

export default function NoteScreen() {
  const [isFavorite, setIsFavorite] = useState(false);

  return (
    <>
      <Stack.Toolbar placement="right">
        <Stack.Toolbar.Button
          icon={isFavorite ? 'star.fill' : 'star'}
          onPress={() => setIsFavorite(!isFavorite)}
        />
        <Stack.Toolbar.Button icon="square.and.arrow.up" onPress={() => Alert.alert('Share')} />
      </Stack.Toolbar>
      <Stack.Toolbar placement="left">
        <Stack.Toolbar.Button icon="sidebar.left" onPress={() => Alert.alert('Sidebar')} />
      </Stack.Toolbar>

      <View style={{ flex: 1, padding: 16 }}>
        <Text>Note content...</Text>
      </View>
    </>
  );
}

图标

🌐 Icons

工具栏按钮支持两种类型的图标：SF 符号和自定义图片。

🌐 Toolbar buttons support two types of icons: SF Symbols and custom images.

SF 符号

🌐 SF Symbols

添加图标最简单的方法是使用 SF Symbols，苹果内置的图标库。将符号名称直接传递给 icon 属性即可：

🌐 The easiest way to add icons is using SF Symbols, Apple's built-in icon library. Pass the symbol name directly to the icon prop:

<Stack.Toolbar.Button icon="star.fill" onPress={() => {}} />
<Stack.Toolbar.Button icon="square.and.arrow.up" onPress={() => {}} />
<Stack.Toolbar.Menu icon="ellipsis.circle">{/* ... */}</Stack.Toolbar.Menu>

你可以在 Apple 的 SF Symbols 应用中浏览可用的符号。

🌐 You can browse available symbols in Apple's SF Symbols app.

自定义图片

🌐 Custom images

你也可以使用自定义图片。在头部工具栏（placement="left" 或 placement="right"）中，直接将图片源传递给 icon 属性：

🌐 You can also use custom images. In header toolbars (placement="left" or placement="right"), pass an image source directly to the icon prop:

import { Stack } from 'expo-router';

export default function Page() {
  return (
    <>
      <Stack.Toolbar placement="right">
        <Stack.Toolbar.Button icon={require('./assets/expo.png')} onPress={() => {}} />
      </Stack.Toolbar>
      {/* Screen content */}
    </>
  );
}

在底部工具栏中，使用来自 expo-image 的 useImage Hook，并将结果传递给 image 属性：

🌐 In the bottom toolbar, use the useImage hook from expo-image and pass the result to the image prop:

import { Stack } from 'expo-router';
import { useImage } from 'expo-image';

export default function Page() {
  const customIcon = useImage('https://simpleicons.org/icons/expo.svg', {
    maxWidth: 24,
    maxHeight: 24,
  });

  return (
    <>
      <Stack.Toolbar>
        <Stack.Toolbar.Button image={customIcon} onPress={() => {}} />
      </Stack.Toolbar>
      {/* Screen content */}
    </>
  );
}

信息 用于底部工具栏自定义图片的 useImage 和 image 属性模式是临时 API，未来版本可能会发生变化。

构建操作菜单

🌐 Building action menus

对于具有多个操作的屏幕，请使用 Stack.Toolbar.Menu 将它们分组到下拉菜单中：

🌐 For screens with multiple actions, use Stack.Toolbar.Menu to group them into a dropdown menu:

import { useState } from 'react';
import { Stack } from 'expo-router';
import { Alert } from 'react-native';

export default function EmailScreen() {
  const [isArchived, setIsArchived] = useState(false);

  return (
    <>
      <Stack.Toolbar placement="right">
        <Stack.Toolbar.Menu icon="ellipsis.circle">
          <Stack.Toolbar.MenuAction
            icon="arrowshape.turn.up.left"
            onPress={() => Alert.alert('Reply')}>
            Reply
          </Stack.Toolbar.MenuAction>

          <Stack.Toolbar.MenuAction
            icon="arrowshape.turn.up.right"
            onPress={() => Alert.alert('Forward')}>
            Forward
          </Stack.Toolbar.MenuAction>

          <Stack.Toolbar.MenuAction
            icon={isArchived ? 'tray.full' : 'archivebox'}
            isOn={isArchived}
            onPress={() => setIsArchived(!isArchived)}>
            {isArchived ? 'Unarchive' : 'Archive'}
          </Stack.Toolbar.MenuAction>

          <Stack.Toolbar.MenuAction icon="trash" destructive onPress={() => Alert.alert('Delete')}>
            Delete
          </Stack.Toolbar.MenuAction>
        </Stack.Toolbar.Menu>
      </Stack.Toolbar>
      {/* Email content */}
    </>
  );
}

Stack.Toolbar.MenuAction 上的 isOn 属性会在操作旁显示勾选标记，对于切换状态很有用。destructive 属性将操作样式设置为红色，以表示危险操作。

🌐 The isOn prop on Stack.Toolbar.MenuAction shows a checkmark next to the action, useful for toggle states. The destructive prop styles the action in red to indicate a dangerous operation.

嵌套子菜单

🌐 Nested submenus

对于更复杂的菜单，可以将 Stack.Toolbar.Menu 嵌套在另一个菜单中。使用 inline 属性可以直接显示子菜单项，而不折叠：

🌐 For more complex menus, nest Stack.Toolbar.Menu inside another menu. Use the inline prop to display submenu items directly without collapsing:

import { useState } from 'react';
import { Stack } from 'expo-router';

export default function EmailScreen() {
  const [sortBy, setSortBy] = useState<'name' | 'date' | 'size'>('name');
  const [showHiddenFiles, setShowHiddenFiles] = useState(false);

  return (
    <>
      <Stack.Toolbar>
        <Stack.Toolbar.Menu icon="ellipsis.circle">
          {/* Inline submenu - options appear directly in the menu */}
          <Stack.Toolbar.Menu inline title="Sort By">
            <Stack.Toolbar.MenuAction isOn={sortBy === 'name'} onPress={() => setSortBy('name')}>
              Name
            </Stack.Toolbar.MenuAction>
            <Stack.Toolbar.MenuAction isOn={sortBy === 'date'} onPress={() => setSortBy('date')}>
              Date
            </Stack.Toolbar.MenuAction>
            <Stack.Toolbar.MenuAction isOn={sortBy === 'size'} onPress={() => setSortBy('size')}>
              Size
            </Stack.Toolbar.MenuAction>
          </Stack.Toolbar.Menu>

          {/* Nested submenu - opens as a separate menu */}
          <Stack.Toolbar.Menu title="Preferences">
            <Stack.Toolbar.MenuAction
              isOn={showHiddenFiles}
              onPress={() => setShowHiddenFiles(!showHiddenFiles)}>
              Show Hidden Files
            </Stack.Toolbar.MenuAction>
          </Stack.Toolbar.Menu>
        </Stack.Toolbar.Menu>
      </Stack.Toolbar>
      {/* Email content */}
    </>
  );
}

使用底部工具栏

🌐 Using the bottom toolbar

iOS 应用通常在底部有一个用于主要操作的工具栏。要添加一个，可以使用 Stack.Toolbar，不需要指定 placement 属性（它默认为 "bottom"）：

🌐 iOS apps commonly have a bottom toolbar for primary actions. To add one, use Stack.Toolbar without a placement prop (it defaults to "bottom"):

import { Stack } from 'expo-router';
import { Alert } from 'react-native';

export default function PhotosScreen() {
  return (
    <>
      <Stack.Toolbar>
        <Stack.Toolbar.Button icon="photo.on.rectangle" onPress={() => Alert.alert('Select')}>
          Select
        </Stack.Toolbar.Button>
        <Stack.Toolbar.Spacer />
        <Stack.Toolbar.Button icon="plus" onPress={() => Alert.alert('Add')}>
          Add
        </Stack.Toolbar.Button>
      </Stack.Toolbar>
    </>
  );
}

Stack.Toolbar.Spacer 在项目之间创建灵活的空间，将它们推到相对的两端。这就是如何实现像在工具栏两端都有按钮的布局的方式。

信息 底部工具栏只能在页面组件内使用，不能在布局文件中使用。

在按钮上添加徽章

🌐 Adding badges to buttons

在标题工具栏中，你可以添加徽章以显示计数或状态。使用 Stack.Toolbar.Icon、Stack.Toolbar.Label 和 Stack.Toolbar.Badge 来组合按钮内容：

🌐 In header toolbars, you can add badges to indicate counts or status. Use Stack.Toolbar.Icon, Stack.Toolbar.Label, and Stack.Toolbar.Badge to compose the button content:

import { Stack } from 'expo-router';

export default function InboxScreen() {
  const unreadCount = 5;

  return (
    <>
      <Stack.Toolbar placement="right">
        <Stack.Toolbar.Button onPress={() => {}}>
          <Stack.Toolbar.Icon sf="bell" />
          <Stack.Toolbar.Label>Notifications</Stack.Toolbar.Label>
          {unreadCount > 0 && <Stack.Toolbar.Badge>{String(unreadCount)}</Stack.Toolbar.Badge>}
        </Stack.Toolbar.Button>
      </Stack.Toolbar>
      {/* Screen content */}
    </>
  );
}

信息 徽章仅在标题位置（left 或 right）有效，底部工具栏不起作用。

嵌入自定义视图

🌐 Embedding custom views

当你需要超越按钮和菜单的功能时，请使用 Stack.Toolbar.View 来嵌入任意 React Native 组件：

🌐 When you need something beyond buttons and menus, use Stack.Toolbar.View to embed any React Native component:

import { Stack } from 'expo-router';
import { Pressable, Alert } from 'react-native';
import { SymbolView } from 'expo-symbols';

export default function SearchScreen() {
  return (
    <>
      <Stack.Toolbar>
        <Stack.Toolbar.View>
          <Pressable
            style={{ width: 32, height: 32, justifyContent: 'center', alignItems: 'center' }}
            onPress={() => {
              Alert.alert('Filter pressed');
            }}>
            <SymbolView name="line.3.horizontal.decrease.circle" size={24} />
          </Pressable>
        </Stack.Toolbar.View>
      </Stack.Toolbar>
      {/* Screen content */}
    </>
  );
}

动态显示和隐藏项目

🌐 Showing and hiding items dynamically

使用 hidden 属性根据状态切换工具栏项：

🌐 Use the hidden prop to toggle toolbar items based on state:

import { useState } from 'react';
import { Stack } from 'expo-router';

export default function DocumentScreen() {
  const [isEditing, setIsEditing] = useState(false);

  return (
    <>
      <Stack.Toolbar placement="right">
        <Stack.Toolbar.Button hidden={isEditing} icon="pencil" onPress={() => setIsEditing(true)} />
        <Stack.Toolbar.Button hidden={!isEditing} onPress={() => setIsEditing(false)}>
          Done
        </Stack.Toolbar.Button>
      </Stack.Toolbar>
      {/* Document content */}
    </>
  );
}

常见问题

🌐 Common problems

import { ThemeProvider, DarkTheme, DefaultTheme } from '@react-navigation/native';
import { 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>
  );
}

import { ThemeProvider, DarkTheme, DefaultTheme } from '@react-navigation/native';
import { 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>
  );
}

import { Stack } from 'expo-router';
import { ScrollView, View, Text } from 'react-native';

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

import { Stack } from 'expo-router';
import { ScrollView, View, Text } from 'react-native';

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

已知的限制

🌐 Known limitations

了解更多

🌐 Learn more

有关完整的 API 文档，包括所有可用属性，请参见 Stack.Toolbar API 参考。

🌐 For complete API documentation, including all available props, see the Stack.Toolbar API reference.