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

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

本地实现

🌐 Native implementations

平台支撑组件
AndroidJetpack Compose LazyColumn。当你提供 onRefresh 时,List 会将其封装在 PullToRefreshBox 中。
iOSSwiftUI List。当你提供 onRefresh 时,List 会应用 refreshable 修改器。
WebReact Native View 并带有滚动溢出。
A list with Wi-Fi, Bluetooth, and Cellular rows, each with a blue iconA list with Wi-Fi, Bluetooth, and Cellular rows, each with a blue icon

安装

🌐 Installation

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.

用法

🌐 Usage

基础列表

🌐 Basic list

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> ); }

带槽的行

🌐 Rows with slots

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> ); }

复合槽子子级

🌐 Compound slot children

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

🌐 For full control over slot content, use the compound API: <ListItem.Leading>, <ListItem.Trailing>, and <ListItem.Supporting>. Anything not wrapped in a slot becomes the headline.

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> ); }

下拉刷新

🌐 Pull-to-refresh

传递一个 async onRefresh 处理程序。平台原生的刷新指示器会一直显示,直到返回的承诺(promise)完成(解决或拒绝)。

🌐 Pass an async onRefresh handler. The platform-native refresh indicator stays visible until the returned promise settles (resolves or rejects).

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';

No API data file found, sorry!

No API data file found, sorry!