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 组件。
如需跨平台使用,请参阅通用
List— 它会根据平台渲染相应的原生组件。
Expo UI List 与官方 SwiftUI List API 相匹配,并支持通过 listStyle 修饰符、各种行和分区修饰符,以及选择、重新排序和编辑功能进行样式设置。


安装
If you are installing this in an existing React Native app, make sure to install expo in your project.
用法
基本列表
带标签和图标的列表
大型列表
使用 List.ForEach 从数组渲染行。将项目作为 data 传入,使用 keyExtractor 为每个项目提供唯一键,并传入一个返回项目行的 children 函数。List.ForEach 只渲染可见区域附近的行,并在滚动时复用这些行。
渲染行时请遵循以下规则:
- 在组件外定义
children函数,或使用useCallback包装它。否则,每次组件渲染时,可见区域附近的行都会重新渲染。 - 复用的行会保留之前显示项目的本地状态(
useState)。项目变化时重置状态,或将状态保存在行外部。 - 尚未准备好的行会显示空占位符。将
estimatedItemSize设置为接近行内容高度的值(不包括List内边距),单位为点。 - 使用
overscanCount在可见行的上方和下方预先准备更多行。 - 要更新行,请传入新的
data数组。不要原地修改数组。 - 设置
recycling={false}可预先渲染每一行。
列表样式
使用 listStyle 修饰符更改列表的外观。
注意: tvOS 不支持
inset、insetGrouped和sidebar样式。
选择和编辑模式
使用复合组件 List.ForEach 的 onDelete 和 onMove 属性启用列表项的选择、删除和重新排序。
- 使用
environment修饰符启用编辑模式 - 使用
keyExtractor属性标识项目 - 使用
selection属性控制所选项目 - 使用
moveDisabled和deleteDisabled修饰符,禁用单个项目上的这些操作
下拉刷新
使用 refreshable 修饰符启用下拉刷新功能。
行样式
使用 listRowBackground、listRowSeparator、listRowSeparatorTint 和 listRowInsets 修饰符自定义单个行。将 alignmentGuide 与 listRowSeparatorLeading 指引配合使用,可设置行分隔线的起始位置。
键盘关闭行为
使用 scrollDismissesKeyboard 修饰符控制滚动时键盘的关闭方式。
标题醒目程度
使用 headerProminence 修饰符调整分区标题的视觉醒目程度。
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<T>>
A group of rows inside List, with optional deletion and reordering.
Pass data with keyExtractor, and render each row from a children function.
Recycles rows unless recycling is false.
(info: {
index: number,
item: T
}) => ReactElementRenders a row. When recycling is true, wrap it in useCallback, or every row
re-renders on each parent render.
Recycled rows are reused for other items, so their local state (useState) carries over.
Reset it when the item changes, or keep the state outside the row.
number • Default: 64Placeholder height in points, excluding List insets, until a row is measured.
Must be positive. Ignored when recycling is false.
(item: T, index: number) => stringReturns a stable, unique string key, also used for List selection.
(indices: number[]) => voidCalled with deleted indices from this group's data array.
(sourceIndices: number[], destination: number) => voidCalled with the source indices and the destination index. The destination index counts
positions before the moved items are removed, so it can equal data.length.
number • Default: 10Extra rows to prepare on each side of the visible rows. Must be a non-negative integer.
Ignored when recycling is false.
boolean • Default: trueRenders only the rows near the visible range and reuses them while scrolling. Set to false to
render every row at once. Set it once; changing it remounts the rows.