Reference version

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

NavigationStack

包含链接和目标视图、可将视图推入导航栈的 SwiftUI NavigationStack 组件。

iOS
tvOS
Included in Expo Go

Expo UI NavigationStack 与官方 SwiftUI NavigationStack API 一致,并显示一个可以将其他视图推入其上的根视图。

点击 NavigationLink 会推入具有相同 value 的 NavigationDestination。

安装

Terminal
- npx expo install @expo/ui
- yarn expo install @expo/ui
- pnpm expo install @expo/ui
- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

基本导航

将根视图和目标视图放入导航栈中。为链接及其目标视图设置相同的 value。使用 navigationTitle 修饰符设置每个屏幕的标题。

NavigationStackExample.tsx
import { Host, List, NavigationDestination, NavigationLink, NavigationStack, Text, VStack, } from '@expo/ui/swift-ui'; import { navigationTitle, padding, } from '@expo/ui/swift-ui/modifiers'; export default function NavigationStackExample() { return ( <Host style={{ flex: 1 }}> <NavigationStack> <List modifiers={[navigationTitle('Settings')]}> <NavigationLink value="account"> <Text>Account</Text> </NavigationLink> <NavigationLink value="notifications"> <Text>Notifications</Text> </NavigationLink> </List> <NavigationDestination value="account"> <VStack modifiers={[ padding({ all: 20 }), navigationTitle('Account'), ]}> <Text>Signed in as [email protected]</Text> </VStack> </NavigationDestination> <NavigationDestination value="notifications"> <VStack modifiers={[ padding({ all: 20 }), navigationTitle('Notifications'), ]}> <Text>All notifications are on.</Text> </VStack> </NavigationDestination> </NavigationStack> </Host> ); }

在 List 中,链接会渲染为带箭头的一行。无论推入该目标视图的链接嵌套多深,目标视图都必须是导航栈的直接子项。

将任意视图作为链接

链接可以包装任意视图。

NavigationLinkCardExample.tsx
import { Host, HStack, Image, NavigationDestination, NavigationLink, NavigationStack, Spacer, Text, VStack, } from '@expo/ui/swift-ui'; import { font, foregroundStyle, navigationTitle, padding, } from '@expo/ui/swift-ui/modifiers'; export default function NavigationLinkCardExample() { return ( <Host style={{ flex: 1 }}> <NavigationStack> <VStack modifiers={[ padding({ all: 20 }), navigationTitle('Today'), ]}> <NavigationLink value="report"> <HStack spacing={12}> <Image systemName="chart.bar.fill" size={28} /> <VStack alignment="leading" spacing={2}> <Text modifiers={[font({ textStyle: 'headline' })]}> Weekly report </Text> <Text modifiers={[ font({ textStyle: 'caption' }), foregroundStyle('secondaryLabel'), ]}> Ready to read </Text> </VStack> <Spacer /> </HStack> </NavigationLink> </VStack> <NavigationDestination value="report"> <VStack modifiers={[ padding({ all: 20 }), navigationTitle('Weekly report'), ]}> <Text>Sessions are up by 12% on last week.</Text> </VStack> </NavigationDestination> </NavigationStack> </Host> ); }

读取和设置路径

导航栈默认维护自己的路径。传入 path 和 onPathChange,即可通过状态驱动导航栈。路径按推入顺序保存每个视图的 value。将其设为空数组即可返回根视图。

NavigationStackPathExample.tsx
import { Button, Host, List, NavigationDestination, NavigationLink, NavigationStack, Text, VStack, } from '@expo/ui/swift-ui'; import { navigationTitle, padding, } from '@expo/ui/swift-ui/modifiers'; import { useState } from 'react'; const ARTICLES = ['Nesting', 'Migration', 'Song']; export default function NavigationStackPathExample() { const [path, setPath] = useState<string[]>([]); return ( <Host style={{ flex: 1 }}> <NavigationStack path={path} onPathChange={setPath}> <List modifiers={[navigationTitle('Articles')]}> {ARTICLES.map(article => ( <NavigationLink key={article} value={article}> <Text>{article}</Text> </NavigationLink> ))} </List> {ARTICLES.map(article => ( <NavigationDestination key={article} value={article}> <VStack spacing={12} modifiers={[ padding({ all: 20 }), navigationTitle(article), ]}> <Text> The chapter about {article.toLowerCase()}. </Text> <Button label="Back to the articles" onPress={() => setPath([])} /> </VStack> </NavigationDestination> ))} </NavigationStack> </Host> ); }

向导航栏添加按钮

使用 Toolbar 包装内容,并将按钮放入 Toolbar.Content。

API

import { NavigationDestination, NavigationLink, NavigationStack, } from '@expo/ui/swift-ui';

Component

iOS

Type: React.Element<NavigationStackProps>

A view that displays a root view and enables you to present additional views over the root view.

Example

const [path, setPath] = useState<string[]>([]); <NavigationStack path={path} onPathChange={setPath}> <List> <NavigationLink value="settings"> <Text>Settings</Text> </NavigationLink> </List> <NavigationDestination value="settings"> <SettingsScreen /> </NavigationDestination> </NavigationStack>

NavigationStackProps

children

iOS
Type: ReactNode

The root view of the stack, and the NavigationDestination views the stack can push. It is displayed inside a navigation bar.

onPathChange

iOS
Optional • Type: (path: string[]) => void

Callback function that is called when the stack pushes or pops a view, for example when a NavigationLink is tapped or the user swipes back. Gets called with the new path.

When path is set, the stack is controlled: a push takes effect once the new path comes back through this prop.

path

iOS
Optional • Type: string[]

The values of the views pushed on top of the root view, in the order they were pushed. Leave it undefined to let the stack manage its own path.

Component

iOS

Type: React.Element<NavigationLinkProps>

A view that controls a navigation presentation. In a List it renders as a row with a disclosure chevron, and tapping it pushes the matching NavigationDestination.

The link has to be inside the NavigationStack itself. Content presented from the stack, such as a BottomSheet or a Popover, is its own presentation context and does not reach the stack's destinations, so give that content its own NavigationStack.

Example

<NavigationLink value="settings"> <Text>Settings</Text> </NavigationLink>

NavigationLinkProps

children

iOS
Type: ReactNode

A view that describes the link.

value

iOS
Type: string

The value to append to the enclosing NavigationStack's path when the link is tapped. The stack presents the NavigationDestination whose value matches.

Component

iOS

Type: React.Element<NavigationDestinationProps>

Associates a destination view with a NavigationLink value, matching SwiftUI's navigationDestination(for:destination:). It must be a direct child of the NavigationStack, however deeply the link that pushes it is nested inside that stack.

Keep it mounted so the pushed screen already carries its navigationTitle when the slide starts, or render one for each value on the stack's path to build screens on demand.

Example

<NavigationDestination value="settings"> <SettingsScreen /> </NavigationDestination>

NavigationDestinationProps

children

iOS
Type: ReactNode

The view pushed onto the stack for value.

value

iOS
Type: string

The NavigationLink value this destination is presented for.