---

📚 引言

在現代 Web 開發中，創建既美觀又功能強大的用戶界面是一項挑戰。Element Plus，作為 Vue 3 生態中的明星 UI 組件庫，以其豐富的組件、優秀的性能和易用性贏得了廣大開發者的青睞。

本文將全面覆蓋 Element Plus 的 常用核心組件，通過 深度分析、最佳實踐案例 以及 詳細的代碼示例，幫助你掌握如何在實際項目中高效利用 Element Plus，構建現代化、響應式的企業級應用。

---

🛠? 核心組件詳解與應用（含完整參數說明）

1. 🎯 el-button 按鈕組件

按鈕是用戶界面中最基本的交互元素之一。Element Plus 的 el-button 提供了多種類型、尺寸和狀態，滿足各種場景需求。

? 參數說明（Props）

參數	類型	可選值	默認值	說明
size	string	large / default / small	default	按鈕尺寸
type	string	primary/ success / warning / danger / info / text	—	按鈕類型
plain	boolean	—	false	是否為樸素按鈕（背景透明，僅邊框和文字）
round	boolean	—	false	是否為圓角按鈕
circle	boolean	—	false	是否為圓形圖標按鈕
loading	boolean	—	false	是否加載中狀態
disabled	boolean	—	false	是否禁用
icon	string / Component	—	—	圖標組件，可使用 @element-plus/icons-vue 中的圖標
autofocus	boolean	—	false	是否自動聚焦
native-type	string	button / submit / reset	button	原生 type 屬性

🧩 事件（Events）

事件名	說明	回調參數
click	點擊按鈕時觸發	—

💡 使用說明與示例

<template><div class="button-group"><!-- 基礎按鈕 --><el-button>默認按鈕</el-button><el-button type="primary">主要按鈕</el-button><el-button type="success">成功按鈕</el-button><el-button type="info">信息按鈕</el-button><el-button type="warning">警告按鈕</el-button><el-button type="danger">危險按鈕</el-button><!-- 樸素按鈕 --><el-button plain>樸素按鈕</el-button><el-button type="primary" plain>樸素主要按鈕</el-button><!-- 圓角按鈕 --><el-button round>圓角按鈕</el-button><el-button type="primary" round>圓角主要按鈕</el-button><!-- 圖標按鈕 --><el-button type="primary" icon="Edit" circle /><el-button type="success" icon="Check" circle /><el-button type="danger" icon="Delete" circle /><!-- 加載狀態 --><el-button type="primary" :loading="true">加載中</el-button><!-- 禁用狀態 --><el-button type="primary" disabled>禁用按鈕</el-button></div>
</template><script setup>
import { Edit, Check, Delete } from '@element-plus/icons-vue'
</script>

---

2. 🖼? el-icon 圖標組件

el-icon 是 Element Plus 的圖標容器，用于統一管理圖標樣式和行為。

? 參數說明（Props）

參數	類型	可選值	默認值	說明
size	string / number	—	—	圖標大小
color	string	—	—	圖標顏色
class	string	—	—	自定義類名

?? 注意：圖標本身通過默認插槽傳入，如 <el-icon><Edit /></el-icon>

💡 使用說明

<template><el-icon :size="20" color="#409eff"><Edit /></el-icon><el-icon class="custom-icon"><Setting /></el-icon>
</template><script setup>
import { Edit, Setting } from '@element-plus/icons-vue'
</script><style>
.custom-icon {color: #67c23a;font-size: 24px;
}
</style>

---

3. 💬 el-message 消息提示組件

用于輕量級的全局消息提示，不打斷用戶操作。

? 方法調用（非組件 Props）

import { ElMessage } from 'element-plus'// 基本用法
ElMessage('這是一條消息')// 指定類型
ElMessage.success('操作成功')
ElMessage.warning('警告內容')
ElMessage.error('錯誤信息')
ElMessage.info('提示信息')// 自定義配置
ElMessage({message: '自定義消息',type: 'success',duration: 3000, // 顯示時間，毫秒showClose: true, // 是否顯示關閉按鈕center: true, // 文字是否居中offset: 60, // 距離窗口頂部的偏移量onClose: () => console.log('消息關閉')
})

? 配置項說明

參數	類型	默認值	說明
message	string / VNode	—	消息文字
type	string	info	主題，可選 success / warning / error / info
icon	Component	—	自定義圖標組件
dangerouslyUseHTMLString	boolean	false	是否將 message 作為 HTML 片段處理
duration	number	3000	顯示時間，毫秒
showClose	boolean	false	是否顯示關閉按鈕
center	boolean	false	文字是否居中
offset	number	20	距離窗口頂部的偏移量
onClose	function	—	關閉時的回調函數

---

4. 🔘 el-radio 單選組件

用于在多個選項中選擇一個。

? el-radio Props

參數	類型	可選值	默認值	說明
model-value / v-model	string / number / boolean	—	—	綁定值
label	string / number / boolean	—	—	Radio 的 value
disabled	boolean	—	false	是否禁用
border	boolean	—	false	是否顯示邊框
size	string	large / default / small	—	尺寸
name	string	—	—	原生 name 屬性

? el-radio-group Props（用于包裹多個 radio）

