ProComponents, templates & AI tooling
HeroUI
2.3k
快速开始
组件
发布说明

ListGroup 列表组

基于 Surface 的容器，用于分组展示列表项并保持一致的布局与间距。

Figma源代码样式源代码

导入

import { ListGroup } from 'heroui-native';

结构

<ListGroup>
  <ListGroup.Item>
    <ListGroup.ItemPrefix>...</ListGroup.ItemPrefix>
    <ListGroup.ItemContent>
      <ListGroup.ItemTitle>...</ListGroup.ItemTitle>
      <ListGroup.ItemDescription>...</ListGroup.ItemDescription>
    </ListGroup.ItemContent>
    <ListGroup.ItemSuffix />
  </ListGroup.Item>
</ListGroup>
  • ListGroup：基于 Surface 的根容器，用于分组列表项；支持全部 Surface 变体（default、secondary、tertiary、transparent）。
  • ListGroup.Item：可按压的水平 flex-row 行容器，提供统一的间距与对齐。
  • ListGroup.ItemPrefix：可选前导槽，用于图标、头像等。
  • ListGroup.ItemContent：flex-1 包裹标题与说明，占据剩余横向空间。
  • ListGroup.ItemTitle：主标题，前景色与中等字重。
  • ListGroup.ItemDescription：次要说明，弱化颜色与较小字号。
  • ListGroup.ItemSuffix：可选尾部槽；默认渲染右箭头；传入子节点可覆盖默认图标。

用法

基础用法

通过组合子部件创建带标题与说明的分组列表。

<ListGroup>
  <ListGroup.Item>
    <ListGroup.ItemContent>
      <ListGroup.ItemTitle>个人信息</ListGroup.ItemTitle>
      <ListGroup.ItemDescription>
        姓名、邮箱、手机号
      </ListGroup.ItemDescription>
    </ListGroup.ItemContent>
    <ListGroup.ItemSuffix />
  </ListGroup.Item>
  <Separator className="mx-4" />
  <ListGroup.Item>
    <ListGroup.ItemContent>
      <ListGroup.ItemTitle>支付方式</ListGroup.ItemTitle>
      <ListGroup.ItemDescription>
        Visa 尾号 4829
      </ListGroup.ItemDescription>
    </ListGroup.ItemContent>
    <ListGroup.ItemSuffix />
  </ListGroup.Item>
</ListGroup>

带图标

使用 ListGroup.ItemPrefix 放置前置图标。

<ListGroup>
  <ListGroup.Item>
    <ListGroup.ItemPrefix>
      <Icon name="person-outline" size={22} />
    </ListGroup.ItemPrefix>
    <ListGroup.ItemContent>
      <ListGroup.ItemTitle>个人资料</ListGroup.ItemTitle>
      <ListGroup.ItemDescription>
        姓名、照片、简介
      </ListGroup.ItemDescription>
    </ListGroup.ItemContent>
    <ListGroup.ItemSuffix />
  </ListGroup.Item>
  <Separator className="mx-4" />
  <ListGroup.Item>
    <ListGroup.ItemPrefix>
      <Icon name="lock-closed-outline" size={22} />
    </ListGroup.ItemPrefix>
    <ListGroup.ItemContent>
      <ListGroup.ItemTitle>安全</ListGroup.ItemTitle>
      <ListGroup.ItemDescription>
        密码、双重验证
      </ListGroup.ItemDescription>
    </ListGroup.ItemContent>
    <ListGroup.ItemSuffix />
  </ListGroup.Item>
</ListGroup>

仅标题

省略 ListGroup.ItemDescription 以展示仅标题行。

<ListGroup>
  <ListGroup.Item>
    <ListGroup.ItemPrefix>
      <Icon name="wifi-outline" size={22} />
    </ListGroup.ItemPrefix>
    <ListGroup.ItemContent>
      <ListGroup.ItemTitle>Wi-Fi</ListGroup.ItemTitle>
    </ListGroup.ItemContent>
    <ListGroup.ItemSuffix />
  </ListGroup.Item>
  <Separator className="mx-4" />
  <ListGroup.Item>
    <ListGroup.ItemPrefix>
      <Icon name="bluetooth-outline" size={22} />
    </ListGroup.ItemPrefix>
    <ListGroup.ItemContent>
      <ListGroup.ItemTitle>蓝牙</ListGroup.ItemTitle>
    </ListGroup.ItemContent>
    <ListGroup.ItemSuffix />
  </ListGroup.Item>
</ListGroup>

Surface 变体

为根容器应用不同的视觉变体。

