列表

一个虚拟化的垂直行容器，配有可点击的 ListItem 原语。

Android

iOS

Web

Included in Expo Go

Recommended version:

~57.0.3

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

安装

🌐 Installation

Terminal

- npx 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 { 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);

  return (
    <Host style={{ flex: 1 }}>
      <List>
        {ITEMS.map(item => (
          <ListItem key={item.id} onPress={() => setSelected(item.name)}>
            {item.name}
          </ListItem>
        ))}
      </List>
      {selected != null && <Text>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 { Host, Icon, List, ListItem, Row, Text } from '@expo/ui';

export default function ListItemCompoundExample() {
  return (
    <Host style={{ flex: 1 }}>
      <List>
        <ListItem onPress={() => {}}>
          <ListItem.Leading>
            <Icon name="star.fill" size={20} color="#FFD60A" />
          </ListItem.Leading>
          <Row spacing={0}>
            <Text textStyle={{ color: 'gray' }}>{`#42: `}</Text>
            <Text>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 一致性被接受，但指示器仅在 Android 和 iOS 上显示。

应用接口

🌐 API

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

Component

`List`

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`

Optional • Type: ReactNode

The list rows. Usually <ListItem> elements.

`onRefresh`

Only for:

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`

Optional • Type: string

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

Components

`ListItem`

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`

Optional • Type: ReactNode

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

`leading`

Optional • Type: ReactNode

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

`modifiers`

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`

Optional • Type: () => void

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

`supportingText`

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`

Optional • Type: string

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

`trailing`

Optional • Type: ReactNode

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

`ListItem.Leading`

Type: React.Element<FC<ListItemLeadingProps>>

Props for the ListItem.Leading slot marker.

ListItemLeadingProps

`children`

Optional • Type: ReactNode

Content rendered in the leading (start) slot.

`ListItem.Supporting`

Type: React.Element<FC<ListItemSupportingProps>>

Props for the ListItem.Supporting slot marker.

ListItemSupportingProps

`children`

Optional • Type: ReactNode

Content rendered below the headline.

`ListItem.Trailing`

Type: React.Element<FC<ListItemTrailingProps>>

Props for the ListItem.Trailing slot marker.

ListItemTrailingProps

`children`

Optional • Type: ReactNode

Content rendered in the trailing (end) slot.