參數	類型	可選值	默認值	說明
model-value / v-model	string / number / boolean	—	—	綁定值
size	string	large / default / small	—	尺寸
disabled	boolean	—	false	是否禁用
text-color	string	—	#ffffff	按鈕形式的 Radio 激活時的文本顏色
fill	string	—	#409eff	按鈕形式的 Radio 激活時的填充色和邊框色

💡 使用說明

<template><!-- 基礎單選 --><el-radio v-model="radio" label="1">選項A</el-radio><el-radio v-model="radio" label="2">選項B</el-radio><!-- 帶邊框 --><el-radio-group v-model="radio2"><el-radio label="1" border>選項A</el-radio><el-radio label="2" border disabled>選項B</el-radio></el-radio-group><!-- 按鈕樣式 --><el-radio-group v-model="radio3" size="large"><el-radio-button label="上海">上海</el-radio-button><el-radio-button label="北京">北京</el-radio-button><el-radio-button label="廣州">廣州</el-radio-button></el-radio-group>
</template><script setup>
import { ref } from 'vue'
const radio = ref('1')
const radio2 = ref('1')
const radio3 = ref('上海')
</script>

---

5. 🔽 el-select 選擇器組件

下拉選擇器，支持單選、多選、搜索、遠程加載等。

? el-select Props

參數	類型	可選值	默認值	說明
model-value / v-model	string / number / array	—	—	綁定值
multiple	boolean	—	false	是否多選
disabled	boolean	—	false	是否禁用
clearable	boolean	—	false	是否可以清空選項
filterable	boolean	—	false	是否可搜索
allow-create	boolean	—	false	是否允許用戶創建新條目
loading	boolean	—	false	是否正在從遠程獲取數據
remote	boolean	—	false	是否為遠程搜索
remote-method	function	—	—	遠程搜索方法
placeholder	string	—	請選擇	占位符
size	string	large / default / small	—	尺寸
collapse-tags	boolean	—	false	多選時是否將選中值按文字的形式展示
collapse-tags-tooltip	boolean	—	false	多選時折疊的標簽是否顯示 tooltip

? el-option Props

參數	類型	可選值	默認值	說明
value	string / number / boolean	—	—	選項的值
label	string	—	—	選項的標簽，若不設置則默認與 value 相同
disabled	boolean	—	false	是否禁用該選項

💡 使用說明

<template><!-- 基礎選擇 --><el-select v-model="value" placeholder="請選擇"><el-optionv-for="item in options":key="item.value":label="item.label":value="item.value"/></el-select><!-- 多選 --><el-select v-model="multipleValue" multiple placeholder="請選擇"><el-optionv-for="item in options":key="item.value":label="item.label":value="item.value"/></el-select><!-- 遠程搜索 --><el-selectv-model="remoteValue"multiplefilterableremotereserve-keywordplaceholder="請輸入關鍵詞":remote-method="remoteMethod":loading="loading"><el-optionv-for="item in remoteOptions":key="item.value":label="item.label":value="item.value"/></el-select>
</template><script setup>
import { ref } from 'vue'const value = ref('')
const multipleValue = ref([])
const remoteValue = ref([])
const loading = ref(false)
const remoteOptions = ref([])const options = [{ value: 'option1', label: '黃金糕' },{ value: 'option2', label: '雙皮奶' },{ value: 'option3', label: '蚵仔煎' },
]const remoteMethod = (query) => {if (query !== '') {loading.value = truesetTimeout(() => {loading.value = falseremoteOptions.value = options.filter(item => item.label.toLowerCase().includes(query.toLowerCase()))}, 200)} else {remoteOptions.value = []}
}
</script>

---

6. 🔀 el-switch 開關組件

用于兩種狀態間的切換，如開啟/關閉。

? Props

參數	類型	可選值	默認值	說明
model-value / v-model	boolean / string / number	—	false	綁定值
disabled	boolean	—	false	是否禁用
width	string / number	—	40	寬度
inline-prompt	boolean	—	false	是否在開關內顯示文字
active-icon	Component	—	—	自定義激活時的圖標組件
inactive-icon	Component	—	—	自定義未激活時的圖標組件
active-text	string	—	—	激活時的文字
inactive-text	string	—	—	未激活時的文字
active-value	string / number / boolean	—	true	激活時的值
inactive-value	string / number / boolean	—	false	未激活時的值
active-color	string	—	#409eff	激活時的背景色
inactive-color	string	—	#c0ccda	未激活時的背景色
name	string	—	—	原生 name 屬性

💡 使用說明

<template><el-switchv-model="value1"active-text="開"inactive-text="關"/><el-switchv-model="value2"class="ml-2"inline-promptactive-icon="Check"inactive-icon="Close"/><el-switchv-model="value3"class="ml-2"style="--el-switch-on-color: #13ce66; --el-switch-off-color: #ff4949"/>
</template><script setup>
import { ref } from 'vue'
import { Check, Close } from '@element-plus/icons-vue'const value1 = ref(true)
const value2 = ref(false)
const value3 = ref(true)
</script>

---

7. 📝 el-form 表單組件

表單容器，用于管理表單項的布局、校驗和提交。

? el-form Props

