企业官网建设流程全解析

Element Plus Button 组件完全指南：从基础用法到 API 深度解析

【免费下载链接】element-plus🎉 A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus

Element Plus（由 Element 团队打造的开源 Vue.js 3 UI 组件库）中的Button是使用频率最高的交互组件之一。本指南以官方文档 docs/en-US/component/button.md 为骨架，结合仓库内源码（如 packages/components/button/src/button.vue、use-button.ts 等）深入讲解Button与ButtonGroup的全部用法、属性、插槽与底层实现原理，帮助读者在项目中熟练驾驭从基础样式到自定义主题的完整能力。

基础用法

Button组件提供了丰富的视觉样式开关，通过type、plain、round、dashed与circle五个核心属性即可组合出绝大多数常见按钮形态。

<template> <div class="flex flex-wrap gap-4"> <el-button>Default</el-button> <el-button type="primary">Primary</el-button> <el-button type="success">Success</el-button> <el-button type="info">Info</el-button> <el-button type="warning">Warning</el-button> <el-button type="danger">Danger</el-button> </div> <div class="flex flex-wrap gap-4 mt-4"> <el-button plain>Plain</el-button> <el-button type="primary" plain>Primary Plain</el-button> <el-button round>Round</el-button> <el-button type="success" circle>✓</el-button> <el-button type="warning" dashed>Dashed</el-button> </div> </template>

• type：按钮主题，取值default | primary | success | warning | danger | info（另含已被弃用的text，见下文）。若同时设置color属性，自定义颜色优先级更高。
• plain：素雅扁平风格，保留边框但去掉填充底色，常用于次要操作。
• round：完全圆角按钮（胶囊形）。
• dashed：虚线边框按钮（自 2.13.3 版本加入）。
• circle：正圆形按钮，常搭配图标单独使用。

从源码看，这些属性最终会通过 button.vue 中的buttonKls计算属性映射为el-button--primary、is-plain、is-round、is-dashed、is-circle等 BEM 样式类；而各主题颜色则由 packages/theme-chalk/src/button.scss 通过 CSS 变量统一控制，同时定义了对hover、active、focus-visible状态的默认过渡与配色，保证交互反馈一致。

禁用按钮

disabled属性接受Boolean值，用于控制按钮是否可交互。禁用状态下按钮不可点击、不可聚焦，且视觉上呈现灰色降级效果。

<template> <div class="flex flex-wrap gap-4"> <el-button disabled>Disabled</el-button> <el-button type="primary" disabled>Primary Disabled</el-button> <el-button plain disabled>Plain Disabled</el-button> </div> </template>

需要特别注意的是，disabled并不仅仅是“样式灰化”。在 use-button.ts 中，当渲染标签为原生button时，组件会把disabled与loading同时写入原生属性的disabled与ariaDisabled，保证无障碍访问（ARIA）语义正确；在 handleClick 中，禁用或加载状态下点击事件会被拦截（stopPropagation）而不会向上冒泡。

此外，disabled状态还与表单联动：通过useFormDisabled（来自@element-plus/components/form），当Button被放置于被禁用的el-form/el-form-item中时，会自动继承表单级禁用状态。

Link 按钮（链接风格）

从 2.2.1 版本开始，Element Plus 提供了全新的linkAPI 来渲染链接风格的按钮，用于替代已被弃用的type="text"。链接按钮没有边框和背景，仅在悬停时有颜色变化，适合放置在正文或表格中作为行内操作入口。

<template> <div class="flex flex-wrap items-center gap-4"> <el-button link>Default Link</el-button> <el-button link type="primary">Primary Link</el-button> <el-button link type="success">Success Link</el-button> <el-button link type="info">Info Link</el-button> <el-button link type="warning">Warning Link</el-button> <el-button link type="danger">Danger Link</el-button> </div> </template>

警告（deprecated）：type="text"已被标记为弃用，并将在 3.0.0 版本中移除。官方建议切换到新的linkAPI，并通过type属性来设置链接按钮的主题色。源码层面同样给出了佐证——button.ts 中text类型带有@deprecated注释，且 use-button.ts 通过useDeprecated钩子在运行时抛出弃用提示。

文字按钮

文字按钮（Text Button）自 2.2.0 版本起采用了全新设计：无边框、无背景，仅保留文字本身，视觉上比链接按钮更具“可点击”的语义暗示。由于type属性同时承担了按钮主题色的职责，官方为此新增了独立的text: booleanAPI。

<template> <div class="flex flex-wrap gap-4"> <el-button text>Default Text</el-button> <el-button text type="primary">Primary Text</el-button> <el-button text type="success">Success Text</el-button> <el-button text type="info">Info Text</el-button> <el-button text type="warning">Warning Text</el-button> <el-button text type="danger">Danger Text</el-button> </div> </template>

