Vant

繁體中文

简体中文
English

繁體中文

简体中文
English

Appearance

Cell 單元格 - Vant 4

Cell 單元格 ​

🎯 介紹 ​

Cell 單元格就像是行動應用介面中的「萬能積木」 🧱！它是構建清單頁面的基礎元素，就像樂高積木一樣，可以自由組合搭建出各種精美的介面。

無論是設定頁面的選項清單、聯絡人資訊展示，還是商品詳情的屬性說明，Cell 都能以簡潔優雅的方式呈現資訊，讓複雜的資料變得井井有條 ✨。它就像一個貼心的「資訊管家」，幫你把內容整理得清晰明瞭！

📦 引入 ​

透過以下方式來全域註冊元件，更多註冊方式請參考元件註冊。

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

🚀 程式碼演示 ​

基礎用法 ​

Cell 就像一個獨立的「小房間」 🏠，可以單獨存在，也可以和兄弟姐妹們住在 CellGroup 這個「大家庭」裡。

當 Cell 們聚在一起時，CellGroup 就像一個貼心的「管家」，為它們提供統一的邊框裝飾，讓整個清單看起來更加整齊美觀 ✨。

html

卡片風格 ​

想要讓你的清單更有現代感？🎨 透過 CellGroup 的 inset 屬性，就能瞬間把普通的清單變成時尚的圓角卡片！

這種卡片風格就像給內容穿上了一件優雅的「外套」，讓資訊展示更加精緻，特別適合現代化的應用設計 💫。

html

單元格大小 ​

想要調整 Cell 的「身材」？💪 透過 size 屬性就能輕鬆控制！

就像給衣服選擇尺碼一樣，你可以讓 Cell 變得更緊湊或更寬鬆，完美適配不同的設計需求 👔。

html

展示圖示 ​

為你的 Cell 添加一個醒目的「小徽章」！🎖️ 透過 icon 屬性，可以在標題左側放置各種精美的圖示。

這些小圖示就像是內容的「身分證」，讓使用者一眼就能識別不同類型的資訊，提升介面的可讀性和美觀度 ✨。

html

展示箭頭 ​

想要暗示使用者「這裡可以點擊」？👆 設定 is-link 屬性後，Cell 右側就會出現一個優雅的小箭頭！

而且這個箭頭還很「聽話」，透過 arrow-direction 屬性可以讓它指向上下左右任意方向，就像一個貼心的「導航員」 🧭。

html

頁面導航 ​

讓你的 Cell 變身「傳送門」！🚪 透過 url 屬性可以實現網頁跳轉，或者用 to 屬性進行路由導航。

就像給每個 Cell 都裝上了「小火箭」，使用者輕輕一點就能飛到目標頁面，體驗絲滑的頁面切換 🚀。

html

分組標題 ​

想要給你的清單加個「小標籤」？🏷️ 透過 CellGroup 的 title 屬性就能為一組 Cell 添加醒目的標題。

這個標題就像是「章節名」，幫助使用者快速理解下面內容的分類，讓資訊結構更加清晰明瞭 📚。

html

使用插槽 ​

當標準配置無法滿足你的創意時，插槽就是你的「魔法工具箱」！🎩✨

透過插槽可以自由定製 Cell 的任何部分，讓你的想像力盡情發揮，打造獨一無二的介面效果 🎨。

html

垂直居中 ​

追求完美對齊？透過 center 屬性可以讓 Cell 的左側圖示與右側內容都完美垂直居中！

就像給內容們排了一個整齊的「隊列」，無論高矮胖瘦都能站在同一條水平線上，看起來特別舒服 😌。

html

API ​

CellGroup Props ​

參數說明類型預設值
title分組標題string-
inset是否展示為圓角卡片風格booleanfalse
border是否顯示外邊框booleantrue

Cell Props ​

參數說明類型預設值
title左側標題*numberstring*
value右側內容*numberstring*
label標題下方的描述資訊*numberstring*
size單元格大小，可選值為 large``normalstring-
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自訂單元格最右側的額外內容

類型定義 ​

元件匯出以下類型定義：

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

主題定製 ​

樣式變數 ​

