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.

列表

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

iOS
tvOS
Included in Expo Go
Recommended version:
~58.0.1

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

包含 Favorites 和 Recents 分区的列表,每行显示一个彩色 SF Symbol 图标和标签包含 Favorites 和 Recents 分区的列表,每行显示一个彩色 SF Symbol 图标和标签

安装

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.

用法

基本列表

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

带标签和图标的列表

ListWithLabelsExample.tsx
import { Host, List, Label, Section } from '@expo/ui/swift-ui'; export default function ListWithLabelsExample() { return ( <Host style={{ flex: 1 }}> <List> <Section title="Settings"> <Label title="Wi-Fi" systemImage="wifi" /> <Label title="Bluetooth" systemImage="antenna.radiowaves.left.and.right" /> <Label title="Cellular" systemImage="antenna.radiowaves.left.and.right.circle" /> </Section> </List> </Host> ); }

列表样式

使用 listStyle 修饰符更改列表的外观。

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="Style Picker"> <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="Sample Items"> <Text>Item 1</Text> <Text>Item 2</Text> <Text>Item 3</Text> </Section> </List> </Host> ); }

选择和编辑模式

使用复合组件 List.ForEach 的 onDelete 和 onMove 属性启用列表项的选择、删除和重新排序。

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="Settings"> <Toggle label="Edit mode" isOn={editMode} onIsOnChange={setEditMode} /> </Section> <Section title="Tasks"> <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> ); }

下拉刷新

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

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="Data"> <Text>Pull down to refresh</Text> {lastRefresh && ( <Text> Last refresh: {lastRefresh.toLocaleTimeString()} </Text> )} </Section> </List> </Host> ); }

行样式

使用 listRowBackground、listRowSeparator、listRowSeparatorTint 和 listRowInsets 修饰符自定义单个行。将 alignmentGuide 与 listRowSeparatorLeading 指引配合使用,可设置行分隔线的起始位置。

RowStylingExample.tsx
import { Host, List, Text, Section } from '@expo/ui/swift-ui'; import { alignmentGuide, listRowBackground, listRowSeparator, listRowSeparatorTint, listRowInsets, } from '@expo/ui/swift-ui/modifiers'; export default function RowStylingExample() { return ( <Host style={{ flex: 1 }}> <List> <Section title="Styled Rows"> <Text modifiers={[listRowBackground('blue')]}> Blue background </Text> <Text modifiers={[listRowSeparator('hidden')]}> Hidden separator </Text> <Text modifiers={[listRowSeparatorTint('red')]}> Red separator </Text> <Text modifiers={[listRowInsets({ leading: 40 })]}> Extra leading inset </Text> <Text modifiers={[ listRowInsets({ leading: 0, trailing: 0 }), ]}> No horizontal insets </Text> <Text modifiers={[ alignmentGuide('listRowSeparatorLeading', 32), ]}> Separator starts 32 points in </Text> </Section> </List> </Host> ); }

键盘关闭行为

使用 scrollDismissesKeyboard 修饰符控制滚动时键盘的关闭方式。

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="Form"> <TextField placeholder="Name" /> <TextField placeholder="Email" /> <TextField placeholder="Phone" /> </Section> </List> </Host> ); }

标题醒目程度

使用 headerProminence 修饰符调整分区标题的视觉醒目程度。

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="Important Section"> <Text>This section has increased header prominence</Text> </Section> <Section title="Another Section"> <Text>Headers are more prominent</Text> </Section> </List> </Host> ); }

API

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

Components

List

iOS
tvOS

Type: React.Element<ListProps>

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

ListProps

children

iOS
tvOS
Type: ReactNode

The children elements to be rendered inside the list.

onSelectionChange

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

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

selection

iOS
tvOS
Optional • Type: (string | number)[]

The currently selected item tags.

ListForEach

iOS
tvOS

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

iOS
tvOS
Type: ReactNode

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

onDelete

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

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

onMove

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

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