列表
一个用于显示可滚动项目列表的 SwiftUI 列表组件。
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.
安装
🌐 Installation
- npx expo install @expo/uiIf you are installing this in an existing React Native app, make sure to install expo in your project.
用法
🌐 Usage
基础列表
🌐 Basic list
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
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.
注意:
inset、insetGrouped和sidebar样式在 tvOS 上不可用。
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 复合组件以及 onDelete 和 onMove 属性,启用列表项的选择、删除和重新排序功能。
🌐 Enable selection, deletion, and reordering of list items using the List.ForEach compound component with onDelete and onMove props.
- 使用
environment修饰符来启用编辑模式 - 使用
tag修饰符来识别项目 - 使用
selection属性来控制选中的项目 - 使用
moveDisabled和deleteDisabled修饰符来禁用单个项目上的这些操作
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.
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
使用listRowBackground、listRowSeparator和listRowInsets修饰符来自定义单独的行。
🌐 Use listRowBackground, listRowSeparator, and listRowInsets modifiers to customize individual rows.
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.
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.
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
Type: React.Element<ListProps>
A list component that renders its children using a native SwiftUI List.
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).
(indices: number[]) => voidCallback triggered when items are deleted. Receives an array of indices that were deleted.
See: Official SwiftUI documentation.
(sourceIndices: number[], destination: number) => voidCallback triggered when items are moved. Receives the source indices and destination index.
See: Official SwiftUI documentation.