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">
      <bk-button>Default</bk-button>
      <bk-button type="primary">Primary</bk-button>
      <bk-button type="success">Success</bk-button>
      <bk-button type="info">Info</bk-button>
      <bk-button type="warning">Warning</bk-button>
      <bk-button type="danger">Danger</bk-button>
    </div>

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

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

    <div class="button-row">
      <bk-button icon="tabler:search" circle />
      <bk-button type="primary" icon="tabler:edit" circle />
      <bk-button type="success" icon="tabler:check" circle />
      <bk-button type="info" icon="tabler:message" circle />
      <bk-button type="warning" icon="tabler:star" circle />
      <bk-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 属性用于控制按钮是否禁用，接受布尔值。

通过 disabled 属性设置按钮是否禁用，该属性值为布尔类型。

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

    <div class="button-row">
      <bk-button plain disabled>Plain</bk-button>
      <bk-button type="primary" plain disabled>Primary</bk-button>
      <bk-button type="success" plain disabled>Success</bk-button>
      <bk-button type="info" plain disabled>Info</bk-button>
      <bk-button type="warning" plain disabled>Warning</bk-button>
      <bk-button type="danger" plain disabled>Danger</bk-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" 已被废弃，Element Plus 计划在 3.0.0 版本中移除该用法，请切换至新的 API。

新 API link 已在 Element Plus 2.2.1 版本中新增，你可以通过 type API 为链接按钮设置主题样式。

Basic link button

Disabled link button

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

  <p>Disabled link button</p>
  <div>
    <bk-button v-for="button in buttons" :key="button.text" :type="button.type" link disabled>
      {{ button.text }}
    </bk-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 新增了 text: boolean 专属 API 用于定义文字按钮。

无边框、无背景色的纯文字按钮。

Basic text button

Background color always on

Disabled text button

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

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

  <p>Disabled text button</p>
  <div>
    <bk-button v-for="button in buttons" :key="button.text" :type="button.type" text disabled>
      {{ button.text }}
    </bk-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>
    <bk-button type="primary" icon="tabler:edit" />
    <bk-button type="primary" icon="tabler:share" />
    <bk-button type="primary" icon="tabler:trash" />
    <bk-button type="primary" icon="tabler:search">Search</bk-button>
    <bk-button type="primary">
      Upload<bk-icon class="el-icon--right" icon="tabler:upload" />
    </bk-button>
  </div>
</template>

隐藏源码

按钮组

将一系列同类操作的按钮组合展示，使用 <bk-button-group> 标签包裹即可。

使用 <bk-button-group> 标签对按钮进行分组。

HorizontalVertical

<template>
  <bk-button-group class="mb-4">
    <bk-button type="primary" icon="tabler:chevron-left">Previous Page</bk-button>
    <bk-button type="primary">
      Next Page<bk-icon class="el-icon--right" icon="tabler:chevron-right" />
    </bk-button>
  </bk-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 />

  <bk-button-group :direction="direction">
    <bk-button type="primary" icon="tabler:smart-home" />
    <bk-button type="primary" icon="tabler:adjustments-horizontal" />
    <bk-button type="primary" icon="tabler:notification" />
  </bk-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>
  <el-button type="primary" loading>Loading</el-button>
  <bk-button type="primary" loading>Loading</bk-button>
  <bk-button type="primary" loading-icon="tabler:loader-3" loading>Loading</bk-button>
  <bk-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
  </bk-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(--bk-button-text-color);
  stroke-linecap: round;
}
</style>

隐藏源码

尺寸

除默认尺寸外，按钮组件提供了 large、small 两种额外尺寸，适配不同场景。

使用 size 属性设置按钮尺寸，可选值为 large、small。

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

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

隐藏源码

自定义标签

可自定义按钮渲染的根元素标签，例如 button、div、a、router-link、nuxt-link 等。

div

a

<template>
  <bk-button>button</bk-button>
  <bk-button tag="div" role="button" tabindex="0">div</bk-button>
  <bk-button
    type="primary"
    tag="a"
    href="https://github.com/dongchen-xie/vue-business-kit"
    target="_blank"
    rel="noopener noreferrer"
    class="!color-#fff"
  >
    a
  </bk-button>
</template>

隐藏源码

Button API

Button 属性

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

Element Plus Button 原生属性

属性名	说明	类型	默认值
size	按钮尺寸	enum	—
type	按钮类型，设置 color 时优先级高于 type	enum	—
plain	是否为朴素按钮	boolean	false
text	是否为文字按钮	boolean	false
bg	文字按钮是否始终显示背景色	boolean	false
link	是否为链接按钮	boolean	false
round	是否为圆角按钮	boolean	false
circle	是否为圆形按钮	boolean	false
loading	是否为加载状态	boolean	false
disabled	是否禁用按钮	boolean	false
autofocus	原生自动聚焦属性	boolean	false
native-type	原生 button 标签的 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 Exposes

Element Plus Button Exposes

名称	说明	类型
ref	按钮 DOM 元素	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