元件提供了下列 CSS 變數，可用於自訂樣式，使用方法請參考 ConfigProvider 元件。

名稱預設值描述
--van-cell-font-sizevar(--van-font-size-md)-
--van-cell-line-height24px-
--van-cell-vertical-padding10px-
--van-cell-horizontal-paddingvar(--van-padding-md)-
--van-cell-text-colorvar(--van-text-color)-
--van-cell-backgroundvar(--van-background-2)-
--van-cell-border-colorvar(--van-border-color)-
--van-cell-active-colorvar(--van-active-color)-
--van-cell-required-colorvar(--van-danger-color)-
--van-cell-label-colorvar(--van-text-color-2)-
--van-cell-label-font-sizevar(--van-font-size-sm)-
--van-cell-label-line-heightvar(--van-line-height-sm)-
--van-cell-label-margin-topvar(--van-padding-base)-
--van-cell-value-colorvar(--van-text-color-2)-
--van-cell-value-font-sizeinherit-
--van-cell-icon-size16px-
--van-cell-right-icon-colorvar(--van-gray-6)-
--van-cell-large-vertical-paddingvar(--van-padding-sm)-
--van-cell-large-title-font-sizevar(--van-font-size-lg)-
--van-cell-large-label-font-sizevar(--van-font-size-md)-
--van-cell-large-value-font-sizeinherit-
--van-cell-group-backgroundvar(--van-background-2)-
--van-cell-group-title-colorvar(--van-text-color-2)-
--van-cell-group-title-paddingvar(--van-padding-md) var(--van-padding-md) var(--van-padding-xs)-
--van-cell-group-title-font-sizevar(--van-font-size-md)-
--van-cell-group-title-line-height16px-
--van-cell-group-inset-padding0 var(--van-padding-md)-
--van-cell-group-inset-radiusvar(--van-radius-lg)-
--van-cell-group-inset-title-paddingvar(--van-padding-md) var(--van-padding-md) var(--van-padding-xs) var(--van-padding-xl)-

最佳實踐 ​

資訊層級設計 ​

合理的資訊層級能讓使用者快速獲取關鍵資訊 📋。建議遵循以下原則：

html
<!-- ✅ 推薦：清晰的資訊層級 -->
<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="這是一個非常非常長的標題，可能會影響使用者體驗和介面美觀度" />

互動狀態設計 ​

明確的互動提示能提升使用者體驗 ✨：

html
<!-- ✅ 推薦：明確的互動提示 -->
<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 的長清單，建議配合虛擬捲動技術：

html
<!-- 對於超長清單，建議配合 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>

事件處理最佳化 ​

使用事件委託減少記憶體佔用：

javascript
// ✅ 推薦：使用事件委託
const handleCellClick = (item) => {
  // 統一處理點擊事件
  router.push(`/detail/${item.id}`);
};

// ❌ 避免：為每個 Cell 綁定獨立事件處理器

設計建議 ​

視覺層次 ​

  • 標題：使用簡潔明瞭的文字，避免過長 📝
  • 描述：提供必要的補充資訊，使用較小字號 📄
  • 圖示：選擇語義明確的圖示，保持風格統一 🎨
  • 間距：合理使用 size 屬性控制資訊密度 📏

互動回饋 ​

  • 可點擊的 Cell 應該設定 is-link 屬性 👆
  • 重要操作可以使用不同的箭頭方向提示 ➡️
  • 適當使用 center 屬性保持視覺平衡 ⚖️

常見問題解決 ​

Q: 如何實現 Cell 的條件渲染？ ​

html
<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 的右側內容？ ​

html
<van-cell title="自訂右側">
  <template #right-icon>
    <van-switch v-model="checked" />
  </template>
</van-cell>

Q: 如何實現 Cell 的動態樣式？ ​

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

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

Q: 如何處理長文字內容？ ​

html
<!-- 使用 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>

相關元件 ​

延伸閱讀 ​

💡 小提示：Cell 元件是建構行動端介面的基礎元件，合理使用可以讓你的應用介面更加規範和易用！

基於Vant構建的企業級移動端解決方案

Copyright © 2025 siex.cn ｜ sitemap