Button 按钮

基于 Element Plus Button 增强的按钮组件，支持 Iconify 图标。

基础用法

使用 type、plain、round、circle 和 icon 来定义按钮的样式。（icon 属性支持 Element Plus 图标和 Iconify 图标名称，例如 'tabler:refresh'）

<template>
  <div class="button-example">
    <div class="button-row">
      <ep-button>Default</ep-button>
      <ep-button type="primary">Primary</ep-button>
      <ep-button type="success">Success</ep-button>
      <ep-button type="info">Info</ep-button>
      <ep-button type="warning">Warning</ep-button>
      <ep-button type="danger">Danger</ep-button>
    </div>

    <div class="button-row">
      <ep-button plain>Plain</ep-button>
      <ep-button type="primary" plain>Primary</ep-button>
      <ep-button type="success" plain>Success</ep-button>
      <ep-button type="info" plain>Info</ep-button>
      <ep-button type="warning" plain>Warning</ep-button>
      <ep-button type="danger" plain>Danger</ep-button>
    </div>

    <div class="button-row">
      <ep-button round>Round</ep-button>
      <ep-button type="primary" round>Primary</ep-button>
      <ep-button type="success" round>Success</ep-button>
      <ep-button type="info" round>Info</ep-button>
      <ep-button type="warning" round>Warning</ep-button>
      <ep-button type="danger" round>Danger</ep-button>
    </div>

    <div class="button-row">
      <ep-button icon="tabler:search" circle />
      <ep-button type="primary" icon="tabler:edit" circle />
      <ep-button type="success" icon="tabler:check" circle />
      <ep-button type="info" icon="tabler:message" circle />
      <ep-button type="warning" icon="tabler:star" circle />
      <ep-button type="danger" icon="tabler:trash" circle />
    </div>
  </div>
</template>
<script lang="ts" setup>
defineOptions({
  name: "basic"
})
</script>
<style scoped>
.button-example {
  display: flex;
  flex-direction: column;
  gap: 1rem;
}

.button-row {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
  align-items: center;
}

.button-row > * {
  margin: 0;
}
</style>

隐藏源码

禁用状态

使用 disabled 属性来定义按钮是否被禁用。该属性接受一个 Boolean 类型的值。

<template>
  <div class="button-example">
    <div class="button-row">
      <ep-button disabled>Default</ep-button>
      <ep-button type="primary" disabled>Primary</ep-button>
      <ep-button type="success" disabled>Success</ep-button>
      <ep-button type="info" disabled>Info</ep-button>
      <ep-button type="warning" disabled>Warning</ep-button>
      <ep-button type="danger" disabled>Danger</ep-button>
    </div>

    <div class="button-row">
      <ep-button plain disabled>Plain</ep-button>
      <ep-button type="primary" plain disabled>Primary</ep-button>
      <ep-button type="success" plain disabled>Success</ep-button>
      <ep-button type="info" plain disabled>Info</ep-button>
      <ep-button type="warning" plain disabled>Warning</ep-button>
      <ep-button type="danger" plain disabled>Danger</ep-button>
    </div>
  </div>
</template>

<style scoped>
.button-example {
  display: flex;
  flex-direction: column;
  gap: 1rem;
}

.button-row {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
  align-items: center;
}

.button-row > * {
  margin: 0;
}
</style>

隐藏源码

链接按钮

WARNING

type="text" 已被 废弃，将在 3.0.0 版本中移除，请考虑切换到新的 API。

新的 API link 已在 2.2.1 版本中添加，你可以使用 type API 来设置链接按钮的主题。

Basic link button

Disabled link button

<template>
  <p>Basic link button</p>
  <div class="mb-4">
    <ep-button v-for="button in buttons" :key="button.text" :type="button.type" link>
      {{ button.text }}
    </ep-button>
  </div>

  <p>Disabled link button</p>
  <div>
    <ep-button v-for="button in buttons" :key="button.text" :type="button.type" link disabled>
      {{ button.text }}
    </ep-button>
  </div>
</template>

<script setup lang="ts">
const buttons = [
  { type: "", text: "plain" },
  { type: "primary", text: "primary" },
  { type: "success", text: "success" },
  { type: "info", text: "info" },
  { type: "warning", text: "warning" },
  { type: "danger", text: "danger" }
] as const
</script>

隐藏源码

文字按钮

TIP

