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

列表

一个用于显示可滚动项目列表的 SwiftUI 列表组件。

iOS
tvOS
Included in Expo Go
Recommended version:
~57.0.3

信息 有关跨平台使用,请参阅通用 List —— 它会根据平台呈现相应的原生组件。

Expo UI 列表与官方 SwiftUI List API 匹配,并支持通过 listStyle 修饰符进行样式设置,以及各种行/节修饰符,还支持选择、重新排序和编辑功能。

🌐 Expo UI List matches the official SwiftUI List API and supports styling via the listStyle modifier, various row/section modifiers, as well as selection, reordering, and editing capabilities.

A List with Favorites and Recents sections, each row showing a colored SF Symbol icon and a label

安装

🌐 Installation

Terminal
npx expo install @expo/ui

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

用法

🌐 Usage

基础列表

🌐 Basic list

BasicListExample.tsx
import { Host, List, Text, Section } from '@expo/ui/swift-ui'; export default function BasicListExample() { return ( <Host style={{ flex: 1 }}> <List> <Section title="水果"> <Text>Apple</Text> <Text>Banana</Text> <Text>Orange</Text> </Section> <Section title="蔬菜"> <Text>Carrot</Text> <Text>Broccoli</Text> <Text>Spinach</Text> </Section> </List> </Host> ); }

带标签和图标的列表

🌐 List with labels and icons

ListWithLabelsExample.tsx
import { Host, List, Label, Section } from '@expo/ui/swift-ui'; export default function ListWithLabelsExample() { return ( <Host style={{ flex: 1 }}> <List> <Section title="设置"> <Label title="无线网络" systemImage="wifi" /> <Label title="蓝牙" systemImage="antenna.radiowaves.left.and.right" /> <Label title="蜂窝网络" systemImage="antenna.radiowaves.left.and.right.circle" /> </Section> </List> </Host> ); }

列表样式

🌐 List styles

使用 listStyle 修饰符来更改列表的显示方式。

🌐 Use the listStyle modifier to change the list's appearance.

注意: insetinsetGroupedsidebar 样式在 tvOS 上不可用。

ListStylesExample.tsx
import { useState } from 'react'; import { Host, List, Text, Section, Picker } from '@expo/ui/swift-ui'; import { listStyle, pickerStyle, tag } from '@expo/ui/swift-ui/modifiers'; const styles = ['automatic', 'plain', 'inset', 'insetGrouped', 'grouped', 'sidebar'] as const; export default function ListStylesExample() { const [styleIndex, setStyleIndex] = useState(0); return ( <Host style={{ flex: 1 }}> <List modifiers={[listStyle(styles[styleIndex])]}> <Section title="样式选择器"> <Picker label="List Style" selection={styleIndex} onSelectionChange={setStyleIndex} modifiers={[pickerStyle('menu')]}> {styles.map((style, index) => ( <Text key={style} modifiers={[tag(index)]}> {style} </Text> ))} </Picker> </Section> <Section title="样品项目"> <Text>Item 1</Text> <Text>Item 2</Text> <Text>Item 3</Text> </Section> </List> </Host> ); }

选择和编辑模式

🌐 Selection and edit mode

使用 List.ForEach 复合组件以及 onDeleteonMove 属性,启用列表项的选择、删除和重新排序功能。

🌐 Enable selection, deletion, and reordering of list items using the List.ForEach compound component with onDelete and onMove props.

EditableListExample.tsx
import { useState } from 'react'; import { Host, List, Label, Section, Button, Toggle } from '@expo/ui/swift-ui'; import { environment, tag } from '@expo/ui/swift-ui/modifiers'; type Task = { id: string; title: string }; const INITIAL_TASKS: Task[] = [ { id: '1', title: 'Task 1' }, { id: '2', title: 'Task 2' }, { id: '3', title: 'Task 3' }, { id: '4', title: 'Task 4' }, ]; export default function EditableListExample() { const [tasks, setTasks] = useState<Task[]>(INITIAL_TASKS); const [selectedIds, setSelectedIds] = useState<string[]>([]); const [editMode, setEditMode] = useState(false); const handleDelete = (indices: number[]) => { setTasks(prev => prev.filter((_, i) => !indices.includes(i))); }; const handleMove = (sourceIndices: number[], destination: number) => { setTasks(prev => { const newTasks = [...prev]; const [removed] = newTasks.splice(sourceIndices[0], 1); const adjustedDest = sourceIndices[0] < destination ? destination - 1 : destination; newTasks.splice(adjustedDest, 0, removed); return newTasks; }); }; return ( <Host style={{ flex: 1 }}> <List selection={selectedIds} onSelectionChange={ids => setSelectedIds(ids.map(String))} modifiers={[environment('editMode', editMode ? 'active' : 'inactive')]}> <Section title="设置"> <Toggle label="Edit Mode" isOn={editMode} onIsOnChange={setEditMode} /> </Section> <Section title="任务"> <List.ForEach onDelete={handleDelete} onMove={handleMove}> {tasks.map(task => ( <Label key={task.id} title={task.title} modifiers={[tag(task.id)]} /> ))} </List.ForEach> </Section> </List> </Host> ); }

