组件功能

列表项组件（ListViewItem）用于在 ListView 中展示单个列表条目，是构建列表型界面的基本单元。

该组件支持灵活的子组件组合、对齐与间距控制，并可配置整行点击动作，适用于信息展示与操作入口并存的场景。

基础用法

通过 children 属性定义列表项内部的展示内容，可组合图标、文本等组件，形成基础列表结构。

Template 示例：

<ListViewItem gap="16px" align="center">
  <Icon name="user" size="lg" />
  <Text value="用户名称" />
</ListViewItem>

效果展示如下：

属性说明

注意：

★ 标记为必填属性。

Alignment 类型说明

用于控制列表项内子组件的垂直对齐方式，支持以下取值：

• "start" - 顶部对齐

• "center" - 居中对齐

• "end" - 底部对齐

• "baseline" - 基线对齐

• "stretch" - 拉伸对齐

交互效果说明

当配置了 onClickAction 时：

• 鼠标悬停时背景变灰。

• 显示 pointer 手形光标。

• 整个列表项可点击。

  适用于跳转、选择等需要触发操作的场景。

使用示例

以下示例展示了一个可点击的列表项，点击后跳转至用户资料页面。

Template 示例：

<ListView>
  <ListViewItem 
    gap="16px" 
    align="center"
    onClickAction={{
      type: "sys.go_to_url",
      payload: { url: "/profile" }
    }}
>
    <Icon name="profile" size="lg" color="#0052D9" />
    <Col gap="4px" flex={1}>
      <Text value="用户资料" size="md" weight="semibold" />
      <Caption value="查看和编辑个人信息" size="sm" />
    </Col>
    <Button label="查看" variant="outline" size="sm" />
  </ListViewItem>
</ListView>

效果展示如下：

典型布局模式

1. 图标 + 文本

适用于简单的列表或轻量信息展示。

Template 示例：

<ListViewItem gap="12px" align="center">
  <Icon name="document" />
  <Text value="文档名称" />
</ListViewItem>

效果展示如下：

2. 图标 + 标题 + 描述

适用于需要展示补充说明信息的列表项。

Template 示例：

<ListViewItem gap="16px" align="center">
  <Icon name="mail" size="lg" />
  <Col gap="4px" flex={1}>
    <Text value="邮件标题" weight="semibold" />
    <Caption value="邮件摘要内容" />
  </Col>
</ListViewItem>

效果展示如下：

3. 完整信息卡片

适用于列表中包含操作按钮的复杂场景。

Template 示例：

<ListViewItem gap="16px" align="center">
  <Image src="https://cdn.xiaowei.qq.com/webim/assets/static/widget/lib-v1.0.0/img/self_introduction.png" size="48px" radius="full" />
  <Col gap="4px" flex={1}>
    <Text value="董俊言(Julian)" weight="semibold" />
    <Caption value="产品经理" />
  </Col>
  <Button label="关注" size="sm" />
</ListViewItem>

效果展示如下：