文字按钮已升级为新设计，如果你想使用之前的版本，可以查看 Link。

API 也已更新，因为 type 属性也代表按钮的样式。所以 Element Plus 必须为文字按钮创建一个新的 API text: boolean。

没有边框和背景色的按钮。

Basic text button

Background color always on

Disabled text button

<template>
  <p>Basic text button</p>
  <div class="mb-4">
    <ep-button v-for="button in buttons" :key="button.text" :type="button.type" text>
      {{ button.text }}
    </ep-button>
  </div>

  <p>Background color always on</p>
  <div class="mb-4">
    <ep-button v-for="button in buttons" :key="button.text" :type="button.type" text bg>
      {{ button.text }}
    </ep-button>
  </div>

  <p>Disabled text button</p>
  <div>
    <ep-button v-for="button in buttons" :key="button.text" :type="button.type" text disabled>
      {{ button.text }}
    </ep-button>
  </div>
</template>

<script setup lang="ts">
const buttons = [
  { type: "", text: "plain" },
  { type: "primary", text: "primary" },
  { type: "success", text: "success" },
  { type: "info", text: "info" },
  { type: "warning", text: "warning" },
  { type: "danger", text: "danger" }
] as const
</script>

隐藏源码

图标按钮

使用图标为按钮添加更多含义。你也可以单独使用图标来节省空间，或者与文字一起使用。

使用 icon 属性来添加图标。你可以使用 Iconify 图标名称（例如 'tabler:home'）或在 Element Plus 图标组件中查找图标列表。在文字右侧添加图标可以通过 <i> 标签实现。也可以使用自定义图标。以下示例使用 Iconify。

<template>
  <div>
    <ep-button type="primary" icon="tabler:edit" />
    <ep-button type="primary" icon="tabler:share" />
    <ep-button type="primary" icon="tabler:trash" />
    <ep-button type="primary" icon="tabler:search">Search</ep-button>
    <ep-button type="primary">
      Upload<ep-icon class="el-icon--right" icon="tabler:upload" />
    </ep-button>
  </div>
</template>

隐藏源码

按钮组

显示为按钮组，可用于分组一系列类似的操作。

使用 <el-button-group> 标签来分组你的按钮。

HorizontalVertical

<template>
  <el-button-group class="mb-4">
    <ep-button type="primary" icon="tabler:chevron-left">Previous Page</ep-button>
    <ep-button type="primary">
      Next Page<ep-icon class="el-icon--right" icon="tabler:chevron-right" />
    </ep-button>
  </el-button-group>
  <br />
  <el-radio-group v-model="direction" class="mb-2">
    <el-radio value="horizontal">Horizontal</el-radio>
    <el-radio value="vertical">Vertical</el-radio>
  </el-radio-group>
  <br />

  <el-button-group :direction="direction">
    <ep-button type="primary" icon="tabler:smart-home" />
    <ep-button type="primary" icon="tabler:adjustments-horizontal" />
    <ep-button type="primary" icon="tabler:notification" />
  </el-button-group>
</template>

<script setup lang="ts">
import { ref } from "vue"

const direction = ref<"horizontal" | "vertical">("horizontal")
</script>

隐藏源码

加载状态按钮

点击按钮来加载数据，然后按钮显示加载状态。

设置 loading 属性为 true 来显示加载状态。

TIP

你可以使用 loading 插槽或 loadingIcon 来自定义加载组件。

注意：loading 插槽的优先级高于 loadingIcon

<template>
  <ep-button type="primary" loading>Loading</ep-button>
  <ep-button type="primary" loading-icon="tabler:loader-3" loading>Loading</ep-button>
  <ep-button type="primary" loading>
    <template #loading>
      <div class="custom-loading">
        <svg class="circular" viewBox="-10, -10, 50, 50">
          <path
            class="path"
            d="
            M 30 15
            L 28 17
            M 25.61 25.61
            A 15 15, 0, 0, 1, 15 30
            A 15 15, 0, 1, 1, 27.99 7.5
            L 15 15
          "
            style="stroke-width: 4px; fill: #fff"
          />
        </svg>
      </div>
    </template>
    Loading
  </ep-button>
</template>

<style scoped>
.el-button .custom-loading .circular {
  margin-right: 6px;
  width: 18px;
  height: 18px;
  animation: loading-rotate 2s linear infinite;
}
.el-button .custom-loading .circular .path {
  animation: loading-dash 1.5s ease-in-out infinite;
  stroke-dasharray: 90, 150;
  stroke-dashoffset: 0;
  stroke-width: 2;
  stroke: var(--ep-button-text-color);
  stroke-linecap: round;
}
</style>

隐藏源码

尺寸

除了默认尺寸外，按钮组件还提供了三个额外的尺寸供你在不同场景中选择。

使用 size 属性来设置额外的尺寸，可选值包括 large、small。

<template>
  <div class="flex flex-wrap items-center mb-4">
    <ep-button size="large">Large</ep-button>
    <ep-button>Default</ep-button>
    <ep-button size="small">Small</ep-button>
    <ep-button size="large" icon="tabler:search">Search</ep-button>
    <ep-button icon="tabler:search">Search</ep-button>
    <ep-button size="small" icon="tabler:search">Search</ep-button>
  </div>
  <div class="flex flex-wrap items-center mb-4">
    <ep-button size="large" round>Large</ep-button>
    <ep-button round>Default</ep-button>
    <ep-button size="small" round>Small</ep-button>
    <ep-button size="large" icon="tabler:search" round>Search</ep-button>
    <ep-button icon="tabler:search" round>Search</ep-button>
    <ep-button size="small" icon="tabler:search" round>Search</ep-button>
  </div>
  <div class="flex flex-wrap items-center">
    <ep-button icon="tabler:search" size="large" circle />
    <ep-button icon="tabler:search" circle />
    <ep-button icon="tabler:search" size="small" circle />
  </div>
</template>

<script setup lang="ts"></script>

隐藏源码

标签

你可以自定义元素标签，例如 button、div、a、router-link、nuxt-link。

div

a

<template>
  <ep-button>button</ep-button>
  <ep-button tag="div" role="button" tabindex="0">div</ep-button>
  <ep-button
    type="primary"
    tag="a"
    href="https://github.com/element-plus/element-plus"
    target="_blank"
    rel="noopener noreferrer"
    class="!color-#fff"
  >
    a
  </ep-button>
</template>

隐藏源码

Button API

Button 属性

名称	说明	类型	默认值
icon	图标组件或 iconify 图标名	string / Component	—
loading-icon	自定义加载图标组件	string / Component	Loading

Element Plus Button 属性

名称	说明	类型	默认值
size	按钮尺寸	enum	—
type	按钮类型，当设置 color 时，后者优先	enum	—
plain	是否为朴素按钮	boolean	false
text	是否为文字按钮	boolean	false
bg	是否始终显示文字按钮的背景色	boolean	false
link	是否为链接按钮	boolean	false
round	是否为圆角按钮	boolean	false
circle	是否为圆形按钮	boolean	false
loading	是否为加载中状态	boolean	false
loading-icon	自定义加载图标组件	string / Component	Loading
disabled	按钮是否为禁用状态	boolean	false
icon	图标组件	string / Component	—
autofocus	原生 autofocus 属性	boolean	false
native-type	原生 type 属性	enum	button
auto-insert-space	自动在两个中文字符之间插入空格（仅当文本长度为 2 且所有字符都是中文时生效）	boolean	false
color	自定义按钮颜色，自动计算 hover 和 active 颜色	string	—
dark	深色模式，自动将 color 转换为深色模式颜色	boolean	false
tag	自定义元素标签	string / Component	button

Button 插槽

Element Plus Button 插槽

名称	说明
default	自定义默认内容
loading	自定义加载中组件
icon	自定义图标组件

Button 暴露

Element Plus Button 暴露

名称	说明	类型
ref	按钮 html 元素	object
size	按钮尺寸	object
type	按钮类型	object
disabled	按钮是否禁用	object
shouldAddSpace	是否添加空格	object

ButtonGroup API

ButtonGroup 属性

Element Plus ButtonGroup 属性

名称	说明	类型	默认值
size	控制该按钮组内按钮的大小	enum	—
type	控制该按钮组内按钮的类型	enum	—
direction	显示方向	enum	horizontal

ButtonGroup 插槽

Element Plus ButtonGroup 插槽

名称	说明	子标签
default	自定义按钮组内容	Button

类型声明

显示声明

import type { ButtonProps } from "element-plus"
import type { Component } from "vue"

export interface EpButtonProps extends Omit<ButtonProps, "icon"> {
  icon?: string | Component
}