<ListGroup variant="transparent">
  <ListGroup.Item>
    <ListGroup.ItemContent>
      <ListGroup.ItemTitle>Wi-Fi</ListGroup.ItemTitle>
    </ListGroup.ItemContent>
    <ListGroup.ItemSuffix />
  </ListGroup.Item>
</ListGroup>

自定义尾部

向 ListGroup.ItemSuffix 传入子节点以覆盖默认箭头。

<ListGroup>
  <ListGroup.Item>
    <ListGroup.ItemContent>
      <ListGroup.ItemTitle>语言</ListGroup.ItemTitle>
      <ListGroup.ItemDescription>简体中文</ListGroup.ItemDescription>
    </ListGroup.ItemContent>
    <ListGroup.ItemSuffix>
      <Icon name="arrow-forward" size={18} />
    </ListGroup.ItemSuffix>
  </ListGroup.Item>
  <Separator className="mx-4" />
  <ListGroup.Item>
    <ListGroup.ItemContent>
      <ListGroup.ItemTitle>通知</ListGroup.ItemTitle>
    </ListGroup.ItemContent>
    <ListGroup.ItemSuffix>
      <Chip variant="primary" color="danger">
        <Chip.Label className="font-bold">7</Chip.Label>
      </Chip>
    </ListGroup.ItemSuffix>
  </ListGroup.Item>
</ListGroup>

自定义尾部图标属性

通过 iconProps 调整默认箭头尺寸与颜色。

<ListGroup>
  <ListGroup.Item>
    <ListGroup.ItemContent>
      <ListGroup.ItemTitle>存储空间</ListGroup.ItemTitle>
      <ListGroup.ItemDescription>
        已用 12.4 GB / 共 50 GB
      </ListGroup.ItemDescription>
    </ListGroup.ItemContent>
    <ListGroup.ItemSuffix iconProps={{ size: 18, color: mutedColor }} />
  </ListGroup.Item>
</ListGroup>

配合 PressableFeedback

用 PressableFeedback 包裹列表项以添加缩放与水波纹反馈。此模式下将 onPress 放在 PressableFeedback 上，并对 ListGroup.Item 使用 disabled。

import { ListGroup, PressableFeedback, Separator } from 'heroui-native';

<ListGroup>
  <PressableFeedback animation={false} onPress={() => {}}>
    <PressableFeedback.Scale>
      <ListGroup.Item disabled>
        <ListGroup.ItemContent>
          <ListGroup.ItemTitle>外观</ListGroup.ItemTitle>
          <ListGroup.ItemDescription>
            主题、字号、显示
          </ListGroup.ItemDescription>
        </ListGroup.ItemContent>
        <ListGroup.ItemSuffix />
      </ListGroup.Item>
    </PressableFeedback.Scale>
    <PressableFeedback.Ripple />
  </PressableFeedback>
  <Separator className="mx-4" />
  <PressableFeedback animation={false} onPress={() => {}}>
    <PressableFeedback.Scale>
      <ListGroup.Item disabled>
        <ListGroup.ItemContent>
          <ListGroup.ItemTitle>通知</ListGroup.ItemTitle>
          <ListGroup.ItemDescription>
            提醒、声音、角标
          </ListGroup.ItemDescription>
        </ListGroup.ItemContent>
        <ListGroup.ItemSuffix />
      </ListGroup.Item>
    </PressableFeedback.Scale>
    <PressableFeedback.Ripple />
  </PressableFeedback>
</ListGroup>

示例

import { Ionicons } from '@expo/vector-icons';
import { ListGroup, Separator, useThemeColor } from 'heroui-native';
import { View, Text } from 'react-native';
import { withUniwind } from 'uniwind';

const StyledIonicons = withUniwind(Ionicons);