文字按钮还支持与bg属性组合使用，使背景色常驻（适用于表格行悬停等场景）：

<el-button text bg>Text with BG</el-button>

提示：文字按钮在 2.2.0 的升级属于破坏性变更。如果你仍希望使用旧版（类似普通按钮）的视觉风格，可参考 Link 组件文档 中的基础用法。

图标按钮

图标可以显著增强按钮的信息表达力。icon属性接受图标组件（或图标名字符串），单独使用图标可以节省空间，也可以与文字搭配使用。所有可用图标可在 Element Plus 的 Icon 组件文档中查阅。

<template> <div class="flex flex-wrap gap-4"> <el-button type="primary" :icon="Search">Search</el-button> <el-button type="primary" :icon="Edit">Edit</el-button> <el-button type="success" :icon="Check">Check</el-button> <el-button type="danger" :icon="Delete">Delete</el-button> <el-button type="warning" :icon="StarFilled">Star</el-button> </div> <div class="flex flex-wrap gap-4 mt-4"> <el-button type="primary" :icon="Search" circle /> <el-button type="primary" :icon="Edit" circle /> <el-button type="success" :icon="Check" circle /> <el-button type="danger" :icon="Delete" circle /> </div> </template> <script setup lang="ts"> import { Check, Delete, Edit, Search, StarFilled } from '@element-plus/icons-vue' </script>

图标放在文字右侧时，可以借助<i>标签手动拼接；自定义 SVG 图标组件同样可以直接传入。从源码看，button.vue 中图标通过el-icon包裹渲染，且组件根节点插槽结构在加载状态、图标、文字三者的渲染优先级上有明确划分。

按钮组

<el-button-group>用于将一系列同类操作聚合显示为一个整体，按钮之间自动去除相邻边框、合并圆角，形成紧密的分组视觉效果。自 2.11.9 版本起，按钮组还支持direction属性控制排列方向。

<template> <el-button-group> <el-button type="primary">Left</el-button> <el-button type="primary">Center</el-button> <el-button type="primary">Right</el-button> </el-button-group> </template>

垂直方向排列示例：

<template> <el-button-group direction="vertical"> <el-button type="primary">Top</el-button> <el-button type="primary">Middle</el-button> <el-button type="primary">Bottom</el-button> </el-button-group> </template>

底层原理：ButtonGroup通过 button-group.vue 中的provide向子按钮注入size与type上下文（InjectionKey 定义在 constants.ts），子按钮在 use-button.ts 中通过inject读取——因此ButtonGroup的size/type会作为子按钮属性的兜底默认值生效，无需在每个子按钮上重复书写。

加载状态按钮

点击按钮触发数据加载是后台系统的典型交互。将loading属性设为true即可进入加载态，此时按钮内置 Loading 图标旋转，并自动拦截点击。

<template> <el-button type="primary" :loading="loading" @click="handleClick"> {{ loading ? 'Loading...' : 'Click to load' }} </el-button> </template> <script setup lang="ts"> import { ref } from 'vue' const loading = ref(false) const handleClick = () => { loading.value = true setTimeout(() => (loading.value = false), 2000) } </script>

定制加载图标有两种方式：

• loading插槽：完全自定义加载区域的内容；
• loadingIcon属性：替换默认的 Loading 图标组件。

注意：loading插槽的优先级高于loadingIcon属性。这一优先级在 button.vue 的模板中直接体现——当存在$slots.loading时渲染插槽，否则才渲染loadingIcon。默认的loadingIcon为组件库内置的Loading图标（见 button.ts）。

尺寸

除默认尺寸外，Button提供large与small两种附加尺寸，适配不同界面密度与层级场景。尺寸可作用于单个按钮，也可由外层ButtonGroup或el-form统一控制。

<template> <div class="flex flex-wrap items-center gap-4"> <el-button size="large">Large</el-button> <el-button>Default</el-button> <el-button size="small">Small</el-button> </div> <el-button-group class="mt-4"> <el-button size="large">Large</el-button> <el-button size="large">Large</el-button> </el-button-group> </template>

尺寸的解析逻辑值得留意：在 use-button.ts 中，按钮尺寸通过useFormSize计算，优先级为：按钮自身size>ButtonGroup的size> 表单（el-form）的size> 全局配置。这与 CSS 中$button-padding-vertical、$button-font-size等变量在 button.scss 中的尺寸映射一一对应。

自定义元素标签