參數	類型	可選值	默認值	說明
model	object	—	—	表單數據對象
rules	object	—	—	表單驗證規則
inline	boolean	—	false	行內表單模式
label-position	string	top / left / right	right	標簽的位置
label-width	string / number	—	—	標簽的寬度
label-suffix	string	—	—	表單域標簽的后綴
hide-required-asterisk	boolean	—	false	是否隱藏必填字段的標簽旁邊的紅色星號
require-asterisk-position	string	left / right	left	必填字段的星號位置
show-message	boolean	—	true	是否顯示校驗錯誤信息
inline-message	boolean	—	false	是否以行內形式展示校驗信息
status-icon	boolean	—	false	是否在輸入框中顯示校驗結果圖標
disabled	boolean	—	false	是否禁用該表單內的所有組件
scroll-to-error	boolean	—	false	提交表單時，如果校驗失敗，是否自動滾動到第一個錯誤表單項

? el-form-item Props

參數	類型	可選值	默認值	說明
label	string	—	—	標簽文本
label-width	string / number	—	—	標簽的寬度
prop	string	—	—	對應的 model 字段名，用于校驗
required	boolean	—	false	是否必填
rules	object / array	—	—	表單驗證規則
error	string	—	—	表單域的錯誤信息，設置后會覆蓋校驗規則的錯誤信息
show-message	boolean	—	true	是否顯示校驗錯誤信息
inline-message	boolean	—	false	是否以行內形式展示校驗信息
size	string	large / default / small	—	尺寸

?? 注意：el-form-item 必須設置 prop 屬性才能進行校驗。

💡 使用說明

<template><el-formref="ruleFormRef":model="form":rules="rules"label-width="120px"><el-form-item label="用戶名" prop="username"><el-input v-model="form.username" /></el-form-item><el-form-item label="郵箱" prop="email"><el-input v-model="form.email" /></el-form-item><el-form-item label="年齡" prop="age"><el-input-number v-model="form.age" :min="1" :max="150" /></el-form-item><el-form-item><el-button type="primary" @click="submitForm(ruleFormRef)">提交</el-button><el-button @click="resetForm(ruleFormRef)">重置</el-button></el-form-item></el-form>
</template><script setup>
import { ref } from 'vue'
import { ElMessage } from 'element-plus'const ruleFormRef = ref()
const form = ref({username: '',email: '',age: 18,
})const rules = ref({username: [{ required: true, message: '請輸入用戶名', trigger: 'blur' },{ min: 3, max: 15, message: '長度在 3 到 15 個字符', trigger: 'blur' }],email: [{ required: true, message: '請輸入郵箱地址', trigger: 'blur' },{ type: 'email', message: '請輸入正確的郵箱地址', trigger: ['blur', 'change'] }],age: [{ required: true, message: '請輸入年齡', trigger: 'blur' },{ type: 'number', message: '年齡必須為數字值', trigger: 'blur' }]
})const submitForm = async (formEl) => {if (!formEl) returntry {await formEl.validate()ElMessage.success('提交成功！')} catch (error) {console.log('校驗失敗', error)}
}const resetForm = (formEl) => {if (!formEl) returnformEl.resetFields()
}
</script>

---

8. 📊 el-table 表格組件

用于展示大量結構化數據。

? el-table Props

參數	類型	可選值	默認值	說明
data	array	—	—	顯示的數據
height	string / number	—	—	表格高度
max-height	string / number	—	—	表格最大高度
stripe	boolean	—	false	是否為斑馬紋 table
border	boolean	—	false	是否帶有縱向邊框
fit	boolean	—	true	列的寬度是否自撐開
show-header	boolean	—	true	是否顯示表頭
highlight-current-row	boolean	—	false	是否要高亮當前行
current-row-key	string / number	—	—	當前行的 key，只寫屬性
row-class-name	string / function	—	—	行的 className 的回調方法
row-style	object / function	—	—	行的 style 的回調方法
cell-class-name	string / function	—	—	單元格的 className 的回調方法
cell-style	object / function	—	—	單元格的 style 的回調方法
header-row-class-name	string / function	—	—	表頭行的 className 的回調方法
header-row-style	object / function	—	—	表頭行的 style 的回調方法
header-cell-class-name	string / function	—	—	表頭單元格的 className 的回調方法
header-cell-style	object / function	—	—	表頭單元格的 style 的回調方法
row-key	string / function	—	—	行數據的 Key，用來優化渲染
empty-text	string	—	暫無數據	空數據時顯示的文本內容
default-expand-all	boolean	—	false	是否默認展開所有行
expand-row-keys	array	—	—	可以通過該屬性設置展開的行，需要設置 row-key
default-sort	object	—	—	默認的排序列的 prop 和順序
tooltip-effect	string	dark / light	dark	tooltip 的 effect 屬性
show-summary	boolean	—	false	是否在表尾顯示合計行
sum-text	string	—	合計	合計行第一列的文本
summary-method	function	—	—	自定義的合計計算方法
span-method	function	—	—	合并行或列的計算方法
select-on-indeterminate	boolean	—	true	在多選表格中，當僅有部分行被選中時，點擊表頭的多選框是否選擇所有項
indent	number	—	16	展示樹形數據時，樹節點的縮進
lazy	boolean	—	false	是否懶加載子節點數據
load	function	—	—	加載子節點數據的函數
tree-props	object	—	{ hasChildren: 'hasChildren', children: 'children' }	渲染嵌套數據的配置選項

