Element Plus Button 组件完全指南从基础用法到 API 深度解析【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusElement 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 classflex flex-wrap gap-4 el-buttonDefault/el-button el-button typeprimaryPrimary/el-button el-button typesuccessSuccess/el-button el-button typeinfoInfo/el-button el-button typewarningWarning/el-button el-button typedangerDanger/el-button /div div classflex flex-wrap gap-4 mt-4 el-button plainPlain/el-button el-button typeprimary plainPrimary Plain/el-button el-button roundRound/el-button el-button typesuccess circle✓/el-button el-button typewarning dashedDashed/el-button /div /templatetype按钮主题取值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 classflex flex-wrap gap-4 el-button disabledDisabled/el-button el-button typeprimary disabledPrimary Disabled/el-button el-button plain disabledPlain 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 来渲染链接风格的按钮用于替代已被弃用的typetext。链接按钮没有边框和背景仅在悬停时有颜色变化适合放置在正文或表格中作为行内操作入口。template div classflex flex-wrap items-center gap-4 el-button linkDefault Link/el-button el-button link typeprimaryPrimary Link/el-button el-button link typesuccessSuccess Link/el-button el-button link typeinfoInfo Link/el-button el-button link typewarningWarning Link/el-button el-button link typedangerDanger Link/el-button /div /template警告deprecatedtypetext已被标记为弃用并将在 3.0.0 版本中移除。官方建议切换到新的linkAPI并通过type属性来设置链接按钮的主题色。源码层面同样给出了佐证——button.ts 中text类型带有deprecated注释且 use-button.ts 通过useDeprecated钩子在运行时抛出弃用提示。文字按钮文字按钮Text Button自 2.2.0 版本起采用了全新设计无边框、无背景仅保留文字本身视觉上比链接按钮更具“可点击”的语义暗示。由于type属性同时承担了按钮主题色的职责官方为此新增了独立的text: booleanAPI。template div classflex flex-wrap gap-4 el-button textDefault Text/el-button el-button text typeprimaryPrimary Text/el-button el-button text typesuccessSuccess Text/el-button el-button text typeinfoInfo Text/el-button el-button text typewarningWarning Text/el-button el-button text typedangerDanger Text/el-button /div /template文字按钮还支持与bg属性组合使用使背景色常驻适用于表格行悬停等场景el-button text bgText with BG/el-button提示文字按钮在 2.2.0 的升级属于破坏性变更。如果你仍希望使用旧版类似普通按钮的视觉风格可参考 Link 组件文档 中的基础用法。图标按钮图标可以显著增强按钮的信息表达力。icon属性接受图标组件或图标名字符串单独使用图标可以节省空间也可以与文字搭配使用。所有可用图标可在 Element Plus 的 Icon 组件文档中查阅。template div classflex flex-wrap gap-4 el-button typeprimary :iconSearchSearch/el-button el-button typeprimary :iconEditEdit/el-button el-button typesuccess :iconCheckCheck/el-button el-button typedanger :iconDeleteDelete/el-button el-button typewarning :iconStarFilledStar/el-button /div div classflex flex-wrap gap-4 mt-4 el-button typeprimary :iconSearch circle / el-button typeprimary :iconEdit circle / el-button typesuccess :iconCheck circle / el-button typedanger :iconDelete circle / /div /template script setup langts 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 typeprimaryLeft/el-button el-button typeprimaryCenter/el-button el-button typeprimaryRight/el-button /el-button-group /template垂直方向排列示例template el-button-group directionvertical el-button typeprimaryTop/el-button el-button typeprimaryMiddle/el-button el-button typeprimaryBottom/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 typeprimary :loadingloading clickhandleClick {{ loading ? Loading... : Click to load }} /el-button /template script setup langts 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 classflex flex-wrap items-center gap-4 el-button sizelargeLarge/el-button el-buttonDefault/el-button el-button sizesmallSmall/el-button /div el-button-group classmt-4 el-button sizelargeLarge/el-button el-button sizelargeLarge/el-button /el-button-group /template尺寸的解析逻辑值得留意在 use-button.ts 中按钮尺寸通过useFormSize计算优先级为按钮自身sizeButtonGroup的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 classflex flex-wrap gap-4 el-button tagdiv roundas div/el-button el-button taga roundas a/el-button el-button tagrouter-link :to/ roundas router-link/el-button /div /template从源码实现看button.vue 使用动态组件component :istag渲染且tag的默认值为button见 button.ts。只有当tag为原生button时组件才会附加type提交类型、disabled、autofocus等原生属性渲染为其他标签时这些属性会被忽略以兼容第三方组件的 prop 体系见 use-button.ts。自定义颜色betacolor属性允许直接指定按钮颜色组件会自动计算对应的 hover 与 active 状态颜色无需手动维护三套色值。自 2.13.7 版本起color同样适用于link与text按钮配合dark属性还可自动转换出适配暗色模式的配色。template div classflex flex-wrap gap-4 el-button color#626aef :darkisDarkDefault/el-button el-button color#626aef :darkisDark plainPlain/el-button el-button color#626aef :darkisDark linkLink/el-button el-button color#626aef :darkisDark textText/el-button el-button color#626aef :darkisDark text bgText 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 APIButton Attributes名称说明类型默认值size按钮尺寸enumlarge \| default \| small—type按钮主题设置color时后者优先级更高enumdefault \| primary \| success \| warning \| danger \| info \| \| texttext已弃用—plain是否为朴素按钮booleanfalsetext ^(2.2.0)是否为文字按钮booleanfalsebg ^(2.2.0)文字按钮背景是否常驻booleanfalselink ^(2.2.1)是否为链接按钮booleanfalseround是否为圆角胶囊按钮booleanfalsecircle是否为圆形按钮booleanfalsedashed ^(2.13.3)是否为虚线边框按钮booleanfalseloading是否为加载状态booleanfalseloading-icon自定义加载图标组件string/ComponentLoadingdisabled是否禁用booleanfalseicon图标组件string/Component—autofocus同原生autofocusbooleanfalsenative-type同原生按钮typeenumbutton \| submit \| resetbuttonauto-insert-space两个汉字之间自动插入空格仅当文本长度为 2 且全为汉字时生效booleanfalsecolor自定义按钮颜色自动计算 hover / active 色自 ^(2.13.7) 起支持 link/text 按钮string—dark暗色模式自动将color转换为暗色配色booleanfalsetag ^(2.3.4)自定义渲染元素标签string/Componentbutton补充说明依据源码 button.tsnative-type取值为button | submit | reset其中reset还会联动触发所在表单的resetFields()见 use-button.tstype的合法值由常量buttonTypes限定表示不指定、回落到组件的默认主题loading-icon默认值为组件库内置的Loading图标已通过markRaw标记避免被 Vue 响应式代理auto-insert-space的底层判定在 use-button.ts通过正则/^\p{Unified_Ideograph}{2}$/u校验插槽文本是否恰好为两个汉字命中后为文字包裹元素追加el-button__text--expand类以插入字距规避两个汉字并排时的视觉拥挤。Button Slots名称说明default自定义默认内容loading自定义加载状态组件icon自定义图标组件Button Exposes名称说明类型ref按钮 HTML 元素RefHTMLButtonElementsize按钮尺寸ComputedRef \| small \| default \| largetype按钮主题ComputedRef \| default \| primary \| success \| warning \| info \| danger \| textdisabled是否禁用ComputedRefbooleanshouldAddSpace是否自动添加字距ComputedRefboolean以上 expose 由 button.vue 的defineExpose导出可通过模板 ref 在父组件中访问例如在测试或自动化场景中读取按钮的实际尺寸与禁用状态。ButtonGroup APIButtonGroup Attributes名称说明类型默认值size控制组内按钮尺寸enumlarge \| default \| small—type控制组内按钮主题enumprimary \| success \| warning \| danger \| info—direction ^(2.11.9)排列方向enumhorizontal \| verticalhorizontalButtonGroup Slots名称说明子标签default自定义按钮组内容Button综合示例将上述能力组合即可快速搭建一个覆盖常见状态的工具栏template el-button-group el-button typeprimary :iconPlus新增/el-button el-button typeprimary :iconEdit编辑/el-button el-button typedanger :iconDelete删除/el-button el-button typewarning :loadingexporting导出/el-button /el-button-group /template script setup langts 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
