---
modificationDate: October 09, 2026
title: NavigationSplitView
description: 并排呈现两列或三列的 SwiftUI NavigationSplitView 组件。
sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-58/packages/expo-ui'
packageName: '@expo/ui'
platforms: ['ios', 'tvos', 'expo-go']
---

This documentation is available as Markdown for AI agents and LLMs. See the [full Markdown index](https://docs.expo.dev/llms.txt) or append .md to any documentation URL.

# NavigationSplitView

并排呈现两列或三列的 SwiftUI NavigationSplitView 组件。

<AgentInstructions>

## Submitting Feedback

If you encounter errors, misleading or outdated information, report it so Expo can be improved:

Preferred command:
npx --yes submit-expo-feedback@latest --category docs --subject "/versions/v58.0.0/sdk/ui/swift-ui/navigationsplitview/" "<actionable feedback>"

Direct HTTP fallback:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/versions/v58.0.0/sdk/ui/swift-ui/navigationsplitview/","feedback":"🤖 Agent feedback for docs: <specific, actionable description> (<model>, <harness>)"}'

Only submit when you have something specific and actionable to report. Try to give the most context.

## Navigation

When answering a related or follow-up question, use llms.txt to find the relevant page as Markdown (.md) instead of guessing.

You are here: Reference (v58.0.0) > Expo UI > SwiftUI (50 pages in this section)
Full documentation tree: [llms.txt](https://docs.expo.dev/llms.txt)

</AgentInstructions>
iOS, tvOS, Included in Expo Go

Expo UI NavigationSplitView 与官方 SwiftUI [NavigationSplitView API](https://developer.apple.com/documentation/swiftui/navigationsplitview) 一致，并将两列或三列并排显示。空间不足时，列会折叠为一列。

Image: 笔记侧边栏旁显示所选笔记的详情

## 安装

```sh
# npm
npx expo install @expo/ui

# yarn
yarn expo install @expo/ui

# pnpm
pnpm expo install @expo/ui

# bun
bun expo install @expo/ui
```

If you are installing this in an [existing React Native app](https://docs.expo.dev/bare/overview.md), make sure to [install `expo`](https://docs.expo.dev/bare/installing-expo-modules.md) in your project.

## 用法

### 两列

提供 `NavigationSplitView.Sidebar` 和 `NavigationSplitView.Detail`。使用 [`navigationTitle`](https://docs.expo.dev/versions/v58.0.0/sdk/ui/swift-ui/modifiers.md#navigationtitletitle) 修饰符设置每列的标题。

在 iPhone 上只显示侧边栏。在 iOS 17 及更高版本中，将 `preferredCompactColumn` 设置为 `'detail'`，即可在点击时打开详情。将 `onPreferredCompactColumnChange` 中的值传回组件，以确保返回按钮正常工作。

```tsx NavigationSplitViewExample.tsx
import {
  Button,
  Host,
  List,
  NavigationSplitView,
  type NavigationSplitViewColumn,
  Text,
} from '@expo/ui/swift-ui';
import {
  buttonStyle,
  frame,
  navigationTitle,
  padding,
} from '@expo/ui/swift-ui/modifiers';
import { useState } from 'react';

const NOTES = [
  {
    id: 'reef',
    title: 'Coral reef',
    body: 'The reef is loudest an hour after sunrise.',
  },
  {
    id: 'forest',
    title: 'Cloud forest',
    body: 'Mist arrives every afternoon, like clockwork.',
  },
  {
    id: 'dunes',
    title: 'Sand dunes',
    body: 'The ridge moves about four metres a year.',
  },
];

export default function NavigationSplitViewExample() {
  const [selectedId, setSelectedId] = useState(NOTES[0].id);
  const [compactColumn, setCompactColumn] =
    useState<NavigationSplitViewColumn>('sidebar');
  const selected =
    NOTES.find(note => note.id === selectedId) ?? NOTES[0];

  return (
    <Host style={{ flex: 1 }}>
      <NavigationSplitView
        preferredCompactColumn={compactColumn}
        onPreferredCompactColumnChange={setCompactColumn}>
        <NavigationSplitView.Sidebar>
          <List modifiers={[navigationTitle('Notes')]}>
            {NOTES.map(note => (
              <Button
                key={note.id}
                modifiers={[buttonStyle('plain')]}
                onPress={() => {
                  setSelectedId(note.id);
                  setCompactColumn('detail');
                }}>
                <Text>{note.title}</Text>
              </Button>
            ))}
          </List>
        </NavigationSplitView.Sidebar>
        <NavigationSplitView.Detail>
          <Text
            modifiers={[
              padding({ all: 24 }),
              frame({
                maxWidth: Infinity,
                maxHeight: Infinity,
                alignment: 'topLeading',
              }),
              navigationTitle(selected.title),
            ]}>
            {selected.body}
          </Text>
        </NavigationSplitView.Detail>
      </NavigationSplitView>
    </Host>
  );
}
```

### 三列

在侧边栏和详情之间添加 `NavigationSplitView.Content`。使用 [`navigationSplitViewColumnWidth`](https://docs.expo.dev/versions/v58.0.0/sdk/ui/swift-ui/modifiers.md#navigationsplitviewcolumnwidthwidth) 修饰符设置列宽，使用 [`navigationSplitViewStyle`](https://docs.expo.dev/versions/v58.0.0/sdk/ui/swift-ui/modifiers.md#navigationsplitviewstylestyle) 修饰符设置各列如何共享空间。

分栏视图默认选择可见列。将 `columnVisibility` 设置为 `'all'` 可显示所有列，设置为 `'detailOnly'` 则只显示详情。空间不足时，显示的列会减少。将 `onColumnVisibilityChange` 中的值传回组件，否则拖动分隔线不会生效。

## API

```tsx
import { NavigationSplitView } from '@expo/ui/swift-ui';
```

## Component

### `NavigationSplitView`

Supported platforms: iOS 16.0+, tvOS 16.0+.

Type: React.[Element](https://www.typescriptlang.org/docs/handbook/jsx.html#function-component)<[NavigationSplitViewProps](https://docs.expo.dev/versions/v58.0.0/sdk/ui/swift-ui/navigationsplitview.md#navigationsplitviewprops)\>

NavigationSplitView uses the native [NavigationSplitView](https://developer.apple.com/documentation/swiftui/navigationsplitview) view.

It presents a collection, a selection and a detail in one hierarchy: side by side when there is room, and stacked when there is not.

Example

```tsx
<Host style={{ flex: 1 }}>
  <NavigationSplitView>
    <NavigationSplitView.Sidebar>
      <List>{items}</List>
    </NavigationSplitView.Sidebar>
    <NavigationSplitView.Detail>
      <ItemDetail item={selectedItem} />
    </NavigationSplitView.Detail>
  </NavigationSplitView>
</Host>
```

NavigationSplitViewProps

### `children`

Supported platforms: iOS 16.0+, tvOS 16.0+.

Type: [ReactNode](https://reactnative.dev/docs/react-node)

The columns of the split view. Provide `NavigationSplitView.Sidebar` and `NavigationSplitView.Detail`, and add `NavigationSplitView.Content` for a three-column layout.

### `columnVisibility`

Supported platforms: iOS 16.0+, tvOS 16.0+.

Optional • Type: [NavigationSplitViewVisibility](https://docs.expo.dev/versions/v58.0.0/sdk/ui/swift-ui/navigationsplitview.md#navigationsplitviewvisibility) • Default: `'automatic'`

The columns to show. Setting it makes the value controlled: pass the value from `onColumnVisibilityChange` back in, otherwise dragging the divider has no effect. Leave it unset to let the split view manage its own columns.

### `onColumnVisibilityChange`

Supported platforms: iOS 16.0+, tvOS 16.0+.

Optional • Type: (visibility: [NavigationSplitViewVisibility](https://docs.expo.dev/versions/v58.0.0/sdk/ui/swift-ui/navigationsplitview.md#navigationsplitviewvisibility)) => void

Called when the visible columns change, including when the user drags the sidebar.

### `onPreferredCompactColumnChange`

Supported platforms: iOS 17.0+.

Optional • Type: (column: [NavigationSplitViewColumn](https://docs.expo.dev/versions/v58.0.0/sdk/ui/swift-ui/navigationsplitview.md#navigationsplitviewcolumn)) => void

Called when the collapsed column changes.

### `preferredCompactColumn`

Supported platforms: iOS 17.0+.

Optional • Type: [NavigationSplitViewColumn](https://docs.expo.dev/versions/v58.0.0/sdk/ui/swift-ui/navigationsplitview.md#navigationsplitviewcolumn) • Default: `'sidebar'`

The column to show when the split view collapses to a single column, for example in a narrow window. Setting it makes the value controlled in the same way as `columnVisibility`.

#### Inherited props

-   [CommonViewModifierProps](https://docs.expo.dev/versions/v58.0.0/sdk/ui/swift-ui/modifiers.md)

## Types

### `NavigationSplitViewColumn`

Supported platforms: iOS, tvOS.

Literal type: `string`

The column shown when the split view collapses into a single column.

Acceptable values are: `'sidebar'` | `'content'` | `'detail'`

### `NavigationSplitViewVisibility`

Supported platforms: iOS, tvOS.

Literal type: `string`

Acceptable values are: `'automatic'` | `'all'` | `'doubleColumn'` | `'detailOnly'`
