Cell 单元格 - Vant 4

Cell 单元格

🎯 介绍

Cell 单元格就像是移动应用界面中的"万能积木" 🧱！它是构建列表页面的基础元素，就像乐高积木一样，可以自由组合搭建出各种精美的界面。

无论是设置页面的选项列表、联系人信息展示，还是商品详情的属性说明，Cell 都能以简洁优雅的方式呈现信息，让复杂的数据变得井井有条 ✨。它就像一个贴心的"信息管家"，帮你把内容整理得清晰明了！

📦 引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from'vue'; import { Cell, CellGroup } from'vant'; const app = createApp(); app.use(Cell); app.use(CellGroup);

🚀 代码演示

基础用法

Cell 就像一个独立的"小房间" 🏠，可以单独存在，也可以和兄弟姐妹们住在 CellGroup 这个"大家庭"里。

当 Cell 们聚在一起时，CellGroup 就像一个贴心的"管家"，为它们提供统一的边框装饰，让整个列表看起来更加整齐美观 ✨。

卡片风格

想要让你的列表更有现代感？🎨 通过 CellGroup 的 inset 属性，就能瞬间把普通的列表变成时尚的圆角卡片！

这种卡片风格就像给内容穿上了一件优雅的"外套"，让信息展示更加精致，特别适合现代化的应用设计 💫。

单元格大小

想要调整 Cell 的"身材"？💪 通过 size 属性就能轻松控制！

就像给衣服选择尺码一样，你可以让 Cell 变得更紧凑或更宽松，完美适配不同的设计需求 👔。

展示图标

为你的 Cell 添加一个醒目的"小徽章"！🎖️ 通过 icon 属性，可以在标题左侧放置各种精美的图标。

这些小图标就像是内容的"身份证"，让用户一眼就能识别不同类型的信息，提升界面的可读性和美观度 ✨。

展示箭头

想要暗示用户"这里可以点击"？👆 设置 is-link 属性后，Cell 右侧就会出现一个优雅的小箭头！

而且这个箭头还很"听话"，通过 arrow-direction 属性可以让它指向上下左右任意方向，就像一个贴心的"导航员" 🧭。

页面导航

让你的 Cell 变身"传送门"！🚪 通过 url 属性可以实现网页跳转，或者用 to 属性进行路由导航。

就像给每个 Cell 都装上了"小火箭"，用户轻轻一点就能飞到目标页面，体验丝滑的页面切换 🚀。

分组标题

想要给你的列表加个"小标签"？🏷️ 通过 CellGroup 的 title 属性就能为一组 Cell 添加醒目的标题。

这个标题就像是"章节名"，帮助用户快速理解下面内容的分类，让信息结构更加清晰明了 📚。

使用插槽

当标准配置无法满足你的创意时，插槽就是你的"魔法工具箱"！🎩✨

通过插槽可以自由定制 Cell 的任何部分，让你的想象力尽情发挥，打造独一无二的界面效果 🎨。

垂直居中

追求完美对齐？通过 center 属性可以让 Cell 的左侧图标与右侧内容都完美垂直居中！

就像给内容们排了一个整齐的"队列"，无论高矮胖瘦都能站在同一条水平线上，看起来特别舒服 😌。

API

CellGroup Props

参数	说明	类型	默认值
title	分组标题	string	-
inset	是否展示为圆角卡片风格	boolean	false
border	是否显示外边框	boolean	true

Cell Props

参数	说明	类型	默认值
title	左侧标题	*number	string*
value	右侧内容	*number	string*
label	标题下方的描述信息	*number	string*
size	单元格大小，可选值为 large``normal	string	-
icon	左侧图标名称或图片链接，等同于 Icon 组件的 name 属性	string	-

| icon-prefix | 图标类名前缀，等同于 Icon 组件的 class-prefix 属性 | string | van-icon |

| tag | 根节点对应的 HTML 标签名 | string | div | | url | 点击后跳转的链接地址 | string | - | | to | 点击后跳转的目标路由对象，等同于 Vue Router 的 to 属性 | string | object | - |

| border | 是否显示内边框 | boolean | true | | replace | 是否在跳转时替换当前页面历史 | boolean | false | | clickable | 是否开启点击反馈 | boolean | null | | is-link | 是否展示右侧箭头并开启点击反馈 | boolean | false | | required | 是否显示表单必填星号 | boolean | false | | center | 是否使内容垂直居中 | boolean | false | | arrow-direction | 箭头方向，可选值为 left``up``down | string | right | | title-style | 左侧标题额外样式 | string | Array | object | - | | title-class | 左侧标题额外类名 | string | Array | object | - | | value-class | 右侧内容额外类名 | string | Array | object | - | | label-class | 描述信息额外类名 | string | Array | object | - |

Cell Events

事件名	说明	回调参数
click	点击单元格时触发	event: MouseEvent

CellGroup Slots

名称	说明
default	默认插槽
title	自定义分组标题

Cell Slots

名称	说明
title	自定义左侧标题
value	自定义右侧内容
label	自定义标题下方的描述信息
icon	自定义左侧图标
right-icon	自定义右侧图标
extra	自定义单元格最右侧的额外内容

类型定义

组件导出以下类型定义：

importtype { CellSize, CellProps, CellGroupProps, CellArrowDirection, } from'vant';