? el-table-column Props

參數	類型	可選值	默認值	說明
type	string	selection / index / expand	—	列類型
index	number / function	—	—	如果 type 為 index ，可以通過 index 屬性設置行索引
column-key	string	—	—	column 的 key，如果需要使用 filter-change 事件，則需此屬性
label	string	—	—	顯示的標題
prop	string	—	—	對應列內容的字段名
width	string / number	—	—	對應列的寬度
min-width	string / number	—	—	對應列的最小寬度
fixed	string / boolean	true / left / right	—	列是否固定
render-header	function	—	—	列標題 Label 區域渲染使用的 Function
sortable	boolean / string	true / false / custom	false	對應列是否可以排序
sort-method	function	—	—	對數據進行排序的時候使用的方法
resizable	boolean	—	true	對應列是否可以通過拖動改變寬度
formatter	function	—	—	用來格式化內容
show-overflow-tooltip	boolean	—	false	當內容過長被隱藏時是否顯示 tooltip
align	string	left / center / right	left	對齊方式
header-align	string	left / center / right	—	表頭對齊方式，若不設置，則繼承 align 的值
class-name	string	—	—	列的 className
label-class-name	string	—	—	當前列標題的自定義類名
selectable	function	—	—	僅對 type="selection" 的列有效，類型為 Function，Function 的返回值用來決定這一行的 checkbox 是否可以勾選
reserve-selection	boolean	—	false	僅對 type="selection" 的列有效，類型為 Boolean，為 true 則會在數據更新之后保留之前選中的選項
filters	array	—	—	數據篩選的選項，數組格式，數組中的元素需要有 text 和 value 屬性
filter-placement	string	top / top-start / top-end / bottom / bottom-start / bottom-end / left / left-start / left-end / right / right-start / right-end	—	過濾彈出框的定位
filter-multiple	boolean	—	true	數據篩選的選項是否多選
filter-method	function	—	—	數據篩選使用的方法，如果是多選的篩選項，對每一條數據會執行多次，任意一次返回 true 就會顯示
filtered-value	array	—	—	選中的數據篩選項，如果設置了這個值，列的篩選狀態會受控于外部

?? 注意：由于篇幅限制，el-table 的事件、方法和插槽未在此詳述，但它們同樣重要，如 @selection-change、@sort-change、@filter-change 等。

💡 使用說明

<template><el-table:data="tableData"style="width: 100%"height="400"borderstripe@selection-change="handleSelectionChange"><el-table-column type="selection" width="55" /><el-table-column type="index" width="60" /><el-table-column prop="name" label="姓名" width="120" /><el-table-column prop="age" label="年齡" width="100" sortable /><el-table-column prop="address" label="地址" show-overflow-tooltip /><el-table-column label="操作" width="180"><template #default="{ row }"><el-button size="small" @click="handleEdit(row)">編輯</el-button><el-button size="small" type="danger" @click="handleDelete(row)">刪除</el-button></template></el-table-column></el-table>
</template><script setup>
import { ref } from 'vue'const tableData = ref([{ name: '張三', age: 25, address: '上海市普陀區金沙江路 1518 弄' },{ name: '李四', age: 30, address: '上海市普陀區金沙江路 1517 弄' },{ name: '王五', age: 28, address: '上海市普陀區金沙江路 1519 弄' }
])const multipleSelection = ref([])const handleSelectionChange = (val) => {multipleSelection.value = val
}const handleEdit = (row) => {console.log('編輯', row)
}const handleDelete = (row) => {console.log('刪除', row)
}
</script>

---

9. 🍽? el-menu 菜單組件

用于構建導航菜單。

? el-menu Props

參數	類型	可選值	默認值	說明
mode	string	horizontal / vertical	vertical	菜單模式
collapse	boolean	—	false	是否水平折疊收起菜單
background-color	string	—	#ffffff	菜單的背景色
text-color	string	—	#303133	菜單的文字顏色
active-text-color	string	—	#409eff	菜單激活時的文字顏色
default-active	string	—	—	當前激活菜單的 index
default-openeds	array	—	—	當前打開的 sub-menu 的 index 的數組
unique-opened	boolean	—	false	是否只保持一個子菜單的展開
menu-trigger	string	hover / click	hover	子菜單打開的觸發方式
router	boolean	—	false	是否使用 vue-router 的模式，啟用該模式會在激活導航時以 index 作為 path 進行路由跳轉
collapse-transition	boolean	—	true	是否開啟折疊動畫

? el-menu-item Props

參數	類型	可選值	默認值	說明
index	string	—	—	唯一標志
route	object / string	—	—	Vue Router 路徑對象或字符串
disabled	boolean	—	false	是否禁用

? el-sub-menu Props

參數	類型	可選值	默認值	說明
index	string	—	—	唯一標志
popper-class	string	—	—	彈出菜單的自定義類名
popper-offset	number	—	6	彈出菜單和父菜單的距離
teleported	boolean	—	true	是否將彈出菜單放置于 body 內

