ListViewItem 列表项

组件功能

列表项组件（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>

效果展示如下：