export default function ListGroupExample() {
  const mutedColor = useThemeColor('muted');

  return (
    <View className="flex-1 justify-center px-5">
      <Text className="text-sm text-muted mb-2 ml-2">账户</Text>
      <ListGroup className="mb-6">
        <ListGroup.Item>
          <ListGroup.ItemPrefix>
            <StyledIonicons
              name="person-outline"
              size={22}
              className="text-foreground"
            />
          </ListGroup.ItemPrefix>
          <ListGroup.ItemContent>
            <ListGroup.ItemTitle>个人信息</ListGroup.ItemTitle>
            <ListGroup.ItemDescription>
              姓名、邮箱、手机号
            </ListGroup.ItemDescription>
          </ListGroup.ItemContent>
          <ListGroup.ItemSuffix />
        </ListGroup.Item>
        <Separator className="mx-4" />
        <ListGroup.Item>
          <ListGroup.ItemPrefix>
            <StyledIonicons
              name="card-outline"
              size={22}
              className="text-foreground"
            />
          </ListGroup.ItemPrefix>
          <ListGroup.ItemContent>
            <ListGroup.ItemTitle>支付方式</ListGroup.ItemTitle>
            <ListGroup.ItemDescription>
              Visa 尾号 4829
            </ListGroup.ItemDescription>
          </ListGroup.ItemContent>
          <ListGroup.ItemSuffix />
        </ListGroup.Item>
      </ListGroup>
      <Text className="text-sm text-muted mb-2 ml-2">偏好设置</Text>
      <ListGroup>
        <ListGroup.Item>
          <ListGroup.ItemPrefix>
            <StyledIonicons
              name="color-palette-outline"
              size={22}
              className="text-foreground"
            />
          </ListGroup.ItemPrefix>
          <ListGroup.ItemContent>
            <ListGroup.ItemTitle>外观</ListGroup.ItemTitle>
            <ListGroup.ItemDescription>
              主题、字号、显示
            </ListGroup.ItemDescription>
          </ListGroup.ItemContent>
          <ListGroup.ItemSuffix />
        </ListGroup.Item>
        <Separator className="mx-4" />
        <ListGroup.Item>
          <ListGroup.ItemPrefix>
            <StyledIonicons
              name="notifications-outline"
              size={22}
              className="text-foreground"
            />
          </ListGroup.ItemPrefix>
          <ListGroup.ItemContent>
            <ListGroup.ItemTitle>通知</ListGroup.ItemTitle>
            <ListGroup.ItemDescription>
              提醒、声音、角标
            </ListGroup.ItemDescription>
          </ListGroup.ItemContent>
          <ListGroup.ItemSuffix iconProps={{ size: 18, color: mutedColor }} />
        </ListGroup.Item>
      </ListGroup>
    </View>
  );
}

更多示例见 GitHub 仓库。

API 参考

ListGroup

proptypedefaultdescription
childrenReact.ReactNode-分组内的子节点
variant'default' | 'secondary' | 'tertiary' | 'transparent''default'底层 Surface 容器的视觉变体
classNamestring-根容器额外 class
...ViewPropsViewProps-支持全部标准 React Native View 属性

ListGroup.Item

proptypedefaultdescription
childrenReact.ReactNode-列表行内的子节点
classNamestring-列表行额外 class
...PressablePropsPressableProps-支持全部标准 React Native Pressable 属性

ListGroup.ItemPrefix

proptypedefaultdescription
childrenReact.ReactNode-前导内容，如图标或头像
classNamestring-前导区域额外 class
...ViewPropsViewProps-支持全部标准 React Native View 属性

ListGroup.ItemContent

proptypedefaultdescription
childrenReact.ReactNode-内容区，通常为标题与说明
classNamestring-内容区额外 class
...ViewPropsViewProps-支持全部标准 React Native View 属性

ListGroup.ItemTitle

proptypedefaultdescription
childrenReact.ReactNode-标题文本或自定义内容
classNamestring-标题额外 class
...ViewPropsViewProps-支持全部标准 React Native View 属性

ListGroup.ItemDescription

proptypedefaultdescription
childrenReact.ReactNode-说明文本或自定义内容
classNamestring-说明额外 class
...ViewPropsViewProps-支持全部标准 React Native View 属性

ListGroup.ItemSuffix

proptypedefaultdescription
childrenReact.ReactNode-自定义尾部内容；提供时将覆盖默认右箭头图标
classNamestring-尾部额外 class
iconPropsListGroupIconProps-自定义默认右箭头图标；仅在无 children 时生效
...ViewPropsViewProps-支持全部标准 React Native View 属性

ListGroupIconProps

proptypedefaultdescription
sizenumber16箭头图标尺寸（像素）
colorstring主题的 muted 颜色箭头图标颜色

LinkButton 链接按钮

幽灵样式按钮，无高亮按压反馈，适合行内链接式交互。

Menu 菜单

浮动上下文菜单，支持定位、选择分组与多种呈现方式。

本页目录

导入结构用法基础用法带图标仅标题Surface 变体自定义尾部自定义尾部图标属性配合 PressableFeedback示例API 参考ListGroupListGroup.ItemListGroup.ItemPrefixListGroup.ItemContentListGroup.ItemTitleListGroup.ItemDescriptionListGroup.ItemSuffixListGroupIconProps