💡 使用說明

<template><el-menu:default-active="activeIndex"class="el-menu-demo"mode="horizontal"@select="handleSelect"><el-menu-item index="1">處理中心</el-menu-item><el-sub-menu index="2"><template #title>我的工作臺</template><el-menu-item index="2-1">選項1</el-menu-item><el-menu-item index="2-2">選項2</el-menu-item><el-menu-item index="2-3">選項3</el-menu-item></el-sub-menu><el-menu-item index="3" disabled>消息中心</el-menu-item><el-menu-item index="4">訂單管理</el-menu-item></el-menu>
</template><script setup>
import { ref } from 'vue'const activeIndex = ref('1')const handleSelect = (key, keyPath) => {console.log(key, keyPath)
}
</script>

---

10. 🧱 el-layout 布局組件

用于構建頁面整體布局。

? el-container Props

參數	類型	可選值	默認值	說明
direction	string	horizontal / vertical	—	子元素的排列方向

? el-header Props

參數	類型	可選值	默認值	說明
height	string	—	60px	頂欄高度

? el-aside Props

參數	類型	可選值	默認值	說明
width	string	—	300px	側邊欄寬度

? el-main Props

參數	類型	可選值	默認值	說明
—	—	—	—	無特殊參數

? el-footer Props

參數	類型	可選值	默認值	說明
height	string	—	60px	底欄高度

💡 使用說明

<template><el-container style="height: 100vh;"><el-aside width="200px"><el-menudefault-active="1"class="el-menu-vertical-demo"@open="handleOpen"@close="handleClose"><el-menu-item index="1"><el-icon><Location /></el-icon><span>導航一</span></el-menu-item><el-menu-item index="2"><el-icon><Menu /></el-icon><span>導航二</span></el-menu-item></el-menu></el-aside><el-container><el-header>Header</el-header><el-main>Main Content</el-main><el-footer>Footer</el-footer></el-container></el-container>
</template><script setup>
import { Location, Menu } from '@element-plus/icons-vue'
const handleOpen = (key, keyPath) => {console.log(key, keyPath)
}
const handleClose = (key, keyPath) => {console.log(key, keyPath)
}
</script>

---

11. 📦 el-container 組件

已在 el-layout 部分介紹。

---

12. 🎠 el-carousel 輪播圖組件

用于實現圖片或內容的輪播展示。

? el-carousel Props

參數	類型	可選值	默認值	說明
height	string	—	—	輪播圖的高度
initial-index	number	—	0	初始顯示的索引
trigger	string	hover / click	hover	指示器的觸發方式
autoplay	boolean	—	true	是否自動切換
interval	number	—	3000	自動切換的時間間隔，單位為毫秒
indicator-position	string	none / outside / inside	—	指示器的位置
arrow	string	always / hover / never	hover	切換箭頭的顯示時機
type	string	card / —	—	走馬燈的類型
loop	boolean	—	true	是否循環顯示
direction	string	horizontal / vertical	horizontal	滾動方向

? el-carousel-item Props

參數	類型	可選值	默認值	說明
—	—	—	—	無特殊參數

💡 使用說明

<template><el-carousel height="200px"><el-carousel-item v-for="item in 4" :key="item"><h3 class="small justify-center">{{ item }}</h3></el-carousel-item></el-carousel>
</template><style>
.el-carousel__item h3 {color: #475669;opacity: 0.75;line-height: 200px;margin: 0;text-align: center;
}.el-carousel__item:nth-child(2n) {background-color: #99a9bf;
}.el-carousel__item:nth-child(2n + 1) {background-color: #d3dce6;
}
</style>

---

13. 📜 el-scrollbar 滾動條組件

el-scrollbar 是一個自定義滾動條組件，用于替代瀏覽器原生的滾動條，提供更美觀、更可控的滾動體驗。它特別適用于需要在固定高度或寬度的容器內展示大量內容的場景。

? Props

參數	類型	可選值	默認值	說明
height	string / number	—	—	設置滾動條容器的高度
max-height	string / number	—	—	設置滾動條容器的最大高度
native	boolean	—	false	是否使用原生滾動條，如果為 true，則不會自定義滾動條樣式，而是使用瀏覽器原生滾動條
wrap-style	object / string	—	—	外層容器 wrap的自定義樣式
wrap-class	string / object / array	—	—	外層容器 wrap的自定義類名
view-class	string / object / array	—	—	內容視圖 view的自定義類名
view-style	object / string	—	—	內容視圖 view的自定義樣式
noresize	boolean	—	false	防止 resize事件觸發重新計算
tag	string	—	div	視圖的元素標簽名
always	boolean	—	false	是否總是顯示滾動條

? 事件 (Events)

事件名	說明	回調參數
scroll	滾動時觸發	scroll: { scrollLeft, scrollTop }

? 方法 (Methods)

方法名	說明	參數
handleScroll	手動觸發滾動事件	—
scrollTo	將內容滾動到指定的位置	options: 可以是數字（表示 scrollTop）或包含 top 和 left 的對象
getScrollTop	獲取當前滾動的垂直位置	—
setScrollTop	設置垂直滾動位置	scrollTop: 滾動位置
getScrollLeft	獲取當前滾動的水平位置	—
setScrollLeft	設置水平滾動位置	scrollLeft: 滾動位置

