This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
列表 一个用于显示可滚动项目列表的 SwiftUI 列表组件。
Recommended version:
~57.0.22
信息 有关跨平台使用,请参阅通用 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.
信息 List 还没有实现行的懒渲染:React 会一次性创建所有行,所以大型列表的挂载可能会很慢。我们正在努力改进这一点。对于大型列表,我们推荐使用 FlashList 或 Legend List 。
安装
🌐 Installation
- 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.
用法
🌐 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
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.
注意: 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.
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 ( ) => {
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 、listRowSeparatorTint 和 listRowInsets 修饰符来定制单独的行。使用 alignmentGuide 和 listRowSeparatorLeading 指南来设置行分隔符的起始位置。
🌐 Use listRowBackground , listRowSeparator , listRowSeparatorTint , and listRowInsets modifiers to customize individual rows. Use alignmentGuide with the listRowSeparatorLeading guide to set where a row separator starts.
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 = " 样式化行" >
< 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 >
) ;
}
键盘隐藏行为
🌐 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 Type: React.Element < ListProps >
A list component that renders its children using a native SwiftUI List.
The children elements to be rendered inside the list.
Optional • Type: ( selection: ( string | number ) [] ) => void
Callback triggered when the selection changes in a list.
Returns an array of selected item tags.
Optional • Type: ( string | number ) []
The currently selected item tags.
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).
The children elements to be rendered inside the List.ForEach.
Optional • Type: ( indices: number[] ) => void
Callback triggered when items are deleted.
Receives an array of indices that were deleted.
Optional • Type: ( sourceIndices: number[], destination: number ) => void
Callback triggered when items are moved.
Receives the source indices and destination index.