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.

列表

一个虚拟化的垂直行容器,与可点击的 ListItem 基元配对使用

Android
iOS
Web
Included in Expo Go
Recommended version:
~58.0.1

List 提供一个虚拟化的垂直行容器,通常填充 ListItem 子元素。它提供平台原生的界面样式(分隔线、内嵌样式、下拉刷新)。ListItem 是一个可点击的行,带有 leading/trailing/supportingText 插槽。

原生实现

平台底层组件
AndroidJetpack Compose LazyColumn。当你提供 onRefresh 时,List 会将其包装在 PullToRefreshBox 中。
iOSSwiftUI List。当你提供 onRefresh 时,List 会应用 refreshable 修饰符。
Web带有滚动溢出的 React Native View。
包含 Wi-Fi、Bluetooth 和 Cellular 行的列表,每行都有一个蓝色图标包含 Wi-Fi、Bluetooth 和 Cellular 行的列表,每行都有一个蓝色图标

安装

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.

用法

基本列表

ListExample.tsx
import { useState } from 'react'; import { useColorScheme } from 'react-native'; import { Host, List, ListItem, Text } from '@expo/ui'; const ITEMS = [ { id: 1, name: 'Avocado toast' }, { id: 2, name: 'Bagel with cream cheese' }, { id: 3, name: 'Cappuccino' }, ]; export default function ListExample() { const [selected, setSelected] = useState<string | null>(null); const colorScheme = useColorScheme(); const ink = { color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' }; return ( <Host style={{ flex: 1 }}> <List> {ITEMS.map(item => ( <ListItem key={item.id} onPress={() => setSelected(item.name)}> {item.name} </ListItem> ))} </List> {selected != null && <Text textStyle={ink}>{`Selected: ${selected}`}</Text>} </Host> ); }

带插槽的行

ListItem 接受 leading、trailing 和 supportingText 简写属性,用于常见场景。当需要更丰富的内容时,为其中任意属性传入一个 ReactNode。

ListItemSlotsExample.tsx
import { Host, Icon, List, ListItem } from '@expo/ui'; const CHEVRON = Icon.select({ ios: 'chevron.right', android: require('@expo/material-symbols/chevron_right.xml'), }); export default function ListItemSlotsExample() { return ( <Host style={{ flex: 1 }}> <List> <ListItem onPress={() => {}} trailing={<Icon name={CHEVRON} size={14} color="gray" />} supportingText="Secondary line below the headline"> Profile </ListItem> <ListItem onPress={() => {}} trailing={<Icon name={CHEVRON} size={14} color="gray" />}> Settings </ListItem> </List> </Host> ); }

复合插槽子元素

要完全控制插槽内容,请使用复合 API:<ListItem.Leading>、<ListItem.Trailing> 和 <ListItem.Supporting>。任何未包裹在插槽中的内容都会成为标题。

ListItemCompoundExample.tsx
import { useColorScheme } from 'react-native'; import { Host, Icon, List, ListItem, Row, Text } from '@expo/ui'; const STAR = Icon.select({ ios: 'star.fill', android: require('@expo/material-symbols/star.xml'), }); export default function ListItemCompoundExample() { const colorScheme = useColorScheme(); const ink = { color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' }; return ( <Host style={{ flex: 1 }}> <List> <ListItem onPress={() => {}}> <ListItem.Leading> <Icon name={STAR} size={20} color="#FFD60A" /> </ListItem.Leading> <Row spacing={0}> <Text textStyle={{ color: 'gray' }}>{`#42: `}</Text> <Text textStyle={ink}>Composite headline</Text> </Row> <ListItem.Supporting>Richer slot content</ListItem.Supporting> </ListItem> </List> </Host> ); }

下拉刷新

传入一个 async onRefresh 处理函数。平台原生的刷新指示器会一直显示,直到返回的 promise 完成(resolve 或 reject)。

ListRefreshExample.tsx
import { useState } from 'react'; import { Host, List, ListItem } from '@expo/ui'; export default function ListRefreshExample() { const [items, setItems] = useState([1, 2, 3]); const handleRefresh = async () => { await new Promise(resolve => setTimeout(resolve, 1500)); setItems(prev => [Math.max(...prev) + 1, ...prev]); }; return ( <Host style={{ flex: 1 }}> <List onRefresh={handleRefresh}> {items.map(id => ( <ListItem key={id}>{`Item #${id}`}</ListItem> ))} </List> </Host> ); }

API

import { List, ListItem } from '@expo/ui';

Component

List

Android
iOS
Web

Type: React.Element<ListProps>

A vertical container of rows. Typically populated with ListItem children.

Props for the List component. A virtualized vertical container of rows. Typically populated with ListItem children, though any node is accepted.

ListProps

children

Android
iOS
Web
Optional • Type: ReactNode

The list rows. Usually <ListItem> elements.

onRefresh

Android
iOS
Optional • Type: () => Promise<void>

Optional pull-to-refresh handler. When provided, the list shows the platform-native refresh affordance. The returned promise drives the indicator's visibility.

testID

Android
iOS
Web
Optional • Type: string

Identifier used to locate the component in end-to-end tests.

Components

ListItem

Android
iOS
Web

Type: React.Element<ListItemProps>

A tappable row in a list. Composes with List. Pass row content via the leading / trailing / supportingText shorthand props or the compound <ListItem.Leading> / <ListItem.Trailing> / <ListItem.Supporting> slot children.

Props for the ListItem component. A tappable row in a list.

ListItemProps

children

Android
iOS
Web
Optional • Type: ReactNode

Headline content of the row. The remaining (non-slot) children are rendered in the headline area.

colors

Android
Optional • Type: ListItemColors

Row colors. Applied on Android via Compose's ListItem.colors.

leading

Android
iOS
Web
Optional • Type: ReactNode

Shorthand for the leading slot. Overridden by <ListItem.Leading> if both are provided.

modifiers

Android
iOS
Web
Optional • Type: ModifierConfig[]

Platform-specific modifier escape hatch. Pass an array of modifier configs from @expo/ui/swift-ui/modifiers or @expo/ui/jetpack-compose/modifiers. On iOS these are applied to the underlying SwiftUI Button and can override its default buttonStyle(.plain).

onPress

Android
iOS
Web
Optional • Type: () => void

Tap handler. Activates over the entire row rectangle, including the empty gap between leading/headline/trailing.

supportingText

Android
iOS
Web
Optional • Type: ReactNode

Shorthand for the supporting (sub-)text slot. Strings are rendered with platform-appropriate secondary styling; pass a ReactNode for richer content. Overridden by <ListItem.Supporting> if both are provided.

testID

Android
iOS
Web
Optional • Type: string

Identifier used to locate the component in end-to-end tests.

trailing

Android
iOS
Web
Optional • Type: ReactNode

Shorthand for the trailing slot. Overridden by <ListItem.Trailing> if both are provided.

ListItem.Leading

Android
iOS
Web

Type: React.Element<FC<ListItemLeadingProps>>

Props for the ListItem.Leading slot marker.

ListItemLeadingProps

children

Android
iOS
Web
Optional • Type: ReactNode

Content rendered in the leading (start) slot.

ListItem.Supporting

Android
iOS
Web

Type: React.Element<FC<ListItemSupportingProps>>

Props for the ListItem.Supporting slot marker.

ListItemSupportingProps

children

Android
iOS
Web
Optional • Type: ReactNode

Content rendered below the headline.

ListItem.Trailing

Android
iOS
Web

Type: React.Element<FC<ListItemTrailingProps>>

Props for the ListItem.Trailing slot marker.

ListItemTrailingProps

children

Android
iOS
Web
Optional • Type: ReactNode

Content rendered in the trailing (end) slot.

Interfaces

ListItemColors

Android

Colors for a ListItem's row elements, matching Jetpack Compose's ListItemDefaults.colors() on Android.

PropertyTypeDescription
containerColor(optional)ColorValue
-
contentColor(optional)ColorValue
-
leadingContentColor(optional)ColorValue
-
overlineContentColor(optional)ColorValue
-
supportingContentColor(optional)ColorValue
-
trailingContentColor(optional)ColorValue
-