下拉刷新

🌐 Pull to refresh

使用 refreshable 修饰符来启用下拉刷新功能。

🌐 Use the refreshable modifier to enable pull-to-refresh functionality.

RefreshableListExample.tsx
import { useState } from 'react'; import { Host, List, Text, Section } from '@expo/ui/swift-ui'; import { refreshable } from '@expo/ui/swift-ui/modifiers'; export default function RefreshableListExample() { const [lastRefresh, setLastRefresh] = useState<Date | null>(null); const handleRefresh = async () => { // Simulate async data fetching await new Promise(resolve => setTimeout(resolve, 1500)); setLastRefresh(new Date()); }; return ( <Host style={{ flex: 1 }}> <List modifiers={[refreshable(handleRefresh)]}> <Section title="数据"> <Text>Pull down to refresh</Text> {lastRefresh && <Text>Last refresh: {lastRefresh.toLocaleTimeString()}</Text>} </Section> </List> </Host> ); }

行样式

🌐 Row styling

使用listRowBackgroundlistRowSeparatorlistRowInsets修饰符来自定义单独的行。

🌐 Use listRowBackground, listRowSeparator, and listRowInsets modifiers to customize individual rows.

RowStylingExample.tsx
import { Host, List, Text, Section } from '@expo/ui/swift-ui'; import { listRowBackground, listRowSeparator, listRowInsets } from '@expo/ui/swift-ui/modifiers'; export default function RowStylingExample() { return ( <Host style={{ flex: 1 }}> <List> <Section title="样式化行"> <Text modifiers={[listRowBackground('blue')]}>Blue background</Text> <Text modifiers={[listRowSeparator('hidden')]}>Hidden separator</Text> <Text modifiers={[listRowInsets({ leading: 40 })]}>Extra leading inset</Text> <Text modifiers={[listRowInsets({ leading: 0, trailing: 0 })]}>No horizontal insets</Text> </Section> </List> </Host> ); }

键盘隐藏行为

🌐 Keyboard dismiss behavior

使用 scrollDismissesKeyboard 修饰符来控制滚动时键盘的收回方式。

🌐 Use the scrollDismissesKeyboard modifier to control how the keyboard is dismissed when scrolling.

KeyboardDismissExample.tsx
import { Host, List, Section, TextField } from '@expo/ui/swift-ui'; import { scrollDismissesKeyboard } from '@expo/ui/swift-ui/modifiers'; export default function KeyboardDismissExample() { return ( <Host style={{ flex: 1 }}> <List modifiers={[scrollDismissesKeyboard('interactively')]}> <Section title="表格"> <TextField placeholder="Name" /> <TextField placeholder="Email" /> <TextField placeholder="Phone" /> </Section> </List> </Host> ); }

标题突出

🌐 Header prominence

使用 headerProminence 修饰符来调整章节标题的视觉突出性。

🌐 Use the headerProminence modifier to adjust the visual prominence of section headers.

HeaderProminenceExample.tsx
import { Host, List, Text, Section } from '@expo/ui/swift-ui'; import { headerProminence } from '@expo/ui/swift-ui/modifiers'; export default function HeaderProminenceExample() { return ( <Host style={{ flex: 1 }}> <List modifiers={[headerProminence('increased')]}> <Section title="重要部分"> <Text>This section has increased header prominence</Text> </Section> <Section title="另一部分"> <Text>Headers are more prominent</Text> </Section> </List> </Host> ); }

应用接口

🌐 API

import { List } from '@expo/ui/swift-ui';

Components

List

Type: React.Element<ListProps>

A list component that renders its children using a native SwiftUI List.

ListProps

children

Type: ReactNode

The children elements to be rendered inside the list.

onSelectionChange

Optional • Type: (selection: (string | number)[]) => void

Callback triggered when the selection changes in a list. Returns an array of selected item tags.

selection

Optional • Type: (string | number)[]

The currently selected item tags.

ListForEach

Type: React.Element<ListForEachProps>

A compound component of List that enables item deletion and reordering. This component must be used as a child of List (as List.ForEach).

ListForEachProps

children

Type: ReactNode

The children elements to be rendered inside the List.ForEach.

onDelete

Optional • Type: (indices: number[]) => void

Callback triggered when items are deleted. Receives an array of indices that were deleted.

See: Official SwiftUI documentation.

onMove

Optional • Type: (sourceIndices: number[], destination: number) => void

Callback triggered when items are moved. Receives the source indices and destination index.

See: Official SwiftUI documentation.