主题定制

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-cell-font-size	var(--van-font-size-md)	-
--van-cell-line-height	24px	-
--van-cell-vertical-padding	10px	-
--van-cell-horizontal-padding	var(--van-padding-md)	-
--van-cell-text-color	var(--van-text-color)	-
--van-cell-background	var(--van-background-2)	-
--van-cell-border-color	var(--van-border-color)	-
--van-cell-active-color	var(--van-active-color)	-
--van-cell-required-color	var(--van-danger-color)	-
--van-cell-label-color	var(--van-text-color-2)	-
--van-cell-label-font-size	var(--van-font-size-sm)	-
--van-cell-label-line-height	var(--van-line-height-sm)	-
--van-cell-label-margin-top	var(--van-padding-base)	-
--van-cell-value-color	var(--van-text-color-2)	-
--van-cell-value-font-size	inherit	-
--van-cell-icon-size	16px	-
--van-cell-right-icon-color	var(--van-gray-6)	-
--van-cell-large-vertical-padding	var(--van-padding-sm)	-
--van-cell-large-title-font-size	var(--van-font-size-lg)	-
--van-cell-large-label-font-size	var(--van-font-size-md)	-
--van-cell-large-value-font-size	inherit	-
--van-cell-group-background	var(--van-background-2)	-
--van-cell-group-title-color	var(--van-text-color-2)	-
--van-cell-group-title-padding	var(--van-padding-md) var(--van-padding-md) var(--van-padding-xs)	-
--van-cell-group-title-font-size	var(--van-font-size-md)	-
--van-cell-group-title-line-height	16px	-
--van-cell-group-inset-padding	0 var(--van-padding-md)	-
--van-cell-group-inset-radius	var(--van-radius-lg)	-
--van-cell-group-inset-title-padding	var(--van-padding-md) var(--van-padding-md) var(--van-padding-xs) var(--van-padding-xl)	-

最佳实践

信息层级设计

合理的信息层级能让用户快速获取关键信息 📋。建议遵循以下原则：

<!-- ✅ 推荐：清晰的信息层级 -->
<van-cell-group title="个人信息">
  <van-cell title="姓名" value="张三" />
  <van-cell title="手机号" value="138****8888" label="已验证" />
  <van-cell title="邮箱" value="zhangsan@example.com" label="未验证" />
</van-cell-group>

<!-- ❌ 避免：信息过于冗长 -->
<van-cell title="这是一个非常非常长的标题，可能会影响用户体验和界面美观度" />

交互状态设计

明确的交互提示能提升用户体验 ✨：

<!-- ✅ 推荐：明确的交互提示 -->
<van-cell title="设置" is-link />
<van-cell title="帮助中心" is-link url="/help" />
<van-cell title="退出登录" @click="logout" />

<!-- ✅ 推荐：合理使用图标 -->
<van-cell title="消息通知" icon="bell-o" is-link />
<van-cell title="隐私设置" icon="shield-o" is-link />

性能优化小贴士

长列表优化

对于包含大量 Cell 的长列表，建议配合虚拟滚动技术：

<!-- 对于超长列表，建议配合 List 组件使用 -->
<van-list v-model:loading="loading" @load="onLoad">
  <van-cell-group v-for="group in dataList" :key="group.id">
    <van-cell 
      v-for="item in group.items" 
      :key="item.id"
      :title="item.title"
      :value="item.value"
    />
  </van-cell-group>
</van-list>

事件处理优化

使用事件委托减少内存占用：

// ✅ 推荐：使用事件委托
const handleCellClick = (item) => {
  // 统一处理点击事件
  router.push(`/detail/${item.id}`);
};

// ❌ 避免：为每个 Cell 绑定独立事件处理器

设计建议

视觉层次

• 标题：使用简洁明了的文字，避免过长 📝
• 描述：提供必要的补充信息，使用较小字号 📄
• 图标：选择语义明确的图标，保持风格统一 🎨
• 间距：合理使用 size 属性控制信息密度 📏

交互反馈

• 可点击的 Cell 应该设置 is-link 属性 👆
• 重要操作可以使用不同的箭头方向提示 ➡️
• 适当使用 center 属性保持视觉平衡 ⚖️

常见问题解决

Q: 如何实现 Cell 的条件渲染？

<van-cell-group>
  <van-cell 
    v-if="user.isVip" 
    title="VIP特权" 
    icon="diamond-o" 
    is-link 
  />
  <van-cell title="普通功能" is-link />
</van-cell-group>

Q: 如何自定义 Cell 的右侧内容？

<van-cell title="自定义右侧">
  <template #right-icon>
    <van-switch v-model="checked" />
  </template>
</van-cell>

Q: 如何实现 Cell 的动态样式？

<van-cell 
  :title="item.title"
  :class="{ 'highlight': item.isImportant }"
/>

<style>
.highlight {
  background-color: #fff7e6;
  border-left: 3px solid #ff9500;
}
</style>

Q: 如何处理长文本内容？

<!-- 使用 label 显示详细信息 -->
<van-cell 
  title="商品名称"
  value="iPhone 14 Pro Max"
  label="深空黑色 256GB 支持5G网络"
/>

<!-- 或使用插槽自定义布局 -->
<van-cell title="描述">
  <template #value>
    <div class="multi-line-text">
      这是一段很长的描述文字...
    </div>
  </template>
</van-cell>

相关组件

• List 列表 - 长列表展示和虚拟滚动
• SwipeCell 滑动单元格 - 支持滑动操作的单元格
• Field 输入框 - 表单输入场景
• NavBar 导航栏 - 页面导航
• IndexBar 索引栏 - 快速定位

延伸阅读

• 移动端列表设计规范
• iOS 人机界面指南 - 列表
• Material Design - Lists
• 无障碍设计指南