💡 使用說明與示例

el-scrollbar 組件非常適合用于創建自定義的滾動區域，比如側邊欄菜單、對話框內容區、代碼預覽窗格等。

<template><div class="scrollbar-container"><!-- 基礎垂直滾動條 --><el-scrollbar height="200px"><p v-for="item in 20" :key="item" class="scrollbar-demo-item">{{ item }}</p></el-scrollbar><!-- 帶有自定義樣式的滾動條 --><el-scrollbar height="200px" :wrap-style="{ 'background': 'rgb(235, 235, 235)' }":always="true"><p v-for="item in 20" :key="item" class="scrollbar-demo-item">{{ item }}</p></el-scrollbar><!-- 水平和垂直滾動條 --><el-scrollbar height="200px" style="width: 300px;"><div style="width: 800px; white-space: nowrap;"><span v-for="item in 50" :key="item" class="scrollbar-demo-item" style="display: inline-block;">{{ item }}</span></div></el-scrollbar><!-- 監聽滾動事件 --><el-scrollbar height="200px" @scroll="onScroll"><p v-for="item in 30" :key="item" class="scrollbar-demo-item">監聽滾動 - {{ item }}</p></el-scrollbar><p>滾動位置: {{ scrollPosition }}</p><!-- 使用方法控制滾動 --><el-scrollbar ref="scrollbarRef" height="200px"><p v-for="item in 50" :key="item" class="scrollbar-demo-item">可編程控制 - {{ item }}</p></el-scrollbar><div class="control-buttons"><el-button @click="scrollToTop">滾動到頂部</el-button><el-button @click="scrollToBottom">滾動到底部</el-button><el-button @click="scrollToPosition">滾動到位置 1000</el-button></div></div>
</template><script setup>
import { ref } from 'vue'
import { ElScrollbar, ElButton } from 'element-plus'const scrollPosition = ref({ scrollLeft: 0, scrollTop: 0 })
const scrollbarRef = ref()const onScroll = (scroll) => {scrollPosition.value = scroll
}const scrollToTop = () => {scrollbarRef.value?.setScrollTop(0)
}const scrollToBottom = () => {// 獲取內容總高度并滾動到底部const wrapElement = scrollbarRef.value?.wrap$ if (wrapElement) {scrollbarRef.value?.setScrollTop(wrapElement.scrollHeight - wrapElement.clientHeight)}
}const scrollToPosition = () => {scrollbarRef.value?.setScrollTop(1000)
}
</script><style scoped>
.scrollbar-container {display: flex;flex-direction: column;gap: 20px;padding: 20px;
}.scrollbar-demo-item {display: flex;align-items: center;justify-content: center;height: 50px;margin: 10px;text-align: center;border-radius: 4px;background: var(--el-color-primary-light-9);color: var(--el-color-primary);
}.control-buttons {margin-top: 10px;display: flex;gap: 10px;
}
</style>

🎯 應用場景

1. 固定高度內容區域：當需要在一個固定大小的容器內展示可能超出其范圍的內容時，如側邊欄、彈窗內容、列表預覽等。
2. 美化滾動體驗：原生滾動條在不同操作系統上樣式不一，且可能占用過多空間。el-scrollbar 提供了更精致、更一致的視覺效果。
3. 精確控制滾動：通過其提供的方法，可以精確控制滾動位置，實現平滑滾動、錨點跳轉等高級功能。
4. 性能優化：在某些情況下，使用虛擬滾動結合 el-scrollbar 可以優化大量數據的渲染性能。

?? 注意事項

• 性能：雖然 el-scrollbar 提供了更好的視覺體驗，但它是一個 JavaScript 實現的組件，對于非常長的列表，可能會比原生滾動條消耗更多性能。在極端情況下，考慮使用 native="true" 或虛擬滾動技術。
• 觸摸設備：確保在移動設備上的觸摸滾動體驗是流暢的。
• 樣式覆蓋：可以通過 wrap-class、view-class 等屬性或深度選擇器來自定義滾動條的外觀。

14. 💬 el-tooltip 文字提示組件

el-tooltip 組件用于當目標元素的文本內容過長被省略時，鼠標懸停時顯示完整內容，或者用于對某個元素進行簡短說明。

? Props