自 2.3.4 版本起，tag属性允许将按钮渲染为任意元素，例如button、div、a，乃至router-link、nuxt-link等组件，方便在单页应用路由场景下直接生成链接。

<template> <div class="flex flex-wrap gap-4"> <el-button tag="div" round>as div</el-button> <el-button tag="a" round>as a</el-button> <el-button tag="router-link" :to="'/'" round>as router-link</el-button> </div> </template>

从源码实现看，button.vue 使用动态组件<component :is="tag">渲染，且tag的默认值为'button'（见 button.ts）。只有当tag为原生button时，组件才会附加type（提交类型）、disabled、autofocus等原生属性；渲染为其他标签时这些属性会被忽略，以兼容第三方组件的 prop 体系（见 use-button.ts）。

自定义颜色（beta）

color属性允许直接指定按钮颜色，组件会自动计算对应的 hover 与 active 状态颜色，无需手动维护三套色值。自 2.13.7 版本起，color同样适用于link与text按钮；配合dark属性还可自动转换出适配暗色模式的配色。

<template> <div class="flex flex-wrap gap-4"> <el-button color="#626aef" :dark="isDark">Default</el-button> <el-button color="#626aef" :dark="isDark" plain>Plain</el-button> <el-button color="#626aef" :dark="isDark" link>Link</el-button> <el-button color="#626aef" :dark="isDark" text>Text</el-button> <el-button color="#626aef" :dark="isDark" text bg>Text BG</el-button> </div> </template>

实现原理：颜色计算集中在 button-custom.ts 的useButtonCustomStyle中，核心要点如下：

• 使用@ctrl/tinycolor进行颜色运算；
• 若传入的是 CSS 变量（如var(--el-color-primary)），会先通过getComputedStyle解析出真实色值（见button-custom.ts第 23-29 行）；
• 浅色模式下 hover 色通过tint（混合白色）提亮、active 色通过darken（与#141414混合 20%）加深；
• 暗色模式（dark: true）下逻辑反转，hover 与 active 使用更暗/更深的色阶；
• 计算出的结果以 CSS 变量（--el-button-*-bg-color等）形式写入组件内联样式，直接覆盖 button.scss 中的默认变量，因此无需额外写样式即可生效。

完整可运行的示例可参考官方示例 docs/examples/button/custom.vue，其中覆盖了 Default / Plain / Link / Text / Text BG 及各自的 Disabled 组合形态。

Button API

Button Attributes

补充说明（依据源码 button.ts）：

• native-type取值为'button' | 'submit' | 'reset'，其中reset还会联动触发所在表单的resetFields()（见 use-button.ts）；
• type的合法值由常量buttonTypes限定，''表示不指定、回落到组件的默认主题；
• loading-icon默认值为组件库内置的Loading图标（已通过markRaw标记，避免被 Vue 响应式代理）；
• auto-insert-space的底层判定在 use-button.ts：通过正则/^\p{Unified_Ideograph}{2}$/u校验插槽文本是否恰好为两个汉字，命中后为文字包裹元素追加el-button__text--expand类以插入字距，规避两个汉字并排时的视觉拥挤。

Button Slots

Button Exposes

以上 expose 由 button.vue 的defineExpose导出，可通过模板 ref 在父组件中访问，例如在测试或自动化场景中读取按钮的实际尺寸与禁用状态。

ButtonGroup API

ButtonGroup Attributes

ButtonGroup Slots

综合示例

将上述能力组合，即可快速搭建一个覆盖常见状态的工具栏：

<template> <el-button-group> <el-button type="primary" :icon="Plus">新增</el-button> <el-button type="primary" :icon="Edit">编辑</el-button> <el-button type="danger" :icon="Delete">删除</el-button> <el-button type="warning" :loading="exporting">导出</el-button> </el-button-group> </template> <script setup lang="ts"> import { ref } from 'vue' import { Delete, Edit, Plus } from '@element-plus/icons-vue' const exporting = ref(false) </script>

关于组件树的安装方式：ElButton与ElButtonGroup均通过 index.ts 的withInstall注册，既可全局安装（app.use(ElementPlus)），也可按需引入（配合unplugin-vue-components等工具自动注册）。

关键参考文件

• 官方组件文档：docs/en-US/component/button.md
• 组件主模板：packages/components/button/src/button.vue
• 属性与事件定义：packages/components/button/src/button.ts
• 行为逻辑（尺寸/禁用/点击/字距）：packages/components/button/src/use-button.ts
• 自定义颜色计算：packages/components/button/src/button-custom.ts
• 按钮组实现：packages/components/button/src/button-group.vue
• 样式主题：packages/theme-chalk/src/button.scss

【免费下载链接】element-plus🎉 A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus