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.

LazyVStack

一个用于懒加载垂直布局的 SwiftUI LazyVStack 组件。

iOS
tvOS
Included in Expo Go

Expo UI LazyVStack 与官方 SwiftUI LazyVStack API 一致,并沿垂直方向排列其子项。

安装

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.

用法

基本懒加载垂直堆栈

应在 ScrollView 中使用 LazyVStack。LazyVStack 的每个子项都是一行。使用 spacing 和 alignment 属性设置行之间的间距和对齐方式。

BasicLazyVStackExample.tsx
import { Host, ScrollView, LazyVStack, Text, } from '@expo/ui/swift-ui'; export default function BasicLazyVStackExample() { return ( <Host style={{ flex: 1 }}> <ScrollView> <LazyVStack spacing={12}> <Text>Wi-Fi</Text> <Text>Bluetooth</Text> <Text>Notifications</Text> </LazyVStack> </ScrollView> </Host> ); }

大型列表

使用 LazyVStack.ForEach 从数组渲染行。将项目作为 data 传入,使用 keyExtractor 为每个项目提供唯一键,并传入一个返回项目行的 children 函数。LazyVStack.ForEach 只渲染可见区域附近的行,并在滚动时复用这些行。

LargeLazyVStackExample.tsx
import { Host, ScrollView, LazyVStack, Text, } from '@expo/ui/swift-ui'; type Contact = { id: string; name: string }; const contacts: Contact[] = Array.from( { length: 10000 }, (_, i) => ({ id: String(i), name: `Contact ${i + 1}`, }) ); function renderContact({ item }: { item: Contact }) { return <Text>{item.name}</Text>; } export default function LargeLazyVStackExample() { return ( <Host style={{ flex: 1 }}> <ScrollView> <LazyVStack spacing={12}> <LazyVStack.ForEach data={contacts} keyExtractor={contact => contact.id} estimatedItemSize={20}> {renderContact} </LazyVStack.ForEach> </LazyVStack> </ScrollView> </Host> ); }

渲染行时请遵循以下规则:

  • 在组件外定义 children 函数,或使用 useCallback 包装它。否则,每次组件渲染时,可见区域附近的行都会重新渲染。
  • 复用的行会保留之前显示项目的本地状态(useState)。项目变化时重置状态,或将状态保存在行外部。
  • 尚未准备好的行会显示空占位符。将 estimatedItemSize 设置为接近行高的值,单位为点。
  • 使用 overscanCount 在可见行的上方和下方预先准备更多行。
  • 要更新行,请传入新的 data 数组。不要原地修改数组。
  • 设置 recycling={false} 可预先渲染每一行。

API

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

Components

LazyVStackForEach

iOS
tvOS

Type: React.Element<LazyVStackForEachProps<T>>

A block of recycled rows inside LazyVStack. Only a small pool of rows around the visible range is mounted. Rows that are not ready yet show a placeholder of estimatedItemSize, or of the size last measured for that row.

Mount it as a direct child of LazyVStack.

LazyVStackForEachProps

children

iOS
tvOS
Type: (info: { index: number, item: T }) => ReactElement

Renders a row. 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.

data

iOS
tvOS
Type: readonly T[]

Items to display. Replace the array when updating data.

estimatedItemSize

iOS
tvOS
Optional • Type: number • Default: 64

Placeholder size in points along the stack axis, until a row is measured. Must be positive. Ignored when recycling is false.

keyExtractor

iOS
tvOS
Type: (item: T, index: number) => string

Returns a stable, unique string key for each item.

overscanCount

iOS
tvOS
Optional • Type: number • Default: 10

Extra rows to prepare on each side of the visible rows. Must be a non-negative integer. Ignored when recycling is false.

recycling

iOS
tvOS
Optional • Type: boolean • Default: true

Renders 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.

LazyVStack

iOS
tvOS

Type: React.Element<LazyVStackProps>

LazyVStackProps

alignment

iOS
tvOS
Optional • Literal type: string

The horizontal alignment of children within the stack.

Acceptable values are: 'center' | 'leading' | 'trailing'

children

iOS
tvOS
Type: ReactNode

spacing

iOS
tvOS
Optional • Type: number

The spacing between children.