參數	類型	可選值	默認值	說明
model-value / v-model	boolean	—	—	狀態是否可見
content	string	—	—	顯示的內容，也可以通過 slot#content 傳入 DOM
placement	string	top / top-start / top-end / bottom / bottom-start / bottom-end / left / left-start / left-end / right / right-start / right-end	bottom	出現位置
value-on-clear	boolean	—	—	清除時的值
disabled	boolean	—	false	是否禁用
offset	number	—	0	出現位置的偏移量
transition	string	—	el-fade-in-linear	定義漸變動畫
visible-arrow	boolean	—	true	是否顯示箭頭
popper-options	object	—	{ boundariesElement: 'body', gpuAcceleration: false }	popper.js 參數
open-delay	number	—	0	出現之前的延遲（毫秒），僅在 trigger 為 hover 時有效
close-delay	number	—	200	消失之前的延遲（毫秒），僅在 trigger 為 hover 時有效
tabindex	number / string	—	0	tooltip 的 tabindex
show-after	number	—	0	顯示延遲，單位毫秒
hide-after	number	—	0	關閉延遲，單位毫秒
auto-close	number	—	0	點擊后自動關閉延時，單位毫秒
manual	boolean	—	false	是否手動控制狀態，true 則不會自動顯示隱藏
effect	string	dark / light	dark	默認提供的主題
enterable	boolean	—	true	鼠標是否可以進入 tooltip
hide-on-click	boolean	—	false	是否在點擊后隱藏
popper-class	string	—	—	為 popper 添加類名，可用于自定義樣式
popper-style	object	—	—	為 popper 添加內聯樣式
trigger	string	hover / focus / click / manual	hover	觸發方式
virtual-ref	object	—	—	虛擬元素的 ref，用于與其引用的元素進行交互
virtual-triggering	boolean	—	true	是否觸發虛擬元素事件
teleported	boolean	—	true	tooltip 是否會被插入到 body 元素上
persistent	boolean	—	false	tooltip 是否會對 v-model 進行響應

? 事件 (Events)

事件名	說明	回調參數
show	tooltip 顯示時觸發	—
hide	tooltip 隱藏時觸發	—

? Slots

插槽名	說明
—	內容，也可以使用 content 屬性
content	內容，當需要傳入 DOM 時使用

💡 使用說明與示例

el-tooltip 是提升用戶體驗的重要組件，常用于按鈕、表格單元格、標簽等元素的說明。

<template><div class="tooltip-container"><!-- 基礎用法 --><el-tooltip content="這是一段提示文字" placement="top"><el-button>頂部顯示</el-button></el-tooltip><el-tooltip content="這是一段提示文字" placement="bottom"><el-button>底部顯示</el-button></el-tooltip><el-tooltip content="這是一段提示文字" placement="left"><el-button>左側顯示</el-button></el-tooltip><el-tooltip content="這是一段提示文字" placement="right"><el-button>右側顯示</el-button></el-tooltip><!-- 主題與效果 --><el-tooltip content="深色主題" effect="dark"><el-button>深色</el-button></el-tooltip><el-tooltip content="淺色主題" effect="light"><el-button>淺色</el-button></el-tooltip><!-- 延遲顯示與關閉 --><el-tooltip content="延遲顯示" :open-delay="500" :close-delay="300"><el-button>延遲顯示</el-button></el-tooltip><!-- 點擊觸發 --><el-tooltip content="點擊顯示提示" trigger="click"><el-button>點擊觸發</el-button></el-tooltip><!-- 手動控制 --><el-tooltip v-model="visible" content="手動控制的提示" :manual="true" placement="top"><template #content><span>這是 <b>加粗</b> 的提示內容</span></template><el-button @click="visible = !visible">手動控制</el-button></el-tooltip><!-- 復雜內容 --><el-tooltip placement="top"><template #content><div>多行內容</div><div><el-tag size="small">標簽</el-tag></div></template><el-button>復雜內容</el-button></el-tooltip><!-- 禁用狀態 --><el-tooltip content="禁用的提示" disabled><el-button disabled>禁用按鈕</el-button></el-tooltip></div>
</template><script setup>
import { ref } from 'vue'
import { ElTooltip, ElButton, ElTag } from 'element-plus'const visible = ref(false)
</script><style scoped>
.tooltip-container {display: flex;flex-wrap: wrap;gap: 10px;padding: 20px;
}
</style>

🎯 應用場景

1. 按鈕說明：為功能圖標或簡短按鈕文字提供詳細說明。
2. 表格內容溢出：當表格單元格內容過長被截斷時，鼠標懸停顯示完整內容。
3. 表單驗證提示：在輸入框旁邊提供格式或要求的提示。
4. 導航菜單：在側邊欄圖標菜單中，鼠標懸停顯示菜單名稱。
5. 狀態說明：對某些狀態標簽或徽章提供更詳細的解釋。

?? 注意事項

• 內容長度：避免在 tooltip 中放置過多內容，通常應保持簡短。
• 可訪問性：確保 tooltip 內容對屏幕閱讀器等輔助技術是可訪問的。
• 觸發方式：根據使用場景選擇合適的觸發方式（hover, click, focus）。
• 移動端：在觸摸設備上，hover 觸發可能不理想，考慮使用 click 觸發。

---

15. 🔽 el-collapse 折疊面板組件

el-collapse 組件用于實現內容的折疊與展開，可以有效節省頁面空間，讓用戶按需查看信息。

? Props

參數	類型	可選值	默認值	說明
model-value / v-model	array / string	—	—	當前激活的面板的 name，如果是手風琴模式，則為字符串
accordion	boolean	—	false	是否啟用手風琴模式，即每次只允許展開一個面板

? 事件 (Events)

事件名	說明	回調參數
update:model-value	激活面板時觸發	(activeNames: array / string)
change	激活面板時觸發（與 update:model-value 類似）	(activeNames: array / string)

? 插槽 (Slots)

插槽名	說明	子組件
—	默認插槽，用于放置 el-collapse-item 組件	el-collapse-item

? el-collapse-item Props

參數	類型	可選值	默認值	說明
name	string / number	—	—	唯一標志符，v-model 的值
title	string	—	—	面板標題
disabled	boolean	—	false	是否禁用

💡 使用說明與示例

el-collapse 是組織分組信息的理想選擇，常用于 FAQ、配置面板、詳情頁等。

<template><div class="collapse-container"><!-- 基礎折疊面板 --><el-collapse v-model="activeNames" @change="handleChange"><el-collapse-item name="1"><template #title>一致性 Consistency<i class="header-icon el-icon-info"></i></template><div>與現實生活一致：與現實生活的流程、邏輯保持一致，遵循用戶習慣的語言和概念；</div><div>在界面中一致：所有的元素和結構需保持一致，比如：設計樣式、圖標和文本、元素的位置等。</div></el-collapse-item><el-collapse-item name="2"><template #title>反饋 Feedback</template><div>控制反饋：通過界面樣式和交互動效讓用戶可以清晰的感知自己的操作；</div><div>頁面反饋：頁面操作后，告知用戶操作成功。</div></el-collapse-item><el-collapse-item name="3" disabled><template #title>效率 Efficiency</template><div>簡化流程：設計簡潔直觀的操作流程；</div><div>清晰明確：語言表達清晰且表意明確，讓用戶快速理解進而作出決策；</div><div>幫助用戶識別：界面簡單直白，讓用戶快速識別而非回憶，減少用戶記憶負擔。</div></el-collapse-item><el-collapse-item name="4"><template #title>可控 Controllability</template><div>用戶決策：根據場景可給予用戶操作建議或安全提示，但不能代替用戶進行決策；</div><div>權限：尊重用戶的選擇，包括取消操作的權利。</div></el-collapse-item></el-collapse><!-- 手風琴模式 --><h3>手風琴模式</h3><el-collapse v-model="activeName" accordion><el-collapse-item name="1"><template #title>一致性 Consistency<i class="header-icon el-icon-info"></i></template><div>與現實生活一致：與現實生活的流程、邏輯保持一致，遵循用戶習慣的語言和概念；</div><div>在界面中一致：所有的元素和結構需保持一致，比如：設計樣式、圖標和文本、元素的位置等。</div></el-collapse-item><el-collapse-item name="2"><template #title>反饋 Feedback</template><div>控制反饋：通過界面樣式和交互動效讓用戶可以清晰的感知自己的操作；</div><div>頁面反饋：頁面操作后，告知用戶操作成功。</div></el-collapse-item><el-collapse-item name="3"><template #title>效率 Efficiency</template><div>簡化流程：設計簡潔直觀的操作流程；</div><div>清晰明確：語言表達清晰且表意明確，讓用戶快速理解進而作出決策；</div><div>幫助用戶識別：界面簡單直白，讓用戶快速識別而非回憶，減少用戶記憶負擔。</div></el-collapse-item><el-collapse-item name="4"><template #title>可控 Controllability</template><div>用戶決策：根據場景可給予用戶操作建議或安全提示，但不能代替用戶進行決策；</div><div>權限：尊重用戶的選擇，包括取消操作的權利。</div></el-collapse-item></el-collapse><!-- 動態控制 --><div class="control-section"><el-button @click="toggleAll">切換所有面板</el-button><el-button @click="expandFirst">展開第一個</el-button><el-button @click="collapseAll">收起所有</el-button></div></div>
</template><script setup>
import { ref } from 'vue'
import { ElCollapse, ElCollapseItem, ElButton } from 'element-plus'const activeNames = ref(['1'])
const activeName = ref('1')const handleChange = (val) => {console.log('Collapse changed:', val)
}const toggleAll = () => {if (activeNames.value.length === 0) {activeNames.value = ['1', '2', '4'] // 排除禁用的項} else {activeNames.value = []}
}const expandFirst = () => {activeNames.value = ['1']
}const collapseAll = () => {activeNames.value = []
}
</script><style scoped>
.collapse-container {padding: 20px;
}.collapse-container h3 {margin: 20px 0 10px 0;font-weight: normal;color: #666;
}.header-icon {margin-left: 5px;color: #999;
}.control-section {margin-top: 20px;display: flex;gap: 10px;
}
</style>

🎯 應用場景

1. FAQ 頁面：常見問題解答，用戶點擊問題展開查看答案。
2. 配置面板：將復雜的配置項分組折疊，用戶按需展開設置。
3. 詳情頁：在商品詳情、用戶詳情等頁面中，將次要信息折疊。
4. 表單分組：在長表單中，將相關字段分組并可折疊。
5. 文檔/幫助中心：組織層級化的幫助文檔。

?? 注意事項

• 內容組織：合理劃分折疊項，確保每個面板內的內容主題明確。
• 默認展開：根據用戶最可能查看的內容，合理設置默認展開的面板。
• 手風琴模式：當信息具有互斥性或需要用戶逐項查看時，使用手風琴模式。
• 性能：對于包含大量動態內容的折疊面板，考慮懶加載或條件渲染以優化性能。

---