# Element Plus Vue3 组件库完整文档

> 来源: https://element-plus.org/zh-CN/
> 生成日期: 2026-06-24
> 基于 Vue 3.x 的桌面端组件库，使用 el- 前缀
> 支持 Composition API（<script setup>）

---

<!-- ============================================ -->
<!-- 类别: 指南 -->
<!-- ============================================ -->

## [guide/design] 设计原则
> 官方文档: https://element-plus.org/zh-CN/guide/design.html

---

# 设计原则 [​](#设计原则)

Consistency

Feedback

Efficiency

Controllability

## 一致 Consistency [​](#一致-consistency)

-   **与现实生活一致：** 与现实生活的流程、逻辑保持一致，遵循用户习惯的语言和概念；

-   **在界面中一致：** 所有的元素和结构需保持一致，比如：设计样式、图标和文本、元素的位置等。

## 反馈 Feedback [​](#反馈-feedback)

-   **控制反馈：** 通过界面样式和交互动效让用户可以清晰的感知自己的操作；

-   **页面反馈：** 操作后，通过页面元素的变化清晰地展现当前状态。

## 效率 Efficiency [​](#效率-efficiency)

-   **简化流程：** 设计简洁直观的操作流程；

-   **清晰明确：** 语言表达清晰且表意明确，让用户快速理解进而作出决策；

-   **帮助用户识别：** 界面简单直白，让用户快速识别而非回忆，减少用户记忆负担。

## 可控 Controllability [​](#可控-controllability)

-   **用户决策：** 根据场景可给予用户操作建议或安全提示，但不能代替用户进行决策；

-   **结果可控：** 用户可以自由的进行操作，包括撤销、回退和终止当前操作等。

[导航](https://element-plus.org/zh-CN/guide/nav)




---
## [guide/nav] 导航指南
> 官方文档: https://element-plus.org/zh-CN/guide/nav.html

---

# 导航 [​](#导航)

导航可以解决用户在访问页面时：在哪里，去哪里，怎样去的问题。 一般导航会有「侧栏导航」和「顶部导航」2 种类型。

## 选择合适的导航 [​](#选择合适的导航)

选择合适的导航可以让用户在产品的使用过程中非常流畅，相反若是不合适就会引起用户操作不适（方向不明确）。 以下是「侧栏导航」和 「顶部导航」的区别。

## 侧栏导航 [​](#侧栏导航)

可将导航栏固定在左侧，提高导航可见性，方便页面之间切换； 顶部可放置常用工具，如搜索条、帮助按钮、通知按钮等。 适用于中后台的管理型、工具型网站。

### 一级类目 [​](#一级类目)

适用于结构简单的网站：只有一级页面时。 不需要使用面包屑。

### 二级类目 [​](#二级类目)

侧栏中最多可显示两级导航； 侧栏中最多可显示两级导航； 当使用二级导航时，我们建议搭配使用面包屑，方便用户定位自己的位置和快速返回。

### 三级类目 [​](#三级类目)

适用于较复杂的工具型后台。 适用于较复杂的工具型后台，左侧栏为一级导航，中间栏可显示其对应的二级导航，也可放置其他的工具型选项。

## 顶部导航 [​](#顶部导航)

顺应了从上至下的正常浏览顺序，方便浏览信息； 顶部宽度限制了导航的数量和文本长度。

适用于导航较少，页面篇幅较长的网站。

[设计](https://element-plus.org/zh-CN/guide/design)

[安装](https://element-plus.org/zh-CN/guide/installation)




---
## [guide/installation] 安装指南
> 官方文档: https://element-plus.org/zh-CN/guide/installation.html

---

# 安装 [​](#安装)

## 兼容性2.5.0 [​](#兼容性)

Element Plus 支持最近两个版本的浏览器。

如果您需要支持旧版本的浏览器，请自行添加 [Babel](https://babeljs.io/) 和相应的 Polyfill 。

由于 Vue 3 不再支持 IE11，Element Plus 也不再支持 IE 浏览器。

| 版本 | ![Chrome](https://cdn.jsdelivr.net/npm/@browser-logos/chrome/chrome_32x32.png)
Chrome | ![IE](https://cdn.jsdelivr.net/npm/@browser-logos/edge/edge_32x32.png)
Edge | ![Firefox](https://cdn.jsdelivr.net/npm/@browser-logos/firefox/firefox_32x32.png)
Firefox | ![Safari](https://cdn.jsdelivr.net/npm/@browser-logos/safari/safari_32x32.png)
Safari |
| --- | --- | --- | --- | --- |
| < 2.5.0 | Chrome ≥ 64 | Edge ≥ 79 | Firefox ≥ 78 | Safari ≥ 12 |
| 2.5.0 + | Chrome ≥ 85 | Edge ≥ 85 | Firefox ≥ 79 | Safari ≥ 14.1 |

### Sass [​](#sass)

在`2.8.5`及以后的版本, [Sass](https://github.com/sass) 的最低支持版本为 `1.79.0`.

如果您的终端提示 `legacy JS API Deprecation Warning`，您可以在 [vite.config.ts](https://cn.vite.dev/config/shared-options#css-preprocessoroptions) 中配置以下代码：

vite.config.ts

ts

```
import { defineConfig } from 'vite'
// https://vitejs.dev/config/
export default defineConfig({
  // ...
  css: {
    preprocessorOptions: {
      scss: { api: 'modern-compiler' },
    },
  },
  // ...
})
```

### 版本 [​](#版本)

Element Plus 目前还处于快速开发迭代中。 [![ElementPlus version badge](https://img.shields.io/npm/v/element-plus.svg?style=flat-square)](https://www.npmjs.org/package/element-plus)

此外，在dev 分支上的每个提交和 PR 都将被发布到 [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new)，如果您想要使用一些未发布的内容，您可以参考 [这里](https://github.com/element-plus/element-plus/issues/18433#issuecomment-2392618431)。

## 使用包管理器 [​](#使用包管理器)

**我们建议使用包管理器（[NPM](https://www.npmjs.com/)、[Yarn](https://classic.yarnpkg.com/lang/en/)、[PNPM](https://pnpm.io/)）安装 Element Plus**， 这样您就可以使用诸如 [Vite](https://vitejs.dev/) 和 [Webpack](https://webpack.js.org/) 之类的打包工具。

选择一个你喜欢的包管理器

npmyarnpnpm

shell

```
$ npm install element-plus --save
```

shell

```
$ yarn add element-plus
```

shell

```
$ pnpm install element-plus
```

如果你的网络环境不佳，推荐使用 [cnpm](https://github.com/cnpm/cnpm) 或使用 [npmmirror](https://npmmirror.com/)

shell

```
npm config set registry https://registry.npmmirror.com
```

## 浏览器直接引入 [​](#浏览器直接引入)

直接通过浏览器的 HTML 标签导入 Element Plus，然后就可以使用全局变量 `ElementPlus` 了。

根据不同的 CDN 提供商有不同的引入方式， 我们在这里以 [unpkg](https://unpkg.com/) 和 [jsDelivr](https://jsdelivr.com/) 举例。 你也可以使用其它的 CDN 供应商。

unpkgjsDelivr

html

```
<head>
  <!-- 导入样式 -->
  <link rel="stylesheet" href="//unpkg.com/element-plus/dist/index.css" />
  <!-- 导入 Vue 3 -->
  <script src="//unpkg.com/vue@3"></script>
  <!-- 导入组件库 -->
  <script src="//unpkg.com/element-plus"></script>
</head>
```

html

```
<head>
  <!-- 导入样式 -->
  <link
    rel="stylesheet"
    href="//cdn.jsdelivr.net/npm/element-plus/dist/index.css"
  />
  <!-- 导入 Vue 3 -->
  <script src="//cdn.jsdelivr.net/npm/vue@3"></script>
  <!-- 导入组件库 -->
  <script src="//cdn.jsdelivr.net/npm/element-plus"></script>
</head>
```

TIP

我们建议使用 CDN 引入 Element Plus 的用户在链接地址上锁定版本，以免将来 Element Plus 升级时受到非兼容性更新的影响。 锁定版本的方法请查看 [unpkg.com](https://unpkg.com/)。

由于原生的 HTML 解析行为的限制，单个闭合标签可能会导致一些例外情况，所以请使用双封闭标签， [参考](https://vuejs.org/guide/essentials/component-basics.html#in-dom-template-parsing-caveats)

html

```
<!-- 示例 -->
<el-table>
  <el-table-column></el-table-column>
  <el-table-column></el-table-column>
</el-table>
```

## Hello World [​](#hello-world)

通过 CDN 的方式我们可以很容易地使用 Element Plus 写出一个 Hello world 页面。 [在线演示](https://codepen.io/iamkun/pen/YzWMaVr)

如果是通过包管理器安装，并希望配合打包工具使用，请阅读下一节：[快速上手](https://element-plus.org/en-US/guide/quickstart)。

[导航](https://element-plus.org/zh-CN/guide/nav)

[快速开始](https://element-plus.org/zh-CN/guide/quickstart)




---
## [guide/quickstart] 快速开始
> 官方文档: https://element-plus.org/zh-CN/guide/quickstart.html

---

# 快速开始 [​](#快速开始)

本节将介绍如何在项目中使用 Element Plus。

## 用法 [​](#用法)

### 完整引入 [​](#完整引入)

如果你对打包后的文件大小不是很在乎，那么使用完整导入会更方便。

main.ts

ts

```
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'

const app = createApp(App)

app.use(ElementPlus)
app.mount('#app')
```

#### Volar 支持 [​](#volar-支持)

如果您使用 Volar，请在 `tsconfig.json` 中通过 `compilerOptions.type` 指定全局组件类型。

tsconfig.json

json

```
{
  "compilerOptions": {
    // ...
    "types": ["element-plus/global"]
  }
}
```

### 按需导入 [​](#按需导入)

您需要使用额外的插件来导入要使用的组件。

#### 自动导入 推荐 [​](#自动导入-推荐)

首先你需要安装`unplugin-vue-components` 和 `unplugin-auto-import`这两款插件

npmyarnpnpm

shell

```
$ npm install -D unplugin-vue-components unplugin-auto-import
```

shell

```
$ yarn add -D unplugin-vue-components unplugin-auto-import
```

shell

```
$ pnpm install -D unplugin-vue-components unplugin-auto-import
```

然后把下列代码插入到你的 `Vite` 或 `Webpack` 的配置文件中

vite.config.tswebpack.config.js

ts

```
import { defineConfig } from 'vite'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  // ...
  plugins: [
    // ...
    AutoImport({
      resolvers: [ElementPlusResolver()],
    }),
    Components({
      resolvers: [ElementPlusResolver()],
    }),
  ],
})
```

js

```
const AutoImport = require('unplugin-auto-import/webpack')
const Components = require('unplugin-vue-components/webpack')
const { ElementPlusResolver } = require('unplugin-vue-components/resolvers')

module.exports = {
  // ...
  plugins: [
    AutoImport({
      resolvers: [ElementPlusResolver()],
    }),
    Components({
      resolvers: [ElementPlusResolver()],
    }),
  ],
}
```

想了解更多打包 ([Rollup](https://rollupjs.org/), [Vue CLI](https://cli.vuejs.org/)) 和配置工具，请参考 [unplugin-vue-components](https://github.com/antfu/unplugin-vue-components#installation) 和 [unplugin-auto-import](https://github.com/antfu/unplugin-auto-import#install)。

#### Nuxt [​](#nuxt)

对于 Nuxt 用户，只需要安装 `@element-plus/nuxt` 即可。

npmyarnpnpm

shell

```
$ npm install -D @element-plus/nuxt
```

shell

```
$ yarn add -D @element-plus/nuxt
```

shell

```
$ pnpm install -D @element-plus/nuxt
```

然后将下面的代码写入你的配置文件.

nuxt.config.ts

ts

```
export default defineNuxtConfig({
  modules: ['@element-plus/nuxt'],
})
```

配置文档参考 [docs](https://github.com/element-plus/element-plus-nuxt#readme).

### 手动导入 [​](#手动导入)

Element Plus 提供了基于 ES Module 的开箱即用的 [Tree Shaking](https://webpack.js.org/guides/tree-shaking/) 功能。

但你需要安装 [unplugin-element-plus](https://github.com/element-plus/unplugin-element-plus) 来导入样式。 配置文档参考 [docs](https://github.com/element-plus/unplugin-element-plus#readme).

App.vue

vue

```
<template>
  <el-button>I am ElButton</el-button>
</template>

<script setup lang="ts">
import { ElButton } from 'element-plus'
</script>
```

vite.config.ts

ts

```
import { defineConfig } from 'vite'
import ElementPlus from 'unplugin-element-plus/vite'

export default defineConfig({
  // ...
  plugins: [ElementPlus()],
})
```

## 快捷搭建项目模板 [​](#快捷搭建项目模板)

我们提供了 [Vite 模板](https://github.com/element-plus/element-plus-vite-starter)。

对于Nuxt 用户，我们有一个 [Nuxt 模板](https://github.com/element-plus/element-plus-nuxt-starter)。

对于 Laravel 用户，我们也准备了 [Laravel 模板](https://github.com/element-plus/element-plus-in-laravel-starter)。

## 全局配置 [​](#全局配置)

在引入 ElementPlus 时，可以传入一个包含 `size` 和 `zIndex` 属性的全局配置对象。 `size` 用于设置表单组件的默认尺寸，`zIndex` 用于设置弹出组件的层级，`zIndex` 的默认值为 `2000`。

完整引入：

main.ts

ts

```
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus, { size: 'small', zIndex: 3000 })
```

按需引入:

App.vue

vue

```
<template>
  <el-config-provider :size="size" :z-index="zIndex">
    <app />
  </el-config-provider>
</template>

<script setup lang="ts">
import { ElConfigProvider } from 'element-plus'

const zIndex = 3000
const size = 'small'
</script>
```

## 使用 Nuxt.js [​](#使用-nuxt-js)

您也可以使用 [Nuxt.js](https://nuxt.com/): 更多详情请参考 [Element Plus Nuxt.js 初始化模板](https://github.com/element-plus/element-plus-nuxt-starter)。

## 开始使用 [​](#开始使用)

现在你可以启动项目了。 对于每个组件的用法，请参考单个组件对应的文档。

[安装](https://element-plus.org/zh-CN/guide/installation)

[国际化](https://element-plus.org/zh-CN/guide/i18n)




---
## [guide/i18n] 国际化指南
> 官方文档: https://element-plus.org/zh-CN/guide/i18n.html

---

# 国际化 [​](#国际化)

Element Plus 组件**默认**使用英文。 如果你想使用其他语言，请继续阅读以了解具体方法。

## 全局配置 [​](#全局配置)

Element Plus 提供了全局配置选项。

main.ts

ts

```
import ElementPlus from 'element-plus'
import zhCn from 'element-plus/es/locale/lang/zh-cn'

app.use(ElementPlus, {
  locale: zhCn,
})
```

## ConfigProvider [​](#configprovider)

Element Plus还提供一个 Vue 组件 [ConfigProvider](https://element-plus.org/zh-CN/component/config-provider) 用于全局配置本地化设置和其他设置。

App.vue

vue

```
<template>
  <el-config-provider :locale="zhCn">
    <app />
  </el-config-provider>
</template>

<script setup lang="ts">
import { ElConfigProvider } from 'element-plus'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
</script>
```

## 日期和时间本地化 [​](#日期和时间本地化)

我们使用 [Day.js](https://day.js.org/docs/en/i18n/i18n) 库来管理组件的日期和时间，例如 `DatePicker`。 在 Day.js 中设置合适的语言也非常重要，这样才能确保国际化功能正常工作。 您必须分开导入Day.js的区域设置。

ts

```
import 'dayjs/locale/zh-cn'
```

## CDN 用法 [​](#cdn-用法)

完整文档请参阅：[ConfigProvider](https://element-plus.org/en-US/component/config-provider) 让我们以 unpkg 为例：

html

```
<script src="//unpkg.com/element-plus/dist/locale/zh-cn"></script>
<script>
  app.use(ElementPlus, {
    locale: ElementPlusLocaleZhCn,
  })
</script>
```

关于完整文档，请参阅： [ConfigProvider](https://element-plus.org/zh-CN/component/config-provider)

[支持的语言列表](https://github.com/element-plus/element-plus/tree/dev/packages/locale/lang)

-   简体中文（zh-cn）
-   美国英语（en）
-   阿塞拜疆语（az）
-   德语（de）
-   葡萄牙语（pt）
-   西班牙语（es）
-   丹麦语（da）
-   法语（fr）
-   挪威语（nb-NO）
-   繁体中文（zh-tw）
-   意大利语（it）
-   韩语（ko）
-   日语（ja）
-   荷兰语（nl）
-   越南语（vi）
-   俄语（ru）
-   土耳其语（tr）
-   巴西葡萄牙语（pt-br）
-   波斯语（fa）
-   泰语（th）
-   印度尼西亚语（id）
-   保加利亚语（bg）
-   普什图语（pa）
-   波兰语（pl）
-   芬兰语（fi）
-   瑞典语（sv）
-   希腊语（el）
-   斯洛伐克语（sk）
-   加泰罗尼亚语（ca）
-   捷克语（cs）
-   乌克兰语（uk）
-   土库曼语（tk）
-   泰米尔语（ta）
-   拉脱维亚语（lv）
-   南非荷兰语（af）
-   爱沙尼亚语（et）
-   斯洛文尼亚语（sl）
-   阿拉伯语（ar）
-   希伯来语（he）
-   老挝语 (lo)
-   立陶宛语（lt）
-   蒙古语（mn）
-   哈萨克语（kk）
-   匈牙利语（hu）
-   罗马尼亚语（ro）
-   库尔德语（ku）
-   库尔德语 (ckb)
-   维吾尔语 (ug-cn)
-   高棉语 (km)
-   塞尔维亚语 (sr)
-   巴斯克语 (eu)
-   吉尔吉斯语 (ky)
-   亚美尼亚语 (hy-am)
-   克罗地亚语（hr）
-   世界语 (eo)
-   孟加拉语 (bn)
-   马来语 (ms)
-   马达加斯加 (mg)
-   斯瓦希里语(sw)
-   乌兹别克语 (uz-uz)
-   埃及阿拉伯语 (ar-eg)
-   缅甸语 (my)
-   印地语 (hi)
-   挪威语 (no)
-   中国香港 (zh-hk)
-   中国澳门 (zh-mo)
-   泰卢固语 (te)

如果你需要其他语言，欢迎提交 [PR](https://github.com/element-plus/element-plus/pulls)。 你只需要在 [这里](https://github.com/element-plus/element-plus/tree/dev/packages/locale/lang) 添加一个语言文件即可。

[快速开始](https://element-plus.org/zh-CN/guide/quickstart)

[从 Element UI 升级](https://element-plus.org/zh-CN/guide/migration)




---
## [guide/migration] 从 Element UI 升级
> 官方文档: https://element-plus.org/zh-CN/guide/migration.html

---

# 迁移 [​](#迁移)

[此指南](https://github.com/element-plus/element-plus/discussions/5658) 将帮助您从 Element Ui 2.x 升级到 Element Plus。

## Vue 3 迁移构建 [​](#vue-3-迁移构建)

使用 Element Plus 与 Vue 3 迁移构建时可能遇到一些问题。 有些组件依赖于 Vue 3 内部 API。 [尝试将全局组件或将你项目中每个组件的版本调整为3](https://v3-migration.vuejs.org/migration-build.html) 。

## 迁移工具 🛠️ [​](#迁移工具)

我们已经为您提供了一个迁移工具，可以将您的项目从 [Element UI](https://element.eleme.io/) 迁移到 Element Plus。 您可以在 [这里](https://github.com/thx/gogocode/tree/main/packages/gogocode-plugin-element) 找到 gogo code 迁移工具。

我们已经在 [Vue Element Admin](https://github.com/PanJiaChen/vue-element-admin) (Vue 2 + Element UI) 上测试了此工具。 您可以在 [这里](https://github.com/gogocodeio/vue-element-admin) 找到可移植代码。

[国际化](https://element-plus.org/zh-CN/guide/i18n)

[主题](https://element-plus.org/zh-CN/guide/theming)




---
## [guide/theming] 主题指南
> 官方文档: https://element-plus.org/zh-CN/guide/theming.html

---

# 自定义主题 [​](#自定义主题)

Element Plus 默认提供一套主题，CSS 命名采用 BEM 的风格，方便使用者覆盖样式。 但是如果需要大规模替换样式，例如： 将主题颜色从蓝色改为橙色或绿色，也许一个个将其覆盖起来不是一个好主意。

我们提供四种方法来改变样式变量。

## 更换主题色 [​](#更换主题色)

以下是自定义主题的一些例子。

-   全部导入：[element-plus-vite-starter](https://github.com/element-plus/element-plus-vite-starter)
-   按需导入：[unplugin-element-plus/examples/vite](https://github.com/element-plus/unplugin-element-plus)

### 通过 SCSS 变量 [​](#通过-scss-变量)

`theme-chalk` 使用SCSS编写而成。 你可以在 [`packages/theme-chalk/src/common/var.scss`](https://github.com/element-plus/element-plus/blob/dev/packages/theme-chalk/src/common/var.scss) 文件中查找SCSS变量。

WARNING

我们使用 sass 模块（[sass:map](https://sass-lang.com/documentation/values/maps)...）和 `@use` 来重构所有的 SCSS 变量。 通过对所有 SCSS 变量使用 `@use`，解决了由 `@import` 造成的重复输出问题。

> [介绍Sass 模块 | CSS-TRICKS](https://css-tricks.com/introducing-sass-modules/)

例如，我们使用 `$colors` 作为 map 来保存不同类型的颜色。

`$notification` 是所有 `notification` 组件的变量的映射。

今后，我们将为每个组件自定义的变量编写文档。 你也可以直接查看源代码 [var.scss](https://github.com/element-plus/element-plus/blob/dev/packages/theme-chalk/src/common/var.scss)。

scss

```
$colors: () !default;
$colors: map.deep-merge(
  (
    'white': #ffffff,
    'black': #000000,
    'primary': (
      'base': #409eff,
    ),
    'success': (
      'base': #67c23a,
    ),
    'warning': (
      'base': #e6a23c,
    ),
    'danger': (
      'base': #f56c6c,
    ),
    'error': (
      'base': #f56c6c,
    ),
    'info': (
      'base': #909399,
    ),
  ),
  $colors
);
```

### 如何覆盖它？ [​](#如何覆盖它)

如果您的项目也使用了 SCSS，可以直接修改 Element Plus 的样式变量。 新建一个样式文件，例如 `styles/element/index.scss`：

WARNING

您应该使用 `@use 'xxx.scss' as *;` 代替 `@import 'xxx.scss';`。

因为 sass 团队说他们最终会删除 `@import` 语法。

> [Sass: @use](https://sass-lang.com/documentation/at-rules/use) vs [Sass: @import](https://sass-lang.com/documentation/at-rules/import)

styles/element/index.scss

scss

```
/* just override what you need */
@forward 'element-plus/theme-chalk/src/common/var.scss' with (
  $colors: (
    'primary': (
      'base': green,
    ),
  )
);

// If you just import on demand, you can ignore the following content.
// 如果你想导入所有样式:
// @use "element-plus/theme-chalk/src/index.scss" as *;
```

然后在你的项目入口文件中，导入这个样式文件以替换 Element Plus 内置的 CSS：

TIP

在 element-plus scss 文件之前导入`element/index.scss`以避免 sass 混合变量的问题，因为我们需要通过你的自定义变量生成 light-x。

创建一个 `element/index.scss` 文件来合并你的变量和 element-plus 的变量。 （如果你在 TypeScript 中导入了它们，他们将不会被合并）

TIP

除此以外，你应该将你的 scss 文件与 element 变量的 scss 文件区分开来。 如果将它们混合在一起，`element-plus` 每次热更新都需要编译大量的 scss 文件，这将会导致编译速度变慢。

main.ts

ts

```
import { createApp } from 'vue'
import './styles/element/index.scss'
import ElementPlus from 'element-plus'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus)
```

如果你正在使用vite，并且你想在按需导入时自定义主题。

使用 `scss.additionalData` 来编译所有应用 scss 变量的组件。

vite.config.ts

ts

```
import path from 'path'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
// 也可以使用 unplugin-vue-components
// import Components from 'unplugin-vue-components/vite'
// import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
// 或使用 unplugin-element-plus
import ElementPlus from 'unplugin-element-plus/vite'

export default defineConfig({
  resolve: {
    alias: {
      '~/': `${path.resolve(__dirname, 'src')}/`,
    },
  },
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "~/styles/element/index.scss" as *;`,
      },
    },
  },
  plugins: [
    vue(),
    // 使用 unplugin-vue-components
    // Components({
    //   resolvers: [
    //     ElementPlusResolver({
    //       importStyle: "sass",
    //       // directives: true,
    //       // version: "2.1.5",
    //     }),
    //   ],
    // }),
    // 或使用 unplugin-element-plus
    ElementPlus({
      useSource: true,
    }),
  ],
})
```

如果您正在使用 webpack，并且需要在按需导入时自定义主题。

webpack.config.js

js

```
// 使用 unplugin-element-plus

import ElementPlus from 'unplugin-element-plus/webpack'

export default defineConfig({
  css: {
    loaderOptions: {
      scss: {
        additionalData: `@use "~/styles/element/index.scss" as *;`,
      },
    },
  },
  plugins: [
    ElementPlus({
      useSource: true,
    }),
  ],
})
```

### 通过 CSS 变量设置 [​](#通过-css-变量设置)

CSS 变量是一个非常有用的功能，几乎所有浏览器都支持。 （IE：啊这？)

> 从 [使用CSS自定义属性(变量) | MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) 了解更多信息

我们用 css 变量来重构了几乎所有组件的样式系统。

TIP

它兼容 SCSS 变量系统。 我们使用 SCSS 的函数自动生成需要用到的 css 变量。

这意味着你可以动态地改变组件内的个别变量，以便更好地自定义组件样式，而不需要修改 SCSS 文件重新编译一次。

> 之后，每个组件的 css 变量名称和作用将被写入到对应的组件文档中。

就像这样：

css

```
:root {
  --el-color-primary: green;
}
```

如果你只想自定义一个特定的组件，只需为某些组件单独添加内联样式。

html

```
<el-tag style="--el-tag-bg-color: red">Tag</el-tag>
```

出于性能原因，更加推荐你在类名下添加自定义 css 变量，而不是在全局的 `:root` 下。

css

```
.custom-class {
  --el-tag-bg-color: red;
}
```

如果您想要通过 js 控制 css 变量，可以这样做：

ts

```
// document.documentElement 是全局变量时
const el = document.documentElement
// const el = document.getElementById('xxx')

// 获取 css 变量
getComputedStyle(el).getPropertyValue(`--el-color-primary`)

// 设置 css 变量
el.style.setProperty('--el-color-primary', 'red')
```

如果你想要更优雅的方式，请看这里。 [useCssVar | VueUse](https://vueuse.org/core/usecssvar/)

[从 Element UI 升级](https://element-plus.org/zh-CN/guide/migration)

[暗黑模式](https://element-plus.org/zh-CN/guide/dark-mode)




---
## [guide/dark-mode] 暗黑模式指南
> 官方文档: https://element-plus.org/zh-CN/guide/dark-mode.html

---

# 暗黑模式 2.2.0 [​](#暗黑模式)

现在，Element Plus 终于支持了暗黑模式！

我们提取并整理了所有的设计变量，并通过 CSS Vars 技术实现动态更新主题。

## 如何启用？ [​](#如何启用)

首先你可以创建一个开关来控制 `暗黑模式` 的 class 类名。

> 如果您只需要暗色模式，只需在 html 上添加一个名为 `dark` 的类 。

html

```
<html class="dark">
  <head></head>
  <body></body>
</html>
```

> 如果您想动态切换，建议使用 [useDark | VueUse](https://vueuse.org/core/useDark/)。

只需要如下在项目入口文件修改一行代码：

main.ts

ts

```
// if you just want to import css
import 'element-plus/theme-chalk/dark/css-vars.css'
```

> 也可以参考我们提供的 [element-plus-vite-starter 模版](https://github.com/element-plus/element-plus-vite-starter) 例子。

## 自定义变量 [​](#自定义变量)

### 通过 CSS [​](#通过-css)

直接覆盖对应的 css 变量即可

像这样，新建一个 `styles/dark/css-vars.css`文件:

css

```
html.dark {
  /* 自定义深色背景颜色 */
  --el-bg-color: #626aef;
}
```

在 Element Plus 的样式之后导入它

main.ts

ts

```
import 'element-plus/theme-chalk/dark/css-vars.css'
import './styles/dark/css-vars.css'
```

### 通过 SCSS [​](#通过-scss)

如果您使用 scss，您也可以导入 scss 文件来实现一样的效果

> 您可以参考 [自定义主题](https://element-plus.org/zh-CN/guide/theming) 获取更多信息。

styles/element/index.scss

scss

```
/*just override what you need*/
@forward 'element-plus/theme-chalk/src/dark/var.scss' with (
  $bg-color: (
    'page': #0a0a0a,
    '': #626aef,
    'overlay': #1d1e1f,
  )
);
```

main.ts

ts

```
import './styles/element/index.scss'

// or just want to import scss?
// import 'element-plus/theme-chalk/src/dark/css-vars.scss'
```

[主题](https://element-plus.org/zh-CN/guide/theming)

[自定义命名空间](https://element-plus.org/zh-CN/guide/namespace)




---
## [guide/namespace] 自定义命名空间
> 官方文档: https://element-plus.org/zh-CN/guide/namespace.html

---

## 自定义命名空间 2.2.0 [​](#自定义命名空间)

TIP

我们提供了 [element-plus-vite-starter 模版](https://github.com/element-plus/element-plus-vite-starter)。 查看代码了解使用方法。

Element Plus 提供的默认命名空间为 `el`。 在特殊情况下，我们需要自定义命名空间。

由于我们使用 sass 书写样式，如果您需要自定义所有命名空间， 我们假定用户使用了 sass 书写样式。

您必须同时设置 `ElConfigProvider` 和 scss `$namespace`。

### 设置 `ElConfigProvider` [​](#设置-elconfigprovider)

使用 `ElConfigProvider` 包装您的根组件。

App.vue

vue

```
<template>
  <el-config-provider namespace="ep">
    <!-- ... -->
  </el-config-provider>
</template>
```

### 设置 SCSS 和 CSS 变量 [​](#设置-scss-和-css-变量)

创建 `styles/element/index.scss`：

styles/element/index.scss

scss

```
// we can add this to custom namespace, default is 'el'
@forward 'element-plus/theme-chalk/src/mixins/config.scss' with (
  $namespace: 'ep'
);
// ...
```

在 `vite.config.ts` 中导入 `styles/element/index.scss`：

> Webpack也是如此，它需要在 `preprocessorOptions` 中设置。

vite.config.ts

ts

```
import { defineConfig } from 'vite'
// https://vitejs.dev/config/
export default defineConfig({
  // ...
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "~/styles/element/index.scss" as *;`,
      },
    },
  },
  // ...
})
```

就这么简单。

[暗黑模式](https://element-plus.org/zh-CN/guide/dark-mode)

[自定义默认值](https://element-plus.org/zh-CN/guide/custom-defaults)




---
## [guide/custom-defaults] 自定义默认值
> 官方文档: https://element-plus.org/zh-CN/guide/custom-defaults.html

---

# 自定义默认值 [​](#自定义默认值)

组件库允许您自定义组件属性的默认值。

通过提前配置默认值，您可以减少重复的prop声明并保持模板更干净和更一致。

## 基础用法 [​](#基础用法)

您可以使用组件提供的静态`setPropsDefaults`方法自定义组件的属性默认值。

TIP

请注意，默认自定义**仅适用于声明式组件** 并且 **必须在组件初始化之前执行**。

配置的默认值是全局的。 一旦设置，它们将应用于注册了该组件的所有Vue应用程序。

组件首次渲染后，其默认值将变为不可变，无法再更改。

main.ts

ts

```
import { ElButton } from 'element-plus'

ElButton.setPropsDefaults({
  type: 'primary',
  size: 'small',
})
```

应用自定义设置后，以下两种用法等效：

App.vue

vue

```
<template>
  <el-button>Hello</el-button>
  <el-button type="primary" size="small">Hello</el-button>
</template>
```

WARNING

不建议为其他组件内部使用的组件设置默认值。

例如：

ts

```
// 这将导致 el-autocomplete 组件的行为发生改变。
ElInput.setPropsDefaults({ maxlength: 1 })
```

[自定义命名空间](https://element-plus.org/zh-CN/guide/namespace)

[SSR](https://element-plus.org/zh-CN/guide/ssr)




---
## [guide/ssr] SSR 指南
> 官方文档: https://element-plus.org/zh-CN/guide/ssr.html

---

# 服务端渲染 (SSR) [​](#服务端渲染-ssr)

当使用 Element Plus 在 SSR 场景下开发时，您需要在 SSR 期间进行特殊处理，以避免水合错误。

TIP

对于Nuxt 用户，我们提供的 [Nuxt 模块](https://github.com/element-plus/element-plus-nuxt) 已经包含了对这些问题的处理方案。 您只需要安装它就可以了。

## 提供一个ID [​](#提供一个id)

提供的值用于生成 ElementPlus 中的唯一ID。 因为不同的 IDs 容易发生SSR中的水合率错误， 为了确保服务器端和客户端生成相同的ID， 我们需要将 `ID_injection_key` 注入到 Vue。

main.ts

ts

```
// irrelevant code omitted
import { createApp } from 'vue'
import { ID_INJECTION_KEY } from 'element-plus'
import App from './App.vue'

const app = createApp(App)
app.provide(ID_INJECTION_KEY, {
  prefix: 1024,
  current: 0,
})
```

## 配置 ZIndex [​](#配置-zindex)

当您使用SSR进行开发时，您可能会遇到 `z-index` 引起的水合错误。 在这种情况下，我们建议注入一个初始值以避免这种错误。

main.ts

ts

```
// irrelevant code omitted
import { createApp } from 'vue'
import { ZINDEX_INJECTION_KEY } from 'element-plus'
import App from './App.vue'

const app = createApp(App)
app.provide(ZINDEX_INJECTION_KEY, { current: 0 })
```

## Teleports [​](#teleports)

[Teleport](https://vuejs.org/guide/scaling-up/ssr.html#teleports) 被元素加元件中的多个组件内部使用 (例如) ElDialog, ElDrawer, ElTooltip, ElDropdown, ElSelect, ElDatePicker ...)，所以在SSR期间需要特殊处理。

### 在挂载时渲染 Teleport [​](#在挂载时渲染-teleport)

一个较容易的解决办法是有条件渲染挂载上的 Teleport 。

例如，在Nuxt中使用 `ClientOnly` 这个组件。

html

```
<client-only>
  <el-tooltip content="the tooltip content">
    <el-button>tooltip</el-button>
  </el-tooltip>
</client-only>
```

或

vue

```
<script setup>
import { ref } from 'vue'

const isClient = ref(false)

onMounted(() => {
  isClient.value = true
})
</script>

<template>
  <el-tooltip v-if="isClient" content="the tooltip content">
    <el-button>tooltip</el-button>
  </el-tooltip>
</template>
```

### 注入 Teleport 标记 [​](#注入-teleport-标记)

另一种方式是将传送标记注入到你的 HTML 页面末尾的正确位置。

您需要注入靠近 `<body>` 标签的传送标记。

html

```
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Element Plus</title>
    <!--preload-links-->
  </head>
  <body>
    <!--app-teleports-->
    <div id="app"><!--app-html--></div>
    <script type="module" src="/src/entry-client.js"></script>
  </body>
</html>
```

TIP

如果您修改了 [Namespace](https://element-plus.org/zh-CN/guide/namespace) 或 `append-to` 属性，您需要调整 `#el-popper-container-` 值。

src/entry-server.js

js

```
// irrelevant code omitted
import { renderToString } from 'vue/server-renderer'
import { createApp } from './main'

export async function render(url, manifest) {
  // ...
  const ctx = {}
  const html = await renderToString(app, ctx)
  const preloadLinks = renderPreloadLinks(ctx.modules, manifest)
  const teleports = renderTeleports(ctx.teleports)

  return [html, preloadLinks, teleports]
}

function renderTeleports(teleports) {
  if (!teleports) return ''
  return Object.entries(teleports).reduce((all, [key, value]) => {
    if (key.startsWith('#el-popper-container-')) {
      return `${all}<div id="${key.slice(1)}">${value}</div>`
    }
    return all
  }, teleports.body || '')
}
```

server.js or prerender.js

js

```
// irrelevant code omitted
const [appHtml, preloadLinks, teleports] = await render(url, manifest)

const html = template
  .replace('<!--preload-links-->', preloadLinks)
  .replace('<!--app-html-->', appHtml)
  .replace(/(\n|\r\n)\s*<!--app-teleports-->/, teleports)
```

[自定义默认值](https://element-plus.org/zh-CN/guide/custom-defaults)

[内置过渡动画](https://element-plus.org/zh-CN/guide/transitions)




---
## [guide/transitions] 内置过渡动画
> 官方文档: https://element-plus.org/zh-CN/guide/transitions.html

---

# 内置过渡动画 [​](#内置过渡动画)

Element Plus 内应用在部分组件的过渡动画，你也可以直接使用。 在使用之前，请阅读 [官方的过渡组件文档](https://vuejs.org/guide/built-ins/transition.html)。

## Fade 淡入淡出 [​](#fade-淡入淡出)

提供 `el-fade-in-linear` 和 `el-fade-in` 两种效果。

Click Me

.el-fade-in-linear

.el-fade-in

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1idXR0b24gQGNsaWNrPVwic2hvdyA9ICFzaG93XCI+Q2xpY2sgTWU8L2VsLWJ1dHRvbj5cblxuICAgIDxkaXYgY2xhc3M9XCJmYWRlLWNvbnRhaW5lclwiPlxuICAgICAgPHRyYW5zaXRpb24gbmFtZT1cImVsLWZhZGUtaW4tbGluZWFyXCI+XG4gICAgICAgIDxkaXYgdi1zaG93PVwic2hvd1wiIGNsYXNzPVwidHJhbnNpdGlvbi1ib3hcIj4uZWwtZmFkZS1pbi1saW5lYXI8L2Rpdj5cbiAgICAgIDwvdHJhbnNpdGlvbj5cbiAgICAgIDx0cmFuc2l0aW9uIG5hbWU9XCJlbC1mYWRlLWluXCI+XG4gICAgICAgIDxkaXYgdi1zaG93PVwic2hvd1wiIGNsYXNzPVwidHJhbnNpdGlvbi1ib3hcIj4uZWwtZmFkZS1pbjwvZGl2PlxuICAgICAgPC90cmFuc2l0aW9uPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHNob3cgPSByZWYodHJ1ZSlcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmZhZGUtY29udGFpbmVyIHtcbiAgZGlzcGxheTogZmxleDtcbiAgZmxleC13cmFwOiB3cmFwO1xuICBnYXA6IDE2cHg7XG4gIG1pbi1oZWlnaHQ6IDEwMHB4O1xuICBtYXJnaW4tdG9wOiAyMHB4O1xufVxuXG4udHJhbnNpdGlvbi1ib3gge1xuICB3aWR0aDogMjAwcHg7XG4gIGhlaWdodDogMTAwcHg7XG4gIGJvcmRlci1yYWRpdXM6IHZhcigtLWVsLWJvcmRlci1yYWRpdXMtYmFzZSk7XG4gIGJhY2tncm91bmQtY29sb3I6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG4gIGNvbG9yOiAjZmZmO1xuICBwYWRkaW5nOiA0MHB4IDIwcHg7XG4gIGJveC1zaXppbmc6IGJvcmRlci1ib3g7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/transitions/fade.vue)_

vue

```
<template>
  <div>
    <el-button @click="show = !show">Click Me</el-button>

    <div class="fade-container">
      <transition name="el-fade-in-linear">
        <div v-show="show" class="transition-box">.el-fade-in-linear</div>
      </transition>
      <transition name="el-fade-in">
        <div v-show="show" class="transition-box">.el-fade-in</div>
      </transition>
    </div>
  </div>
</template>

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

const show = ref(true)
</script>

<style scoped>
.fade-container {
  display: flex;
  flex-wrap: wrap;
  gap: 16px;
  min-height: 100px;
  margin-top: 20px;
}

.transition-box {
  width: 200px;
  height: 100px;
  border-radius: var(--el-border-radius-base);
  background-color: var(--el-color-primary);
  text-align: center;
  color: #fff;
  padding: 40px 20px;
  box-sizing: border-box;
}
</style>
```

隐藏源代码

## Zoom 缩放 [​](#zoom-缩放)

`el-zoom-in-left`, `el-zoom-in-center`, `el-zoom-in-top` and `el-zoom-in-bottom` are provided.

Click Me

.el-zoom-in-left

.el-zoom-in-center

.el-zoom-in-top

.el-zoom-in-bottom

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1idXR0b24gQGNsaWNrPVwic2hvdyA9ICFzaG93XCI+Q2xpY2sgTWU8L2VsLWJ1dHRvbj5cblxuICAgIDxkaXYgY2xhc3M9XCJ0cmFuc2l0aW9uLWNvbnRhaW5lclwiPlxuICAgICAgPHRyYW5zaXRpb24gbmFtZT1cImVsLXpvb20taW4tbGVmdFwiPlxuICAgICAgICA8ZGl2IHYtc2hvdz1cInNob3dcIiBjbGFzcz1cInRyYW5zaXRpb24tYm94XCI+LmVsLXpvb20taW4tbGVmdDwvZGl2PlxuICAgICAgPC90cmFuc2l0aW9uPlxuXG4gICAgICA8dHJhbnNpdGlvbiBuYW1lPVwiZWwtem9vbS1pbi1jZW50ZXJcIj5cbiAgICAgICAgPGRpdiB2LXNob3c9XCJzaG93XCIgY2xhc3M9XCJ0cmFuc2l0aW9uLWJveFwiPi5lbC16b29tLWluLWNlbnRlcjwvZGl2PlxuICAgICAgPC90cmFuc2l0aW9uPlxuXG4gICAgICA8dHJhbnNpdGlvbiBuYW1lPVwiZWwtem9vbS1pbi10b3BcIj5cbiAgICAgICAgPGRpdiB2LXNob3c9XCJzaG93XCIgY2xhc3M9XCJ0cmFuc2l0aW9uLWJveFwiPi5lbC16b29tLWluLXRvcDwvZGl2PlxuICAgICAgPC90cmFuc2l0aW9uPlxuXG4gICAgICA8dHJhbnNpdGlvbiBuYW1lPVwiZWwtem9vbS1pbi1ib3R0b21cIj5cbiAgICAgICAgPGRpdiB2LXNob3c9XCJzaG93XCIgY2xhc3M9XCJ0cmFuc2l0aW9uLWJveFwiPi5lbC16b29tLWluLWJvdHRvbTwvZGl2PlxuICAgICAgPC90cmFuc2l0aW9uPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHNob3cgPSByZWYodHJ1ZSlcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLnRyYW5zaXRpb24tY29udGFpbmVyIHtcbiAgZGlzcGxheTogZmxleDtcbiAgbWFyZ2luLXRvcDogMjBweDtcbiAgbWluLWhlaWdodDogMTAwcHg7XG4gIGZsZXgtd3JhcDogd3JhcDtcbiAgZ2FwOiAxNnB4O1xufVxuXG4udHJhbnNpdGlvbi1ib3gge1xuICB3aWR0aDogMjAwcHg7XG4gIGhlaWdodDogMTAwcHg7XG4gIGJvcmRlci1yYWRpdXM6IHZhcigtLWVsLWJvcmRlci1yYWRpdXMtYmFzZSk7XG4gIGJhY2tncm91bmQtY29sb3I6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG4gIGNvbG9yOiAjZmZmO1xuICBwYWRkaW5nOiAyMHB4O1xuICBib3gtc2l6aW5nOiBib3JkZXItYm94O1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBqdXN0aWZ5LWNvbnRlbnQ6IGNlbnRlcjtcbiAgd29yZC1icmVhazogYnJlYWstd29yZDtcbiAgZm9udC1zaXplOiAxNHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/transitions/zoom.vue)_

vue

```
<template>
  <div>
    <el-button @click="show = !show">Click Me</el-button>

    <div class="transition-container">
      <transition name="el-zoom-in-left">
        <div v-show="show" class="transition-box">.el-zoom-in-left</div>
      </transition>

      <transition name="el-zoom-in-center">
        <div v-show="show" class="transition-box">.el-zoom-in-center</div>
      </transition>

      <transition name="el-zoom-in-top">
        <div v-show="show" class="transition-box">.el-zoom-in-top</div>
      </transition>

      <transition name="el-zoom-in-bottom">
        <div v-show="show" class="transition-box">.el-zoom-in-bottom</div>
      </transition>
    </div>
  </div>
</template>

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

const show = ref(true)
</script>

<style scoped>
.transition-container {
  display: flex;
  margin-top: 20px;
  min-height: 100px;
  flex-wrap: wrap;
  gap: 16px;
}

.transition-box {
  width: 200px;
  height: 100px;
  border-radius: var(--el-border-radius-base);
  background-color: var(--el-color-primary);
  text-align: center;
  color: #fff;
  padding: 20px;
  box-sizing: border-box;
  display: flex;
  align-items: center;
  justify-content: center;
  word-break: break-word;
  font-size: 14px;
}
</style>
```

隐藏源代码

## Collapse 折叠面板 [​](#collapse-折叠面板)

使用 `el-collapse-transition` 组件实现折叠展开效果。

Click Me

el-collapse-transition

el-collapse-transition

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1idXR0b24gQGNsaWNrPVwic2hvdyA9ICFzaG93XCI+Q2xpY2sgTWU8L2VsLWJ1dHRvbj5cblxuICAgIDxkaXYgc3R5bGU9XCJtYXJnaW4tdG9wOiAyMHB4OyBoZWlnaHQ6IDIxMHB4XCI+XG4gICAgICA8ZWwtY29sbGFwc2UtdHJhbnNpdGlvbj5cbiAgICAgICAgPGRpdiB2LXNob3c9XCJzaG93XCI+XG4gICAgICAgICAgPGRpdiBjbGFzcz1cInRyYW5zaXRpb24tYm94XCI+ZWwtY29sbGFwc2UtdHJhbnNpdGlvbjwvZGl2PlxuICAgICAgICAgIDxkaXYgY2xhc3M9XCJ0cmFuc2l0aW9uLWJveCBtdC1bMTBweF1cIj5lbC1jb2xsYXBzZS10cmFuc2l0aW9uPC9kaXY+XG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jb2xsYXBzZS10cmFuc2l0aW9uPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHNob3cgPSByZWYodHJ1ZSlcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLnRyYW5zaXRpb24tYm94IHtcbiAgd2lkdGg6IDIwMHB4O1xuICBoZWlnaHQ6IDEwMHB4O1xuICBib3JkZXItcmFkaXVzOiB2YXIoLS1lbC1ib3JkZXItcmFkaXVzLWJhc2UpO1xuICBiYWNrZ3JvdW5kLWNvbG9yOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBjb2xvcjogI2ZmZjtcbiAgcGFkZGluZzogNDBweCAyMHB4O1xuICBib3gtc2l6aW5nOiBib3JkZXItYm94O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/transitions/collapse.vue)_

vue

```
<template>
  <div>
    <el-button @click="show = !show">Click Me</el-button>

    <div style="margin-top: 20px; height: 210px">
      <el-collapse-transition>
        <div v-show="show">
          <div class="transition-box">el-collapse-transition</div>
          <div class="transition-box mt-[10px]">el-collapse-transition</div>
        </div>
      </el-collapse-transition>
    </div>
  </div>
</template>

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

const show = ref(true)
</script>

<style scoped>
.transition-box {
  width: 200px;
  height: 100px;
  border-radius: var(--el-border-radius-base);
  background-color: var(--el-color-primary);
  text-align: center;
  color: #fff;
  padding: 40px 20px;
  box-sizing: border-box;
}
</style>
```

隐藏源代码

## 按需导入 [​](#按需导入)

main.ts

ts

```
// collapse
import { ElCollapseTransition } from 'element-plus'
// fade/zoom
import 'element-plus/theme-chalk/base.css'
import App from './App.vue'

const app = createApp(App)
app.component(ElCollapseTransition.name, ElCollapseTransition)
```

[SSR](https://element-plus.org/zh-CN/guide/ssr)

[更新日志](https://element-plus.org/zh-CN/guide/changelog)




---
## [guide/changelog] 更新日志
> 官方文档: https://element-plus.org/zh-CN/guide/changelog.html

---

# 更新日志 [​](#更新日志)

Element Plus 团队在正常情况下使用 **每周** 发布策略， 但关键的 bug 修复将需要热修复，所以实际发布版本 **可能** 每周超过 1 次。

在此页面上，您只能看到我们的 [更新日志](https://github.com/element-plus/element-plus/blob/dev/CHANGELOG.en-US.md) 最新的 30 条记录。

您可以查看 `2.5.0` 版本之后的 [升级变化](https://github.com/element-plus/element-plus/issues/15834)。

[内置过渡动画](https://element-plus.org/zh-CN/guide/transitions)

[开发指南](https://element-plus.org/zh-CN/guide/dev-guide)




---
## [guide/dev-guide] 开发指南
> 官方文档: https://element-plus.org/zh-CN/guide/dev-guide.html

---

# 本地开发 [​](#本地开发)

## 启动项目 [​](#启动项目)

使用命令

shell

```
pnpm i
```

该项目将安装所有依赖

## 网站预览 [​](#网站预览)

使用命令

shell

```
pnpm docs:dev
```

该项目将启动网站，网站内你可以预览全部现有组件

## 本地开发 [​](#本地开发-1)

查看 [本地开发指南](https://github.com/element-plus/element-plus/blob/dev/CONTRIBUTING.md)

1.  使用命令

shell

```
pnpm dev
```

将启动本地开发环境

2.  将你的组件添加到 `play/src/App.vue`

App.vue

vue

```
<template>
  <ComponentYouAreDeveloping />
</template>

<script setup lang="ts">
// make sure this component is registered in @element-plus/components
</script>
```

根据需要修改 `App.vue` 文件让开发过程顺利进行

## 以下命令在开发过程中也很有用 [​](#以下命令在开发过程中也很有用)

### 生成组件模板 [​](#生成组件模板)

使用命令

shell

```
pnpm gen <component-name>
# eg.
pnpm gen awesome
pnpm gen awesome-button
```

将在 `packages/components/awesome` 和 `packages/components/awesome-button` 目录下生成组件模板。

### 同步语言文件 [​](#同步语言文件)

使用命令

shell

```
pnpm locale:sync
```

将把 `en.ts` 语言文件中的新字段同步到其他语言文件，并添加注释 `// to be translated`。

[更新日志](https://element-plus.org/zh-CN/guide/changelog)

[开发常见问题](https://element-plus.org/zh-CN/guide/dev-faq)




---
## [guide/dev-faq] 开发常见问题
> 官方文档: https://element-plus.org/zh-CN/guide/dev-faq.html

---

# 开发常见问题 [​](#开发常见问题)

这里是开发方面容易遇到的问题

## 如果你遇到依赖相关问题 [​](#如果你遇到依赖相关问题)

shell

```
rm -rf node_modules
pnpm i
```

## 链接本地依赖 [​](#链接本地依赖)

shell

```
# 获取构建结果
pnpm build
cd dist/element-plus
# set cur element-plus to global `node_modules`
pnpm link --global
# for esm we also need link element-plus for dist
pnpm link --global element-plus

# 进入你的项目, 链接到 `element-plus`
cd your-project
pnpm link --global element-plus
```

> 更多信息查看 [pnpm link](https://pnpm.io/cli/link)

## 主题 [​](#主题)

我们不应在scss文件中写入中文注释

那将会在 vite 构建下的 css 文件开头生成警告信息 `@charset "UTF-8";`

> 更多信息见 [#3219](https://github.com/element-plus/element-plus/issues/3219)

[开发指南](https://element-plus.org/zh-CN/guide/dev-guide)

[提交示例](https://element-plus.org/zh-CN/guide/commit-examples)




---
## [guide/commit-examples] 提交示例
> 官方文档: https://element-plus.org/zh-CN/guide/commit-examples.html

---

# 提交示例 [​](#提交示例)

## 为什么存在这个章节? [​](#为什么存在这个章节)

详情请参阅 [通用惯例](https://www.conventionalcommits.org/)。

一个好的 Git 提交信息能够使我们：

1.  了解贡献者试图做什么
2.  自动生成更改日志

### 写入提交消息的规则 [​](#写入提交消息的规则)

md

```
# (如果通过, 当前提交会实现...) <subject> (最多 72 个字符)

# |<---- 使用最多 72 个字符 ---->|

# 解释清楚为什么要作出此修改

# |<---- 尝试将每一行控制在 72 个字符以内 ---->|

# 提供链接、相关标签关键词、文章或其他资源信息

# 使用issue和合并请求的全链接地址替代部分链接

# 因为它们在GitLab之外显示为纯文本

# --- 提交结束 ---

# --------------------

# 不要忘记

# 将主题行大写(英文标题)

# 主题行使用命令式语气

# 不要在主题行末尾带有一段时间

# 主题行至少包含 3 个单词

# 主题和空行之间使用空行隔开

# 当提交的更改行数超过30行或至少3个文件需要发生修改时

# 应在提交的主体信息中说明修改的详情

# 不要使用 Emojis 表情符号

# 在主体信息中解释提交的是什么内容, 为什么提交, 如何实现

# 每行以 "-" 开头, 写入多行可描述信息要点

# 详见: https://chris.beams.io/posts/git-commit/

# --------------------
```

### 提交消息的模板 [​](#提交消息的模板)

下面是供参考的模板提交消息。

md

```
feat(components): [button] 我用按钮实现了某些功能

主体行和主体内容之间用空白行隔开(可以有预期时间)
通过一行或多行描述你的修改信息
每一行的首字母大写
且每一行的总字符数限制在72个以内最优, 超过了将不易于他人理解

- 你也可以通过添加子项列表符号来为内容布局
```

主题标题的格式是：

```
[type](scope 域): [messages]
```

关于**type** 和 **scope**属性允许的值可以在 [commitlint.config.js](https://github.com/element-plus/element-plus/blob/c2ee36a7fc72b17742d43ecdff4e2912c416141d/commitlint.config.js#L57) 文件内查看

### 相关链接 [​](#相关链接)

[保持 git 提交历史简洁](https://about.gitlab.com/blog/2018/06/07/keeping-git-commit-history-clean/)

[开发常见问题](https://element-plus.org/zh-CN/guide/dev-faq)

[翻译](https://element-plus.org/zh-CN/guide/translation)




---
## [guide/translation] 翻译指南
> 官方文档: https://element-plus.org/zh-CN/guide/translation.html

---

# 翻译 [​](#翻译)

## 文档 [​](#文档)

在本章中，我们将讨论如何帮助翻译 Element Plus 开发文档。

### 背景 [​](#背景)

在给文档站做升级之前，每一次文档改动都需要改五种语言，大部分的贡献者都只会自己的母语和一门外语，大部分的贡献者也会寻求翻译器来翻译其它自己不熟悉的外语，而翻译器翻译的内容对母语者可能造成误解，并且对贡献者来说也是一件麻烦的事情。

所以我们决定把文档站做升级。

-   从 Webpack 升级到了 Vite
-   从手动维护的到自动化

我们采用了 [Crowdin](https://crowdin.com/) 作为自动化的第一步来升级文档站。

### 我怎么才能帮忙贡献翻译的内容？ [​](#我怎么才能帮忙贡献翻译的内容)

1.  在 [Crowdin](https://crowdin.com/) 上创建一个账号，推荐使用你的 GitHub 账号第三方登录。
2.  进入 [Element Plus](https://crowdin.com/project/element-plus) 项目。
3.  选择你想要贡献翻译的语言。
4.  选择你想要贡献翻译的具体文件。
5.  开始翻译。

这个过程很简单，Crowin 的用户界面也非常直观，还可以选择中文模式，你应该很容易就可以学会如何使用它。 当你提交完你的翻译之后，它会在翻译审核通过之后上线。

### 我怎么样能帮助翻译审核？ [​](#我怎么样能帮助翻译审核)

你可以通过在 Crowdin [发起 issue](https://crowdin.com/project/element-plus/discussions) 的方式通知我们，issue 内请告知你希望成为哪个语言的校对官。

[提交示例](https://element-plus.org/zh-CN/guide/commit-examples)




---
## [guide/resource] 资源
> 官方文档: https://element-plus.org/zh-CN/resource/index.html

---

# 资源

更多设计资源正在处于开发状态。

如果您有兴趣参与 Element Plus 的设计，请通过 [element-plus@outlook.com](mailto:element-plus@outlook.com) 联系我们。

### 2024 MasterGo UI Kit

在 MasterGo 中使用经过治理的 Element 组件库搭建设计系统，优化了自适应布局，组件状态更齐全，变体切换更符合开发习惯。

[下载](https://mastergo.com/community/resource/124855257836266)

### 2023 Figma UI Kit

使用 Figma 的最新变量能力的组件设计集合，提供了Light/Dark/Dark Alpha主题切换，帮助您快速搭建原型设计。

[下载](https://tatrck.com/h/0Hu30uVO121R?url=https%3A%2F%2Fwww.figma.com%2Fcommunity%2Ffile%2F1305760370797950824%2Felement-plus-design-system-ui-kit)

### 2023 Figma Variables

所有组件支持使用变量可以在普通模式和黑暗模式之间快速切换。

[下载](https://tatrck.com/h/0Hu30uVO121R?url=https%3A%2F%2Fwww.figma.com%2Fcommunity%2Ffile%2F1256091634199852065)

### 2022 Figma Template

2022年全新设计的 Figma 组件库，应用了自动布局与可变组件等新特性。

[下载](https://tatrck.com/h/0Hu30uVO121R?url=https%3A%2F%2Fwww.figma.com%2Fcommunity%2Ffile%2F1021254029764378306)

### 2022 Sketch Template

2022年全新设计的 Sketch 组件库，提供完整的组件支持。在提升设计效率的同时，保证统一的视觉风格。

[下载](https://github.com/ElementUI/Resources/raw/master/Element_Plus_Design_System_2022_1.0_Beta.zip)

### 2022 Axure Components

通过在 Axure 中导入 Element Plus 组件库，可以在交互设计阶段方便地调用常用的组件

[下载](https://github.com/ElementUI/Resources/raw/master/Element_Components_v2.1.0.rplib)

Released under the [MIT License](https://opensource.org/licenses/MIT).

Made with ❤️ by [Element Plus](https://github.com/element-plus)




---

<!-- ============================================ -->
<!-- 类别: 基础组件 -->
<!-- ============================================ -->

## [basic/button] Button 按钮
> 官方文档: https://element-plus.org/zh-CN/component/button.html

---

# Button 按钮 [​](#button-按钮)

更新日志待解决

18

常用的操作按钮。

## 基础用法 [​](#基础用法)

使用 `type`, `plain`, `round`, `dashed` 和 `circle` 来定义按钮的样式。

DefaultPrimarySuccessInfoWarningDanger

PlainPrimarySuccessInfoWarningDanger

RoundPrimarySuccessInfoWarningDanger

DashedPrimarySuccessInfoWarningDanger

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiYnV0dG9uLWV4YW1wbGVcIj5cbiAgICA8ZGl2IGNsYXNzPVwiYnV0dG9uLXJvd1wiPlxuICAgICAgPGVsLWJ1dHRvbj5EZWZhdWx0PC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCI+UHJpbWFyeTwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwic3VjY2Vzc1wiPlN1Y2Nlc3M8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cImluZm9cIj5JbmZvPC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJ3YXJuaW5nXCI+V2FybmluZzwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwiZGFuZ2VyXCI+RGFuZ2VyPC9lbC1idXR0b24+XG4gICAgPC9kaXY+XG5cbiAgICA8ZGl2IGNsYXNzPVwiYnV0dG9uLXJvd1wiPlxuICAgICAgPGVsLWJ1dHRvbiBwbGFpbj5QbGFpbjwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiIHBsYWluPlByaW1hcnk8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInN1Y2Nlc3NcIiBwbGFpbj5TdWNjZXNzPC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJpbmZvXCIgcGxhaW4+SW5mbzwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwid2FybmluZ1wiIHBsYWluPldhcm5pbmc8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cImRhbmdlclwiIHBsYWluPkRhbmdlcjwvZWwtYnV0dG9uPlxuICAgIDwvZGl2PlxuXG4gICAgPGRpdiBjbGFzcz1cImJ1dHRvbi1yb3dcIj5cbiAgICAgIDxlbC1idXR0b24gcm91bmQ+Um91bmQ8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiByb3VuZD5QcmltYXJ5PC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJzdWNjZXNzXCIgcm91bmQ+U3VjY2VzczwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwiaW5mb1wiIHJvdW5kPkluZm88L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cIndhcm5pbmdcIiByb3VuZD5XYXJuaW5nPC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJkYW5nZXJcIiByb3VuZD5EYW5nZXI8L2VsLWJ1dHRvbj5cbiAgICA8L2Rpdj5cblxuICAgIDxkaXYgY2xhc3M9XCJidXR0b24tcm93XCI+XG4gICAgICA8ZWwtYnV0dG9uIGRhc2hlZD5EYXNoZWQ8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBkYXNoZWQ+UHJpbWFyeTwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwic3VjY2Vzc1wiIGRhc2hlZD5TdWNjZXNzPC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJpbmZvXCIgZGFzaGVkPkluZm88L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cIndhcm5pbmdcIiBkYXNoZWQ+V2FybmluZzwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwiZGFuZ2VyXCIgZGFzaGVkPkRhbmdlcjwvZWwtYnV0dG9uPlxuICAgIDwvZGl2PlxuXG4gICAgPGRpdiBjbGFzcz1cImJ1dHRvbi1yb3dcIj5cbiAgICAgIDxlbC1idXR0b24gOmljb249XCJTZWFyY2hcIiBjaXJjbGUgLz5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiA6aWNvbj1cIkVkaXRcIiBjaXJjbGUgLz5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInN1Y2Nlc3NcIiA6aWNvbj1cIkNoZWNrXCIgY2lyY2xlIC8+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJpbmZvXCIgOmljb249XCJNZXNzYWdlXCIgY2lyY2xlIC8+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJ3YXJuaW5nXCIgOmljb249XCJTdGFyXCIgY2lyY2xlIC8+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJkYW5nZXJcIiA6aWNvbj1cIkRlbGV0ZVwiIGNpcmNsZSAvPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQge1xuICBDaGVjayxcbiAgRGVsZXRlLFxuICBFZGl0LFxuICBNZXNzYWdlLFxuICBTZWFyY2gsXG4gIFN0YXIsXG59IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uYnV0dG9uLWV4YW1wbGUge1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LWRpcmVjdGlvbjogY29sdW1uO1xuICBnYXA6IDFyZW07XG59XG5cbi5idXR0b24tcm93IHtcbiAgZGlzcGxheTogZmxleDtcbiAgZmxleC13cmFwOiB3cmFwO1xuICBnYXA6IDFyZW07XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG59XG5cbi5idXR0b24tcm93ID4gKiB7XG4gIG1hcmdpbjogMDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/button/basic.vue)_

vue

```
<template>
  <div class="button-example">
    <div class="button-row">
      <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="button-row">
      <el-button plain>Plain</el-button>
      <el-button type="primary" plain>Primary</el-button>
      <el-button type="success" plain>Success</el-button>
      <el-button type="info" plain>Info</el-button>
      <el-button type="warning" plain>Warning</el-button>
      <el-button type="danger" plain>Danger</el-button>
    </div>

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

    <div class="button-row">
      <el-button dashed>Dashed</el-button>
      <el-button type="primary" dashed>Primary</el-button>
      <el-button type="success" dashed>Success</el-button>
      <el-button type="info" dashed>Info</el-button>
      <el-button type="warning" dashed>Warning</el-button>
      <el-button type="danger" dashed>Danger</el-button>
    </div>

    <div class="button-row">
      <el-button :icon="Search" circle />
      <el-button type="primary" :icon="Edit" circle />
      <el-button type="success" :icon="Check" circle />
      <el-button type="info" :icon="Message" circle />
      <el-button type="warning" :icon="Star" circle />
      <el-button type="danger" :icon="Delete" circle />
    </div>
  </div>
</template>

<script lang="ts" setup>
import {
  Check,
  Delete,
  Edit,
  Message,
  Search,
  Star,
} from '@element-plus/icons-vue'
</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` 属性来控制按钮是否为禁用状态。 该属性接受一个 `Boolean` 类型的值。

DefaultPrimarySuccessInfoWarningDanger

PlainPrimarySuccessInfoWarningDanger

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiYnV0dG9uLWV4YW1wbGVcIj5cbiAgICA8ZGl2IGNsYXNzPVwiYnV0dG9uLXJvd1wiPlxuICAgICAgPGVsLWJ1dHRvbiBkaXNhYmxlZD5EZWZhdWx0PC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgZGlzYWJsZWQ+UHJpbWFyeTwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwic3VjY2Vzc1wiIGRpc2FibGVkPlN1Y2Nlc3M8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cImluZm9cIiBkaXNhYmxlZD5JbmZvPC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJ3YXJuaW5nXCIgZGlzYWJsZWQ+V2FybmluZzwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwiZGFuZ2VyXCIgZGlzYWJsZWQ+RGFuZ2VyPC9lbC1idXR0b24+XG4gICAgPC9kaXY+XG5cbiAgICA8ZGl2IGNsYXNzPVwiYnV0dG9uLXJvd1wiPlxuICAgICAgPGVsLWJ1dHRvbiBwbGFpbiBkaXNhYmxlZD5QbGFpbjwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiIHBsYWluIGRpc2FibGVkPlByaW1hcnk8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInN1Y2Nlc3NcIiBwbGFpbiBkaXNhYmxlZD5TdWNjZXNzPC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJpbmZvXCIgcGxhaW4gZGlzYWJsZWQ+SW5mbzwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwid2FybmluZ1wiIHBsYWluIGRpc2FibGVkPldhcm5pbmc8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cImRhbmdlclwiIHBsYWluIGRpc2FibGVkPkRhbmdlcjwvZWwtYnV0dG9uPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZSBzY29wZWQ+XG4uYnV0dG9uLWV4YW1wbGUge1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LWRpcmVjdGlvbjogY29sdW1uO1xuICBnYXA6IDFyZW07XG59XG5cbi5idXR0b24tcm93IHtcbiAgZGlzcGxheTogZmxleDtcbiAgZmxleC13cmFwOiB3cmFwO1xuICBnYXA6IDFyZW07XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG59XG5cbi5idXR0b24tcm93ID4gKiB7XG4gIG1hcmdpbjogMDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/button/disabled.vue)_

vue

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

    <div class="button-row">
      <el-button plain disabled>Plain</el-button>
      <el-button type="primary" plain disabled>Primary</el-button>
      <el-button type="success" plain disabled>Success</el-button>
      <el-button type="info" plain disabled>Info</el-button>
      <el-button type="warning" plain disabled>Warning</el-button>
      <el-button type="danger" plain disabled>Danger</el-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

plainprimarysuccessinfowarningdanger

Disabled link button

plainprimarysuccessinfowarningdanger

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8cD5CYXNpYyBsaW5rIGJ1dHRvbjwvcD5cbiAgPGRpdiBjbGFzcz1cIm1iLTRcIj5cbiAgICA8ZWwtYnV0dG9uXG4gICAgICB2LWZvcj1cImJ1dHRvbiBpbiBidXR0b25zXCJcbiAgICAgIDprZXk9XCJidXR0b24udGV4dFwiXG4gICAgICA6dHlwZT1cImJ1dHRvbi50eXBlXCJcbiAgICAgIGxpbmtcbiAgICA+XG4gICAgICB7eyBidXR0b24udGV4dCB9fVxuICAgIDwvZWwtYnV0dG9uPlxuICA8L2Rpdj5cblxuICA8cD5EaXNhYmxlZCBsaW5rIGJ1dHRvbjwvcD5cbiAgPGRpdj5cbiAgICA8ZWwtYnV0dG9uXG4gICAgICB2LWZvcj1cImJ1dHRvbiBpbiBidXR0b25zXCJcbiAgICAgIDprZXk9XCJidXR0b24udGV4dFwiXG4gICAgICA6dHlwZT1cImJ1dHRvbi50eXBlXCJcbiAgICAgIGxpbmtcbiAgICAgIGRpc2FibGVkXG4gICAgPlxuICAgICAge3sgYnV0dG9uLnRleHQgfX1cbiAgICA8L2VsLWJ1dHRvbj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuY29uc3QgYnV0dG9ucyA9IFtcbiAgeyB0eXBlOiAnJywgdGV4dDogJ3BsYWluJyB9LFxuICB7IHR5cGU6ICdwcmltYXJ5JywgdGV4dDogJ3ByaW1hcnknIH0sXG4gIHsgdHlwZTogJ3N1Y2Nlc3MnLCB0ZXh0OiAnc3VjY2VzcycgfSxcbiAgeyB0eXBlOiAnaW5mbycsIHRleHQ6ICdpbmZvJyB9LFxuICB7IHR5cGU6ICd3YXJuaW5nJywgdGV4dDogJ3dhcm5pbmcnIH0sXG4gIHsgdHlwZTogJ2RhbmdlcicsIHRleHQ6ICdkYW5nZXInIH0sXG5dIGFzIGNvbnN0XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/button/link.vue)_

vue

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

  <p>Disabled link button</p>
  <div>
    <el-button
      v-for="button in buttons"
      :key="button.text"
      :type="button.type"
      link
      disabled
    >
      {{ button.text }}
    </el-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

文字按钮在现在有了全新的设计样式。 2.2.0 如果您想要使用老版样式的按钮，可以考虑使用 [Link](https://element-plus.org/zh-CN/component/link#basic) 组件。

API也已更新，由于 `type` 属性会同时控制按钮的样式， 因此我们通过一个新的 API `text: boolean` 来控制文字按钮。

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

Basic text button

plainprimarysuccessinfowarningdanger

Background color always on

plainprimarysuccessinfowarningdanger

Disabled text button

plainprimarysuccessinfowarningdanger

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8cD5CYXNpYyB0ZXh0IGJ1dHRvbjwvcD5cbiAgPGRpdiBjbGFzcz1cIm1iLTRcIj5cbiAgICA8ZWwtYnV0dG9uXG4gICAgICB2LWZvcj1cImJ1dHRvbiBpbiBidXR0b25zXCJcbiAgICAgIDprZXk9XCJidXR0b24udGV4dFwiXG4gICAgICA6dHlwZT1cImJ1dHRvbi50eXBlXCJcbiAgICAgIHRleHRcbiAgICA+XG4gICAgICB7eyBidXR0b24udGV4dCB9fVxuICAgIDwvZWwtYnV0dG9uPlxuICA8L2Rpdj5cblxuICA8cD5CYWNrZ3JvdW5kIGNvbG9yIGFsd2F5cyBvbjwvcD5cbiAgPGRpdiBjbGFzcz1cIm1iLTRcIj5cbiAgICA8ZWwtYnV0dG9uXG4gICAgICB2LWZvcj1cImJ1dHRvbiBpbiBidXR0b25zXCJcbiAgICAgIDprZXk9XCJidXR0b24udGV4dFwiXG4gICAgICA6dHlwZT1cImJ1dHRvbi50eXBlXCJcbiAgICAgIHRleHRcbiAgICAgIGJnXG4gICAgPlxuICAgICAge3sgYnV0dG9uLnRleHQgfX1cbiAgICA8L2VsLWJ1dHRvbj5cbiAgPC9kaXY+XG5cbiAgPHA+RGlzYWJsZWQgdGV4dCBidXR0b248L3A+XG4gIDxkaXY+XG4gICAgPGVsLWJ1dHRvblxuICAgICAgdi1mb3I9XCJidXR0b24gaW4gYnV0dG9uc1wiXG4gICAgICA6a2V5PVwiYnV0dG9uLnRleHRcIlxuICAgICAgOnR5cGU9XCJidXR0b24udHlwZVwiXG4gICAgICB0ZXh0XG4gICAgICBkaXNhYmxlZFxuICAgID5cbiAgICAgIHt7IGJ1dHRvbi50ZXh0IH19XG4gICAgPC9lbC1idXR0b24+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmNvbnN0IGJ1dHRvbnMgPSBbXG4gIHsgdHlwZTogJycsIHRleHQ6ICdwbGFpbicgfSxcbiAgeyB0eXBlOiAncHJpbWFyeScsIHRleHQ6ICdwcmltYXJ5JyB9LFxuICB7IHR5cGU6ICdzdWNjZXNzJywgdGV4dDogJ3N1Y2Nlc3MnIH0sXG4gIHsgdHlwZTogJ2luZm8nLCB0ZXh0OiAnaW5mbycgfSxcbiAgeyB0eXBlOiAnd2FybmluZycsIHRleHQ6ICd3YXJuaW5nJyB9LFxuICB7IHR5cGU6ICdkYW5nZXInLCB0ZXh0OiAnZGFuZ2VyJyB9LFxuXSBhcyBjb25zdFxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/button/text.vue)_

vue

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

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

  <p>Disabled text button</p>
  <div>
    <el-button
      v-for="button in buttons"
      :key="button.text"
      :type="button.type"
      text
      disabled
    >
      {{ button.text }}
    </el-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` 属性来为按钮添加图标。 您可以在我们的 Icon 组件中找到所需图标。 通过向右方添加`<i>`标签来添加图标， 你也可以使用自定义图标。

Search Upload

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiA6aWNvbj1cIkVkaXRcIiAvPlxuICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiA6aWNvbj1cIlNoYXJlXCIgLz5cbiAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgOmljb249XCJEZWxldGVcIiAvPlxuICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiA6aWNvbj1cIlNlYXJjaFwiPlNlYXJjaDwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIj5cbiAgICAgIFVwbG9hZDxlbC1pY29uIGNsYXNzPVwiZWwtaWNvbi0tcmlnaHRcIj48VXBsb2FkIC8+PC9lbC1pY29uPlxuICAgIDwvZWwtYnV0dG9uPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+XG5pbXBvcnQgeyBEZWxldGUsIEVkaXQsIFNlYXJjaCwgU2hhcmUsIFVwbG9hZCB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/button/icon.vue)_

vue

```
<template>
  <div>
    <el-button type="primary" :icon="Edit" />
    <el-button type="primary" :icon="Share" />
    <el-button type="primary" :icon="Delete" />
    <el-button type="primary" :icon="Search">Search</el-button>
    <el-button type="primary">
      Upload<el-icon class="el-icon--right"><Upload /></el-icon>
    </el-button>
  </div>
</template>

<script setup lang="ts">
import { Delete, Edit, Search, Share, Upload } from '@element-plus/icons-vue'
</script>
```

隐藏源代码

## 按钮组 [​](#按钮组)

以按钮组的方式出现，常用于多项类似操作。

在 2.11.9 中，您可以使用 `direction` 属性。

使用 `<el-button-group>` 对多个按钮分组。

Previous Page Next Page

HorizontalVertical

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uLWdyb3VwIGNsYXNzPVwibWItNFwiPlxuICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiA6aWNvbj1cIkFycm93TGVmdFwiPlByZXZpb3VzIFBhZ2U8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCI+XG4gICAgICBOZXh0IFBhZ2U8ZWwtaWNvbiBjbGFzcz1cImVsLWljb24tLXJpZ2h0XCI+PEFycm93UmlnaHQgLz48L2VsLWljb24+XG4gICAgPC9lbC1idXR0b24+XG4gIDwvZWwtYnV0dG9uLWdyb3VwPlxuICA8YnIgLz5cbiAgPGVsLXJhZGlvLWdyb3VwIHYtbW9kZWw9XCJkaXJlY3Rpb25cIiBjbGFzcz1cIm1iLTJcIj5cbiAgICA8ZWwtcmFkaW8gdmFsdWU9XCJob3Jpem9udGFsXCI+SG9yaXpvbnRhbDwvZWwtcmFkaW8+XG4gICAgPGVsLXJhZGlvIHZhbHVlPVwidmVydGljYWxcIj5WZXJ0aWNhbDwvZWwtcmFkaW8+XG4gIDwvZWwtcmFkaW8tZ3JvdXA+XG4gIDxiciAvPlxuXG4gIDxlbC1idXR0b24tZ3JvdXAgOmRpcmVjdGlvbj1cImRpcmVjdGlvblwiPlxuICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiA6aWNvbj1cIkhvdXNlXCIgLz5cbiAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgOmljb249XCJPcGVyYXRpb25cIiAvPlxuICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiA6aWNvbj1cIk5vdGlmaWNhdGlvblwiIC8+XG4gIDwvZWwtYnV0dG9uLWdyb3VwPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7XG4gIEFycm93TGVmdCxcbiAgQXJyb3dSaWdodCxcbiAgSG91c2UsXG4gIE5vdGlmaWNhdGlvbixcbiAgT3BlcmF0aW9uLFxufSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgZGlyZWN0aW9uID0gcmVmPCdob3Jpem9udGFsJyB8ICd2ZXJ0aWNhbCc+KCdob3Jpem9udGFsJylcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/button/group.vue)_

vue

```
<template>
  <el-button-group class="mb-4">
    <el-button type="primary" :icon="ArrowLeft">Previous Page</el-button>
    <el-button type="primary">
      Next Page<el-icon class="el-icon--right"><ArrowRight /></el-icon>
    </el-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">
    <el-button type="primary" :icon="House" />
    <el-button type="primary" :icon="Operation" />
    <el-button type="primary" :icon="Notification" />
  </el-button-group>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import {
  ArrowLeft,
  ArrowRight,
  House,
  Notification,
  Operation,
} from '@element-plus/icons-vue'

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

隐藏源代码

## 加载状态按钮 [​](#加载状态按钮)

点击按钮来加载数据，并向用户反馈加载状态。

通过设置 `loading` 属性为 `true` 来显示加载中状态。

TIP

您可以使用 `loading` 插槽或 `loadingIcon`属性自定义您的loading图标

ps: `loading` 插槽优先级高于`loadingIcon`属性

LoadingLoading

Loading

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgbG9hZGluZz5Mb2FkaW5nPC9lbC1idXR0b24+XG4gIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiA6bG9hZGluZy1pY29uPVwiRWxlbWVcIiBsb2FkaW5nPkxvYWRpbmc8L2VsLWJ1dHRvbj5cbiAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiIGxvYWRpbmc+XG4gICAgPHRlbXBsYXRlICNsb2FkaW5nPlxuICAgICAgPGRpdiBjbGFzcz1cImN1c3RvbS1sb2FkaW5nXCI+XG4gICAgICAgIDxzdmcgY2xhc3M9XCJjaXJjdWxhclwiIHZpZXdCb3g9XCItMTAsIC0xMCwgNTAsIDUwXCI+XG4gICAgICAgICAgPHBhdGhcbiAgICAgICAgICAgIGNsYXNzPVwicGF0aFwiXG4gICAgICAgICAgICBkPVwiXG4gICAgICAgICAgICBNIDMwIDE1XG4gICAgICAgICAgICBMIDI4IDE3XG4gICAgICAgICAgICBNIDI1LjYxIDI1LjYxXG4gICAgICAgICAgICBBIDE1IDE1LCAwLCAwLCAxLCAxNSAzMFxuICAgICAgICAgICAgQSAxNSAxNSwgMCwgMSwgMSwgMjcuOTkgNy41XG4gICAgICAgICAgICBMIDE1IDE1XG4gICAgICAgICAgXCJcbiAgICAgICAgICAgIHN0eWxlPVwic3Ryb2tlLXdpZHRoOiA0cHg7IGZpbGw6IHJnYmEoMCwgMCwgMCwgMClcIlxuICAgICAgICAgIC8+XG4gICAgICAgIDwvc3ZnPlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgICBMb2FkaW5nXG4gIDwvZWwtYnV0dG9uPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IEVsZW1lIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5lbC1idXR0b24gLmN1c3RvbS1sb2FkaW5nIC5jaXJjdWxhciB7XG4gIG1hcmdpbi1yaWdodDogNnB4O1xuICB3aWR0aDogMThweDtcbiAgaGVpZ2h0OiAxOHB4O1xuICBhbmltYXRpb246IGxvYWRpbmctcm90YXRlIDJzIGxpbmVhciBpbmZpbml0ZTtcbn1cbi5lbC1idXR0b24gLmN1c3RvbS1sb2FkaW5nIC5jaXJjdWxhciAucGF0aCB7XG4gIGFuaW1hdGlvbjogbG9hZGluZy1kYXNoIDEuNXMgZWFzZS1pbi1vdXQgaW5maW5pdGU7XG4gIHN0cm9rZS1kYXNoYXJyYXk6IDkwLCAxNTA7XG4gIHN0cm9rZS1kYXNob2Zmc2V0OiAwO1xuICBzdHJva2Utd2lkdGg6IDI7XG4gIHN0cm9rZTogdmFyKC0tZWwtYnV0dG9uLXRleHQtY29sb3IpO1xuICBzdHJva2UtbGluZWNhcDogcm91bmQ7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/button/loading.vue)_

vue

```
<template>
  <el-button type="primary" loading>Loading</el-button>
  <el-button type="primary" :loading-icon="Eleme" loading>Loading</el-button>
  <el-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: rgba(0, 0, 0, 0)"
          />
        </svg>
      </div>
    </template>
    Loading
  </el-button>
</template>

<script lang="ts" setup>
import { Eleme } from '@element-plus/icons-vue'
</script>

<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(--el-button-text-color);
  stroke-linecap: round;
}
</style>
```

隐藏源代码

## 调整尺寸 [​](#调整尺寸)

除了默认的大小，按钮组件还提供了几种额外的尺寸可供选择，以便适配不同的场景。

使用 `size` 属性额外配置尺寸，可使用 `large`和`small`两种值。

LargeDefaultSmallSearchSearchSearch

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgaXRlbXMtY2VudGVyIG1iLTRcIj5cbiAgICA8ZWwtYnV0dG9uIHNpemU9XCJsYXJnZVwiPkxhcmdlPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbj5EZWZhdWx0PC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBzaXplPVwic21hbGxcIj5TbWFsbDwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gc2l6ZT1cImxhcmdlXCIgOmljb249XCJTZWFyY2hcIj5TZWFyY2g8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIDppY29uPVwiU2VhcmNoXCI+U2VhcmNoPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBzaXplPVwic21hbGxcIiA6aWNvbj1cIlNlYXJjaFwiPlNlYXJjaDwvZWwtYnV0dG9uPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cImZsZXggZmxleC13cmFwIGl0ZW1zLWNlbnRlciBtYi00XCI+XG4gICAgPGVsLWJ1dHRvbiBzaXplPVwibGFyZ2VcIiByb3VuZD5MYXJnZTwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gcm91bmQ+RGVmYXVsdDwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gc2l6ZT1cInNtYWxsXCIgcm91bmQ+U21hbGw8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIHNpemU9XCJsYXJnZVwiIDppY29uPVwiU2VhcmNoXCIgcm91bmQ+U2VhcmNoPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiA6aWNvbj1cIlNlYXJjaFwiIHJvdW5kPlNlYXJjaDwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gc2l6ZT1cInNtYWxsXCIgOmljb249XCJTZWFyY2hcIiByb3VuZD5TZWFyY2g8L2VsLWJ1dHRvbj5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJmbGV4IGZsZXgtd3JhcCBpdGVtcy1jZW50ZXJcIj5cbiAgICA8ZWwtYnV0dG9uIDppY29uPVwiU2VhcmNoXCIgc2l6ZT1cImxhcmdlXCIgY2lyY2xlIC8+XG4gICAgPGVsLWJ1dHRvbiA6aWNvbj1cIlNlYXJjaFwiIGNpcmNsZSAvPlxuICAgIDxlbC1idXR0b24gOmljb249XCJTZWFyY2hcIiBzaXplPVwic21hbGxcIiBjaXJjbGUgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgU2VhcmNoIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/button/size.vue)_

vue

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

<script setup lang="ts">
import { Search } from '@element-plus/icons-vue'
</script>
```

隐藏源代码

## Tag 2.3.4 [​](#tag)

您可以自定义元素标签。例如，按钮，div，路由链接，nuxt链接。

button

div

[a](https://github.com/element-plus/element-plus)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uPmJ1dHRvbjwvZWwtYnV0dG9uPlxuICA8ZWwtYnV0dG9uIHRhZz1cImRpdlwiIHJvbGU9XCJidXR0b25cIiB0YWJpbmRleD1cIjBcIj5kaXY8L2VsLWJ1dHRvbj5cbiAgPGVsLWJ1dHRvblxuICAgIHR5cGU9XCJwcmltYXJ5XCJcbiAgICB0YWc9XCJhXCJcbiAgICBocmVmPVwiaHR0cHM6Ly9naXRodWIuY29tL2VsZW1lbnQtcGx1cy9lbGVtZW50LXBsdXNcIlxuICAgIHRhcmdldD1cIl9ibGFua1wiXG4gICAgcmVsPVwibm9vcGVuZXIgbm9yZWZlcnJlclwiXG4gID5cbiAgICBhXG4gIDwvZWwtYnV0dG9uPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/button/tag.vue)_

vue

```
<template>
  <el-button>button</el-button>
  <el-button tag="div" role="button" tabindex="0">div</el-button>
  <el-button
    type="primary"
    tag="a"
    href="https://github.com/element-plus/element-plus"
    target="_blank"
    rel="noopener noreferrer"
  >
    a
  </el-button>
</template>
```

隐藏源代码

## 自定义颜色 beta [​](#自定义颜色)

您可以自定义按钮的颜色。

我们将自动计算按钮处于 hover 和 active 状态时的颜色。

自 2.13.7 起，`color` 属性也适用于 `link` 和 `text` 按钮。

DefaultPlainLinkTextText BGDisabled Disabled Plain Disabled Link Disabled Text Disabled Text BG

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IGlzRGFyayB9IGZyb20gJ34vY29tcG9zYWJsZXMvZGFyaydcbjwvc2NyaXB0PlxuXG48dGVtcGxhdGU+XG4gIDxkaXY+XG4gICAgPGVsLWJ1dHRvbiBjb2xvcj1cIiM2MjZhZWZcIiA6ZGFyaz1cImlzRGFya1wiPkRlZmF1bHQ8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNvbG9yPVwiIzYyNmFlZlwiIDpkYXJrPVwiaXNEYXJrXCIgcGxhaW4+UGxhaW48L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNvbG9yPVwiIzYyNmFlZlwiIDpkYXJrPVwiaXNEYXJrXCIgbGluaz5MaW5rPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjb2xvcj1cIiM2MjZhZWZcIiA6ZGFyaz1cImlzRGFya1wiIHRleHQ+VGV4dDwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gY29sb3I9XCIjNjI2YWVmXCIgOmRhcms9XCJpc0RhcmtcIiB0ZXh0IGJnPlRleHQgQkc8L2VsLWJ1dHRvbj5cblxuICAgIDxlbC1idXR0b24gY29sb3I9XCIjNjI2YWVmXCIgOmRhcms9XCJpc0RhcmtcIiBkaXNhYmxlZD5EaXNhYmxlZDwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gY29sb3I9XCIjNjI2YWVmXCIgOmRhcms9XCJpc0RhcmtcIiBkaXNhYmxlZCBwbGFpbj5cbiAgICAgIERpc2FibGVkIFBsYWluXG4gICAgPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjb2xvcj1cIiM2MjZhZWZcIiA6ZGFyaz1cImlzRGFya1wiIGRpc2FibGVkIGxpbms+XG4gICAgICBEaXNhYmxlZCBMaW5rXG4gICAgPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjb2xvcj1cIiM2MjZhZWZcIiA6ZGFyaz1cImlzRGFya1wiIGRpc2FibGVkIHRleHQ+XG4gICAgICBEaXNhYmxlZCBUZXh0XG4gICAgPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjb2xvcj1cIiM2MjZhZWZcIiA6ZGFyaz1cImlzRGFya1wiIGRpc2FibGVkIHRleHQgYmc+XG4gICAgICBEaXNhYmxlZCBUZXh0IEJHXG4gICAgPC9lbC1idXR0b24+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/button/custom.vue)_

vue

```
<script lang="ts" setup>
import { isDark } from '~/composables/dark'
</script>

<template>
  <div>
    <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>

    <el-button color="#626aef" :dark="isDark" disabled>Disabled</el-button>
    <el-button color="#626aef" :dark="isDark" disabled plain>
      Disabled Plain
    </el-button>
    <el-button color="#626aef" :dark="isDark" disabled link>
      Disabled Link
    </el-button>
    <el-button color="#626aef" :dark="isDark" disabled text>
      Disabled Text
    </el-button>
    <el-button color="#626aef" :dark="isDark" disabled text bg>
      Disabled Text BG
    </el-button>
  </div>
</template>
```

隐藏源代码

## Button API [​](#button-api)

### Button Attributes [​](#button-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| size | 尺寸 | `enum` | — |
| type | 按钮类型，在设置`color`时，后者优先。 | `enum` | — |
| plain | 是否为朴素按钮 | `boolean` | false |
| text 2.2.0 | 是否为文字按钮 | `boolean` | false |
| bg 2.2.0 | 是否显示文字按钮背景颜色 | `boolean` | false |
| link 2.2.1 | 是否为链接按钮 | `boolean` | false |
| round | 是否为圆角按钮 | `boolean` | false |
| circle | 是否为圆形按钮 | `boolean` | false |
| dashed 2.13.3 | 是否是虚线按钮 | `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` 触发后的颜色 自 2.13.7 起，支持 `link`/`text` 按钮。 | `string` | — |
| dark | dark 模式, 意味着自动设置 `color` 为 dark 模式的颜色 | `boolean` | false |
| tag 2.3.4 | 自定义元素标签 | `string` / `Component` | button |

### Button Slots [​](#button-slots)

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

### Button Exposes [​](#button-exposes)

| 属性名 | 说明 | 类型 |
| --- | --- | --- |
| ref | 按钮 html 元素 | `object` |
| size | 按钮尺寸 | `object` |
| type | 按钮类型 | `object` |
| disabled | 按钮已禁用 | `object` |
| shouldAddSpace | 是否在两个字符之间插入空格 | `object` |

## ButtonGroup API [​](#buttongroup-api)

### ButtonGroup Attributes [​](#buttongroup-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| size | 用于控制该按钮组内按钮的大小 | `enum` | — |
| type | 用于控制该按钮组内按钮的类型 | `enum` | — |
| direction 2.11.9 | 展示的方向 | `enum` | horizontal |

### ButtonGroup Slots [​](#buttongroup-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义按钮组内容 | Button |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/button) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/button.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/button.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/45122329?v=4&size=64)](https://github.com/cokemine)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/24487727?v=4&size=64)](https://github.com/LostElkByte)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/57352899?v=4&size=64)](https://github.com/VisualYuki)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/41461715?v=4&size=64)](https://github.com/VENI-VIDIVICI)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/30883395?v=4&size=64)](https://github.com/webvs2)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/109908413?v=4&size=64)](https://github.com/sleepyShen1989)[![](https://avatars.githubusercontent.com/u/73946940?v=4&size=64)](https://github.com/jiechen257)[![](https://avatars.githubusercontent.com/u/23433168?v=4&size=64)](https://github.com/hunter-fl)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/102006695?v=4&size=64)](https://github.com/cuongle-hdwebsoft)[![](https://avatars.githubusercontent.com/u/6948318?v=4&size=64)](https://github.com/dreambo8563)[![](https://avatars.githubusercontent.com/u/42372070?v=4&size=64)](https://github.com/Map1en)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/61005888?v=4&size=64)](https://github.com/kuizuo)[![](https://avatars.githubusercontent.com/u/4241620?v=4&size=64)](https://github.com/muhammadcahya)[![](https://avatars.githubusercontent.com/u/191817983?v=4&size=64)](https://github.com/zhuft-moon)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/145281501?v=4&size=64)](https://github.com/typed-sigterm)[![](https://avatars.githubusercontent.com/u/30796346?v=4&size=64)](https://github.com/lyh0371)

[Overview 组件总览](https://element-plus.org/zh-CN/component/overview)

[Border 边框](https://element-plus.org/zh-CN/component/border)




---
## [basic/border] Border 边框
> 官方文档: https://element-plus.org/zh-CN/component/border.html

---

# Border 边框 [​](#border-边框)

我们对边框进行统一规范，可用于按钮、卡片、弹窗等组件里。

## 边框样式 [​](#边框样式)

我们提供了以下几种边框样式，以供选择。

<table class="demo-border" data-v-fc2962eb=""><tbody data-v-fc2962eb=""><tr data-v-fc2962eb=""><td class="text" data-v-fc2962eb="">Name</td><td class="text" data-v-fc2962eb="">Thickness</td><td class="line" data-v-fc2962eb="">Demo</td></tr><tr data-v-fc2962eb=""><td class="text" data-v-fc2962eb="">Solid</td><td class="text" data-v-fc2962eb="">1px</td><td class="line" data-v-fc2962eb=""><div data-v-fc2962eb=""></div></td></tr><tr data-v-fc2962eb=""><td class="text" data-v-fc2962eb="">Dashed</td><td class="text" data-v-fc2962eb="">2px</td><td class="line" data-v-fc2962eb=""><div class="dashed" data-v-fc2962eb=""></div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8dGFibGUgY2xhc3M9XCJkZW1vLWJvcmRlclwiPlxuICAgIDx0Ym9keT5cbiAgICAgIDx0cj5cbiAgICAgICAgPHRkIGNsYXNzPVwidGV4dFwiPk5hbWU8L3RkPlxuICAgICAgICA8dGQgY2xhc3M9XCJ0ZXh0XCI+VGhpY2tuZXNzPC90ZD5cbiAgICAgICAgPHRkIGNsYXNzPVwibGluZVwiPkRlbW88L3RkPlxuICAgICAgPC90cj5cbiAgICAgIDx0cj5cbiAgICAgICAgPHRkIGNsYXNzPVwidGV4dFwiPlNvbGlkPC90ZD5cbiAgICAgICAgPHRkIGNsYXNzPVwidGV4dFwiPjFweDwvdGQ+XG4gICAgICAgIDx0ZCBjbGFzcz1cImxpbmVcIj5cbiAgICAgICAgICA8ZGl2IC8+XG4gICAgICAgIDwvdGQ+XG4gICAgICA8L3RyPlxuICAgICAgPHRyPlxuICAgICAgICA8dGQgY2xhc3M9XCJ0ZXh0XCI+RGFzaGVkPC90ZD5cbiAgICAgICAgPHRkIGNsYXNzPVwidGV4dFwiPjJweDwvdGQ+XG4gICAgICAgIDx0ZCBjbGFzcz1cImxpbmVcIj5cbiAgICAgICAgICA8ZGl2IGNsYXNzPVwiZGFzaGVkXCIgLz5cbiAgICAgICAgPC90ZD5cbiAgICAgIDwvdHI+XG4gICAgPC90Ym9keT5cbiAgPC90YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1ib3JkZXIgLnRleHQge1xuICB3aWR0aDogMTUlO1xufVxuLmRlbW8tYm9yZGVyIC5saW5lIHtcbiAgd2lkdGg6IDcwJTtcbn1cbi5kZW1vLWJvcmRlciAubGluZSBkaXYge1xuICB3aWR0aDogMTAwJTtcbiAgaGVpZ2h0OiAwO1xuICBib3JkZXItdG9wOiAxcHggc29saWQgdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbn1cbi5kZW1vLWJvcmRlciAubGluZSAuZGFzaGVkIHtcbiAgYm9yZGVyLXRvcDogMnB4IGRhc2hlZCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/border/border.vue)_

vue

```
<template>
  <table class="demo-border">
    <tbody>
      <tr>
        <td class="text">Name</td>
        <td class="text">Thickness</td>
        <td class="line">Demo</td>
      </tr>
      <tr>
        <td class="text">Solid</td>
        <td class="text">1px</td>
        <td class="line">
          <div />
        </td>
      </tr>
      <tr>
        <td class="text">Dashed</td>
        <td class="text">2px</td>
        <td class="line">
          <div class="dashed" />
        </td>
      </tr>
    </tbody>
  </table>
</template>

<style scoped>
.demo-border .text {
  width: 15%;
}
.demo-border .line {
  width: 70%;
}
.demo-border .line div {
  width: 100%;
  height: 0;
  border-top: 1px solid var(--el-border-color);
}
.demo-border .line .dashed {
  border-top: 2px dashed var(--el-border-color);
}
</style>
```

隐藏源代码

## 圆角 [​](#圆角)

我们提供了以下几种圆角样式，以供选择。

No Radius

`border-radius: "0px"`

Small Radius

`border-radius: 2px`

Large Radius

`border-radius: 4px`

Round Radius

`border-radius: 20px`

TS

JS

_[](https://element-plus.run/?extra_packages=%40vueuse%2Fcore#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IDpndXR0ZXI9XCIxMlwiIGNsYXNzPVwiZGVtby1yYWRpdXNcIj5cbiAgICA8ZWwtY29sXG4gICAgICB2LWZvcj1cIihyYWRpdXMsIGkpIGluIHJhZGl1c0dyb3VwXCJcbiAgICAgIDprZXk9XCJpXCJcbiAgICAgIDpzcGFuPVwiNlwiXG4gICAgICA6eHM9XCJ7IHNwYW46IDEyIH1cIlxuICAgID5cbiAgICAgIDxkaXYgY2xhc3M9XCJ0aXRsZVwiPnt7IHJhZGl1cy5uYW1lIH19PC9kaXY+XG4gICAgICA8ZGl2IGNsYXNzPVwidmFsdWVcIj5cbiAgICAgICAgPGNvZGU+XG4gICAgICAgICAgYm9yZGVyLXJhZGl1czpcbiAgICAgICAgICB7e1xuICAgICAgICAgICAgcmFkaXVzLnR5cGVcbiAgICAgICAgICAgICAgPyB1c2VDc3NWYXIoYC0tZWwtYm9yZGVyLXJhZGl1cy0ke3JhZGl1cy50eXBlfWApXG4gICAgICAgICAgICAgIDogJ1wiMHB4XCInXG4gICAgICAgICAgfX1cbiAgICAgICAgPC9jb2RlPlxuICAgICAgPC9kaXY+XG4gICAgICA8ZGl2XG4gICAgICAgIGNsYXNzPVwicmFkaXVzXCJcbiAgICAgICAgOnN0eWxlPVwie1xuICAgICAgICAgIGJvcmRlclJhZGl1czogcmFkaXVzLnR5cGVcbiAgICAgICAgICAgID8gYHZhcigtLWVsLWJvcmRlci1yYWRpdXMtJHtyYWRpdXMudHlwZX0pYFxuICAgICAgICAgICAgOiAnJyxcbiAgICAgICAgfVwiXG4gICAgICAvPlxuICAgIDwvZWwtY29sPlxuICA8L2VsLXJvdz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyB1c2VDc3NWYXIgfSBmcm9tICdAdnVldXNlL2NvcmUnXG5cbmNvbnN0IHJhZGl1c0dyb3VwID0gcmVmKFtcbiAge1xuICAgIG5hbWU6ICdObyBSYWRpdXMnLFxuICAgIHR5cGU6ICcnLFxuICB9LFxuICB7XG4gICAgbmFtZTogJ1NtYWxsIFJhZGl1cycsXG4gICAgdHlwZTogJ3NtYWxsJyxcbiAgfSxcbiAge1xuICAgIG5hbWU6ICdMYXJnZSBSYWRpdXMnLFxuICAgIHR5cGU6ICdiYXNlJyxcbiAgfSxcbiAge1xuICAgIG5hbWU6ICdSb3VuZCBSYWRpdXMnLFxuICAgIHR5cGU6ICdyb3VuZCcsXG4gIH0sXG5dKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1yYWRpdXMgLnRpdGxlIHtcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3ItcmVndWxhcik7XG4gIGZvbnQtc2l6ZTogMThweDtcbiAgbWFyZ2luOiAxMHB4IDA7XG59XG4uZGVtby1yYWRpdXMgLnZhbHVlIHtcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3ItcHJpbWFyeSk7XG4gIGZvbnQtc2l6ZTogMTZweDtcbiAgbWFyZ2luOiAxMHB4IDA7XG59XG4uZGVtby1yYWRpdXMgLnJhZGl1cyB7XG4gIGhlaWdodDogNDBweDtcbiAgd2lkdGg6IDcwJTtcbiAgYm9yZGVyOiAxcHggc29saWQgdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgYm9yZGVyLXJhZGl1czogMDtcbiAgbWFyZ2luLXRvcDogMjBweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/border/radius.vue)_

vue

```
<template>
  <el-row :gutter="12" class="demo-radius">
    <el-col
      v-for="(radius, i) in radiusGroup"
      :key="i"
      :span="6"
      :xs="{ span: 12 }"
    >
      <div class="title">{{ radius.name }}</div>
      <div class="value">
        <code>
          border-radius:
          {{
            radius.type
              ? useCssVar(`--el-border-radius-${radius.type}`)
              : '"0px"'
          }}
        </code>
      </div>
      <div
        class="radius"
        :style="{
          borderRadius: radius.type
            ? `var(--el-border-radius-${radius.type})`
            : '',
        }"
      />
    </el-col>
  </el-row>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { useCssVar } from '@vueuse/core'

const radiusGroup = ref([
  {
    name: 'No Radius',
    type: '',
  },
  {
    name: 'Small Radius',
    type: 'small',
  },
  {
    name: 'Large Radius',
    type: 'base',
  },
  {
    name: 'Round Radius',
    type: 'round',
  },
])
</script>

<style scoped>
.demo-radius .title {
  color: var(--el-text-color-regular);
  font-size: 18px;
  margin: 10px 0;
}
.demo-radius .value {
  color: var(--el-text-color-primary);
  font-size: 16px;
  margin: 10px 0;
}
.demo-radius .radius {
  height: 40px;
  width: 70%;
  border: 1px solid var(--el-border-color);
  border-radius: 0;
  margin-top: 20px;
}
</style>
```

隐藏源代码

## 阴影 [​](#阴影)

我们提供了以下几种投影样式，以供选择。

Basic Shadow`--el-box-shadow`

Light Shadow`--el-box-shadow-light`

Lighter Shadow`--el-box-shadow-lighter`

Dark Shadow`--el-box-shadow-dark`

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBqdXN0aWZ5LWJldHdlZW4gaXRlbXMtY2VudGVyIGZsZXgtd3JhcFwiPlxuICAgIDxkaXZcbiAgICAgIHYtZm9yPVwiKHNoYWRvdywgaSkgaW4gc2hhZG93R3JvdXBcIlxuICAgICAgOmtleT1cImlcIlxuICAgICAgY2xhc3M9XCJmbGV4IGZsZXgtY29sIGp1c3RpZnktY2VudGVyIGl0ZW1zLWNlbnRlclwiXG4gICAgICBtPVwiYXV0b1wiXG4gICAgICB3PVwiNDZcIlxuICAgID5cbiAgICAgIDxkaXZcbiAgICAgICAgY2xhc3M9XCJpbmxpbmUtZmxleFwiXG4gICAgICAgIGg9XCIzMFwiXG4gICAgICAgIHc9XCIzMFwiXG4gICAgICAgIG09XCIyXCJcbiAgICAgICAgOnN0eWxlPVwie1xuICAgICAgICAgIGJveFNoYWRvdzogYHZhcigke2dldENzc1Zhck5hbWUoc2hhZG93LnR5cGUpfSlgLFxuICAgICAgICB9XCJcbiAgICAgIC8+XG4gICAgICA8c3BhbiBwPVwieS00XCIgY2xhc3M9XCJkZW1vLXNoYWRvdy10ZXh0XCIgdGV4dD1cInNtXCI+XG4gICAgICAgIHt7IHNoYWRvdy5uYW1lIH19XG4gICAgICA8L3NwYW4+XG4gICAgICA8Y29kZSB0ZXh0PVwieHNcIj5cbiAgICAgICAge3sgZ2V0Q3NzVmFyTmFtZShzaGFkb3cudHlwZSkgfX1cbiAgICAgIDwvY29kZT5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBzaGFkb3dHcm91cCA9IHJlZihbXG4gIHtcbiAgICBuYW1lOiAnQmFzaWMgU2hhZG93JyxcbiAgICB0eXBlOiAnJyxcbiAgfSxcbiAge1xuICAgIG5hbWU6ICdMaWdodCBTaGFkb3cnLFxuICAgIHR5cGU6ICdsaWdodCcsXG4gIH0sXG4gIHtcbiAgICBuYW1lOiAnTGlnaHRlciBTaGFkb3cnLFxuICAgIHR5cGU6ICdsaWdodGVyJyxcbiAgfSxcbiAge1xuICAgIG5hbWU6ICdEYXJrIFNoYWRvdycsXG4gICAgdHlwZTogJ2RhcmsnLFxuICB9LFxuXSlcblxuY29uc3QgZ2V0Q3NzVmFyTmFtZSA9ICh0eXBlOiBzdHJpbmcpID0+IHtcbiAgcmV0dXJuIGAtLWVsLWJveC1zaGFkb3cke3R5cGUgPyAnLScgOiAnJ30ke3R5cGV9YFxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/border/shadow.vue)_

vue

```
<template>
  <div class="flex justify-between items-center flex-wrap">
    <div
      v-for="(shadow, i) in shadowGroup"
      :key="i"
      class="flex flex-col justify-center items-center"
      m="auto"
      w="46"
    >
      <div
        class="inline-flex"
        h="30"
        w="30"
        m="2"
        :style="{
          boxShadow: `var(${getCssVarName(shadow.type)})`,
        }"
      />
      <span p="y-4" class="demo-shadow-text" text="sm">
        {{ shadow.name }}
      </span>
      <code text="xs">
        {{ getCssVarName(shadow.type) }}
      </code>
    </div>
  </div>
</template>

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

const shadowGroup = ref([
  {
    name: 'Basic Shadow',
    type: '',
  },
  {
    name: 'Light Shadow',
    type: 'light',
  },
  {
    name: 'Lighter Shadow',
    type: 'lighter',
  },
  {
    name: 'Dark Shadow',
    type: 'dark',
  },
])

const getCssVarName = (type: string) => {
  return `--el-box-shadow${type ? '-' : ''}${type}`
}
</script>
```

隐藏源代码

## 源代码 [​](#源代码)

[文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/border.md)

[Button 按钮](https://element-plus.org/zh-CN/component/button)

[Color 色彩](https://element-plus.org/zh-CN/component/color)




---
## [basic/color] Color 色彩
> 官方文档: https://element-plus.org/zh-CN/component/color.html

---

# Color 色彩 [​](#color-色彩)

Element Plus 为了避免视觉传达差异，使用一套特定的调色板来规定颜色，为你所搭建的产品提供一致的外观视觉感受。

## 主色 [​](#主色)

Element Plus 默认的主题色是明亮、友好的蓝色。

Brand Color

#409EFF

## 辅助色 [​](#辅助色)

除了主颜色外，您需要在不同的场景中使用不同的场景颜色 (例如，危险的颜色表示危险的操作)

Success

#67C23A

Warning

#E6A23C

Danger

#F56C6C

Info

#909399

## 中性色 [​](#中性色)

中性色用于文本、背景和边框颜色。 通过运用不同的中性色，来表现层次结构。

Primary Text

#303133

Regular Text

#606266

Secondary Text

#909399

Placeholder Text

#A8ABB2

Disabled Text

#C0C4CC

Darker Border

#CDD0D6

Dark Border

#D4D7DE

Base Border

#DCDFE6

Light Border

#E4E7ED

Lighter Border

#EBEEF5

Extra-light Border

#F2F6FC

Darker Fill

#E6E8EB

Dark Fill

#EBEDF0

Base Fill

#F0F2F5

Light Fill

#F5F7FA

Lighter Fill

#FAFAFA

Extra-light Fill

#FAFCFF

Blank Fill

#FFFFFF

Basic Black

#000000

Basic White

#FFFFFF

Transparent

Transparent

Page Background

#F2F3F5

Base Background

#FFFFFF

Overlay Background

#FFFFFF

## 源代码 [​](#源代码)

[文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/color.md)

[Border 边框](https://element-plus.org/zh-CN/component/border)

[Container 布局容器](https://element-plus.org/zh-CN/component/container)




---
## [basic/container] Container 布局容器
> 官方文档: https://element-plus.org/zh-CN/component/container.html

---

# Container 布局容器 [​](#container-布局容器)

更新日志待解决

3

用于布局的容器组件，方便快速搭建页面的基本结构：

`<el-container>`：外层容器。 当子元素中包含 `<el-header>` 或 `<el-footer>` 时，全部子元素会垂直上下排列， 否则会水平左右排列。

`<el-header>`：顶栏容器。

`<el-aside>`：侧边栏容器。

`<el-main>`：主要区域容器。

`<el-footer>`：底栏容器。

TIP

以上组件采用了 flex 布局，使用前请确定目标浏览器是否兼容。 此外， `<el-container>`的直接子元素必须是后四个组件中的一个或多个。 后四个组件的父元素必须是一个 `<el-container>`

## 常见页面布局 [​](#常见页面布局)

Main

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiY29tbW9uLWxheW91dFwiPlxuICAgIDxlbC1jb250YWluZXI+XG4gICAgICA8ZWwtaGVhZGVyPkhlYWRlcjwvZWwtaGVhZGVyPlxuICAgICAgPGVsLW1haW4+TWFpbjwvZWwtbWFpbj5cbiAgICA8L2VsLWNvbnRhaW5lcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/container/layout-hm.vue)_

vue

```
<template>
  <div class="common-layout">
    <el-container>
      <el-header>Header</el-header>
      <el-main>Main</el-main>
    </el-container>
  </div>
</template>
```

隐藏源代码

Main

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiY29tbW9uLWxheW91dFwiPlxuICAgIDxlbC1jb250YWluZXI+XG4gICAgICA8ZWwtaGVhZGVyPkhlYWRlcjwvZWwtaGVhZGVyPlxuICAgICAgPGVsLW1haW4+TWFpbjwvZWwtbWFpbj5cbiAgICAgIDxlbC1mb290ZXI+Rm9vdGVyPC9lbC1mb290ZXI+XG4gICAgPC9lbC1jb250YWluZXI+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/container/layout-hmf.vue)_

vue

```
<template>
  <div class="common-layout">
    <el-container>
      <el-header>Header</el-header>
      <el-main>Main</el-main>
      <el-footer>Footer</el-footer>
    </el-container>
  </div>
</template>
```

隐藏源代码

Main

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiY29tbW9uLWxheW91dFwiPlxuICAgIDxlbC1jb250YWluZXI+XG4gICAgICA8ZWwtYXNpZGUgd2lkdGg9XCIyMDBweFwiPkFzaWRlPC9lbC1hc2lkZT5cbiAgICAgIDxlbC1tYWluPk1haW48L2VsLW1haW4+XG4gICAgICA8ZWwtYXNpZGUgd2lkdGg9XCIyMDBweFwiPkFzaWRlPC9lbC1hc2lkZT5cbiAgICA8L2VsLWNvbnRhaW5lcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/container/layout-am.vue)_

vue

```
<template>
  <div class="common-layout">
    <el-container>
      <el-aside width="200px">Aside</el-aside>
      <el-main>Main</el-main>
      <el-aside width="200px">Aside</el-aside>
    </el-container>
  </div>
</template>
```

隐藏源代码

Main

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiY29tbW9uLWxheW91dFwiPlxuICAgIDxlbC1jb250YWluZXI+XG4gICAgICA8ZWwtaGVhZGVyPkhlYWRlcjwvZWwtaGVhZGVyPlxuICAgICAgPGVsLWNvbnRhaW5lcj5cbiAgICAgICAgPGVsLWFzaWRlIHdpZHRoPVwiMjAwcHhcIj5Bc2lkZTwvZWwtYXNpZGU+XG4gICAgICAgIDxlbC1tYWluPk1haW48L2VsLW1haW4+XG4gICAgICA8L2VsLWNvbnRhaW5lcj5cbiAgICA8L2VsLWNvbnRhaW5lcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/container/layout-ham.vue)_

vue

```
<template>
  <div class="common-layout">
    <el-container>
      <el-header>Header</el-header>
      <el-container>
        <el-aside width="200px">Aside</el-aside>
        <el-main>Main</el-main>
      </el-container>
    </el-container>
  </div>
</template>
```

隐藏源代码

Main

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiY29tbW9uLWxheW91dFwiPlxuICAgIDxlbC1jb250YWluZXI+XG4gICAgICA8ZWwtaGVhZGVyPkhlYWRlcjwvZWwtaGVhZGVyPlxuICAgICAgPGVsLWNvbnRhaW5lcj5cbiAgICAgICAgPGVsLWFzaWRlIHdpZHRoPVwiMjAwcHhcIj5Bc2lkZTwvZWwtYXNpZGU+XG4gICAgICAgIDxlbC1jb250YWluZXI+XG4gICAgICAgICAgPGVsLW1haW4+TWFpbjwvZWwtbWFpbj5cbiAgICAgICAgICA8ZWwtZm9vdGVyPkZvb3RlcjwvZWwtZm9vdGVyPlxuICAgICAgICA8L2VsLWNvbnRhaW5lcj5cbiAgICAgIDwvZWwtY29udGFpbmVyPlxuICAgIDwvZWwtY29udGFpbmVyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/container/layout-hamf.vue)_

vue

```
<template>
  <div class="common-layout">
    <el-container>
      <el-header>Header</el-header>
      <el-container>
        <el-aside width="200px">Aside</el-aside>
        <el-container>
          <el-main>Main</el-main>
          <el-footer>Footer</el-footer>
        </el-container>
      </el-container>
    </el-container>
  </div>
</template>
```

隐藏源代码

Main

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiY29tbW9uLWxheW91dFwiPlxuICAgIDxlbC1jb250YWluZXI+XG4gICAgICA8ZWwtYXNpZGUgd2lkdGg9XCIyMDBweFwiPkFzaWRlPC9lbC1hc2lkZT5cbiAgICAgIDxlbC1jb250YWluZXI+XG4gICAgICAgIDxlbC1oZWFkZXI+SGVhZGVyPC9lbC1oZWFkZXI+XG4gICAgICAgIDxlbC1tYWluPk1haW48L2VsLW1haW4+XG4gICAgICA8L2VsLWNvbnRhaW5lcj5cbiAgICA8L2VsLWNvbnRhaW5lcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/container/layout-ahm.vue)_

vue

```
<template>
  <div class="common-layout">
    <el-container>
      <el-aside width="200px">Aside</el-aside>
      <el-container>
        <el-header>Header</el-header>
        <el-main>Main</el-main>
      </el-container>
    </el-container>
  </div>
</template>
```

隐藏源代码

Main

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiY29tbW9uLWxheW91dFwiPlxuICAgIDxlbC1jb250YWluZXI+XG4gICAgICA8ZWwtYXNpZGUgd2lkdGg9XCIyMDBweFwiPkFzaWRlPC9lbC1hc2lkZT5cbiAgICAgIDxlbC1jb250YWluZXI+XG4gICAgICAgIDxlbC1oZWFkZXI+SGVhZGVyPC9lbC1oZWFkZXI+XG4gICAgICAgIDxlbC1tYWluPk1haW48L2VsLW1haW4+XG4gICAgICAgIDxlbC1mb290ZXI+Rm9vdGVyPC9lbC1mb290ZXI+XG4gICAgICA8L2VsLWNvbnRhaW5lcj5cbiAgICA8L2VsLWNvbnRhaW5lcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/container/layout-ahmf.vue)_

vue

```
<template>
  <div class="common-layout">
    <el-container>
      <el-aside width="200px">Aside</el-aside>
      <el-container>
        <el-header>Header</el-header>
        <el-main>Main</el-main>
        <el-footer>Footer</el-footer>
      </el-container>
    </el-container>
  </div>
</template>
```

隐藏源代码

## 例子 [​](#例子)

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 693px;"><colgroup><col name="el-table_1_column_1" width="140"><col name="el-table_1_column_2" width="120"><col name="el-table_1_column_3" width="433"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY29udGFpbmVyIGNsYXNzPVwibGF5b3V0LWNvbnRhaW5lci1kZW1vXCIgc3R5bGU9XCJoZWlnaHQ6IDUwMHB4XCI+XG4gICAgPGVsLWFzaWRlIHdpZHRoPVwiMjAwcHhcIj5cbiAgICAgIDxlbC1zY3JvbGxiYXI+XG4gICAgICAgIDxlbC1tZW51IDpkZWZhdWx0LW9wZW5lZHM9XCJbJzEnLCAnMyddXCI+XG4gICAgICAgICAgPGVsLXN1Yi1tZW51IGluZGV4PVwiMVwiPlxuICAgICAgICAgICAgPHRlbXBsYXRlICN0aXRsZT5cbiAgICAgICAgICAgICAgPGVsLWljb24+PG1lc3NhZ2UgLz48L2VsLWljb24+TmF2aWdhdG9yIE9uZVxuICAgICAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgICAgIDxlbC1tZW51LWl0ZW0tZ3JvdXA+XG4gICAgICAgICAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+R3JvdXAgMTwvdGVtcGxhdGU+XG4gICAgICAgICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIxLTFcIj5PcHRpb24gMTwvZWwtbWVudS1pdGVtPlxuICAgICAgICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMS0yXCI+T3B0aW9uIDI8L2VsLW1lbnUtaXRlbT5cbiAgICAgICAgICAgIDwvZWwtbWVudS1pdGVtLWdyb3VwPlxuICAgICAgICAgICAgPGVsLW1lbnUtaXRlbS1ncm91cCB0aXRsZT1cIkdyb3VwIDJcIj5cbiAgICAgICAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjEtM1wiPk9wdGlvbiAzPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgICAgICA8L2VsLW1lbnUtaXRlbS1ncm91cD5cbiAgICAgICAgICAgIDxlbC1zdWItbWVudSBpbmRleD1cIjEtNFwiPlxuICAgICAgICAgICAgICA8dGVtcGxhdGUgI3RpdGxlPk9wdGlvbjQ8L3RlbXBsYXRlPlxuICAgICAgICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMS00LTFcIj5PcHRpb24gNC0xPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgICAgICA8L2VsLXN1Yi1tZW51PlxuICAgICAgICAgIDwvZWwtc3ViLW1lbnU+XG4gICAgICAgICAgPGVsLXN1Yi1tZW51IGluZGV4PVwiMlwiPlxuICAgICAgICAgICAgPHRlbXBsYXRlICN0aXRsZT5cbiAgICAgICAgICAgICAgPGVsLWljb24+PGljb24tbWVudSAvPjwvZWwtaWNvbj5OYXZpZ2F0b3IgVHdvXG4gICAgICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICAgICAgPGVsLW1lbnUtaXRlbS1ncm91cD5cbiAgICAgICAgICAgICAgPHRlbXBsYXRlICN0aXRsZT5Hcm91cCAxPC90ZW1wbGF0ZT5cbiAgICAgICAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjItMVwiPk9wdGlvbiAxPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIyLTJcIj5PcHRpb24gMjwvZWwtbWVudS1pdGVtPlxuICAgICAgICAgICAgPC9lbC1tZW51LWl0ZW0tZ3JvdXA+XG4gICAgICAgICAgICA8ZWwtbWVudS1pdGVtLWdyb3VwIHRpdGxlPVwiR3JvdXAgMlwiPlxuICAgICAgICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMi0zXCI+T3B0aW9uIDM8L2VsLW1lbnUtaXRlbT5cbiAgICAgICAgICAgIDwvZWwtbWVudS1pdGVtLWdyb3VwPlxuICAgICAgICAgICAgPGVsLXN1Yi1tZW51IGluZGV4PVwiMi00XCI+XG4gICAgICAgICAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+T3B0aW9uIDQ8L3RlbXBsYXRlPlxuICAgICAgICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMi00LTFcIj5PcHRpb24gNC0xPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgICAgICA8L2VsLXN1Yi1tZW51PlxuICAgICAgICAgIDwvZWwtc3ViLW1lbnU+XG4gICAgICAgICAgPGVsLXN1Yi1tZW51IGluZGV4PVwiM1wiPlxuICAgICAgICAgICAgPHRlbXBsYXRlICN0aXRsZT5cbiAgICAgICAgICAgICAgPGVsLWljb24+PHNldHRpbmcgLz48L2VsLWljb24+TmF2aWdhdG9yIFRocmVlXG4gICAgICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICAgICAgPGVsLW1lbnUtaXRlbS1ncm91cD5cbiAgICAgICAgICAgICAgPHRlbXBsYXRlICN0aXRsZT5Hcm91cCAxPC90ZW1wbGF0ZT5cbiAgICAgICAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjMtMVwiPk9wdGlvbiAxPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIzLTJcIj5PcHRpb24gMjwvZWwtbWVudS1pdGVtPlxuICAgICAgICAgICAgPC9lbC1tZW51LWl0ZW0tZ3JvdXA+XG4gICAgICAgICAgICA8ZWwtbWVudS1pdGVtLWdyb3VwIHRpdGxlPVwiR3JvdXAgMlwiPlxuICAgICAgICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMy0zXCI+T3B0aW9uIDM8L2VsLW1lbnUtaXRlbT5cbiAgICAgICAgICAgIDwvZWwtbWVudS1pdGVtLWdyb3VwPlxuICAgICAgICAgICAgPGVsLXN1Yi1tZW51IGluZGV4PVwiMy00XCI+XG4gICAgICAgICAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+T3B0aW9uIDQ8L3RlbXBsYXRlPlxuICAgICAgICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMy00LTFcIj5PcHRpb24gNC0xPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgICAgICA8L2VsLXN1Yi1tZW51PlxuICAgICAgICAgIDwvZWwtc3ViLW1lbnU+XG4gICAgICAgIDwvZWwtbWVudT5cbiAgICAgIDwvZWwtc2Nyb2xsYmFyPlxuICAgIDwvZWwtYXNpZGU+XG5cbiAgICA8ZWwtY29udGFpbmVyPlxuICAgICAgPGVsLWhlYWRlciBzdHlsZT1cInRleHQtYWxpZ246IHJpZ2h0OyBmb250LXNpemU6IDEycHhcIj5cbiAgICAgICAgPGRpdiBjbGFzcz1cInRvb2xiYXJcIj5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24+XG4gICAgICAgICAgICA8ZWwtaWNvbiBzdHlsZT1cIm1hcmdpbi1yaWdodDogOHB4OyBtYXJnaW4tdG9wOiAxcHhcIj5cbiAgICAgICAgICAgICAgPHNldHRpbmcgLz5cbiAgICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgICAgIDx0ZW1wbGF0ZSAjZHJvcGRvd24+XG4gICAgICAgICAgICAgIDxlbC1kcm9wZG93bi1tZW51PlxuICAgICAgICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlZpZXc8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgICAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0+QWRkPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPkRlbGV0ZTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICAgICAgPC9lbC1kcm9wZG93bi1tZW51PlxuICAgICAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgICA8L2VsLWRyb3Bkb3duPlxuICAgICAgICAgIDxzcGFuPlRvbTwvc3Bhbj5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2VsLWhlYWRlcj5cblxuICAgICAgPGVsLW1haW4+XG4gICAgICAgIDxlbC1zY3JvbGxiYXI+XG4gICAgICAgICAgPGVsLXRhYmxlIDpkYXRhPVwidGFibGVEYXRhXCI+XG4gICAgICAgICAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJkYXRlXCIgbGFiZWw9XCJEYXRlXCIgd2lkdGg9XCIxNDBcIiAvPlxuICAgICAgICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIHdpZHRoPVwiMTIwXCIgLz5cbiAgICAgICAgICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiAvPlxuICAgICAgICAgIDwvZWwtdGFibGU+XG4gICAgICAgIDwvZWwtc2Nyb2xsYmFyPlxuICAgICAgPC9lbC1tYWluPlxuICAgIDwvZWwtY29udGFpbmVyPlxuICA8L2VsLWNvbnRhaW5lcj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBNZW51IGFzIEljb25NZW51LCBNZXNzYWdlLCBTZXR0aW5nIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmNvbnN0IGl0ZW0gPSB7XG4gIGRhdGU6ICcyMDE2LTA1LTAyJyxcbiAgbmFtZTogJ1RvbScsXG4gIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxufVxuY29uc3QgdGFibGVEYXRhID0gcmVmKEFycmF5LmZyb20oeyBsZW5ndGg6IDIwIH0pLmZpbGwoaXRlbSkpXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5sYXlvdXQtY29udGFpbmVyLWRlbW8gLmVsLWhlYWRlciB7XG4gIHBvc2l0aW9uOiByZWxhdGl2ZTtcbiAgYmFja2dyb3VuZC1jb2xvcjogdmFyKC0tZWwtY29sb3ItcHJpbWFyeS1saWdodC03KTtcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3ItcHJpbWFyeSk7XG59XG4ubGF5b3V0LWNvbnRhaW5lci1kZW1vIC5lbC1hc2lkZSB7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXByaW1hcnkpO1xuICBiYWNrZ3JvdW5kOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5LWxpZ2h0LTgpO1xufVxuLmxheW91dC1jb250YWluZXItZGVtbyAuZWwtbWVudSB7XG4gIGJvcmRlci1yaWdodDogbm9uZTtcbn1cbi5sYXlvdXQtY29udGFpbmVyLWRlbW8gLmVsLW1haW4ge1xuICBwYWRkaW5nOiAwO1xufVxuLmxheW91dC1jb250YWluZXItZGVtbyAudG9vbGJhciB7XG4gIGRpc3BsYXk6IGlubGluZS1mbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBqdXN0aWZ5LWNvbnRlbnQ6IGNlbnRlcjtcbiAgaGVpZ2h0OiAxMDAlO1xuICByaWdodDogMjBweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/container/example.vue)_

vue

```
<template>
  <el-container class="layout-container-demo" style="height: 500px">
    <el-aside width="200px">
      <el-scrollbar>
        <el-menu :default-openeds="['1', '3']">
          <el-sub-menu index="1">
            <template #title>
              <el-icon><message /></el-icon>Navigator One
            </template>
            <el-menu-item-group>
              <template #title>Group 1</template>
              <el-menu-item index="1-1">Option 1</el-menu-item>
              <el-menu-item index="1-2">Option 2</el-menu-item>
            </el-menu-item-group>
            <el-menu-item-group title="Group 2">
              <el-menu-item index="1-3">Option 3</el-menu-item>
            </el-menu-item-group>
            <el-sub-menu index="1-4">
              <template #title>Option4</template>
              <el-menu-item index="1-4-1">Option 4-1</el-menu-item>
            </el-sub-menu>
          </el-sub-menu>
          <el-sub-menu index="2">
            <template #title>
              <el-icon><icon-menu /></el-icon>Navigator Two
            </template>
            <el-menu-item-group>
              <template #title>Group 1</template>
              <el-menu-item index="2-1">Option 1</el-menu-item>
              <el-menu-item index="2-2">Option 2</el-menu-item>
            </el-menu-item-group>
            <el-menu-item-group title="Group 2">
              <el-menu-item index="2-3">Option 3</el-menu-item>
            </el-menu-item-group>
            <el-sub-menu index="2-4">
              <template #title>Option 4</template>
              <el-menu-item index="2-4-1">Option 4-1</el-menu-item>
            </el-sub-menu>
          </el-sub-menu>
          <el-sub-menu index="3">
            <template #title>
              <el-icon><setting /></el-icon>Navigator Three
            </template>
            <el-menu-item-group>
              <template #title>Group 1</template>
              <el-menu-item index="3-1">Option 1</el-menu-item>
              <el-menu-item index="3-2">Option 2</el-menu-item>
            </el-menu-item-group>
            <el-menu-item-group title="Group 2">
              <el-menu-item index="3-3">Option 3</el-menu-item>
            </el-menu-item-group>
            <el-sub-menu index="3-4">
              <template #title>Option 4</template>
              <el-menu-item index="3-4-1">Option 4-1</el-menu-item>
            </el-sub-menu>
          </el-sub-menu>
        </el-menu>
      </el-scrollbar>
    </el-aside>

    <el-container>
      <el-header style="text-align: right; font-size: 12px">
        <div class="toolbar">
          <el-dropdown>
            <el-icon style="margin-right: 8px; margin-top: 1px">
              <setting />
            </el-icon>
            <template #dropdown>
              <el-dropdown-menu>
                <el-dropdown-item>View</el-dropdown-item>
                <el-dropdown-item>Add</el-dropdown-item>
                <el-dropdown-item>Delete</el-dropdown-item>
              </el-dropdown-menu>
            </template>
          </el-dropdown>
          <span>Tom</span>
        </div>
      </el-header>

      <el-main>
        <el-scrollbar>
          <el-table :data="tableData">
            <el-table-column prop="date" label="Date" width="140" />
            <el-table-column prop="name" label="Name" width="120" />
            <el-table-column prop="address" label="Address" />
          </el-table>
        </el-scrollbar>
      </el-main>
    </el-container>
  </el-container>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Menu as IconMenu, Message, Setting } from '@element-plus/icons-vue'

const item = {
  date: '2016-05-02',
  name: 'Tom',
  address: 'No. 189, Grove St, Los Angeles',
}
const tableData = ref(Array.from({ length: 20 }).fill(item))
</script>

<style scoped>
.layout-container-demo .el-header {
  position: relative;
  background-color: var(--el-color-primary-light-7);
  color: var(--el-text-color-primary);
}
.layout-container-demo .el-aside {
  color: var(--el-text-color-primary);
  background: var(--el-color-primary-light-8);
}
.layout-container-demo .el-menu {
  border-right: none;
}
.layout-container-demo .el-main {
  padding: 0;
}
.layout-container-demo .toolbar {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  height: 100%;
  right: 20px;
}
</style>
```

隐藏源代码

## Container API [​](#container-api)

### Container Attributes [​](#container-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| direction | 子元素的排列方向 | `enum` | 子元素中有 `el-header` 或 `el-footer` 时为 vertical，否则为 horizontal |

### Container Slots [​](#container-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | Container / Header / Aside / Main / Footer |

## Header API [​](#header-api)

### Header Attributes [​](#header-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| height | 顶栏高度 | `string` | 60px |

### Header Slots [​](#header-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## Aside API [​](#aside-api)

### Aside Attributes [​](#aside-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| width | 侧边栏宽度 | `string` | 300px |

### Aside Slots [​](#aside-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## Main API [​](#main-api)

### Main Slots [​](#main-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## Footer API [​](#footer-api)

### Footer Attributes [​](#footer-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| height | 底栏高度 | `string` | 60px |

### Footer Slots [​](#footer-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/container) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/container.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/container.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/48633709?v=4&size=64)](https://github.com/cosine7)[![](https://avatars.githubusercontent.com/u/102197895?v=4&size=64)](https://github.com/deng-001)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/175172745?v=4&size=64)](https://github.com/JingGaoWei)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)

[Color 色彩](https://element-plus.org/zh-CN/component/color)

[Icon 图标](https://element-plus.org/zh-CN/component/icon)




---
## [basic/icon] Icon 图标
> 官方文档: https://element-plus.org/zh-CN/component/icon.html

---

# Icon 图标 [​](#icon-图标)

更新日志待解决

15

Element Plus 提供了一套常用的图标集合。

## 使用图标 [​](#使用图标)

-   如果你想像用例一样**直接使用**，你需要[全局注册组件](https://v3.vuejs.org/guide/component-registration.html#global-registration)，才能够直接在项目里使用。

-   如若需要查看所有可用的 SVG 图标请查阅 [@element-plus/icons-vue@1.x](https://unpkg.com/browse/@element-plus/icons-vue@1/dist/es/)[@element-plus/icons-vue@latest](https://unpkg.com/browse/@element-plus/icons-vue@latest/dist/types/components/) 和有关 [Icon Collection](#icon-collection) 的源码 [element-plus-icons](https://github.com/element-plus/element-plus-icons)

## 安装 [​](#安装)

### 使用包管理器 [​](#使用包管理器)

# 选择一个你喜欢的包管理器 [​](#选择一个你喜欢的包管理器)

npmyarnpnpm

shell

```
$ npm install @element-plus/icons-vue
```

shell

```
$ yarn add @element-plus/icons-vue
```

shell

```
$ pnpm install @element-plus/icons-vue
```

### 注册所有图标 [​](#注册所有图标)

您需要从 `@element-plus/icons-vue` 中导入所有图标并进行全局注册。

ts

```
// main.ts

// 如果您正在使用CDN引入，请删除下面一行。
import * as ElementPlusIconsVue from '@element-plus/icons-vue'

const app = createApp(App)
for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
  app.component(key, component)
}
```

您也可以参考 [此模板](https://codepen.io/sxzz/pen/xxpvdrg)。

### 浏览器直接引入 [​](#浏览器直接引入)

直接通过浏览器的 HTML 标签导入 Element Plus，然后就可以使用全局变量 `ElementPlusIconsVue`了。

根据不同的 CDN 提供商有不同的引入方式， 根据不同的 CDN 提供商有不同的引入方式， 我们在这里以 [unpkg](https://unpkg.com/) 和 [jsDelivr](https://jsdelivr.com/) 举例。 你也可以使用其它的 CDN 供应商。

unpkgjsDelivr

html

```
<script src="//unpkg.com/@element-plus/icons-vue"></script>
```

html

```
<script src="//cdn.jsdelivr.net/npm/@element-plus/icons-vue"></script>
```

TIP

我们建议使用 CDN 引入 Element Plus 的用户在链接地址上锁定版本，以免将来 Element Plus 升级时受到非兼容性更新的影响。 锁定版本的方法请查看 [unpkg.com](https://unpkg.com/)。

### 自动导入 [​](#自动导入)

使用 [unplugin-icons](https://github.com/antfu/unplugin-icons) 和 [unplugin-auto-import](https://github.com/antfu/unplugin-auto-import) 从 iconify 中自动导入任何图标集。 您可以参考[此模板](https://github.com/sxzz/element-plus-best-practices/blob/db2dfc983ccda5570033a0ac608a1bd9d9a7f658/vite.config.ts#L21-L58)。

## 基础用法 [​](#基础用法)

WARNING

由于 HTML 标准已经定义了一个名为 [menu](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/menu) 的标签，如果你注册的 `Menu` 无法正常工作，则需要使用别名来渲染图标。

vue

```
<!-- 使用 el-icon 为 SVG 图标提供属性 -->
<template>
  <div>
    <el-icon :size="size" :color="color">
      <Edit />
    </el-icon>
    <!-- 或者独立使用它，不从父级获取属性 -->
    <Edit />
  </div>
</template>
```

## 结合 el-icon 使用 [​](#结合-el-icon-使用)

`el-icon` 为原始的 SVG 图标提供额外的属性，细节如下。

vue

```
<template>
  <p>
    with extra class <b>is-loading</b>, your icon is able to rotate 360 deg in 2
    seconds, you can also override this
  </p>
  <el-icon :size="20">
    <Edit />
  </el-icon>
  <el-icon color="#409efc" class="no-inherit">
    <Share />
  </el-icon>
  <el-icon>
    <Delete />
  </el-icon>
  <el-icon class="is-loading">
    <Loading />
  </el-icon>
  <el-button type="primary">
    <el-icon style="vertical-align: middle">
      <Search />
    </el-icon>
    <span style="vertical-align: middle"> Search </span>
  </el-button>
</template>
```

通过添加额外的类名 **is-loading**，你的图标就可以在 2 秒内旋转 360 度，当然你也可以自己改写想要的动画。

搜索

## 直接使用 SVG 图标 [​](#直接使用-svg-图标)

vue

```
<template>
  <div style="font-size: 20px">
    <!-- 由于SVG图标默认不携带任何属性 -->
    <!-- 你需要直接提供它们 -->
    <Edit style="width: 1em; height: 1em; margin-right: 8px" />
    <Share style="width: 1em; height: 1em; margin-right: 8px" />
    <Delete style="width: 1em; height: 1em; margin-right: 8px" />
    <Search style="width: 1em; height: 1em; margin-right: 8px" />
  </div>
</template>
```

## 图标集合 [​](#icon-collection)

TIP

只要你安装了 @element-plus/icons-vue，**就可以在任意版本里使用 SVG 图标**。

**您可以点击图标复制代码**

Copy SVG contentCopy icon code

System

-   Plus
-   Minus
-   CirclePlus
-   Search
-   Female
-   Male
-   Aim
-   House
-   FullScreen
-   Loading
-   Link
-   Service
-   Pointer
-   Star
-   Notification
-   Connection
-   ChatDotRound
-   Setting
-   Clock
-   Position
-   Discount
-   Odometer
-   ChatSquare
-   ChatRound
-   ChatLineRound
-   ChatLineSquare
-   ChatDotSquare
-   View
-   Hide
-   Unlock
-   Lock
-   RefreshRight
-   RefreshLeft
-   Refresh
-   Bell
-   MuteNotification
-   User
-   Check
-   CircleCheck
-   Warning
-   CircleClose
-   Close
-   PieChart
-   More
-   Compass
-   Filter
-   Switch
-   Select
-   SemiSelect
-   CloseBold
-   EditPen
-   Edit
-   Message
-   MessageBox
-   TurnOff
-   Finished
-   Delete
-   Crop
-   SwitchButton
-   Operation
-   Open
-   Remove
-   ZoomOut
-   ZoomIn
-   InfoFilled
-   CircleCheckFilled
-   SuccessFilled
-   WarningFilled
-   CircleCloseFilled
-   QuestionFilled
-   WarnTriangleFilled
-   UserFilled
-   MoreFilled
-   Tools
-   HomeFilled
-   Menu
-   UploadFilled
-   Avatar
-   HelpFilled
-   Share
-   StarFilled
-   Comment
-   Histogram
-   Grid
-   Promotion
-   DeleteFilled
-   RemoveFilled
-   CirclePlusFilled

Arrow

-   ArrowLeft
-   ArrowUp
-   ArrowRight
-   ArrowDown
-   ArrowLeftBold
-   ArrowUpBold
-   ArrowRightBold
-   ArrowDownBold
-   DArrowRight
-   DArrowLeft
-   Download
-   Upload
-   Top
-   Bottom
-   Back
-   Right
-   TopRight
-   TopLeft
-   BottomRight
-   BottomLeft
-   Sort
-   SortUp
-   SortDown
-   Rank
-   CaretLeft
-   CaretTop
-   CaretRight
-   CaretBottom
-   DCaret
-   Expand
-   Fold

Document

-   DocumentAdd
-   Document
-   Notebook
-   Tickets
-   Memo
-   Collection
-   Postcard
-   ScaleToOriginal
-   SetUp
-   DocumentDelete
-   DocumentChecked
-   DataBoard
-   DataAnalysis
-   CopyDocument
-   FolderChecked
-   Files
-   Folder
-   FolderDelete
-   FolderRemove
-   FolderOpened
-   DocumentCopy
-   DocumentRemove
-   FolderAdd
-   FirstAidKit
-   Reading
-   DataLine
-   Management
-   Checked
-   Ticket
-   Failed
-   TrendCharts
-   List

Media

-   Microphone
-   Mute
-   Mic
-   VideoPause
-   VideoCamera
-   VideoPlay
-   Headset
-   Monitor
-   Film
-   Camera
-   Picture
-   PictureRounded
-   Iphone
-   Cellphone
-   VideoCameraFilled
-   PictureFilled
-   Platform
-   CameraFilled
-   BellFilled

Traffic

-   Location
-   LocationInformation
-   DeleteLocation
-   Coordinate
-   Bicycle
-   OfficeBuilding
-   School
-   Guide
-   AddLocation
-   MapLocation
-   Place
-   LocationFilled
-   Van

Food

-   Watermelon
-   Pear
-   NoSmoking
-   Smoking
-   Mug
-   GobletSquareFull
-   GobletFull
-   KnifeFork
-   Sugar
-   Bowl
-   MilkTea
-   Lollipop
-   Coffee
-   Chicken
-   Dish
-   IceTea
-   ColdDrink
-   CoffeeCup
-   DishDot
-   IceDrink
-   IceCream
-   Dessert
-   IceCreamSquare
-   ForkSpoon
-   IceCreamRound
-   Food
-   HotWater
-   Grape
-   Fries
-   Apple
-   Burger
-   Goblet
-   GobletSquare
-   Orange
-   Cherry

Items

-   Printer
-   Calendar
-   CreditCard
-   Box
-   Money
-   Refrigerator
-   Cpu
-   Football
-   Brush
-   Suitcase
-   SuitcaseLine
-   Umbrella
-   AlarmClock
-   Medal
-   GoldMedal
-   Present
-   Mouse
-   Watch
-   QuartzWatch
-   Magnet
-   Help
-   Soccer
-   ToiletPaper
-   ReadingLamp
-   Paperclip
-   MagicStick
-   Basketball
-   Baseball
-   Coin
-   Goods
-   Sell
-   SoldOut
-   Key
-   ShoppingCart
-   ShoppingCartFull
-   ShoppingTrolley
-   Phone
-   Scissor
-   Handbag
-   ShoppingBag
-   Trophy
-   TrophyBase
-   Stopwatch
-   Timer
-   CollectionTag
-   TakeawayBox
-   PriceTag
-   Wallet
-   Opportunity
-   PhoneFilled
-   WalletFilled
-   GoodsFilled
-   Flag
-   BrushFilled
-   Briefcase
-   Stamp

Weather

-   Sunrise
-   Sunny
-   Ship
-   MostlyCloudy
-   PartlyCloudy
-   Sunset
-   Drizzling
-   Pouring
-   Cloudy
-   Moon
-   MoonNight
-   Lightning

Other

-   ChromeFilled
-   Eleme
-   ElemeFilled
-   ElementPlus
-   Shop
-   SwitchFilled
-   WindPower

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| color | svg 的 fill 颜色 | `string` | 继承颜色 |
| size | SVG 图标的大小，size x size | `number` / `string` | 继承字体大小 |

### Slots [​](#slots)

| 名称 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/icon) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/icon.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/icon.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/27912232?v=4&size=64)](https://github.com/Fuphoenixes)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/21235555?v=4&size=64)](https://github.com/zhangenming)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/4318293?v=4&size=64)](https://github.com/cn-troy)[![](https://avatars.githubusercontent.com/u/134276765?v=4&size=64)](https://github.com/zwgwf)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/20151622?v=4&size=64)](https://github.com/william-xue)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/25273880?v=4&size=64)](https://github.com/basonwoo)[![](https://avatars.githubusercontent.com/u/24582461?v=4&size=64)](https://github.com/KevinLjb)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/19891724?v=4&size=64)](https://github.com/pdsuwwz)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)

[Container 布局容器](https://element-plus.org/zh-CN/component/container)

[Layout 布局](https://element-plus.org/zh-CN/component/layout)




---
## [basic/layout] Layout 布局
> 官方文档: https://element-plus.org/zh-CN/component/layout.html

---

# Layout 布局 [​](#layout-布局)

更新日志待解决

5

通过基础的 24 分栏，迅速简便地创建布局。

TIP

组件默认使用 Flex 布局，不需要手动设置 `type="flex"`。

请注意父容器避免使用 `inline` 相关样式，会导致组件宽度不能撑满。

列的基本单位为1，最多24个，最少0个。

## 基础布局 [​](#基础布局)

使用列创建基础网格布局。

通过 `row` 和 `col` 组件，并通过 col 组件的 `span` 属性我们就可以自由地组合布局。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93PlxuICAgIDxlbC1jb2wgOnNwYW49XCIyNFwiPlxuICAgICAgPGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGUtZGFya1wiIC8+XG4gICAgPC9lbC1jb2w+XG4gIDwvZWwtcm93PlxuICA8ZWwtcm93PlxuICAgIDxlbC1jb2wgOnNwYW49XCIxMlwiPlxuICAgICAgPGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCIxMlwiPlxuICAgICAgPGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGUtbGlnaHRcIiAvPlxuICAgIDwvZWwtY29sPlxuICA8L2VsLXJvdz5cbiAgPGVsLXJvdz5cbiAgICA8ZWwtY29sIDpzcGFuPVwiOFwiPlxuICAgICAgPGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI4XCI+XG4gICAgICA8ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZS1saWdodFwiIC8+XG4gICAgPC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjhcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz5cbiAgICA8L2VsLWNvbD5cbiAgPC9lbC1yb3c+XG4gIDxlbC1yb3c+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjZcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz5cbiAgICA8L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpzcGFuPVwiNlwiPlxuICAgICAgPGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGUtbGlnaHRcIiAvPlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+XG4gICAgICA8ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZVwiIC8+XG4gICAgPC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjZcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlLWxpZ2h0XCIgLz5cbiAgICA8L2VsLWNvbD5cbiAgPC9lbC1yb3c+XG4gIDxlbC1yb3c+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjRcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz5cbiAgICA8L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpzcGFuPVwiNFwiPlxuICAgICAgPGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGUtbGlnaHRcIiAvPlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI0XCI+XG4gICAgICA8ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZVwiIC8+XG4gICAgPC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjRcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlLWxpZ2h0XCIgLz5cbiAgICA8L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpzcGFuPVwiNFwiPlxuICAgICAgPGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI0XCI+XG4gICAgICA8ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZS1saWdodFwiIC8+XG4gICAgPC9lbC1jb2w+XG4gIDwvZWwtcm93PlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlPlxuLmVsLXJvdyB7XG4gIG1hcmdpbi1ib3R0b206IDIwcHg7XG59XG5cbi5lbC1yb3c6bGFzdC1jaGlsZCB7XG4gIG1hcmdpbi1ib3R0b206IDA7XG59XG5cbi5lbC1jb2wge1xuICBib3JkZXItcmFkaXVzOiA0cHg7XG59XG5cbi5ncmlkLWNvbnRlbnQge1xuICBib3JkZXItcmFkaXVzOiA0cHg7XG4gIG1pbi1oZWlnaHQ6IDM2cHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/layout/basic-layout.vue)_

vue

```
<template>
  <el-row>
    <el-col :span="24">
      <div class="grid-content ep-bg-purple-dark" />
    </el-col>
  </el-row>
  <el-row>
    <el-col :span="12">
      <div class="grid-content ep-bg-purple" />
    </el-col>
    <el-col :span="12">
      <div class="grid-content ep-bg-purple-light" />
    </el-col>
  </el-row>
  <el-row>
    <el-col :span="8">
      <div class="grid-content ep-bg-purple" />
    </el-col>
    <el-col :span="8">
      <div class="grid-content ep-bg-purple-light" />
    </el-col>
    <el-col :span="8">
      <div class="grid-content ep-bg-purple" />
    </el-col>
  </el-row>
  <el-row>
    <el-col :span="6">
      <div class="grid-content ep-bg-purple" />
    </el-col>
    <el-col :span="6">
      <div class="grid-content ep-bg-purple-light" />
    </el-col>
    <el-col :span="6">
      <div class="grid-content ep-bg-purple" />
    </el-col>
    <el-col :span="6">
      <div class="grid-content ep-bg-purple-light" />
    </el-col>
  </el-row>
  <el-row>
    <el-col :span="4">
      <div class="grid-content ep-bg-purple" />
    </el-col>
    <el-col :span="4">
      <div class="grid-content ep-bg-purple-light" />
    </el-col>
    <el-col :span="4">
      <div class="grid-content ep-bg-purple" />
    </el-col>
    <el-col :span="4">
      <div class="grid-content ep-bg-purple-light" />
    </el-col>
    <el-col :span="4">
      <div class="grid-content ep-bg-purple" />
    </el-col>
    <el-col :span="4">
      <div class="grid-content ep-bg-purple-light" />
    </el-col>
  </el-row>
</template>

<style>
.el-row {
  margin-bottom: 20px;
}

.el-row:last-child {
  margin-bottom: 0;
}

.el-col {
  border-radius: 4px;
}

.grid-content {
  border-radius: 4px;
  min-height: 36px;
}
</style>
```

隐藏源代码

## 分栏间隔 [​](#分栏间隔)

支持列间距。

行提供 `gutter` 属性来指定列之间的间距，其默认值为0。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IDpndXR0ZXI9XCIyMFwiPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPjwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPjwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPjwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPjwvZWwtY29sPlxuICA8L2VsLXJvdz5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZT5cbi5lbC1yb3cge1xuICBtYXJnaW4tYm90dG9tOiAyMHB4O1xufVxuLmVsLXJvdzpsYXN0LWNoaWxkIHtcbiAgbWFyZ2luLWJvdHRvbTogMDtcbn1cbi5lbC1jb2wge1xuICBib3JkZXItcmFkaXVzOiA0cHg7XG59XG5cbi5ncmlkLWNvbnRlbnQge1xuICBib3JkZXItcmFkaXVzOiA0cHg7XG4gIG1pbi1oZWlnaHQ6IDM2cHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/layout/column-spacing.vue)_

vue

```
<template>
  <el-row :gutter="20">
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
  </el-row>
</template>

<style>
.el-row {
  margin-bottom: 20px;
}
.el-row:last-child {
  margin-bottom: 0;
}
.el-col {
  border-radius: 4px;
}

.grid-content {
  border-radius: 4px;
  min-height: 36px;
}
</style>
```

隐藏源代码

## 混合布局 [​](#混合布局)

通过基础的 1/24 分栏任意扩展组合形成较为复杂的混合布局。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IDpndXR0ZXI9XCIyMFwiPlxuICAgIDxlbC1jb2wgOnNwYW49XCIxNlwiPjxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz48L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpzcGFuPVwiOFwiPjxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz48L2VsLWNvbD5cbiAgPC9lbC1yb3c+XG4gIDxlbC1yb3cgOmd1dHRlcj1cIjIwXCI+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjhcIj48ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZVwiIC8+PC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjhcIj48ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZVwiIC8+PC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjRcIj48ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZVwiIC8+PC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjRcIj48ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZVwiIC8+PC9lbC1jb2w+XG4gIDwvZWwtcm93PlxuICA8ZWwtcm93IDpndXR0ZXI9XCIyMFwiPlxuICAgIDxlbC1jb2wgOnNwYW49XCI0XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPjwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCIxNlwiPjxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz48L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpzcGFuPVwiNFwiPjxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz48L2VsLWNvbD5cbiAgPC9lbC1yb3c+XG48L3RlbXBsYXRlPlxuXG48c3R5bGU+XG4uZWwtcm93IHtcbiAgbWFyZ2luLWJvdHRvbTogMjBweDtcbn1cbi5lbC1yb3c6bGFzdC1jaGlsZCB7XG4gIG1hcmdpbi1ib3R0b206IDA7XG59XG4uZWwtY29sIHtcbiAgYm9yZGVyLXJhZGl1czogNHB4O1xufVxuXG4uZ3JpZC1jb250ZW50IHtcbiAgYm9yZGVyLXJhZGl1czogNHB4O1xuICBtaW4taGVpZ2h0OiAzNnB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/layout/hybrid-layout.vue)_

vue

```
<template>
  <el-row :gutter="20">
    <el-col :span="16"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="8"><div class="grid-content ep-bg-purple" /></el-col>
  </el-row>
  <el-row :gutter="20">
    <el-col :span="8"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="8"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="4"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="4"><div class="grid-content ep-bg-purple" /></el-col>
  </el-row>
  <el-row :gutter="20">
    <el-col :span="4"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="16"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="4"><div class="grid-content ep-bg-purple" /></el-col>
  </el-row>
</template>

<style>
.el-row {
  margin-bottom: 20px;
}
.el-row:last-child {
  margin-bottom: 0;
}
.el-col {
  border-radius: 4px;
}

.grid-content {
  border-radius: 4px;
  min-height: 36px;
}
</style>
```

隐藏源代码

## 列偏移 [​](#列偏移)

您可以指定列偏移量。

通过制定 col 组件的 `offset` 属性可以指定分栏偏移的栏数。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IDpndXR0ZXI9XCIyMFwiPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPjwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCIgOm9mZnNldD1cIjZcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz5cbiAgICA8L2VsLWNvbD5cbiAgPC9lbC1yb3c+XG4gIDxlbC1yb3cgOmd1dHRlcj1cIjIwXCI+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjZcIiA6b2Zmc2V0PVwiNlwiPlxuICAgICAgPGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCIgOm9mZnNldD1cIjZcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz5cbiAgICA8L2VsLWNvbD5cbiAgPC9lbC1yb3c+XG4gIDxlbC1yb3cgOmd1dHRlcj1cIjIwXCI+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjEyXCIgOm9mZnNldD1cIjZcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz5cbiAgICA8L2VsLWNvbD5cbiAgPC9lbC1yb3c+XG48L3RlbXBsYXRlPlxuXG48c3R5bGU+XG4uZWwtcm93IHtcbiAgbWFyZ2luLWJvdHRvbTogMjBweDtcbn1cbi5lbC1yb3c6bGFzdC1jaGlsZCB7XG4gIG1hcmdpbi1ib3R0b206IDA7XG59XG4uZWwtY29sIHtcbiAgYm9yZGVyLXJhZGl1czogNHB4O1xufVxuXG4uZ3JpZC1jb250ZW50IHtcbiAgYm9yZGVyLXJhZGl1czogNHB4O1xuICBtaW4taGVpZ2h0OiAzNnB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/layout/column-offset.vue)_

vue

```
<template>
  <el-row :gutter="20">
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="6" :offset="6">
      <div class="grid-content ep-bg-purple" />
    </el-col>
  </el-row>
  <el-row :gutter="20">
    <el-col :span="6" :offset="6">
      <div class="grid-content ep-bg-purple" />
    </el-col>
    <el-col :span="6" :offset="6">
      <div class="grid-content ep-bg-purple" />
    </el-col>
  </el-row>
  <el-row :gutter="20">
    <el-col :span="12" :offset="6">
      <div class="grid-content ep-bg-purple" />
    </el-col>
  </el-row>
</template>

<style>
.el-row {
  margin-bottom: 20px;
}
.el-row:last-child {
  margin-bottom: 0;
}
.el-col {
  border-radius: 4px;
}

.grid-content {
  border-radius: 4px;
  min-height: 36px;
}
</style>
```

隐藏源代码

## 对齐方式 [​](#对齐方式)

默认使用 flex 布局来对分栏进行灵活的对齐。

您可以通过`justify` 属性来定义子元素的排版方式，其取值为start、center、end、space-between、space-around或space-evenly。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IGNsYXNzPVwicm93LWJnXCI+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjZcIj48ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZVwiIC8+PC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjZcIj48ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZS1saWdodFwiIC8+PC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjZcIj48ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZVwiIC8+PC9lbC1jb2w+XG4gIDwvZWwtcm93PlxuICA8ZWwtcm93IGNsYXNzPVwicm93LWJnXCIganVzdGlmeT1cImNlbnRlclwiPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPjwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGUtbGlnaHRcIiAvPjwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPjwvZWwtY29sPlxuICA8L2VsLXJvdz5cbiAgPGVsLXJvdyBjbGFzcz1cInJvdy1iZ1wiIGp1c3RpZnk9XCJlbmRcIj5cbiAgICA8ZWwtY29sIDpzcGFuPVwiNlwiPjxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz48L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpzcGFuPVwiNlwiPjxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlLWxpZ2h0XCIgLz48L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpzcGFuPVwiNlwiPjxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz48L2VsLWNvbD5cbiAgPC9lbC1yb3c+XG4gIDxlbC1yb3cgY2xhc3M9XCJyb3ctYmdcIiBqdXN0aWZ5PVwic3BhY2UtYmV0d2VlblwiPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPjwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGUtbGlnaHRcIiAvPjwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI2XCI+PGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGVcIiAvPjwvZWwtY29sPlxuICA8L2VsLXJvdz5cbiAgPGVsLXJvdyBjbGFzcz1cInJvdy1iZ1wiIGp1c3RpZnk9XCJzcGFjZS1hcm91bmRcIj5cbiAgICA8ZWwtY29sIDpzcGFuPVwiNlwiPjxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz48L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpzcGFuPVwiNlwiPjxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlLWxpZ2h0XCIgLz48L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpzcGFuPVwiNlwiPjxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz48L2VsLWNvbD5cbiAgPC9lbC1yb3c+XG4gIDxlbC1yb3cgY2xhc3M9XCJyb3ctYmdcIiBqdXN0aWZ5PVwic3BhY2UtZXZlbmx5XCI+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjZcIj48ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZVwiIC8+PC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjZcIj48ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZS1saWdodFwiIC8+PC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjZcIj48ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZVwiIC8+PC9lbC1jb2w+XG4gIDwvZWwtcm93PlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlPlxuLmVsLXJvdyB7XG4gIG1hcmdpbi1ib3R0b206IDIwcHg7XG59XG4uZWwtcm93Omxhc3QtY2hpbGQge1xuICBtYXJnaW4tYm90dG9tOiAwO1xufVxuLmVsLWNvbCB7XG4gIGJvcmRlci1yYWRpdXM6IDRweDtcbn1cblxuLmdyaWQtY29udGVudCB7XG4gIGJvcmRlci1yYWRpdXM6IDRweDtcbiAgbWluLWhlaWdodDogMzZweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/layout/alignment.vue)_

vue

```
<template>
  <el-row class="row-bg">
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple-light" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
  </el-row>
  <el-row class="row-bg" justify="center">
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple-light" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
  </el-row>
  <el-row class="row-bg" justify="end">
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple-light" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
  </el-row>
  <el-row class="row-bg" justify="space-between">
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple-light" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
  </el-row>
  <el-row class="row-bg" justify="space-around">
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple-light" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
  </el-row>
  <el-row class="row-bg" justify="space-evenly">
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple-light" /></el-col>
    <el-col :span="6"><div class="grid-content ep-bg-purple" /></el-col>
  </el-row>
</template>

<style>
.el-row {
  margin-bottom: 20px;
}
.el-row:last-child {
  margin-bottom: 0;
}
.el-col {
  border-radius: 4px;
}

.grid-content {
  border-radius: 4px;
  min-height: 36px;
}
</style>
```

隐藏源代码

## 响应式布局 [​](#响应式布局)

参照了 Bootstrap 的 响应式设计，预设了五个响应尺寸：xs、sm、md、lg 和 xl。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IDpndXR0ZXI9XCIxMFwiPlxuICAgIDxlbC1jb2wgOnhzPVwiOFwiIDpzbT1cIjZcIiA6bWQ9XCI0XCIgOmxnPVwiM1wiIDp4bD1cIjFcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJncmlkLWNvbnRlbnQgZXAtYmctcHVycGxlXCIgLz5cbiAgICA8L2VsLWNvbD5cbiAgICA8ZWwtY29sIDp4cz1cIjRcIiA6c209XCI2XCIgOm1kPVwiOFwiIDpsZz1cIjlcIiA6eGw9XCIxMVwiPlxuICAgICAgPGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGUtbGlnaHRcIiAvPlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnhzPVwiNFwiIDpzbT1cIjZcIiA6bWQ9XCI4XCIgOmxnPVwiOVwiIDp4bD1cIjExXCI+XG4gICAgICA8ZGl2IGNsYXNzPVwiZ3JpZC1jb250ZW50IGVwLWJnLXB1cnBsZVwiIC8+XG4gICAgPC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6eHM9XCI4XCIgOnNtPVwiNlwiIDptZD1cIjRcIiA6bGc9XCIzXCIgOnhsPVwiMVwiPlxuICAgICAgPGRpdiBjbGFzcz1cImdyaWQtY29udGVudCBlcC1iZy1wdXJwbGUtbGlnaHRcIiAvPlxuICAgIDwvZWwtY29sPlxuICA8L2VsLXJvdz5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZT5cbi5lbC1jb2wge1xuICBib3JkZXItcmFkaXVzOiA0cHg7XG59XG5cbi5ncmlkLWNvbnRlbnQge1xuICBib3JkZXItcmFkaXVzOiA0cHg7XG4gIG1pbi1oZWlnaHQ6IDM2cHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/layout/responsive-layout.vue)_

vue

```
<template>
  <el-row :gutter="10">
    <el-col :xs="8" :sm="6" :md="4" :lg="3" :xl="1">
      <div class="grid-content ep-bg-purple" />
    </el-col>
    <el-col :xs="4" :sm="6" :md="8" :lg="9" :xl="11">
      <div class="grid-content ep-bg-purple-light" />
    </el-col>
    <el-col :xs="4" :sm="6" :md="8" :lg="9" :xl="11">
      <div class="grid-content ep-bg-purple" />
    </el-col>
    <el-col :xs="8" :sm="6" :md="4" :lg="3" :xl="1">
      <div class="grid-content ep-bg-purple-light" />
    </el-col>
  </el-row>
</template>

<style>
.el-col {
  border-radius: 4px;
}

.grid-content {
  border-radius: 4px;
  min-height: 36px;
}
</style>
```

隐藏源代码

## 基于断点的隐藏类 [​](#基于断点的隐藏类)

Element Plus 额外提供了一系列类名，用于在某些条件下隐藏元素。 这些类名可以添加在任何 DOM 元素或自定义组件上。 如果需要，请自行引入以下文件：

js

```
import 'element-plus/theme-chalk/display.css'
```

这些类名为：

-   `hidden-xs-only` - 当视口在 `xs` 尺寸时隐藏
-   `hidden-sm-only` - 当视口在 `sm` 尺寸时隐藏
-   `hidden-sm-and-down` - 当视口在 `sm` 及以下尺寸时隐藏
-   `hidden-sm-and-up` - 当视口在 `sm` 及以上尺寸时隐藏
-   `hidden-md-only` - 当视口在 `md` 尺寸时隐藏
-   `hidden-md-and-down` - 当视口在 `md` 及以下尺寸时隐藏
-   `hidden-md-and-up` - 当视口在 `md` 及以上尺寸时隐藏
-   `hidden-lg-only` - 当视口在 `lg` 尺寸时隐藏
-   `hidden-lg-and-down` - 当视口在 `lg` 及以下尺寸时隐藏
-   `hidden-lg-and-up` - 当视口在 `lg` 及以上尺寸时隐藏
-   `hidden-xl-only` - 当视口在 `xl` 尺寸时隐藏

## Row API [​](#row-api)

### Row Attributes [​](#row-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| gutter | 栅格间隔 | `number` | 0 |
| justify | flex 布局下的水平排列方式 | `enum` | start |
| align | flex 布局下的垂直排列方式 | `enum` | — |
| tag | 自定义元素标签 | `string` | div |

### Row Slots [​](#row-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | Col |

## Col API [​](#col-api)

### Col Attributes [​](#col-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| span | 栅格占据的列数 | `number` | 24 |
| offset | 栅格左侧的间隔格数 | `number` | 0 |
| push | 栅格向右移动格数 | `number` | 0 |
| pull | 栅格向左移动格数 | `number` | 0 |
| xs | `<768px` 响应式栅格数或者栅格属性对象 | `number` / `object` | — |
| sm | `≥768px` 响应式栅格数或者栅格属性对象 | `number` / `object` | — |
| md | `≥992px` 响应式栅格数或者栅格属性对象 | `number` / `object` | — |
| lg | `≥1200px` 响应式栅格数或者栅格属性对象 | `number` / `object` | — |
| xl | `≥1920px` 响应式栅格数或者栅格属性对象 | `number` / `object` | — |
| tag | 自定义元素标签 | `string` | div |

### Col Slots [​](#col-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## 源代码 [​](#源代码)

[文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/layout.md)

[Icon 图标](https://element-plus.org/zh-CN/component/icon)

[Link 链接](https://element-plus.org/zh-CN/component/link)




---
## [basic/link] Link 链接
> 官方文档: https://element-plus.org/zh-CN/component/link.html

---

# Link 链接 [​](#link-链接)

更新日志待解决

5

文字超链接

安全警告 `href` prop 将会直接渲染到 `<a>` 标签内部。 如果你传递类似 `javascript:alert(1)` 这样的值或恶意 URL，可能会导致 **XSS** 或**开放重定向漏洞**。

在使用前始终验证并净化 URL。 例如：

显示代码示例

js

```
function sanitigzeUrl(url) {
  const allowedprotocol= ['http:', 'https://']
  try {
    const parsed = new URL(url, window.location.origin)
    return allowedProtocols.includes(parsed.protocol) ? parsed.href : '#'
  } catch {
    return '#'
  }
}
```

## 基础用法 [​](#基础用法)

基础的文字链接用法。

[default](https://element-plus.org/)primarysuccesswarningdangerinfo

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1saW5rIGhyZWY9XCJodHRwczovL2VsZW1lbnQtcGx1cy5vcmdcIiB0YXJnZXQ9XCJfYmxhbmtcIj5kZWZhdWx0PC9lbC1saW5rPlxuICAgIDxlbC1saW5rIHR5cGU9XCJwcmltYXJ5XCI+cHJpbWFyeTwvZWwtbGluaz5cbiAgICA8ZWwtbGluayB0eXBlPVwic3VjY2Vzc1wiPnN1Y2Nlc3M8L2VsLWxpbms+XG4gICAgPGVsLWxpbmsgdHlwZT1cIndhcm5pbmdcIj53YXJuaW5nPC9lbC1saW5rPlxuICAgIDxlbC1saW5rIHR5cGU9XCJkYW5nZXJcIj5kYW5nZXI8L2VsLWxpbms+XG4gICAgPGVsLWxpbmsgdHlwZT1cImluZm9cIj5pbmZvPC9lbC1saW5rPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZWwtbGluayB7XG4gIG1hcmdpbi1yaWdodDogOHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/link/basic.vue)_

vue

```
<template>
  <div>
    <el-link href="https://element-plus.org" target="_blank">default</el-link>
    <el-link type="primary">primary</el-link>
    <el-link type="success">success</el-link>
    <el-link type="warning">warning</el-link>
    <el-link type="danger">danger</el-link>
    <el-link type="info">info</el-link>
  </div>
</template>

<style scoped>
.el-link {
  margin-right: 8px;
}
</style>
```

隐藏源代码

## 禁用状态 [​](#禁用状态)

文字链接不可用状态。

defaultprimarysuccesswarningdangerinfo

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1saW5rIGRpc2FibGVkPmRlZmF1bHQ8L2VsLWxpbms+XG4gICAgPGVsLWxpbmsgdHlwZT1cInByaW1hcnlcIiBkaXNhYmxlZD5wcmltYXJ5PC9lbC1saW5rPlxuICAgIDxlbC1saW5rIHR5cGU9XCJzdWNjZXNzXCIgZGlzYWJsZWQ+c3VjY2VzczwvZWwtbGluaz5cbiAgICA8ZWwtbGluayB0eXBlPVwid2FybmluZ1wiIGRpc2FibGVkPndhcm5pbmc8L2VsLWxpbms+XG4gICAgPGVsLWxpbmsgdHlwZT1cImRhbmdlclwiIGRpc2FibGVkPmRhbmdlcjwvZWwtbGluaz5cbiAgICA8ZWwtbGluayB0eXBlPVwiaW5mb1wiIGRpc2FibGVkPmluZm88L2VsLWxpbms+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlIHNjb3BlZD5cbi5lbC1saW5rIHtcbiAgbWFyZ2luLXJpZ2h0OiA4cHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/link/disabled.vue)_

vue

```
<template>
  <div>
    <el-link disabled>default</el-link>
    <el-link type="primary" disabled>primary</el-link>
    <el-link type="success" disabled>success</el-link>
    <el-link type="warning" disabled>warning</el-link>
    <el-link type="danger" disabled>danger</el-link>
    <el-link type="info" disabled>info</el-link>
  </div>
</template>

<style scoped>
.el-link {
  margin-right: 8px;
}
</style>
```

隐藏源代码

## 下划线 [​](#下划线)

控制下划线是否出现

WARNING

属性 `boolean` 值 **将在** 3.0.0 版本中被**移除**，请考虑切换至新的 API。

TIP

从 2.9.9 开始，你可以使用 `'always' | 'hover' | 'never'` 来控制是否显示下划线。 文档中的示例将都使用这些值。 如果您使用的版本 **低于** 2.9.9，请参考：

vue

```
<template>
  <!-- works before 2.9.9, use 'hover' after, removed in 3.0.0 -->
  <el-link underline>link</el-link>
  <!-- works before 2.9.9, use 'never' after, removed in 3.0.0 -->
  <el-link :underline="false">link</el-link>
</template>
```

defaultalwayshovernever

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1saW5rPmRlZmF1bHQ8L2VsLWxpbms+XG4gICAgPGVsLWxpbmsgdW5kZXJsaW5lPVwiYWx3YXlzXCI+YWx3YXlzPC9lbC1saW5rPlxuICAgIDxlbC1saW5rIHVuZGVybGluZT1cImhvdmVyXCI+aG92ZXI8L2VsLWxpbms+XG4gICAgPGVsLWxpbmsgdW5kZXJsaW5lPVwibmV2ZXJcIj5uZXZlcjwvZWwtbGluaz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c3R5bGUgc2NvcGVkPlxuLmVsLWxpbmsge1xuICBtYXJnaW4tcmlnaHQ6IDhweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/link/underline.vue)_

vue

```
<template>
  <div>
    <el-link>default</el-link>
    <el-link underline="always">always</el-link>
    <el-link underline="hover">hover</el-link>
    <el-link underline="never">never</el-link>
  </div>
</template>

<style scoped>
.el-link {
  margin-right: 8px;
}
</style>
```

隐藏源代码

## 图标 [​](#图标)

带图标的链接

TIP

使用 `icon` 属性来为按钮添加图标。 您可以传递组件名称的字符串（提前注册）或组件本身是一个 SVG Vue 组件。 Element Plus 提供了一套图标，您可以在 [icon](https://element-plus.org/zh-CN/component/icon) 找到它们。

Edit Check

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1saW5rIDppY29uPVwiRWRpdFwiPkVkaXQ8L2VsLWxpbms+XG4gICAgPGVsLWxpbms+XG4gICAgICBDaGVjazxlbC1pY29uIGNsYXNzPVwiZWwtaWNvbi0tcmlnaHRcIj48aWNvbi12aWV3IC8+PC9lbC1pY29uPlxuICAgIDwvZWwtbGluaz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgRWRpdCwgVmlldyBhcyBJY29uVmlldyB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZWwtbGluayB7XG4gIG1hcmdpbi1yaWdodDogOHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/link/with-icon.vue)_

vue

```
<template>
  <div>
    <el-link :icon="Edit">Edit</el-link>
    <el-link>
      Check<el-icon class="el-icon--right"><icon-view /></el-icon>
    </el-link>
  </div>
</template>

<script setup lang="ts">
import { Edit, View as IconView } from '@element-plus/icons-vue'
</script>

<style scoped>
.el-link {
  margin-right: 8px;
}
</style>
```

隐藏源代码

## Link API [​](#link-api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| type | 类型 | `enum` | default |
| underline | 控制下划线是否出现 | `enum` | hover |
| disabled | 是否禁用状态 | `boolean` | false |
| href | 原生 href 属性 | `string` | — |
| target | 同原生 `target` 属性 | `enum` | \_self |
| icon | 图标组件 | `string` / `Component` | — |

### Slots [​](#slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |
| icon | 自定义图标组件 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/link) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/link.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/link.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/45218946?v=4&size=64)](https://github.com/comp-squirrel)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/75007029?v=4&size=64)](https://github.com/yj-liuzepeng)[![](https://avatars.githubusercontent.com/u/13871363?v=4&size=64)](https://github.com/logustra)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/67825153?v=4&size=64)](https://github.com/FancyangY)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/57179957?v=4&size=64)](https://github.com/yeonjulee1005)[![](https://avatars.githubusercontent.com/u/43134418?v=4&size=64)](https://github.com/MonsterPi13)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)

[Layout 布局](https://element-plus.org/zh-CN/component/layout)

[Text 文本](https://element-plus.org/zh-CN/component/text)




---
## [basic/text] Text 文本
> 官方文档: https://element-plus.org/zh-CN/component/text.html

---

# Text [​](#text)

更新日志待解决

6

文本的常见操作

## 基础用法 [​](#基础用法)

由 `type` 属性来选择 Text 的类型。

DefaultPrimarySuccessInfoWarningDanger

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGV4dCBjbGFzcz1cIm14LTFcIj5EZWZhdWx0PC9lbC10ZXh0PlxuICA8ZWwtdGV4dCBjbGFzcz1cIm14LTFcIiB0eXBlPVwicHJpbWFyeVwiPlByaW1hcnk8L2VsLXRleHQ+XG4gIDxlbC10ZXh0IGNsYXNzPVwibXgtMVwiIHR5cGU9XCJzdWNjZXNzXCI+U3VjY2VzczwvZWwtdGV4dD5cbiAgPGVsLXRleHQgY2xhc3M9XCJteC0xXCIgdHlwZT1cImluZm9cIj5JbmZvPC9lbC10ZXh0PlxuICA8ZWwtdGV4dCBjbGFzcz1cIm14LTFcIiB0eXBlPVwid2FybmluZ1wiPldhcm5pbmc8L2VsLXRleHQ+XG4gIDxlbC10ZXh0IGNsYXNzPVwibXgtMVwiIHR5cGU9XCJkYW5nZXJcIj5EYW5nZXI8L2VsLXRleHQ+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/text/basic.vue)_

vue

```
<template>
  <el-text class="mx-1">Default</el-text>
  <el-text class="mx-1" type="primary">Primary</el-text>
  <el-text class="mx-1" type="success">Success</el-text>
  <el-text class="mx-1" type="info">Info</el-text>
  <el-text class="mx-1" type="warning">Warning</el-text>
  <el-text class="mx-1" type="danger">Danger</el-text>
</template>
```

隐藏源代码

## 尺寸 [​](#尺寸)

使用 `size` 属性配置尺寸，可选的尺寸大小有: `large`, `default` 或 `small`

LargeDefaultSmall

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGV4dCBjbGFzcz1cIm14LTFcIiBzaXplPVwibGFyZ2VcIj5MYXJnZTwvZWwtdGV4dD5cbiAgPGVsLXRleHQgY2xhc3M9XCJteC0xXCI+RGVmYXVsdDwvZWwtdGV4dD5cbiAgPGVsLXRleHQgY2xhc3M9XCJteC0xXCIgc2l6ZT1cInNtYWxsXCI+U21hbGw8L2VsLXRleHQ+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/text/sizes.vue)_

vue

```
<template>
  <el-text class="mx-1" size="large">Large</el-text>
  <el-text class="mx-1">Default</el-text>
  <el-text class="mx-1" size="small">Small</el-text>
</template>
```

隐藏源代码

## 省略 [​](#省略)

通过 `truncated` 属性，在文本超过视图或最大宽度设置时展示省略符。 通过 `line-clamp` 属性控制多行的样式

Self element set width 100px

Squeezed by parent element

The -webkit-line-clamp CSS property
allows limiting of the contents of
a block to the specified number of lines.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGV4dCBjbGFzcz1cInctMTUwcHggbWItMlwiIHRydW5jYXRlZD5cbiAgICBTZWxmIGVsZW1lbnQgc2V0IHdpZHRoIDEwMHB4XG4gIDwvZWwtdGV4dD5cbiAgPGVsLXJvdyBjbGFzcz1cInctMTUwcHggbWItMlwiPlxuICAgIDxlbC10ZXh0IHRydW5jYXRlZD5TcXVlZXplZCBieSBwYXJlbnQgZWxlbWVudDwvZWwtdGV4dD5cbiAgPC9lbC1yb3c+XG4gIDxlbC10ZXh0IGxpbmUtY2xhbXA9XCIyXCI+XG4gICAgVGhlIC13ZWJraXQtbGluZS1jbGFtcCBDU1MgcHJvcGVydHk8YnIgLz5cbiAgICBhbGxvd3MgbGltaXRpbmcgb2YgdGhlIGNvbnRlbnRzIG9mPGJyIC8+XG4gICAgYSBibG9jayB0byB0aGUgc3BlY2lmaWVkIG51bWJlciBvZiBsaW5lcy5cbiAgPC9lbC10ZXh0PlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/text/truncated.vue)_

vue

```
<template>
  <el-text class="w-150px mb-2" truncated>
    Self element set width 100px
  </el-text>
  <el-row class="w-150px mb-2">
    <el-text truncated>Squeezed by parent element</el-text>
  </el-row>
  <el-text line-clamp="2">
    The -webkit-line-clamp CSS property<br />
    allows limiting of the contents of<br />
    a block to the specified number of lines.
  </el-text>
</template>
```

隐藏源代码

## 覆盖 [​](#覆盖)

使用属性 `tag` 覆盖元素

span

This is a paragraph.

**Bold**

_Italic_

This is subscript

This is superscript

Inserted

~~Deleted~~

Marked

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2UgZGlyZWN0aW9uPVwidmVydGljYWxcIj5cbiAgICA8ZWwtdGV4dD5zcGFuPC9lbC10ZXh0PlxuICAgIDxlbC10ZXh0IHRhZz1cInBcIj5UaGlzIGlzIGEgcGFyYWdyYXBoLjwvZWwtdGV4dD5cbiAgICA8ZWwtdGV4dCB0YWc9XCJiXCI+Qm9sZDwvZWwtdGV4dD5cbiAgICA8ZWwtdGV4dCB0YWc9XCJpXCI+SXRhbGljPC9lbC10ZXh0PlxuICAgIDxlbC10ZXh0PlxuICAgICAgVGhpcyBpc1xuICAgICAgPGVsLXRleHQgdGFnPVwic3ViXCIgc2l6ZT1cInNtYWxsXCI+c3Vic2NyaXB0PC9lbC10ZXh0PlxuICAgIDwvZWwtdGV4dD5cbiAgICA8ZWwtdGV4dD5cbiAgICAgIFRoaXMgaXNcbiAgICAgIDxlbC10ZXh0IHRhZz1cInN1cFwiIHNpemU9XCJzbWFsbFwiPnN1cGVyc2NyaXB0PC9lbC10ZXh0PlxuICAgIDwvZWwtdGV4dD5cbiAgICA8ZWwtdGV4dCB0YWc9XCJpbnNcIj5JbnNlcnRlZDwvZWwtdGV4dD5cbiAgICA8ZWwtdGV4dCB0YWc9XCJkZWxcIj5EZWxldGVkPC9lbC10ZXh0PlxuICAgIDxlbC10ZXh0IHRhZz1cIm1hcmtcIj5NYXJrZWQ8L2VsLXRleHQ+XG4gIDwvZWwtc3BhY2U+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/text/override.vue)_

vue

```
<template>
  <el-space direction="vertical">
    <el-text>span</el-text>
    <el-text tag="p">This is a paragraph.</el-text>
    <el-text tag="b">Bold</el-text>
    <el-text tag="i">Italic</el-text>
    <el-text>
      This is
      <el-text tag="sub" size="small">subscript</el-text>
    </el-text>
    <el-text>
      This is
      <el-text tag="sup" size="small">superscript</el-text>
    </el-text>
    <el-text tag="ins">Inserted</el-text>
    <el-text tag="del">Deleted</el-text>
    <el-text tag="mark">Marked</el-text>
  </el-space>
</template>
```

隐藏源代码

## 混合使用 [​](#混合使用)

混合使用 Text 组件

Element-Plus

Rate

This is text mixed icon and component Button

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2UgZGlyZWN0aW9uPVwidmVydGljYWxcIj5cbiAgICA8ZWwtdGV4dD5cbiAgICAgIDxlbC1pY29uPlxuICAgICAgICA8RWxlbWVudFBsdXMgLz5cbiAgICAgIDwvZWwtaWNvbj5cbiAgICAgIEVsZW1lbnQtUGx1c1xuICAgIDwvZWwtdGV4dD5cbiAgICA8ZWwtcm93PlxuICAgICAgPGVsLXRleHQ+UmF0ZTwvZWwtdGV4dD5cbiAgICAgIDxlbC1yYXRlIGNsYXNzPVwibWwtMVwiIC8+XG4gICAgPC9lbC1yb3c+XG4gICAgPGVsLXRleHQ+XG4gICAgICBUaGlzIGlzIHRleHQgbWl4ZWQgaWNvblxuICAgICAgPGVsLWljb24+XG4gICAgICAgIDxCZWxsIC8+XG4gICAgICA8L2VsLWljb24+XG4gICAgICBhbmQgY29tcG9uZW50XG4gICAgICA8ZWwtYnV0dG9uPkJ1dHRvbjwvZWwtYnV0dG9uPlxuICAgIDwvZWwtdGV4dD5cbiAgPC9lbC1zcGFjZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBCZWxsLCBFbGVtZW50UGx1cyB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/text/mixed.vue)_

vue

```
<template>
  <el-space direction="vertical">
    <el-text>
      <el-icon>
        <ElementPlus />
      </el-icon>
      Element-Plus
    </el-text>
    <el-row>
      <el-text>Rate</el-text>
      <el-rate class="ml-1" />
    </el-row>
    <el-text>
      This is text mixed icon
      <el-icon>
        <Bell />
      </el-icon>
      and component
      <el-button>Button</el-button>
    </el-text>
  </el-space>
</template>

<script lang="ts" setup>
import { Bell, ElementPlus } from '@element-plus/icons-vue'
</script>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 描述 | 类型 | 默认值 |
| --- | --- | --- | --- |
| type | 类型 | `enum` | — |
| size | 大小 | `enum` | default |
| truncated | 显示省略号 | `boolean` | false |
| line-clamp 2.4.0 | 最大行数 | `string` / `number` | — |
| tag | 自定义元素标签 | `string` | span |

### Slots [​](#slots)

| 名称 | 详情 |
| --- | --- |
| default | 默认内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/text) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/text.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/text.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)

[Link 链接](https://element-plus.org/zh-CN/component/link)

[Scrollbar 滚动条](https://element-plus.org/zh-CN/component/scrollbar)




---
## [basic/scrollbar] Scrollbar 滚动条
> 官方文档: https://element-plus.org/zh-CN/component/scrollbar.html

---

# Scrollbar 滚动条 [​](#scrollbar-滚动条)

更新日志待解决

22

用于替换浏览器原生滚动条。

## 基础用法 [​](#基础用法)

通过 `height` 属性设置滚动条高度，若不设置则根据父容器高度自适应。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2Nyb2xsYmFyIGhlaWdodD1cIjQwMHB4XCI+XG4gICAgPHAgdi1mb3I9XCJpdGVtIGluIDIwXCIgOmtleT1cIml0ZW1cIiBjbGFzcz1cInNjcm9sbGJhci1kZW1vLWl0ZW1cIj57eyBpdGVtIH19PC9wPlxuICA8L2VsLXNjcm9sbGJhcj5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZSBzY29wZWQ+XG4uc2Nyb2xsYmFyLWRlbW8taXRlbSB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG4gIGp1c3RpZnktY29udGVudDogY2VudGVyO1xuICBoZWlnaHQ6IDUwcHg7XG4gIG1hcmdpbjogMTBweDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBib3JkZXItcmFkaXVzOiA0cHg7XG4gIGJhY2tncm91bmQ6IHZhcigtLWVsLWNvbG9yLXByaW1hcnktbGlnaHQtOSk7XG4gIGNvbG9yOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/scrollbar/basic-usage.vue)_

vue

```
<template>
  <el-scrollbar height="400px">
    <p v-for="item in 20" :key="item" class="scrollbar-demo-item">{{ item }}</p>
  </el-scrollbar>
</template>

<style scoped>
.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);
}
</style>
```

隐藏源代码

## 横向滚动 [​](#横向滚动)

当元素宽度大于滚动条宽度时，会显示横向滚动条。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2Nyb2xsYmFyPlxuICAgIDxkaXYgY2xhc3M9XCJzY3JvbGxiYXItZmxleC1jb250ZW50XCI+XG4gICAgICA8cCB2LWZvcj1cIml0ZW0gaW4gNTBcIiA6a2V5PVwiaXRlbVwiIGNsYXNzPVwic2Nyb2xsYmFyLWRlbW8taXRlbVwiPlxuICAgICAgICB7eyBpdGVtIH19XG4gICAgICA8L3A+XG4gICAgPC9kaXY+XG4gIDwvZWwtc2Nyb2xsYmFyPlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlIHNjb3BlZD5cbi5zY3JvbGxiYXItZmxleC1jb250ZW50IHtcbiAgZGlzcGxheTogZmxleDtcbiAgd2lkdGg6IGZpdC1jb250ZW50O1xufVxuLnNjcm9sbGJhci1kZW1vLWl0ZW0ge1xuICBmbGV4LXNocmluazogMDtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbiAganVzdGlmeS1jb250ZW50OiBjZW50ZXI7XG4gIHdpZHRoOiAxMDBweDtcbiAgaGVpZ2h0OiA1MHB4O1xuICBtYXJnaW46IDEwcHg7XG4gIHRleHQtYWxpZ246IGNlbnRlcjtcbiAgYm9yZGVyLXJhZGl1czogNHB4O1xuICBiYWNrZ3JvdW5kOiB2YXIoLS1lbC1jb2xvci1kYW5nZXItbGlnaHQtOSk7XG4gIGNvbG9yOiB2YXIoLS1lbC1jb2xvci1kYW5nZXIpO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/scrollbar/horizontal-scroll.vue)_

vue

```
<template>
  <el-scrollbar>
    <div class="scrollbar-flex-content">
      <p v-for="item in 50" :key="item" class="scrollbar-demo-item">
        {{ item }}
      </p>
    </div>
  </el-scrollbar>
</template>

<style scoped>
.scrollbar-flex-content {
  display: flex;
  width: fit-content;
}
.scrollbar-demo-item {
  flex-shrink: 0;
  display: flex;
  align-items: center;
  justify-content: center;
  width: 100px;
  height: 50px;
  margin: 10px;
  text-align: center;
  border-radius: 4px;
  background: var(--el-color-danger-light-9);
  color: var(--el-color-danger);
}
</style>
```

隐藏源代码

## 最大高度 [​](#最大高度)

当元素高度超过最大高度，才会显示滚动条。

Add ItemDelete Item

1

2

3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIEBjbGljaz1cImFkZFwiPkFkZCBJdGVtPC9lbC1idXR0b24+XG4gIDxlbC1idXR0b24gQGNsaWNrPVwib25EZWxldGVcIj5EZWxldGUgSXRlbTwvZWwtYnV0dG9uPlxuICA8ZWwtc2Nyb2xsYmFyIG1heC1oZWlnaHQ9XCI0MDBweFwiPlxuICAgIDxwIHYtZm9yPVwiaXRlbSBpbiBjb3VudFwiIDprZXk9XCJpdGVtXCIgY2xhc3M9XCJzY3JvbGxiYXItZGVtby1pdGVtXCI+XG4gICAgICB7eyBpdGVtIH19XG4gICAgPC9wPlxuICA8L2VsLXNjcm9sbGJhcj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGNvdW50ID0gcmVmKDMpXG5cbmNvbnN0IGFkZCA9ICgpID0+IHtcbiAgY291bnQudmFsdWUrK1xufVxuY29uc3Qgb25EZWxldGUgPSAoKSA9PiB7XG4gIGlmIChjb3VudC52YWx1ZSA+IDApIHtcbiAgICBjb3VudC52YWx1ZS0tXG4gIH1cbn1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLnNjcm9sbGJhci1kZW1vLWl0ZW0ge1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBqdXN0aWZ5LWNvbnRlbnQ6IGNlbnRlcjtcbiAgaGVpZ2h0OiA1MHB4O1xuICBtYXJnaW46IDEwcHg7XG4gIHRleHQtYWxpZ246IGNlbnRlcjtcbiAgYm9yZGVyLXJhZGl1czogNHB4O1xuICBiYWNrZ3JvdW5kOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5LWxpZ2h0LTkpO1xuICBjb2xvcjogdmFyKC0tZWwtY29sb3ItcHJpbWFyeSk7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/scrollbar/max-height.vue)_

vue

```
<template>
  <el-button @click="add">Add Item</el-button>
  <el-button @click="onDelete">Delete Item</el-button>
  <el-scrollbar max-height="400px">
    <p v-for="item in count" :key="item" class="scrollbar-demo-item">
      {{ item }}
    </p>
  </el-scrollbar>
</template>

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

const count = ref(3)

const add = () => {
  count.value++
}
const onDelete = () => {
  if (count.value > 0) {
    count.value--
  }
}
</script>

<style scoped>
.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);
}
</style>
```

隐藏源代码

## 手动滚动 [​](#手动滚动)

通过使用 `setScrollTop` 与 `setScrollLeft` 方法，可以手动控制滚动条滚动。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2Nyb2xsYmFyIHJlZj1cInNjcm9sbGJhclJlZlwiIGhlaWdodD1cIjQwMHB4XCIgYWx3YXlzIEBzY3JvbGw9XCJzY3JvbGxcIj5cbiAgICA8ZGl2IHJlZj1cImlubmVyUmVmXCI+XG4gICAgICA8cCB2LWZvcj1cIml0ZW0gaW4gMjBcIiA6a2V5PVwiaXRlbVwiIGNsYXNzPVwic2Nyb2xsYmFyLWRlbW8taXRlbVwiPlxuICAgICAgICB7eyBpdGVtIH19XG4gICAgICA8L3A+XG4gICAgPC9kaXY+XG4gIDwvZWwtc2Nyb2xsYmFyPlxuXG4gIDxlbC1zbGlkZXJcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIDptYXg9XCJtYXhcIlxuICAgIDpmb3JtYXQtdG9vbHRpcD1cImZvcm1hdFRvb2x0aXBcIlxuICAgIEBpbnB1dD1cImlucHV0U2xpZGVyXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBvbk1vdW50ZWQsIHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBTY3JvbGxiYXJJbnN0YW5jZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxudHlwZSBBcnJheWFibGU8VD4gPSBUIHwgVFtdXG5cbmNvbnN0IG1heCA9IHJlZigwKVxuY29uc3QgdmFsdWUgPSByZWYoMClcbmNvbnN0IGlubmVyUmVmID0gcmVmPEhUTUxEaXZFbGVtZW50PigpXG5jb25zdCBzY3JvbGxiYXJSZWYgPSByZWY8U2Nyb2xsYmFySW5zdGFuY2U+KClcblxub25Nb3VudGVkKCgpID0+IHtcbiAgbWF4LnZhbHVlID0gaW5uZXJSZWYudmFsdWUhLmNsaWVudEhlaWdodCAtIDM4MFxufSlcblxuY29uc3QgaW5wdXRTbGlkZXIgPSAodmFsdWU6IEFycmF5YWJsZTxudW1iZXI+KSA9PiB7XG4gIHNjcm9sbGJhclJlZi52YWx1ZSEuc2V0U2Nyb2xsVG9wKHZhbHVlIGFzIG51bWJlcilcbn1cbmNvbnN0IHNjcm9sbCA9ICh7IHNjcm9sbFRvcCB9OiB7IHNjcm9sbFRvcDogbnVtYmVyIH0pID0+IHtcbiAgdmFsdWUudmFsdWUgPSBzY3JvbGxUb3Bcbn1cbmNvbnN0IGZvcm1hdFRvb2x0aXAgPSAodmFsdWU6IG51bWJlcikgPT4gYCR7dmFsdWV9IHB4YFxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uc2Nyb2xsYmFyLWRlbW8taXRlbSB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG4gIGp1c3RpZnktY29udGVudDogY2VudGVyO1xuICBoZWlnaHQ6IDUwcHg7XG4gIG1hcmdpbjogMTBweDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBib3JkZXItcmFkaXVzOiA0cHg7XG4gIGJhY2tncm91bmQ6IHZhcigtLWVsLWNvbG9yLXByaW1hcnktbGlnaHQtOSk7XG4gIGNvbG9yOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbn1cbi5lbC1zbGlkZXIge1xuICBtYXJnaW4tdG9wOiAyMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/scrollbar/manual-scroll.vue)_

vue

```
<template>
  <el-scrollbar ref="scrollbarRef" height="400px" always @scroll="scroll">
    <div ref="innerRef">
      <p v-for="item in 20" :key="item" class="scrollbar-demo-item">
        {{ item }}
      </p>
    </div>
  </el-scrollbar>

  <el-slider
    v-model="value"
    :max="max"
    :format-tooltip="formatTooltip"
    @input="inputSlider"
  />
</template>

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

import type { ScrollbarInstance } from 'element-plus'

type Arrayable<T> = T | T[]

const max = ref(0)
const value = ref(0)
const innerRef = ref<HTMLDivElement>()
const scrollbarRef = ref<ScrollbarInstance>()

onMounted(() => {
  max.value = innerRef.value!.clientHeight - 380
})

const inputSlider = (value: Arrayable<number>) => {
  scrollbarRef.value!.setScrollTop(value as number)
}
const scroll = ({ scrollTop }: { scrollTop: number }) => {
  value.value = scrollTop
}
const formatTooltip = (value: number) => `${value} px`
</script>

<style scoped>
.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);
}
.el-slider {
  margin-top: 20px;
}
</style>
```

隐藏源代码

## 无限滚动2.10.0 [​](#无限滚动)

`end-reached` 是在滚动条到达底部时触发的。 它可以用作无限滚动。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2Nyb2xsYmFyIGhlaWdodD1cIjQwMHB4XCIgQGVuZC1yZWFjaGVkPVwibG9hZE1vcmVcIj5cbiAgICA8cCB2LWZvcj1cIml0ZW0gaW4gbnVtXCIgOmtleT1cIml0ZW1cIiBjbGFzcz1cInNjcm9sbGJhci1kZW1vLWl0ZW1cIj5cbiAgICAgIHt7IGl0ZW0gfX1cbiAgICA8L3A+XG4gIDwvZWwtc2Nyb2xsYmFyPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBTY3JvbGxiYXJEaXJlY3Rpb24gfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IG51bSA9IHJlZigzMClcblxuY29uc3QgbG9hZE1vcmUgPSAoZGlyZWN0aW9uOiBTY3JvbGxiYXJEaXJlY3Rpb24pID0+IHtcbiAgaWYgKGRpcmVjdGlvbiA9PT0gJ2JvdHRvbScpIHtcbiAgICBudW0udmFsdWUgKz0gNVxuICB9XG59XG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5zY3JvbGxiYXItZGVtby1pdGVtIHtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbiAganVzdGlmeS1jb250ZW50OiBjZW50ZXI7XG4gIGhlaWdodDogNTBweDtcbiAgbWFyZ2luOiAxMHB4O1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG4gIGJvcmRlci1yYWRpdXM6IDRweDtcbiAgYmFja2dyb3VuZDogdmFyKC0tZWwtY29sb3ItcHJpbWFyeS1saWdodC05KTtcbiAgY29sb3I6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xufVxuLmVsLXNsaWRlciB7XG4gIG1hcmdpbi10b3A6IDIwcHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/scrollbar/infinite-scroll.vue)_

vue

```
<template>
  <el-scrollbar height="400px" @end-reached="loadMore">
    <p v-for="item in num" :key="item" class="scrollbar-demo-item">
      {{ item }}
    </p>
  </el-scrollbar>
</template>

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

import type { ScrollbarDirection } from 'element-plus'

const num = ref(30)

const loadMore = (direction: ScrollbarDirection) => {
  if (direction === 'bottom') {
    num.value += 5
  }
}
</script>

<style scoped>
.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);
}
.el-slider {
  margin-top: 20px;
}
</style>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| height | 滚动条高度 | `string` / `number` | — |
| max-height | 滚动条最大高度 | `string` / `number` | — |
| native | 是否使用原生滚动条样式 | `boolean` | false |
| wrap-style | 包裹容器的自定义样式 | `string` / `object` | — |
| wrap-class | 包裹容器的自定义类名 | `string` | — |
| view-style | 视图的自定义样式 | `string` / `object` | — |
| view-class | 视图的自定义类名 | `string` | — |
| noresize | 不响应容器尺寸变化，如果容器尺寸不会发生变化，最好设置它可以优化性能 | `boolean` | false |
| tag | 视图的元素标签 | `string` | div |
| always | 滚动条总是显示 | `boolean` | false |
| min-size | 滚动条最小尺寸 | `number` | 20 |
| id 2.4.0 | 视图ID | `string` | — |
| role 2.4.0 a11y | 视图的角色 | `string` | — |
| aria-label 2.4.0 a11y | 视图的 aria-label | `string` | — |
| aria-orientation 2.4.0 a11y | 视图的 aria-orientation | `enum` | — |
| tabindex 2.8.3 | 容器的tabindex | `number` / `string` | — |
| distance 2.10.5 | 触发到达底部事件的距离（像素） | `number` | 0 |

### Events [​](#events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| scroll | 当触发滚动事件时，返回滚动的距离 | `Function` |
| end-reached 2.10.0 | 触发滚动结束时的触发器 | `Function` |

### Slots [​](#slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

### Exposes [​](#exposes)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| handleScroll | 触发滚动事件 | `Function` |
| scrollTo | 滚动到一组特定坐标 | `Function` |
| setScrollTop | 设置滚动条到顶部的距离 | `Function` |
| setScrollLeft | 设置滚动条到左边的距离 | `Function` |
| update | 手动更新滚动条状态 | `Function` |
| wrapRef | 滚动条包裹的 ref 对象 | `object` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/scrollbar) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/scrollbar.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/scrollbar.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/62818957?v=4&size=64)](https://github.com/ZacharyBear)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/33646534?v=4&size=64)](https://github.com/SevenDreamYang)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/108655466?v=4&size=64)](https://github.com/Karolis-Stoncius)[![](https://avatars.githubusercontent.com/u/24290011?v=4&size=64)](https://github.com/xingyixiang)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)

[Text 文本](https://element-plus.org/zh-CN/component/text)

[Space 间距](https://element-plus.org/zh-CN/component/space)




---
## [basic/space] Space 间距
> 官方文档: https://element-plus.org/zh-CN/component/space.html

---

# Space 间距 [​](#space-间距)

更新日志待解决

5

虽然我们拥有 [Divider 组件](https://element-plus.org/zh-CN/component/divider)，但很多时候我们需要不是一个被 [Divider 组件](https://element-plus.org/zh-CN/component/divider) 分割开的页面结构，因此我们会重复的使用很多的 [Divider 组件](https://element-plus.org/zh-CN/component/divider)，这在我们的开发效率上造成了一定的困扰。 **间距组件**就是为了解决这种困扰应运而生的。

## 基础用法 [​](#基础用法)

最基础的用法，通过这个组件来给组件之间提供统一的间距。

通过间距组件来给多个组件之间提供间距

Card nameOperation button

List item 1

List item 2

List item 3

List item 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2Ugd3JhcD5cbiAgICA8ZWwtY2FyZCB2LWZvcj1cImkgaW4gM1wiIDprZXk9XCJpXCIgY2xhc3M9XCJib3gtY2FyZFwiIHN0eWxlPVwid2lkdGg6IDI1MHB4XCI+XG4gICAgICA8dGVtcGxhdGUgI2hlYWRlcj5cbiAgICAgICAgPGRpdiBjbGFzcz1cImNhcmQtaGVhZGVyXCI+XG4gICAgICAgICAgPHNwYW4+Q2FyZCBuYW1lPC9zcGFuPlxuICAgICAgICAgIDxlbC1idXR0b24gY2xhc3M9XCJidXR0b25cIiB0ZXh0Pk9wZXJhdGlvbiBidXR0b248L2VsLWJ1dHRvbj5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgPGRpdiB2LWZvcj1cIm8gaW4gNFwiIDprZXk9XCJvXCIgY2xhc3M9XCJ0ZXh0IGl0ZW1cIj5cbiAgICAgICAge3sgJ0xpc3QgaXRlbSAnICsgbyB9fVxuICAgICAgPC9kaXY+XG4gICAgPC9lbC1jYXJkPlxuICA8L2VsLXNwYWNlPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/space/basic.vue)_

vue

```
<template>
  <el-space wrap>
    <el-card v-for="i in 3" :key="i" class="box-card" style="width: 250px">
      <template #header>
        <div class="card-header">
          <span>Card name</span>
          <el-button class="button" text>Operation button</el-button>
        </div>
      </template>
      <div v-for="o in 4" :key="o" class="text item">
        {{ 'List item ' + o }}
      </div>
    </el-card>
  </el-space>
</template>
```

隐藏源代码

## 垂直布局 [​](#垂直布局)

使用 `direction` 来控制布局的方式, 背后实际上是利用了 `flex-direction` 来控制.

我们也提供垂直布局方式。

Card nameOperation button

List item 1

List item 2

List item 3

List item 4

Card nameOperation button

List item 1

List item 2

List item 3

List item 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2UgZGlyZWN0aW9uPVwidmVydGljYWxcIj5cbiAgICA8ZWwtY2FyZCB2LWZvcj1cImkgaW4gMlwiIDprZXk9XCJpXCIgY2xhc3M9XCJib3gtY2FyZFwiIHN0eWxlPVwid2lkdGg6IDI1MHB4XCI+XG4gICAgICA8dGVtcGxhdGUgI2hlYWRlcj5cbiAgICAgICAgPGRpdiBjbGFzcz1cImNhcmQtaGVhZGVyXCI+XG4gICAgICAgICAgPHNwYW4+Q2FyZCBuYW1lPC9zcGFuPlxuICAgICAgICAgIDxlbC1idXR0b24gY2xhc3M9XCJidXR0b25cIiB0ZXh0Pk9wZXJhdGlvbiBidXR0b248L2VsLWJ1dHRvbj5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgPGRpdiB2LWZvcj1cIm8gaW4gNFwiIDprZXk9XCJvXCIgY2xhc3M9XCJ0ZXh0IGl0ZW1cIj5cbiAgICAgICAge3sgJ0xpc3QgaXRlbSAnICsgbyB9fVxuICAgICAgPC9kaXY+XG4gICAgPC9lbC1jYXJkPlxuICA8L2VsLXNwYWNlPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/space/vertical-layout.vue)_

vue

```
<template>
  <el-space direction="vertical">
    <el-card v-for="i in 2" :key="i" class="box-card" style="width: 250px">
      <template #header>
        <div class="card-header">
          <span>Card name</span>
          <el-button class="button" text>Operation button</el-button>
        </div>
      </template>
      <div v-for="o in 4" :key="o" class="text item">
        {{ 'List item ' + o }}
      </div>
    </el-card>
  </el-space>
</template>
```

隐藏源代码

## 控制间距的大小 [​](#控制间距的大小)

通过调整 `size` 的值来控制间距的大小

你可以使用内置的尺寸 `small`、`default`、`large` 来设置大小，这些尺寸分别对应 `8px`、`12px`、`16px`。 默认的间距大小为 `small`，也就是 `8px`。

您也可以通过自定义的 size 来控制大小， 参见下一个部分。

LargeDefaultSmall

Card nameOperation button

List item 1

List item 2

List item 3

List item 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2UgZGlyZWN0aW9uPVwidmVydGljYWxcIiBhbGlnbm1lbnQ9XCJzdGFydFwiIDpzaXplPVwiMzBcIj5cbiAgICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInNpemVcIj5cbiAgICAgIDxlbC1yYWRpbyB2YWx1ZT1cImxhcmdlXCI+TGFyZ2U8L2VsLXJhZGlvPlxuICAgICAgPGVsLXJhZGlvIHZhbHVlPVwiZGVmYXVsdFwiPkRlZmF1bHQ8L2VsLXJhZGlvPlxuICAgICAgPGVsLXJhZGlvIHZhbHVlPVwic21hbGxcIj5TbWFsbDwvZWwtcmFkaW8+XG4gICAgPC9lbC1yYWRpby1ncm91cD5cblxuICAgIDxlbC1zcGFjZSB3cmFwIDpzaXplPVwic2l6ZVwiPlxuICAgICAgPGVsLWNhcmQgdi1mb3I9XCJpIGluIDNcIiA6a2V5PVwiaVwiIGNsYXNzPVwiYm94LWNhcmRcIiBzdHlsZT1cIndpZHRoOiAyNTBweFwiPlxuICAgICAgICA8dGVtcGxhdGUgI2hlYWRlcj5cbiAgICAgICAgICA8ZGl2IGNsYXNzPVwiY2FyZC1oZWFkZXJcIj5cbiAgICAgICAgICAgIDxzcGFuPkNhcmQgbmFtZTwvc3Bhbj5cbiAgICAgICAgICAgIDxlbC1idXR0b24gY2xhc3M9XCJidXR0b25cIiB0ZXh0Pk9wZXJhdGlvbiBidXR0b248L2VsLWJ1dHRvbj5cbiAgICAgICAgICA8L2Rpdj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPGRpdiB2LWZvcj1cIm8gaW4gNFwiIDprZXk9XCJvXCIgY2xhc3M9XCJ0ZXh0IGl0ZW1cIj5cbiAgICAgICAgICB7eyAnTGlzdCBpdGVtICcgKyBvIH19XG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jYXJkPlxuICAgIDwvZWwtc3BhY2U+XG4gIDwvZWwtc3BhY2U+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IENvbXBvbmVudFNpemUgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHNpemUgPSByZWY8Q29tcG9uZW50U2l6ZT4oJ2RlZmF1bHQnKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/space/control-size.vue)_

vue

```
<template>
  <el-space direction="vertical" alignment="start" :size="30">
    <el-radio-group v-model="size">
      <el-radio value="large">Large</el-radio>
      <el-radio value="default">Default</el-radio>
      <el-radio value="small">Small</el-radio>
    </el-radio-group>

    <el-space wrap :size="size">
      <el-card v-for="i in 3" :key="i" class="box-card" style="width: 250px">
        <template #header>
          <div class="card-header">
            <span>Card name</span>
            <el-button class="button" text>Operation button</el-button>
          </div>
        </template>
        <div v-for="o in 4" :key="o" class="text item">
          {{ 'List item ' + o }}
        </div>
      </el-card>
    </el-space>
  </el-space>
</template>

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

import type { ComponentSize } from 'element-plus'

const size = ref<ComponentSize>('default')
</script>
```

隐藏源代码

## 自定义 Size [​](#自定义-size)

很多时候，内建的大小不满足设计师的要求，我们可以通过传入自己定义的大小 (数值类型) 来设置。

Card nameOperation button

List item 1

List item 2

List item 3

List item 4

Card nameOperation button

List item 1

List item 2

List item 3

List item 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2xpZGVyIHYtbW9kZWw9XCJzaXplXCIgLz5cbiAgPGVsLXNwYWNlIHdyYXAgOnNpemU9XCJzaXplXCI+XG4gICAgPGVsLWNhcmQgdi1mb3I9XCJpIGluIDJcIiA6a2V5PVwiaVwiIGNsYXNzPVwiYm94LWNhcmRcIiBzdHlsZT1cIndpZHRoOiAyNTBweFwiPlxuICAgICAgPHRlbXBsYXRlICNoZWFkZXI+XG4gICAgICAgIDxkaXYgY2xhc3M9XCJjYXJkLWhlYWRlclwiPlxuICAgICAgICAgIDxzcGFuPkNhcmQgbmFtZTwvc3Bhbj5cbiAgICAgICAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiYnV0dG9uXCIgdGV4dD5PcGVyYXRpb24gYnV0dG9uPC9lbC1idXR0b24+XG4gICAgICAgIDwvZGl2PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDxkaXYgdi1mb3I9XCJvIGluIDRcIiA6a2V5PVwib1wiIGNsYXNzPVwidGV4dCBpdGVtXCI+XG4gICAgICAgIHt7ICdMaXN0IGl0ZW0gJyArIG8gfX1cbiAgICAgIDwvZGl2PlxuICAgIDwvZWwtY2FyZD5cbiAgPC9lbC1zcGFjZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHNpemUgPSByZWYoMjApXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/space/customized-size.vue)_

vue

```
<template>
  <el-slider v-model="size" />
  <el-space wrap :size="size">
    <el-card v-for="i in 2" :key="i" class="box-card" style="width: 250px">
      <template #header>
        <div class="card-header">
          <span>Card name</span>
          <el-button class="button" text>Operation button</el-button>
        </div>
      </template>
      <div v-for="o in 4" :key="o" class="text item">
        {{ 'List item ' + o }}
      </div>
    </el-card>
  </el-space>
</template>

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

const size = ref(20)
</script>
```

隐藏源代码

TIP

不要让 `ElSpace` 与使用依赖父元素百分比宽度（或高度）的元素一起使用（例如 `ElSlider`），这样会造成光标不同步。

## 自动换行 [​](#自动换行)

在 \*\*水平 (horizontal) \*\* 模式下，通过使用 `wrap`（**布尔类型**）来控制自动换行行为。

利用 `wrap` 属性控制换行

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

Text button

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2Ugd3JhcD5cbiAgICA8ZGl2IHYtZm9yPVwiaSBpbiAyMFwiIDprZXk9XCJpXCI+XG4gICAgICA8ZWwtYnV0dG9uIHRleHQ+IFRleHQgYnV0dG9uIDwvZWwtYnV0dG9uPlxuICAgIDwvZGl2PlxuICA8L2VsLXNwYWNlPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/space/auto-wrapping.vue)_

vue

```
<template>
  <el-space wrap>
    <div v-for="i in 20" :key="i">
      <el-button text> Text button </el-button>
    </div>
  </el-space>
</template>
```

隐藏源代码

## 行间分隔符 [​](#行间分隔符)

有时候，仅仅在行间加空白并不能满足我们的日常需求，此时分隔符 (spacer) 就可以发挥非常好的作用了。

## 字母数字类型分隔符 [​](#字母数字类型分隔符)

button 1

|

button 2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2UgOnNpemU9XCJzaXplXCIgc3BhY2VyPVwifFwiPlxuICAgIDxkaXYgdi1mb3I9XCJpIGluIDJcIiA6a2V5PVwiaVwiPlxuICAgICAgPGVsLWJ1dHRvbj4gYnV0dG9uIHt7IGkgfX0gPC9lbC1idXR0b24+XG4gICAgPC9kaXY+XG4gIDwvZWwtc3BhY2U+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBzaXplID0gcmVmKDEwKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/space/literal-type-spacer.vue)_

vue

```
<template>
  <el-space :size="size" spacer="|">
    <div v-for="i in 2" :key="i">
      <el-button> button {{ i }} </el-button>
    </div>
  </el-space>
</template>

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

const size = ref(10)
</script>
```

隐藏源代码

## 分隔符还可以是 VNode 类型 [​](#分隔符还可以是-vnode-类型)

button 1

button 2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2UgOnNpemU9XCJzaXplXCIgOnNwYWNlcj1cInNwYWNlclwiPlxuICAgIDxkaXYgdi1mb3I9XCJpIGluIDJcIiA6a2V5PVwiaVwiPlxuICAgICAgPGVsLWJ1dHRvbj4gYnV0dG9uIHt7IGkgfX0gPC9lbC1idXR0b24+XG4gICAgPC9kaXY+XG4gIDwvZWwtc3BhY2U+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgaCwgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgRWxEaXZpZGVyIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBzaXplID0gcmVmKDEwKVxuY29uc3Qgc3BhY2VyID0gaChFbERpdmlkZXIsIHsgZGlyZWN0aW9uOiAndmVydGljYWwnIH0pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/space/vnode-type-spacer.vue)_

vue

```
<template>
  <el-space :size="size" :spacer="spacer">
    <div v-for="i in 2" :key="i">
      <el-button> button {{ i }} </el-button>
    </div>
  </el-space>
</template>

<script lang="ts" setup>
import { h, ref } from 'vue'
import { ElDivider } from 'element-plus'

const size = ref(10)
const spacer = h(ElDivider, { direction: 'vertical' })
</script>
```

隐藏源代码

## 对齐方式 [​](#对齐方式)

设置该值可以调整所有子节点在容器内的对齐方式，可设置的值与 [align-items](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items) 一致。

使用 `alignment` 属性来对齐

string

button

header

body

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiYWxpZ25tZW50LWNvbnRhaW5lclwiPlxuICAgIDxlbC1zcGFjZT5cbiAgICAgIHN0cmluZ1xuICAgICAgPGVsLWJ1dHRvbj4gYnV0dG9uIDwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWNhcmQ+XG4gICAgICAgIDx0ZW1wbGF0ZSAjaGVhZGVyPiBoZWFkZXIgPC90ZW1wbGF0ZT5cbiAgICAgICAgYm9keVxuICAgICAgPC9lbC1jYXJkPlxuICAgIDwvZWwtc3BhY2U+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwiYWxpZ25tZW50LWNvbnRhaW5lclwiPlxuICAgIDxlbC1zcGFjZSBhbGlnbm1lbnQ9XCJmbGV4LXN0YXJ0XCI+XG4gICAgICBzdHJpbmdcbiAgICAgIDxlbC1idXR0b24+IGJ1dHRvbiA8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1jYXJkPlxuICAgICAgICA8dGVtcGxhdGUgI2hlYWRlcj4gaGVhZGVyIDwvdGVtcGxhdGU+XG4gICAgICAgIGJvZHlcbiAgICAgIDwvZWwtY2FyZD5cbiAgICA8L2VsLXNwYWNlPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cImFsaWdubWVudC1jb250YWluZXJcIj5cbiAgICA8ZWwtc3BhY2UgYWxpZ25tZW50PVwiZmxleC1lbmRcIj5cbiAgICAgIHN0cmluZ1xuICAgICAgPGVsLWJ1dHRvbj4gYnV0dG9uIDwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWNhcmQ+XG4gICAgICAgIDx0ZW1wbGF0ZSAjaGVhZGVyPiBoZWFkZXIgPC90ZW1wbGF0ZT5cbiAgICAgICAgYm9keVxuICAgICAgPC9lbC1jYXJkPlxuICAgIDwvZWwtc3BhY2U+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlPlxuLmFsaWdubWVudC1jb250YWluZXIge1xuICB3aWR0aDogMjQwcHg7XG4gIG1hcmdpbi1ib3R0b206IDIwcHg7XG4gIHBhZGRpbmc6IDhweDtcbiAgYm9yZGVyOiAxcHggc29saWQgdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/space/alignment.vue)_

vue

```
<template>
  <div class="alignment-container">
    <el-space>
      string
      <el-button> button </el-button>
      <el-card>
        <template #header> header </template>
        body
      </el-card>
    </el-space>
  </div>
  <div class="alignment-container">
    <el-space alignment="flex-start">
      string
      <el-button> button </el-button>
      <el-card>
        <template #header> header </template>
        body
      </el-card>
    </el-space>
  </div>
  <div class="alignment-container">
    <el-space alignment="flex-end">
      string
      <el-button> button </el-button>
      <el-card>
        <template #header> header </template>
        body
      </el-card>
    </el-space>
  </div>
</template>

<style>
.alignment-container {
  width: 240px;
  margin-bottom: 20px;
  padding: 8px;
  border: 1px solid var(--el-border-color);
}
</style>
```

隐藏源代码

## 填充容器 [​](#填充容器)

通过 `fill`\*\*（布尔类型）\*\*参数，您可以控制子节点是否自动填充容器。

下面的例子中，当设置为 `fill` 时，子节点的宽度会自动适配容器的宽度。

用 fill 属性让子节点自动填充容器

fill:

Card nameOperation button

List item 1

List item 2

List item 3

List item 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxkaXYgc3R5bGU9XCJtYXJnaW4tYm90dG9tOiAxNXB4XCI+ZmlsbDogPGVsLXN3aXRjaCB2LW1vZGVsPVwiZmlsbFwiIC8+PC9kaXY+XG4gICAgPGVsLXNwYWNlIDpmaWxsPVwiZmlsbFwiIHdyYXA+XG4gICAgICA8ZWwtY2FyZCB2LWZvcj1cImkgaW4gM1wiIDprZXk9XCJpXCIgY2xhc3M9XCJib3gtY2FyZFwiPlxuICAgICAgICA8dGVtcGxhdGUgI2hlYWRlcj5cbiAgICAgICAgICA8ZGl2IGNsYXNzPVwiY2FyZC1oZWFkZXJcIj5cbiAgICAgICAgICAgIDxzcGFuPkNhcmQgbmFtZTwvc3Bhbj5cbiAgICAgICAgICAgIDxlbC1idXR0b24gY2xhc3M9XCJidXR0b25cIiB0ZXh0Pk9wZXJhdGlvbiBidXR0b248L2VsLWJ1dHRvbj5cbiAgICAgICAgICA8L2Rpdj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPGRpdiB2LWZvcj1cIm8gaW4gNFwiIDprZXk9XCJvXCIgY2xhc3M9XCJ0ZXh0IGl0ZW1cIj5cbiAgICAgICAgICB7eyAnTGlzdCBpdGVtICcgKyBvIH19XG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jYXJkPlxuICAgIDwvZWwtc3BhY2U+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgZmlsbCA9IHJlZih0cnVlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/space/fill.vue)_

vue

```
<template>
  <div>
    <div style="margin-bottom: 15px">fill: <el-switch v-model="fill" /></div>
    <el-space :fill="fill" wrap>
      <el-card v-for="i in 3" :key="i" class="box-card">
        <template #header>
          <div class="card-header">
            <span>Card name</span>
            <el-button class="button" text>Operation button</el-button>
          </div>
        </template>
        <div v-for="o in 4" :key="o" class="text item">
          {{ 'List item ' + o }}
        </div>
      </el-card>
    </el-space>
  </div>
</template>

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

const fill = ref(true)
</script>
```

隐藏源代码

也可以使用 `fillRatio` 参数，自定义填充的比例， 默认值为 `100`，代表基于父容器宽度的 `100%` 进行填充

需要注意的是，水平布局和垂直布局的表现形式稍有不同，具体的效果可以查看下面的例子

用 fillRatio 自定义填充比例

direction: horizontalvertical

fillRatio:

Card nameOperation button

List item 1

List item 2

List item 3

List item 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxkaXYgc3R5bGU9XCJtYXJnaW4tYm90dG9tOiAxNXB4XCI+XG4gICAgICBkaXJlY3Rpb246XG4gICAgICA8ZWwtcmFkaW8gdi1tb2RlbD1cImRpcmVjdGlvblwiIHZhbHVlPVwiaG9yaXpvbnRhbFwiPmhvcml6b250YWw8L2VsLXJhZGlvPlxuICAgICAgPGVsLXJhZGlvIHYtbW9kZWw9XCJkaXJlY3Rpb25cIiB2YWx1ZT1cInZlcnRpY2FsXCI+dmVydGljYWw8L2VsLXJhZGlvPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgc3R5bGU9XCJtYXJnaW4tYm90dG9tOiAxNXB4XCI+XG4gICAgICBmaWxsUmF0aW86PGVsLXNsaWRlciB2LW1vZGVsPVwiZmlsbFJhdGlvXCIgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZWwtc3BhY2VcbiAgICAgIGZpbGxcbiAgICAgIHdyYXBcbiAgICAgIDpmaWxsLXJhdGlvPVwiZmlsbFJhdGlvXCJcbiAgICAgIDpkaXJlY3Rpb249XCJkaXJlY3Rpb25cIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMTAwJVwiXG4gICAgPlxuICAgICAgPGVsLWNhcmQgdi1mb3I9XCJpIGluIDVcIiA6a2V5PVwiaVwiIGNsYXNzPVwiYm94LWNhcmRcIj5cbiAgICAgICAgPHRlbXBsYXRlICNoZWFkZXI+XG4gICAgICAgICAgPGRpdiBjbGFzcz1cImNhcmQtaGVhZGVyXCI+XG4gICAgICAgICAgICA8c3Bhbj5DYXJkIG5hbWU8L3NwYW4+XG4gICAgICAgICAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiYnV0dG9uXCIgdGV4dD5PcGVyYXRpb24gYnV0dG9uPC9lbC1idXR0b24+XG4gICAgICAgICAgPC9kaXY+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDxkaXYgdi1mb3I9XCJvIGluIDRcIiA6a2V5PVwib1wiIGNsYXNzPVwidGV4dCBpdGVtXCI+XG4gICAgICAgICAge3sgJ0xpc3QgaXRlbSAnICsgbyB9fVxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZWwtY2FyZD5cbiAgICA8L2VsLXNwYWNlPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgU3BhY2VJbnN0YW5jZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgZGlyZWN0aW9uID0gcmVmPFNwYWNlSW5zdGFuY2VbJ2RpcmVjdGlvbiddPignaG9yaXpvbnRhbCcpXG5jb25zdCBmaWxsUmF0aW8gPSByZWYoMzApXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/space/fill-ratio.vue)_

vue

```
<template>
  <div>
    <div style="margin-bottom: 15px">
      direction:
      <el-radio v-model="direction" value="horizontal">horizontal</el-radio>
      <el-radio v-model="direction" value="vertical">vertical</el-radio>
    </div>
    <div style="margin-bottom: 15px">
      fillRatio:<el-slider v-model="fillRatio" />
    </div>
    <el-space
      fill
      wrap
      :fill-ratio="fillRatio"
      :direction="direction"
      style="width: 100%"
    >
      <el-card v-for="i in 5" :key="i" class="box-card">
        <template #header>
          <div class="card-header">
            <span>Card name</span>
            <el-button class="button" text>Operation button</el-button>
          </div>
        </template>
        <div v-for="o in 4" :key="o" class="text item">
          {{ 'List item ' + o }}
        </div>
      </el-card>
    </el-space>
  </div>
</template>

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

import type { SpaceInstance } from 'element-plus'

const direction = ref<SpaceInstance['direction']>('horizontal')
const fillRatio = ref(30)
</script>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| alignment | 对齐的方式 | `enum` [align-items](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items) | center |
| class | className | `string` / `object` / `array` | — |
| direction | 排列的方向 | `enum` | horizontal |
| prefix-cls | 给 space-items 的类名前缀 | `string` | — |
| style | 额外样式 | `string` / `object` | — |
| spacer | 间隔符 | `string` / `number` / `VNode` | — |
| size | 间隔大小 | `enum` / `number` / `array` | small |
| wrap | 设置是否自动折行 | `boolean` | false |
| fill | 子元素是否填充父容器 | `boolean` | false |
| fill-ratio | 填充父容器的比例 | `number` | 100 |

### Slots [​](#slots)

| 名称 | 说明 |
| --- | --- |
| default | 需要添加间隔的元素 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/space) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/space.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/space.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/35091020?v=4&size=64)](https://github.com/zzh948498)[![](https://avatars.githubusercontent.com/u/43134418?v=4&size=64)](https://github.com/MonsterPi13)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/31943807?v=4&size=64)](https://github.com/ayay459547)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)

[Scrollbar 滚动条](https://element-plus.org/zh-CN/component/scrollbar)

[Splitter 分隔面板](https://element-plus.org/zh-CN/component/splitter)




---
## [basic/splitter] Splitter 分隔面板
> 官方文档: https://element-plus.org/zh-CN/component/splitter.html

---

# Splitter 分隔面板 beta [​](#splitter-分隔面板)

更新日志待解决

5

可将区域水平或垂直分隔，并可自由拖动以调整各个区域的大小。

## 基础用法 [​](#基础用法)

最基本的用法，如果未传入默认尺寸，将自动平均分配。

1

2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2XG4gICAgc3R5bGU9XCJoZWlnaHQ6IDI1MHB4OyBib3gtc2hhZG93OiB2YXIoLS1lbC1ib3JkZXItY29sb3ItbGlnaHQpIDBweCAwcHggMTBweFwiXG4gID5cbiAgICA8ZWwtc3BsaXR0ZXI+XG4gICAgICA8ZWwtc3BsaXR0ZXItcGFuZWwgc2l6ZT1cIjMwJVwiPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiZGVtby1wYW5lbFwiPjE8L2Rpdj5cbiAgICAgIDwvZWwtc3BsaXR0ZXItcGFuZWw+XG4gICAgICA8ZWwtc3BsaXR0ZXItcGFuZWwgOm1pbj1cIjIwMFwiPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiZGVtby1wYW5lbFwiPjI8L2Rpdj5cbiAgICAgIDwvZWwtc3BsaXR0ZXItcGFuZWw+XG4gICAgPC9lbC1zcGxpdHRlcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tcGFuZWwge1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBqdXN0aWZ5LWNvbnRlbnQ6IGNlbnRlcjtcbiAgaGVpZ2h0OiAxMDAlO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/splitter/basic.vue)_

vue

```
<template>
  <div
    style="height: 250px; box-shadow: var(--el-border-color-light) 0px 0px 10px"
  >
    <el-splitter>
      <el-splitter-panel size="30%">
        <div class="demo-panel">1</div>
      </el-splitter-panel>
      <el-splitter-panel :min="200">
        <div class="demo-panel">2</div>
      </el-splitter-panel>
    </el-splitter>
  </div>
</template>

<style scoped>
.demo-panel {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
}
</style>
```

隐藏源代码

## 垂直布局 [​](#垂直布局)

使用垂直方向。

1

2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2XG4gICAgc3R5bGU9XCJoZWlnaHQ6IDI1MHB4OyBib3gtc2hhZG93OiB2YXIoLS1lbC1ib3JkZXItY29sb3ItbGlnaHQpIDBweCAwcHggMTBweFwiXG4gID5cbiAgICA8ZWwtc3BsaXR0ZXIgbGF5b3V0PVwidmVydGljYWxcIj5cbiAgICAgIDxlbC1zcGxpdHRlci1wYW5lbD5cbiAgICAgICAgPGRpdiBjbGFzcz1cImRlbW8tcGFuZWxcIj4xPC9kaXY+XG4gICAgICA8L2VsLXNwbGl0dGVyLXBhbmVsPlxuICAgICAgPGVsLXNwbGl0dGVyLXBhbmVsPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiZGVtby1wYW5lbFwiPjI8L2Rpdj5cbiAgICAgIDwvZWwtc3BsaXR0ZXItcGFuZWw+XG4gICAgPC9lbC1zcGxpdHRlcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tcGFuZWwge1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBqdXN0aWZ5LWNvbnRlbnQ6IGNlbnRlcjtcbiAgaGVpZ2h0OiAxMDAlO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/splitter/vertical.vue)_

vue

```
<template>
  <div
    style="height: 250px; box-shadow: var(--el-border-color-light) 0px 0px 10px"
  >
    <el-splitter layout="vertical">
      <el-splitter-panel>
        <div class="demo-panel">1</div>
      </el-splitter-panel>
      <el-splitter-panel>
        <div class="demo-panel">2</div>
      </el-splitter-panel>
    </el-splitter>
  </div>
</template>

<style scoped>
.demo-panel {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
}
</style>
```

隐藏源代码

## 可折叠 [​](#可折叠)

配置 `collapsible` 可提供快速收缩功能。 你可以使用 `min` 属性来防止折叠后通过拖拽进行扩展。

enable

1

2

3

4

5

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoXG4gICAgdi1tb2RlbD1cImlzQ29sbGFwc2libGVcIlxuICAgIGFjdGl2ZS10ZXh0PVwiZW5hYmxlXCJcbiAgICBpbmFjdGl2ZS10ZXh0PVwiZGlzYWJsZVwiXG4gICAgaW5saW5lLXByb21wdFxuICAgIGNsYXNzPVwibWItMlwiXG4gIC8+XG4gIDxkaXZcbiAgICBzdHlsZT1cImhlaWdodDogMjUwcHg7IGJveC1zaGFkb3c6IHZhcigtLWVsLWJvcmRlci1jb2xvci1saWdodCkgMHB4IDBweCAxMHB4XCJcbiAgPlxuICAgIDxlbC1zcGxpdHRlcj5cbiAgICAgIDxlbC1zcGxpdHRlci1wYW5lbCA6Y29sbGFwc2libGU9XCJpc0NvbGxhcHNpYmxlXCIgbWluPVwiNTBcIj5cbiAgICAgICAgPGRpdiBjbGFzcz1cImRlbW8tcGFuZWxcIj4xPC9kaXY+XG4gICAgICA8L2VsLXNwbGl0dGVyLXBhbmVsPlxuICAgICAgPGVsLXNwbGl0dGVyLXBhbmVsIDpjb2xsYXBzaWJsZT1cImlzQ29sbGFwc2libGVcIj5cbiAgICAgICAgPGRpdiBjbGFzcz1cImRlbW8tcGFuZWxcIj4yPC9kaXY+XG4gICAgICA8L2VsLXNwbGl0dGVyLXBhbmVsPlxuICAgICAgPGVsLXNwbGl0dGVyLXBhbmVsPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiZGVtby1wYW5lbFwiPjM8L2Rpdj5cbiAgICAgIDwvZWwtc3BsaXR0ZXItcGFuZWw+XG4gICAgICA8ZWwtc3BsaXR0ZXItcGFuZWwgOmNvbGxhcHNpYmxlPVwiaXNDb2xsYXBzaWJsZVwiPlxuICAgICAgICA8ZWwtc3BsaXR0ZXIgbGF5b3V0PVwidmVydGljYWxcIj5cbiAgICAgICAgICA8ZWwtc3BsaXR0ZXItcGFuZWwgOmNvbGxhcHNpYmxlPVwiaXNDb2xsYXBzaWJsZVwiPlxuICAgICAgICAgICAgPGRpdiBjbGFzcz1cImRlbW8tcGFuZWxcIj40PC9kaXY+XG4gICAgICAgICAgPC9lbC1zcGxpdHRlci1wYW5lbD5cbiAgICAgICAgICA8ZWwtc3BsaXR0ZXItcGFuZWwgOmNvbGxhcHNpYmxlPVwiaXNDb2xsYXBzaWJsZVwiPlxuICAgICAgICAgICAgPGRpdiBjbGFzcz1cImRlbW8tcGFuZWxcIj41PC9kaXY+XG4gICAgICAgICAgPC9lbC1zcGxpdHRlci1wYW5lbD5cbiAgICAgICAgPC9lbC1zcGxpdHRlcj5cbiAgICAgIDwvZWwtc3BsaXR0ZXItcGFuZWw+XG4gICAgPC9lbC1zcGxpdHRlcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBpc0NvbGxhcHNpYmxlID0gcmVmKHRydWUpXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLXBhbmVsIHtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbiAganVzdGlmeS1jb250ZW50OiBjZW50ZXI7XG4gIGhlaWdodDogMTAwJTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/splitter/collapsible.vue)_

vue

```
<template>
  <el-switch
    v-model="isCollapsible"
    active-text="enable"
    inactive-text="disable"
    inline-prompt
    class="mb-2"
  />
  <div
    style="height: 250px; box-shadow: var(--el-border-color-light) 0px 0px 10px"
  >
    <el-splitter>
      <el-splitter-panel :collapsible="isCollapsible" min="50">
        <div class="demo-panel">1</div>
      </el-splitter-panel>
      <el-splitter-panel :collapsible="isCollapsible">
        <div class="demo-panel">2</div>
      </el-splitter-panel>
      <el-splitter-panel>
        <div class="demo-panel">3</div>
      </el-splitter-panel>
      <el-splitter-panel :collapsible="isCollapsible">
        <el-splitter layout="vertical">
          <el-splitter-panel :collapsible="isCollapsible">
            <div class="demo-panel">4</div>
          </el-splitter-panel>
          <el-splitter-panel :collapsible="isCollapsible">
            <div class="demo-panel">5</div>
          </el-splitter-panel>
        </el-splitter>
      </el-splitter-panel>
    </el-splitter>
  </div>
</template>

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

const isCollapsible = ref(true)
</script>

<style scoped>
.demo-panel {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
}
</style>
```

隐藏源代码

## 禁用拖动 [​](#禁用拖动)

当任一面板禁用 `resizable` 时，拖拽功能将被禁用。

disable

1

drag disable

3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoXG4gICAgdi1tb2RlbD1cInJlc2l6YWJsZVwiXG4gICAgYWN0aXZlLXRleHQ9XCJlbmFibGVcIlxuICAgIGluYWN0aXZlLXRleHQ9XCJkaXNhYmxlXCJcbiAgICBpbmxpbmUtcHJvbXB0XG4gICAgY2xhc3M9XCJtYi0yXCJcbiAgLz5cbiAgPGRpdlxuICAgIHN0eWxlPVwiaGVpZ2h0OiAyNTBweDsgYm94LXNoYWRvdzogdmFyKC0tZWwtYm9yZGVyLWNvbG9yLWxpZ2h0KSAwcHggMHB4IDEwcHhcIlxuICA+XG4gICAgPGVsLXNwbGl0dGVyPlxuICAgICAgPGVsLXNwbGl0dGVyLXBhbmVsPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiZGVtby1wYW5lbFwiPjE8L2Rpdj5cbiAgICAgIDwvZWwtc3BsaXR0ZXItcGFuZWw+XG4gICAgICA8ZWwtc3BsaXR0ZXItcGFuZWwgOnJlc2l6YWJsZT1cInJlc2l6YWJsZVwiPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiZGVtby1wYW5lbFwiPlxuICAgICAgICAgIGRyYWcge3sgcmVzaXphYmxlID8gJ2VuYWJsZScgOiAnZGlzYWJsZScgfX1cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2VsLXNwbGl0dGVyLXBhbmVsPlxuICAgICAgPGVsLXNwbGl0dGVyLXBhbmVsPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiZGVtby1wYW5lbFwiPjM8L2Rpdj5cbiAgICAgIDwvZWwtc3BsaXR0ZXItcGFuZWw+XG4gICAgPC9lbC1zcGxpdHRlcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCByZXNpemFibGUgPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLXBhbmVsIHtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbiAganVzdGlmeS1jb250ZW50OiBjZW50ZXI7XG4gIGhlaWdodDogMTAwJTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/splitter/disableDrag.vue)_

vue

```
<template>
  <el-switch
    v-model="resizable"
    active-text="enable"
    inactive-text="disable"
    inline-prompt
    class="mb-2"
  />
  <div
    style="height: 250px; box-shadow: var(--el-border-color-light) 0px 0px 10px"
  >
    <el-splitter>
      <el-splitter-panel>
        <div class="demo-panel">1</div>
      </el-splitter-panel>
      <el-splitter-panel :resizable="resizable">
        <div class="demo-panel">
          drag {{ resizable ? 'enable' : 'disable' }}
        </div>
      </el-splitter-panel>
      <el-splitter-panel>
        <div class="demo-panel">3</div>
      </el-splitter-panel>
    </el-splitter>
  </div>
</template>

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

const resizable = ref(false)
</script>

<style scoped>
.demo-panel {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
}
</style>
```

隐藏源代码

## 面板大小 [​](#面板大小)

`v-model:size` 可以获取面板的大小。

1

100px

3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2XG4gICAgc3R5bGU9XCJoZWlnaHQ6IDI1MHB4OyBib3gtc2hhZG93OiB2YXIoLS1lbC1ib3JkZXItY29sb3ItbGlnaHQpIDBweCAwcHggMTBweFwiXG4gID5cbiAgICA8ZWwtc3BsaXR0ZXJcbiAgICAgIEByZXNpemUtc3RhcnQ9XCJoYW5kbGVSZXNpemVTdGFydFwiXG4gICAgICBAcmVzaXplLWVuZD1cImhhbmRsZVJlc2l6ZUVuZFwiXG4gICAgICBAcmVzaXplPVwiaGFuZGxlUmVzaXplXCJcbiAgICA+XG4gICAgICA8ZWwtc3BsaXR0ZXItcGFuZWw+XG4gICAgICAgIDxkaXYgY2xhc3M9XCJkZW1vLXBhbmVsXCI+MTwvZGl2PlxuICAgICAgPC9lbC1zcGxpdHRlci1wYW5lbD5cbiAgICAgIDxlbC1zcGxpdHRlci1wYW5lbCB2LW1vZGVsOnNpemU9XCJzaXplXCIgOm1heD1cIjIwMFwiIDptaW49XCI1MFwiPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiZGVtby1wYW5lbFwiPnt7IHNpemUgfX1weDwvZGl2PlxuICAgICAgPC9lbC1zcGxpdHRlci1wYW5lbD5cbiAgICAgIDxlbC1zcGxpdHRlci1wYW5lbD5cbiAgICAgICAgPGRpdiBjbGFzcz1cImRlbW8tcGFuZWxcIj4zPC9kaXY+XG4gICAgICA8L2VsLXNwbGl0dGVyLXBhbmVsPlxuICAgIDwvZWwtc3BsaXR0ZXI+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3Qgc2l6ZSA9IHJlZigxMDApXG5cbmNvbnN0IGhhbmRsZVJlc2l6ZVN0YXJ0ID0gKGluZGV4OiBudW1iZXIsIHNpemVzOiBudW1iZXJbXSkgPT4ge1xuICBjb25zb2xlLmxvZygncmVzaXplU3RhcnQnLCBpbmRleCwgc2l6ZXMpXG59XG5cbmNvbnN0IGhhbmRsZVJlc2l6ZSA9IChpbmRleDogbnVtYmVyLCBzaXplczogbnVtYmVyW10pID0+IHtcbiAgY29uc29sZS5sb2coJ3Jlc2l6ZScsIGluZGV4LCBzaXplcylcbn1cblxuY29uc3QgaGFuZGxlUmVzaXplRW5kID0gKGluZGV4OiBudW1iZXIsIHNpemVzOiBudW1iZXJbXSkgPT4ge1xuICBjb25zb2xlLmxvZygncmVzaXplRW5kJywgaW5kZXgsIHNpemVzKVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1wYW5lbCB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG4gIGp1c3RpZnktY29udGVudDogY2VudGVyO1xuICBoZWlnaHQ6IDEwMCU7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/splitter/size.vue)_

vue

```
<template>
  <div
    style="height: 250px; box-shadow: var(--el-border-color-light) 0px 0px 10px"
  >
    <el-splitter
      @resize-start="handleResizeStart"
      @resize-end="handleResizeEnd"
      @resize="handleResize"
    >
      <el-splitter-panel>
        <div class="demo-panel">1</div>
      </el-splitter-panel>
      <el-splitter-panel v-model:size="size" :max="200" :min="50">
        <div class="demo-panel">{{ size }}px</div>
      </el-splitter-panel>
      <el-splitter-panel>
        <div class="demo-panel">3</div>
      </el-splitter-panel>
    </el-splitter>
  </div>
</template>

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

const size = ref(100)

const handleResizeStart = (index: number, sizes: number[]) => {
  console.log('resizeStart', index, sizes)
}

const handleResize = (index: number, sizes: number[]) => {
  console.log('resize', index, sizes)
}

const handleResizeEnd = (index: number, sizes: number[]) => {
  console.log('resizeEnd', index, sizes)
}
</script>

<style scoped>
.demo-panel {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
}
</style>
```

隐藏源代码

## 延迟2.11.0 [​](#延迟)

当启用`lazy`时，面板大小将不会在拖动时实时更新，只能在拖动结束后更新。

1

2

3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2XG4gICAgc3R5bGU9XCJoZWlnaHQ6IDI1MHB4OyBib3gtc2hhZG93OiB2YXIoLS1lbC1ib3JkZXItY29sb3ItbGlnaHQpIDBweCAwcHggMTBweFwiXG4gID5cbiAgICA8ZWwtc3BsaXR0ZXIgbGF6eT5cbiAgICAgIDxlbC1zcGxpdHRlci1wYW5lbCBjb2xsYXBzaWJsZSBtaW49XCI1MFwiPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiZGVtby1wYW5lbFwiPjE8L2Rpdj5cbiAgICAgIDwvZWwtc3BsaXR0ZXItcGFuZWw+XG4gICAgICA8ZWwtc3BsaXR0ZXItcGFuZWwgY29sbGFwc2libGU+XG4gICAgICAgIDxkaXYgY2xhc3M9XCJkZW1vLXBhbmVsXCI+MjwvZGl2PlxuICAgICAgPC9lbC1zcGxpdHRlci1wYW5lbD5cbiAgICAgIDxlbC1zcGxpdHRlci1wYW5lbCBjb2xsYXBzaWJsZT5cbiAgICAgICAgPGRpdiBjbGFzcz1cImRlbW8tcGFuZWxcIj4zPC9kaXY+XG4gICAgICA8L2VsLXNwbGl0dGVyLXBhbmVsPlxuICAgIDwvZWwtc3BsaXR0ZXI+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLXBhbmVsIHtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbiAganVzdGlmeS1jb250ZW50OiBjZW50ZXI7XG4gIGhlaWdodDogMTAwJTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/splitter/lazy.vue)_

vue

```
<template>
  <div
    style="height: 250px; box-shadow: var(--el-border-color-light) 0px 0px 10px"
  >
    <el-splitter lazy>
      <el-splitter-panel collapsible min="50">
        <div class="demo-panel">1</div>
      </el-splitter-panel>
      <el-splitter-panel collapsible>
        <div class="demo-panel">2</div>
      </el-splitter-panel>
      <el-splitter-panel collapsible>
        <div class="demo-panel">3</div>
      </el-splitter-panel>
    </el-splitter>
  </div>
</template>

<style scoped>
.demo-panel {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
}
</style>
```

隐藏源代码

## Splitter API [​](#splitter-api)

### Splitter Attributes [​](#splitter-attributes)

| 名称 | 详情 | 类型 | 默认值 |
| --- | --- | --- | --- |
| layout | 分隔面板的布局方向 | `enum` | horizontal |
| lazy 2.11.0 | 是否使用懒加载 | `boolean` | false |

### Splitter Events [​](#splitter-events)

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| resize-start | 开始调整面板大小时触发，`index` 是拖拽条的索引。 | `Function` |
| resize | 调整面板大小时触发，`index` 是拖拽条的索引。 | `Function` |
| resize-end | 面板调整大小结束时触发，`index` 是拖拽条的索引。 | `Function` |
| collapse 2.10.3 | 当面板折叠时触发，`index` 是拖拽条的索引。 | `Function` |

## SplitterPanel API [​](#splitterpanel-api)

### SplitterPanel Attributes [​](#splitterpanel-attributes)

| 名称 | 描述 | 类型 | 默认值 |
| --- | --- | --- | --- |
| size / v-model:size | 面板大小(像素或百分比) | `string` / `number` | \- |
| min | 面板最小尺寸(像素或百分比) | `string` / `number` | \- |
| max | 面板的最大尺寸(像素或百分比) | `string` / `number` | \- |
| resizable | 是否可以调整面板大小 | `boolean` | true |
| collapsible | 面板是否可折叠。 | `boolean` | false |

### SplitterPanel Events [​](#splitterpanel-events)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| update:size | 当面板大小改变时触发 | `Function` |

### SplitterPanel Slots [​](#splitterpanel-slots)

| 插槽名 | 详情 |
| --- | --- |
| default | 面板的默认内容 |
| start-collapsible | 自定义起始折叠按钮的内容 |
| end-collapsible | 结束可折叠按钮的自定义内容 |

### SplitterPanel Exposes [​](#splitterpanel-exposes)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| splitterPanelRef 2.11.9 | SplitterPanel html 元素 | `object` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/splitter) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/splitter.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/splitter.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/25793232?v=4&size=64)](https://github.com/Bigpawn)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/57785259?v=4&size=64)](https://github.com/w2xi)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/31533594?v=4&size=64)](https://github.com/Gnalvin)[![](https://avatars.githubusercontent.com/u/20151622?v=4&size=64)](https://github.com/william-xue)

[Space 间距](https://element-plus.org/zh-CN/component/space)

[Typography 排版](https://element-plus.org/zh-CN/component/typography)




---
## [basic/typography] Typography 排版
> 官方文档: https://element-plus.org/zh-CN/component/typography.html

---

# Typography 排版 [​](#typography-排版)

我们对字体进行统一规范，力求在各个操作系统下都有最佳展示效果。

## 字体 [​](#字体)

![](https://element-plus.org/images/typography/term-pingfang.png)![](https://element-plus.org/images/typography/term-hiragino.png)![](https://element-plus.org/images/typography/term-microsoft.png)![](https://element-plus.org/images/typography/term-helvetica.png)![](https://element-plus.org/images/typography/term-arial.png)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IGlzRGFyayB9IGZyb20gJ34vY29tcG9zYWJsZXMvZGFyaydcbjwvc2NyaXB0PlxuXG48dGVtcGxhdGU+XG4gIDxkaXYgdi1pZj1cIiFpc0RhcmtcIiBjbGFzcz1cImRlbW8tdGVybS1ib3hcIj5cbiAgICA8aW1nIHNyYz1cIi9pbWFnZXMvdHlwb2dyYXBoeS90ZXJtLXBpbmdmYW5nLnBuZ1wiIGFsdD1cIlwiIC8+XG4gICAgPGltZyBzcmM9XCIvaW1hZ2VzL3R5cG9ncmFwaHkvdGVybS1oaXJhZ2luby5wbmdcIiBhbHQ9XCJcIiAvPlxuICAgIDxpbWcgc3JjPVwiL2ltYWdlcy90eXBvZ3JhcGh5L3Rlcm0tbWljcm9zb2Z0LnBuZ1wiIGFsdD1cIlwiIC8+XG4gICAgPGltZyBzcmM9XCIvaW1hZ2VzL3R5cG9ncmFwaHkvdGVybS1oZWx2ZXRpY2EucG5nXCIgYWx0PVwiXCIgLz5cbiAgICA8aW1nIHNyYz1cIi9pbWFnZXMvdHlwb2dyYXBoeS90ZXJtLWFyaWFsLnBuZ1wiIGFsdD1cIlwiIC8+XG4gIDwvZGl2PlxuICA8ZGl2IHYtZWxzZSBjbGFzcz1cImRlbW8tdGVybS1ib3hcIj5cbiAgICA8aW1nIHNyYz1cIi9pbWFnZXMvdHlwb2dyYXBoeS90ZXJtLXBpbmdmYW5nLWRhcmsucG5nXCIgYWx0PVwiXCIgLz5cbiAgICA8aW1nIHNyYz1cIi9pbWFnZXMvdHlwb2dyYXBoeS90ZXJtLWhpcmFnaW5vLWRhcmsucG5nXCIgYWx0PVwiXCIgLz5cbiAgICA8aW1nIHNyYz1cIi9pbWFnZXMvdHlwb2dyYXBoeS90ZXJtLW1pY3Jvc29mdC1kYXJrLnBuZ1wiIGFsdD1cIlwiIC8+XG4gICAgPGltZyBzcmM9XCIvaW1hZ2VzL3R5cG9ncmFwaHkvdGVybS1oZWx2ZXRpY2EtZGFyay5wbmdcIiBhbHQ9XCJcIiAvPlxuICAgIDxpbWcgc3JjPVwiL2ltYWdlcy90eXBvZ3JhcGh5L3Rlcm0tYXJpYWwtZGFyay5wbmdcIiBhbHQ9XCJcIiAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZSBzY29wZWQ+XG5pbWcge1xuICB3aWR0aDogMjIwcHg7XG4gIGhlaWdodDogMTc0cHg7XG4gIG1hcmdpbjogMCAyNHB4IDI0cHggMDtcbn1cbmltZzpudGgtb2YtdHlwZSgzKSB7XG4gIG1hcmdpbi1yaWdodDogMDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/typography/font.vue)_

vue

```
<script lang="ts" setup>
import { isDark } from '~/composables/dark'
</script>

<template>
  <div v-if="!isDark" class="demo-term-box">
    <img src="/images/typography/term-pingfang.png" alt="" />
    <img src="/images/typography/term-hiragino.png" alt="" />
    <img src="/images/typography/term-microsoft.png" alt="" />
    <img src="/images/typography/term-helvetica.png" alt="" />
    <img src="/images/typography/term-arial.png" alt="" />
  </div>
  <div v-else class="demo-term-box">
    <img src="/images/typography/term-pingfang-dark.png" alt="" />
    <img src="/images/typography/term-hiragino-dark.png" alt="" />
    <img src="/images/typography/term-microsoft-dark.png" alt="" />
    <img src="/images/typography/term-helvetica-dark.png" alt="" />
    <img src="/images/typography/term-arial-dark.png" alt="" />
  </div>
</template>

<style scoped>
img {
  width: 220px;
  height: 174px;
  margin: 0 24px 24px 0;
}
img:nth-of-type(3) {
  margin-right: 0;
}
</style>
```

隐藏源代码

## 字号 [​](#字号)

<table class="demo-typo-size"><tbody><tr><td>Level</td><td>Font Size</td><td class="color-dark-light">Demo</td></tr><tr style="font-size: var(--el-font-size-extra-small)"><td>Supplementary text</td><td>12px Extra Small</td><td>Build with Element</td></tr><tr style="font-size: var(--el-font-size-small)"><td>Body (small)</td><td>13px Small</td><td>Build with Element</td></tr><tr style="font-size: var(--el-font-size-base)"><td>Body</td><td>14px Base</td><td>Build with Element</td></tr><tr style="font-size: var(--el-font-size-medium)"><td>Small Title</td><td>16px Medium</td><td>Build with Element</td></tr><tr style="font-size: var(--el-font-size-large)"><td>Title</td><td>18px Large</td><td>Build with Element</td></tr><tr style="font-size: var(--el-font-size-extra-large)"><td>Main Title</td><td>20px Extra Large</td><td>Build with Element</td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/?extra_packages=%40vueuse%2Fcore#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8dGFibGUgY2xhc3M9XCJkZW1vLXR5cG8tc2l6ZVwiPlxuICAgIDx0Ym9keT5cbiAgICAgIDx0cj5cbiAgICAgICAgPHRkPkxldmVsPC90ZD5cbiAgICAgICAgPHRkPkZvbnQgU2l6ZTwvdGQ+XG4gICAgICAgIDx0ZCBjbGFzcz1cImNvbG9yLWRhcmstbGlnaHRcIj5EZW1vPC90ZD5cbiAgICAgIDwvdHI+XG4gICAgICA8dHJcbiAgICAgICAgdi1mb3I9XCIoZm9udFNpemUsIGkpIGluIGZvbnRTaXplc1wiXG4gICAgICAgIDprZXk9XCJpXCJcbiAgICAgICAgOnN0eWxlPVwiYGZvbnQtc2l6ZTogdmFyKC0tZWwtZm9udC1zaXplLSR7Zm9udFNpemUudHlwZX0pYFwiXG4gICAgICA+XG4gICAgICAgIDx0ZD57eyBmb250U2l6ZS5sZXZlbCB9fTwvdGQ+XG4gICAgICAgIDx0ZD5cbiAgICAgICAgICB7e1xuICAgICAgICAgICAgdXNlQ3NzVmFyKGAtLWVsLWZvbnQtc2l6ZS0ke2ZvbnRTaXplLnR5cGV9YCkudmFsdWUgK1xuICAgICAgICAgICAgJyAnICtcbiAgICAgICAgICAgIGZvcm1hdFR5cGUoZm9udFNpemUudHlwZSlcbiAgICAgICAgICB9fVxuICAgICAgICA8L3RkPlxuICAgICAgICA8dGQ+QnVpbGQgd2l0aCBFbGVtZW50PC90ZD5cbiAgICAgIDwvdHI+XG4gICAgPC90Ym9keT5cbiAgPC90YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyB1c2VDc3NWYXIgfSBmcm9tICdAdnVldXNlL2NvcmUnXG5cbmNvbnN0IGZvbnRTaXplcyA9IFtcbiAge1xuICAgIGxldmVsOiAnU3VwcGxlbWVudGFyeSB0ZXh0JyxcbiAgICB0eXBlOiAnZXh0cmEtc21hbGwnLFxuICB9LFxuICB7XG4gICAgbGV2ZWw6ICdCb2R5IChzbWFsbCknLFxuICAgIHR5cGU6ICdzbWFsbCcsXG4gIH0sXG4gIHtcbiAgICBsZXZlbDogJ0JvZHknLFxuICAgIHR5cGU6ICdiYXNlJyxcbiAgfSxcbiAge1xuICAgIGxldmVsOiAnU21hbGwgVGl0bGUnLFxuICAgIHR5cGU6ICdtZWRpdW0nLFxuICB9LFxuICB7XG4gICAgbGV2ZWw6ICdUaXRsZScsXG4gICAgdHlwZTogJ2xhcmdlJyxcbiAgfSxcbiAge1xuICAgIGxldmVsOiAnTWFpbiBUaXRsZScsXG4gICAgdHlwZTogJ2V4dHJhLWxhcmdlJyxcbiAgfSxcbl1cblxuZnVuY3Rpb24gZm9ybWF0VHlwZSh0eXBlOiBzdHJpbmcpIHtcbiAgcmV0dXJuIHR5cGVcbiAgICAuc3BsaXQoJy0nKVxuICAgIC5tYXAoKGl0ZW0pID0+IGl0ZW0uY2hhckF0KDApLnRvVXBwZXJDYXNlKCkgKyBpdGVtLnNsaWNlKDEpKVxuICAgIC5qb2luKCcgJylcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/typography/convention.vue)_

vue

```
<template>
  <table class="demo-typo-size">
    <tbody>
      <tr>
        <td>Level</td>
        <td>Font Size</td>
        <td class="color-dark-light">Demo</td>
      </tr>
      <tr
        v-for="(fontSize, i) in fontSizes"
        :key="i"
        :style="`font-size: var(--el-font-size-${fontSize.type})`"
      >
        <td>{{ fontSize.level }}</td>
        <td>
          {{
            useCssVar(`--el-font-size-${fontSize.type}`).value +
            ' ' +
            formatType(fontSize.type)
          }}
        </td>
        <td>Build with Element</td>
      </tr>
    </tbody>
  </table>
</template>

<script lang="ts" setup>
import { useCssVar } from '@vueuse/core'

const fontSizes = [
  {
    level: 'Supplementary text',
    type: 'extra-small',
  },
  {
    level: 'Body (small)',
    type: 'small',
  },
  {
    level: 'Body',
    type: 'base',
  },
  {
    level: 'Small Title',
    type: 'medium',
  },
  {
    level: 'Title',
    type: 'large',
  },
  {
    level: 'Main Title',
    type: 'extra-large',
  },
]

function formatType(type: string) {
  return type
    .split('-')
    .map((item) => item.charAt(0).toUpperCase() + item.slice(1))
    .join(' ')
}
</script>
```

隐藏源代码

## 行高 [​](#行高)

![](https://element-plus.org/images/typography/line-height.png)

-   line-height:1 No line height
-   line-height:1.3 Compact
-   line-height:1.5 Regular
-   line-height:1.7 Loose

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IGlzRGFyayB9IGZyb20gJ34vY29tcG9zYWJsZXMvZGFyaydcbjwvc2NyaXB0PlxuXG48dGVtcGxhdGU+XG4gIDxkaXY+XG4gICAgPGltZ1xuICAgICAgdi1pZj1cImlzRGFya1wiXG4gICAgICBjbGFzcz1cImxpbmVILWxlZnRcIlxuICAgICAgc3JjPVwiL2ltYWdlcy90eXBvZ3JhcGh5L2xpbmUtaGVpZ2h0LWRhcmsucG5nXCJcbiAgICAvPlxuICAgIDxpbWcgdi1lbHNlIGNsYXNzPVwibGluZUgtbGVmdFwiIHNyYz1cIi9pbWFnZXMvdHlwb2dyYXBoeS9saW5lLWhlaWdodC5wbmdcIiAvPlxuICAgIDx1bCBjbGFzcz1cImxpbmVILXJpZ2h0XCI+XG4gICAgICA8bGk+bGluZS1oZWlnaHQ6MSA8c3Bhbj5ObyBsaW5lIGhlaWdodDwvc3Bhbj48L2xpPlxuICAgICAgPGxpPmxpbmUtaGVpZ2h0OjEuMyA8c3Bhbj5Db21wYWN0PC9zcGFuPjwvbGk+XG4gICAgICA8bGk+bGluZS1oZWlnaHQ6MS41IDxzcGFuPlJlZ3VsYXI8L3NwYW4+PC9saT5cbiAgICAgIDxsaT5saW5lLWhlaWdodDoxLjcgPHNwYW4+TG9vc2U8L3NwYW4+PC9saT5cbiAgICA8L3VsPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/typography/line-height.vue)_

vue

```
<script lang="ts" setup>
import { isDark } from '~/composables/dark'
</script>

<template>
  <div>
    <img
      v-if="isDark"
      class="lineH-left"
      src="/images/typography/line-height-dark.png"
    />
    <img v-else class="lineH-left" src="/images/typography/line-height.png" />
    <ul class="lineH-right">
      <li>line-height:1 <span>No line height</span></li>
      <li>line-height:1.3 <span>Compact</span></li>
      <li>line-height:1.5 <span>Regular</span></li>
      <li>line-height:1.7 <span>Loose</span></li>
    </ul>
  </div>
</template>
```

隐藏源代码

## Font-family [​](#font-family)

css

```
font-family:
  Inter, 'Helvetica Neue', Helvetica, 'PingFang SC', 'Hiragino Sans GB',
  'Microsoft YaHei', '微软雅黑', Arial, sans-serif;
```

## 源代码 [​](#源代码)

[文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/typography.md)

[Splitter 分隔面板](https://element-plus.org/zh-CN/component/splitter)

[Config Provider 全局配置](https://element-plus.org/zh-CN/component/config-provider)




---

<!-- ============================================ -->
<!-- 类别: 配置组件 -->
<!-- ============================================ -->

## [config/config-provider] Config Provider 全局配置
> 官方文档: https://element-plus.org/zh-CN/component/config-provider.html

# Config Provider 全局配置 [​](#config-provider-全局配置)

Config Provider 被用来提供全局的配置选项，让你的配置能够在全局都能够被访问到。

## i18n 配置 [​](#i18n-配置)

通过 Config Provider 来配置多语言，让你的应用可以随时切换语言。

使用两个属性来提供 i18n 相关配置

暂无数据

-   1
-   2
-   3
-   4
-   5
-   6

-   10

前往

页

共 100 条

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1idXR0b24gbWItMiBAY2xpY2s9XCJ0b2dnbGVcIj5Td2l0Y2ggTGFuZ3VhZ2U8L2VsLWJ1dHRvbj5cbiAgICA8YnIgLz5cblxuICAgIDxlbC1jb25maWctcHJvdmlkZXIgOmxvY2FsZT1cImxvY2FsZVwiPlxuICAgICAgPGVsLXRhYmxlIG1iLTEgOmRhdGE9XCJbXVwiIC8+XG4gICAgICA8ZWwtcGFnaW5hdGlvbiA6dG90YWw9XCIxMDBcIiAvPlxuICAgIDwvZWwtY29uZmlnLXByb3ZpZGVyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBjb21wdXRlZCwgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHpoQ24gZnJvbSAnZWxlbWVudC1wbHVzL2VzL2xvY2FsZS9sYW5nL3poLWNuJ1xuaW1wb3J0IGVuIGZyb20gJ2VsZW1lbnQtcGx1cy9lcy9sb2NhbGUvbGFuZy9lbidcblxuY29uc3QgbGFuZ3VhZ2UgPSByZWYoJ3poLWNuJylcbmNvbnN0IGxvY2FsZSA9IGNvbXB1dGVkKCgpID0+IChsYW5ndWFnZS52YWx1ZSA9PT0gJ3poLWNuJyA/IHpoQ24gOiBlbikpXG5cbmNvbnN0IHRvZ2dsZSA9ICgpID0+IHtcbiAgbGFuZ3VhZ2UudmFsdWUgPSBsYW5ndWFnZS52YWx1ZSA9PT0gJ3poLWNuJyA/ICdlbicgOiAnemgtY24nXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/config-provider/usage.vue)_

vue

```
<template>
  <div>
    <el-button mb-2 @click="toggle">Switch Language</el-button>
    <br />

    <el-config-provider :locale="locale">
      <el-table mb-1 :data="[]" />
      <el-pagination :total="100" />
    </el-config-provider>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import en from 'element-plus/es/locale/lang/en'

const language = ref('zh-cn')
const locale = computed(() => (language.value === 'zh-cn' ? zhCn : en))

const toggle = () => {
  language.value = language.value === 'zh-cn' ? 'en' : 'zh-cn'
}
</script>
```

隐藏源代码

## 对按钮进行配置 [​](#对按钮进行配置)

autoInsertSpace plain round dashed text

default

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxkaXY+XG4gICAgICA8ZWwtY2hlY2tib3ggdi1tb2RlbD1cImNvbmZpZy5hdXRvSW5zZXJ0U3BhY2VcIj5cbiAgICAgICAgYXV0b0luc2VydFNwYWNlXG4gICAgICA8L2VsLWNoZWNrYm94PlxuICAgICAgPGVsLWNoZWNrYm94IHYtbW9kZWw9XCJjb25maWcucGxhaW5cIj4gcGxhaW4gPC9lbC1jaGVja2JveD5cbiAgICAgIDxlbC1jaGVja2JveCB2LW1vZGVsPVwiY29uZmlnLnJvdW5kXCI+IHJvdW5kIDwvZWwtY2hlY2tib3g+XG4gICAgICA8ZWwtY2hlY2tib3ggdi1tb2RlbD1cImNvbmZpZy5kYXNoZWRcIj4gZGFzaGVkIDwvZWwtY2hlY2tib3g+XG4gICAgICA8ZWwtY2hlY2tib3ggdi1tb2RlbD1cImNvbmZpZy50ZXh0XCI+IHRleHQgPC9lbC1jaGVja2JveD5cbiAgICAgIDxlbC1zZWxlY3Qgdi1tb2RlbD1cImNvbmZpZy50eXBlXCIgY2xhc3M9XCJtbC01XCIgc3R5bGU9XCJtYXgtd2lkdGg6IDE1MHB4XCI+XG4gICAgICAgIDxlbC1vcHRpb25cbiAgICAgICAgICB2LWZvcj1cInR5cGUgaW4gYnV0dG9uVHlwZXMuZmlsdGVyKEJvb2xlYW4pXCJcbiAgICAgICAgICA6a2V5PVwidHlwZVwiXG4gICAgICAgICAgOnZhbHVlPVwidHlwZVwiXG4gICAgICAgIC8+XG4gICAgICA8L2VsLXNlbGVjdD5cbiAgICA8L2Rpdj5cbiAgICA8ZWwtZGl2aWRlciAvPlxuICAgIDxlbC1jb25maWctcHJvdmlkZXIgOmJ1dHRvbj1cImNvbmZpZ1wiPlxuICAgICAgPGVsLWJ1dHRvbj7kuK3mloc8L2VsLWJ1dHRvbj5cbiAgICA8L2VsLWNvbmZpZy1wcm92aWRlcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVhY3RpdmUgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBidXR0b25UeXBlcyB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuaW1wb3J0IHR5cGUgeyBCdXR0b25Db25maWdDb250ZXh0IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBjb25maWcgPSByZWFjdGl2ZTxCdXR0b25Db25maWdDb250ZXh0Pih7XG4gIGF1dG9JbnNlcnRTcGFjZTogdHJ1ZSxcbiAgdHlwZTogJ2RlZmF1bHQnLFxuICBwbGFpbjogdHJ1ZSxcbiAgcm91bmQ6IHRydWUsXG4gIHRleHQ6IGZhbHNlLFxuICBkYXNoZWQ6IGZhbHNlLFxufSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/config-provider/button.vue)_

vue

```
<template>
  <div>
    <div>
      <el-checkbox v-model="config.autoInsertSpace">
        autoInsertSpace
      </el-checkbox>
      <el-checkbox v-model="config.plain"> plain </el-checkbox>
      <el-checkbox v-model="config.round"> round </el-checkbox>
      <el-checkbox v-model="config.dashed"> dashed </el-checkbox>
      <el-checkbox v-model="config.text"> text </el-checkbox>
      <el-select v-model="config.type" class="ml-5" style="max-width: 150px">
        <el-option
          v-for="type in buttonTypes.filter(Boolean)"
          :key="type"
          :value="type"
        />
      </el-select>
    </div>
    <el-divider />
    <el-config-provider :button="config">
      <el-button>中文</el-button>
    </el-config-provider>
  </div>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
import { buttonTypes } from 'element-plus'

import type { ButtonConfigContext } from 'element-plus'

const config = reactive<ButtonConfigContext>({
  autoInsertSpace: true,
  type: 'default',
  plain: true,
  round: true,
  text: false,
  dashed: false,
})
</script>
```

隐藏源代码

## 对链接进行配置2.9.11 [​](#对链接进行配置)

Type:

success

Underline:

always

Link desu!

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJmbGV4IGdhcC00XCI+XG4gICAgICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LWNvbCBiYXNpcy0xNTBweCBnYXAtMVwiPlxuICAgICAgICA8c3Bhbj5UeXBlOjwvc3Bhbj5cbiAgICAgICAgPGVsLXNlbGVjdCB2LW1vZGVsPVwiY29uZmlnLnR5cGVcIj5cbiAgICAgICAgICA8ZWwtb3B0aW9uIHYtZm9yPVwidHlwZSBpbiBsaW5rVHlwZXNcIiA6a2V5PVwidHlwZVwiIDp2YWx1ZT1cInR5cGVcIiAvPlxuICAgICAgICA8L2VsLXNlbGVjdD5cbiAgICAgIDwvZGl2PlxuICAgICAgPGRpdiBjbGFzcz1cImZsZXggZmxleC1jb2wgYmFzaXMtMTUwcHggZ2FwLTFcIj5cbiAgICAgICAgPHNwYW4+VW5kZXJsaW5lOjwvc3Bhbj5cbiAgICAgICAgPGVsLXNlbGVjdCB2LW1vZGVsPVwiY29uZmlnLnVuZGVybGluZVwiPlxuICAgICAgICAgIDxlbC1vcHRpb25cbiAgICAgICAgICAgIHYtZm9yPVwidHlwZSBpbiB1bmRlcmxpbmVPcHRpb25zXCJcbiAgICAgICAgICAgIDprZXk9XCJ0eXBlXCJcbiAgICAgICAgICAgIDp2YWx1ZT1cInR5cGVcIlxuICAgICAgICAgIC8+XG4gICAgICAgIDwvZWwtc2VsZWN0PlxuICAgICAgPC9kaXY+XG4gICAgPC9kaXY+XG4gICAgPGVsLWRpdmlkZXIgLz5cbiAgICA8ZWwtY29uZmlnLXByb3ZpZGVyIDpsaW5rPVwiY29uZmlnXCI+XG4gICAgICA8ZWwtbGluaz5MaW5rIGRlc3UhPC9lbC1saW5rPlxuICAgIDwvZWwtY29uZmlnLXByb3ZpZGVyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWFjdGl2ZSB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBMaW5rQ29uZmlnQ29udGV4dCB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgbGlua1R5cGVzID0gWydwcmltYXJ5JywgJ3N1Y2Nlc3MnLCAnd2FybmluZycsICdpbmZvJywgJ2RhbmdlcicsICdkZWZhdWx0J11cbmNvbnN0IHVuZGVybGluZU9wdGlvbnMgPSBbJ2Fsd2F5cycsICduZXZlcicsICdob3ZlciddXG5cbmNvbnN0IGNvbmZpZyA9IHJlYWN0aXZlPExpbmtDb25maWdDb250ZXh0Pih7XG4gIHR5cGU6ICdzdWNjZXNzJyxcbiAgdW5kZXJsaW5lOiAnYWx3YXlzJyxcbn0pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/config-provider/link.vue)_

vue

```
<template>
  <div>
    <div class="flex gap-4">
      <div class="flex flex-col basis-150px gap-1">
        <span>Type:</span>
        <el-select v-model="config.type">
          <el-option v-for="type in linkTypes" :key="type" :value="type" />
        </el-select>
      </div>
      <div class="flex flex-col basis-150px gap-1">
        <span>Underline:</span>
        <el-select v-model="config.underline">
          <el-option
            v-for="type in underlineOptions"
            :key="type"
            :value="type"
          />
        </el-select>
      </div>
    </div>
    <el-divider />
    <el-config-provider :link="config">
      <el-link>Link desu!</el-link>
    </el-config-provider>
  </div>
</template>

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

import type { LinkConfigContext } from 'element-plus'

const linkTypes = ['primary', 'success', 'warning', 'info', 'danger', 'default']
const underlineOptions = ['always', 'never', 'hover']

const config = reactive<LinkConfigContext>({
  type: 'success',
  underline: 'always',
})
</script>
```

隐藏源代码

## 对 Card 进行配置 2.10.5 [​](#对-card-进行配置)

Shadow:

alwayshovernever

Card desu!

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlYWN0aXZlIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IENhcmRDb25maWdDb250ZXh0IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBjb25maWcgPSByZWFjdGl2ZTxDYXJkQ29uZmlnQ29udGV4dD4oe1xuICBzaGFkb3c6ICdhbHdheXMnLFxufSlcbjwvc2NyaXB0PlxuXG48dGVtcGxhdGU+XG4gIFNoYWRvdzpcbiAgPGRpdiBjbGFzcz1cImZsZXggZmxleC1jb2wganVzdGlmeS1jZW50ZXJcIj5cbiAgICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cImNvbmZpZy5zaGFkb3dcIj5cbiAgICAgIDxlbC1yYWRpbyB2YWx1ZT1cImFsd2F5c1wiPmFsd2F5czwvZWwtcmFkaW8+XG4gICAgICA8ZWwtcmFkaW8gdmFsdWU9XCJob3ZlclwiPmhvdmVyPC9lbC1yYWRpbz5cbiAgICAgIDxlbC1yYWRpbyB2YWx1ZT1cIm5ldmVyXCI+bmV2ZXI8L2VsLXJhZGlvPlxuICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gICAgPGVsLWRpdmlkZXIgLz5cbiAgICA8ZWwtY29uZmlnLXByb3ZpZGVyIDpjYXJkPVwiY29uZmlnXCI+XG4gICAgICA8ZWwtY2FyZD5DYXJkIGRlc3UhPC9lbC1jYXJkPlxuICAgIDwvZWwtY29uZmlnLXByb3ZpZGVyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/config-provider/card.vue)_

vue

```
<script lang="ts" setup>
import { reactive } from 'vue'

import type { CardConfigContext } from 'element-plus'

const config = reactive<CardConfigContext>({
  shadow: 'always',
})
</script>

<template>
  Shadow:
  <div class="flex flex-col justify-center">
    <el-radio-group v-model="config.shadow">
      <el-radio value="always">always</el-radio>
      <el-radio value="hover">hover</el-radio>
      <el-radio value="never">never</el-radio>
    </el-radio-group>
    <el-divider />
    <el-config-provider :card="config">
      <el-card>Card desu!</el-card>
    </el-config-provider>
  </div>
</template>
```

隐藏源代码

## 对 Dialog 进行配置 2.10.7 [​](#对-dialog-进行配置)

transition: string

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IGNvbXB1dGVkLCBuZXh0VGljaywgcmVmLCBzaGFsbG93UmVhY3RpdmUgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgQnV0dG9uSW5zdGFuY2UsIERpYWxvZ1RyYW5zaXRpb24gfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbnR5cGUgR2xvYmFsQ29uZmlnID0ge1xuICBhbGlnbkNlbnRlcjogYm9vbGVhblxuICBkcmFnZ2FibGU6IGJvb2xlYW5cbiAgb3ZlcmZsb3c6IGJvb2xlYW5cbiAgdHJhbnNpdGlvbj86IERpYWxvZ1RyYW5zaXRpb25cbn1cblxuY29uc3QgY29uZmlnID0gc2hhbGxvd1JlYWN0aXZlPEdsb2JhbENvbmZpZz4oe1xuICBhbGlnbkNlbnRlcjogZmFsc2UsXG4gIGRyYWdnYWJsZTogZmFsc2UsXG4gIG92ZXJmbG93OiBmYWxzZSxcbn0pXG5jb25zdCB2aXNpYmxlID0gcmVmKGZhbHNlKVxuY29uc3QgZW5hYmxlVHJhbnNpdGlvbiA9IHJlZihmYWxzZSlcbmNvbnN0IGlzT2JqZWN0VHJhbnNpdGlvbiA9IHJlZihmYWxzZSlcblxuY29uc3QgYnV0dG9uUmVmID0gcmVmPEJ1dHRvbkluc3RhbmNlPigpXG5cbmNvbnN0IEFOSU1BVElPTl9EVVJBVElPTiA9IDMwMFxuXG5jb25zdCBnbG9iYWxDb25maWcgPSBjb21wdXRlZDxHbG9iYWxDb25maWc+KCgpID0+IHtcbiAgbGV0IHRyYW5zaXRpb246IERpYWxvZ1RyYW5zaXRpb24gfCB1bmRlZmluZWRcbiAgaWYgKGVuYWJsZVRyYW5zaXRpb24udmFsdWUpIHtcbiAgICBpZiAoaXNPYmplY3RUcmFuc2l0aW9uLnZhbHVlKSB7XG4gICAgICB0cmFuc2l0aW9uID0ge1xuICAgICAgICBjc3M6IGZhbHNlLFxuICAgICAgICBvbkJlZm9yZUVudGVyKGVsKSB7XG4gICAgICAgICAgbmV4dFRpY2soKCkgPT4ge1xuICAgICAgICAgICAgaWYgKGJ1dHRvblJlZi52YWx1ZSkge1xuICAgICAgICAgICAgICBjb25zdCBidXR0b25SZWN0ID0gYnV0dG9uUmVmLnZhbHVlLnJlZiEuZ2V0Qm91bmRpbmdDbGllbnRSZWN0KClcbiAgICAgICAgICAgICAgY29uc3QgZGlhbG9nRWwgPSBlbC5xdWVyeVNlbGVjdG9yKCcuZWwtZGlhbG9nJykgYXMgSFRNTEVsZW1lbnRcblxuICAgICAgICAgICAgICBpZiAoZGlhbG9nRWwpIHtcbiAgICAgICAgICAgICAgICBjb25zdCBkaWFsb2dSZWN0ID0gZGlhbG9nRWwuZ2V0Qm91bmRpbmdDbGllbnRSZWN0KClcblxuICAgICAgICAgICAgICAgIGNvbnN0IG9mZnNldFggPVxuICAgICAgICAgICAgICAgICAgYnV0dG9uUmVjdC5sZWZ0ICtcbiAgICAgICAgICAgICAgICAgIGJ1dHRvblJlY3Qud2lkdGggLyAyIC1cbiAgICAgICAgICAgICAgICAgIChkaWFsb2dSZWN0LmxlZnQgKyBkaWFsb2dSZWN0LndpZHRoIC8gMilcbiAgICAgICAgICAgICAgICBjb25zdCBvZmZzZXRZID1cbiAgICAgICAgICAgICAgICAgIGJ1dHRvblJlY3QudG9wICtcbiAgICAgICAgICAgICAgICAgIGJ1dHRvblJlY3QuaGVpZ2h0IC8gMiAtXG4gICAgICAgICAgICAgICAgICAoZGlhbG9nUmVjdC50b3AgKyBkaWFsb2dSZWN0LmhlaWdodCAvIDIpXG5cbiAgICAgICAgICAgICAgICBkaWFsb2dFbC5zdHlsZS50cmFuc2Zvcm0gPSBgdHJhbnNsYXRlKCR7b2Zmc2V0WH1weCwgJHtvZmZzZXRZfXB4KSBzY2FsZSgwLjMpYFxuICAgICAgICAgICAgICAgIGRpYWxvZ0VsLnN0eWxlLm9wYWNpdHkgPSAnMCdcbiAgICAgICAgICAgICAgfVxuICAgICAgICAgICAgfVxuICAgICAgICAgIH0pXG4gICAgICAgIH0sXG4gICAgICAgIG9uRW50ZXIoZWwsIGRvbmUpIHtcbiAgICAgICAgICBuZXh0VGljaygoKSA9PiB7XG4gICAgICAgICAgICBjb25zdCBkaWFsb2dFbCA9IGVsLnF1ZXJ5U2VsZWN0b3IoJy5lbC1kaWFsb2cnKSBhcyBIVE1MRWxlbWVudFxuICAgICAgICAgICAgaWYgKGRpYWxvZ0VsKSB7XG4gICAgICAgICAgICAgIC8vIGZvcmNlIHJlZmxvd1xuICAgICAgICAgICAgICBkaWFsb2dFbC5vZmZzZXRIZWlnaHRcblxuICAgICAgICAgICAgICBkaWFsb2dFbC5zdHlsZS50cmFuc2l0aW9uID0gYGFsbCAke0FOSU1BVElPTl9EVVJBVElPTn1tcyBjdWJpYy1iZXppZXIoMC40LCAwLCAxLCAxKWBcbiAgICAgICAgICAgICAgZGlhbG9nRWwuc3R5bGUudHJhbnNmb3JtID0gJ3RyYW5zbGF0ZSgwLCAwKSBzY2FsZSgxKSdcbiAgICAgICAgICAgICAgZGlhbG9nRWwuc3R5bGUub3BhY2l0eSA9ICcxJ1xuXG4gICAgICAgICAgICAgIC8vIHdhaXQgZm9yIGFuaW1hdGlvbiB0byBjb21wbGV0ZSwgdGhlbiBjbGVhbnVwIGlubGluZSBzdHlsZXMgdG8gYXZvaWQgYWZmZWN0aW5nIGRyYWdcbiAgICAgICAgICAgICAgc2V0VGltZW91dCgoKSA9PiB7XG4gICAgICAgICAgICAgICAgZGlhbG9nRWwuc3R5bGUudHJhbnNpdGlvbiA9ICcnXG4gICAgICAgICAgICAgICAgZGlhbG9nRWwuc3R5bGUudHJhbnNmb3JtID0gJydcbiAgICAgICAgICAgICAgICBkaWFsb2dFbC5zdHlsZS5vcGFjaXR5ID0gJydcbiAgICAgICAgICAgICAgICBkb25lKClcbiAgICAgICAgICAgICAgfSwgQU5JTUFUSU9OX0RVUkFUSU9OKVxuICAgICAgICAgICAgfSBlbHNlIHtcbiAgICAgICAgICAgICAgZG9uZSgpXG4gICAgICAgICAgICB9XG4gICAgICAgICAgfSlcbiAgICAgICAgfSxcbiAgICAgICAgb25MZWF2ZShlbCwgZG9uZSkge1xuICAgICAgICAgIGNvbnN0IGRpYWxvZ0VsID0gZWwucXVlcnlTZWxlY3RvcignLmVsLWRpYWxvZycpIGFzIEhUTUxFbGVtZW50XG4gICAgICAgICAgaWYgKGRpYWxvZ0VsKSB7XG4gICAgICAgICAgICBpZiAoYnV0dG9uUmVmLnZhbHVlKSB7XG4gICAgICAgICAgICAgIGNvbnN0IGJ1dHRvblJlY3QgPSBidXR0b25SZWYudmFsdWUucmVmIS5nZXRCb3VuZGluZ0NsaWVudFJlY3QoKVxuICAgICAgICAgICAgICBjb25zdCBkaWFsb2dSZWN0ID0gZGlhbG9nRWwuZ2V0Qm91bmRpbmdDbGllbnRSZWN0KClcblxuICAgICAgICAgICAgICBjb25zdCBjdXJyZW50VHJhbnNmb3JtID0gZGlhbG9nRWwuc3R5bGUudHJhbnNmb3JtXG4gICAgICAgICAgICAgIGxldCBkcmFnT2Zmc2V0WCA9IDBcbiAgICAgICAgICAgICAgbGV0IGRyYWdPZmZzZXRZID0gMFxuXG4gICAgICAgICAgICAgIC8vIGF2b2lkIGRyYWdnYWJsZSBlZmZlY3RcbiAgICAgICAgICAgICAgaWYgKGN1cnJlbnRUcmFuc2Zvcm0pIHtcbiAgICAgICAgICAgICAgICBjb25zdCB0cmFuc2xhdGVNYXRjaCA9IGN1cnJlbnRUcmFuc2Zvcm0ubWF0Y2goXG4gICAgICAgICAgICAgICAgICAvdHJhbnNsYXRlXFwoKFteLF0rKSxcXHMqKFteKV0rKVxcKS9cbiAgICAgICAgICAgICAgICApXG4gICAgICAgICAgICAgICAgaWYgKHRyYW5zbGF0ZU1hdGNoKSB7XG4gICAgICAgICAgICAgICAgICBkcmFnT2Zmc2V0WCA9IE51bWJlci5wYXJzZUZsb2F0KHRyYW5zbGF0ZU1hdGNoWzFdKVxuICAgICAgICAgICAgICAgICAgZHJhZ09mZnNldFkgPSBOdW1iZXIucGFyc2VGbG9hdCh0cmFuc2xhdGVNYXRjaFsyXSlcbiAgICAgICAgICAgICAgICB9XG4gICAgICAgICAgICAgIH1cblxuICAgICAgICAgICAgICBjb25zdCBvZmZzZXRYID1cbiAgICAgICAgICAgICAgICBidXR0b25SZWN0LmxlZnQgK1xuICAgICAgICAgICAgICAgIGJ1dHRvblJlY3Qud2lkdGggLyAyIC1cbiAgICAgICAgICAgICAgICAoZGlhbG9nUmVjdC5sZWZ0ICsgZGlhbG9nUmVjdC53aWR0aCAvIDIpICtcbiAgICAgICAgICAgICAgICBkcmFnT2Zmc2V0WFxuICAgICAgICAgICAgICBjb25zdCBvZmZzZXRZID1cbiAgICAgICAgICAgICAgICBidXR0b25SZWN0LnRvcCArXG4gICAgICAgICAgICAgICAgYnV0dG9uUmVjdC5oZWlnaHQgLyAyIC1cbiAgICAgICAgICAgICAgICAoZGlhbG9nUmVjdC50b3AgKyBkaWFsb2dSZWN0LmhlaWdodCAvIDIpICtcbiAgICAgICAgICAgICAgICBkcmFnT2Zmc2V0WVxuXG4gICAgICAgICAgICAgIGRpYWxvZ0VsLnN0eWxlLnRyYW5zaXRpb24gPSBgYWxsICR7QU5JTUFUSU9OX0RVUkFUSU9OfW1zIGN1YmljLWJlemllcigwLjQsIDAsIDEsIDEpYFxuICAgICAgICAgICAgICBkaWFsb2dFbC5zdHlsZS50cmFuc2Zvcm0gPSBgdHJhbnNsYXRlKCR7b2Zmc2V0WH1weCwgJHtvZmZzZXRZfXB4KSBzY2FsZSgwLjMpYFxuICAgICAgICAgICAgICBkaWFsb2dFbC5zdHlsZS5vcGFjaXR5ID0gJzAnXG5cbiAgICAgICAgICAgICAgLy8gd2FpdCBmb3IgYW5pbWF0aW9uIHRvIGNvbXBsZXRlLCB0aGVuIGNsZWFudXAgaW5saW5lIHN0eWxlc1xuICAgICAgICAgICAgICBzZXRUaW1lb3V0KCgpID0+IHtcbiAgICAgICAgICAgICAgICBkaWFsb2dFbC5zdHlsZS50cmFuc2l0aW9uID0gJydcbiAgICAgICAgICAgICAgICBkaWFsb2dFbC5zdHlsZS50cmFuc2Zvcm0gPSAnJ1xuICAgICAgICAgICAgICAgIGRpYWxvZ0VsLnN0eWxlLm9wYWNpdHkgPSAnJ1xuICAgICAgICAgICAgICAgIGRvbmUoKVxuICAgICAgICAgICAgICB9LCBBTklNQVRJT05fRFVSQVRJT04pXG4gICAgICAgICAgICB9IGVsc2Uge1xuICAgICAgICAgICAgICBkb25lKClcbiAgICAgICAgICAgIH1cbiAgICAgICAgICB9IGVsc2Uge1xuICAgICAgICAgICAgZG9uZSgpXG4gICAgICAgICAgfVxuICAgICAgICB9LFxuICAgICAgfVxuICAgIH0gZWxzZSB7XG4gICAgICB0cmFuc2l0aW9uID0gJ2RpYWxvZy1ib3VuY2UnXG4gICAgfVxuICB9XG4gIHJldHVybiB7XG4gICAgYWxpZ25DZW50ZXI6IGNvbmZpZy5hbGlnbkNlbnRlcixcbiAgICBkcmFnZ2FibGU6IGNvbmZpZy5kcmFnZ2FibGUsXG4gICAgb3ZlcmZsb3c6IGNvbmZpZy5vdmVyZmxvdyxcbiAgICB0cmFuc2l0aW9uLFxuICB9XG59KVxuPC9zY3JpcHQ+XG5cbjx0ZW1wbGF0ZT5cbiAgPGRpdiBjbGFzcz1cImZsZXggZmxleC1jb2wgZ2FwLTQganVzdGlmeS1jZW50ZXJcIj5cbiAgICA8ZGl2IGNsYXNzPVwiZmxleCBpdGVtcy1jZW50ZXIgZ2FwLTJcIj5cbiAgICAgIDxlbC1zd2l0Y2ggdi1tb2RlbD1cImNvbmZpZy5hbGlnbkNlbnRlclwiIGFjdGl2ZS10ZXh0PVwiYWxpZ25DZW50ZXJcIiAvPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJmbGV4IGl0ZW1zLWNlbnRlciBnYXAtNFwiPlxuICAgICAgPGVsLXN3aXRjaCB2LW1vZGVsPVwiY29uZmlnLmRyYWdnYWJsZVwiIGFjdGl2ZS10ZXh0PVwiZHJhZ2dhYmxlXCIgLz5cbiAgICAgIDxlbC1zd2l0Y2hcbiAgICAgICAgdi1tb2RlbD1cImNvbmZpZy5vdmVyZmxvd1wiXG4gICAgICAgIDpkaXNhYmxlZD1cIiFjb25maWcuZHJhZ2dhYmxlXCJcbiAgICAgICAgYWN0aXZlLXRleHQ9XCJvdmVyZmxvd1wiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJmbGV4IGl0ZW1zLWNlbnRlciBnYXAtMlwiPlxuICAgICAgPGVsLXN3aXRjaCB2LW1vZGVsPVwiZW5hYmxlVHJhbnNpdGlvblwiIGFjdGl2ZS10ZXh0PVwiZW5hYmxlIHRyYW5zaXRpb25cIiAvPlxuICAgICAgPGVsLXN3aXRjaFxuICAgICAgICB2LW1vZGVsPVwiaXNPYmplY3RUcmFuc2l0aW9uXCJcbiAgICAgICAgOmRpc2FibGVkPVwiIWVuYWJsZVRyYW5zaXRpb25cIlxuICAgICAgICBhY3RpdmUtdGV4dD1cInRyYW5zaXRpb246IG9iamVjdFwiXG4gICAgICAgIGluYWN0aXZlLXRleHQ9XCJ0cmFuc2l0aW9uOiBzdHJpbmdcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwiZmxleCBpdGVtcy1jZW50ZXIgZ2FwLTJcIj5cbiAgICAgIDxlbC1idXR0b25cbiAgICAgICAgcmVmPVwiYnV0dG9uUmVmXCJcbiAgICAgICAgdHlwZT1cInByaW1hcnlcIlxuICAgICAgICBzaXplPVwic21hbGxcIlxuICAgICAgICBAY2xpY2s9XCJ2aXNpYmxlID0gdHJ1ZVwiXG4gICAgICA+XG4gICAgICAgIE9wZW4gRGlhbG9nXG4gICAgICA8L2VsLWJ1dHRvbj5cbiAgICA8L2Rpdj5cbiAgICA8ZWwtY29uZmlnLXByb3ZpZGVyIDpkaWFsb2c9XCJnbG9iYWxDb25maWdcIj5cbiAgICAgIDxlbC1kaWFsb2cgdi1tb2RlbD1cInZpc2libGVcIiB0aXRsZT1cIkRpYWxvZyBUaXRsZVwiIGRlc3Ryb3ktb24tY2xvc2U+XG4gICAgICAgIERpYWxvZyBDb250ZW50XG4gICAgICA8L2VsLWRpYWxvZz5cbiAgICA8L2VsLWNvbmZpZy1wcm92aWRlcj5cbiAgICA8ZGl2IHYtaWY9XCJlbmFibGVUcmFuc2l0aW9uXCIgY2xhc3M9XCJ0ZXh0LXhzIG9wYWNpdHktNzBcIj5cbiAgICAgIDxkaXYgdi1pZj1cImlzT2JqZWN0VHJhbnNpdGlvblwiPlxuICAgICAgICBVc2luZyBKYXZhU2NyaXB0IGNvbnRyb2xsZWQgYW5pbWF0aW9uOlxuICAgICAgICA8Y29kZT57eyBKU09OLnN0cmluZ2lmeShnbG9iYWxDb25maWcudHJhbnNpdGlvbikgfX08L2NvZGU+XG4gICAgICA8L2Rpdj5cbiAgICAgIDxkaXYgdi1lbHNlPlxuICAgICAgICBVc2luZyBzdHJpbmcgdHJhbnNpdGlvbiBuYW1lOlxuICAgICAgICA8Y29kZT57eyBnbG9iYWxDb25maWcudHJhbnNpdGlvbiB9fTwvY29kZT5cbiAgICAgIDwvZGl2PlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZT5cbi8qIEJvdW5jZSBBbmltYXRpb24gKi9cbi5kaWFsb2ctYm91bmNlLWVudGVyLWFjdGl2ZSxcbi5kaWFsb2ctYm91bmNlLWxlYXZlLWFjdGl2ZSxcbi5kaWFsb2ctYm91bmNlLWVudGVyLWFjdGl2ZSAuZWwtZGlhbG9nLFxuLmRpYWxvZy1ib3VuY2UtbGVhdmUtYWN0aXZlIC5lbC1kaWFsb2cge1xuICB0cmFuc2l0aW9uOiBhbGwgMC41cyBjdWJpYy1iZXppZXIoMC4xNzUsIDAuODg1LCAwLjMyLCAxLjI3NSk7XG59XG5cbi5kaWFsb2ctYm91bmNlLWVudGVyLWZyb20sXG4uZGlhbG9nLWJvdW5jZS1sZWF2ZS10byB7XG4gIG9wYWNpdHk6IDA7XG59XG5cbi5kaWFsb2ctYm91bmNlLWVudGVyLWZyb20gLmVsLWRpYWxvZyxcbi5kaWFsb2ctYm91bmNlLWxlYXZlLXRvIC5lbC1kaWFsb2cge1xuICB0cmFuc2Zvcm06IHNjYWxlKDAuMykgdHJhbnNsYXRlWSgtNTBweCk7XG4gIG9wYWNpdHk6IDA7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/config-provider/dialog.vue)_

vue

```
<script lang="ts" setup>
import { computed, nextTick, ref, shallowReactive } from 'vue'

import type { ButtonInstance, DialogTransition } from 'element-plus'

type GlobalConfig = {
  alignCenter: boolean
  draggable: boolean
  overflow: boolean
  transition?: DialogTransition
}

const config = shallowReactive<GlobalConfig>({
  alignCenter: false,
  draggable: false,
  overflow: false,
})
const visible = ref(false)
const enableTransition = ref(false)
const isObjectTransition = ref(false)

const buttonRef = ref<ButtonInstance>()

const ANIMATION_DURATION = 300

const globalConfig = computed<GlobalConfig>(() => {
  let transition: DialogTransition | undefined
  if (enableTransition.value) {
    if (isObjectTransition.value) {
      transition = {
        css: false,
        onBeforeEnter(el) {
          nextTick(() => {
            if (buttonRef.value) {
              const buttonRect = buttonRef.value.ref!.getBoundingClientRect()
              const dialogEl = el.querySelector('.el-dialog') as HTMLElement

              if (dialogEl) {
                const dialogRect = dialogEl.getBoundingClientRect()

                const offsetX =
                  buttonRect.left +
                  buttonRect.width / 2 -
                  (dialogRect.left + dialogRect.width / 2)
                const offsetY =
                  buttonRect.top +
                  buttonRect.height / 2 -
                  (dialogRect.top + dialogRect.height / 2)

                dialogEl.style.transform = `translate(${offsetX}px, ${offsetY}px) scale(0.3)`
                dialogEl.style.opacity = '0'
              }
            }
          })
        },
        onEnter(el, done) {
          nextTick(() => {
            const dialogEl = el.querySelector('.el-dialog') as HTMLElement
            if (dialogEl) {
              // force reflow
              dialogEl.offsetHeight

              dialogEl.style.transition = `all ${ANIMATION_DURATION}ms cubic-bezier(0.4, 0, 1, 1)`
              dialogEl.style.transform = 'translate(0, 0) scale(1)'
              dialogEl.style.opacity = '1'

              // wait for animation to complete, then cleanup inline styles to avoid affecting drag
              setTimeout(() => {
                dialogEl.style.transition = ''
                dialogEl.style.transform = ''
                dialogEl.style.opacity = ''
                done()
              }, ANIMATION_DURATION)
            } else {
              done()
            }
          })
        },
        onLeave(el, done) {
          const dialogEl = el.querySelector('.el-dialog') as HTMLElement
          if (dialogEl) {
            if (buttonRef.value) {
              const buttonRect = buttonRef.value.ref!.getBoundingClientRect()
              const dialogRect = dialogEl.getBoundingClientRect()

              const currentTransform = dialogEl.style.transform
              let dragOffsetX = 0
              let dragOffsetY = 0

              // avoid draggable effect
              if (currentTransform) {
                const translateMatch = currentTransform.match(
                  /translate\(([^,]+),\s*([^)]+)\)/
                )
                if (translateMatch) {
                  dragOffsetX = Number.parseFloat(translateMatch[1])
                  dragOffsetY = Number.parseFloat(translateMatch[2])
                }
              }

              const offsetX =
                buttonRect.left +
                buttonRect.width / 2 -
                (dialogRect.left + dialogRect.width / 2) +
                dragOffsetX
              const offsetY =
                buttonRect.top +
                buttonRect.height / 2 -
                (dialogRect.top + dialogRect.height / 2) +
                dragOffsetY

              dialogEl.style.transition = `all ${ANIMATION_DURATION}ms cubic-bezier(0.4, 0, 1, 1)`
              dialogEl.style.transform = `translate(${offsetX}px, ${offsetY}px) scale(0.3)`
              dialogEl.style.opacity = '0'

              // wait for animation to complete, then cleanup inline styles
              setTimeout(() => {
                dialogEl.style.transition = ''
                dialogEl.style.transform = ''
                dialogEl.style.opacity = ''
                done()
              }, ANIMATION_DURATION)
            } else {
              done()
            }
          } else {
            done()
          }
        },
      }
    } else {
      transition = 'dialog-bounce'
    }
  }
  return {
    alignCenter: config.alignCenter,
    draggable: config.draggable,
    overflow: config.overflow,
    transition,
  }
})
</script>

<template>
  <div class="flex flex-col gap-4 justify-center">
    <div class="flex items-center gap-2">
      <el-switch v-model="config.alignCenter" active-text="alignCenter" />
    </div>
    <div class="flex items-center gap-4">
      <el-switch v-model="config.draggable" active-text="draggable" />
      <el-switch
        v-model="config.overflow"
        :disabled="!config.draggable"
        active-text="overflow"
      />
    </div>
    <div class="flex items-center gap-2">
      <el-switch v-model="enableTransition" active-text="enable transition" />
      <el-switch
        v-model="isObjectTransition"
        :disabled="!enableTransition"
        active-text="transition: object"
        inactive-text="transition: string"
      />
    </div>
    <div class="flex items-center gap-2">
      <el-button
        ref="buttonRef"
        type="primary"
        size="small"
        @click="visible = true"
      >
        Open Dialog
      </el-button>
    </div>
    <el-config-provider :dialog="globalConfig">
      <el-dialog v-model="visible" title="Dialog Title" destroy-on-close>
        Dialog Content
      </el-dialog>
    </el-config-provider>
    <div v-if="enableTransition" class="text-xs opacity-70">
      <div v-if="isObjectTransition">
        Using JavaScript controlled animation:
        <code>{{ JSON.stringify(globalConfig.transition) }}</code>
      </div>
      <div v-else>
        Using string transition name:
        <code>{{ globalConfig.transition }}</code>
      </div>
    </div>
  </div>
</template>

<style>
/* Bounce Animation */
.dialog-bounce-enter-active,
.dialog-bounce-leave-active,
.dialog-bounce-enter-active .el-dialog,
.dialog-bounce-leave-active .el-dialog {
  transition: all 0.5s cubic-bezier(0.175, 0.885, 0.32, 1.275);
}

.dialog-bounce-enter-from,
.dialog-bounce-leave-to {
  opacity: 0;
}

.dialog-bounce-enter-from .el-dialog,
.dialog-bounce-leave-to .el-dialog {
  transform: scale(0.3) translateY(-50px);
  opacity: 0;
}
</style>
```

隐藏源代码

## 对消息进行配置 [​](#对消息进行配置)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1jb25maWctcHJvdmlkZXIgOm1lc3NhZ2U9XCJjb25maWdcIj5cbiAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwib3BlblwiPk9QRU48L2VsLWJ1dHRvbj5cbiAgICA8L2VsLWNvbmZpZy1wcm92aWRlcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVhY3RpdmUgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBFbE1lc3NhZ2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGNvbmZpZyA9IHJlYWN0aXZlKHtcbiAgbWF4OiAzLFxuICBwbGFpbjogdHJ1ZSxcbiAgcGxhY2VtZW50OiAnYm90dG9tJyxcbn0pXG5cbmNvbnN0IG9wZW4gPSAoKSA9PiB7XG4gIEVsTWVzc2FnZSgnVGhpcyBpcyBhIG1lc3NhZ2UgZnJvbSBib3R0b20uJylcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/config-provider/message.vue)_

vue

```
<template>
  <div>
    <el-config-provider :message="config">
      <el-button @click="open">OPEN</el-button>
    </el-config-provider>
  </div>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
import { ElMessage } from 'element-plus'

const config = reactive({
  max: 3,
  plain: true,
  placement: 'bottom',
})

const open = () => {
  ElMessage('This is a message from bottom.')
}
</script>
```

隐藏源代码

## 空值配置2.7.0 [​](#空值配置)

支持的组件

-   Cascader 级联选择器
-   ColorPicker 2.10.3
-   DatePicker 日期选择器
-   Select 选择器
-   SelectV2 选择器
-   TimePicker 时间选择器
-   TimeSelect 时间选择
-   TreeSelect 树形选择

设置 `empty-values` 来配置组件的默认空值。 默认值是 `['', null, undefined]`。 如果认为空字符串不是一个空值，可以设置成 `[undefined, null]`。

设置 `value-on-clear` 以设置清空选项的值。 组件默认值是 `undefined`。 在日期组件中是 `null`。 如果想设置成 `undefined`，请使用 `() => undefined`。

All

All

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY29uZmlnLXByb3ZpZGVyIDp2YWx1ZS1vbi1jbGVhcj1cIm51bGxcIiA6ZW1wdHktdmFsdWVzPVwiW3VuZGVmaW5lZCwgbnVsbF1cIj5cbiAgICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTQgaXRlbXMtY2VudGVyXCI+XG4gICAgICA8ZWwtc2VsZWN0XG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTFcIlxuICAgICAgICBjbGVhcmFibGVcbiAgICAgICAgcGxhY2Vob2xkZXI9XCJTZWxlY3RcIlxuICAgICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICAgIEBjaGFuZ2U9XCJoYW5kbGVDaGFuZ2VcIlxuICAgICAgPlxuICAgICAgICA8ZWwtb3B0aW9uXG4gICAgICAgICAgdi1mb3I9XCJpdGVtIGluIG9wdGlvbnNcIlxuICAgICAgICAgIDprZXk9XCJpdGVtLnZhbHVlXCJcbiAgICAgICAgICA6bGFiZWw9XCJpdGVtLmxhYmVsXCJcbiAgICAgICAgICA6dmFsdWU9XCJpdGVtLnZhbHVlXCJcbiAgICAgICAgLz5cbiAgICAgIDwvZWwtc2VsZWN0PlxuICAgICAgPGVsLXNlbGVjdC12MlxuICAgICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgICAgY2xlYXJhYmxlXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCJcbiAgICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgICA6dmFsdWUtb24tY2xlYXI9XCIoKSA9PiB1bmRlZmluZWRcIlxuICAgICAgICBAY2hhbmdlPVwiaGFuZGxlQ2hhbmdlXCJcbiAgICAgIC8+XG4gICAgPC9kaXY+XG4gIDwvZWwtY29uZmlnLXByb3ZpZGVyPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVsTWVzc2FnZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgdmFsdWUxID0gcmVmKCcnKVxuY29uc3QgdmFsdWUyID0gcmVmKCcnKVxuY29uc3Qgb3B0aW9ucyA9IFtcbiAge1xuICAgIHZhbHVlOiAnJyxcbiAgICBsYWJlbDogJ0FsbCcsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjEnLFxuICAgIGxhYmVsOiAnT3B0aW9uMScsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjInLFxuICAgIGxhYmVsOiAnT3B0aW9uMicsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjMnLFxuICAgIGxhYmVsOiAnT3B0aW9uMycsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjQnLFxuICAgIGxhYmVsOiAnT3B0aW9uNCcsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjUnLFxuICAgIGxhYmVsOiAnT3B0aW9uNScsXG4gIH0sXG5dXG5cbmNvbnN0IGhhbmRsZUNoYW5nZSA9ICh2YWx1ZSkgPT4ge1xuICBpZiAoW3VuZGVmaW5lZCwgbnVsbF0uaW5jbHVkZXModmFsdWUpKSB7XG4gICAgRWxNZXNzYWdlLmluZm8oYFRoZSBjbGVhciB2YWx1ZSBpczogJHt2YWx1ZX1gKVxuICB9XG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/config-provider/empty-values.vue)_

vue

```
<template>
  <el-config-provider :value-on-clear="null" :empty-values="[undefined, null]">
    <div class="flex flex-wrap gap-4 items-center">
      <el-select
        v-model="value1"
        clearable
        placeholder="Select"
        style="width: 240px"
        @change="handleChange"
      >
        <el-option
          v-for="item in options"
          :key="item.value"
          :label="item.label"
          :value="item.value"
        />
      </el-select>
      <el-select-v2
        v-model="value2"
        clearable
        placeholder="Select"
        style="width: 240px"
        :options="options"
        :value-on-clear="() => undefined"
        @change="handleChange"
      />
    </div>
  </el-config-provider>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElMessage } from 'element-plus'

const value1 = ref('')
const value2 = ref('')
const options = [
  {
    value: '',
    label: 'All',
  },
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]

const handleChange = (value) => {
  if ([undefined, null].includes(value)) {
    ElMessage.info(`The clear value is: ${value}`)
  }
}
</script>
```

隐藏源代码

## 表格配置 2.13.3 [​](#表格配置)

showOverflowTooltip

dark

Date

Name

Address (inherited from config-provider)

Address (explicit false)

2016-05-04

Aleyna Kutzner

Lohrbergstr. 86c, Süd Lilli, Saarland

Lohrbergstr. 86c, Süd Lilli, Saarland

2016-05-03

Helen Jacobi

760 A Street, South Frankfield, Illinois

760 A Street, South Frankfield, Illinois

2016-05-02

Brandon Deckert

Arnold-Ohletz-Str. 41a, Alt Malinascheid, Thüringen

Arnold-Ohletz-Str. 41a, Alt Malinascheid, Thüringen

2016-05-01

Margie Smith

23618 Windsor Drive, West Ricardoview, Idaho

23618 Windsor Drive, West Ricardoview, Idaho

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxkaXY+XG4gICAgICA8ZWwtY2hlY2tib3ggdi1tb2RlbD1cImNvbmZpZy5zaG93T3ZlcmZsb3dUb29sdGlwXCI+XG4gICAgICAgIHNob3dPdmVyZmxvd1Rvb2x0aXBcbiAgICAgIDwvZWwtY2hlY2tib3g+XG4gICAgICA8ZWwtc2VsZWN0XG4gICAgICAgIHYtbW9kZWw9XCJjb25maWcudG9vbHRpcEVmZmVjdFwiXG4gICAgICAgIGNsYXNzPVwibWwtNVwiXG4gICAgICAgIHN0eWxlPVwibWF4LXdpZHRoOiAxNTBweFwiXG4gICAgICA+XG4gICAgICAgIDxlbC1vcHRpb24gdmFsdWU9XCJkYXJrXCIgbGFiZWw9XCJkYXJrXCIgLz5cbiAgICAgICAgPGVsLW9wdGlvbiB2YWx1ZT1cImxpZ2h0XCIgbGFiZWw9XCJsaWdodFwiIC8+XG4gICAgICA8L2VsLXNlbGVjdD5cbiAgICA8L2Rpdj5cbiAgICA8ZWwtZGl2aWRlciAvPlxuICAgIDxlbC1jb25maWctcHJvdmlkZXIgOnRhYmxlPVwiY29uZmlnXCI+XG4gICAgICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCI+XG4gICAgICAgIDxlbC10YWJsZS1jb2x1bW4gdHlwZT1cInNlbGVjdGlvblwiIHdpZHRoPVwiNTVcIiAvPlxuICAgICAgICA8ZWwtdGFibGUtY29sdW1uIGxhYmVsPVwiRGF0ZVwiIHdpZHRoPVwiMTIwXCI+XG4gICAgICAgICAgPHRlbXBsYXRlICNkZWZhdWx0PVwic2NvcGVcIj57eyBzY29wZS5yb3cuZGF0ZSB9fTwvdGVtcGxhdGU+XG4gICAgICAgIDwvZWwtdGFibGUtY29sdW1uPlxuICAgICAgICA8ZWwtdGFibGUtY29sdW1uIHByb3BlcnR5PVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIHdpZHRoPVwiMTIwXCIgLz5cbiAgICAgICAgPGVsLXRhYmxlLWNvbHVtblxuICAgICAgICAgIHByb3BlcnR5PVwiYWRkcmVzc1wiXG4gICAgICAgICAgbGFiZWw9XCJBZGRyZXNzIChpbmhlcml0ZWQgZnJvbSBjb25maWctcHJvdmlkZXIpXCJcbiAgICAgICAgICB3aWR0aD1cIjMwMFwiXG4gICAgICAgIC8+XG4gICAgICAgIDxlbC10YWJsZS1jb2x1bW5cbiAgICAgICAgICBwcm9wZXJ0eT1cImFkZHJlc3NcIlxuICAgICAgICAgIGxhYmVsPVwiQWRkcmVzcyAoZXhwbGljaXQgZmFsc2UpXCJcbiAgICAgICAgICA6c2hvdy1vdmVyZmxvdy10b29sdGlwPVwiZmFsc2VcIlxuICAgICAgICAvPlxuICAgICAgPC9lbC10YWJsZT5cbiAgICA8L2VsLWNvbmZpZy1wcm92aWRlcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVhY3RpdmUgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgVGFibGVDb25maWdDb250ZXh0IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBjb25maWcgPSByZWFjdGl2ZTxUYWJsZUNvbmZpZ0NvbnRleHQ+KHtcbiAgc2hvd092ZXJmbG93VG9vbHRpcDogdHJ1ZSxcbiAgdG9vbHRpcEVmZmVjdDogJ2RhcmsnLFxufSlcblxuaW50ZXJmYWNlIFVzZXIge1xuICBkYXRlOiBzdHJpbmdcbiAgbmFtZTogc3RyaW5nXG4gIGFkZHJlc3M6IHN0cmluZ1xufVxuXG5jb25zdCB0YWJsZURhdGE6IFVzZXJbXSA9IFtcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA0JyxcbiAgICBuYW1lOiAnQWxleW5hIEt1dHpuZXInLFxuICAgIGFkZHJlc3M6ICdMb2hyYmVyZ3N0ci4gODZjLCBTw7xkIExpbGxpLCBTYWFybGFuZCcsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ0hlbGVuIEphY29iaScsXG4gICAgYWRkcmVzczogJzc2MCBBIFN0cmVldCwgU291dGggRnJhbmtmaWVsZCwgSWxsaW5vaXMnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDInLFxuICAgIG5hbWU6ICdCcmFuZG9uIERlY2tlcnQnLFxuICAgIGFkZHJlc3M6ICdBcm5vbGQtT2hsZXR6LVN0ci4gNDFhLCBBbHQgTWFsaW5hc2NoZWlkLCBUaMO8cmluZ2VuJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICBuYW1lOiAnTWFyZ2llIFNtaXRoJyxcbiAgICBhZGRyZXNzOiAnMjM2MTggV2luZHNvciBEcml2ZSwgV2VzdCBSaWNhcmRvdmlldywgSWRhaG8nLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/config-provider/table.vue)_

vue

```
<template>
  <div>
    <div>
      <el-checkbox v-model="config.showOverflowTooltip">
        showOverflowTooltip
      </el-checkbox>
      <el-select
        v-model="config.tooltipEffect"
        class="ml-5"
        style="max-width: 150px"
      >
        <el-option value="dark" label="dark" />
        <el-option value="light" label="light" />
      </el-select>
    </div>
    <el-divider />
    <el-config-provider :table="config">
      <el-table :data="tableData" style="width: 100%">
        <el-table-column type="selection" width="55" />
        <el-table-column label="Date" width="120">
          <template #default="scope">{{ scope.row.date }}</template>
        </el-table-column>
        <el-table-column property="name" label="Name" width="120" />
        <el-table-column
          property="address"
          label="Address (inherited from config-provider)"
          width="300"
        />
        <el-table-column
          property="address"
          label="Address (explicit false)"
          :show-overflow-tooltip="false"
        />
      </el-table>
    </el-config-provider>
  </div>
</template>

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

import type { TableConfigContext } from 'element-plus'

const config = reactive<TableConfigContext>({
  showOverflowTooltip: true,
  tooltipEffect: 'dark',
})

interface User {
  date: string
  name: string
  address: string
}

const tableData: User[] = [
  {
    date: '2016-05-04',
    name: 'Aleyna Kutzner',
    address: 'Lohrbergstr. 86c, Süd Lilli, Saarland',
  },
  {
    date: '2016-05-03',
    name: 'Helen Jacobi',
    address: '760 A Street, South Frankfield, Illinois',
  },
  {
    date: '2016-05-02',
    name: 'Brandon Deckert',
    address: 'Arnold-Ohletz-Str. 41a, Alt Malinascheid, Thüringen',
  },
  {
    date: '2016-05-01',
    name: 'Margie Smith',
    address: '23618 Windsor Drive, West Ricardoview, Idaho',
  },
]
</script>
```

隐藏源代码

## 实验性功能 [​](#实验性功能)

在本节中，您可以学习如何使用 Config Provider 来提供实验性功能。 现在，我们还没有添加任何实验性功能，但在未来的规划中，我们将添加一些实验性功能。 您可以使用此配置来管理这些功能。

## API [​](#api)

### Config Provider Attributes [​](#config-provider-attributes)

属性名

说明

类型

默认值

locale

翻译文本对象

`object`[](https://github.com/element-plus/element-plus/blob/a98ff9b40c0c3d2b9959f99919bd8363e3e3c25a/packages/locale/index.ts#L5) [languages](https://github.com/element-plus/element-plus/tree/dev/packages/locale/lang)

[en](https://github.com/element-plus/element-plus/blob/dev/packages/locale/lang/en.ts)

size

全局组件大小

`enum`

default

zIndex

全局初始化 zIndex 的值

`number`

—

namespace

全局组件类名称前缀 (需要配合 [$namespace](https://github.com/element-plus/element-plus/blob/dev/packages/theme-chalk/src/mixins/config.scss#L1) 使用)

`string`

el

button

按钮相关配置，[详见下表](#button-attribute)

`object`

详见下表

link

链接相关的配置， [见下表](#link-attribute)

`object`

详见下表

dialog 2.10.7

dialog 相关的配置， [见下表](#dialog-attribute)

`object`

详见下表

message

消息相关配置， [详见下表](#message-attribute)

`object`

详见下表

experimental-features

将要添加的实验阶段的功能，所有功能都是默认设置为 false

`object`

—

empty-values 2.7.0

输入类组件空值

`array`

—

value-on-clear 2.7.0

输入类组件清空值

`string` / `number` / `boolean` / `Function`

—

table 2.13.3

表格相关配置， [详见下表](#table-attribute)

`object`

详见下表

### Button Attribute [​](#button-attribute)

参数

描述

类型

默认值

type 2.9.11

按钮类型，在设置`color`时，后者优先。

`enum`

—

autoInsertSpace

两个中文字符之间自动插入空格(仅当文本长度为 2 且所有字符均为中文时才生效)

`boolean`

false

plain 2.9.11

是否为朴素按钮

`boolean`

false

text 2.11.0

是否为文字按钮

`boolean`

false

round 2.9.11

是否为圆角按钮

`boolean`

false

dashed 2.13.3

是否是虚线按钮

`boolean`

false

### 链接属性 [​](#链接属性)

参数

描述

类型

默认值

type 2.9.11

类型

`enum`

default

underline 2.9.11

控制下划线是否出现

`enum`

hover

### Card Attribute [​](#card-attribute)

属性

描述

类型

默认值

shadow 2.10.5

设置阴影显示时机

`enum`

—

### Dialog 属性 [​](#dialog-属性)

属性

描述

类型

默认值

align-center 2.10.7

是否水平垂直对齐对话框

`boolean`

false

draggable 2.10.7

为 Dialog 启用可拖拽功能

`boolean`

false

overflow 2.10.7

拖动范围可以超出可视区

`boolean`

false

transition 2.10.7

对话框动画的自定义过渡配置。 可以是一个字符串（过渡名称），也可以是一个包含 Vue 过渡属性的对象。

`string` / `object`

—

### Message Attribute [​](#message-attribute)

属性

详情

类型

默认值

max

可同时显示的消息最大数量

`number`

—

grouping 2.8.2

合并内容相同的消息，不支持 VNode 类型的消息

`boolean`

—

duration 2.8.2

显示时间，单位为毫秒。 设为 0 则不会自动关闭

`number`

—

showClose 2.8.2

是否显示关闭按钮

`boolean`

—

offset 2.8.2

Message 距离窗口顶部的偏移量

`number`

—

plain 2.9.11

是否纯色

`boolean`

—

placement 2.11.0

消息放置位置

`enum`

—

### Table Attribute 2.13.3 [​](#table-attribute)

属性

详情

Type

Default

show-overflow-tooltip

是否隐藏额外内容并在单元格悬停时使用 Tooltip 显示它们。这将影响全部列的展示，详请参考[tooltip-options](#table-attributes)

`boolean` / \[`object`\]

—

tooltip-effect

溢出的 tooltip 的 `effect`

`enum`

dark

tooltip-options

溢出 tooltip 的选项，[参见下述 tooltip 组件](./tooltip.html#attributes)

`object`

`object`

tooltip-formatter

使用 `show-overflow-tooltip` 时自定义 tooltip 内容

`Function`

—

### Config Provider Slots [​](#config-provider-slots)

名称

Description

Type

default

自定义默认内容

config: 提供全局配置（从顶部继承）

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/config-provider) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/config-provider.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/config-provider.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/33687038?v=4&size=64)](https://github.com/guozi9999)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/35426360?v=4&size=64)](https://github.com/Jungzl)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)[![](https://avatars.githubusercontent.com/u/106626227?v=4&size=64)](https://github.com/build-admin)

[Typography 排版](/zh-CN/component/typography)

[Autocomplete 自动补全输入框](/zh-CN/component/autocomplete)

---

<!-- ============================================ -->
<!-- 类别: 表单组件 -->
<!-- ============================================ -->

## [form/autocomplete] Autocomplete 自动补全输入框
> 官方文档: https://element-plus.org/zh-CN/component/autocomplete.html

---

# 自动补全输入框 [​](#自动补全输入框)

更新日志待解决

6

根据输入内容提供对应的输入建议。

## 基础用法 [​](#基础用法)

Autocomplete 组件提供输入建议。

`fetch-suggestions` 属性是返回建议输入的方法。 在此示例中， `querySearch(queryString, cb)` 方法通过 `cb(data)` 给 Autocomplete 组件返回建议。

list suggestions when activated

list suggestions on input

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1hdXRvY29tcGxldGVcIj5cbiAgICA8ZGl2IGNsYXNzPVwiZGVtby1ibG9ja1wiPlxuICAgICAgPGRpdiBjbGFzcz1cImRlbW8tdGl0bGVcIj5saXN0IHN1Z2dlc3Rpb25zIHdoZW4gYWN0aXZhdGVkPC9kaXY+XG4gICAgICA8ZWwtYXV0b2NvbXBsZXRlXG4gICAgICAgIHYtbW9kZWw9XCJzdGF0ZTFcIlxuICAgICAgICA6ZmV0Y2gtc3VnZ2VzdGlvbnM9XCJxdWVyeVNlYXJjaFwiXG4gICAgICAgIGNsZWFyYWJsZVxuICAgICAgICBjbGFzcz1cInctNTBcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBJbnB1dFwiXG4gICAgICAgIEBzZWxlY3Q9XCJoYW5kbGVTZWxlY3RcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwiZGVtby1ibG9ja1wiPlxuICAgICAgPGRpdiBjbGFzcz1cImRlbW8tdGl0bGVcIj5saXN0IHN1Z2dlc3Rpb25zIG9uIGlucHV0PC9kaXY+XG4gICAgICA8ZWwtYXV0b2NvbXBsZXRlXG4gICAgICAgIHYtbW9kZWw9XCJzdGF0ZTJcIlxuICAgICAgICA6ZmV0Y2gtc3VnZ2VzdGlvbnM9XCJxdWVyeVNlYXJjaFwiXG4gICAgICAgIDp0cmlnZ2VyLW9uLWZvY3VzPVwiZmFsc2VcIlxuICAgICAgICBjbGVhcmFibGVcbiAgICAgICAgY2xhc3M9XCJ3LTUwXCJcbiAgICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgSW5wdXRcIlxuICAgICAgICBAc2VsZWN0PVwiaGFuZGxlU2VsZWN0XCJcbiAgICAgIC8+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IG9uTW91bnRlZCwgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbnRlcmZhY2UgUmVzdGF1cmFudEl0ZW0ge1xuICB2YWx1ZTogc3RyaW5nXG4gIGxpbms6IHN0cmluZ1xufVxuXG5jb25zdCBzdGF0ZTEgPSByZWYoJycpXG5jb25zdCBzdGF0ZTIgPSByZWYoJycpXG5cbmNvbnN0IHJlc3RhdXJhbnRzID0gcmVmPFJlc3RhdXJhbnRJdGVtW10+KFtdKVxuY29uc3QgcXVlcnlTZWFyY2ggPSAocXVlcnlTdHJpbmc6IHN0cmluZywgY2I6IGFueSkgPT4ge1xuICBjb25zdCByZXN1bHRzID0gcXVlcnlTdHJpbmdcbiAgICA/IHJlc3RhdXJhbnRzLnZhbHVlLmZpbHRlcihjcmVhdGVGaWx0ZXIocXVlcnlTdHJpbmcpKVxuICAgIDogcmVzdGF1cmFudHMudmFsdWVcbiAgLy8gY2FsbCBjYWxsYmFjayBmdW5jdGlvbiB0byByZXR1cm4gc3VnZ2VzdGlvbnNcbiAgY2IocmVzdWx0cylcbn1cbmNvbnN0IGNyZWF0ZUZpbHRlciA9IChxdWVyeVN0cmluZzogc3RyaW5nKSA9PiB7XG4gIHJldHVybiAocmVzdGF1cmFudDogUmVzdGF1cmFudEl0ZW0pID0+IHtcbiAgICByZXR1cm4gKFxuICAgICAgcmVzdGF1cmFudC52YWx1ZS50b0xvd2VyQ2FzZSgpLmluZGV4T2YocXVlcnlTdHJpbmcudG9Mb3dlckNhc2UoKSkgPT09IDBcbiAgICApXG4gIH1cbn1cbmNvbnN0IGxvYWRBbGwgPSAoKSA9PiB7XG4gIHJldHVybiBbXG4gICAgeyB2YWx1ZTogJ3Z1ZScsIGxpbms6ICdodHRwczovL2dpdGh1Yi5jb20vdnVlanMvdnVlJyB9LFxuICAgIHsgdmFsdWU6ICdlbGVtZW50JywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS9FbGVtZUZFL2VsZW1lbnQnIH0sXG4gICAgeyB2YWx1ZTogJ2Nvb2tpbmcnLCBsaW5rOiAnaHR0cHM6Ly9naXRodWIuY29tL0VsZW1lRkUvY29va2luZycgfSxcbiAgICB7IHZhbHVlOiAnbWludC11aScsIGxpbms6ICdodHRwczovL2dpdGh1Yi5jb20vRWxlbWVGRS9taW50LXVpJyB9LFxuICAgIHsgdmFsdWU6ICd2dWV4JywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS92dWVqcy92dWV4JyB9LFxuICAgIHsgdmFsdWU6ICd2dWUtcm91dGVyJywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS92dWVqcy92dWUtcm91dGVyJyB9LFxuICAgIHsgdmFsdWU6ICdiYWJlbCcsIGxpbms6ICdodHRwczovL2dpdGh1Yi5jb20vYmFiZWwvYmFiZWwnIH0sXG4gIF1cbn1cblxuY29uc3QgaGFuZGxlU2VsZWN0ID0gKGl0ZW06IFJlY29yZDxzdHJpbmcsIGFueT4pID0+IHtcbiAgY29uc29sZS5sb2coaXRlbSlcbn1cblxub25Nb3VudGVkKCgpID0+IHtcbiAgcmVzdGF1cmFudHMudmFsdWUgPSBsb2FkQWxsKClcbn0pXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWF1dG9jb21wbGV0ZSB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGZsZXgtd3JhcDogd3JhcDtcbiAgZ2FwOiAycmVtO1xufVxuXG4uZGVtby1ibG9jayB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGZsZXgtZGlyZWN0aW9uOiBjb2x1bW47XG4gIGdhcDogMC41cmVtO1xufVxuXG4uZGVtby10aXRsZSB7XG4gIGZvbnQtc2l6ZTogMC44NzVyZW07XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG4gIG1pbi1oZWlnaHQ6IDIuNWVtO1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xufVxuXG5AbWVkaWEgc2NyZWVuIGFuZCAobWF4LXdpZHRoOiA3NjhweCkge1xuICAuZGVtby1hdXRvY29tcGxldGUge1xuICAgIGdhcDogMXJlbTtcbiAgfVxuXG4gIC5kZW1vLWJsb2NrIHtcbiAgICB3aWR0aDogMTAwJTtcbiAgfVxufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/autocomplete/autocomplete.vue)_

vue

```
<template>
  <div class="demo-autocomplete">
    <div class="demo-block">
      <div class="demo-title">list suggestions when activated</div>
      <el-autocomplete
        v-model="state1"
        :fetch-suggestions="querySearch"
        clearable
        class="w-50"
        placeholder="Please Input"
        @select="handleSelect"
      />
    </div>
    <div class="demo-block">
      <div class="demo-title">list suggestions on input</div>
      <el-autocomplete
        v-model="state2"
        :fetch-suggestions="querySearch"
        :trigger-on-focus="false"
        clearable
        class="w-50"
        placeholder="Please Input"
        @select="handleSelect"
      />
    </div>
  </div>
</template>

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

interface RestaurantItem {
  value: string
  link: string
}

const state1 = ref('')
const state2 = ref('')

const restaurants = ref<RestaurantItem[]>([])
const querySearch = (queryString: string, cb: any) => {
  const results = queryString
    ? restaurants.value.filter(createFilter(queryString))
    : restaurants.value
  // call callback function to return suggestions
  cb(results)
}
const createFilter = (queryString: string) => {
  return (restaurant: RestaurantItem) => {
    return (
      restaurant.value.toLowerCase().indexOf(queryString.toLowerCase()) === 0
    )
  }
}
const loadAll = () => {
  return [
    { value: 'vue', link: 'https://github.com/vuejs/vue' },
    { value: 'element', link: 'https://github.com/ElemeFE/element' },
    { value: 'cooking', link: 'https://github.com/ElemeFE/cooking' },
    { value: 'mint-ui', link: 'https://github.com/ElemeFE/mint-ui' },
    { value: 'vuex', link: 'https://github.com/vuejs/vuex' },
    { value: 'vue-router', link: 'https://github.com/vuejs/vue-router' },
    { value: 'babel', link: 'https://github.com/babel/babel' },
  ]
}

const handleSelect = (item: Record<string, any>) => {
  console.log(item)
}

onMounted(() => {
  restaurants.value = loadAll()
})
</script>

<style scoped>
.demo-autocomplete {
  display: flex;
  flex-wrap: wrap;
  gap: 2rem;
}

.demo-block {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}

.demo-title {
  font-size: 0.875rem;
  color: var(--el-text-color-secondary);
  min-height: 2.5em;
  display: flex;
  align-items: center;
}

@media screen and (max-width: 768px) {
  .demo-autocomplete {
    gap: 1rem;
  }

  .demo-block {
    width: 100%;
  }
}
</style>
```

隐藏源代码

## 自定义模板 [​](#自定义模板)

自定义如何显示输入建议。

使用 `scoped slot` 自定义输入建议。 在这个范围中，你可以使用 `item` 键来访问当前输入建议对象。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYXV0b2NvbXBsZXRlXG4gICAgdi1tb2RlbD1cInN0YXRlXCJcbiAgICA6ZmV0Y2gtc3VnZ2VzdGlvbnM9XCJxdWVyeVNlYXJjaFwiXG4gICAgcG9wcGVyLWNsYXNzPVwibXktYXV0b2NvbXBsZXRlXCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgQHNlbGVjdD1cImhhbmRsZVNlbGVjdFwiXG4gID5cbiAgICA8dGVtcGxhdGUgI3N1ZmZpeD5cbiAgICAgIDxlbC1pY29uIGNsYXNzPVwiZWwtaW5wdXRfX2ljb25cIiBAY2xpY2s9XCJoYW5kbGVJY29uQ2xpY2tcIj5cbiAgICAgICAgPGVkaXQgLz5cbiAgICAgIDwvZWwtaWNvbj5cbiAgICA8L3RlbXBsYXRlPlxuICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD1cInsgaXRlbSB9XCI+XG4gICAgICA8ZGl2IGNsYXNzPVwidmFsdWVcIj57eyBpdGVtLnZhbHVlIH19PC9kaXY+XG4gICAgICA8c3BhbiBjbGFzcz1cImxpbmtcIj57eyBpdGVtLmxpbmsgfX08L3NwYW4+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1hdXRvY29tcGxldGU+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgb25Nb3VudGVkLCByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBFZGl0IH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmludGVyZmFjZSBMaW5rSXRlbSB7XG4gIHZhbHVlOiBzdHJpbmdcbiAgbGluazogc3RyaW5nXG59XG5cbmNvbnN0IHN0YXRlID0gcmVmKCcnKVxuY29uc3QgbGlua3MgPSByZWY8TGlua0l0ZW1bXT4oW10pXG5cbmNvbnN0IHF1ZXJ5U2VhcmNoID0gKHF1ZXJ5U3RyaW5nOiBzdHJpbmcsIGNiKSA9PiB7XG4gIGNvbnN0IHJlc3VsdHMgPSBxdWVyeVN0cmluZ1xuICAgID8gbGlua3MudmFsdWUuZmlsdGVyKGNyZWF0ZUZpbHRlcihxdWVyeVN0cmluZykpXG4gICAgOiBsaW5rcy52YWx1ZVxuICAvLyBjYWxsIGNhbGxiYWNrIGZ1bmN0aW9uIHRvIHJldHVybiBzdWdnZXN0aW9uIG9iamVjdHNcbiAgY2IocmVzdWx0cylcbn1cbmNvbnN0IGNyZWF0ZUZpbHRlciA9IChxdWVyeVN0cmluZzogc3RyaW5nKSA9PiB7XG4gIHJldHVybiAocmVzdGF1cmFudDogTGlua0l0ZW0pID0+IHtcbiAgICByZXR1cm4gKFxuICAgICAgcmVzdGF1cmFudC52YWx1ZS50b0xvd2VyQ2FzZSgpLmluZGV4T2YocXVlcnlTdHJpbmcudG9Mb3dlckNhc2UoKSkgPT09IDBcbiAgICApXG4gIH1cbn1cbmNvbnN0IGxvYWRBbGwgPSAoKSA9PiB7XG4gIHJldHVybiBbXG4gICAgeyB2YWx1ZTogJ3Z1ZScsIGxpbms6ICdodHRwczovL2dpdGh1Yi5jb20vdnVlanMvdnVlJyB9LFxuICAgIHsgdmFsdWU6ICdlbGVtZW50JywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS9FbGVtZUZFL2VsZW1lbnQnIH0sXG4gICAgeyB2YWx1ZTogJ2Nvb2tpbmcnLCBsaW5rOiAnaHR0cHM6Ly9naXRodWIuY29tL0VsZW1lRkUvY29va2luZycgfSxcbiAgICB7IHZhbHVlOiAnbWludC11aScsIGxpbms6ICdodHRwczovL2dpdGh1Yi5jb20vRWxlbWVGRS9taW50LXVpJyB9LFxuICAgIHsgdmFsdWU6ICd2dWV4JywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS92dWVqcy92dWV4JyB9LFxuICAgIHsgdmFsdWU6ICd2dWUtcm91dGVyJywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS92dWVqcy92dWUtcm91dGVyJyB9LFxuICAgIHsgdmFsdWU6ICdiYWJlbCcsIGxpbms6ICdodHRwczovL2dpdGh1Yi5jb20vYmFiZWwvYmFiZWwnIH0sXG4gIF1cbn1cbmNvbnN0IGhhbmRsZVNlbGVjdCA9IChpdGVtOiBSZWNvcmQ8c3RyaW5nLCBhbnk+KSA9PiB7XG4gIGNvbnNvbGUubG9nKGl0ZW0pXG59XG5cbmNvbnN0IGhhbmRsZUljb25DbGljayA9IChldjogRXZlbnQpID0+IHtcbiAgY29uc29sZS5sb2coZXYpXG59XG5cbm9uTW91bnRlZCgoKSA9PiB7XG4gIGxpbmtzLnZhbHVlID0gbG9hZEFsbCgpXG59KVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5teS1hdXRvY29tcGxldGUgbGkge1xuICBsaW5lLWhlaWdodDogbm9ybWFsO1xuICBwYWRkaW5nOiA3cHg7XG59XG4ubXktYXV0b2NvbXBsZXRlIGxpIC5uYW1lIHtcbiAgdGV4dC1vdmVyZmxvdzogZWxsaXBzaXM7XG4gIG92ZXJmbG93OiBoaWRkZW47XG59XG4ubXktYXV0b2NvbXBsZXRlIGxpIC5hZGRyIHtcbiAgZm9udC1zaXplOiAxMnB4O1xuICBjb2xvcjogI2I0YjRiNDtcbn1cbi5teS1hdXRvY29tcGxldGUgbGkgLmhpZ2hsaWdodGVkIC5hZGRyIHtcbiAgY29sb3I6ICNkZGQ7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/autocomplete/autocomplete-template.vue)_

vue

```
<template>
  <el-autocomplete
    v-model="state"
    :fetch-suggestions="querySearch"
    popper-class="my-autocomplete"
    placeholder="Please input"
    @select="handleSelect"
  >
    <template #suffix>
      <el-icon class="el-input__icon" @click="handleIconClick">
        <edit />
      </el-icon>
    </template>
    <template #default="{ item }">
      <div class="value">{{ item.value }}</div>
      <span class="link">{{ item.link }}</span>
    </template>
  </el-autocomplete>
</template>

<script lang="ts" setup>
import { onMounted, ref } from 'vue'
import { Edit } from '@element-plus/icons-vue'

interface LinkItem {
  value: string
  link: string
}

const state = ref('')
const links = ref<LinkItem[]>([])

const querySearch = (queryString: string, cb) => {
  const results = queryString
    ? links.value.filter(createFilter(queryString))
    : links.value
  // call callback function to return suggestion objects
  cb(results)
}
const createFilter = (queryString: string) => {
  return (restaurant: LinkItem) => {
    return (
      restaurant.value.toLowerCase().indexOf(queryString.toLowerCase()) === 0
    )
  }
}
const loadAll = () => {
  return [
    { value: 'vue', link: 'https://github.com/vuejs/vue' },
    { value: 'element', link: 'https://github.com/ElemeFE/element' },
    { value: 'cooking', link: 'https://github.com/ElemeFE/cooking' },
    { value: 'mint-ui', link: 'https://github.com/ElemeFE/mint-ui' },
    { value: 'vuex', link: 'https://github.com/vuejs/vuex' },
    { value: 'vue-router', link: 'https://github.com/vuejs/vue-router' },
    { value: 'babel', link: 'https://github.com/babel/babel' },
  ]
}
const handleSelect = (item: Record<string, any>) => {
  console.log(item)
}

const handleIconClick = (ev: Event) => {
  console.log(ev)
}

onMounted(() => {
  links.value = loadAll()
})
</script>

<style>
.my-autocomplete li {
  line-height: normal;
  padding: 7px;
}
.my-autocomplete li .name {
  text-overflow: ellipsis;
  overflow: hidden;
}
.my-autocomplete li .addr {
  font-size: 12px;
  color: #b4b4b4;
}
.my-autocomplete li .highlighted .addr {
  color: #ddd;
}
</style>
```

隐藏源代码

## 远程搜索 [​](#远程搜索)

从服务端搜索数据。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYXV0b2NvbXBsZXRlXG4gICAgdi1tb2RlbD1cInN0YXRlXCJcbiAgICA6ZmV0Y2gtc3VnZ2VzdGlvbnM9XCJxdWVyeVNlYXJjaEFzeW5jXCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgQHNlbGVjdD1cImhhbmRsZVNlbGVjdFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgb25Nb3VudGVkLCByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHN0YXRlID0gcmVmKCcnKVxuXG5pbnRlcmZhY2UgTGlua0l0ZW0ge1xuICB2YWx1ZTogc3RyaW5nXG4gIGxpbms6IHN0cmluZ1xufVxuXG5jb25zdCBsaW5rcyA9IHJlZjxMaW5rSXRlbVtdPihbXSlcblxuY29uc3QgbG9hZEFsbCA9ICgpID0+IHtcbiAgcmV0dXJuIFtcbiAgICB7IHZhbHVlOiAndnVlJywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS92dWVqcy92dWUnIH0sXG4gICAgeyB2YWx1ZTogJ2VsZW1lbnQnLCBsaW5rOiAnaHR0cHM6Ly9naXRodWIuY29tL0VsZW1lRkUvZWxlbWVudCcgfSxcbiAgICB7IHZhbHVlOiAnY29va2luZycsIGxpbms6ICdodHRwczovL2dpdGh1Yi5jb20vRWxlbWVGRS9jb29raW5nJyB9LFxuICAgIHsgdmFsdWU6ICdtaW50LXVpJywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS9FbGVtZUZFL21pbnQtdWknIH0sXG4gICAgeyB2YWx1ZTogJ3Z1ZXgnLCBsaW5rOiAnaHR0cHM6Ly9naXRodWIuY29tL3Z1ZWpzL3Z1ZXgnIH0sXG4gICAgeyB2YWx1ZTogJ3Z1ZS1yb3V0ZXInLCBsaW5rOiAnaHR0cHM6Ly9naXRodWIuY29tL3Z1ZWpzL3Z1ZS1yb3V0ZXInIH0sXG4gICAgeyB2YWx1ZTogJ2JhYmVsJywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS9iYWJlbC9iYWJlbCcgfSxcbiAgXVxufVxuXG5sZXQgdGltZW91dDogUmV0dXJuVHlwZTx0eXBlb2Ygc2V0VGltZW91dD5cbmNvbnN0IHF1ZXJ5U2VhcmNoQXN5bmMgPSAocXVlcnlTdHJpbmc6IHN0cmluZywgY2I6IChhcmc6IGFueSkgPT4gdm9pZCkgPT4ge1xuICBjb25zdCByZXN1bHRzID0gcXVlcnlTdHJpbmdcbiAgICA/IGxpbmtzLnZhbHVlLmZpbHRlcihjcmVhdGVGaWx0ZXIocXVlcnlTdHJpbmcpKVxuICAgIDogbGlua3MudmFsdWVcblxuICBjbGVhclRpbWVvdXQodGltZW91dClcbiAgdGltZW91dCA9IHNldFRpbWVvdXQoKCkgPT4ge1xuICAgIGNiKHJlc3VsdHMpXG4gIH0sIDMwMDAgKiBNYXRoLnJhbmRvbSgpKVxufVxuY29uc3QgY3JlYXRlRmlsdGVyID0gKHF1ZXJ5U3RyaW5nOiBzdHJpbmcpID0+IHtcbiAgcmV0dXJuIChyZXN0YXVyYW50OiBMaW5rSXRlbSkgPT4ge1xuICAgIHJldHVybiAoXG4gICAgICByZXN0YXVyYW50LnZhbHVlLnRvTG93ZXJDYXNlKCkuaW5kZXhPZihxdWVyeVN0cmluZy50b0xvd2VyQ2FzZSgpKSA9PT0gMFxuICAgIClcbiAgfVxufVxuXG5jb25zdCBoYW5kbGVTZWxlY3QgPSAoaXRlbTogUmVjb3JkPHN0cmluZywgYW55PikgPT4ge1xuICBjb25zb2xlLmxvZyhpdGVtKVxufVxuXG5vbk1vdW50ZWQoKCkgPT4ge1xuICBsaW5rcy52YWx1ZSA9IGxvYWRBbGwoKVxufSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/autocomplete/remote-search.vue)_

vue

```
<template>
  <el-autocomplete
    v-model="state"
    :fetch-suggestions="querySearchAsync"
    placeholder="Please input"
    @select="handleSelect"
  />
</template>

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

const state = ref('')

interface LinkItem {
  value: string
  link: string
}

const links = ref<LinkItem[]>([])

const loadAll = () => {
  return [
    { value: 'vue', link: 'https://github.com/vuejs/vue' },
    { value: 'element', link: 'https://github.com/ElemeFE/element' },
    { value: 'cooking', link: 'https://github.com/ElemeFE/cooking' },
    { value: 'mint-ui', link: 'https://github.com/ElemeFE/mint-ui' },
    { value: 'vuex', link: 'https://github.com/vuejs/vuex' },
    { value: 'vue-router', link: 'https://github.com/vuejs/vue-router' },
    { value: 'babel', link: 'https://github.com/babel/babel' },
  ]
}

let timeout: ReturnType<typeof setTimeout>
const querySearchAsync = (queryString: string, cb: (arg: any) => void) => {
  const results = queryString
    ? links.value.filter(createFilter(queryString))
    : links.value

  clearTimeout(timeout)
  timeout = setTimeout(() => {
    cb(results)
  }, 3000 * Math.random())
}
const createFilter = (queryString: string) => {
  return (restaurant: LinkItem) => {
    return (
      restaurant.value.toLowerCase().indexOf(queryString.toLowerCase()) === 0
    )
  }
}

const handleSelect = (item: Record<string, any>) => {
  console.log(item)
}

onMounted(() => {
  links.value = loadAll()
})
</script>
```

隐藏源代码

## 自定义加载 2.5.0 [​](#自定义加载)

修改加载区域内容

loading icon1

loading icon2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1hdXRvY29tcGxldGVcIj5cbiAgICA8ZGl2IGNsYXNzPVwiZGVtby1ibG9ja1wiPlxuICAgICAgPGRpdiBjbGFzcz1cImRlbW8tdGl0bGVcIj5sb2FkaW5nIGljb24xPC9kaXY+XG4gICAgICA8ZWwtYXV0b2NvbXBsZXRlXG4gICAgICAgIHYtbW9kZWw9XCJzdGF0ZVwiXG4gICAgICAgIDpmZXRjaC1zdWdnZXN0aW9ucz1cInF1ZXJ5U2VhcmNoQXN5bmNcIlxuICAgICAgICBjbGFzcz1cInctNTBcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgICAgIEBzZWxlY3Q9XCJoYW5kbGVTZWxlY3RcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI2xvYWRpbmc+XG4gICAgICAgICAgPHN2ZyBjbGFzcz1cImNpcmN1bGFyXCIgdmlld0JveD1cIjAgMCA1MCA1MFwiPlxuICAgICAgICAgICAgPGNpcmNsZSBjbGFzcz1cInBhdGhcIiBjeD1cIjI1XCIgY3k9XCIyNVwiIHI9XCIyMFwiIGZpbGw9XCJub25lXCIgLz5cbiAgICAgICAgICA8L3N2Zz5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtYXV0b2NvbXBsZXRlPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJkZW1vLWJsb2NrXCI+XG4gICAgICA8ZGl2IGNsYXNzPVwiZGVtby10aXRsZVwiPmxvYWRpbmcgaWNvbjI8L2Rpdj5cbiAgICAgIDxlbC1hdXRvY29tcGxldGVcbiAgICAgICAgdi1tb2RlbD1cInN0YXRlXCJcbiAgICAgICAgOmZldGNoLXN1Z2dlc3Rpb25zPVwicXVlcnlTZWFyY2hBc3luY1wiXG4gICAgICAgIGNsYXNzPVwidy01MFwiXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgICAgICAgQHNlbGVjdD1cImhhbmRsZVNlbGVjdFwiXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjbG9hZGluZz5cbiAgICAgICAgICA8ZWwtaWNvbiBjbGFzcz1cImlzLWxvYWRpbmdcIj5cbiAgICAgICAgICAgIDxzdmcgY2xhc3M9XCJjaXJjdWxhclwiIHZpZXdCb3g9XCIwIDAgMjAgMjBcIj5cbiAgICAgICAgICAgICAgPGdcbiAgICAgICAgICAgICAgICBjbGFzcz1cInBhdGgyIGxvYWRpbmctcGF0aFwiXG4gICAgICAgICAgICAgICAgc3Ryb2tlLXdpZHRoPVwiMFwiXG4gICAgICAgICAgICAgICAgc3R5bGU9XCJhbmltYXRpb246IG5vbmU7IHN0cm9rZTogbm9uZVwiXG4gICAgICAgICAgICAgID5cbiAgICAgICAgICAgICAgICA8Y2lyY2xlIHI9XCIzLjM3NVwiIGNsYXNzPVwiZG90MVwiIHJ4PVwiMFwiIHJ5PVwiMFwiIC8+XG4gICAgICAgICAgICAgICAgPGNpcmNsZSByPVwiMy4zNzVcIiBjbGFzcz1cImRvdDJcIiByeD1cIjBcIiByeT1cIjBcIiAvPlxuICAgICAgICAgICAgICAgIDxjaXJjbGUgcj1cIjMuMzc1XCIgY2xhc3M9XCJkb3Q0XCIgcng9XCIwXCIgcnk9XCIwXCIgLz5cbiAgICAgICAgICAgICAgICA8Y2lyY2xlIHI9XCIzLjM3NVwiIGNsYXNzPVwiZG90M1wiIHJ4PVwiMFwiIHJ5PVwiMFwiIC8+XG4gICAgICAgICAgICAgIDwvZz5cbiAgICAgICAgICAgIDwvc3ZnPlxuICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtYXV0b2NvbXBsZXRlPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBvbk1vdW50ZWQsIHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3Qgc3RhdGUgPSByZWYoJycpXG5cbmludGVyZmFjZSBMaW5rSXRlbSB7XG4gIHZhbHVlOiBzdHJpbmdcbiAgbGluazogc3RyaW5nXG59XG5cbmNvbnN0IGxpbmtzID0gcmVmPExpbmtJdGVtW10+KFtdKVxuXG5jb25zdCBsb2FkQWxsID0gKCkgPT4ge1xuICByZXR1cm4gW1xuICAgIHsgdmFsdWU6ICd2dWUnLCBsaW5rOiAnaHR0cHM6Ly9naXRodWIuY29tL3Z1ZWpzL3Z1ZScgfSxcbiAgICB7IHZhbHVlOiAnZWxlbWVudCcsIGxpbms6ICdodHRwczovL2dpdGh1Yi5jb20vRWxlbWVGRS9lbGVtZW50JyB9LFxuICAgIHsgdmFsdWU6ICdjb29raW5nJywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS9FbGVtZUZFL2Nvb2tpbmcnIH0sXG4gICAgeyB2YWx1ZTogJ21pbnQtdWknLCBsaW5rOiAnaHR0cHM6Ly9naXRodWIuY29tL0VsZW1lRkUvbWludC11aScgfSxcbiAgICB7IHZhbHVlOiAndnVleCcsIGxpbms6ICdodHRwczovL2dpdGh1Yi5jb20vdnVlanMvdnVleCcgfSxcbiAgICB7IHZhbHVlOiAndnVlLXJvdXRlcicsIGxpbms6ICdodHRwczovL2dpdGh1Yi5jb20vdnVlanMvdnVlLXJvdXRlcicgfSxcbiAgICB7IHZhbHVlOiAnYmFiZWwnLCBsaW5rOiAnaHR0cHM6Ly9naXRodWIuY29tL2JhYmVsL2JhYmVsJyB9LFxuICBdXG59XG5cbmxldCB0aW1lb3V0OiBSZXR1cm5UeXBlPHR5cGVvZiBzZXRUaW1lb3V0PlxuY29uc3QgcXVlcnlTZWFyY2hBc3luYyA9IChxdWVyeVN0cmluZzogc3RyaW5nLCBjYjogKGFyZzogYW55KSA9PiB2b2lkKSA9PiB7XG4gIGNvbnN0IHJlc3VsdHMgPSBxdWVyeVN0cmluZ1xuICAgID8gbGlua3MudmFsdWUuZmlsdGVyKGNyZWF0ZUZpbHRlcihxdWVyeVN0cmluZykpXG4gICAgOiBsaW5rcy52YWx1ZVxuXG4gIGNsZWFyVGltZW91dCh0aW1lb3V0KVxuICB0aW1lb3V0ID0gc2V0VGltZW91dCgoKSA9PiB7XG4gICAgY2IocmVzdWx0cylcbiAgfSwgNTAwMCAqIE1hdGgucmFuZG9tKCkpXG59XG5jb25zdCBjcmVhdGVGaWx0ZXIgPSAocXVlcnlTdHJpbmc6IHN0cmluZykgPT4ge1xuICByZXR1cm4gKHJlc3RhdXJhbnQ6IExpbmtJdGVtKSA9PiB7XG4gICAgcmV0dXJuIChcbiAgICAgIHJlc3RhdXJhbnQudmFsdWUudG9Mb3dlckNhc2UoKS5pbmRleE9mKHF1ZXJ5U3RyaW5nLnRvTG93ZXJDYXNlKCkpID09PSAwXG4gICAgKVxuICB9XG59XG5cbmNvbnN0IGhhbmRsZVNlbGVjdCA9IChpdGVtOiBSZWNvcmQ8c3RyaW5nLCBhbnk+KSA9PiB7XG4gIGNvbnNvbGUubG9nKGl0ZW0pXG59XG5cbm9uTW91bnRlZCgoKSA9PiB7XG4gIGxpbmtzLnZhbHVlID0gbG9hZEFsbCgpXG59KVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1hdXRvY29tcGxldGUge1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LXdyYXA6IHdyYXA7XG4gIGdhcDogMnJlbTtcbn1cblxuLmRlbW8tYmxvY2sge1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LWRpcmVjdGlvbjogY29sdW1uO1xuICBnYXA6IDAuNXJlbTtcbn1cblxuLmRlbW8tdGl0bGUge1xuICBmb250LXNpemU6IDAuODc1cmVtO1xuICBjb2xvcjogdmFyKC0tZWwtdGV4dC1jb2xvci1zZWNvbmRhcnkpO1xuICBtaW4taGVpZ2h0OiAyLjVlbTtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbn1cblxuQG1lZGlhIHNjcmVlbiBhbmQgKG1heC13aWR0aDogNzY4cHgpIHtcbiAgLmRlbW8tYXV0b2NvbXBsZXRlIHtcbiAgICBnYXA6IDFyZW07XG4gIH1cbiAgLmRlbW8tYmxvY2sge1xuICAgIHdpZHRoOiAxMDAlO1xuICB9XG59XG48L3N0eWxlPlxuXG48c3R5bGU+XG4uY2lyY3VsYXIge1xuICBkaXNwbGF5OiBpbmxpbmU7XG4gIGhlaWdodDogMzBweDtcbiAgd2lkdGg6IDMwcHg7XG4gIGFuaW1hdGlvbjogbG9hZGluZy1yb3RhdGUgMnMgbGluZWFyIGluZmluaXRlO1xufVxuLnBhdGgge1xuICBhbmltYXRpb246IGxvYWRpbmctZGFzaCAxLjVzIGVhc2UtaW4tb3V0IGluZmluaXRlO1xuICBzdHJva2UtZGFzaGFycmF5OiA5MCwgMTUwO1xuICBzdHJva2UtZGFzaG9mZnNldDogMDtcbiAgc3Ryb2tlLXdpZHRoOiAyO1xuICBzdHJva2U6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xuICBzdHJva2UtbGluZWNhcDogcm91bmQ7XG59XG4ubG9hZGluZy1wYXRoIC5kb3QxIHtcbiAgdHJhbnNmb3JtOiB0cmFuc2xhdGUoMy43NXB4LCAzLjc1cHgpO1xuICBmaWxsOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbiAgYW5pbWF0aW9uOiBjdXN0b20tc3Bpbi1tb3ZlIDFzIGluZmluaXRlIGxpbmVhciBhbHRlcm5hdGU7XG4gIG9wYWNpdHk6IDAuMztcbn1cbi5sb2FkaW5nLXBhdGggLmRvdDIge1xuICB0cmFuc2Zvcm06IHRyYW5zbGF0ZShjYWxjKDEwMCUgLSAzLjc1cHgpLCAzLjc1cHgpO1xuICBmaWxsOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbiAgYW5pbWF0aW9uOiBjdXN0b20tc3Bpbi1tb3ZlIDFzIGluZmluaXRlIGxpbmVhciBhbHRlcm5hdGU7XG4gIG9wYWNpdHk6IDAuMztcbiAgYW5pbWF0aW9uLWRlbGF5OiAwLjRzO1xufVxuLmxvYWRpbmctcGF0aCAuZG90MyB7XG4gIHRyYW5zZm9ybTogdHJhbnNsYXRlKDMuNzVweCwgY2FsYygxMDAlIC0gMy43NXB4KSk7XG4gIGZpbGw6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xuICBhbmltYXRpb246IGN1c3RvbS1zcGluLW1vdmUgMXMgaW5maW5pdGUgbGluZWFyIGFsdGVybmF0ZTtcbiAgb3BhY2l0eTogMC4zO1xuICBhbmltYXRpb24tZGVsYXk6IDEuMnM7XG59XG4ubG9hZGluZy1wYXRoIC5kb3Q0IHtcbiAgdHJhbnNmb3JtOiB0cmFuc2xhdGUoY2FsYygxMDAlIC0gMy43NXB4KSwgY2FsYygxMDAlIC0gMy43NXB4KSk7XG4gIGZpbGw6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xuICBhbmltYXRpb246IGN1c3RvbS1zcGluLW1vdmUgMXMgaW5maW5pdGUgbGluZWFyIGFsdGVybmF0ZTtcbiAgb3BhY2l0eTogMC4zO1xuICBhbmltYXRpb24tZGVsYXk6IDAuOHM7XG59XG5Aa2V5ZnJhbWVzIGxvYWRpbmctcm90YXRlIHtcbiAgdG8ge1xuICAgIHRyYW5zZm9ybTogcm90YXRlKDM2MGRlZyk7XG4gIH1cbn1cbkBrZXlmcmFtZXMgbG9hZGluZy1kYXNoIHtcbiAgMCUge1xuICAgIHN0cm9rZS1kYXNoYXJyYXk6IDEsIDIwMDtcbiAgICBzdHJva2UtZGFzaG9mZnNldDogMDtcbiAgfVxuICA1MCUge1xuICAgIHN0cm9rZS1kYXNoYXJyYXk6IDkwLCAxNTA7XG4gICAgc3Ryb2tlLWRhc2hvZmZzZXQ6IC00MHB4O1xuICB9XG4gIDEwMCUge1xuICAgIHN0cm9rZS1kYXNoYXJyYXk6IDkwLCAxNTA7XG4gICAgc3Ryb2tlLWRhc2hvZmZzZXQ6IC0xMjBweDtcbiAgfVxufVxuQGtleWZyYW1lcyBjdXN0b20tc3Bpbi1tb3ZlIHtcbiAgdG8ge1xuICAgIG9wYWNpdHk6IDE7XG4gIH1cbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/autocomplete/custom-loading.vue)_

vue

```
<template>
  <div class="demo-autocomplete">
    <div class="demo-block">
      <div class="demo-title">loading icon1</div>
      <el-autocomplete
        v-model="state"
        :fetch-suggestions="querySearchAsync"
        class="w-50"
        placeholder="Please input"
        @select="handleSelect"
      >
        <template #loading>
          <svg class="circular" viewBox="0 0 50 50">
            <circle class="path" cx="25" cy="25" r="20" fill="none" />
          </svg>
        </template>
      </el-autocomplete>
    </div>
    <div class="demo-block">
      <div class="demo-title">loading icon2</div>
      <el-autocomplete
        v-model="state"
        :fetch-suggestions="querySearchAsync"
        class="w-50"
        placeholder="Please input"
        @select="handleSelect"
      >
        <template #loading>
          <el-icon class="is-loading">
            <svg class="circular" viewBox="0 0 20 20">
              <g
                class="path2 loading-path"
                stroke-width="0"
                style="animation: none; stroke: none"
              >
                <circle r="3.375" class="dot1" rx="0" ry="0" />
                <circle r="3.375" class="dot2" rx="0" ry="0" />
                <circle r="3.375" class="dot4" rx="0" ry="0" />
                <circle r="3.375" class="dot3" rx="0" ry="0" />
              </g>
            </svg>
          </el-icon>
        </template>
      </el-autocomplete>
    </div>
  </div>
</template>

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

const state = ref('')

interface LinkItem {
  value: string
  link: string
}

const links = ref<LinkItem[]>([])

const loadAll = () => {
  return [
    { value: 'vue', link: 'https://github.com/vuejs/vue' },
    { value: 'element', link: 'https://github.com/ElemeFE/element' },
    { value: 'cooking', link: 'https://github.com/ElemeFE/cooking' },
    { value: 'mint-ui', link: 'https://github.com/ElemeFE/mint-ui' },
    { value: 'vuex', link: 'https://github.com/vuejs/vuex' },
    { value: 'vue-router', link: 'https://github.com/vuejs/vue-router' },
    { value: 'babel', link: 'https://github.com/babel/babel' },
  ]
}

let timeout: ReturnType<typeof setTimeout>
const querySearchAsync = (queryString: string, cb: (arg: any) => void) => {
  const results = queryString
    ? links.value.filter(createFilter(queryString))
    : links.value

  clearTimeout(timeout)
  timeout = setTimeout(() => {
    cb(results)
  }, 5000 * Math.random())
}
const createFilter = (queryString: string) => {
  return (restaurant: LinkItem) => {
    return (
      restaurant.value.toLowerCase().indexOf(queryString.toLowerCase()) === 0
    )
  }
}

const handleSelect = (item: Record<string, any>) => {
  console.log(item)
}

onMounted(() => {
  links.value = loadAll()
})
</script>

<style scoped>
.demo-autocomplete {
  display: flex;
  flex-wrap: wrap;
  gap: 2rem;
}

.demo-block {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}

.demo-title {
  font-size: 0.875rem;
  color: var(--el-text-color-secondary);
  min-height: 2.5em;
  display: flex;
  align-items: center;
}

@media screen and (max-width: 768px) {
  .demo-autocomplete {
    gap: 1rem;
  }
  .demo-block {
    width: 100%;
  }
}
</style>

<style>
.circular {
  display: inline;
  height: 30px;
  width: 30px;
  animation: loading-rotate 2s linear infinite;
}
.path {
  animation: loading-dash 1.5s ease-in-out infinite;
  stroke-dasharray: 90, 150;
  stroke-dashoffset: 0;
  stroke-width: 2;
  stroke: var(--el-color-primary);
  stroke-linecap: round;
}
.loading-path .dot1 {
  transform: translate(3.75px, 3.75px);
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
}
.loading-path .dot2 {
  transform: translate(calc(100% - 3.75px), 3.75px);
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 0.4s;
}
.loading-path .dot3 {
  transform: translate(3.75px, calc(100% - 3.75px));
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 1.2s;
}
.loading-path .dot4 {
  transform: translate(calc(100% - 3.75px), calc(100% - 3.75px));
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 0.8s;
}
@keyframes loading-rotate {
  to {
    transform: rotate(360deg);
  }
}
@keyframes loading-dash {
  0% {
    stroke-dasharray: 1, 200;
    stroke-dashoffset: 0;
  }
  50% {
    stroke-dasharray: 90, 150;
    stroke-dashoffset: -40px;
  }
  100% {
    stroke-dasharray: 90, 150;
    stroke-dashoffset: -120px;
  }
}
@keyframes custom-spin-move {
  to {
    opacity: 1;
  }
}
</style>
```

隐藏源代码

## 自定义头部与底部 2.10.6 [​](#自定义头部与底部)

你可以通过插槽来自定义下拉菜单的头部和底部。

使用插槽自定义内容。

Custom header content

Custom footer content

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiYXV0b2NvbXBsZXRlLWN1c3RvbS1oZWFkZXItZm9vdGVyXCI+XG4gICAgPGRpdj5cbiAgICAgIDxwPkN1c3RvbSBoZWFkZXIgY29udGVudDwvcD5cbiAgICAgIDxlbC1hdXRvY29tcGxldGVcbiAgICAgICAgdi1tb2RlbD1cImhlYWRlclNsb3RTdGF0ZVwiXG4gICAgICAgIDpmZXRjaC1zdWdnZXN0aW9ucz1cInF1ZXJ5U2VhcmNoQXN5bmNcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgICAgIEBzZWxlY3Q9XCJoYW5kbGVTZWxlY3RcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI2hlYWRlcj5oZWFkZXIgY29udGVudDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLWF1dG9jb21wbGV0ZT5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2PlxuICAgICAgPHA+Q3VzdG9tIGZvb3RlciBjb250ZW50PC9wPlxuICAgICAgPGVsLWF1dG9jb21wbGV0ZVxuICAgICAgICByZWY9XCJmb290ZXJBdXRvY29tcGxldGVSZWZcIlxuICAgICAgICB2LW1vZGVsPVwiZm9vdGVyU2xvdHN0YXRlXCJcbiAgICAgICAgOmZldGNoLXN1Z2dlc3Rpb25zPVwicXVlcnlTZWFyY2hBc3luY1wiXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgICAgICAgQHNlbGVjdD1cImhhbmRsZVNlbGVjdFwiXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjZm9vdGVyPlxuICAgICAgICAgIDxlbC1idXR0b24gbGluayBzaXplPVwic21hbGxcIiBAY2xpY2s9XCJoYW5kbGVDbGVhclwiPiBDbGVhciA8L2VsLWJ1dHRvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtYXV0b2NvbXBsZXRlPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBvbk1vdW50ZWQsIHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaGVhZGVyU2xvdFN0YXRlID0gcmVmKCcnKVxuY29uc3QgZm9vdGVyU2xvdHN0YXRlID0gcmVmKCcnKVxuXG5pbnRlcmZhY2UgTGlua0l0ZW0ge1xuICB2YWx1ZTogc3RyaW5nXG4gIGxpbms6IHN0cmluZ1xufVxuXG5jb25zdCBsaW5rcyA9IHJlZjxMaW5rSXRlbVtdPihbXSlcblxuY29uc3QgbG9hZEFsbCA9ICgpID0+IHtcbiAgcmV0dXJuIFtcbiAgICB7IHZhbHVlOiAndnVlJywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS92dWVqcy92dWUnIH0sXG4gICAgeyB2YWx1ZTogJ2VsZW1lbnQnLCBsaW5rOiAnaHR0cHM6Ly9naXRodWIuY29tL0VsZW1lRkUvZWxlbWVudCcgfSxcbiAgICB7IHZhbHVlOiAnY29va2luZycsIGxpbms6ICdodHRwczovL2dpdGh1Yi5jb20vRWxlbWVGRS9jb29raW5nJyB9LFxuICAgIHsgdmFsdWU6ICdtaW50LXVpJywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS9FbGVtZUZFL21pbnQtdWknIH0sXG4gICAgeyB2YWx1ZTogJ3Z1ZXgnLCBsaW5rOiAnaHR0cHM6Ly9naXRodWIuY29tL3Z1ZWpzL3Z1ZXgnIH0sXG4gICAgeyB2YWx1ZTogJ3Z1ZS1yb3V0ZXInLCBsaW5rOiAnaHR0cHM6Ly9naXRodWIuY29tL3Z1ZWpzL3Z1ZS1yb3V0ZXInIH0sXG4gICAgeyB2YWx1ZTogJ2JhYmVsJywgbGluazogJ2h0dHBzOi8vZ2l0aHViLmNvbS9iYWJlbC9iYWJlbCcgfSxcbiAgXVxufVxuXG5sZXQgdGltZW91dDogUmV0dXJuVHlwZTx0eXBlb2Ygc2V0VGltZW91dD5cbmNvbnN0IHF1ZXJ5U2VhcmNoQXN5bmMgPSAocXVlcnlTdHJpbmc6IHN0cmluZywgY2I6IChhcmc6IGFueSkgPT4gdm9pZCkgPT4ge1xuICBjb25zdCByZXN1bHRzID0gcXVlcnlTdHJpbmdcbiAgICA/IGxpbmtzLnZhbHVlLmZpbHRlcihjcmVhdGVGaWx0ZXIocXVlcnlTdHJpbmcpKVxuICAgIDogbGlua3MudmFsdWVcblxuICBjbGVhclRpbWVvdXQodGltZW91dClcbiAgdGltZW91dCA9IHNldFRpbWVvdXQoKCkgPT4ge1xuICAgIGNiKHJlc3VsdHMpXG4gIH0sIDMwMDAgKiBNYXRoLnJhbmRvbSgpKVxufVxuY29uc3QgY3JlYXRlRmlsdGVyID0gKHF1ZXJ5U3RyaW5nOiBzdHJpbmcpID0+IHtcbiAgcmV0dXJuIChyZXN0YXVyYW50OiBMaW5rSXRlbSkgPT4ge1xuICAgIHJldHVybiAoXG4gICAgICByZXN0YXVyYW50LnZhbHVlLnRvTG93ZXJDYXNlKCkuaW5kZXhPZihxdWVyeVN0cmluZy50b0xvd2VyQ2FzZSgpKSA9PT0gMFxuICAgIClcbiAgfVxufVxuXG5jb25zdCBoYW5kbGVTZWxlY3QgPSAoaXRlbTogUmVjb3JkPHN0cmluZywgYW55PikgPT4ge1xuICBjb25zb2xlLmxvZyhpdGVtKVxufVxuXG5vbk1vdW50ZWQoKCkgPT4ge1xuICBsaW5rcy52YWx1ZSA9IGxvYWRBbGwoKVxufSlcblxuY29uc3QgZm9vdGVyQXV0b2NvbXBsZXRlUmVmID0gcmVmKClcbmNvbnN0IGhhbmRsZUNsZWFyID0gKCkgPT4ge1xuICBmb290ZXJTbG90c3RhdGUudmFsdWUgPSAnJ1xuICBmb290ZXJBdXRvY29tcGxldGVSZWYudmFsdWUuZ2V0RGF0YSgpXG59XG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5hdXRvY29tcGxldGUtY3VzdG9tLWhlYWRlci1mb290ZXIge1xuICBkaXNwbGF5OiBmbGV4O1xufVxuXG4uYXV0b2NvbXBsZXRlLWN1c3RvbS1oZWFkZXItZm9vdGVyID4gZGl2IHtcbiAgZmxleDogMTtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xufVxuLmF1dG9jb21wbGV0ZS1jdXN0b20taGVhZGVyLWZvb3RlciA+IGRpdiA+IDpkZWVwKC5lbC1hdXRvY29tcGxldGUpIHtcbiAgd2lkdGg6IDUwJTtcbn1cblxuLmF1dG9jb21wbGV0ZS1jdXN0b20taGVhZGVyLWZvb3RlciA+IGRpdjpub3QoOmxhc3QtY2hpbGQpIHtcbiAgYm9yZGVyLXJpZ2h0OiAxcHggc29saWQgdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/autocomplete/custom-header-footer.vue)_

vue

```
<template>
  <div class="autocomplete-custom-header-footer">
    <div>
      <p>Custom header content</p>
      <el-autocomplete
        v-model="headerSlotState"
        :fetch-suggestions="querySearchAsync"
        placeholder="Please input"
        @select="handleSelect"
      >
        <template #header>header content</template>
      </el-autocomplete>
    </div>
    <div>
      <p>Custom footer content</p>
      <el-autocomplete
        ref="footerAutocompleteRef"
        v-model="footerSlotstate"
        :fetch-suggestions="querySearchAsync"
        placeholder="Please input"
        @select="handleSelect"
      >
        <template #footer>
          <el-button link size="small" @click="handleClear"> Clear </el-button>
        </template>
      </el-autocomplete>
    </div>
  </div>
</template>

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

const headerSlotState = ref('')
const footerSlotstate = ref('')

interface LinkItem {
  value: string
  link: string
}

const links = ref<LinkItem[]>([])

const loadAll = () => {
  return [
    { value: 'vue', link: 'https://github.com/vuejs/vue' },
    { value: 'element', link: 'https://github.com/ElemeFE/element' },
    { value: 'cooking', link: 'https://github.com/ElemeFE/cooking' },
    { value: 'mint-ui', link: 'https://github.com/ElemeFE/mint-ui' },
    { value: 'vuex', link: 'https://github.com/vuejs/vuex' },
    { value: 'vue-router', link: 'https://github.com/vuejs/vue-router' },
    { value: 'babel', link: 'https://github.com/babel/babel' },
  ]
}

let timeout: ReturnType<typeof setTimeout>
const querySearchAsync = (queryString: string, cb: (arg: any) => void) => {
  const results = queryString
    ? links.value.filter(createFilter(queryString))
    : links.value

  clearTimeout(timeout)
  timeout = setTimeout(() => {
    cb(results)
  }, 3000 * Math.random())
}
const createFilter = (queryString: string) => {
  return (restaurant: LinkItem) => {
    return (
      restaurant.value.toLowerCase().indexOf(queryString.toLowerCase()) === 0
    )
  }
}

const handleSelect = (item: Record<string, any>) => {
  console.log(item)
}

onMounted(() => {
  links.value = loadAll()
})

const footerAutocompleteRef = ref()
const handleClear = () => {
  footerSlotstate.value = ''
  footerAutocompleteRef.value.getData()
}
</script>

<style scoped>
.autocomplete-custom-header-footer {
  display: flex;
}

.autocomplete-custom-header-footer > div {
  flex: 1;
  text-align: center;
}
.autocomplete-custom-header-footer > div > :deep(.el-autocomplete) {
  width: 50%;
}

.autocomplete-custom-header-footer > div:not(:last-child) {
  border-right: 1px solid var(--el-border-color);
}
</style>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `string` | — |
| placeholder | 占位文本 | `string` | — |
| clearable | 是否可清空 | `boolean` | false |
| disabled | 自动补全组件是否被禁用 | `boolean` | false |
| value-key | 输入建议对象中用于显示的键名 | `string` | value |
| debounce | 获取输入建议的防抖延时，单位为毫秒 | `number` | 300 |
| placement | 菜单弹出位置 | `enum` | bottom-start |
| fetch-suggestions | 获取输入建议的方法， 仅当你的输入建议数据 resolve 时，通过调用 `callback(data:[])` 来返回它 | `array` / `Function` | — |
| trigger-on-focus | whether show suggestions when input focus | `boolean` | true |
| select-when-unmatched | 在输入没有任何匹配建议的情况下，按下回车是否触发 `select` 事件 | `boolean` | false |
| name | 等价于原生 input `name` 属性 | `string` | — |
| aria-label a11y 2.7.2 | 原生 `aria-label`属性 | `string` | — |
| hide-loading | 是否隐藏远程加载时的加载图标 | `boolean` | false |
| popper-class | 下拉列表的类名 | `string` / `object` | '' |
| popper-style 2.11.4 | autocomplete 下拉列表的类名 | `string` / `object` | — |
| popper-options 2.14.0 | [popper.js](https://popper.js.org/docs/v2/) parameters | `object`refer to [popper.js](https://popper.js.org/docs/v2/) doc | {} |
| show-after 2.14.0 | 下拉菜单的内容是否有箭头 | `boolean` | true |
| teleported | 是否将下拉列表元素插入 append-to 指向的元素下 | `boolean` | true |
| append-to 2.9.9 | 下拉框挂载到哪个 DOM 元素 | `CSSSelector` / `HTMLElement` | — |
| highlight-first-item | 是否默认高亮远程搜索结果的第一项 | `boolean` | false |
| fit-input-width | 下拉框的宽度是否与输入框相同 | `boolean` | false |
| popper-append-to-body deprecated | 是否将下拉列表插入至 body 元素。 在下拉列表的定位出现问题时，可将该属性设置为 false | `boolean` | false |
| loop-navigation 2.11.4 | 键盘导航是否从末尾循环到开头 | `boolean` | true |
| [input props](https://element-plus.org/zh-CN/component/input#attributes) | — | — | — |

### Events [​](#events)

| 事件名 | 详情 | 类型 |
| --- | --- | --- |
| blur | 当选择器的输入框失去焦点时触发 | `Function` |
| focus | 当选择器的输入框获得焦点时触发 | `Function` |
| input | 在 Input 值改变时触发 | `Function` |
| clear | 在点击由 `clearable` 属性生成的清空按钮时触发 | `Function` |
| select | 点击选中建议项时触发 | `Function` |
| change | 在 Input 值改变时触发 | `Function` |

### Slots [​](#slots)

| 插槽名 | 描述说明 | 类型 |
| --- | --- | --- |
| default | 自定义输入建议的内容。 | `object` |
| header 2.10.6 | 下拉列表顶部的内容 | \- |
| footer 2.10.6 | 下拉列表底部的内容 | \- |
| prefix | 输入框头部内容 | \- |
| suffix | 输入框尾部内容 | \- |
| prepend | 输入框前置内容，在 prefix 之前 | \- |
| append | 输入框后置内容，在 suffix 之后 | \- |
| loading 2.5.0 | 修改加载区域内容 | \- |

### Exposes [​](#exposes)

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| activated | 自动补全输入框是否被激活 | `object` |
| blur | 使 input 失去焦点 | `Function` |
| close | 折叠建议列表 | `Function` |
| focus | 使 input 获取焦点 | `Function` |
| handleSelect | 手动触发选中建议事件 | `Function` |
| handleKeyEnter | 手动触发键盘回车事件 | `Function` |
| highlightedIndex | 当前高亮显示选项的索引 | `object` |
| highlight | 在建议中高亮显示一个项目 | `Function` |
| inputRef | el-input 组件实例 | `object` |
| loading | 远程获取提示内容的加载状态指示器 | `object` |
| popperRef | el-tooltip 组件实例 | `object` |
| suggestions | 获取自动补全结果 | `object` |
| getData 2.8.4 | 加载建议列表 | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/autocomplete) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/autocomplete.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/autocomplete.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)[![](https://avatars.githubusercontent.com/u/24540820?v=4&size=64)](https://github.com/catanswer)[![](https://avatars.githubusercontent.com/u/78132554?v=4&size=64)](https://github.com/momei-LJM)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/32381310?v=4&size=64)](https://github.com/dormadekhin)[![](https://avatars.githubusercontent.com/u/7897937?v=4&size=64)](https://github.com/myronliu347)[![](https://avatars.githubusercontent.com/u/30046649?v=4&size=64)](https://github.com/MrWeilian)[![](https://avatars.githubusercontent.com/u/59350883?v=4&size=64)](https://github.com/init-qy)[![](https://avatars.githubusercontent.com/u/25103518?v=4&size=64)](https://github.com/richex-cn)[![](https://avatars.githubusercontent.com/u/22910740?v=4&size=64)](https://github.com/StephenKe)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/6063358?v=4&size=64)](https://github.com/xxholly32)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/36978416?v=4&size=64)](https://github.com/SimonaliaChen)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/33687038?v=4&size=64)](https://github.com/guozi9999)[![](https://avatars.githubusercontent.com/u/66454152?v=4&size=64)](https://github.com/bryqiu)[![](https://avatars.githubusercontent.com/u/140705167?v=4&size=64)](https://github.com/zhongli-kira)[![](https://avatars.githubusercontent.com/u/65594411?v=4&size=64)](https://github.com/Heising)[![](https://avatars.githubusercontent.com/u/109908413?v=4&size=64)](https://github.com/sleepyShen1989)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/166272183?v=4&size=64)](https://github.com/voyagerFeng)[![](https://avatars.githubusercontent.com/u/40999116?v=4&size=64)](https://github.com/jasonren0403)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)

[Config Provider 全局配置](https://element-plus.org/zh-CN/component/config-provider)

[Cascader 级联选择器](https://element-plus.org/zh-CN/component/cascader)




---
## [form/cascader] Cascader 级联选择器
> 官方文档: https://element-plus.org/zh-CN/component/cascader.html

---

# Cascader 级联选择器 [​](#cascader-级联选择器)

更新日志待解决

33

当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择。

## 基础用法 [​](#基础用法)

有两种触发子菜单的方式

只需为 Cascader 的`options`属性指定选项数组即可渲染出一个级联选择器。 通过 `props.expandTrigger` 属性控制子节点的展开方式

Child options expand when clicked (default)

Child options expand when hovered

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+Q2hpbGQgb3B0aW9ucyBleHBhbmQgd2hlbiBjbGlja2VkIChkZWZhdWx0KTwvcD5cbiAgICA8ZWwtY2FzY2FkZXIgdi1tb2RlbD1cInZhbHVlXCIgOm9wdGlvbnM9XCJvcHRpb25zXCIgQGNoYW5nZT1cImhhbmRsZUNoYW5nZVwiIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+Q2hpbGQgb3B0aW9ucyBleHBhbmQgd2hlbiBob3ZlcmVkPC9wPlxuICAgIDxlbC1jYXNjYWRlclxuICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgICBAY2hhbmdlPVwiaGFuZGxlQ2hhbmdlXCJcbiAgICAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKFtdKVxuXG5jb25zdCBwcm9wcyA9IHtcbiAgZXhwYW5kVHJpZ2dlcjogJ2hvdmVyJyBhcyBjb25zdCxcbn1cblxuY29uc3QgaGFuZGxlQ2hhbmdlID0gKHZhbHVlKSA9PiB7XG4gIGNvbnNvbGUubG9nKHZhbHVlKVxufVxuXG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6ICdndWlkZScsXG4gICAgbGFiZWw6ICdHdWlkZScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkaXNjaXBsaW5lcycsXG4gICAgICAgIGxhYmVsOiAnRGlzY2lwbGluZXMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29uc2lzdGVuY3knLFxuICAgICAgICAgICAgbGFiZWw6ICdDb25zaXN0ZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2ZlZWRiYWNrJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRmVlZGJhY2snLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdlZmZpY2llbmN5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnRWZmaWNpZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgICBsYWJlbDogJ0NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnbmF2aWdhdGlvbicsXG4gICAgICAgIGxhYmVsOiAnTmF2aWdhdGlvbicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzaWRlIG5hdicsXG4gICAgICAgICAgICBsYWJlbDogJ1NpZGUgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RvcCBuYXYnLFxuICAgICAgICAgICAgbGFiZWw6ICdUb3AgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnY29tcG9uZW50JyxcbiAgICBsYWJlbDogJ0NvbXBvbmVudCcsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdiYXNpYycsXG4gICAgICAgIGxhYmVsOiAnQmFzaWMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbGF5b3V0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGF5b3V0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sb3InLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xvcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3R5cG9ncmFwaHknLFxuICAgICAgICAgICAgbGFiZWw6ICdUeXBvZ3JhcGh5JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaWNvbicsXG4gICAgICAgICAgICBsYWJlbDogJ0ljb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdidXR0b24nLFxuICAgICAgICAgICAgbGFiZWw6ICdCdXR0b24nLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICBsYWJlbDogJ0Zvcm0nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncmFkaW8nLFxuICAgICAgICAgICAgbGFiZWw6ICdSYWRpbycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NoZWNrYm94JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ2hlY2tib3gnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdpbnB1dCcsXG4gICAgICAgICAgICBsYWJlbDogJ0lucHV0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaW5wdXQtbnVtYmVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnSW5wdXROdW1iZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzZWxlY3QnLFxuICAgICAgICAgICAgbGFiZWw6ICdTZWxlY3QnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXNjYWRlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhc2NhZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc3dpdGNoJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU3dpdGNoJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2xpZGVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU2xpZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGltZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdUaW1lUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdEYXRlUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZXRpbWUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGF0ZVRpbWVQaWNrZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd1cGxvYWQnLFxuICAgICAgICAgICAgbGFiZWw6ICdVcGxvYWQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdyYXRlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUmF0ZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICAgICAgbGFiZWw6ICdGb3JtJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkYXRhJyxcbiAgICAgICAgbGFiZWw6ICdEYXRhJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RhYmxlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGFibGUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0YWcnLFxuICAgICAgICAgICAgbGFiZWw6ICdUYWcnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwcm9ncmVzcycsXG4gICAgICAgICAgICBsYWJlbDogJ1Byb2dyZXNzJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndHJlZScsXG4gICAgICAgICAgICBsYWJlbDogJ1RyZWUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwYWdpbmF0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUGFnaW5hdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2JhZGdlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQmFkZ2UnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ25vdGljZScsXG4gICAgICAgIGxhYmVsOiAnTm90aWNlJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2FsZXJ0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQWxlcnQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdsb2FkaW5nJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTG9hZGluZycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lc3NhZ2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbWVzc2FnZS1ib3gnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlQm94JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbm90aWZpY2F0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTm90aWZpY2F0aW9uJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICduYXZpZ2F0aW9uJyxcbiAgICAgICAgbGFiZWw6ICdOYXZpZ2F0aW9uJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lbnUnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZW51JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGFicycsXG4gICAgICAgICAgICBsYWJlbDogJ1RhYnMnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdicmVhZGNydW1iJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQnJlYWRjcnVtYicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Ryb3Bkb3duJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRHJvcGRvd24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzdGVwcycsXG4gICAgICAgICAgICBsYWJlbDogJ1N0ZXBzJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdvdGhlcnMnLFxuICAgICAgICBsYWJlbDogJ090aGVycycsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdkaWFsb2cnLFxuICAgICAgICAgICAgbGFiZWw6ICdEaWFsb2cnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0b29sdGlwJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVG9vbHRpcCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3BvcG92ZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdQb3BvdmVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2FyZCcsXG4gICAgICAgICAgICBsYWJlbDogJ0NhcmQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXJvdXNlbCcsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhcm91c2VsJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sbGFwc2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xsYXBzZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAncmVzb3VyY2UnLFxuICAgIGxhYmVsOiAnUmVzb3VyY2UnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnYXh1cmUnLFxuICAgICAgICBsYWJlbDogJ0F4dXJlIENvbXBvbmVudHMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdza2V0Y2gnLFxuICAgICAgICBsYWJlbDogJ1NrZXRjaCBUZW1wbGF0ZXMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkb2NzJyxcbiAgICAgICAgbGFiZWw6ICdEZXNpZ24gRG9jdW1lbnRhdGlvbicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/basic.vue)_

vue

```
<template>
  <div class="m-4">
    <p>Child options expand when clicked (default)</p>
    <el-cascader v-model="value" :options="options" @change="handleChange" />
  </div>
  <div class="m-4">
    <p>Child options expand when hovered</p>
    <el-cascader
      v-model="value"
      :options="options"
      :props="props"
      @change="handleChange"
    />
  </div>
</template>

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

const value = ref([])

const props = {
  expandTrigger: 'hover' as const,
}

const handleChange = (value) => {
  console.log(value)
}

const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
          {
            value: 'feedback',
            label: 'Feedback',
          },
          {
            value: 'efficiency',
            label: 'Efficiency',
          },
          {
            value: 'controllability',
            label: 'Controllability',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
          {
            value: 'top nav',
            label: 'Top Navigation',
          },
        ],
      },
    ],
  },
  {
    value: 'component',
    label: 'Component',
    children: [
      {
        value: 'basic',
        label: 'Basic',
        children: [
          {
            value: 'layout',
            label: 'Layout',
          },
          {
            value: 'color',
            label: 'Color',
          },
          {
            value: 'typography',
            label: 'Typography',
          },
          {
            value: 'icon',
            label: 'Icon',
          },
          {
            value: 'button',
            label: 'Button',
          },
        ],
      },
      {
        value: 'form',
        label: 'Form',
        children: [
          {
            value: 'radio',
            label: 'Radio',
          },
          {
            value: 'checkbox',
            label: 'Checkbox',
          },
          {
            value: 'input',
            label: 'Input',
          },
          {
            value: 'input-number',
            label: 'InputNumber',
          },
          {
            value: 'select',
            label: 'Select',
          },
          {
            value: 'cascader',
            label: 'Cascader',
          },
          {
            value: 'switch',
            label: 'Switch',
          },
          {
            value: 'slider',
            label: 'Slider',
          },
          {
            value: 'time-picker',
            label: 'TimePicker',
          },
          {
            value: 'date-picker',
            label: 'DatePicker',
          },
          {
            value: 'datetime-picker',
            label: 'DateTimePicker',
          },
          {
            value: 'upload',
            label: 'Upload',
          },
          {
            value: 'rate',
            label: 'Rate',
          },
          {
            value: 'form',
            label: 'Form',
          },
        ],
      },
      {
        value: 'data',
        label: 'Data',
        children: [
          {
            value: 'table',
            label: 'Table',
          },
          {
            value: 'tag',
            label: 'Tag',
          },
          {
            value: 'progress',
            label: 'Progress',
          },
          {
            value: 'tree',
            label: 'Tree',
          },
          {
            value: 'pagination',
            label: 'Pagination',
          },
          {
            value: 'badge',
            label: 'Badge',
          },
        ],
      },
      {
        value: 'notice',
        label: 'Notice',
        children: [
          {
            value: 'alert',
            label: 'Alert',
          },
          {
            value: 'loading',
            label: 'Loading',
          },
          {
            value: 'message',
            label: 'Message',
          },
          {
            value: 'message-box',
            label: 'MessageBox',
          },
          {
            value: 'notification',
            label: 'Notification',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'menu',
            label: 'Menu',
          },
          {
            value: 'tabs',
            label: 'Tabs',
          },
          {
            value: 'breadcrumb',
            label: 'Breadcrumb',
          },
          {
            value: 'dropdown',
            label: 'Dropdown',
          },
          {
            value: 'steps',
            label: 'Steps',
          },
        ],
      },
      {
        value: 'others',
        label: 'Others',
        children: [
          {
            value: 'dialog',
            label: 'Dialog',
          },
          {
            value: 'tooltip',
            label: 'Tooltip',
          },
          {
            value: 'popover',
            label: 'Popover',
          },
          {
            value: 'card',
            label: 'Card',
          },
          {
            value: 'carousel',
            label: 'Carousel',
          },
          {
            value: 'collapse',
            label: 'Collapse',
          },
        ],
      },
    ],
  },
  {
    value: 'resource',
    label: 'Resource',
    children: [
      {
        value: 'axure',
        label: 'Axure Components',
      },
      {
        value: 'sketch',
        label: 'Sketch Templates',
      },
      {
        value: 'docs',
        label: 'Design Documentation',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 有禁用选项 [​](#有禁用选项)

通过在数据源中设置 `disabled` 字段来声明该选项是禁用的

本例中，`options`指定的数组中的第一个元素含有`disabled: true`键值对，因此是禁用的。 在默认情况下，Cascader 会检查数据中每一项的`disabled`字段是否为`true`，如果你的数据中表示禁用含义的字段名不为`disabled`，可以通过`props.disabled`属性来指定（详见下方 API 表格）。 当然，`value`、`label`和`children`这三个字段名也可以通过同样的方式指定。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FzY2FkZXIgOm9wdGlvbnM9XCJvcHRpb25zXCIgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6ICdndWlkZScsXG4gICAgbGFiZWw6ICdHdWlkZScsXG4gICAgZGlzYWJsZWQ6IHRydWUsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkaXNjaXBsaW5lcycsXG4gICAgICAgIGxhYmVsOiAnRGlzY2lwbGluZXMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29uc2lzdGVuY3knLFxuICAgICAgICAgICAgbGFiZWw6ICdDb25zaXN0ZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2ZlZWRiYWNrJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRmVlZGJhY2snLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdlZmZpY2llbmN5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnRWZmaWNpZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgICBsYWJlbDogJ0NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnbmF2aWdhdGlvbicsXG4gICAgICAgIGxhYmVsOiAnTmF2aWdhdGlvbicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzaWRlIG5hdicsXG4gICAgICAgICAgICBsYWJlbDogJ1NpZGUgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RvcCBuYXYnLFxuICAgICAgICAgICAgbGFiZWw6ICdUb3AgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnY29tcG9uZW50JyxcbiAgICBsYWJlbDogJ0NvbXBvbmVudCcsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdiYXNpYycsXG4gICAgICAgIGxhYmVsOiAnQmFzaWMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbGF5b3V0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGF5b3V0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sb3InLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xvcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3R5cG9ncmFwaHknLFxuICAgICAgICAgICAgbGFiZWw6ICdUeXBvZ3JhcGh5JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaWNvbicsXG4gICAgICAgICAgICBsYWJlbDogJ0ljb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdidXR0b24nLFxuICAgICAgICAgICAgbGFiZWw6ICdCdXR0b24nLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICBsYWJlbDogJ0Zvcm0nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncmFkaW8nLFxuICAgICAgICAgICAgbGFiZWw6ICdSYWRpbycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NoZWNrYm94JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ2hlY2tib3gnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdpbnB1dCcsXG4gICAgICAgICAgICBsYWJlbDogJ0lucHV0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaW5wdXQtbnVtYmVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnSW5wdXROdW1iZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzZWxlY3QnLFxuICAgICAgICAgICAgbGFiZWw6ICdTZWxlY3QnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXNjYWRlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhc2NhZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc3dpdGNoJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU3dpdGNoJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2xpZGVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU2xpZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGltZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdUaW1lUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdEYXRlUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZXRpbWUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGF0ZVRpbWVQaWNrZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd1cGxvYWQnLFxuICAgICAgICAgICAgbGFiZWw6ICdVcGxvYWQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdyYXRlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUmF0ZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICAgICAgbGFiZWw6ICdGb3JtJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkYXRhJyxcbiAgICAgICAgbGFiZWw6ICdEYXRhJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RhYmxlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGFibGUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0YWcnLFxuICAgICAgICAgICAgbGFiZWw6ICdUYWcnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwcm9ncmVzcycsXG4gICAgICAgICAgICBsYWJlbDogJ1Byb2dyZXNzJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndHJlZScsXG4gICAgICAgICAgICBsYWJlbDogJ1RyZWUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwYWdpbmF0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUGFnaW5hdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2JhZGdlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQmFkZ2UnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ25vdGljZScsXG4gICAgICAgIGxhYmVsOiAnTm90aWNlJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2FsZXJ0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQWxlcnQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdsb2FkaW5nJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTG9hZGluZycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lc3NhZ2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbWVzc2FnZS1ib3gnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlQm94JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbm90aWZpY2F0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTm90aWZpY2F0aW9uJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICduYXZpZ2F0aW9uJyxcbiAgICAgICAgbGFiZWw6ICdOYXZpZ2F0aW9uJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lbnUnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZW51JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGFicycsXG4gICAgICAgICAgICBsYWJlbDogJ1RhYnMnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdicmVhZGNydW1iJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQnJlYWRjcnVtYicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Ryb3Bkb3duJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRHJvcGRvd24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzdGVwcycsXG4gICAgICAgICAgICBsYWJlbDogJ1N0ZXBzJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdvdGhlcnMnLFxuICAgICAgICBsYWJlbDogJ090aGVycycsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdkaWFsb2cnLFxuICAgICAgICAgICAgbGFiZWw6ICdEaWFsb2cnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0b29sdGlwJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVG9vbHRpcCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3BvcG92ZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdQb3BvdmVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2FyZCcsXG4gICAgICAgICAgICBsYWJlbDogJ0NhcmQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXJvdXNlbCcsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhcm91c2VsJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sbGFwc2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xsYXBzZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAncmVzb3VyY2UnLFxuICAgIGxhYmVsOiAnUmVzb3VyY2UnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnYXh1cmUnLFxuICAgICAgICBsYWJlbDogJ0F4dXJlIENvbXBvbmVudHMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdza2V0Y2gnLFxuICAgICAgICBsYWJlbDogJ1NrZXRjaCBUZW1wbGF0ZXMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkb2NzJyxcbiAgICAgICAgbGFiZWw6ICdEZXNpZ24gRG9jdW1lbnRhdGlvbicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/option-disabling.vue)_

vue

```
<template>
  <el-cascader :options="options" />
</template>

<script lang="ts" setup>
const options = [
  {
    value: 'guide',
    label: 'Guide',
    disabled: true,
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
          {
            value: 'feedback',
            label: 'Feedback',
          },
          {
            value: 'efficiency',
            label: 'Efficiency',
          },
          {
            value: 'controllability',
            label: 'Controllability',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
          {
            value: 'top nav',
            label: 'Top Navigation',
          },
        ],
      },
    ],
  },
  {
    value: 'component',
    label: 'Component',
    children: [
      {
        value: 'basic',
        label: 'Basic',
        children: [
          {
            value: 'layout',
            label: 'Layout',
          },
          {
            value: 'color',
            label: 'Color',
          },
          {
            value: 'typography',
            label: 'Typography',
          },
          {
            value: 'icon',
            label: 'Icon',
          },
          {
            value: 'button',
            label: 'Button',
          },
        ],
      },
      {
        value: 'form',
        label: 'Form',
        children: [
          {
            value: 'radio',
            label: 'Radio',
          },
          {
            value: 'checkbox',
            label: 'Checkbox',
          },
          {
            value: 'input',
            label: 'Input',
          },
          {
            value: 'input-number',
            label: 'InputNumber',
          },
          {
            value: 'select',
            label: 'Select',
          },
          {
            value: 'cascader',
            label: 'Cascader',
          },
          {
            value: 'switch',
            label: 'Switch',
          },
          {
            value: 'slider',
            label: 'Slider',
          },
          {
            value: 'time-picker',
            label: 'TimePicker',
          },
          {
            value: 'date-picker',
            label: 'DatePicker',
          },
          {
            value: 'datetime-picker',
            label: 'DateTimePicker',
          },
          {
            value: 'upload',
            label: 'Upload',
          },
          {
            value: 'rate',
            label: 'Rate',
          },
          {
            value: 'form',
            label: 'Form',
          },
        ],
      },
      {
        value: 'data',
        label: 'Data',
        children: [
          {
            value: 'table',
            label: 'Table',
          },
          {
            value: 'tag',
            label: 'Tag',
          },
          {
            value: 'progress',
            label: 'Progress',
          },
          {
            value: 'tree',
            label: 'Tree',
          },
          {
            value: 'pagination',
            label: 'Pagination',
          },
          {
            value: 'badge',
            label: 'Badge',
          },
        ],
      },
      {
        value: 'notice',
        label: 'Notice',
        children: [
          {
            value: 'alert',
            label: 'Alert',
          },
          {
            value: 'loading',
            label: 'Loading',
          },
          {
            value: 'message',
            label: 'Message',
          },
          {
            value: 'message-box',
            label: 'MessageBox',
          },
          {
            value: 'notification',
            label: 'Notification',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'menu',
            label: 'Menu',
          },
          {
            value: 'tabs',
            label: 'Tabs',
          },
          {
            value: 'breadcrumb',
            label: 'Breadcrumb',
          },
          {
            value: 'dropdown',
            label: 'Dropdown',
          },
          {
            value: 'steps',
            label: 'Steps',
          },
        ],
      },
      {
        value: 'others',
        label: 'Others',
        children: [
          {
            value: 'dialog',
            label: 'Dialog',
          },
          {
            value: 'tooltip',
            label: 'Tooltip',
          },
          {
            value: 'popover',
            label: 'Popover',
          },
          {
            value: 'card',
            label: 'Card',
          },
          {
            value: 'carousel',
            label: 'Carousel',
          },
          {
            value: 'collapse',
            label: 'Collapse',
          },
        ],
      },
    ],
  },
  {
    value: 'resource',
    label: 'Resource',
    children: [
      {
        value: 'axure',
        label: 'Axure Components',
      },
      {
        value: 'sketch',
        label: 'Sketch Templates',
      },
      {
        value: 'docs',
        label: 'Design Documentation',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 可清空 [​](#可清空)

通过 `clearable` 设置输入框可清空

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FzY2FkZXIgOm9wdGlvbnM9XCJvcHRpb25zXCIgY2xlYXJhYmxlIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuY29uc3Qgb3B0aW9ucyA9IFtcbiAge1xuICAgIHZhbHVlOiAnZ3VpZGUnLFxuICAgIGxhYmVsOiAnR3VpZGUnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnZGlzY2lwbGluZXMnLFxuICAgICAgICBsYWJlbDogJ0Rpc2NpcGxpbmVzJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbnNpc3RlbmN5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ29uc2lzdGVuY3knLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdmZWVkYmFjaycsXG4gICAgICAgICAgICBsYWJlbDogJ0ZlZWRiYWNrJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZWZmaWNpZW5jeScsXG4gICAgICAgICAgICBsYWJlbDogJ0VmZmljaWVuY3knLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjb250cm9sbGFiaWxpdHknLFxuICAgICAgICAgICAgbGFiZWw6ICdDb250cm9sbGFiaWxpdHknLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ25hdmlnYXRpb24nLFxuICAgICAgICBsYWJlbDogJ05hdmlnYXRpb24nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2lkZSBuYXYnLFxuICAgICAgICAgICAgbGFiZWw6ICdTaWRlIE5hdmlnYXRpb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0b3AgbmF2JyxcbiAgICAgICAgICAgIGxhYmVsOiAnVG9wIE5hdmlnYXRpb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ2NvbXBvbmVudCcsXG4gICAgbGFiZWw6ICdDb21wb25lbnQnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnYmFzaWMnLFxuICAgICAgICBsYWJlbDogJ0Jhc2ljJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2xheW91dCcsXG4gICAgICAgICAgICBsYWJlbDogJ0xheW91dCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbG9yJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ29sb3InLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0eXBvZ3JhcGh5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnVHlwb2dyYXBoeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2ljb24nLFxuICAgICAgICAgICAgbGFiZWw6ICdJY29uJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnYnV0dG9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQnV0dG9uJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdmb3JtJyxcbiAgICAgICAgbGFiZWw6ICdGb3JtJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3JhZGlvJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUmFkaW8nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjaGVja2JveCcsXG4gICAgICAgICAgICBsYWJlbDogJ0NoZWNrYm94JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaW5wdXQnLFxuICAgICAgICAgICAgbGFiZWw6ICdJbnB1dCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2lucHV0LW51bWJlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0lucHV0TnVtYmVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2VsZWN0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnU2VsZWN0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2FzY2FkZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdDYXNjYWRlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3N3aXRjaCcsXG4gICAgICAgICAgICBsYWJlbDogJ1N3aXRjaCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3NsaWRlcicsXG4gICAgICAgICAgICBsYWJlbDogJ1NsaWRlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RpbWUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGltZVBpY2tlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2RhdGUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGF0ZVBpY2tlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2RhdGV0aW1lLXBpY2tlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0RhdGVUaW1lUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndXBsb2FkJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVXBsb2FkJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncmF0ZScsXG4gICAgICAgICAgICBsYWJlbDogJ1JhdGUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdmb3JtJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRm9ybScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnZGF0YScsXG4gICAgICAgIGxhYmVsOiAnRGF0YScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0YWJsZScsXG4gICAgICAgICAgICBsYWJlbDogJ1RhYmxlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGFnJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGFnJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncHJvZ3Jlc3MnLFxuICAgICAgICAgICAgbGFiZWw6ICdQcm9ncmVzcycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RyZWUnLFxuICAgICAgICAgICAgbGFiZWw6ICdUcmVlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncGFnaW5hdGlvbicsXG4gICAgICAgICAgICBsYWJlbDogJ1BhZ2luYXRpb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdiYWRnZScsXG4gICAgICAgICAgICBsYWJlbDogJ0JhZGdlJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdub3RpY2UnLFxuICAgICAgICBsYWJlbDogJ05vdGljZScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdhbGVydCcsXG4gICAgICAgICAgICBsYWJlbDogJ0FsZXJ0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbG9hZGluZycsXG4gICAgICAgICAgICBsYWJlbDogJ0xvYWRpbmcnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdtZXNzYWdlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTWVzc2FnZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lc3NhZ2UtYm94JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTWVzc2FnZUJveCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ25vdGlmaWNhdGlvbicsXG4gICAgICAgICAgICBsYWJlbDogJ05vdGlmaWNhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnbmF2aWdhdGlvbicsXG4gICAgICAgIGxhYmVsOiAnTmF2aWdhdGlvbicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdtZW51JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTWVudScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RhYnMnLFxuICAgICAgICAgICAgbGFiZWw6ICdUYWJzJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnYnJlYWRjcnVtYicsXG4gICAgICAgICAgICBsYWJlbDogJ0JyZWFkY3J1bWInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdkcm9wZG93bicsXG4gICAgICAgICAgICBsYWJlbDogJ0Ryb3Bkb3duJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc3RlcHMnLFxuICAgICAgICAgICAgbGFiZWw6ICdTdGVwcycsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnb3RoZXJzJyxcbiAgICAgICAgbGFiZWw6ICdPdGhlcnMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGlhbG9nJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGlhbG9nJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndG9vbHRpcCcsXG4gICAgICAgICAgICBsYWJlbDogJ1Rvb2x0aXAnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwb3BvdmVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUG9wb3ZlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NhcmQnLFxuICAgICAgICAgICAgbGFiZWw6ICdDYXJkJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2Fyb3VzZWwnLFxuICAgICAgICAgICAgbGFiZWw6ICdDYXJvdXNlbCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbGxhcHNlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ29sbGFwc2UnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ3Jlc291cmNlJyxcbiAgICBsYWJlbDogJ1Jlc291cmNlJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2F4dXJlJyxcbiAgICAgICAgbGFiZWw6ICdBeHVyZSBDb21wb25lbnRzJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnc2tldGNoJyxcbiAgICAgICAgbGFiZWw6ICdTa2V0Y2ggVGVtcGxhdGVzJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnZG9jcycsXG4gICAgICAgIGxhYmVsOiAnRGVzaWduIERvY3VtZW50YXRpb24nLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/clearable.vue)_

vue

```
<template>
  <el-cascader :options="options" clearable />
</template>

<script lang="ts" setup>
const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
          {
            value: 'feedback',
            label: 'Feedback',
          },
          {
            value: 'efficiency',
            label: 'Efficiency',
          },
          {
            value: 'controllability',
            label: 'Controllability',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
          {
            value: 'top nav',
            label: 'Top Navigation',
          },
        ],
      },
    ],
  },
  {
    value: 'component',
    label: 'Component',
    children: [
      {
        value: 'basic',
        label: 'Basic',
        children: [
          {
            value: 'layout',
            label: 'Layout',
          },
          {
            value: 'color',
            label: 'Color',
          },
          {
            value: 'typography',
            label: 'Typography',
          },
          {
            value: 'icon',
            label: 'Icon',
          },
          {
            value: 'button',
            label: 'Button',
          },
        ],
      },
      {
        value: 'form',
        label: 'Form',
        children: [
          {
            value: 'radio',
            label: 'Radio',
          },
          {
            value: 'checkbox',
            label: 'Checkbox',
          },
          {
            value: 'input',
            label: 'Input',
          },
          {
            value: 'input-number',
            label: 'InputNumber',
          },
          {
            value: 'select',
            label: 'Select',
          },
          {
            value: 'cascader',
            label: 'Cascader',
          },
          {
            value: 'switch',
            label: 'Switch',
          },
          {
            value: 'slider',
            label: 'Slider',
          },
          {
            value: 'time-picker',
            label: 'TimePicker',
          },
          {
            value: 'date-picker',
            label: 'DatePicker',
          },
          {
            value: 'datetime-picker',
            label: 'DateTimePicker',
          },
          {
            value: 'upload',
            label: 'Upload',
          },
          {
            value: 'rate',
            label: 'Rate',
          },
          {
            value: 'form',
            label: 'Form',
          },
        ],
      },
      {
        value: 'data',
        label: 'Data',
        children: [
          {
            value: 'table',
            label: 'Table',
          },
          {
            value: 'tag',
            label: 'Tag',
          },
          {
            value: 'progress',
            label: 'Progress',
          },
          {
            value: 'tree',
            label: 'Tree',
          },
          {
            value: 'pagination',
            label: 'Pagination',
          },
          {
            value: 'badge',
            label: 'Badge',
          },
        ],
      },
      {
        value: 'notice',
        label: 'Notice',
        children: [
          {
            value: 'alert',
            label: 'Alert',
          },
          {
            value: 'loading',
            label: 'Loading',
          },
          {
            value: 'message',
            label: 'Message',
          },
          {
            value: 'message-box',
            label: 'MessageBox',
          },
          {
            value: 'notification',
            label: 'Notification',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'menu',
            label: 'Menu',
          },
          {
            value: 'tabs',
            label: 'Tabs',
          },
          {
            value: 'breadcrumb',
            label: 'Breadcrumb',
          },
          {
            value: 'dropdown',
            label: 'Dropdown',
          },
          {
            value: 'steps',
            label: 'Steps',
          },
        ],
      },
      {
        value: 'others',
        label: 'Others',
        children: [
          {
            value: 'dialog',
            label: 'Dialog',
          },
          {
            value: 'tooltip',
            label: 'Tooltip',
          },
          {
            value: 'popover',
            label: 'Popover',
          },
          {
            value: 'card',
            label: 'Card',
          },
          {
            value: 'carousel',
            label: 'Carousel',
          },
          {
            value: 'collapse',
            label: 'Collapse',
          },
        ],
      },
    ],
  },
  {
    value: 'resource',
    label: 'Resource',
    children: [
      {
        value: 'axure',
        label: 'Axure Components',
      },
      {
        value: 'sketch',
        label: 'Sketch Templates',
      },
      {
        value: 'docs',
        label: 'Design Documentation',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 自定义清除图标2.11.0 [​](#自定义清除图标)

你可以通过`clear-icon`属性自定义清除图标

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FzY2FkZXJcbiAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgIGNsZWFyYWJsZVxuICAgIDpjbGVhci1pY29uPVwiQ2xvc2VCb2xkXCJcbiAgICBwbGFjZWhvbGRlcj1cIkN1c3RvbSBjbGVhciBpY29uXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBDbG9zZUJvbGQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3Qgb3B0aW9ucyA9IFtcbiAge1xuICAgIHZhbHVlOiAnZ3VpZGUnLFxuICAgIGxhYmVsOiAnR3VpZGUnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnZGlzY2lwbGluZXMnLFxuICAgICAgICBsYWJlbDogJ0Rpc2NpcGxpbmVzJyxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/clear-icon.vue)_

vue

```
<template>
  <el-cascader
    :options="options"
    clearable
    :clear-icon="CloseBold"
    placeholder="Custom clear icon"
  />
</template>

<script lang="ts" setup>
import { CloseBold } from '@element-plus/icons-vue'

const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 仅显示最后一级 [​](#仅显示最后一级)

可以仅在输入框中显示选中项最后一级的标签，而不是选中项所在的完整路径。

属性`show-all-levels`定义了是否显示完整的路径， 将其赋值为 `false` 则仅显示最后一级。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FzY2FkZXIgOm9wdGlvbnM9XCJvcHRpb25zXCIgOnNob3ctYWxsLWxldmVscz1cImZhbHNlXCIgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6ICdndWlkZScsXG4gICAgbGFiZWw6ICdHdWlkZScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkaXNjaXBsaW5lcycsXG4gICAgICAgIGxhYmVsOiAnRGlzY2lwbGluZXMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29uc2lzdGVuY3knLFxuICAgICAgICAgICAgbGFiZWw6ICdDb25zaXN0ZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2ZlZWRiYWNrJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRmVlZGJhY2snLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdlZmZpY2llbmN5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnRWZmaWNpZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgICBsYWJlbDogJ0NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnbmF2aWdhdGlvbicsXG4gICAgICAgIGxhYmVsOiAnTmF2aWdhdGlvbicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzaWRlIG5hdicsXG4gICAgICAgICAgICBsYWJlbDogJ1NpZGUgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RvcCBuYXYnLFxuICAgICAgICAgICAgbGFiZWw6ICdUb3AgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnY29tcG9uZW50JyxcbiAgICBsYWJlbDogJ0NvbXBvbmVudCcsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdiYXNpYycsXG4gICAgICAgIGxhYmVsOiAnQmFzaWMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbGF5b3V0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGF5b3V0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sb3InLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xvcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3R5cG9ncmFwaHknLFxuICAgICAgICAgICAgbGFiZWw6ICdUeXBvZ3JhcGh5JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaWNvbicsXG4gICAgICAgICAgICBsYWJlbDogJ0ljb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdidXR0b24nLFxuICAgICAgICAgICAgbGFiZWw6ICdCdXR0b24nLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICBsYWJlbDogJ0Zvcm0nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncmFkaW8nLFxuICAgICAgICAgICAgbGFiZWw6ICdSYWRpbycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NoZWNrYm94JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ2hlY2tib3gnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdpbnB1dCcsXG4gICAgICAgICAgICBsYWJlbDogJ0lucHV0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaW5wdXQtbnVtYmVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnSW5wdXROdW1iZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzZWxlY3QnLFxuICAgICAgICAgICAgbGFiZWw6ICdTZWxlY3QnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXNjYWRlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhc2NhZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc3dpdGNoJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU3dpdGNoJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2xpZGVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU2xpZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGltZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdUaW1lUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdEYXRlUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZXRpbWUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGF0ZVRpbWVQaWNrZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd1cGxvYWQnLFxuICAgICAgICAgICAgbGFiZWw6ICdVcGxvYWQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdyYXRlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUmF0ZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICAgICAgbGFiZWw6ICdGb3JtJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkYXRhJyxcbiAgICAgICAgbGFiZWw6ICdEYXRhJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RhYmxlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGFibGUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0YWcnLFxuICAgICAgICAgICAgbGFiZWw6ICdUYWcnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwcm9ncmVzcycsXG4gICAgICAgICAgICBsYWJlbDogJ1Byb2dyZXNzJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndHJlZScsXG4gICAgICAgICAgICBsYWJlbDogJ1RyZWUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwYWdpbmF0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUGFnaW5hdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2JhZGdlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQmFkZ2UnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ25vdGljZScsXG4gICAgICAgIGxhYmVsOiAnTm90aWNlJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2FsZXJ0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQWxlcnQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdsb2FkaW5nJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTG9hZGluZycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lc3NhZ2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbWVzc2FnZS1ib3gnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlQm94JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbm90aWZpY2F0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTm90aWZpY2F0aW9uJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICduYXZpZ2F0aW9uJyxcbiAgICAgICAgbGFiZWw6ICdOYXZpZ2F0aW9uJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lbnUnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZW51JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGFicycsXG4gICAgICAgICAgICBsYWJlbDogJ1RhYnMnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdicmVhZGNydW1iJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQnJlYWRjcnVtYicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Ryb3Bkb3duJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRHJvcGRvd24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzdGVwcycsXG4gICAgICAgICAgICBsYWJlbDogJ1N0ZXBzJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdvdGhlcnMnLFxuICAgICAgICBsYWJlbDogJ090aGVycycsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdkaWFsb2cnLFxuICAgICAgICAgICAgbGFiZWw6ICdEaWFsb2cnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0b29sdGlwJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVG9vbHRpcCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3BvcG92ZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdQb3BvdmVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2FyZCcsXG4gICAgICAgICAgICBsYWJlbDogJ0NhcmQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXJvdXNlbCcsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhcm91c2VsJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sbGFwc2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xsYXBzZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAncmVzb3VyY2UnLFxuICAgIGxhYmVsOiAnUmVzb3VyY2UnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnYXh1cmUnLFxuICAgICAgICBsYWJlbDogJ0F4dXJlIENvbXBvbmVudHMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdza2V0Y2gnLFxuICAgICAgICBsYWJlbDogJ1NrZXRjaCBUZW1wbGF0ZXMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkb2NzJyxcbiAgICAgICAgbGFiZWw6ICdEZXNpZ24gRG9jdW1lbnRhdGlvbicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/last-level.vue)_

vue

```
<template>
  <el-cascader :options="options" :show-all-levels="false" />
</template>

<script lang="ts" setup>
const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
          {
            value: 'feedback',
            label: 'Feedback',
          },
          {
            value: 'efficiency',
            label: 'Efficiency',
          },
          {
            value: 'controllability',
            label: 'Controllability',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
          {
            value: 'top nav',
            label: 'Top Navigation',
          },
        ],
      },
    ],
  },
  {
    value: 'component',
    label: 'Component',
    children: [
      {
        value: 'basic',
        label: 'Basic',
        children: [
          {
            value: 'layout',
            label: 'Layout',
          },
          {
            value: 'color',
            label: 'Color',
          },
          {
            value: 'typography',
            label: 'Typography',
          },
          {
            value: 'icon',
            label: 'Icon',
          },
          {
            value: 'button',
            label: 'Button',
          },
        ],
      },
      {
        value: 'form',
        label: 'Form',
        children: [
          {
            value: 'radio',
            label: 'Radio',
          },
          {
            value: 'checkbox',
            label: 'Checkbox',
          },
          {
            value: 'input',
            label: 'Input',
          },
          {
            value: 'input-number',
            label: 'InputNumber',
          },
          {
            value: 'select',
            label: 'Select',
          },
          {
            value: 'cascader',
            label: 'Cascader',
          },
          {
            value: 'switch',
            label: 'Switch',
          },
          {
            value: 'slider',
            label: 'Slider',
          },
          {
            value: 'time-picker',
            label: 'TimePicker',
          },
          {
            value: 'date-picker',
            label: 'DatePicker',
          },
          {
            value: 'datetime-picker',
            label: 'DateTimePicker',
          },
          {
            value: 'upload',
            label: 'Upload',
          },
          {
            value: 'rate',
            label: 'Rate',
          },
          {
            value: 'form',
            label: 'Form',
          },
        ],
      },
      {
        value: 'data',
        label: 'Data',
        children: [
          {
            value: 'table',
            label: 'Table',
          },
          {
            value: 'tag',
            label: 'Tag',
          },
          {
            value: 'progress',
            label: 'Progress',
          },
          {
            value: 'tree',
            label: 'Tree',
          },
          {
            value: 'pagination',
            label: 'Pagination',
          },
          {
            value: 'badge',
            label: 'Badge',
          },
        ],
      },
      {
        value: 'notice',
        label: 'Notice',
        children: [
          {
            value: 'alert',
            label: 'Alert',
          },
          {
            value: 'loading',
            label: 'Loading',
          },
          {
            value: 'message',
            label: 'Message',
          },
          {
            value: 'message-box',
            label: 'MessageBox',
          },
          {
            value: 'notification',
            label: 'Notification',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'menu',
            label: 'Menu',
          },
          {
            value: 'tabs',
            label: 'Tabs',
          },
          {
            value: 'breadcrumb',
            label: 'Breadcrumb',
          },
          {
            value: 'dropdown',
            label: 'Dropdown',
          },
          {
            value: 'steps',
            label: 'Steps',
          },
        ],
      },
      {
        value: 'others',
        label: 'Others',
        children: [
          {
            value: 'dialog',
            label: 'Dialog',
          },
          {
            value: 'tooltip',
            label: 'Tooltip',
          },
          {
            value: 'popover',
            label: 'Popover',
          },
          {
            value: 'card',
            label: 'Card',
          },
          {
            value: 'carousel',
            label: 'Carousel',
          },
          {
            value: 'collapse',
            label: 'Collapse',
          },
        ],
      },
    ],
  },
  {
    value: 'resource',
    label: 'Resource',
    children: [
      {
        value: 'axure',
        label: 'Axure Components',
      },
      {
        value: 'sketch',
        label: 'Sketch Templates',
      },
      {
        value: 'docs',
        label: 'Design Documentation',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 多选 [​](#多选)

在标签中添加 `:props="props"` 并设置 `props = { multiple: true }` 来开启多选模式。

正确用法：

vue

```
<template>
  <el-cascader :props="props" />
</template>

<script lang="ts" setup>
const props = { multiple: true }
</script>
```

错误用法：

vue

```
<template>
  <!--  Object literal binging here is invalid syntax for cascader  -->
  <el-cascader :props="{ multiple: true }" />
</template>
```

使用多选时，所有选中的标签将默认显示。 您可以设置 `collapse = true` 将选中的标签折叠。 您可以设置 `max-collapse-tags` 来显示最大tag数量，默认1。 您可以使用 `collapse-tags-tooltip` 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。

Display all tags (default)

Collapse tags

Collapse tags tooltip

Max Collapse Tags

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+RGlzcGxheSBhbGwgdGFncyAoZGVmYXVsdCk8L3A+XG4gICAgPGVsLWNhc2NhZGVyIDpvcHRpb25zPVwib3B0aW9uc1wiIDpwcm9wcz1cInByb3BzXCIgY2xlYXJhYmxlIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+Q29sbGFwc2UgdGFnczwvcD5cbiAgICA8ZWwtY2FzY2FkZXIgOm9wdGlvbnM9XCJvcHRpb25zXCIgOnByb3BzPVwicHJvcHNcIiBjb2xsYXBzZS10YWdzIGNsZWFyYWJsZSAvPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cIm0tNFwiPlxuICAgIDxwPkNvbGxhcHNlIHRhZ3MgdG9vbHRpcDwvcD5cbiAgICA8ZWwtY2FzY2FkZXJcbiAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgICBjb2xsYXBzZS10YWdzXG4gICAgICBjb2xsYXBzZS10YWdzLXRvb2x0aXBcbiAgICAgIGNsZWFyYWJsZVxuICAgIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+TWF4IENvbGxhcHNlIFRhZ3M8L3A+XG4gICAgPGVsLWNhc2NhZGVyXG4gICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgOnByb3BzPVwicHJvcHNcIlxuICAgICAgY29sbGFwc2UtdGFnc1xuICAgICAgY29sbGFwc2UtdGFncy10b29sdGlwXG4gICAgICA6bWF4LWNvbGxhcHNlLXRhZ3M9XCIzXCJcbiAgICAgIGNsZWFyYWJsZVxuICAgIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IHByb3BzID0geyBtdWx0aXBsZTogdHJ1ZSB9XG5cbmNvbnN0IG9wdGlvbnMgPSBbXG4gIHtcbiAgICB2YWx1ZTogMSxcbiAgICBsYWJlbDogJ0FzaWEnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAyLFxuICAgICAgICBsYWJlbDogJ0NoaW5hJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7IHZhbHVlOiAzLCBsYWJlbDogJ0JlaWppbmcnIH0sXG4gICAgICAgICAgeyB2YWx1ZTogNCwgbGFiZWw6ICdTaGFuZ2hhaScgfSxcbiAgICAgICAgICB7IHZhbHVlOiA1LCBsYWJlbDogJ0hhbmd6aG91JyB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6IDYsXG4gICAgICAgIGxhYmVsOiAnSmFwYW4nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHsgdmFsdWU6IDcsIGxhYmVsOiAnVG9reW8nIH0sXG4gICAgICAgICAgeyB2YWx1ZTogOCwgbGFiZWw6ICdPc2FrYScgfSxcbiAgICAgICAgICB7IHZhbHVlOiA5LCBsYWJlbDogJ0t5b3RvJyB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6IDEwLFxuICAgICAgICBsYWJlbDogJ0tvcmVhJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7IHZhbHVlOiAxMSwgbGFiZWw6ICdTZW91bCcgfSxcbiAgICAgICAgICB7IHZhbHVlOiAxMiwgbGFiZWw6ICdCdXNhbicgfSxcbiAgICAgICAgICB7IHZhbHVlOiAxMywgbGFiZWw6ICdUYWVndScgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAxNCxcbiAgICBsYWJlbDogJ0V1cm9wZScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6IDE1LFxuICAgICAgICBsYWJlbDogJ0ZyYW5jZScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAgeyB2YWx1ZTogMTYsIGxhYmVsOiAnUGFyaXMnIH0sXG4gICAgICAgICAgeyB2YWx1ZTogMTcsIGxhYmVsOiAnTWFyc2VpbGxlJyB9LFxuICAgICAgICAgIHsgdmFsdWU6IDE4LCBsYWJlbDogJ0x5b24nIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogMTksXG4gICAgICAgIGxhYmVsOiAnVUsnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHsgdmFsdWU6IDIwLCBsYWJlbDogJ0xvbmRvbicgfSxcbiAgICAgICAgICB7IHZhbHVlOiAyMSwgbGFiZWw6ICdCaXJtaW5naGFtJyB9LFxuICAgICAgICAgIHsgdmFsdWU6IDIyLCBsYWJlbDogJ01hbmNoZXN0ZXInIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogMjMsXG4gICAgbGFiZWw6ICdOb3J0aCBBbWVyaWNhJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogMjQsXG4gICAgICAgIGxhYmVsOiAnVVMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHsgdmFsdWU6IDI1LCBsYWJlbDogJ05ldyBZb3JrJyB9LFxuICAgICAgICAgIHsgdmFsdWU6IDI2LCBsYWJlbDogJ0xvcyBBbmdlbGVzJyB9LFxuICAgICAgICAgIHsgdmFsdWU6IDI3LCBsYWJlbDogJ1dhc2hpbmd0b24nIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogMjgsXG4gICAgICAgIGxhYmVsOiAnQ2FuYWRhJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7IHZhbHVlOiAyOSwgbGFiZWw6ICdUb3JvbnRvJyB9LFxuICAgICAgICAgIHsgdmFsdWU6IDMwLCBsYWJlbDogJ01vbnRyZWFsJyB9LFxuICAgICAgICAgIHsgdmFsdWU6IDMxLCBsYWJlbDogJ090dGF3YScgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/multiple-selection.vue)_

vue

```
<template>
  <div class="m-4">
    <p>Display all tags (default)</p>
    <el-cascader :options="options" :props="props" clearable />
  </div>
  <div class="m-4">
    <p>Collapse tags</p>
    <el-cascader :options="options" :props="props" collapse-tags clearable />
  </div>
  <div class="m-4">
    <p>Collapse tags tooltip</p>
    <el-cascader
      :options="options"
      :props="props"
      collapse-tags
      collapse-tags-tooltip
      clearable
    />
  </div>
  <div class="m-4">
    <p>Max Collapse Tags</p>
    <el-cascader
      :options="options"
      :props="props"
      collapse-tags
      collapse-tags-tooltip
      :max-collapse-tags="3"
      clearable
    />
  </div>
</template>

<script lang="ts" setup>
const props = { multiple: true }

const options = [
  {
    value: 1,
    label: 'Asia',
    children: [
      {
        value: 2,
        label: 'China',
        children: [
          { value: 3, label: 'Beijing' },
          { value: 4, label: 'Shanghai' },
          { value: 5, label: 'Hangzhou' },
        ],
      },
      {
        value: 6,
        label: 'Japan',
        children: [
          { value: 7, label: 'Tokyo' },
          { value: 8, label: 'Osaka' },
          { value: 9, label: 'Kyoto' },
        ],
      },
      {
        value: 10,
        label: 'Korea',
        children: [
          { value: 11, label: 'Seoul' },
          { value: 12, label: 'Busan' },
          { value: 13, label: 'Taegu' },
        ],
      },
    ],
  },
  {
    value: 14,
    label: 'Europe',
    children: [
      {
        value: 15,
        label: 'France',
        children: [
          { value: 16, label: 'Paris' },
          { value: 17, label: 'Marseille' },
          { value: 18, label: 'Lyon' },
        ],
      },
      {
        value: 19,
        label: 'UK',
        children: [
          { value: 20, label: 'London' },
          { value: 21, label: 'Birmingham' },
          { value: 22, label: 'Manchester' },
        ],
      },
    ],
  },
  {
    value: 23,
    label: 'North America',
    children: [
      {
        value: 24,
        label: 'US',
        children: [
          { value: 25, label: 'New York' },
          { value: 26, label: 'Los Angeles' },
          { value: 27, label: 'Washington' },
        ],
      },
      {
        value: 28,
        label: 'Canada',
        children: [
          { value: 29, label: 'Toronto' },
          { value: 30, label: 'Montreal' },
          { value: 31, label: 'Ottawa' },
        ],
      },
    ],
  },
]
</script>
```

隐藏源代码

## 选择任意一级选项 [​](#选择任意一级选项)

在单选模式下，你只能选择叶子节点；而在多选模式下，勾选父节点真正选中的都是叶子节点。 启用该功能后，可让父子节点取消关联，选择任意一级选项。

可通过 `props.checkStrictly = true` 来设置父子节点取消选中关联，从而达到选择任意一级选项的目的。

Select any level of options (Single selection)

Select any level of options (Multiple selection)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+U2VsZWN0IGFueSBsZXZlbCBvZiBvcHRpb25zIChTaW5nbGUgc2VsZWN0aW9uKTwvcD5cbiAgICA8ZWwtY2FzY2FkZXIgOm9wdGlvbnM9XCJvcHRpb25zXCIgOnByb3BzPVwicHJvcHMxXCIgY2xlYXJhYmxlIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+U2VsZWN0IGFueSBsZXZlbCBvZiBvcHRpb25zIChNdWx0aXBsZSBzZWxlY3Rpb24pPC9wPlxuICAgIDxlbC1jYXNjYWRlciA6b3B0aW9ucz1cIm9wdGlvbnNcIiA6cHJvcHM9XCJwcm9wczJcIiBjbGVhcmFibGUgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuY29uc3QgcHJvcHMxID0ge1xuICBjaGVja1N0cmljdGx5OiB0cnVlLFxufVxuXG5jb25zdCBwcm9wczIgPSB7XG4gIG11bHRpcGxlOiB0cnVlLFxuICBjaGVja1N0cmljdGx5OiB0cnVlLFxufVxuXG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6ICdndWlkZScsXG4gICAgbGFiZWw6ICdHdWlkZScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkaXNjaXBsaW5lcycsXG4gICAgICAgIGxhYmVsOiAnRGlzY2lwbGluZXMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29uc2lzdGVuY3knLFxuICAgICAgICAgICAgbGFiZWw6ICdDb25zaXN0ZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2ZlZWRiYWNrJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRmVlZGJhY2snLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdlZmZpY2llbmN5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnRWZmaWNpZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgICBsYWJlbDogJ0NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnbmF2aWdhdGlvbicsXG4gICAgICAgIGxhYmVsOiAnTmF2aWdhdGlvbicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzaWRlIG5hdicsXG4gICAgICAgICAgICBsYWJlbDogJ1NpZGUgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RvcCBuYXYnLFxuICAgICAgICAgICAgbGFiZWw6ICdUb3AgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnY29tcG9uZW50JyxcbiAgICBsYWJlbDogJ0NvbXBvbmVudCcsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdiYXNpYycsXG4gICAgICAgIGxhYmVsOiAnQmFzaWMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbGF5b3V0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGF5b3V0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sb3InLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xvcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3R5cG9ncmFwaHknLFxuICAgICAgICAgICAgbGFiZWw6ICdUeXBvZ3JhcGh5JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaWNvbicsXG4gICAgICAgICAgICBsYWJlbDogJ0ljb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdidXR0b24nLFxuICAgICAgICAgICAgbGFiZWw6ICdCdXR0b24nLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICBsYWJlbDogJ0Zvcm0nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncmFkaW8nLFxuICAgICAgICAgICAgbGFiZWw6ICdSYWRpbycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NoZWNrYm94JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ2hlY2tib3gnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdpbnB1dCcsXG4gICAgICAgICAgICBsYWJlbDogJ0lucHV0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaW5wdXQtbnVtYmVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnSW5wdXROdW1iZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzZWxlY3QnLFxuICAgICAgICAgICAgbGFiZWw6ICdTZWxlY3QnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXNjYWRlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhc2NhZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc3dpdGNoJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU3dpdGNoJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2xpZGVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU2xpZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGltZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdUaW1lUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdEYXRlUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZXRpbWUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGF0ZVRpbWVQaWNrZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd1cGxvYWQnLFxuICAgICAgICAgICAgbGFiZWw6ICdVcGxvYWQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdyYXRlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUmF0ZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICAgICAgbGFiZWw6ICdGb3JtJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkYXRhJyxcbiAgICAgICAgbGFiZWw6ICdEYXRhJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RhYmxlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGFibGUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0YWcnLFxuICAgICAgICAgICAgbGFiZWw6ICdUYWcnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwcm9ncmVzcycsXG4gICAgICAgICAgICBsYWJlbDogJ1Byb2dyZXNzJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndHJlZScsXG4gICAgICAgICAgICBsYWJlbDogJ1RyZWUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwYWdpbmF0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUGFnaW5hdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2JhZGdlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQmFkZ2UnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ25vdGljZScsXG4gICAgICAgIGxhYmVsOiAnTm90aWNlJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2FsZXJ0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQWxlcnQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdsb2FkaW5nJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTG9hZGluZycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lc3NhZ2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbWVzc2FnZS1ib3gnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlQm94JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbm90aWZpY2F0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTm90aWZpY2F0aW9uJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICduYXZpZ2F0aW9uJyxcbiAgICAgICAgbGFiZWw6ICdOYXZpZ2F0aW9uJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lbnUnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZW51JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGFicycsXG4gICAgICAgICAgICBsYWJlbDogJ1RhYnMnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdicmVhZGNydW1iJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQnJlYWRjcnVtYicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Ryb3Bkb3duJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRHJvcGRvd24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzdGVwcycsXG4gICAgICAgICAgICBsYWJlbDogJ1N0ZXBzJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdvdGhlcnMnLFxuICAgICAgICBsYWJlbDogJ090aGVycycsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdkaWFsb2cnLFxuICAgICAgICAgICAgbGFiZWw6ICdEaWFsb2cnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0b29sdGlwJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVG9vbHRpcCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3BvcG92ZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdQb3BvdmVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2FyZCcsXG4gICAgICAgICAgICBsYWJlbDogJ0NhcmQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXJvdXNlbCcsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhcm91c2VsJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sbGFwc2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xsYXBzZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAncmVzb3VyY2UnLFxuICAgIGxhYmVsOiAnUmVzb3VyY2UnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnYXh1cmUnLFxuICAgICAgICBsYWJlbDogJ0F4dXJlIENvbXBvbmVudHMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdza2V0Y2gnLFxuICAgICAgICBsYWJlbDogJ1NrZXRjaCBUZW1wbGF0ZXMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkb2NzJyxcbiAgICAgICAgbGFiZWw6ICdEZXNpZ24gRG9jdW1lbnRhdGlvbicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/any-level.vue)_

vue

```
<template>
  <div class="m-4">
    <p>Select any level of options (Single selection)</p>
    <el-cascader :options="options" :props="props1" clearable />
  </div>
  <div class="m-4">
    <p>Select any level of options (Multiple selection)</p>
    <el-cascader :options="options" :props="props2" clearable />
  </div>
</template>

<script lang="ts" setup>
const props1 = {
  checkStrictly: true,
}

const props2 = {
  multiple: true,
  checkStrictly: true,
}

const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
          {
            value: 'feedback',
            label: 'Feedback',
          },
          {
            value: 'efficiency',
            label: 'Efficiency',
          },
          {
            value: 'controllability',
            label: 'Controllability',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
          {
            value: 'top nav',
            label: 'Top Navigation',
          },
        ],
      },
    ],
  },
  {
    value: 'component',
    label: 'Component',
    children: [
      {
        value: 'basic',
        label: 'Basic',
        children: [
          {
            value: 'layout',
            label: 'Layout',
          },
          {
            value: 'color',
            label: 'Color',
          },
          {
            value: 'typography',
            label: 'Typography',
          },
          {
            value: 'icon',
            label: 'Icon',
          },
          {
            value: 'button',
            label: 'Button',
          },
        ],
      },
      {
        value: 'form',
        label: 'Form',
        children: [
          {
            value: 'radio',
            label: 'Radio',
          },
          {
            value: 'checkbox',
            label: 'Checkbox',
          },
          {
            value: 'input',
            label: 'Input',
          },
          {
            value: 'input-number',
            label: 'InputNumber',
          },
          {
            value: 'select',
            label: 'Select',
          },
          {
            value: 'cascader',
            label: 'Cascader',
          },
          {
            value: 'switch',
            label: 'Switch',
          },
          {
            value: 'slider',
            label: 'Slider',
          },
          {
            value: 'time-picker',
            label: 'TimePicker',
          },
          {
            value: 'date-picker',
            label: 'DatePicker',
          },
          {
            value: 'datetime-picker',
            label: 'DateTimePicker',
          },
          {
            value: 'upload',
            label: 'Upload',
          },
          {
            value: 'rate',
            label: 'Rate',
          },
          {
            value: 'form',
            label: 'Form',
          },
        ],
      },
      {
        value: 'data',
        label: 'Data',
        children: [
          {
            value: 'table',
            label: 'Table',
          },
          {
            value: 'tag',
            label: 'Tag',
          },
          {
            value: 'progress',
            label: 'Progress',
          },
          {
            value: 'tree',
            label: 'Tree',
          },
          {
            value: 'pagination',
            label: 'Pagination',
          },
          {
            value: 'badge',
            label: 'Badge',
          },
        ],
      },
      {
        value: 'notice',
        label: 'Notice',
        children: [
          {
            value: 'alert',
            label: 'Alert',
          },
          {
            value: 'loading',
            label: 'Loading',
          },
          {
            value: 'message',
            label: 'Message',
          },
          {
            value: 'message-box',
            label: 'MessageBox',
          },
          {
            value: 'notification',
            label: 'Notification',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'menu',
            label: 'Menu',
          },
          {
            value: 'tabs',
            label: 'Tabs',
          },
          {
            value: 'breadcrumb',
            label: 'Breadcrumb',
          },
          {
            value: 'dropdown',
            label: 'Dropdown',
          },
          {
            value: 'steps',
            label: 'Steps',
          },
        ],
      },
      {
        value: 'others',
        label: 'Others',
        children: [
          {
            value: 'dialog',
            label: 'Dialog',
          },
          {
            value: 'tooltip',
            label: 'Tooltip',
          },
          {
            value: 'popover',
            label: 'Popover',
          },
          {
            value: 'card',
            label: 'Card',
          },
          {
            value: 'carousel',
            label: 'Carousel',
          },
          {
            value: 'collapse',
            label: 'Collapse',
          },
        ],
      },
    ],
  },
  {
    value: 'resource',
    label: 'Resource',
    children: [
      {
        value: 'axure',
        label: 'Axure Components',
      },
      {
        value: 'sketch',
        label: 'Sketch Templates',
      },
      {
        value: 'docs',
        label: 'Design Documentation',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 动态加载 [​](#动态加载)

当选中某一级时，动态加载该级下的选项。

通过`lazy`开启动态加载，并通过`lazyload`来设置加载数据源的方法。 `lazyload`方法有两个参数，第一个参数`node`为当前点击的节点，第二个`resolve`为数据加载完成的回调(必须调用)。 为了更准确的显示节点的状态，还可以对节点数据添加是否为叶子节点的标志位 (默认字段为`leaf`，可通过`props.leaf`修改)。 否则，将以有无子节点来判断其是否为叶子节点。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FzY2FkZXIgOnByb3BzPVwicHJvcHNcIiAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB0eXBlIHsgQ2FzY2FkZXJQcm9wcyB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxubGV0IGlkID0gMFxuY29uc3QgcHJvcHM6IENhc2NhZGVyUHJvcHMgPSB7XG4gIGxhenk6IHRydWUsXG4gIGxhenlMb2FkKG5vZGUsIHJlc29sdmUpIHtcbiAgICBjb25zdCB7IGxldmVsIH0gPSBub2RlXG4gICAgc2V0VGltZW91dCgoKSA9PiB7XG4gICAgICBjb25zdCBub2RlcyA9IEFycmF5LmZyb20oeyBsZW5ndGg6IGxldmVsICsgMSB9KS5tYXAoKGl0ZW0pID0+ICh7XG4gICAgICAgIHZhbHVlOiArK2lkLFxuICAgICAgICBsYWJlbDogYE9wdGlvbiAtICR7aWR9YCxcbiAgICAgICAgbGVhZjogbGV2ZWwgPj0gMixcbiAgICAgIH0pKVxuICAgICAgLy8gSW52b2tlIGByZXNvbHZlYCBjYWxsYmFjayB0byByZXR1cm4gdGhlIGNoaWxkIG5vZGVzIGRhdGEgYW5kIGluZGljYXRlIHRoZSBsb2FkaW5nIGlzIGZpbmlzaGVkLlxuICAgICAgcmVzb2x2ZShub2RlcylcbiAgICB9LCAxMDAwKVxuICB9LFxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/dynamic-loading.vue)_

vue

```
<template>
  <el-cascader :props="props" />
</template>

<script lang="ts" setup>
import type { CascaderProps } from 'element-plus'

let id = 0
const props: CascaderProps = {
  lazy: true,
  lazyLoad(node, resolve) {
    const { level } = node
    setTimeout(() => {
      const nodes = Array.from({ length: level + 1 }).map((item) => ({
        value: ++id,
        label: `Option - ${id}`,
        leaf: level >= 2,
      }))
      // Invoke `resolve` callback to return the child nodes data and indicate the loading is finished.
      resolve(nodes)
    }, 1000)
  },
}
</script>
```

隐藏源代码

## 可搜索 [​](#可搜索)

可以快捷地搜索选项并选择。

通过添加`filterable`来启用过滤。 Cascader 会匹配所有节点的标签和它们的亲节点的标签，是否包含有输入的关键字。 你也可以用`filter-method`自定义搜索逻辑，接受一个函数，第一个参数是节点`node`，第二个参数是搜索关键词`keyword`，通过返回布尔值表示是否命中。

Filterable (Single selection)

Filterable (Multiple selection)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+RmlsdGVyYWJsZSAoU2luZ2xlIHNlbGVjdGlvbik8L3A+XG4gICAgPGVsLWNhc2NhZGVyXG4gICAgICBwbGFjZWhvbGRlcj1cIlRyeSBzZWFyY2hpbmdMIEd1aWRlXCJcbiAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICBmaWx0ZXJhYmxlXG4gICAgLz5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJtLTRcIj5cbiAgICA8cD5GaWx0ZXJhYmxlIChNdWx0aXBsZSBzZWxlY3Rpb24pPC9wPlxuICAgIDxlbC1jYXNjYWRlclxuICAgICAgcGxhY2Vob2xkZXI9XCJUcnkgc2VhcmNoaW5nTCBHdWlkZVwiXG4gICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgOnByb3BzPVwicHJvcHNcIlxuICAgICAgZmlsdGVyYWJsZVxuICAgIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IHByb3BzID0ge1xuICBtdWx0aXBsZTogdHJ1ZSxcbn1cblxuY29uc3Qgb3B0aW9ucyA9IFtcbiAge1xuICAgIHZhbHVlOiAnZ3VpZGUnLFxuICAgIGxhYmVsOiAnR3VpZGUnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnZGlzY2lwbGluZXMnLFxuICAgICAgICBsYWJlbDogJ0Rpc2NpcGxpbmVzJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbnNpc3RlbmN5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ29uc2lzdGVuY3knLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdmZWVkYmFjaycsXG4gICAgICAgICAgICBsYWJlbDogJ0ZlZWRiYWNrJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZWZmaWNpZW5jeScsXG4gICAgICAgICAgICBsYWJlbDogJ0VmZmljaWVuY3knLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjb250cm9sbGFiaWxpdHknLFxuICAgICAgICAgICAgbGFiZWw6ICdDb250cm9sbGFiaWxpdHknLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ25hdmlnYXRpb24nLFxuICAgICAgICBsYWJlbDogJ05hdmlnYXRpb24nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2lkZSBuYXYnLFxuICAgICAgICAgICAgbGFiZWw6ICdTaWRlIE5hdmlnYXRpb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0b3AgbmF2JyxcbiAgICAgICAgICAgIGxhYmVsOiAnVG9wIE5hdmlnYXRpb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ2NvbXBvbmVudCcsXG4gICAgbGFiZWw6ICdDb21wb25lbnQnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnYmFzaWMnLFxuICAgICAgICBsYWJlbDogJ0Jhc2ljJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2xheW91dCcsXG4gICAgICAgICAgICBsYWJlbDogJ0xheW91dCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbG9yJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ29sb3InLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0eXBvZ3JhcGh5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnVHlwb2dyYXBoeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2ljb24nLFxuICAgICAgICAgICAgbGFiZWw6ICdJY29uJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnYnV0dG9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQnV0dG9uJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdmb3JtJyxcbiAgICAgICAgbGFiZWw6ICdGb3JtJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3JhZGlvJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUmFkaW8nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjaGVja2JveCcsXG4gICAgICAgICAgICBsYWJlbDogJ0NoZWNrYm94JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaW5wdXQnLFxuICAgICAgICAgICAgbGFiZWw6ICdJbnB1dCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2lucHV0LW51bWJlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0lucHV0TnVtYmVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2VsZWN0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnU2VsZWN0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2FzY2FkZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdDYXNjYWRlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3N3aXRjaCcsXG4gICAgICAgICAgICBsYWJlbDogJ1N3aXRjaCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3NsaWRlcicsXG4gICAgICAgICAgICBsYWJlbDogJ1NsaWRlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RpbWUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGltZVBpY2tlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2RhdGUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGF0ZVBpY2tlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2RhdGV0aW1lLXBpY2tlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0RhdGVUaW1lUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndXBsb2FkJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVXBsb2FkJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncmF0ZScsXG4gICAgICAgICAgICBsYWJlbDogJ1JhdGUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdmb3JtJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRm9ybScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnZGF0YScsXG4gICAgICAgIGxhYmVsOiAnRGF0YScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0YWJsZScsXG4gICAgICAgICAgICBsYWJlbDogJ1RhYmxlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGFnJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGFnJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncHJvZ3Jlc3MnLFxuICAgICAgICAgICAgbGFiZWw6ICdQcm9ncmVzcycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RyZWUnLFxuICAgICAgICAgICAgbGFiZWw6ICdUcmVlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncGFnaW5hdGlvbicsXG4gICAgICAgICAgICBsYWJlbDogJ1BhZ2luYXRpb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdiYWRnZScsXG4gICAgICAgICAgICBsYWJlbDogJ0JhZGdlJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdub3RpY2UnLFxuICAgICAgICBsYWJlbDogJ05vdGljZScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdhbGVydCcsXG4gICAgICAgICAgICBsYWJlbDogJ0FsZXJ0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbG9hZGluZycsXG4gICAgICAgICAgICBsYWJlbDogJ0xvYWRpbmcnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdtZXNzYWdlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTWVzc2FnZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lc3NhZ2UtYm94JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTWVzc2FnZUJveCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ25vdGlmaWNhdGlvbicsXG4gICAgICAgICAgICBsYWJlbDogJ05vdGlmaWNhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnbmF2aWdhdGlvbicsXG4gICAgICAgIGxhYmVsOiAnTmF2aWdhdGlvbicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdtZW51JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTWVudScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RhYnMnLFxuICAgICAgICAgICAgbGFiZWw6ICdUYWJzJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnYnJlYWRjcnVtYicsXG4gICAgICAgICAgICBsYWJlbDogJ0JyZWFkY3J1bWInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdkcm9wZG93bicsXG4gICAgICAgICAgICBsYWJlbDogJ0Ryb3Bkb3duJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc3RlcHMnLFxuICAgICAgICAgICAgbGFiZWw6ICdTdGVwcycsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnb3RoZXJzJyxcbiAgICAgICAgbGFiZWw6ICdPdGhlcnMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGlhbG9nJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGlhbG9nJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndG9vbHRpcCcsXG4gICAgICAgICAgICBsYWJlbDogJ1Rvb2x0aXAnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwb3BvdmVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUG9wb3ZlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NhcmQnLFxuICAgICAgICAgICAgbGFiZWw6ICdDYXJkJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2Fyb3VzZWwnLFxuICAgICAgICAgICAgbGFiZWw6ICdDYXJvdXNlbCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbGxhcHNlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ29sbGFwc2UnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ3Jlc291cmNlJyxcbiAgICBsYWJlbDogJ1Jlc291cmNlJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2F4dXJlJyxcbiAgICAgICAgbGFiZWw6ICdBeHVyZSBDb21wb25lbnRzJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnc2tldGNoJyxcbiAgICAgICAgbGFiZWw6ICdTa2V0Y2ggVGVtcGxhdGVzJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnZG9jcycsXG4gICAgICAgIGxhYmVsOiAnRGVzaWduIERvY3VtZW50YXRpb24nLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/filterable.vue)_

vue

```
<template>
  <div class="m-4">
    <p>Filterable (Single selection)</p>
    <el-cascader
      placeholder="Try searchingL Guide"
      :options="options"
      filterable
    />
  </div>
  <div class="m-4">
    <p>Filterable (Multiple selection)</p>
    <el-cascader
      placeholder="Try searchingL Guide"
      :options="options"
      :props="props"
      filterable
    />
  </div>
</template>

<script lang="ts" setup>
const props = {
  multiple: true,
}

const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
          {
            value: 'feedback',
            label: 'Feedback',
          },
          {
            value: 'efficiency',
            label: 'Efficiency',
          },
          {
            value: 'controllability',
            label: 'Controllability',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
          {
            value: 'top nav',
            label: 'Top Navigation',
          },
        ],
      },
    ],
  },
  {
    value: 'component',
    label: 'Component',
    children: [
      {
        value: 'basic',
        label: 'Basic',
        children: [
          {
            value: 'layout',
            label: 'Layout',
          },
          {
            value: 'color',
            label: 'Color',
          },
          {
            value: 'typography',
            label: 'Typography',
          },
          {
            value: 'icon',
            label: 'Icon',
          },
          {
            value: 'button',
            label: 'Button',
          },
        ],
      },
      {
        value: 'form',
        label: 'Form',
        children: [
          {
            value: 'radio',
            label: 'Radio',
          },
          {
            value: 'checkbox',
            label: 'Checkbox',
          },
          {
            value: 'input',
            label: 'Input',
          },
          {
            value: 'input-number',
            label: 'InputNumber',
          },
          {
            value: 'select',
            label: 'Select',
          },
          {
            value: 'cascader',
            label: 'Cascader',
          },
          {
            value: 'switch',
            label: 'Switch',
          },
          {
            value: 'slider',
            label: 'Slider',
          },
          {
            value: 'time-picker',
            label: 'TimePicker',
          },
          {
            value: 'date-picker',
            label: 'DatePicker',
          },
          {
            value: 'datetime-picker',
            label: 'DateTimePicker',
          },
          {
            value: 'upload',
            label: 'Upload',
          },
          {
            value: 'rate',
            label: 'Rate',
          },
          {
            value: 'form',
            label: 'Form',
          },
        ],
      },
      {
        value: 'data',
        label: 'Data',
        children: [
          {
            value: 'table',
            label: 'Table',
          },
          {
            value: 'tag',
            label: 'Tag',
          },
          {
            value: 'progress',
            label: 'Progress',
          },
          {
            value: 'tree',
            label: 'Tree',
          },
          {
            value: 'pagination',
            label: 'Pagination',
          },
          {
            value: 'badge',
            label: 'Badge',
          },
        ],
      },
      {
        value: 'notice',
        label: 'Notice',
        children: [
          {
            value: 'alert',
            label: 'Alert',
          },
          {
            value: 'loading',
            label: 'Loading',
          },
          {
            value: 'message',
            label: 'Message',
          },
          {
            value: 'message-box',
            label: 'MessageBox',
          },
          {
            value: 'notification',
            label: 'Notification',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'menu',
            label: 'Menu',
          },
          {
            value: 'tabs',
            label: 'Tabs',
          },
          {
            value: 'breadcrumb',
            label: 'Breadcrumb',
          },
          {
            value: 'dropdown',
            label: 'Dropdown',
          },
          {
            value: 'steps',
            label: 'Steps',
          },
        ],
      },
      {
        value: 'others',
        label: 'Others',
        children: [
          {
            value: 'dialog',
            label: 'Dialog',
          },
          {
            value: 'tooltip',
            label: 'Tooltip',
          },
          {
            value: 'popover',
            label: 'Popover',
          },
          {
            value: 'card',
            label: 'Card',
          },
          {
            value: 'carousel',
            label: 'Carousel',
          },
          {
            value: 'collapse',
            label: 'Collapse',
          },
        ],
      },
    ],
  },
  {
    value: 'resource',
    label: 'Resource',
    children: [
      {
        value: 'axure',
        label: 'Axure Components',
      },
      {
        value: 'sketch',
        label: 'Sketch Templates',
      },
      {
        value: 'docs',
        label: 'Design Documentation',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 自定义节点内容 [​](#自定义节点内容)

可以自定义备选项的节点内容

你可以通过 `scoped slot` 自定义节点的内容。 您可以访问 scope 中的 `node` 和 `data` 属性，分别表示当前节点的 Node 对象和当前节点的数据。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FzY2FkZXIgOm9wdGlvbnM9XCJvcHRpb25zXCI+XG4gICAgPHRlbXBsYXRlICNkZWZhdWx0PVwieyBub2RlLCBkYXRhIH1cIj5cbiAgICAgIDxzcGFuPnt7IGRhdGEubGFiZWwgfX08L3NwYW4+XG4gICAgICA8c3BhbiB2LWlmPVwiIW5vZGUuaXNMZWFmXCI+ICh7eyBkYXRhLmNoaWxkcmVuLmxlbmd0aCB9fSkgPC9zcGFuPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtY2FzY2FkZXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuY29uc3Qgb3B0aW9ucyA9IFtcbiAge1xuICAgIHZhbHVlOiAnZ3VpZGUnLFxuICAgIGxhYmVsOiAnR3VpZGUnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnZGlzY2lwbGluZXMnLFxuICAgICAgICBsYWJlbDogJ0Rpc2NpcGxpbmVzJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbnNpc3RlbmN5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ29uc2lzdGVuY3knLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdmZWVkYmFjaycsXG4gICAgICAgICAgICBsYWJlbDogJ0ZlZWRiYWNrJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZWZmaWNpZW5jeScsXG4gICAgICAgICAgICBsYWJlbDogJ0VmZmljaWVuY3knLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjb250cm9sbGFiaWxpdHknLFxuICAgICAgICAgICAgbGFiZWw6ICdDb250cm9sbGFiaWxpdHknLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ25hdmlnYXRpb24nLFxuICAgICAgICBsYWJlbDogJ05hdmlnYXRpb24nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2lkZSBuYXYnLFxuICAgICAgICAgICAgbGFiZWw6ICdTaWRlIE5hdmlnYXRpb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0b3AgbmF2JyxcbiAgICAgICAgICAgIGxhYmVsOiAnVG9wIE5hdmlnYXRpb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ2NvbXBvbmVudCcsXG4gICAgbGFiZWw6ICdDb21wb25lbnQnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnYmFzaWMnLFxuICAgICAgICBsYWJlbDogJ0Jhc2ljJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2xheW91dCcsXG4gICAgICAgICAgICBsYWJlbDogJ0xheW91dCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbG9yJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ29sb3InLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0eXBvZ3JhcGh5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnVHlwb2dyYXBoeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2ljb24nLFxuICAgICAgICAgICAgbGFiZWw6ICdJY29uJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnYnV0dG9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQnV0dG9uJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdmb3JtJyxcbiAgICAgICAgbGFiZWw6ICdGb3JtJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3JhZGlvJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUmFkaW8nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjaGVja2JveCcsXG4gICAgICAgICAgICBsYWJlbDogJ0NoZWNrYm94JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaW5wdXQnLFxuICAgICAgICAgICAgbGFiZWw6ICdJbnB1dCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2lucHV0LW51bWJlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0lucHV0TnVtYmVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2VsZWN0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnU2VsZWN0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2FzY2FkZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdDYXNjYWRlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3N3aXRjaCcsXG4gICAgICAgICAgICBsYWJlbDogJ1N3aXRjaCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3NsaWRlcicsXG4gICAgICAgICAgICBsYWJlbDogJ1NsaWRlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RpbWUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGltZVBpY2tlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2RhdGUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGF0ZVBpY2tlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2RhdGV0aW1lLXBpY2tlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0RhdGVUaW1lUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndXBsb2FkJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVXBsb2FkJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncmF0ZScsXG4gICAgICAgICAgICBsYWJlbDogJ1JhdGUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdmb3JtJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRm9ybScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnZGF0YScsXG4gICAgICAgIGxhYmVsOiAnRGF0YScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0YWJsZScsXG4gICAgICAgICAgICBsYWJlbDogJ1RhYmxlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGFnJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGFnJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncHJvZ3Jlc3MnLFxuICAgICAgICAgICAgbGFiZWw6ICdQcm9ncmVzcycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RyZWUnLFxuICAgICAgICAgICAgbGFiZWw6ICdUcmVlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncGFnaW5hdGlvbicsXG4gICAgICAgICAgICBsYWJlbDogJ1BhZ2luYXRpb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdiYWRnZScsXG4gICAgICAgICAgICBsYWJlbDogJ0JhZGdlJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdub3RpY2UnLFxuICAgICAgICBsYWJlbDogJ05vdGljZScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdhbGVydCcsXG4gICAgICAgICAgICBsYWJlbDogJ0FsZXJ0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbG9hZGluZycsXG4gICAgICAgICAgICBsYWJlbDogJ0xvYWRpbmcnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdtZXNzYWdlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTWVzc2FnZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lc3NhZ2UtYm94JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTWVzc2FnZUJveCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ25vdGlmaWNhdGlvbicsXG4gICAgICAgICAgICBsYWJlbDogJ05vdGlmaWNhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnbmF2aWdhdGlvbicsXG4gICAgICAgIGxhYmVsOiAnTmF2aWdhdGlvbicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdtZW51JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTWVudScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RhYnMnLFxuICAgICAgICAgICAgbGFiZWw6ICdUYWJzJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnYnJlYWRjcnVtYicsXG4gICAgICAgICAgICBsYWJlbDogJ0JyZWFkY3J1bWInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdkcm9wZG93bicsXG4gICAgICAgICAgICBsYWJlbDogJ0Ryb3Bkb3duJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc3RlcHMnLFxuICAgICAgICAgICAgbGFiZWw6ICdTdGVwcycsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnb3RoZXJzJyxcbiAgICAgICAgbGFiZWw6ICdPdGhlcnMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGlhbG9nJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGlhbG9nJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndG9vbHRpcCcsXG4gICAgICAgICAgICBsYWJlbDogJ1Rvb2x0aXAnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwb3BvdmVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUG9wb3ZlcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NhcmQnLFxuICAgICAgICAgICAgbGFiZWw6ICdDYXJkJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2Fyb3VzZWwnLFxuICAgICAgICAgICAgbGFiZWw6ICdDYXJvdXNlbCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbGxhcHNlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ29sbGFwc2UnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ3Jlc291cmNlJyxcbiAgICBsYWJlbDogJ1Jlc291cmNlJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2F4dXJlJyxcbiAgICAgICAgbGFiZWw6ICdBeHVyZSBDb21wb25lbnRzJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnc2tldGNoJyxcbiAgICAgICAgbGFiZWw6ICdTa2V0Y2ggVGVtcGxhdGVzJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnZG9jcycsXG4gICAgICAgIGxhYmVsOiAnRGVzaWduIERvY3VtZW50YXRpb24nLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/custom-content.vue)_

vue

```
<template>
  <el-cascader :options="options">
    <template #default="{ node, data }">
      <span>{{ data.label }}</span>
      <span v-if="!node.isLeaf"> ({{ data.children.length }}) </span>
    </template>
  </el-cascader>
</template>

<script lang="ts" setup>
const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
          {
            value: 'feedback',
            label: 'Feedback',
          },
          {
            value: 'efficiency',
            label: 'Efficiency',
          },
          {
            value: 'controllability',
            label: 'Controllability',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
          {
            value: 'top nav',
            label: 'Top Navigation',
          },
        ],
      },
    ],
  },
  {
    value: 'component',
    label: 'Component',
    children: [
      {
        value: 'basic',
        label: 'Basic',
        children: [
          {
            value: 'layout',
            label: 'Layout',
          },
          {
            value: 'color',
            label: 'Color',
          },
          {
            value: 'typography',
            label: 'Typography',
          },
          {
            value: 'icon',
            label: 'Icon',
          },
          {
            value: 'button',
            label: 'Button',
          },
        ],
      },
      {
        value: 'form',
        label: 'Form',
        children: [
          {
            value: 'radio',
            label: 'Radio',
          },
          {
            value: 'checkbox',
            label: 'Checkbox',
          },
          {
            value: 'input',
            label: 'Input',
          },
          {
            value: 'input-number',
            label: 'InputNumber',
          },
          {
            value: 'select',
            label: 'Select',
          },
          {
            value: 'cascader',
            label: 'Cascader',
          },
          {
            value: 'switch',
            label: 'Switch',
          },
          {
            value: 'slider',
            label: 'Slider',
          },
          {
            value: 'time-picker',
            label: 'TimePicker',
          },
          {
            value: 'date-picker',
            label: 'DatePicker',
          },
          {
            value: 'datetime-picker',
            label: 'DateTimePicker',
          },
          {
            value: 'upload',
            label: 'Upload',
          },
          {
            value: 'rate',
            label: 'Rate',
          },
          {
            value: 'form',
            label: 'Form',
          },
        ],
      },
      {
        value: 'data',
        label: 'Data',
        children: [
          {
            value: 'table',
            label: 'Table',
          },
          {
            value: 'tag',
            label: 'Tag',
          },
          {
            value: 'progress',
            label: 'Progress',
          },
          {
            value: 'tree',
            label: 'Tree',
          },
          {
            value: 'pagination',
            label: 'Pagination',
          },
          {
            value: 'badge',
            label: 'Badge',
          },
        ],
      },
      {
        value: 'notice',
        label: 'Notice',
        children: [
          {
            value: 'alert',
            label: 'Alert',
          },
          {
            value: 'loading',
            label: 'Loading',
          },
          {
            value: 'message',
            label: 'Message',
          },
          {
            value: 'message-box',
            label: 'MessageBox',
          },
          {
            value: 'notification',
            label: 'Notification',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'menu',
            label: 'Menu',
          },
          {
            value: 'tabs',
            label: 'Tabs',
          },
          {
            value: 'breadcrumb',
            label: 'Breadcrumb',
          },
          {
            value: 'dropdown',
            label: 'Dropdown',
          },
          {
            value: 'steps',
            label: 'Steps',
          },
        ],
      },
      {
        value: 'others',
        label: 'Others',
        children: [
          {
            value: 'dialog',
            label: 'Dialog',
          },
          {
            value: 'tooltip',
            label: 'Tooltip',
          },
          {
            value: 'popover',
            label: 'Popover',
          },
          {
            value: 'card',
            label: 'Card',
          },
          {
            value: 'carousel',
            label: 'Carousel',
          },
          {
            value: 'collapse',
            label: 'Collapse',
          },
        ],
      },
    ],
  },
  {
    value: 'resource',
    label: 'Resource',
    children: [
      {
        value: 'axure',
        label: 'Axure Components',
      },
      {
        value: 'sketch',
        label: 'Sketch Templates',
      },
      {
        value: 'docs',
        label: 'Design Documentation',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 自定义建议项2.9.5 [​](#自定义建议项)

你可以通过 `suggestion-item` 插槽自定义建议项。 你可以在作用域中访问 `item`，它代表建议项。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FzY2FkZXIgOm9wdGlvbnM9XCJvcHRpb25zXCIgZmlsdGVyYWJsZSBwbGFjZWhvbGRlcj1cIlRyeSBzZWFyY2hpbmc6IEd1aWRlXCI+XG4gICAgPHRlbXBsYXRlICNzdWdnZXN0aW9uLWl0ZW09XCJ7IGl0ZW0gfVwiPlxuICAgICAgPHNwYW4+8J+UjSB7eyBpdGVtLnBhdGhMYWJlbHMuam9pbignID4gJykgfX08L3NwYW4+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1jYXNjYWRlcj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6ICdndWlkZScsXG4gICAgbGFiZWw6ICdHdWlkZScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkaXNjaXBsaW5lcycsXG4gICAgICAgIGxhYmVsOiAnRGlzY2lwbGluZXMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29uc2lzdGVuY3knLFxuICAgICAgICAgICAgbGFiZWw6ICdDb25zaXN0ZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2ZlZWRiYWNrJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRmVlZGJhY2snLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdlZmZpY2llbmN5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnRWZmaWNpZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgICBsYWJlbDogJ0NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnbmF2aWdhdGlvbicsXG4gICAgICAgIGxhYmVsOiAnTmF2aWdhdGlvbicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzaWRlIG5hdicsXG4gICAgICAgICAgICBsYWJlbDogJ1NpZGUgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RvcCBuYXYnLFxuICAgICAgICAgICAgbGFiZWw6ICdUb3AgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnY29tcG9uZW50JyxcbiAgICBsYWJlbDogJ0NvbXBvbmVudCcsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdiYXNpYycsXG4gICAgICAgIGxhYmVsOiAnQmFzaWMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbGF5b3V0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGF5b3V0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sb3InLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xvcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3R5cG9ncmFwaHknLFxuICAgICAgICAgICAgbGFiZWw6ICdUeXBvZ3JhcGh5JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaWNvbicsXG4gICAgICAgICAgICBsYWJlbDogJ0ljb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdidXR0b24nLFxuICAgICAgICAgICAgbGFiZWw6ICdCdXR0b24nLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICBsYWJlbDogJ0Zvcm0nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncmFkaW8nLFxuICAgICAgICAgICAgbGFiZWw6ICdSYWRpbycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NoZWNrYm94JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ2hlY2tib3gnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdpbnB1dCcsXG4gICAgICAgICAgICBsYWJlbDogJ0lucHV0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaW5wdXQtbnVtYmVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnSW5wdXROdW1iZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzZWxlY3QnLFxuICAgICAgICAgICAgbGFiZWw6ICdTZWxlY3QnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXNjYWRlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhc2NhZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc3dpdGNoJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU3dpdGNoJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2xpZGVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU2xpZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGltZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdUaW1lUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdEYXRlUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZXRpbWUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGF0ZVRpbWVQaWNrZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd1cGxvYWQnLFxuICAgICAgICAgICAgbGFiZWw6ICdVcGxvYWQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdyYXRlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUmF0ZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICAgICAgbGFiZWw6ICdGb3JtJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkYXRhJyxcbiAgICAgICAgbGFiZWw6ICdEYXRhJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RhYmxlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGFibGUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0YWcnLFxuICAgICAgICAgICAgbGFiZWw6ICdUYWcnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwcm9ncmVzcycsXG4gICAgICAgICAgICBsYWJlbDogJ1Byb2dyZXNzJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndHJlZScsXG4gICAgICAgICAgICBsYWJlbDogJ1RyZWUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwYWdpbmF0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUGFnaW5hdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2JhZGdlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQmFkZ2UnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ25vdGljZScsXG4gICAgICAgIGxhYmVsOiAnTm90aWNlJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2FsZXJ0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQWxlcnQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdsb2FkaW5nJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTG9hZGluZycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lc3NhZ2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbWVzc2FnZS1ib3gnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlQm94JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbm90aWZpY2F0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTm90aWZpY2F0aW9uJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICduYXZpZ2F0aW9uJyxcbiAgICAgICAgbGFiZWw6ICdOYXZpZ2F0aW9uJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lbnUnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZW51JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGFicycsXG4gICAgICAgICAgICBsYWJlbDogJ1RhYnMnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdicmVhZGNydW1iJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQnJlYWRjcnVtYicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Ryb3Bkb3duJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRHJvcGRvd24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzdGVwcycsXG4gICAgICAgICAgICBsYWJlbDogJ1N0ZXBzJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdvdGhlcnMnLFxuICAgICAgICBsYWJlbDogJ090aGVycycsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdkaWFsb2cnLFxuICAgICAgICAgICAgbGFiZWw6ICdEaWFsb2cnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0b29sdGlwJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVG9vbHRpcCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3BvcG92ZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdQb3BvdmVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2FyZCcsXG4gICAgICAgICAgICBsYWJlbDogJ0NhcmQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXJvdXNlbCcsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhcm91c2VsJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sbGFwc2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xsYXBzZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAncmVzb3VyY2UnLFxuICAgIGxhYmVsOiAnUmVzb3VyY2UnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnYXh1cmUnLFxuICAgICAgICBsYWJlbDogJ0F4dXJlIENvbXBvbmVudHMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdza2V0Y2gnLFxuICAgICAgICBsYWJlbDogJ1NrZXRjaCBUZW1wbGF0ZXMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkb2NzJyxcbiAgICAgICAgbGFiZWw6ICdEZXNpZ24gRG9jdW1lbnRhdGlvbicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/custom-suggestion-item.vue)_

vue

```
<template>
  <el-cascader :options="options" filterable placeholder="Try searching: Guide">
    <template #suggestion-item="{ item }">
      <span>🔍 {{ item.pathLabels.join(' > ') }}</span>
    </template>
  </el-cascader>
</template>

<script lang="ts" setup>
const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
          {
            value: 'feedback',
            label: 'Feedback',
          },
          {
            value: 'efficiency',
            label: 'Efficiency',
          },
          {
            value: 'controllability',
            label: 'Controllability',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
          {
            value: 'top nav',
            label: 'Top Navigation',
          },
        ],
      },
    ],
  },
  {
    value: 'component',
    label: 'Component',
    children: [
      {
        value: 'basic',
        label: 'Basic',
        children: [
          {
            value: 'layout',
            label: 'Layout',
          },
          {
            value: 'color',
            label: 'Color',
          },
          {
            value: 'typography',
            label: 'Typography',
          },
          {
            value: 'icon',
            label: 'Icon',
          },
          {
            value: 'button',
            label: 'Button',
          },
        ],
      },
      {
        value: 'form',
        label: 'Form',
        children: [
          {
            value: 'radio',
            label: 'Radio',
          },
          {
            value: 'checkbox',
            label: 'Checkbox',
          },
          {
            value: 'input',
            label: 'Input',
          },
          {
            value: 'input-number',
            label: 'InputNumber',
          },
          {
            value: 'select',
            label: 'Select',
          },
          {
            value: 'cascader',
            label: 'Cascader',
          },
          {
            value: 'switch',
            label: 'Switch',
          },
          {
            value: 'slider',
            label: 'Slider',
          },
          {
            value: 'time-picker',
            label: 'TimePicker',
          },
          {
            value: 'date-picker',
            label: 'DatePicker',
          },
          {
            value: 'datetime-picker',
            label: 'DateTimePicker',
          },
          {
            value: 'upload',
            label: 'Upload',
          },
          {
            value: 'rate',
            label: 'Rate',
          },
          {
            value: 'form',
            label: 'Form',
          },
        ],
      },
      {
        value: 'data',
        label: 'Data',
        children: [
          {
            value: 'table',
            label: 'Table',
          },
          {
            value: 'tag',
            label: 'Tag',
          },
          {
            value: 'progress',
            label: 'Progress',
          },
          {
            value: 'tree',
            label: 'Tree',
          },
          {
            value: 'pagination',
            label: 'Pagination',
          },
          {
            value: 'badge',
            label: 'Badge',
          },
        ],
      },
      {
        value: 'notice',
        label: 'Notice',
        children: [
          {
            value: 'alert',
            label: 'Alert',
          },
          {
            value: 'loading',
            label: 'Loading',
          },
          {
            value: 'message',
            label: 'Message',
          },
          {
            value: 'message-box',
            label: 'MessageBox',
          },
          {
            value: 'notification',
            label: 'Notification',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'menu',
            label: 'Menu',
          },
          {
            value: 'tabs',
            label: 'Tabs',
          },
          {
            value: 'breadcrumb',
            label: 'Breadcrumb',
          },
          {
            value: 'dropdown',
            label: 'Dropdown',
          },
          {
            value: 'steps',
            label: 'Steps',
          },
        ],
      },
      {
        value: 'others',
        label: 'Others',
        children: [
          {
            value: 'dialog',
            label: 'Dialog',
          },
          {
            value: 'tooltip',
            label: 'Tooltip',
          },
          {
            value: 'popover',
            label: 'Popover',
          },
          {
            value: 'card',
            label: 'Card',
          },
          {
            value: 'carousel',
            label: 'Carousel',
          },
          {
            value: 'collapse',
            label: 'Collapse',
          },
        ],
      },
    ],
  },
  {
    value: 'resource',
    label: 'Resource',
    children: [
      {
        value: 'axure',
        label: 'Axure Components',
      },
      {
        value: 'sketch',
        label: 'Sketch Templates',
      },
      {
        value: 'docs',
        label: 'Design Documentation',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 级联面板 [​](#级联面板)

级联面板是级联选择器的核心组件，与级联选择器一样，有单选、多选、动态加载等多种功能。

和级联选择器一样，通过 `options` 来指定选项，也可通过 `props` 来设置多选、动态加载等功能，具体详情见下方API表格。

-   Guide
-   Component
-   Resource

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FzY2FkZXItcGFuZWwgOm9wdGlvbnM9XCJvcHRpb25zXCIgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6ICdndWlkZScsXG4gICAgbGFiZWw6ICdHdWlkZScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkaXNjaXBsaW5lcycsXG4gICAgICAgIGxhYmVsOiAnRGlzY2lwbGluZXMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29uc2lzdGVuY3knLFxuICAgICAgICAgICAgbGFiZWw6ICdDb25zaXN0ZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2ZlZWRiYWNrJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRmVlZGJhY2snLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdlZmZpY2llbmN5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnRWZmaWNpZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgICBsYWJlbDogJ0NvbnRyb2xsYWJpbGl0eScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnbmF2aWdhdGlvbicsXG4gICAgICAgIGxhYmVsOiAnTmF2aWdhdGlvbicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzaWRlIG5hdicsXG4gICAgICAgICAgICBsYWJlbDogJ1NpZGUgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RvcCBuYXYnLFxuICAgICAgICAgICAgbGFiZWw6ICdUb3AgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnY29tcG9uZW50JyxcbiAgICBsYWJlbDogJ0NvbXBvbmVudCcsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdiYXNpYycsXG4gICAgICAgIGxhYmVsOiAnQmFzaWMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbGF5b3V0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGF5b3V0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sb3InLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xvcicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3R5cG9ncmFwaHknLFxuICAgICAgICAgICAgbGFiZWw6ICdUeXBvZ3JhcGh5JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaWNvbicsXG4gICAgICAgICAgICBsYWJlbDogJ0ljb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdidXR0b24nLFxuICAgICAgICAgICAgbGFiZWw6ICdCdXR0b24nLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICBsYWJlbDogJ0Zvcm0nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncmFkaW8nLFxuICAgICAgICAgICAgbGFiZWw6ICdSYWRpbycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NoZWNrYm94JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ2hlY2tib3gnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdpbnB1dCcsXG4gICAgICAgICAgICBsYWJlbDogJ0lucHV0JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnaW5wdXQtbnVtYmVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnSW5wdXROdW1iZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzZWxlY3QnLFxuICAgICAgICAgICAgbGFiZWw6ICdTZWxlY3QnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXNjYWRlcicsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhc2NhZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc3dpdGNoJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU3dpdGNoJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2xpZGVyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnU2xpZGVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGltZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdUaW1lUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZS1waWNrZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdEYXRlUGlja2VyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZGF0ZXRpbWUtcGlja2VyJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRGF0ZVRpbWVQaWNrZXInLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd1cGxvYWQnLFxuICAgICAgICAgICAgbGFiZWw6ICdVcGxvYWQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdyYXRlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUmF0ZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICAgICAgbGFiZWw6ICdGb3JtJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkYXRhJyxcbiAgICAgICAgbGFiZWw6ICdEYXRhJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3RhYmxlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVGFibGUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0YWcnLFxuICAgICAgICAgICAgbGFiZWw6ICdUYWcnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwcm9ncmVzcycsXG4gICAgICAgICAgICBsYWJlbDogJ1Byb2dyZXNzJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndHJlZScsXG4gICAgICAgICAgICBsYWJlbDogJ1RyZWUnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdwYWdpbmF0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUGFnaW5hdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2JhZGdlJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQmFkZ2UnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ25vdGljZScsXG4gICAgICAgIGxhYmVsOiAnTm90aWNlJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2FsZXJ0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQWxlcnQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdsb2FkaW5nJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTG9hZGluZycsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lc3NhZ2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbWVzc2FnZS1ib3gnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZXNzYWdlQm94JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbm90aWZpY2F0aW9uJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTm90aWZpY2F0aW9uJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICduYXZpZ2F0aW9uJyxcbiAgICAgICAgbGFiZWw6ICdOYXZpZ2F0aW9uJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ21lbnUnLFxuICAgICAgICAgICAgbGFiZWw6ICdNZW51JyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAndGFicycsXG4gICAgICAgICAgICBsYWJlbDogJ1RhYnMnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdicmVhZGNydW1iJyxcbiAgICAgICAgICAgIGxhYmVsOiAnQnJlYWRjcnVtYicsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2Ryb3Bkb3duJyxcbiAgICAgICAgICAgIGxhYmVsOiAnRHJvcGRvd24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzdGVwcycsXG4gICAgICAgICAgICBsYWJlbDogJ1N0ZXBzJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdvdGhlcnMnLFxuICAgICAgICBsYWJlbDogJ090aGVycycsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdkaWFsb2cnLFxuICAgICAgICAgICAgbGFiZWw6ICdEaWFsb2cnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0b29sdGlwJyxcbiAgICAgICAgICAgIGxhYmVsOiAnVG9vbHRpcCcsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3BvcG92ZXInLFxuICAgICAgICAgICAgbGFiZWw6ICdQb3BvdmVyJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY2FyZCcsXG4gICAgICAgICAgICBsYWJlbDogJ0NhcmQnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjYXJvdXNlbCcsXG4gICAgICAgICAgICBsYWJlbDogJ0Nhcm91c2VsJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29sbGFwc2UnLFxuICAgICAgICAgICAgbGFiZWw6ICdDb2xsYXBzZScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAncmVzb3VyY2UnLFxuICAgIGxhYmVsOiAnUmVzb3VyY2UnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnYXh1cmUnLFxuICAgICAgICBsYWJlbDogJ0F4dXJlIENvbXBvbmVudHMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdza2V0Y2gnLFxuICAgICAgICBsYWJlbDogJ1NrZXRjaCBUZW1wbGF0ZXMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkb2NzJyxcbiAgICAgICAgbGFiZWw6ICdEZXNpZ24gRG9jdW1lbnRhdGlvbicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/panel.vue)_

vue

```
<template>
  <el-cascader-panel :options="options" />
</template>

<script lang="ts" setup>
const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
          {
            value: 'feedback',
            label: 'Feedback',
          },
          {
            value: 'efficiency',
            label: 'Efficiency',
          },
          {
            value: 'controllability',
            label: 'Controllability',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
          {
            value: 'top nav',
            label: 'Top Navigation',
          },
        ],
      },
    ],
  },
  {
    value: 'component',
    label: 'Component',
    children: [
      {
        value: 'basic',
        label: 'Basic',
        children: [
          {
            value: 'layout',
            label: 'Layout',
          },
          {
            value: 'color',
            label: 'Color',
          },
          {
            value: 'typography',
            label: 'Typography',
          },
          {
            value: 'icon',
            label: 'Icon',
          },
          {
            value: 'button',
            label: 'Button',
          },
        ],
      },
      {
        value: 'form',
        label: 'Form',
        children: [
          {
            value: 'radio',
            label: 'Radio',
          },
          {
            value: 'checkbox',
            label: 'Checkbox',
          },
          {
            value: 'input',
            label: 'Input',
          },
          {
            value: 'input-number',
            label: 'InputNumber',
          },
          {
            value: 'select',
            label: 'Select',
          },
          {
            value: 'cascader',
            label: 'Cascader',
          },
          {
            value: 'switch',
            label: 'Switch',
          },
          {
            value: 'slider',
            label: 'Slider',
          },
          {
            value: 'time-picker',
            label: 'TimePicker',
          },
          {
            value: 'date-picker',
            label: 'DatePicker',
          },
          {
            value: 'datetime-picker',
            label: 'DateTimePicker',
          },
          {
            value: 'upload',
            label: 'Upload',
          },
          {
            value: 'rate',
            label: 'Rate',
          },
          {
            value: 'form',
            label: 'Form',
          },
        ],
      },
      {
        value: 'data',
        label: 'Data',
        children: [
          {
            value: 'table',
            label: 'Table',
          },
          {
            value: 'tag',
            label: 'Tag',
          },
          {
            value: 'progress',
            label: 'Progress',
          },
          {
            value: 'tree',
            label: 'Tree',
          },
          {
            value: 'pagination',
            label: 'Pagination',
          },
          {
            value: 'badge',
            label: 'Badge',
          },
        ],
      },
      {
        value: 'notice',
        label: 'Notice',
        children: [
          {
            value: 'alert',
            label: 'Alert',
          },
          {
            value: 'loading',
            label: 'Loading',
          },
          {
            value: 'message',
            label: 'Message',
          },
          {
            value: 'message-box',
            label: 'MessageBox',
          },
          {
            value: 'notification',
            label: 'Notification',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'menu',
            label: 'Menu',
          },
          {
            value: 'tabs',
            label: 'Tabs',
          },
          {
            value: 'breadcrumb',
            label: 'Breadcrumb',
          },
          {
            value: 'dropdown',
            label: 'Dropdown',
          },
          {
            value: 'steps',
            label: 'Steps',
          },
        ],
      },
      {
        value: 'others',
        label: 'Others',
        children: [
          {
            value: 'dialog',
            label: 'Dialog',
          },
          {
            value: 'tooltip',
            label: 'Tooltip',
          },
          {
            value: 'popover',
            label: 'Popover',
          },
          {
            value: 'card',
            label: 'Card',
          },
          {
            value: 'carousel',
            label: 'Carousel',
          },
          {
            value: 'collapse',
            label: 'Collapse',
          },
        ],
      },
    ],
  },
  {
    value: 'resource',
    label: 'Resource',
    children: [
      {
        value: 'axure',
        label: 'Axure Components',
      },
      {
        value: 'sketch',
        label: 'Sketch Templates',
      },
      {
        value: 'docs',
        label: 'Design Documentation',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 自定义标签 2.10.3 [​](#自定义标签)

您可以自定义标签。

将自定义的标签插入 `el-cascader` 的 slot 中即可。 `collapse-tags`, `collapse-tags-tooltip`, `max-collapse-tags` 在此模式下不生效.

Using slots allows for more flexible control over the display.

Display top-level tags only

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+VXNpbmcgc2xvdHMgYWxsb3dzIGZvciBtb3JlIGZsZXhpYmxlIGNvbnRyb2wgb3ZlciB0aGUgZGlzcGxheS48L3A+XG4gICAgPGVsLWNhc2NhZGVyIDpvcHRpb25zPVwib3B0aW9uc1wiIDpwcm9wcz1cInByb3BzXCIgY2xlYXJhYmxlPlxuICAgICAgPHRlbXBsYXRlICN0YWc9XCJ7IGRhdGEgfVwiPlxuICAgICAgICA8ZWwtdGFnXG4gICAgICAgICAgdi1mb3I9XCIoaXRlbSwgaW5kZXgpIGluIGdldFRhZ3MoZGF0YSlcIlxuICAgICAgICAgIDprZXk9XCJpdGVtXCJcbiAgICAgICAgICA6Y29sb3I9XCJpbmRleCAlIDIgPT09IDAgPyAnI0ZGREUwQScgOiAnJ1wiXG4gICAgICAgID5cbiAgICAgICAgICB7eyBpdGVtIH19XG4gICAgICAgIDwvZWwtdGFnPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWNhc2NhZGVyPlxuICAgIDxwPkRpc3BsYXkgdG9wLWxldmVsIHRhZ3Mgb25seTwvcD5cbiAgICA8ZWwtY2FzY2FkZXIgOm9wdGlvbnM9XCJvcHRpb25zXCIgOnByb3BzPVwicHJvcHNcIiBjbGVhcmFibGU+XG4gICAgICA8dGVtcGxhdGUgI3RhZz1cInsgZGF0YSB9XCI+XG4gICAgICAgIDxlbC10YWcgdi1mb3I9XCJpdGVtIGluIGdldFRvcExldmVsVGFncyhkYXRhKVwiIDprZXk9XCJpdGVtXCI+XG4gICAgICAgICAge3sgaXRlbSB9fVxuICAgICAgICA8L2VsLXRhZz5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1jYXNjYWRlcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHR5cGUgeyBUYWcgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHByb3BzID0geyBtdWx0aXBsZTogdHJ1ZSB9XG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6IDEsXG4gICAgbGFiZWw6ICdBc2lhJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogMixcbiAgICAgICAgbGFiZWw6ICdDaGluYScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAgeyB2YWx1ZTogMywgbGFiZWw6ICdCZWlqaW5nJyB9LFxuICAgICAgICAgIHsgdmFsdWU6IDQsIGxhYmVsOiAnU2hhbmdoYWknIH0sXG4gICAgICAgICAgeyB2YWx1ZTogNSwgbGFiZWw6ICdIYW5nemhvdScgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiA2LFxuICAgICAgICBsYWJlbDogJ0phcGFuJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7IHZhbHVlOiA3LCBsYWJlbDogJ1Rva3lvJyB9LFxuICAgICAgICAgIHsgdmFsdWU6IDgsIGxhYmVsOiAnT3Nha2EnIH0sXG4gICAgICAgICAgeyB2YWx1ZTogOSwgbGFiZWw6ICdLeW90bycgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAxMCxcbiAgICAgICAgbGFiZWw6ICdLb3JlYScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAgeyB2YWx1ZTogMTEsIGxhYmVsOiAnU2VvdWwnIH0sXG4gICAgICAgICAgeyB2YWx1ZTogMTIsIGxhYmVsOiAnQnVzYW4nIH0sXG4gICAgICAgICAgeyB2YWx1ZTogMTMsIGxhYmVsOiAnVGFlZ3UnIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogMTQsXG4gICAgbGFiZWw6ICdFdXJvcGUnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAxNSxcbiAgICAgICAgbGFiZWw6ICdGcmFuY2UnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHsgdmFsdWU6IDE2LCBsYWJlbDogJ1BhcmlzJyB9LFxuICAgICAgICAgIHsgdmFsdWU6IDE3LCBsYWJlbDogJ01hcnNlaWxsZScgfSxcbiAgICAgICAgICB7IHZhbHVlOiAxOCwgbGFiZWw6ICdMeW9uJyB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6IDE5LFxuICAgICAgICBsYWJlbDogJ1VLJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7IHZhbHVlOiAyMCwgbGFiZWw6ICdMb25kb24nIH0sXG4gICAgICAgICAgeyB2YWx1ZTogMjEsIGxhYmVsOiAnQmlybWluZ2hhbScgfSxcbiAgICAgICAgICB7IHZhbHVlOiAyMiwgbGFiZWw6ICdNYW5jaGVzdGVyJyB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgdmFsdWU6IDIzLFxuICAgIGxhYmVsOiAnTm9ydGggQW1lcmljYScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6IDI0LFxuICAgICAgICBsYWJlbDogJ1VTJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7IHZhbHVlOiAyNSwgbGFiZWw6ICdOZXcgWW9yaycgfSxcbiAgICAgICAgICB7IHZhbHVlOiAyNiwgbGFiZWw6ICdMb3MgQW5nZWxlcycgfSxcbiAgICAgICAgICB7IHZhbHVlOiAyNywgbGFiZWw6ICdXYXNoaW5ndG9uJyB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6IDI4LFxuICAgICAgICBsYWJlbDogJ0NhbmFkYScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAgeyB2YWx1ZTogMjksIGxhYmVsOiAnVG9yb250bycgfSxcbiAgICAgICAgICB7IHZhbHVlOiAzMCwgbGFiZWw6ICdNb250cmVhbCcgfSxcbiAgICAgICAgICB7IHZhbHVlOiAzMSwgbGFiZWw6ICdPdHRhd2EnIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG5jb25zdCBnZXRUYWdzID0gKGRhdGE6IFRhZ1tdKSA9PiB7XG4gIHJldHVybiBkYXRhLm1hcCgoaXRlbSkgPT4gaXRlbS50ZXh0KVxufVxuY29uc3QgZ2V0VG9wTGV2ZWxUYWdzID0gKGRhdGE6IFRhZ1tdKSA9PiB7XG4gIGNvbnN0IHNldDogU2V0PHN0cmluZz4gPSBuZXcgU2V0KClcbiAgZm9yIChjb25zdCBkYXR1bSBvZiBkYXRhKSB7XG4gICAgbGV0IHBhcmVudCA9IGRhdHVtLm5vZGU/LnBhcmVudFxuICAgIHdoaWxlIChwYXJlbnQgJiYgcGFyZW50LmxldmVsICE9PSAxKSB7XG4gICAgICBwYXJlbnQgPSBwYXJlbnQucGFyZW50XG4gICAgfVxuICAgIGNvbnN0IGxhYmVsID0gcGFyZW50Py5kYXRhPy5sYWJlbFxuICAgIGxhYmVsICYmIHNldC5hZGQobGFiZWwpXG4gIH1cbiAgcmV0dXJuIFsuLi5zZXRdXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/custom-tag.vue)_

vue

```
<template>
  <div class="m-4">
    <p>Using slots allows for more flexible control over the display.</p>
    <el-cascader :options="options" :props="props" clearable>
      <template #tag="{ data }">
        <el-tag
          v-for="(item, index) in getTags(data)"
          :key="item"
          :color="index % 2 === 0 ? '#FFDE0A' : ''"
        >
          {{ item }}
        </el-tag>
      </template>
    </el-cascader>
    <p>Display top-level tags only</p>
    <el-cascader :options="options" :props="props" clearable>
      <template #tag="{ data }">
        <el-tag v-for="item in getTopLevelTags(data)" :key="item">
          {{ item }}
        </el-tag>
      </template>
    </el-cascader>
  </div>
</template>

<script lang="ts" setup>
import type { Tag } from 'element-plus'

const props = { multiple: true }
const options = [
  {
    value: 1,
    label: 'Asia',
    children: [
      {
        value: 2,
        label: 'China',
        children: [
          { value: 3, label: 'Beijing' },
          { value: 4, label: 'Shanghai' },
          { value: 5, label: 'Hangzhou' },
        ],
      },
      {
        value: 6,
        label: 'Japan',
        children: [
          { value: 7, label: 'Tokyo' },
          { value: 8, label: 'Osaka' },
          { value: 9, label: 'Kyoto' },
        ],
      },
      {
        value: 10,
        label: 'Korea',
        children: [
          { value: 11, label: 'Seoul' },
          { value: 12, label: 'Busan' },
          { value: 13, label: 'Taegu' },
        ],
      },
    ],
  },
  {
    value: 14,
    label: 'Europe',
    children: [
      {
        value: 15,
        label: 'France',
        children: [
          { value: 16, label: 'Paris' },
          { value: 17, label: 'Marseille' },
          { value: 18, label: 'Lyon' },
        ],
      },
      {
        value: 19,
        label: 'UK',
        children: [
          { value: 20, label: 'London' },
          { value: 21, label: 'Birmingham' },
          { value: 22, label: 'Manchester' },
        ],
      },
    ],
  },
  {
    value: 23,
    label: 'North America',
    children: [
      {
        value: 24,
        label: 'US',
        children: [
          { value: 25, label: 'New York' },
          { value: 26, label: 'Los Angeles' },
          { value: 27, label: 'Washington' },
        ],
      },
      {
        value: 28,
        label: 'Canada',
        children: [
          { value: 29, label: 'Toronto' },
          { value: 30, label: 'Montreal' },
          { value: 31, label: 'Ottawa' },
        ],
      },
    ],
  },
]
const getTags = (data: Tag[]) => {
  return data.map((item) => item.text)
}
const getTopLevelTags = (data: Tag[]) => {
  const set: Set<string> = new Set()
  for (const datum of data) {
    let parent = datum.node?.parent
    while (parent && parent.level !== 1) {
      parent = parent.parent
    }
    const label = parent?.data?.label
    label && set.add(label)
  }
  return [...set]
}
</script>
```

隐藏源代码

## 已勾选项显示策略 2.10.5 [​](#已勾选项显示策略)

控制在多选模式下已选值的显示方式。

在多选模式下，你可以使用 `show-checked-strategy` 来控制已选值的显示方式。 默认策略为 `child`，即显示所有已选中的子节点。 `parent` 策略仅在其所有子节点都被选中时显示父节点。

Strategy: child (default, show all selected child nodes)

Strategy: parent (show only parent nodes when all children are selected)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+U3RyYXRlZ3k6IGNoaWxkIChkZWZhdWx0LCBzaG93IGFsbCBzZWxlY3RlZCBjaGlsZCBub2Rlcyk8L3A+XG4gICAgPGVsLWNhc2NhZGVyXG4gICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgICBzaG93LWNoZWNrZWQtc3RyYXRlZ3k9XCJjaGlsZFwiXG4gICAgICBjbGVhcmFibGVcbiAgICAgIEBjaGFuZ2U9XCJoYW5kbGVDaGFuZ2UxXCJcbiAgICAvPlxuICA8L2Rpdj5cblxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+XG4gICAgICBTdHJhdGVneTogcGFyZW50IChzaG93IG9ubHkgcGFyZW50IG5vZGVzIHdoZW4gYWxsIGNoaWxkcmVuIGFyZSBzZWxlY3RlZClcbiAgICA8L3A+XG4gICAgPGVsLWNhc2NhZGVyXG4gICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgICBzaG93LWNoZWNrZWQtc3RyYXRlZ3k9XCJwYXJlbnRcIlxuICAgICAgY2xlYXJhYmxlXG4gICAgICBAY2hhbmdlPVwiaGFuZGxlQ2hhbmdlMlwiXG4gICAgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZTEgPSByZWYoW10pXG5jb25zdCB2YWx1ZTIgPSByZWYoW10pXG5jb25zdCBwcm9wcyA9IHtcbiAgbXVsdGlwbGU6IHRydWUsXG59XG5cbmNvbnN0IGhhbmRsZUNoYW5nZTEgPSAodmFsdWUpID0+IHtcbiAgY29uc29sZS5sb2coJ0NoaWxkIHN0cmF0ZWd5OicsIHZhbHVlKVxufVxuXG5jb25zdCBoYW5kbGVDaGFuZ2UyID0gKHZhbHVlKSA9PiB7XG4gIGNvbnNvbGUubG9nKCdQYXJlbnQgc3RyYXRlZ3k6JywgdmFsdWUpXG59XG5cbmNvbnN0IG9wdGlvbnMgPSBbXG4gIHtcbiAgICB2YWx1ZTogJ2d1aWRlJyxcbiAgICBsYWJlbDogJ0d1aWRlJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2Rpc2NpcGxpbmVzJyxcbiAgICAgICAgbGFiZWw6ICdEaXNjaXBsaW5lcycsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjb25zaXN0ZW5jeScsXG4gICAgICAgICAgICBsYWJlbDogJ0NvbnNpc3RlbmN5JyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICduYXZpZ2F0aW9uJyxcbiAgICAgICAgbGFiZWw6ICdOYXZpZ2F0aW9uJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3NpZGUgbmF2JyxcbiAgICAgICAgICAgIGxhYmVsOiAnU2lkZSBOYXZpZ2F0aW9uJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdjb21wb25lbnQnLFxuICAgIGxhYmVsOiAnQ29tcG9uZW50JyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2Jhc2ljJyxcbiAgICAgICAgbGFiZWw6ICdCYXNpYycsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdsYXlvdXQnLFxuICAgICAgICAgICAgbGFiZWw6ICdMYXlvdXQnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2Zvcm0nLFxuICAgICAgICBsYWJlbDogJ0Zvcm0nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAncmFkaW8nLFxuICAgICAgICAgICAgbGFiZWw6ICdSYWRpbycsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAncmVzb3VyY2UnLFxuICAgIGxhYmVsOiAnUmVzb3VyY2UnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnYXh1cmUnLFxuICAgICAgICBsYWJlbDogJ0F4dXJlIENvbXBvbmVudHMnLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/show-checked-strategy.vue)_

vue

```
<template>
  <div class="m-4">
    <p>Strategy: child (default, show all selected child nodes)</p>
    <el-cascader
      v-model="value1"
      :options="options"
      :props="props"
      show-checked-strategy="child"
      clearable
      @change="handleChange1"
    />
  </div>

  <div class="m-4">
    <p>
      Strategy: parent (show only parent nodes when all children are selected)
    </p>
    <el-cascader
      v-model="value2"
      :options="options"
      :props="props"
      show-checked-strategy="parent"
      clearable
      @change="handleChange2"
    />
  </div>
</template>

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

const value1 = ref([])
const value2 = ref([])
const props = {
  multiple: true,
}

const handleChange1 = (value) => {
  console.log('Child strategy:', value)
}

const handleChange2 = (value) => {
  console.log('Parent strategy:', value)
}

const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
        ],
      },
    ],
  },
  {
    value: 'component',
    label: 'Component',
    children: [
      {
        value: 'basic',
        label: 'Basic',
        children: [
          {
            value: 'layout',
            label: 'Layout',
          },
        ],
      },
      {
        value: 'form',
        label: 'Form',
        children: [
          {
            value: 'radio',
            label: 'Radio',
          },
        ],
      },
    ],
  },
  {
    value: 'resource',
    label: 'Resource',
    children: [
      {
        value: 'axure',
        label: 'Axure Components',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 点击选中节点 2.10.5 [​](#点击选中节点)

只使用 `multiple` 或 `checkStrictly` 属性。

你可以添加 `checkOnClickNode`，使节点本身也能被点击（不仅限于前缀图标）。 通过 `showPrefix` 来切换前缀的显示与隐藏。 :::tip 添加 `checkOnClickLeaf` 属性可以仅勾选叶子节点（最末级子节点），该功能默认启用。 :::

hide prefixshow prefix

checkStrictly | Single mode

Multiple mode

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LWNvbCBpdGVtcy1jZW50ZXJcIj5cbiAgICA8ZWwtc3dpdGNoXG4gICAgICB2LW1vZGVsPVwic2hvd1ByZWZpeFwiXG4gICAgICBhY3RpdmUtdGV4dD1cInNob3cgcHJlZml4XCJcbiAgICAgIGluYWN0aXZlLXRleHQ9XCJoaWRlIHByZWZpeFwiXG4gICAgLz5cbiAgICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXBcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJtLTRcIj5cbiAgICAgICAgPHA+Y2hlY2tTdHJpY3RseSB8IFNpbmdsZSBtb2RlPC9wPlxuICAgICAgICA8ZWwtY2FzY2FkZXJcbiAgICAgICAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgICAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICAgICAgOnByb3BzPVwicHJvcHMxXCJcbiAgICAgICAgICBjbGVhcmFibGVcbiAgICAgICAgLz5cbiAgICAgIDwvZGl2PlxuICAgICAgPGRpdiBjbGFzcz1cIm0tNFwiPlxuICAgICAgICA8cD5NdWx0aXBsZSBtb2RlPC9wPlxuICAgICAgICA8ZWwtY2FzY2FkZXJcbiAgICAgICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgICAgICBzaG93LWNoZWNrZWQtc3RyYXRlZ3k9XCJwYXJlbnRcIlxuICAgICAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICAgICAgOnByb3BzPVwicHJvcHMyXCJcbiAgICAgICAgICBjbGVhcmFibGVcbiAgICAgICAgLz5cbiAgICAgIDwvZGl2PlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBjb21wdXRlZCwgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZigpXG5jb25zdCB2YWx1ZTIgPSByZWYoKVxuY29uc3Qgc2hvd1ByZWZpeCA9IHJlZih0cnVlKVxuXG5jb25zdCBwcm9wczEgPSBjb21wdXRlZCgoKSA9PiAoe1xuICBzaG93UHJlZml4OiBzaG93UHJlZml4LnZhbHVlLFxuICBjaGVja1N0cmljdGx5OiB0cnVlLFxuICBjaGVja09uQ2xpY2tOb2RlOiB0cnVlLFxufSkpXG5jb25zdCBwcm9wczIgPSBjb21wdXRlZCgoKSA9PiAoe1xuICBzaG93UHJlZml4OiBzaG93UHJlZml4LnZhbHVlLFxuICBtdWx0aXBsZTogdHJ1ZSxcbiAgY2hlY2tPbkNsaWNrTm9kZTogdHJ1ZSxcbn0pKVxuXG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6ICdndWlkZScsXG4gICAgbGFiZWw6ICdHdWlkZScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkaXNjaXBsaW5lcycsXG4gICAgICAgIGxhYmVsOiAnRGlzY2lwbGluZXMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnY29uc2lzdGVuY3knLFxuICAgICAgICAgICAgbGFiZWw6ICdDb25zaXN0ZW5jeScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnbmF2aWdhdGlvbicsXG4gICAgICAgIGxhYmVsOiAnTmF2aWdhdGlvbicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdzaWRlIG5hdicsXG4gICAgICAgICAgICBsYWJlbDogJ1NpZGUgTmF2aWdhdGlvbicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnY29tcG9uZW50JyxcbiAgICBsYWJlbDogJ0NvbXBvbmVudCcsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdiYXNpYycsXG4gICAgICAgIGxhYmVsOiAnQmFzaWMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnbGF5b3V0JyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGF5b3V0JyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdmb3JtJyxcbiAgICAgICAgbGFiZWw6ICdGb3JtJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ3JhZGlvJyxcbiAgICAgICAgICAgIGxhYmVsOiAnUmFkaW8nLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ3Jlc291cmNlJyxcbiAgICBsYWJlbDogJ1Jlc291cmNlJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogJ2F4dXJlJyxcbiAgICAgICAgbGFiZWw6ICdBeHVyZSBDb21wb25lbnRzJyxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/check-on-click-node.vue)_

vue

```
<template>
  <div class="flex flex-col items-center">
    <el-switch
      v-model="showPrefix"
      active-text="show prefix"
      inactive-text="hide prefix"
    />
    <div class="flex flex-wrap">
      <div class="m-4">
        <p>checkStrictly | Single mode</p>
        <el-cascader
          v-model="value"
          :options="options"
          :props="props1"
          clearable
        />
      </div>
      <div class="m-4">
        <p>Multiple mode</p>
        <el-cascader
          v-model="value2"
          show-checked-strategy="parent"
          :options="options"
          :props="props2"
          clearable
        />
      </div>
    </div>
  </div>
</template>

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

const value = ref()
const value2 = ref()
const showPrefix = ref(true)

const props1 = computed(() => ({
  showPrefix: showPrefix.value,
  checkStrictly: true,
  checkOnClickNode: true,
}))
const props2 = computed(() => ({
  showPrefix: showPrefix.value,
  multiple: true,
  checkOnClickNode: true,
}))

const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
        ],
      },
    ],
  },
  {
    value: 'component',
    label: 'Component',
    children: [
      {
        value: 'basic',
        label: 'Basic',
        children: [
          {
            value: 'layout',
            label: 'Layout',
          },
        ],
      },
      {
        value: 'form',
        label: 'Form',
        children: [
          {
            value: 'radio',
            label: 'Radio',
          },
        ],
      },
    ],
  },
  {
    value: 'resource',
    label: 'Resource',
    children: [
      {
        value: 'axure',
        label: 'Axure Components',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 自定义头部与底部 2.10.5 [​](#自定义头部与底部)

你可以通过插槽来自定义下拉菜单的头部和底部。

使用插槽自定义内容。

Custom header content

Custom footer content

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiY2FzY2FkZXItY3VzdG9tLWhlYWRlci1mb290ZXJcIj5cbiAgICA8ZGl2PlxuICAgICAgPHA+Q3VzdG9tIGhlYWRlciBjb250ZW50PC9wPlxuICAgICAgPGVsLWNhc2NhZGVyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgICAgIHBvcHBlci1jbGFzcz1cImNhc2NhZGVyLWN1c3RvbS1oZWFkZXJcIlxuICAgICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgICAgIGNsZWFyYWJsZVxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI2hlYWRlcj5cbiAgICAgICAgICA8ZWwtY2hlY2tib3hcbiAgICAgICAgICAgIHYtbW9kZWw9XCJjaGVja0FsbFwiXG4gICAgICAgICAgICA6aW5kZXRlcm1pbmF0ZT1cImluZGV0ZXJtaW5hdGVcIlxuICAgICAgICAgICAgQGNoYW5nZT1cImhhbmRsZUNoZWNrQWxsXCJcbiAgICAgICAgICA+XG4gICAgICAgICAgICBBbGxcbiAgICAgICAgICA8L2VsLWNoZWNrYm94PlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1jYXNjYWRlcj5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2PlxuICAgICAgPHA+Q3VzdG9tIGZvb3RlciBjb250ZW50PC9wPlxuICAgICAgPGVsLWNhc2NhZGVyIHYtbW9kZWw9XCJ2YWx1ZVwiIDpvcHRpb25zPVwib3B0aW9uc1wiIDpwcm9wcz1cInByb3BzXCIgY2xlYXJhYmxlPlxuICAgICAgICA8dGVtcGxhdGUgI2Zvb3Rlcj5cbiAgICAgICAgICA8ZWwtYnV0dG9uIGxpbmsgc2l6ZT1cInNtYWxsXCIgQGNsaWNrPVwiaGFuZGxlQ2xlYXJcIj4gQ2xlYXIgPC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLWNhc2NhZGVyPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBjb21wdXRlZCwgcmVmLCB3YXRjaCB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBDYXNjYWRlck9wdGlvbiwgQ2hlY2tib3hWYWx1ZVR5cGUgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHByb3BzID0geyBtdWx0aXBsZTogdHJ1ZSB9XG5jb25zdCBjaGVja0FsbCA9IHJlZihmYWxzZSlcbmNvbnN0IGluZGV0ZXJtaW5hdGUgPSByZWYoZmFsc2UpXG5jb25zdCB2YWx1ZSA9IHJlZjxzdHJpbmdbXVtdPihbXSlcbmNvbnN0IG9wdGlvbnMgPSByZWYoW1xuICB7XG4gICAgdmFsdWU6ICdndWlkZScsXG4gICAgbGFiZWw6ICdHdWlkZScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdkaXNjaXBsaW5lcycsXG4gICAgICAgIGxhYmVsOiAnRGlzY2lwbGluZXMnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHsgdmFsdWU6ICdjb25zaXN0ZW5jeScsIGxhYmVsOiAnQ29uc2lzdGVuY3knIH0sXG4gICAgICAgICAgeyB2YWx1ZTogJ2ZlZWRiYWNrJywgbGFiZWw6ICdGZWVkYmFjaycgfSxcbiAgICAgICAgICB7IHZhbHVlOiAnZWZmaWNpZW5jeScsIGxhYmVsOiAnRWZmaWNpZW5jeScgfSxcbiAgICAgICAgICB7IHZhbHVlOiAnY29udHJvbGxhYmlsaXR5JywgbGFiZWw6ICdDb250cm9sbGFiaWxpdHknIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dKVxuXG5jb25zdCBnZXRBbGxWYWx1ZVBhdGhzID0gY29tcHV0ZWQoKCkgPT4ge1xuICBjb25zdCByZXN1bHQ6IHN0cmluZ1tdW10gPSBbXVxuICBjb25zdCBxdWV1ZTogeyBub2RlOiBDYXNjYWRlck9wdGlvbjsgcGF0aDogc3RyaW5nW10gfVtdID0gb3B0aW9ucy52YWx1ZS5tYXAoXG4gICAgKG5vZGUpID0+ICh7IG5vZGUsIHBhdGg6IFtub2RlLnZhbHVlXSB9KVxuICApXG5cbiAgd2hpbGUgKHF1ZXVlLmxlbmd0aCA+IDApIHtcbiAgICBjb25zdCB7IG5vZGUsIHBhdGggfSA9IHF1ZXVlLnNoaWZ0KCkhXG4gICAgaWYgKG5vZGUuY2hpbGRyZW4/Lmxlbmd0aCkge1xuICAgICAgbm9kZS5jaGlsZHJlbi5mb3JFYWNoKChjaGlsZCkgPT4ge1xuICAgICAgICBxdWV1ZS5wdXNoKHsgbm9kZTogY2hpbGQsIHBhdGg6IFsuLi5wYXRoLCBjaGlsZC52YWx1ZSBhcyBzdHJpbmddIH0pXG4gICAgICB9KVxuICAgIH0gZWxzZSB7XG4gICAgICByZXN1bHQucHVzaChwYXRoKVxuICAgIH1cbiAgfVxuICByZXR1cm4gcmVzdWx0XG59KVxuXG53YXRjaCh2YWx1ZSwgKHZhbCkgPT4ge1xuICBpZiAodmFsLmxlbmd0aCA9PT0gMCkge1xuICAgIGNoZWNrQWxsLnZhbHVlID0gZmFsc2VcbiAgICBpbmRldGVybWluYXRlLnZhbHVlID0gZmFsc2VcbiAgfSBlbHNlIGlmICh2YWwubGVuZ3RoID09PSBnZXRBbGxWYWx1ZVBhdGhzLnZhbHVlLmxlbmd0aCkge1xuICAgIGNoZWNrQWxsLnZhbHVlID0gdHJ1ZVxuICAgIGluZGV0ZXJtaW5hdGUudmFsdWUgPSBmYWxzZVxuICB9IGVsc2Uge1xuICAgIGluZGV0ZXJtaW5hdGUudmFsdWUgPSB0cnVlXG4gIH1cbn0pXG5cbmNvbnN0IGhhbmRsZUNoZWNrQWxsID0gKHZhbDogQ2hlY2tib3hWYWx1ZVR5cGUpID0+IHtcbiAgaW5kZXRlcm1pbmF0ZS52YWx1ZSA9IGZhbHNlXG4gIHZhbHVlLnZhbHVlID0gdmFsID8gZ2V0QWxsVmFsdWVQYXRocy52YWx1ZSA6IFtdXG59XG5cbmNvbnN0IGhhbmRsZUNsZWFyID0gKCkgPT4ge1xuICB2YWx1ZS52YWx1ZSA9IFtdXG59XG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5jYXNjYWRlci1jdXN0b20taGVhZGVyLWZvb3RlciB7XG4gIGRpc3BsYXk6IGZsZXg7XG59XG5cbi5jYXNjYWRlci1jdXN0b20taGVhZGVyLWZvb3RlciA+IGRpdiB7XG4gIGZsZXg6IDE7XG4gIHRleHQtYWxpZ246IGNlbnRlcjtcbn1cblxuLmNhc2NhZGVyLWN1c3RvbS1oZWFkZXItZm9vdGVyID4gZGl2Om5vdCg6bGFzdC1jaGlsZCkge1xuICBib3JkZXItcmlnaHQ6IDFweCBzb2xpZCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xufVxuXG4uY2FzY2FkZXItY3VzdG9tLWhlYWRlciAuZWwtY2hlY2tib3gge1xuICBkaXNwbGF5OiBmbGV4O1xuICBoZWlnaHQ6IHVuc2V0O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/custom-header-footer.vue)_

vue

```
<template>
  <div class="cascader-custom-header-footer">
    <div>
      <p>Custom header content</p>
      <el-cascader
        v-model="value"
        popper-class="cascader-custom-header"
        :options="options"
        :props="props"
        clearable
      >
        <template #header>
          <el-checkbox
            v-model="checkAll"
            :indeterminate="indeterminate"
            @change="handleCheckAll"
          >
            All
          </el-checkbox>
        </template>
      </el-cascader>
    </div>
    <div>
      <p>Custom footer content</p>
      <el-cascader v-model="value" :options="options" :props="props" clearable>
        <template #footer>
          <el-button link size="small" @click="handleClear"> Clear </el-button>
        </template>
      </el-cascader>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref, watch } from 'vue'

import type { CascaderOption, CheckboxValueType } from 'element-plus'

const props = { multiple: true }
const checkAll = ref(false)
const indeterminate = ref(false)
const value = ref<string[][]>([])
const options = ref([
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          { value: 'consistency', label: 'Consistency' },
          { value: 'feedback', label: 'Feedback' },
          { value: 'efficiency', label: 'Efficiency' },
          { value: 'controllability', label: 'Controllability' },
        ],
      },
    ],
  },
])

const getAllValuePaths = computed(() => {
  const result: string[][] = []
  const queue: { node: CascaderOption; path: string[] }[] = options.value.map(
    (node) => ({ node, path: [node.value] })
  )

  while (queue.length > 0) {
    const { node, path } = queue.shift()!
    if (node.children?.length) {
      node.children.forEach((child) => {
        queue.push({ node: child, path: [...path, child.value as string] })
      })
    } else {
      result.push(path)
    }
  }
  return result
})

watch(value, (val) => {
  if (val.length === 0) {
    checkAll.value = false
    indeterminate.value = false
  } else if (val.length === getAllValuePaths.value.length) {
    checkAll.value = true
    indeterminate.value = false
  } else {
    indeterminate.value = true
  }
})

const handleCheckAll = (val: CheckboxValueType) => {
  indeterminate.value = false
  value.value = val ? getAllValuePaths.value : []
}

const handleClear = () => {
  value.value = []
}
</script>

<style scoped>
.cascader-custom-header-footer {
  display: flex;
}

.cascader-custom-header-footer > div {
  flex: 1;
  text-align: center;
}

.cascader-custom-header-footer > div:not(:last-child) {
  border-right: 1px solid var(--el-border-color);
}

.cascader-custom-header .el-checkbox {
  display: flex;
  height: unset;
}
</style>
```

隐藏源代码

## 虚拟滚动 2.14.0 [​](#虚拟滚动)

当处理大量数据时，您可以启用虚拟滚动以提高性能。

将 `virtual-scroll` 设置为 `true` 以启用虚拟滚动。 您还可以使用 `height` 自定义菜单高度，并使用 `item-size` 自定义节点高度。 默认高度为 204px，默认节点大小为 34px。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FzY2FkZXJcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgOmZpbHRlci1tZXRob2Q9XCJmaWx0ZXJNZXRob2RcIlxuICAgIGZpbHRlcmFibGVcbiAgICB2aXJ0dWFsLXNjcm9sbFxuICAgIGNsZWFyYWJsZVxuICAgIHBsYWNlaG9sZGVyPVwiU2VsZWN0IHdpdGggbGFyZ2UgZGF0YVwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IENhc2NhZGVyTm9kZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuaW50ZXJmYWNlIENhc2NhZGVyRXhhbXBsZU9wdGlvbiB7XG4gIHZhbHVlOiBzdHJpbmdcbiAgbGFiZWw6IHN0cmluZ1xuICBjaGlsZHJlbj86IENhc2NhZGVyRXhhbXBsZU9wdGlvbltdXG59XG5cbmNvbnN0IHZhbHVlID0gcmVmPHN0cmluZ1tdPihbXSlcblxuY29uc3QgZmlsdGVyTWV0aG9kID0gKG5vZGU6IENhc2NhZGVyTm9kZSwga2V5d29yZDogc3RyaW5nKSA9PiB7XG4gIHJldHVybiBub2RlLnRleHQudG9Mb3dlckNhc2UoKS5pbmNsdWRlcyhrZXl3b3JkLnRvTG93ZXJDYXNlKCkpXG59XG5cbmNvbnN0IGdlbmVyYXRlT3B0aW9ucyA9IChjb3VudDogbnVtYmVyKTogQ2FzY2FkZXJFeGFtcGxlT3B0aW9uW10gPT4ge1xuICByZXR1cm4gQXJyYXkuZnJvbSh7IGxlbmd0aDogY291bnQgfSkubWFwKChfLCBpbmRleCkgPT4gKHtcbiAgICB2YWx1ZTogYG9wdGlvbi0ke2luZGV4fWAsXG4gICAgbGFiZWw6IGBPcHRpb24gJHtpbmRleCArIDF9YCxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogYGNoaWxkLSR7aW5kZXh9LTFgLFxuICAgICAgICBsYWJlbDogYENoaWxkICR7aW5kZXggKyAxfS0xYCxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogYGdyYW5kY2hpbGQtJHtpbmRleH0tMS0xYCxcbiAgICAgICAgICAgIGxhYmVsOiBgR3JhbmRjaGlsZCAke2luZGV4ICsgMX0tMS0xYCxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiBgZ3JhbmRjaGlsZC0ke2luZGV4fS0xLTJgLFxuICAgICAgICAgICAgbGFiZWw6IGBHcmFuZGNoaWxkICR7aW5kZXggKyAxfS0xLTJgLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogYGNoaWxkLSR7aW5kZXh9LTJgLFxuICAgICAgICBsYWJlbDogYENoaWxkICR7aW5kZXggKyAxfS0yYCxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSkpXG59XG5cbmNvbnN0IG9wdGlvbnMgPSByZWY8Q2FzY2FkZXJFeGFtcGxlT3B0aW9uW10+KGdlbmVyYXRlT3B0aW9ucygyMDAwMCkpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/virtual-scroll.vue)_

vue

```
<template>
  <el-cascader
    v-model="value"
    :options="options"
    :filter-method="filterMethod"
    filterable
    virtual-scroll
    clearable
    placeholder="Select with large data"
  />
</template>

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

import type { CascaderNode } from 'element-plus'

interface CascaderExampleOption {
  value: string
  label: string
  children?: CascaderExampleOption[]
}

const value = ref<string[]>([])

const filterMethod = (node: CascaderNode, keyword: string) => {
  return node.text.toLowerCase().includes(keyword.toLowerCase())
}

const generateOptions = (count: number): CascaderExampleOption[] => {
  return Array.from({ length: count }).map((_, index) => ({
    value: `option-${index}`,
    label: `Option ${index + 1}`,
    children: [
      {
        value: `child-${index}-1`,
        label: `Child ${index + 1}-1`,
        children: [
          {
            value: `grandchild-${index}-1-1`,
            label: `Grandchild ${index + 1}-1-1`,
          },
          {
            value: `grandchild-${index}-1-2`,
            label: `Grandchild ${index + 1}-1-2`,
          },
        ],
      },
      {
        value: `child-${index}-2`,
        label: `Child ${index + 1}-2`,
      },
    ],
  }))
}

const options = ref<CascaderExampleOption[]>(generateOptions(20000))
</script>
```

隐藏源代码

## 自定义建议面板宽度 2.14.0 [​](#自定义建议面板宽度)

建议面板（筛选时）的宽度默认会根据匹配到的选项中的最大宽度自动计算。 如果您通过 `suggestion-item` 插槽自定义建议选项，选项中显示的文本很可能不等于 `label` 的值，从而导致计算错误。 在这种情况下，您可以使用 `fit-input-width` 属性来固定其宽度。 当值为 `number` 时，宽度为固定的具体像素值。

TIP

`fit-input-width` 属性仅控制搜索时建议面板的宽度，不影响默认的级联面板。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTQgaXRlbXMtY2VudGVyXCI+XG4gICAgPGVsLWNhc2NhZGVyXG4gICAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiRGVmYXVsdCBleHBhbmRpbmcgcGFuZWxcIlxuICAgICAgZmlsdGVyYWJsZVxuICAgIC8+XG5cbiAgICA8ZWwtY2FzY2FkZXJcbiAgICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJGaXQgaW5wdXQgd2lkdGhcIlxuICAgICAgZmlsdGVyYWJsZVxuICAgICAgZml0LWlucHV0LXdpZHRoXG4gICAgLz5cblxuICAgIDxlbC1jYXNjYWRlclxuICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICBwbGFjZWhvbGRlcj1cIkZpeGVkIHdpZHRoICg0MDBweClcIlxuICAgICAgZmlsdGVyYWJsZVxuICAgICAgOmZpdC1pbnB1dC13aWR0aD1cIjQwMFwiXG4gICAgPlxuICAgICAgPHRlbXBsYXRlICNzdWdnZXN0aW9uLWl0ZW09XCJ7IGl0ZW0gfVwiPlxuICAgICAgICA8ZGl2Pnt7IGl0ZW0udGV4dCB9fSAoQ3VzdG9tIGNvbnRlbnQgdGhhdCBpcyB2ZXJ5IGxvbmcpPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtY2FzY2FkZXI+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoKVxuY29uc3Qgb3B0aW9ucyA9IFtcbiAge1xuICAgIHZhbHVlOiAnZ3VpZGUnLFxuICAgIGxhYmVsOiAnR3VpZGUnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnZGlzY2lwbGluZXMnLFxuICAgICAgICBsYWJlbDogJ0Rpc2NpcGxpbmVzJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJ2NvbnNpc3RlbmN5JyxcbiAgICAgICAgICAgIGxhYmVsOiAnQ29uc2lzdGVuY3knLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdmZWVkYmFjaycsXG4gICAgICAgICAgICBsYWJlbDogJ0ZlZWRiYWNrJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnZWZmaWNpZW5jeScsXG4gICAgICAgICAgICBsYWJlbDogJ0VmZmljaWVuY3knLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICdjb250cm9sbGFiaWxpdHknLFxuICAgICAgICAgICAgbGFiZWw6ICdDb250cm9sbGFiaWxpdHknLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ25hdmlnYXRpb24nLFxuICAgICAgICBsYWJlbDogJ05hdmlnYXRpb24nLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnc2lkZSBuYXYnLFxuICAgICAgICAgICAgbGFiZWw6ICdTaWRlIE5hdmlnYXRpb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICd0b3AgbmF2JyxcbiAgICAgICAgICAgIGxhYmVsOiAnVG9wIE5hdmlnYXRpb24nLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/cascader/fit-input-width.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-4 items-center">
    <el-cascader
      v-model="value"
      :options="options"
      placeholder="Default expanding panel"
      filterable
    />

    <el-cascader
      v-model="value"
      :options="options"
      placeholder="Fit input width"
      filterable
      fit-input-width
    />

    <el-cascader
      v-model="value"
      :options="options"
      placeholder="Fixed width (400px)"
      filterable
      :fit-input-width="400"
    >
      <template #suggestion-item="{ item }">
        <div>{{ item.text }} (Custom content that is very long)</div>
      </template>
    </el-cascader>
  </div>
</template>

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

const value = ref()
const options = [
  {
    value: 'guide',
    label: 'Guide',
    children: [
      {
        value: 'disciplines',
        label: 'Disciplines',
        children: [
          {
            value: 'consistency',
            label: 'Consistency',
          },
          {
            value: 'feedback',
            label: 'Feedback',
          },
          {
            value: 'efficiency',
            label: 'Efficiency',
          },
          {
            value: 'controllability',
            label: 'Controllability',
          },
        ],
      },
      {
        value: 'navigation',
        label: 'Navigation',
        children: [
          {
            value: 'side nav',
            label: 'Side Navigation',
          },
          {
            value: 'top nav',
            label: 'Top Navigation',
          },
        ],
      },
    ],
  },
]
</script>
```

隐藏源代码

## Cascader API [​](#cascader-api)

### Cascader Attributes [​](#cascader-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `string` / `number` /`array` | — |
| options | 选项的数据源， `value` 和 `label` 可以通过 `CascaderProps` 自定义. | `array` | — |
| [props](#cascaderprops) | 配置选项, 请参阅下面 `CascaderProps` 表。 | `object` | — |
| size | 尺寸 | `enum` | — |
| placeholder | 输入框占位文本 | `string` | — |
| disabled | 是否禁用 | `boolean` | — |
| clearable | 是否支持清空选项 | `boolean` | — |
| clear-icon 2.11.0 | 自定义清除图标 | `string` / `object` | CircleClose |
| show-all-levels | 输入框中是否显示选中值的完整路径 | `boolean` | true |
| collapse-tags | 多选模式下是否折叠Tag | `boolean` | — |
| collapse-tags-tooltip | 当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此属性，`collapse-tags`属性必须设定为 true | `boolean` | false |
| max-collapse-tags-tooltip-height 2.10.2 | collapse tags 的最大高度 | `string` / `number` | — |
| separator | 用于分隔选项的字符 | `string` | ' / ' |
| filterable | 该选项是否可以被搜索 | `boolean` | — |
| filter-method | 自定义搜索逻辑，第一个参数是`node`，第二个参数是`keyword`，返回的布尔值表示是否保留该选项 | `Function` | — |
| debounce | 搜索关键词正在输入时的去抖延迟，单位为毫秒 | `number` | 300 |
| before-filter | 过滤函数调用前，所要调用的钩子函数，该函数接收要过滤的值作为参数。 如果该函数的返回值是 `false` 或者是一个被拒绝的 `Promise`，那么接下来的过滤逻辑便不会执行。 | `Function` | — |
| popper-class | Cascader 下拉菜单和标签提示的自定义类名 | `string` | '' |
| popper-style | Cascader 下拉菜单和标签提示的自定义样式 | `string` / `object` | — |
| teleported | 弹层是否使用 teleport | `boolean` | true |
| effect 2.10.5 | tooltip 主题，内置了 `dark` / `light` 两种 | `enum` / `string` | light |
| tag-type | 标签类型 | `enum` | info |
| tag-effect 2.7.8 | tag effect | `enum` | light |
| validate-event | 输入时是否触发表单的校验 | `boolean` | true |
| max-collapse-tags 2.3.10 | 需要显示的 Tag 的最大数量 要使用此功能，`collapse-tags`的值必须为true | `number` | 1 |
| empty-values 2.7.0 | 组件的空值配置， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `array` | — |
| value-on-clear 2.7.0 | 清空选项的值， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `string` / `number` / `boolean` / `Function` | — |
| persistent 2.7.8 | 当下拉框未被激活并且`persistent`设置为`false`，下拉框容器会被删除。 | `boolean` | true |
| fallback-placements 2.8.1 | Tooltip 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | `array` | — |
| placement 2.8.1 | 下拉框出现的位置 | `enum` | bottom-start |
| popper-append-to-body deprecated | 是否将弹出的内容直接插入到 body 元素。 在弹出内容的边框定位出现问题时，可将该属性设置为 false | `boolean` | true |
| show-checked-strategy 2.10.5 | 多选模式下已选节点的展示策略。 当你想让显示更简洁时，使用 `parent`。 当你想显示每个子项时，使用 `child`。 | `enum` | child |
| virtual-scroll 2.14.0 | 是否为大数据启用虚拟滚动 | `boolean` | false |
| fit-input-width 2.14.0 | 建议面板的宽度是否与输入框一致；如果值为 `number`，则宽度为固定值。 | `boolean` / `number` | false |
| item-size 2.14.0 | 虚拟滚动的节点高度 (px) | `number` | 34 |
| height 2.14.0 | 虚拟滚动的菜单高度 (px) | `number` | 204 |

### Cascader Events [​](#cascader-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 当绑定值变化时触发的事件 | `Function` |
| expand-change | 当展开节点发生变化时触发 | `Function` |
| blur | 当失去焦点时触发 | `Function` |
| focus | 当获得焦点时触发 | `Function` |
| clear 2.7.7 | 可清空的单选模式下用户点击清空按钮时触发 | `Function` |
| visible-change | 下拉框出现/隐藏时触发 | `Function` |
| remove-tag | 在多选模式下，移除Tag时触发 | `Function` |

### Cascader Slots [​](#cascader-slots)

| 插槽名 | 说明 | Type |
| --- | --- | --- |
| default | 自定义备选项的节点内容，分别为当前节点的 Node 对象和数据 | `object` |
| empty | 无匹配选项时的内容 | — |
| prefix 2.9.4 | 输入框头部内容 | — |
| suggestion-item 2.9.5 | 搜索时自定义建议项内容 | `object` |
| tag 2.10.3 | 自定义tag样式 | `object` |
| header 2.10.5 | 下拉列表顶部的内容 | — |
| footer 2.10.5 | 下拉列表底部的内容 | — |

### Cascader Exposes [​](#cascader-exposes)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| getCheckedNodes | 获取一个当前选中节点的数组。(仅仅是传单) 是否只返回叶选中的节点，默认是 `false` | `Function` |
| cascaderPanelRef | cascader 面板的 ref | `object` |
| togglePopperVisible 2.2.31 | 切换 popper 可见状态 | `Function` |
| contentRef | cascader 内容的 ref | `object` |
| presentText 2.8.4 | 选中的内容文本 | `object` |
| focus 2.11.8 | 使 input 获取焦点 | `Function` |
| blur 2.11.8 | 使 input 失去焦点 | `Function` |

## CascaderPanel API [​](#cascaderpanel-api)

### CascaderPanel Attributes [​](#cascaderpanel-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `string`/`number`/`array` | — |
| options | 选项的数据源， `value` 和 `label` 可以通过 `CascaderProps` 自定义. | `array` | — |
| [props](#cascaderprops) | 配置选项, 请参阅下面 `CascaderProps` 表。 | `object` | — |
| virtual-scroll 2.14.0 | 是否为大数据启用虚拟滚动 | `boolean` | false |
| item-size 2.14.0 | 虚拟滚动的节点高度 (px) | `number` | 34 |
| height 2.14.0 | 虚拟滚动的菜单高度 (px) | `number` | 204 |

### CascaderPanel Events [​](#cascaderpanel-events)

| 方法名 | Description | Type |
| --- | --- | --- |
| change | 当选中节点变化时触发 | `Function` |
| update:modelValue | 当绑定值变化时触发的事件 | `Function` |
| expand-change | 当展开节点发生变化时触发 | `Function` |
| close | 面板的关闭事件，提供给 Cascader 以便做更好的判断。 | `Function` |

### CascaderPanel Slots [​](#cascaderpanel-slots)

| 事件名 | 说明 | Type |
| --- | --- | --- |
| default | 下级节点的自定义内容，它们分别是当前节点对象和节点数据。 | `object` |
| empty 2.8.3 | 没有数据时面板的内容。 | — |

### CascaderPanel Exposes [​](#cascaderpanel-exposes)

| 属性名 | 说明 | Type |
| --- | --- | --- |
| getCheckedNodes | 获取一个当前选中节点的数组。(仅仅是传单) 是否只返回叶选中的节点，默认是 `false` | `Function` |
| clearCheckedNodes | 清空选中的节点 | `Function` |

## CascaderProps [​](#cascaderprops)

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| expandTrigger | 次级菜单的展开方式 | `enum` | click |
| multiple | 是否多选 | `boolean` | false |
| checkStrictly | 是否严格的遵守父子节点不互相关联 | `boolean` | 你好 |
| emitPath | 在选中节点改变时，是否返回由该节点所在的各级菜单的值所组成的数组，若设置 false，则只返回该节点的值 | `boolean` | true |
| lazy | 是否动态加载子节点，需与 lazyLoad 方法结合使用 | `boolean` | 你好 |
| lazyLoad | 加载动态数据的方法，仅在 lazy 为 true 时有效 reject 参数在 2.11.5 版本及以上支持。 | `Function` | — |
| value | 指定选项的值为选项对象的某个属性值 | `string` | value |
| label | 指定选项标签为选项对象的某个属性值 | `string` | label |
| children | 指定选项的子选项为选项对象的某个属性值 | `string` | children |
| disabled | 指定选项的禁用为选项对象的某个属性值 | `string` | disabled |
| leaf | 指定选项的叶子节点的标志位为选项对象的某个属性值 | `string` | leaf |
| hoverThreshold | hover 时展开菜单的灵敏度阈值 | `number` | 500 |
| checkOnClickNode 2.10.5 | 点击节点时是否选中或取消选中该节点 | `boolean` | 你好 |
| checkOnClickLeaf 2.10.5 | 点击叶子节点（最后一级子节点）时，是否选中或取消选中该节点 | `boolean` | true |
| showPrefix 2.10.5 | 是否显示单选框或复选框的前缀（图标） | `boolean` | true |

## 类型声明 [​](#类型声明)

显示类型声明

ts

```
type CascaderNodeValue = string | number
type CascaderNodePathValue = CascaderNodeValue[]
type CascaderValue =
  | CascaderNodeValue
  | CascaderNodePathValue
  | (CascaderNodeValue | CascaderNodePathValue)[]

type Resolve = (data: any) => void

type ExpandTrigger = 'click' | 'hover'

type LazyLoad = (node: Node, resolve: Resolve, reject: () => void) => void

type isDisabled = (data: CascaderOption, node: Node) => boolean

type isLeaf = (data: CascaderOption, node: Node) => boolean

interface CascaderOption extends Record<string, unknown> {
  label?: string
  value?: CascaderNodeValue
  children?: CascaderOption[]
  disabled?: boolean
  leaf?: boolean
}

interface CascaderProps {
  expandTrigger?: ExpandTrigger
  multiple?: boolean
  checkStrictly?: boolean
  emitPath?: boolean
  lazy?: boolean
  lazyLoad?: LazyLoad
  value?: string
  label?: string
  children?: string
  disabled?: string | isDisabled
  leaf?: string | isLeaf
  hoverThreshold?: number
}

class Node {
  readonly uid: number
  readonly level: number
  readonly value: CascaderNodeValue
  readonly label: string
  readonly pathNodes: Node[]
  readonly pathValues: CascaderNodePathValue
  readonly pathLabels: string[]

  childrenData: ChildrenData
  children: Node[]
  text: string
  loaded: boolean
  /**
   * Is it checked
   *
   * @default false
   */
  checked: boolean
  /**
   * Used to indicate the intermediate state of unchecked and fully checked child nodes
   *
   * @default false
   */
  indeterminate: boolean
  /**
   * Loading Status
   *
   * @default false
   */
  loading: boolean

  // getter
  isDisabled: boolean
  isLeaf: boolean
  valueByOption: CascaderNodeValue | CascaderNodePathValue

  // method
  appendChild(childData: CascaderOption): Node
  calcText(allLevels: boolean, separator: string): string
  broadcast(): void
  emit(): void
  onParentCheck(checked: boolean): void
  onChildCheck(): void
  setCheckState(checked: boolean): void
  doCheck(checked: boolean): void
}

Node as CascaderNode
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/cascader) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/cascader.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/cascader.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/36978416?v=4&size=64)](https://github.com/SimonaliaChen)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)[![](https://avatars.githubusercontent.com/u/22659150?v=4&size=64)](https://github.com/ntnyq)[![](https://avatars.githubusercontent.com/u/30046649?v=4&size=64)](https://github.com/MrWeilian)[![](https://avatars.githubusercontent.com/u/109908413?v=4&size=64)](https://github.com/sleepyShen1989)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/16513587?v=4&size=64)](https://github.com/oooah)[![](https://avatars.githubusercontent.com/u/49630878?v=4&size=64)](https://github.com/a869246700)[![](https://avatars.githubusercontent.com/u/67454874?v=4&size=64)](https://github.com/nigiwen)[![](https://avatars.githubusercontent.com/u/163709439?v=4&size=64)](https://github.com/upthen)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/9692408?v=4&size=64)](https://github.com/DiamondYuan)[![](https://avatars.githubusercontent.com/u/63226115?v=4&size=64)](https://github.com/DavidKitano)[![](https://avatars.githubusercontent.com/u/35138018?v=4&size=64)](https://github.com/tuskermanshu)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/15872986?v=4&size=64)](https://github.com/chenweiyi)[![](https://avatars.githubusercontent.com/u/169252980?v=4&size=64)](https://github.com/xiaochenchen-igg-com)[![](https://avatars.githubusercontent.com/u/73569598?v=4&size=64)](https://github.com/sechi747)[![](https://avatars.githubusercontent.com/u/127809872?v=4&size=64)](https://github.com/123outsider)[![](https://avatars.githubusercontent.com/u/54931083?v=4&size=64)](https://github.com/wjp980108)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/17698194?v=4&size=64)](https://github.com/nieyuyao)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/57179957?v=4&size=64)](https://github.com/yeonjulee1005)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/101238421?v=4&size=64)](https://github.com/acyza)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/62927479?v=4&size=64)](https://github.com/anflower)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)[![](https://avatars.githubusercontent.com/u/39672197?v=4&size=64)](https://github.com/bchen1029)

[Autocomplete 自动补全输入框](https://element-plus.org/zh-CN/component/autocomplete)

[Checkbox 多选框](https://element-plus.org/zh-CN/component/checkbox)




---
## [form/checkbox] Checkbox 多选框
> 官方文档: https://element-plus.org/zh-CN/component/checkbox.html

---

# Checkbox 多选框 [​](#checkbox-多选框)

更新日志待解决

25

在一组备选项中进行多选。

WARNING

`label` 作为 `value` 来使用已经被 **废弃**, 建议`label` 只用来表示展示的文字，这个被废弃的用法**将会在** 3.0.0 版本被移除，请考虑使用新 API 替换.

TIP

新的 API `value` 已在 2.6.0 版本添加，文档中的示例都将使用 `value`。 如果您使用的版本 **低于** 2.6.0 并且使用 `checkbox-group`，请参考：

vue

```
<template>
  <el-checkbox-group v-model="checkList">
    <!-- works when >=2.6.0, recommended ✔️ value not work when <2.6.0 ❌ -->
    <el-checkbox label="Option 1" value="Value 1" />
    <!-- works when <2.6.0, deprecated act as value when >=3.0.0 -->
    <el-checkbox label="Option 2 & Value 2" />
  </el-checkbox-group>
</template>
```

## 基础用法 [​](#基础用法)

单独使用可以表示两种状态之间的切换，写在标签中的内容为 checkbox 按钮后的介绍。

`checkbox-group`元素能把多个 checkbox 管理为一组，只需要在 Group 中使用 `v-model` 绑定 `Array` 类型的变量即可。 只有一个选项时的默认值类型为 `Boolean`，当选中时值为`true`。 `el-checkbox` 标签中的内容将成为复选框按钮之后的描述。

Option 1Option 2

Option 1Option 2

Option 1Option 2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1jaGVja2JveCB2LW1vZGVsPVwiY2hlY2tlZDFcIiBsYWJlbD1cIk9wdGlvbiAxXCIgc2l6ZT1cImxhcmdlXCIgLz5cbiAgICA8ZWwtY2hlY2tib3ggdi1tb2RlbD1cImNoZWNrZWQyXCIgbGFiZWw9XCJPcHRpb24gMlwiIHNpemU9XCJsYXJnZVwiIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibXktMlwiPlxuICAgIDxlbC1jaGVja2JveCB2LW1vZGVsPVwiY2hlY2tlZDNcIiBsYWJlbD1cIk9wdGlvbiAxXCIgLz5cbiAgICA8ZWwtY2hlY2tib3ggdi1tb2RlbD1cImNoZWNrZWQ0XCIgbGFiZWw9XCJPcHRpb24gMlwiIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibXQtMlwiPlxuICAgIDxlbC1jaGVja2JveCB2LW1vZGVsPVwiY2hlY2tlZDVcIiBsYWJlbD1cIk9wdGlvbiAxXCIgc2l6ZT1cInNtYWxsXCIgLz5cbiAgICA8ZWwtY2hlY2tib3ggdi1tb2RlbD1cImNoZWNrZWQ2XCIgbGFiZWw9XCJPcHRpb24gMlwiIHNpemU9XCJzbWFsbFwiIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgY2hlY2tlZDEgPSByZWYodHJ1ZSlcbmNvbnN0IGNoZWNrZWQyID0gcmVmKGZhbHNlKVxuY29uc3QgY2hlY2tlZDMgPSByZWYoZmFsc2UpXG5jb25zdCBjaGVja2VkNCA9IHJlZihmYWxzZSlcbmNvbnN0IGNoZWNrZWQ1ID0gcmVmKGZhbHNlKVxuY29uc3QgY2hlY2tlZDYgPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/checkbox/basic.vue)_

vue

```
<template>
  <div>
    <el-checkbox v-model="checked1" label="Option 1" size="large" />
    <el-checkbox v-model="checked2" label="Option 2" size="large" />
  </div>
  <div class="my-2">
    <el-checkbox v-model="checked3" label="Option 1" />
    <el-checkbox v-model="checked4" label="Option 2" />
  </div>
  <div class="mt-2">
    <el-checkbox v-model="checked5" label="Option 1" size="small" />
    <el-checkbox v-model="checked6" label="Option 2" size="small" />
  </div>
</template>

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

const checked1 = ref(true)
const checked2 = ref(false)
const checked3 = ref(false)
const checked4 = ref(false)
const checked5 = ref(false)
const checked6 = ref(false)
</script>
```

隐藏源代码

## 禁用状态 [​](#禁用状态)

多选框不可用状态。

设置 `disabled` 属性即可。

DisabledNot disabled

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2hlY2tib3ggdi1tb2RlbD1cImNoZWNrZWQxXCIgZGlzYWJsZWQ+RGlzYWJsZWQ8L2VsLWNoZWNrYm94PlxuICA8ZWwtY2hlY2tib3ggdi1tb2RlbD1cImNoZWNrZWQyXCI+Tm90IGRpc2FibGVkPC9lbC1jaGVja2JveD5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGNoZWNrZWQxID0gcmVmKGZhbHNlKVxuY29uc3QgY2hlY2tlZDIgPSByZWYodHJ1ZSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/checkbox/disabled.vue)_

vue

```
<template>
  <el-checkbox v-model="checked1" disabled>Disabled</el-checkbox>
  <el-checkbox v-model="checked2">Not disabled</el-checkbox>
</template>

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

const checked1 = ref(false)
const checked2 = ref(true)
</script>
```

隐藏源代码

## 多选框组 [​](#多选框组)

适用于多个勾选框绑定到同一个数组的情景，通过是否勾选来表示这一组选项中选中的项。

在 `el-checkbox` 元素中定义 `v-model` 绑定变量，单一的 `checkbox` 中，默认绑定变量的值会是 `Boolean`，选中为 `true`。 在 `el-checkbox` 组件中，`value` 是选择框的值。 如果该组件下没有被传入内容，那么 `label` 将会作为 checkbox 按钮后的介绍。 `value` 也与数组中的元素值相对应。 如果指定的值存在于数组中，就处于选择状态，反之亦然。

Option AOption BOption Cdisabledselected and disabled

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2hlY2tib3gtZ3JvdXAgdi1tb2RlbD1cImNoZWNrTGlzdFwiPlxuICAgIDxlbC1jaGVja2JveCBsYWJlbD1cIk9wdGlvbiBBXCIgdmFsdWU9XCJWYWx1ZSBBXCIgLz5cbiAgICA8ZWwtY2hlY2tib3ggbGFiZWw9XCJPcHRpb24gQlwiIHZhbHVlPVwiVmFsdWUgQlwiIC8+XG4gICAgPGVsLWNoZWNrYm94IGxhYmVsPVwiT3B0aW9uIENcIiB2YWx1ZT1cIlZhbHVlIENcIiAvPlxuICAgIDxlbC1jaGVja2JveCBsYWJlbD1cImRpc2FibGVkXCIgdmFsdWU9XCJWYWx1ZSBkaXNhYmxlZFwiIGRpc2FibGVkIC8+XG4gICAgPGVsLWNoZWNrYm94XG4gICAgICBsYWJlbD1cInNlbGVjdGVkIGFuZCBkaXNhYmxlZFwiXG4gICAgICB2YWx1ZT1cIlZhbHVlIHNlbGVjdGVkIGFuZCBkaXNhYmxlZFwiXG4gICAgICBkaXNhYmxlZFxuICAgIC8+XG4gIDwvZWwtY2hlY2tib3gtZ3JvdXA+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBjaGVja0xpc3QgPSByZWYoWydWYWx1ZSBzZWxlY3RlZCBhbmQgZGlzYWJsZWQnLCAnVmFsdWUgQSddKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/checkbox/grouping.vue)_

vue

```
<template>
  <el-checkbox-group v-model="checkList">
    <el-checkbox label="Option A" value="Value A" />
    <el-checkbox label="Option B" value="Value B" />
    <el-checkbox label="Option C" value="Value C" />
    <el-checkbox label="disabled" value="Value disabled" disabled />
    <el-checkbox
      label="selected and disabled"
      value="Value selected and disabled"
      disabled
    />
  </el-checkbox-group>
</template>

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

const checkList = ref(['Value selected and disabled', 'Value A'])
</script>
```

隐藏源代码

## Options 属性 2.11.2 [​](#options-属性)

基础用法 `el-checkbox-group` 的快捷示例。 您可以通过 `props` 属性自定义 `options` 的别名。

Option AOption BOption Cdisabledselected and disabled

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2hlY2tib3gtZ3JvdXAgdi1tb2RlbD1cImNoZWNrTGlzdFwiIDpvcHRpb25zPVwib3B0aW9uc1wiIDpwcm9wcz1cInByb3BzXCIgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGNoZWNrTGlzdCA9IHJlZihbJ1ZhbHVlIHNlbGVjdGVkIGFuZCBkaXNhYmxlZCcsICdWYWx1ZSBBJ10pXG5jb25zdCBwcm9wcyA9IHsgbGFiZWw6ICduYW1lJywgdmFsdWU6ICdpZCcsIGRpc2FibGVkOiAndW5hYmxlJyB9XG5jb25zdCBvcHRpb25zID0gW1xuICB7IG5hbWU6ICdPcHRpb24gQScsIGlkOiAnVmFsdWUgQScgfSxcbiAgeyBuYW1lOiAnT3B0aW9uIEInLCBpZDogJ1ZhbHVlIEInIH0sXG4gIHsgbmFtZTogJ09wdGlvbiBDJywgaWQ6ICdWYWx1ZSBDJyB9LFxuICB7IG5hbWU6ICdkaXNhYmxlZCcsIGlkOiAnVmFsdWUgZGlzYWJsZWQnLCB1bmFibGU6IHRydWUgfSxcbiAge1xuICAgIG5hbWU6ICdzZWxlY3RlZCBhbmQgZGlzYWJsZWQnLFxuICAgIGlkOiAnVmFsdWUgc2VsZWN0ZWQgYW5kIGRpc2FibGVkJyxcbiAgICB1bmFibGU6IHRydWUsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/checkbox/options.vue)_

vue

```
<template>
  <el-checkbox-group v-model="checkList" :options="options" :props="props" />
</template>

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

const checkList = ref(['Value selected and disabled', 'Value A'])
const props = { label: 'name', value: 'id', disabled: 'unable' }
const options = [
  { name: 'Option A', id: 'Value A' },
  { name: 'Option B', id: 'Value B' },
  { name: 'Option C', id: 'Value C' },
  { name: 'disabled', id: 'Value disabled', unable: true },
  {
    name: 'selected and disabled',
    id: 'Value selected and disabled',
    unable: true,
  },
]
</script>
```

隐藏源代码

## 中间状态 [​](#中间状态)

`indeterminate` 属性用以表示 checkbox 的不确定状态，一般用于实现全选的效果

 Check all

ShanghaiBeijingGuangzhouShenzhen

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2hlY2tib3hcbiAgICB2LW1vZGVsPVwiY2hlY2tBbGxcIlxuICAgIDppbmRldGVybWluYXRlPVwiaXNJbmRldGVybWluYXRlXCJcbiAgICBAY2hhbmdlPVwiaGFuZGxlQ2hlY2tBbGxDaGFuZ2VcIlxuICA+XG4gICAgQ2hlY2sgYWxsXG4gIDwvZWwtY2hlY2tib3g+XG4gIDxlbC1jaGVja2JveC1ncm91cFxuICAgIHYtbW9kZWw9XCJjaGVja2VkQ2l0aWVzXCJcbiAgICBAY2hhbmdlPVwiaGFuZGxlQ2hlY2tlZENpdGllc0NoYW5nZVwiXG4gID5cbiAgICA8ZWwtY2hlY2tib3ggdi1mb3I9XCJjaXR5IGluIGNpdGllc1wiIDprZXk9XCJjaXR5XCIgOmxhYmVsPVwiY2l0eVwiIDp2YWx1ZT1cImNpdHlcIj5cbiAgICAgIHt7IGNpdHkgfX1cbiAgICA8L2VsLWNoZWNrYm94PlxuICA8L2VsLWNoZWNrYm94LWdyb3VwPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBDaGVja2JveFZhbHVlVHlwZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgY2hlY2tBbGwgPSByZWYoZmFsc2UpXG5jb25zdCBpc0luZGV0ZXJtaW5hdGUgPSByZWYodHJ1ZSlcbmNvbnN0IGNoZWNrZWRDaXRpZXMgPSByZWYoWydTaGFuZ2hhaScsICdCZWlqaW5nJ10pXG5jb25zdCBjaXRpZXMgPSBbJ1NoYW5naGFpJywgJ0JlaWppbmcnLCAnR3Vhbmd6aG91JywgJ1NoZW56aGVuJ11cblxuY29uc3QgaGFuZGxlQ2hlY2tBbGxDaGFuZ2UgPSAodmFsOiBDaGVja2JveFZhbHVlVHlwZSkgPT4ge1xuICBjaGVja2VkQ2l0aWVzLnZhbHVlID0gdmFsID8gY2l0aWVzIDogW11cbiAgaXNJbmRldGVybWluYXRlLnZhbHVlID0gZmFsc2Vcbn1cbmNvbnN0IGhhbmRsZUNoZWNrZWRDaXRpZXNDaGFuZ2UgPSAodmFsdWU6IENoZWNrYm94VmFsdWVUeXBlW10pID0+IHtcbiAgY29uc3QgY2hlY2tlZENvdW50ID0gdmFsdWUubGVuZ3RoXG4gIGNoZWNrQWxsLnZhbHVlID0gY2hlY2tlZENvdW50ID09PSBjaXRpZXMubGVuZ3RoXG4gIGlzSW5kZXRlcm1pbmF0ZS52YWx1ZSA9IGNoZWNrZWRDb3VudCA+IDAgJiYgY2hlY2tlZENvdW50IDwgY2l0aWVzLmxlbmd0aFxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/checkbox/intermediate.vue)_

vue

```
<template>
  <el-checkbox
    v-model="checkAll"
    :indeterminate="isIndeterminate"
    @change="handleCheckAllChange"
  >
    Check all
  </el-checkbox>
  <el-checkbox-group
    v-model="checkedCities"
    @change="handleCheckedCitiesChange"
  >
    <el-checkbox v-for="city in cities" :key="city" :label="city" :value="city">
      {{ city }}
    </el-checkbox>
  </el-checkbox-group>
</template>

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

import type { CheckboxValueType } from 'element-plus'

const checkAll = ref(false)
const isIndeterminate = ref(true)
const checkedCities = ref(['Shanghai', 'Beijing'])
const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']

const handleCheckAllChange = (val: CheckboxValueType) => {
  checkedCities.value = val ? cities : []
  isIndeterminate.value = false
}
const handleCheckedCitiesChange = (value: CheckboxValueType[]) => {
  const checkedCount = value.length
  checkAll.value = checkedCount === cities.length
  isIndeterminate.value = checkedCount > 0 && checkedCount < cities.length
}
</script>
```

隐藏源代码

## 可选项目数量的限制 [​](#可选项目数量的限制)

使用 `min` 和 `max` 属性能够限制可以被勾选的项目的数量。

ShanghaiBeijingGuangzhouShenzhen

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2hlY2tib3gtZ3JvdXAgdi1tb2RlbD1cImNoZWNrZWRDaXRpZXNcIiA6bWluPVwiMVwiIDptYXg9XCIyXCI+XG4gICAgPGVsLWNoZWNrYm94IHYtZm9yPVwiY2l0eSBpbiBjaXRpZXNcIiA6a2V5PVwiY2l0eVwiIDpsYWJlbD1cImNpdHlcIiA6dmFsdWU9XCJjaXR5XCI+XG4gICAgICB7eyBjaXR5IH19XG4gICAgPC9lbC1jaGVja2JveD5cbiAgPC9lbC1jaGVja2JveC1ncm91cD5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGNoZWNrZWRDaXRpZXMgPSByZWYoWydTaGFuZ2hhaScsICdCZWlqaW5nJ10pXG5jb25zdCBjaXRpZXMgPSBbJ1NoYW5naGFpJywgJ0JlaWppbmcnLCAnR3Vhbmd6aG91JywgJ1NoZW56aGVuJ11cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/checkbox/limitation.vue)_

vue

```
<template>
  <el-checkbox-group v-model="checkedCities" :min="1" :max="2">
    <el-checkbox v-for="city in cities" :key="city" :label="city" :value="city">
      {{ city }}
    </el-checkbox>
  </el-checkbox-group>
</template>

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

const checkedCities = ref(['Shanghai', 'Beijing'])
const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
</script>
```

隐藏源代码

## 按钮样式 [​](#按钮样式)

按钮样式的多选组合。

只需要把 `el-checkbox` 元素替换为 `el-checkbox-button` 元素即可。 此外，Element Plus 还提供了`size`属性。

ShanghaiBeijingGuangzhouShenzhen

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1jaGVja2JveC1ncm91cCB2LW1vZGVsPVwiY2hlY2tib3hHcm91cDFcIiBzaXplPVwibGFyZ2VcIj5cbiAgICAgIDxlbC1jaGVja2JveC1idXR0b24gdi1mb3I9XCJjaXR5IGluIGNpdGllc1wiIDprZXk9XCJjaXR5XCIgOnZhbHVlPVwiY2l0eVwiPlxuICAgICAgICB7eyBjaXR5IH19XG4gICAgICA8L2VsLWNoZWNrYm94LWJ1dHRvbj5cbiAgICA8L2VsLWNoZWNrYm94LWdyb3VwPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cImRlbW8tYnV0dG9uLXN0eWxlXCI+XG4gICAgPGVsLWNoZWNrYm94LWdyb3VwIHYtbW9kZWw9XCJjaGVja2JveEdyb3VwMlwiPlxuICAgICAgPGVsLWNoZWNrYm94LWJ1dHRvbiB2LWZvcj1cImNpdHkgaW4gY2l0aWVzXCIgOmtleT1cImNpdHlcIiA6dmFsdWU9XCJjaXR5XCI+XG4gICAgICAgIHt7IGNpdHkgfX1cbiAgICAgIDwvZWwtY2hlY2tib3gtYnV0dG9uPlxuICAgIDwvZWwtY2hlY2tib3gtZ3JvdXA+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwiZGVtby1idXR0b24tc3R5bGVcIj5cbiAgICA8ZWwtY2hlY2tib3gtZ3JvdXAgdi1tb2RlbD1cImNoZWNrYm94R3JvdXAzXCIgc2l6ZT1cInNtYWxsXCI+XG4gICAgICA8ZWwtY2hlY2tib3gtYnV0dG9uXG4gICAgICAgIHYtZm9yPVwiY2l0eSBpbiBjaXRpZXNcIlxuICAgICAgICA6a2V5PVwiY2l0eVwiXG4gICAgICAgIDp2YWx1ZT1cImNpdHlcIlxuICAgICAgICA6ZGlzYWJsZWQ9XCJjaXR5ID09PSAnQmVpamluZydcIlxuICAgICAgPlxuICAgICAgICB7eyBjaXR5IH19XG4gICAgICA8L2VsLWNoZWNrYm94LWJ1dHRvbj5cbiAgICA8L2VsLWNoZWNrYm94LWdyb3VwPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cImRlbW8tYnV0dG9uLXN0eWxlXCI+XG4gICAgPGVsLWNoZWNrYm94LWdyb3VwIHYtbW9kZWw9XCJjaGVja2JveEdyb3VwNFwiIHNpemU9XCJzbWFsbFwiIGRpc2FibGVkPlxuICAgICAgPGVsLWNoZWNrYm94LWJ1dHRvbiB2LWZvcj1cImNpdHkgaW4gY2l0aWVzXCIgOmtleT1cImNpdHlcIiA6dmFsdWU9XCJjaXR5XCI+XG4gICAgICAgIHt7IGNpdHkgfX1cbiAgICAgIDwvZWwtY2hlY2tib3gtYnV0dG9uPlxuICAgIDwvZWwtY2hlY2tib3gtZ3JvdXA+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgY2hlY2tib3hHcm91cDEgPSByZWYoWydTaGFuZ2hhaSddKVxuY29uc3QgY2hlY2tib3hHcm91cDIgPSByZWYoWydTaGFuZ2hhaSddKVxuY29uc3QgY2hlY2tib3hHcm91cDMgPSByZWYoWydTaGFuZ2hhaSddKVxuY29uc3QgY2hlY2tib3hHcm91cDQgPSByZWYoWydTaGFuZ2hhaSddKVxuY29uc3QgY2l0aWVzID0gWydTaGFuZ2hhaScsICdCZWlqaW5nJywgJ0d1YW5nemhvdScsICdTaGVuemhlbiddXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWJ1dHRvbi1zdHlsZSB7XG4gIG1hcmdpbi10b3A6IDI0cHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/checkbox/button-style.vue)_

vue

```
<template>
  <div>
    <el-checkbox-group v-model="checkboxGroup1" size="large">
      <el-checkbox-button v-for="city in cities" :key="city" :value="city">
        {{ city }}
      </el-checkbox-button>
    </el-checkbox-group>
  </div>
  <div class="demo-button-style">
    <el-checkbox-group v-model="checkboxGroup2">
      <el-checkbox-button v-for="city in cities" :key="city" :value="city">
        {{ city }}
      </el-checkbox-button>
    </el-checkbox-group>
  </div>
  <div class="demo-button-style">
    <el-checkbox-group v-model="checkboxGroup3" size="small">
      <el-checkbox-button
        v-for="city in cities"
        :key="city"
        :value="city"
        :disabled="city === 'Beijing'"
      >
        {{ city }}
      </el-checkbox-button>
    </el-checkbox-group>
  </div>
  <div class="demo-button-style">
    <el-checkbox-group v-model="checkboxGroup4" size="small" disabled>
      <el-checkbox-button v-for="city in cities" :key="city" :value="city">
        {{ city }}
      </el-checkbox-button>
    </el-checkbox-group>
  </div>
</template>

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

const checkboxGroup1 = ref(['Shanghai'])
const checkboxGroup2 = ref(['Shanghai'])
const checkboxGroup3 = ref(['Shanghai'])
const checkboxGroup4 = ref(['Shanghai'])
const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
</script>

<style scoped>
.demo-button-style {
  margin-top: 24px;
}
</style>
```

隐藏源代码

## 带有边框 [​](#带有边框)

设置`border`属性可以渲染为带有边框的多选框。

Option1Option2

Option1Option2

Option1Option2

Option1Option2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1jaGVja2JveCB2LW1vZGVsPVwiY2hlY2tlZDFcIiBsYWJlbD1cIk9wdGlvbjFcIiBzaXplPVwibGFyZ2VcIiBib3JkZXIgLz5cbiAgICA8ZWwtY2hlY2tib3ggdi1tb2RlbD1cImNoZWNrZWQyXCIgbGFiZWw9XCJPcHRpb24yXCIgc2l6ZT1cImxhcmdlXCIgYm9yZGVyIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibXQtNFwiPlxuICAgIDxlbC1jaGVja2JveCB2LW1vZGVsPVwiY2hlY2tlZDNcIiBsYWJlbD1cIk9wdGlvbjFcIiBib3JkZXIgLz5cbiAgICA8ZWwtY2hlY2tib3ggdi1tb2RlbD1cImNoZWNrZWQ0XCIgbGFiZWw9XCJPcHRpb24yXCIgYm9yZGVyIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibXQtNFwiPlxuICAgIDxlbC1jaGVja2JveC1ncm91cCB2LW1vZGVsPVwiY2hlY2tib3hHcm91cDFcIiBzaXplPVwic21hbGxcIj5cbiAgICAgIDxlbC1jaGVja2JveCBsYWJlbD1cIk9wdGlvbjFcIiB2YWx1ZT1cIlZhbHVlMVwiIGJvcmRlciAvPlxuICAgICAgPGVsLWNoZWNrYm94IGxhYmVsPVwiT3B0aW9uMlwiIHZhbHVlPVwiVmFsdWUyXCIgYm9yZGVyIC8+XG4gICAgPC9lbC1jaGVja2JveC1ncm91cD5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJtdC00XCI+XG4gICAgPGVsLWNoZWNrYm94LWdyb3VwIHYtbW9kZWw9XCJjaGVja2JveEdyb3VwMVwiIHNpemU9XCJzbWFsbFwiPlxuICAgICAgPGVsLWNoZWNrYm94IGxhYmVsPVwiT3B0aW9uMVwiIHZhbHVlPVwiVmFsdWUxXCIgYm9yZGVyIGRpc2FibGVkIC8+XG4gICAgICA8ZWwtY2hlY2tib3ggbGFiZWw9XCJPcHRpb24yXCIgdmFsdWU9XCJWYWx1ZTJcIiBib3JkZXIgZGlzYWJsZWQgLz5cbiAgICA8L2VsLWNoZWNrYm94LWdyb3VwPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGNoZWNrZWQxID0gcmVmKHRydWUpXG5jb25zdCBjaGVja2VkMiA9IHJlZihmYWxzZSlcbmNvbnN0IGNoZWNrZWQzID0gcmVmKGZhbHNlKVxuY29uc3QgY2hlY2tlZDQgPSByZWYodHJ1ZSlcbmNvbnN0IGNoZWNrYm94R3JvdXAxID0gcmVmKFsnVmFsdWUxJ10pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/checkbox/with-border.vue)_

vue

```
<template>
  <div>
    <el-checkbox v-model="checked1" label="Option1" size="large" border />
    <el-checkbox v-model="checked2" label="Option2" size="large" border />
  </div>
  <div class="mt-4">
    <el-checkbox v-model="checked3" label="Option1" border />
    <el-checkbox v-model="checked4" label="Option2" border />
  </div>
  <div class="mt-4">
    <el-checkbox-group v-model="checkboxGroup1" size="small">
      <el-checkbox label="Option1" value="Value1" border />
      <el-checkbox label="Option2" value="Value2" border />
    </el-checkbox-group>
  </div>
  <div class="mt-4">
    <el-checkbox-group v-model="checkboxGroup1" size="small">
      <el-checkbox label="Option1" value="Value1" border disabled />
      <el-checkbox label="Option2" value="Value2" border disabled />
    </el-checkbox-group>
  </div>
</template>

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

const checked1 = ref(true)
const checked2 = ref(false)
const checked3 = ref(false)
const checked4 = ref(true)
const checkboxGroup1 = ref(['Value1'])
</script>
```

隐藏源代码

## Checkbox API [​](#checkbox-api)

### Checkbox Attributes [​](#checkbox-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `string` / `number` / `boolean` | — |
| value 2.6.0 | 选中状态的值（只有在`checkbox-group`或者绑定对象类型为`array`时有效） | `string` / `number` / `boolean` / `object` | — |
| label | 选中状态的值，只有在绑定对象类型为 `array` 时有效。 如果没有 value， `label`则作为`value`使用 | `string` / `number` / `boolean` / `object` | — |
| true-value 2.6.0 | 选中时的值 | `string` / `number` | — |
| false-value 2.6.0 | 没有选中时的值 | `string` / `number` | — |
| disabled | 是否禁用 | `boolean` | false |
| border | 是否显示边框 | `boolean` | false |
| size | Checkbox 的尺寸 | `enum` | — |
| name | 原生 name 属性 | `string` | — |
| checked | 当前是否勾选 | `boolean` | false |
| indeterminate | 设置不确定状态，仅负责样式控制 | `boolean` | false |
| validate-event | 输入时是否触发表单的校验 | `boolean` | true |
| tabindex | 输入框的 tabindex | `string` / `number` | — |
| id | input id | `string` | — |
| aria-controls a11y 2.7.2 | 与 [aria-control](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls)一致, 当 `indeterminate`为 `true`时生效 | `string` | — |
| aria-label a11y | 原生 `aria-label`属性 | `string` | — |
| true-label deprecated | 选中时的值 | `string` / `number` | — |
| false-label deprecated | 没有选中时的值 | `string` / `number` | — |
| controls a11y deprecated | 和 [aria-control](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls)一致。当 `indeterminate` 为 `true` 时生效 | `string` | — |

### Checkbox Events [​](#checkbox-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 当绑定值变化时触发的事件 | `Function` |

### Checkbox Slots [​](#checkbox-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## CheckboxGroup API [​](#checkboxgroup-api)

### CheckboxGroup Attributes [​](#checkboxgroup-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 绑定值 | `array` | \[\] |
| size | 多选框组尺寸 | `enum` | — |
| disabled | 是否禁用 | `boolean` | false |
| min | 可被勾选的 checkbox 的最小数量 | `number` | — |
| max | 可被勾选的 checkbox 的最大数量 | `number` | — |
| aria-label a11y 2.7.2 | 原生 `aria-label`属性 | `string` | — |
| text-color | 当按钮为活跃状态时的字体颜色 | `string` | #ffffff |
| fill | 当按钮为活跃状态时的边框和背景颜色 | `string` | #409eff |
| tag | 复选框组元素标签 | `string` | div |
| validate-event | 是否触发表单验证 | `boolean` | true |
| label a11y deprecated | 原生 `aria-label`属性 | `string` | — |
| options 2.11.2 | 选项的数据源， `value` 的 key 和 `label` 和 `disabled`可以通过 `props`自定义. | `array` | — |
| props 2.11.2 | options 的配置 | `object` | `{value: 'value', label: 'label', disabled: 'disabled'}` |
| type 2.11.5 | 用于渲染选项的组件类型（例如 `'button'`） | `enum` | 'checkbox' |

### CheckboxGroup Events [​](#checkboxgroup-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 当绑定值变化时触发的事件 | `Function` |

### CheckboxGroup Slots [​](#checkboxgroup-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | Checkbox / Checkbox-button |

## CheckboxButton API [​](#checkboxbutton-api)

### CheckboxButton Attributes [​](#checkboxbutton-attributes)

| 名称 | 详情 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value 2.6.0 | 选中状态的值，只有在绑定对象类型为 `array` 时有效。 | `string` / `number` / `boolean` / `object` | — |
| label | 选中状态的值，只有在绑定对象类型为 `array` 时有效。 如果没有 value， `label`则作为`value`使用 | `string` / `number` / `boolean` / `object` | — |
| true-value 2.6.0 | 选中时的值 | `string` / `number` | — |
| false-value 2.6.0 | 没有选中时的值 | `string` / `number` | — |
| disabled | 是否禁用 | `boolean` | false |
| name | 原生 name 属性 | `string` | — |
| checked | 当前是否勾选 | `boolean` | false |
| true-label deprecated | 选中时的值 | `string` / `number` | — |
| false-label deprecated | 没有选中时的值 | `string` / `number` | — |

### CheckboxButton Slots [​](#checkboxbutton-slots)

| 插槽名 | 描述 |
| --- | --- |
| default | 自定义默认内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/checkbox) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/checkbox.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/checkbox.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/72490874?v=4&size=64)](https://github.com/zuwenyin)[![](https://avatars.githubusercontent.com/u/140705167?v=4&size=64)](https://github.com/zhongli-kira)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/28594168?v=4&size=64)](https://github.com/neostfox)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/35138018?v=4&size=64)](https://github.com/tuskermanshu)[![](https://avatars.githubusercontent.com/u/108655466?v=4&size=64)](https://github.com/Karolis-Stoncius)[![](https://avatars.githubusercontent.com/u/36906371?v=4&size=64)](https://github.com/iamdin)[![](https://avatars.githubusercontent.com/u/59350883?v=4&size=64)](https://github.com/init-qy)[![](https://avatars.githubusercontent.com/u/43134418?v=4&size=64)](https://github.com/MonsterPi13)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/43210216?v=4&size=64)](https://github.com/ytx222)[![](https://avatars.githubusercontent.com/u/25120803?v=4&size=64)](https://github.com/leeonon)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/5445667?v=4&size=64)](https://github.com/iceshou)[![](https://avatars.githubusercontent.com/u/45122329?v=4&size=64)](https://github.com/cokemine)[![](https://avatars.githubusercontent.com/u/188531008?v=4&size=64)](https://github.com/dengguangmiaoyyds)[![](https://avatars.githubusercontent.com/u/25742988?v=4&size=64)](https://github.com/Geekhyt)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)

[Cascader 级联选择器](https://element-plus.org/zh-CN/component/cascader)

[ColorPickerPanel 颜色选择器面板](https://element-plus.org/zh-CN/component/color-picker-panel)




---
## [form/color-picker-panel] ColorPickerPanel 颜色选择器面板
> 官方文档: https://element-plus.org/zh-CN/component/color-picker-panel.html

---

# ColorPickerPanel 颜色选择器面板 beta [​](#colorpickerpanel-颜色选择器面板)

更新日志待解决

0

`ColorPickerPanel`是`ColorPicker`的核心组件。

## 基础用法 [​](#基础用法)

ColorPickerPanel 需要一个字符串类型的变量才能绑定到 v-model。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY29sb3ItcGlja2VyLXBhbmVsIHYtbW9kZWw9XCJjb2xvclwiIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBjb2xvciA9IHJlZignIzQwOUVGRicpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/color-picker-panel/basic.vue)_

vue

```
<template>
  <el-color-picker-panel v-model="color" />
</template>

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

const color = ref('#409EFF')
</script>
```

隐藏源代码

## 选择透明度 [​](#选择透明度)

ColorPickerPanel 支持Alpha 通道选择。 要激活 Alpha 选择，只需添加 "show-alpha" 属性。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY29sb3ItcGlja2VyLXBhbmVsIHYtbW9kZWw9XCJjb2xvclwiIHNob3ctYWxwaGEgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGNvbG9yID0gcmVmKCdyZ2JhKDE5LCAyMDYsIDEwMiwgMC44KScpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/color-picker-panel/alpha.vue)_

vue

```
<template>
  <el-color-picker-panel v-model="color" show-alpha />
</template>

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

const color = ref('rgba(19, 206, 102, 0.8)')
</script>
```

隐藏源代码

## 预定义颜色 [​](#预定义颜色)

颜色选择板支持预定义的颜色选项

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY29sb3ItcGlja2VyLXBhbmVsXG4gICAgdi1tb2RlbD1cImNvbG9yXCJcbiAgICBzaG93LWFscGhhXG4gICAgOnByZWRlZmluZT1cInByZWRlZmluZUNvbG9yc1wiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBjb2xvciA9IHJlZigncmdiYSgyNTUsIDY5LCAwLCAwLjY4KScpXG5jb25zdCBwcmVkZWZpbmVDb2xvcnMgPSBbXG4gICcjZmY0NTAwJyxcbiAgJyNmZjhjMDAnLFxuICAnI2ZmZDcwMCcsXG4gICcjOTBlZTkwJyxcbiAgJyMwMGNlZDEnLFxuICAnIzFlOTBmZicsXG4gICcjYzcxNTg1JyxcbiAgJ3JnYmEoMjU1LCA2OSwgMCwgMC42OCknLFxuICAncmdiKDI1NSwgMTIwLCAwKScsXG4gICdoc3YoNTEsIDEwMCwgOTgpJyxcbiAgJ2hzdmEoMTIwLCA0MCwgOTQsIDAuNSknLFxuICAnaHNsKDE4MSwgMTAwJSwgMzclKScsXG4gICdoc2xhKDIwOSwgMTAwJSwgNTYlLCAwLjczKScsXG4gICcjYzcxNTg1NzcnLFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/color-picker-panel/predefined-color.vue)_

vue

```
<template>
  <el-color-picker-panel
    v-model="color"
    show-alpha
    :predefine="predefineColors"
  />
</template>

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

const color = ref('rgba(255, 69, 0, 0.68)')
const predefineColors = [
  '#ff4500',
  '#ff8c00',
  '#ffd700',
  '#90ee90',
  '#00ced1',
  '#1e90ff',
  '#c71585',
  'rgba(255, 69, 0, 0.68)',
  'rgb(255, 120, 0)',
  'hsv(51, 100, 98)',
  'hsva(120, 40, 94, 0.5)',
  'hsl(181, 100%, 37%)',
  'hsla(209, 100%, 56%, 0.73)',
  '#c7158577',
]
</script>
```

隐藏源代码

## Border 边框 [​](#border-边框)

默认情况下，边框是默认的，如果你不想要边框请参考示例。

No border:

TS

JS

_[](https://element-plus.run/?extra_packages=%40vueuse%2Fcore#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHJlZj1cImNvbnRhaW5lclJlZlwiPlxuICAgIDxkaXYgY2xhc3M9XCJ0ZXh0LWNlbnRlclwiPk5vIGJvcmRlcjo8L2Rpdj5cbiAgICA8ZWwtZGl2aWRlciAvPlxuICAgIDxkaXYgY2xhc3M9XCJmbGV4IGZsZXgtd3JhcCBqdXN0aWZ5LWNlbnRlciBnYXAtNFwiPlxuICAgICAgPGRpdiBjbGFzcz1cInAtNVwiPlxuICAgICAgICA8ZWwtY29sb3ItcGlja2VyLXBhbmVsIHYtbW9kZWw9XCJ2YWx1ZVwiIDpib3JkZXI9XCJmYWxzZVwiIC8+XG4gICAgICA8L2Rpdj5cbiAgICAgIDxlbC1kaXZpZGVyXG4gICAgICAgIGNsYXNzPVwiaC1hdXRvXCJcbiAgICAgICAgOmRpcmVjdGlvbj1cImlzTmFycm93ID8gJ2hvcml6b250YWwnIDogJ3ZlcnRpY2FsJ1wiXG4gICAgICAvPlxuICAgICAgPGVsLWNhcmQ+XG4gICAgICAgIDxlbC1jb2xvci1waWNrZXItcGFuZWwgdi1tb2RlbD1cInZhbHVlXCIgOmJvcmRlcj1cImZhbHNlXCIgLz5cbiAgICAgIDwvZWwtY2FyZD5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgY29tcHV0ZWQsIHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IHVzZUVsZW1lbnRTaXplIH0gZnJvbSAnQHZ1ZXVzZS9jb3JlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZignI2ZmNjkwMCcpXG5jb25zdCBjb250YWluZXJSZWYgPSByZWY8SFRNTEVsZW1lbnQ+KClcblxuY29uc3QgeyB3aWR0aCB9ID0gdXNlRWxlbWVudFNpemUoY29udGFpbmVyUmVmKVxuXG5jb25zdCBpc05hcnJvdyA9IGNvbXB1dGVkKCgpID0+IHdpZHRoLnZhbHVlIDwgODE1KVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/color-picker-panel/border.vue)_

vue

```
<template>
  <div ref="containerRef">
    <div class="text-center">No border:</div>
    <el-divider />
    <div class="flex flex-wrap justify-center gap-4">
      <div class="p-5">
        <el-color-picker-panel v-model="value" :border="false" />
      </div>
      <el-divider
        class="h-auto"
        :direction="isNarrow ? 'horizontal' : 'vertical'"
      />
      <el-card>
        <el-color-picker-panel v-model="value" :border="false" />
      </el-card>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'
import { useElementSize } from '@vueuse/core'

const value = ref('#ff6900')
const containerRef = ref<HTMLElement>()

const { width } = useElementSize(containerRef)

const isNarrow = computed(() => width.value < 815)
</script>
```

隐藏源代码

## 禁用 [​](#禁用)

"禁用"属性决定颜色选择器是否完全禁用。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY29sb3ItcGlja2VyLXBhbmVsXG4gICAgdi1tb2RlbD1cImNvbG9yXCJcbiAgICBkaXNhYmxlZFxuICAgIHNob3ctYWxwaGFcbiAgICA6cHJlZGVmaW5lPVwicHJlZGVmaW5lQ29sb3JzXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGNvbG9yID0gcmVmKCcjZmY2OTAwJylcbmNvbnN0IHByZWRlZmluZUNvbG9ycyA9IFtcbiAgJyNmZjQ1MDAnLFxuICAnI2ZmOGMwMCcsXG4gICcjZmZkNzAwJyxcbiAgJyM5MGVlOTAnLFxuICAnIzAwY2VkMScsXG4gICcjMWU5MGZmJyxcbiAgJyNjNzE1ODUnLFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/color-picker-panel/disabled.vue)_

vue

```
<template>
  <el-color-picker-panel
    v-model="color"
    disabled
    show-alpha
    :predefine="predefineColors"
  />
</template>

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

const color = ref('#ff6900')
const predefineColors = [
  '#ff4500',
  '#ff8c00',
  '#ffd700',
  '#90ee90',
  '#00ced1',
  '#1e90ff',
  '#c71585',
]
</script>
```

隐藏源代码

## API [​](#api)

### 属性 [​](#属性)

| 方法名 | 详情 | 事件参数 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 绑定值 | `string` | — |
| border | 颜色选择器面板是否有边框 | `boolean` | true |
| disabled | 是否禁用 | `boolean` | false |
| show-alpha | 是否显示 alpha 滑块 | `boolean` | false |
| color-format | 写入 v-model 的颜色的格式 | `enum` | `enum` |
| predefine | 预定义颜色 | `array` | — |
| validate-event 2.11.7 | 是否触发表单验证 | `boolean` | true |
| hue-slider-class 2.13.6 | 类名将会传递给 hue-slider | `object` | ::: |
| hue-slider-style 2.13.6 | 样式将会传递给 hue-slider | `string` / `object` | ::: |

### 插槽 [​](#插槽)

| 方法名 | 详情 |
| --- | --- |
| footer | 输入框之后要附加的内容 |

### 对外暴露的方法 [​](#对外暴露的方法)

| 方法名 | 详情 | 事件参数 |
| --- | --- | --- |
| color | 当前色彩对象 | `object` |
| inputRef | 自定义 input ref | `object` |
| update 2.11.4 | 更新子组件 | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/color-picker-panel) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/color-picker-panel.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/color-picker-panel.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/62818957?v=4&size=64)](https://github.com/ZacharyBear)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/1472924?v=4&size=64)](https://github.com/hdwills)

[Checkbox 多选框](https://element-plus.org/zh-CN/component/checkbox)

[Color Picker 颜色选择器](https://element-plus.org/zh-CN/component/color-picker)




---
## [form/color-picker] Color Picker 颜色选择器
> 官方文档: https://element-plus.org/zh-CN/component/color-picker.html

---

# ColorPicker 颜色选择器 [​](#colorpicker-颜色选择器)

更新日志待解决

4

用于颜色选择，支持多种格式。

## 基础用法 [​](#基础用法)

使用 v-model 与 Vue 实例中的一个变量进行双向绑定，绑定的变量需要是字符串类型。

With default value

With no default value

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1jb2xvci1ibG9ja1wiPlxuICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPldpdGggZGVmYXVsdCB2YWx1ZTwvc3Bhbj5cbiAgICA8ZWwtY29sb3ItcGlja2VyIHYtbW9kZWw9XCJjb2xvcjFcIiAvPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cImRlbW8tY29sb3ItYmxvY2tcIj5cbiAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5XaXRoIG5vIGRlZmF1bHQgdmFsdWU8L3NwYW4+XG4gICAgPGVsLWNvbG9yLXBpY2tlciB2LW1vZGVsPVwiY29sb3IyXCIgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBjb2xvcjEgPSByZWYoJyM0MDlFRkYnKVxuY29uc3QgY29sb3IyID0gcmVmKClcbjwvc2NyaXB0PlxuXG48c3R5bGU+XG4uZGVtby1jb2xvci1ibG9jayB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG4gIG1hcmdpbi1ib3R0b206IDE2cHg7XG59XG4uZGVtby1jb2xvci1ibG9jayAuZGVtb25zdHJhdGlvbiB7XG4gIG1hcmdpbi1yaWdodDogMTZweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/color-picker/basic.vue)_

vue

```
<template>
  <div class="demo-color-block">
    <span class="demonstration">With default value</span>
    <el-color-picker v-model="color1" />
  </div>
  <div class="demo-color-block">
    <span class="demonstration">With no default value</span>
    <el-color-picker v-model="color2" />
  </div>
</template>

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

const color1 = ref('#409EFF')
const color2 = ref()
</script>

<style>
.demo-color-block {
  display: flex;
  align-items: center;
  margin-bottom: 16px;
}
.demo-color-block .demonstration {
  margin-right: 16px;
}
</style>
```

隐藏源代码

## 选择透明度 [​](#选择透明度)

ColorPicker 支持普通颜色，也支持带 Alpha 通道的颜色，通过`show-alpha`属性即可控制是否支持透明度的选择。 要启用 Alpha 选择，只需添加 `show-alpha` 属性。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY29sb3ItcGlja2VyIHYtbW9kZWw9XCJjb2xvclwiIHNob3ctYWxwaGEgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGNvbG9yID0gcmVmKCdyZ2JhKDE5LCAyMDYsIDEwMiwgMC44KScpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/color-picker/alpha.vue)_

vue

```
<template>
  <el-color-picker v-model="color" show-alpha />
</template>

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

const color = ref('rgba(19, 206, 102, 0.8)')
</script>
```

隐藏源代码

## 预定义颜色 [​](#预定义颜色)

ColorPicker 支持预定义颜色

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY29sb3ItcGlja2VyIHYtbW9kZWw9XCJjb2xvclwiIHNob3ctYWxwaGEgOnByZWRlZmluZT1cInByZWRlZmluZUNvbG9yc1wiIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBjb2xvciA9IHJlZigncmdiYSgyNTUsIDY5LCAwLCAwLjY4KScpXG5jb25zdCBwcmVkZWZpbmVDb2xvcnMgPSByZWYoW1xuICAnI2ZmNDUwMCcsXG4gICcjZmY4YzAwJyxcbiAgJyNmZmQ3MDAnLFxuICAnIzkwZWU5MCcsXG4gICcjMDBjZWQxJyxcbiAgJyMxZTkwZmYnLFxuICAnI2M3MTU4NScsXG4gICdyZ2JhKDI1NSwgNjksIDAsIDAuNjgpJyxcbiAgJ3JnYigyNTUsIDEyMCwgMCknLFxuICAnaHN2KDUxLCAxMDAsIDk4KScsXG4gICdoc3ZhKDEyMCwgNDAsIDk0LCAwLjUpJyxcbiAgJ2hzbCgxODEsIDEwMCUsIDM3JSknLFxuICAnaHNsYSgyMDksIDEwMCUsIDU2JSwgMC43MyknLFxuICAnI2M3MTU4NTc3Jyxcbl0pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/color-picker/predefined-color.vue)_

vue

```
<template>
  <el-color-picker v-model="color" show-alpha :predefine="predefineColors" />
</template>

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

const color = ref('rgba(255, 69, 0, 0.68)')
const predefineColors = ref([
  '#ff4500',
  '#ff8c00',
  '#ffd700',
  '#90ee90',
  '#00ced1',
  '#1e90ff',
  '#c71585',
  'rgba(255, 69, 0, 0.68)',
  'rgb(255, 120, 0)',
  'hsv(51, 100, 98)',
  'hsva(120, 40, 94, 0.5)',
  'hsl(181, 100%, 37%)',
  'hsla(209, 100%, 56%, 0.73)',
  '#c7158577',
])
</script>
```

隐藏源代码

## 不同尺寸 [​](#不同尺寸)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1jb2xvci1zaXplc1wiPlxuICAgIDxlbC1jb2xvci1waWNrZXIgdi1tb2RlbD1cImNvbG9yXCIgc2l6ZT1cImxhcmdlXCIgLz5cbiAgICA8ZWwtY29sb3ItcGlja2VyIHYtbW9kZWw9XCJjb2xvclwiIC8+XG4gICAgPGVsLWNvbG9yLXBpY2tlciB2LW1vZGVsPVwiY29sb3JcIiBzaXplPVwic21hbGxcIiAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGNvbG9yID0gcmVmKCcjNDA5RUZGJylcbjwvc2NyaXB0PlxuXG48c3R5bGU+XG4uZGVtby1jb2xvci1zaXplcyAuZWwtY29sb3ItcGlja2VyOm5vdCg6bGFzdC1jaGlsZCkge1xuICBtYXJnaW4tcmlnaHQ6IDE2cHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/color-picker/sizes.vue)_

vue

```
<template>
  <div class="demo-color-sizes">
    <el-color-picker v-model="color" size="large" />
    <el-color-picker v-model="color" />
    <el-color-picker v-model="color" size="small" />
  </div>
</template>

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

const color = ref('#409EFF')
</script>

<style>
.demo-color-sizes .el-color-picker:not(:last-child) {
  margin-right: 16px;
}
</style>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `string` | — |
| disabled | 是否禁用 | `boolean` | false |
| clearable 2.13.1 | 文本框可输入 | `boolean` | true |
| size | 尺寸 | `enum` | — |
| show-alpha | 是否支持透明度选择 | `boolean` | false |
| color-format | 写入 v-model 的颜色的格式 | `enum` | `enum` |
| popper-class | ColorPicker 下拉框的类名 | `string` / `object` | '' |
| popper-style 2.11.4 | ColorPicker 下拉面板的自定义样式 | `string` / `object` | — |
| predefine | 预定义颜色 | `array` | — |
| validate-event | 输入时是否触发表单的校验 | `boolean` | true |
| tabindex | ColorPicker 的 tabindex | `string` / `number` | 0 |
| aria-label a11y 2.7.2 | ColorPicker 的 aria-label | `string` | — |
| empty-values 2.10.3 | 组件的空值配置， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `array` | — |
| value-on-clear 2.10.3 | 清空选项的值， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `string` / `number` / `boolean` / `Function` | — |
| id | ColorPicker 的 id | `string` | — |
| teleported 2.7.2 | 是否将 popover 的下拉列表渲染至 body 下 | `boolean` | true |
| label a11y deprecated | ColorPicker 的 aria-label | `string` | — |
| persistent 2.10.5 | 当颜色选择器未激活且 persistent 为 false 时，颜色面板将被销毁。 | `boolean` | true |
| append-to 2.10.5 | 挂载到哪个 DOM 元素 | `CSSSelector` / `HTMLElement` | \- |

### Events [​](#events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 当绑定值变化时触发 | `Function` |
| active-change | 面板中当前显示的颜色发生改变时触发 | `Function` |
| focus 2.4.0 | 当获得焦点时触发 | `Function` |
| blur 2.4.0 | 当失去焦点时触发 | `Function` |
| clear 2.13.1 | 当点击清除按钮时触发 | `Function` |

### Exposes [​](#exposes)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| color | 当前色彩对象 | `object` |
| show 2.3.3 | 手动显示颜色选择器 | `Function` |
| hide 2.3.3 | 手动隐藏颜色选择器 | `Function` |
| focus 2.3.13 | 使 picker 获得焦点 | `Function` |
| blur 2.3.13 | 使 picker 失去焦点 | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/color-picker) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/color-picker.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/color-picker.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/83899365?v=4&size=64)](https://github.com/chensuifengran)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/31885971?v=4&size=64)](https://github.com/wonderl17)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/111559907?v=4&size=64)](https://github.com/JCL206312)[![](https://avatars.githubusercontent.com/u/26516275?v=4&size=64)](https://github.com/zhanghaifeng213)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/78132554?v=4&size=64)](https://github.com/momei-LJM)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/47178158?v=4&size=64)](https://github.com/Aaron-zon)[![](https://avatars.githubusercontent.com/u/43257608?v=4&size=64)](https://github.com/Liao-js)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/3360879?v=4&size=64)](https://github.com/xiterjia)[![](https://avatars.githubusercontent.com/u/25458528?v=4&size=64)](https://github.com/weidehai)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/17247526?v=4&size=64)](https://github.com/nabaonan)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)

[ColorPickerPanel 颜色选择器面板](https://element-plus.org/zh-CN/component/color-picker-panel)

[Date Picker Panel 日期选择器面板](https://element-plus.org/zh-CN/component/date-picker-panel)




---
## [form/date-picker-panel] DatePickerPanel 日期选择器面板
> 官方文档: https://element-plus.org/zh-CN/component/date-picker-panel.html

---

# DatePickerPane 日期选择器面板 beta [​](#datepickerpane-日期选择器面板)

更新日志待解决

2

`DatePickerPanel`是`DatePicker`的核心组件。

## 选择某一天 [​](#选择某一天)

以”日“为基本单位，基础的日期选择控件

2026 June

| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
| --- | --- | --- | --- | --- | --- | --- |
|
31

 |

1

 |

2

 |

3

 |

4

 |

5

 |

6

 |
|

7

 |

8

 |

9

 |

10

 |

11

 |

12

 |

13

 |
|

14

 |

15

 |

16

 |

17

 |

18

 |

19

 |

20

 |
|

21

 |

22

 |

23

 |

24

 |

25

 |

26

 |

27

 |
|

28

 |

29

 |

30

 |

1

 |

2

 |

3

 |

4

 |
|

5

 |

6

 |

7

 |

8

 |

9

 |

10

 |

11

 |

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBqdXN0aWZ5LWNlbnRlclwiPlxuICAgIDxlbC1kYXRlLXBpY2tlci1wYW5lbCB2LW1vZGVsPVwidmFsdWVcIiAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKClcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker-panel/basic.vue)_

vue

```
<template>
  <div class="flex justify-center">
    <el-date-picker-panel v-model="value" />
  </div>
</template>

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

const value = ref()
</script>
```

隐藏源代码

## 边框 [​](#边框)

默认情况下，边框是默认的，如果你不想要边框请参考示例。 例如，`DatePicker`不继承`border`。

No border:

2026 June

| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
| --- | --- | --- | --- | --- | --- | --- |
|
31

 |

1

 |

2

 |

3

 |

4

 |

5

 |

6

 |
|

7

 |

8

 |

9

 |

10

 |

11

 |

12

 |

13

 |
|

14

 |

15

 |

16

 |

17

 |

18

 |

19

 |

20

 |
|

21

 |

22

 |

23

 |

24

 |

25

 |

26

 |

27

 |
|

28

 |

29

 |

30

 |

1

 |

2

 |

3

 |

4

 |
|

5

 |

6

 |

7

 |

8

 |

9

 |

10

 |

11

 |

2026 June

| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
| --- | --- | --- | --- | --- | --- | --- |
|
31

 |

1

 |

2

 |

3

 |

4

 |

5

 |

6

 |
|

7

 |

8

 |

9

 |

10

 |

11

 |

12

 |

13

 |
|

14

 |

15

 |

16

 |

17

 |

18

 |

19

 |

20

 |
|

21

 |

22

 |

23

 |

24

 |

25

 |

26

 |

27

 |
|

28

 |

29

 |

30

 |

1

 |

2

 |

3

 |

4

 |
|

5

 |

6

 |

7

 |

8

 |

9

 |

10

 |

11

 |

TS

JS

_[](https://element-plus.run/?extra_packages=%40vueuse%2Fcore#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2XG4gICAgcmVmPVwiY29udGFpbmVyUmVmXCJcbiAgICA6Y2xhc3M9XCJbJ2RhdGUtcGlja2VyLS1leGFtcGxlJywgeyAnaXMtbmFycm93JzogaXNOYXJyb3cgfV1cIlxuICA+XG4gICAgPGRpdiBjbGFzcz1cInRleHQtY2VudGVyXCI+Tm8gYm9yZGVyOjwvZGl2PlxuICAgIDxlbC1kaXZpZGVyIC8+XG4gICAgPGRpdiBjbGFzcz1cImRhdGUtcGlja2VyLS1mbGV4LWNvbnRhaW5lclwiPlxuICAgICAgPGRpdiBjbGFzcz1cInAtWzIwcHhdXCI+XG4gICAgICAgIDxlbC1kYXRlLXBpY2tlci1wYW5lbCB2LW1vZGVsPVwidmFsdWVcIiA6Ym9yZGVyPVwiZmFsc2VcIiAvPlxuICAgICAgPC9kaXY+XG4gICAgICA8ZWwtZGl2aWRlclxuICAgICAgICBjbGFzcz1cImRpdmlkZXJcIlxuICAgICAgICA6ZGlyZWN0aW9uPVwiaXNOYXJyb3cgPyAnaG9yaXpvbnRhbCcgOiAndmVydGljYWwnXCJcbiAgICAgIC8+XG4gICAgICA8ZWwtY2FyZD5cbiAgICAgICAgPGVsLWRhdGUtcGlja2VyLXBhbmVsIHYtbW9kZWw9XCJ2YWx1ZVwiIDpib3JkZXI9XCJmYWxzZVwiIC8+XG4gICAgICA8L2VsLWNhcmQ+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IGNvbXB1dGVkLCByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyB1c2VFbGVtZW50U2l6ZSB9IGZyb20gJ0B2dWV1c2UvY29yZSdcblxuY29uc3QgdmFsdWUgPSByZWYoKVxuY29uc3QgY29udGFpbmVyUmVmID0gcmVmPEhUTUxFbGVtZW50PigpXG5cbmNvbnN0IHsgd2lkdGggfSA9IHVzZUVsZW1lbnRTaXplKGNvbnRhaW5lclJlZilcblxuY29uc3QgaXNOYXJyb3cgPSBjb21wdXRlZCgoKSA9PiB3aWR0aC52YWx1ZSA8IDgxNSlcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRhdGUtcGlja2VyLS1mbGV4LWNvbnRhaW5lciB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGZsZXgtd3JhcDogd3JhcDtcbiAgZ2FwOiAxNnB4O1xuICBqdXN0aWZ5LWNvbnRlbnQ6IGNlbnRlcjtcbn1cbi5kaXZpZGVyIHtcbiAgaGVpZ2h0OiBhdXRvO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker-panel/border.vue)_

vue

```
<template>
  <div
    ref="containerRef"
    :class="['date-picker--example', { 'is-narrow': isNarrow }]"
  >
    <div class="text-center">No border:</div>
    <el-divider />
    <div class="date-picker--flex-container">
      <div class="p-[20px]">
        <el-date-picker-panel v-model="value" :border="false" />
      </div>
      <el-divider
        class="divider"
        :direction="isNarrow ? 'horizontal' : 'vertical'"
      />
      <el-card>
        <el-date-picker-panel v-model="value" :border="false" />
      </el-card>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'
import { useElementSize } from '@vueuse/core'

const value = ref()
const containerRef = ref<HTMLElement>()

const { width } = useElementSize(containerRef)

const isNarrow = computed(() => width.value < 815)
</script>

<style scoped>
.date-picker--flex-container {
  display: flex;
  flex-wrap: wrap;
  gap: 16px;
  justify-content: center;
}
.divider {
  height: auto;
}
</style>
```

隐藏源代码

## 禁用 [​](#禁用)

"禁用"属性决定日期选择器是否完全禁用。

EnabledDisabled

2026 June

| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
| --- | --- | --- | --- | --- | --- | --- |
|
31

 |

1

 |

2

 |

3

 |

4

 |

5

 |

6

 |
|

7

 |

8

 |

9

 |

10

 |

11

 |

12

 |

13

 |
|

14

 |

15

 |

16

 |

17

 |

18

 |

19

 |

20

 |
|

21

 |

22

 |

23

 |

24

 |

25

 |

26

 |

27

 |
|

28

 |

29

 |

30

 |

1

 |

2

 |

3

 |

4

 |
|

5

 |

6

 |

7

 |

8

 |

9

 |

10

 |

11

 |

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LWNvbCBpdGVtcy1jZW50ZXJcIj5cbiAgICA8ZWwtc3dpdGNoXG4gICAgICB2LW1vZGVsPVwiZGlzYWJsZWRcIlxuICAgICAgYWN0aXZlLXRleHQ9XCJEaXNhYmxlZFwiXG4gICAgICBpbmFjdGl2ZS10ZXh0PVwiRW5hYmxlZFwiXG4gICAgLz5cbiAgICA8ZWwtZGF0ZS1waWNrZXItcGFuZWwgdi1tb2RlbD1cInZhbHVlXCIgOmRpc2FibGVkPVwiZGlzYWJsZWRcIiAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKClcbmNvbnN0IGRpc2FibGVkID0gcmVmKHRydWUpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker-panel/disabled.vue)_

vue

```
<template>
  <div class="flex flex-col items-center">
    <el-switch
      v-model="disabled"
      active-text="Disabled"
      inactive-text="Enabled"
    />
    <el-date-picker-panel v-model="value" :disabled="disabled" />
  </div>
</template>

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

const value = ref()
const disabled = ref(true)
</script>
```

隐藏源代码

## 展示类型 [​](#展示类型)

时间面板的类型由 `type` 属性指定。

Type:

date

2026 June

| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
| --- | --- | --- | --- | --- | --- | --- |
|
31

 |

1

 |

2

 |

3

 |

4

 |

5

 |

6

 |
|

7

 |

8

 |

9

 |

10

 |

11

 |

12

 |

13

 |
|

14

 |

15

 |

16

 |

17

 |

18

 |

19

 |

20

 |
|

21

 |

22

 |

23

 |

24

 |

25

 |

26

 |

27

 |
|

28

 |

29

 |

30

 |

1

 |

2

 |

3

 |

4

 |
|

5

 |

6

 |

7

 |

8

 |

9

 |

10

 |

11

 |

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJmbGV4IGdhcC00XCI+XG4gICAgICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LWNvbCBiYXNpcy0xNTBweCBnYXAtMVwiPlxuICAgICAgICA8c3Bhbj5UeXBlOjwvc3Bhbj5cbiAgICAgICAgPGVsLXNlbGVjdCB2LW1vZGVsPVwidHlwZVwiPlxuICAgICAgICAgIDxlbC1vcHRpb25cbiAgICAgICAgICAgIHYtZm9yPVwib3B0aW9uVHlwZSBpbiB0eXBlc1wiXG4gICAgICAgICAgICA6a2V5PVwib3B0aW9uVHlwZVwiXG4gICAgICAgICAgICA6dmFsdWU9XCJvcHRpb25UeXBlXCJcbiAgICAgICAgICAvPlxuICAgICAgICA8L2VsLXNlbGVjdD5cbiAgICAgIDwvZGl2PlxuICAgIDwvZGl2PlxuICAgIDxlbC1kaXZpZGVyIC8+XG4gICAgPGRpdiBjbGFzcz1cImZsZXgganVzdGlmeS1jZW50ZXJcIj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlci1wYW5lbCB2LW1vZGVsPVwiZGF0ZVwiIDp0eXBlPVwidHlwZVwiIC8+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiwgd2F0Y2ggfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgRGF0ZVBpY2tlclR5cGUgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGRhdGUgPSByZWYoKVxuY29uc3QgdHlwZSA9IHJlZjxEYXRlUGlja2VyVHlwZT4oJ2RhdGUnKVxuXG53YXRjaCh0eXBlLCAoKSA9PiB7XG4gIGRhdGUudmFsdWUgPSB1bmRlZmluZWRcbn0pXG5cbmNvbnN0IHR5cGVzOiBEYXRlUGlja2VyVHlwZVtdID0gW1xuICAneWVhcicsXG4gICd5ZWFycycsXG4gICdtb250aCcsXG4gICdtb250aHMnLFxuICAnZGF0ZScsXG4gICdkYXRlcycsXG4gICd3ZWVrJyxcbiAgJ2RhdGV0aW1lJyxcbiAgJ2RhdGV0aW1lcmFuZ2UnLFxuICAnZGF0ZXJhbmdlJyxcbiAgJ21vbnRocmFuZ2UnLFxuICAneWVhcnJhbmdlJyxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker-panel/all-types.vue)_

vue

```
<template>
  <div>
    <div class="flex gap-4">
      <div class="flex flex-col basis-150px gap-1">
        <span>Type:</span>
        <el-select v-model="type">
          <el-option
            v-for="optionType in types"
            :key="optionType"
            :value="optionType"
          />
        </el-select>
      </div>
    </div>
    <el-divider />
    <div class="flex justify-center">
      <el-date-picker-panel v-model="date" :type="type" />
    </div>
  </div>
</template>

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

import type { DatePickerType } from 'element-plus'

const date = ref()
const type = ref<DatePickerType>('date')

watch(type, () => {
  date.value = undefined
})

const types: DatePickerType[] = [
  'year',
  'years',
  'month',
  'months',
  'date',
  'dates',
  'week',
  'datetime',
  'datetimerange',
  'daterange',
  'monthrange',
  'yearrange',
]
</script>
```

隐藏源代码

## 本地化 [​](#本地化)

由于 Element Plus 的默认语言为英语，如果你需要设置其它的语言，请参考[国际化](https://element-plus.org/zh-CN/guide/i18n)文档。

要注意的是：日期相关的文字（月份，每一周的第一天等等） 也都进行了本地化配置。

## 应用开发接口（API） [​](#应用开发接口-api)

### 属性 [​](#属性)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 绑定值，如果是 `range` 选择器，数组长度应为 2 | `number` / `string` / `Date` / `array` | '' |
| border | 日期选择器是否有边框 | `boolean` | true |
| disabled | 禁用 | `boolean` | false |
| clearable | 是否显示清除按钮 | `boolean` | true |
| editable 2.13.0 | 文本框可输入 | `boolean` | true |
| type | 选择器类型，默认是普通选择器 | `enum` | date |
| default-value | 可选，选择器打开时默认显示的时间 | `object` | — |
| default-time | 范围选择时选中日期所使用的当日内具体时刻 | `object` | — |
| value-format | 可选，绑定值的格式。 不指定则绑定值为 Date 对象 | `string` | — |
| date-format | 可选，输入框内部面板中显示的日期格式 | `string` see [date formats](https://day.js.org/docs/en/display/format) | YYYY-MM-DD |
| time-format | 可选，输入框内部面板中显示的时间格式 | `string` see [date formats](https://day.js.org/docs/en/display/format) | HH:mm:ss |
| unlink-panels | 在范围选择器里取消两个日期面板之间的联动 | `boolean` | false |
| single-panel 2.14.0 | 在范围选择器中只显示一个面板 | `boolean` | false |
| disabled-date | 一个用来判断该日期是否被禁用的函数，接受一个 Date 对象作为参数。 应该返回一个 Boolean 值。 | `Function` | — |
| shortcuts | 设置快捷选项，需要传入数组对象 | `array` | \[\] |
| cell-class-name | 设置自定义类名 | `Function` | — |
| show-footer | 是否在日期选择器中显示页脚 `enum` | `boolean` | false |
| show-confirm | 是否显示确定按钮 | `boolean` | false |
| show-week-number | 显示周数(除周外) | `boolean` | false |

### Events [​](#events)

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| calendar-change | 在日历所选日期更改时触发 仅限“range”类型。 | `Function` |
| panel-change | 当日期面板改变时触发。 | `Function` |
| clear 2.13.1 | 当点击清除按钮时触发 | `Function` |

### 插槽 [​](#插槽)

| 名称 | 详情 |
| --- | --- |
| default | 自定义单元格内容 |
| prev-month | 上个月的图标 |
| next-month | 下个月的图标 |
| prev-year | 上一年图标 |
| next-year | 下一年图标 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/date-picker-panel) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/date-picker-panel.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/date-picker-panel.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/24487727?v=4&size=64)](https://github.com/LostElkByte)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/7835220?v=4&size=64)](https://github.com/tjyuanpeng)[![](https://avatars.githubusercontent.com/u/70922464?v=4&size=64)](https://github.com/shanecranor)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/110156942?v=4&size=64)](https://github.com/a92126)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)

[Color Picker 颜色选择器](https://element-plus.org/zh-CN/component/color-picker)

[Date Picker 日期选择器](https://element-plus.org/zh-CN/component/date-picker)




---
## [form/date-picker] Date Picker 日期选择器
> 官方文档: https://element-plus.org/zh-CN/component/date-picker.html

---

# DatePicker 日期选择器 [​](#datepicker-日期选择器)

更新日志待解决

66

用于选择或输入日期

## 选择某一天 [​](#选择某一天)

以”日“为基本单位，基础的日期选择控件

基本单位由 `type` 属性指定。 通过 `shortcuts` 配置快捷选项， 通过 `disabledDate` 函数，来设置禁用掉的日期。

largedefaultsmall

Default

Picker with quick options

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInNpemVcIiBhcmlhLWxhYmVsPVwic2l6ZSBjb250cm9sXCIgY2xhc3M9XCJtYi00XCI+XG4gICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cImxhcmdlXCI+bGFyZ2U8L2VsLXJhZGlvLWJ1dHRvbj5cbiAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwiZGVmYXVsdFwiPmRlZmF1bHQ8L2VsLXJhZGlvLWJ1dHRvbj5cbiAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwic21hbGxcIj5zbWFsbDwvZWwtcmFkaW8tYnV0dG9uPlxuICA8L2VsLXJhZGlvLWdyb3VwPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+RGVmYXVsdDwvc3Bhbj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgICAgdHlwZT1cImRhdGVcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSBkYXlcIlxuICAgICAgICA6c2l6ZT1cInNpemVcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPlBpY2tlciB3aXRoIHF1aWNrIG9wdGlvbnM8L3NwYW4+XG4gICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgdi1tb2RlbD1cInZhbHVlMlwiXG4gICAgICAgIHR5cGU9XCJkYXRlXCJcbiAgICAgICAgcGxhY2Vob2xkZXI9XCJQaWNrIGEgZGF5XCJcbiAgICAgICAgOmRpc2FibGVkLWRhdGU9XCJkaXNhYmxlZERhdGVcIlxuICAgICAgICA6c2hvcnRjdXRzPVwic2hvcnRjdXRzXCJcbiAgICAgICAgOnNpemU9XCJzaXplXCJcbiAgICAgIC8+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3Qgc2l6ZSA9IHJlZjwnZGVmYXVsdCcgfCAnbGFyZ2UnIHwgJ3NtYWxsJz4oJ2RlZmF1bHQnKVxuXG5jb25zdCB2YWx1ZTEgPSByZWYoJycpXG5jb25zdCB2YWx1ZTIgPSByZWYoJycpXG5cbmNvbnN0IHNob3J0Y3V0cyA9IFtcbiAge1xuICAgIHRleHQ6ICdUb2RheScsXG4gICAgdmFsdWU6IG5ldyBEYXRlKCksXG4gIH0sXG4gIHtcbiAgICB0ZXh0OiAnWWVzdGVyZGF5JyxcbiAgICB2YWx1ZTogKCkgPT4ge1xuICAgICAgY29uc3QgZGF0ZSA9IG5ldyBEYXRlKClcbiAgICAgIGRhdGUuc2V0VGltZShkYXRlLmdldFRpbWUoKSAtIDM2MDAgKiAxMDAwICogMjQpXG4gICAgICByZXR1cm4gZGF0ZVxuICAgIH0sXG4gIH0sXG4gIHtcbiAgICB0ZXh0OiAnQSB3ZWVrIGFnbycsXG4gICAgdmFsdWU6ICgpID0+IHtcbiAgICAgIGNvbnN0IGRhdGUgPSBuZXcgRGF0ZSgpXG4gICAgICBkYXRlLnNldFRpbWUoZGF0ZS5nZXRUaW1lKCkgLSAzNjAwICogMTAwMCAqIDI0ICogNylcbiAgICAgIHJldHVybiBkYXRlXG4gICAgfSxcbiAgfSxcbl1cblxuY29uc3QgZGlzYWJsZWREYXRlID0gKHRpbWU6IERhdGUpID0+IHtcbiAgcmV0dXJuIHRpbWUuZ2V0VGltZSgpID4gRGF0ZS5ub3coKVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1kYXRlLXBpY2tlciB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIHdpZHRoOiAxMDAlO1xuICBwYWRkaW5nOiAwO1xuICBmbGV4LXdyYXA6IHdyYXA7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyIC5ibG9jayB7XG4gIHBhZGRpbmc6IDEuNXJlbSAwO1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG4gIGJvcmRlci1yaWdodDogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG4gIGZsZXg6IDE7XG4gIG1pbi13aWR0aDogMzAwcHg7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyIC5ibG9jazpsYXN0LWNoaWxkIHtcbiAgYm9yZGVyLXJpZ2h0OiBub25lO1xufVxuXG4uZGVtby1kYXRlLXBpY2tlciAuZGVtb25zdHJhdGlvbiB7XG4gIGRpc3BsYXk6IGJsb2NrO1xuICBjb2xvcjogdmFyKC0tZWwtdGV4dC1jb2xvci1zZWNvbmRhcnkpO1xuICBmb250LXNpemU6IDE0cHg7XG4gIG1hcmdpbi1ib3R0b206IDFyZW07XG59XG5cbkBtZWRpYSBzY3JlZW4gYW5kIChtYXgtd2lkdGg6IDc2OHB4KSB7XG4gIC5kZW1vLWRhdGUtcGlja2VyIC5ibG9jayB7XG4gICAgZmxleDogMCAwIDEwMCU7XG4gICAgcGFkZGluZzogMXJlbSAwO1xuICAgIG1pbi13aWR0aDogYXV0bztcbiAgICBib3JkZXItcmlnaHQ6IG5vbmU7XG4gICAgYm9yZGVyLWJvdHRvbTogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG4gIH1cblxuICAuZGVtby1kYXRlLXBpY2tlciAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gICAgYm9yZGVyLWJvdHRvbTogbm9uZTtcbiAgfVxufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/enter-date.vue)_

vue

```
<template>
  <el-radio-group v-model="size" aria-label="size control" class="mb-4">
    <el-radio-button value="large">large</el-radio-button>
    <el-radio-button value="default">default</el-radio-button>
    <el-radio-button value="small">small</el-radio-button>
  </el-radio-group>
  <div class="demo-date-picker">
    <div class="block">
      <span class="demonstration">Default</span>
      <el-date-picker
        v-model="value1"
        type="date"
        placeholder="Pick a day"
        :size="size"
      />
    </div>
    <div class="block">
      <span class="demonstration">Picker with quick options</span>
      <el-date-picker
        v-model="value2"
        type="date"
        placeholder="Pick a day"
        :disabled-date="disabledDate"
        :shortcuts="shortcuts"
        :size="size"
      />
    </div>
  </div>
</template>

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

const size = ref<'default' | 'large' | 'small'>('default')

const value1 = ref('')
const value2 = ref('')

const shortcuts = [
  {
    text: 'Today',
    value: new Date(),
  },
  {
    text: 'Yesterday',
    value: () => {
      const date = new Date()
      date.setTime(date.getTime() - 3600 * 1000 * 24)
      return date
    },
  },
  {
    text: 'A week ago',
    value: () => {
      const date = new Date()
      date.setTime(date.getTime() - 3600 * 1000 * 24 * 7)
      return date
    },
  },
]

const disabledDate = (time: Date) => {
  return time.getTime() > Date.now()
}
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}

.demo-date-picker .block {
  padding: 1.5rem 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
  min-width: 300px;
}

.demo-date-picker .block:last-child {
  border-right: none;
}

.demo-date-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 1rem;
}

@media screen and (max-width: 768px) {
  .demo-date-picker .block {
    flex: 0 0 100%;
    padding: 1rem 0;
    min-width: auto;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-date-picker .block:last-child {
    border-bottom: none;
  }
}
</style>
```

隐藏源代码

## 其他日期单位 [​](#其他日期单位)

通过扩展基础的日期选择，可以选择周、月、年或多个日期

Week

Dates

Year

Years

Month

Months

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxkaXYgY2xhc3M9XCJjb250YWluZXJcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5XZWVrPC9zcGFuPlxuICAgICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgICAgICB0eXBlPVwid2Vla1wiXG4gICAgICAgICAgZm9ybWF0PVwiW1dlZWtdIHd3XCJcbiAgICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSB3ZWVrXCJcbiAgICAgICAgLz5cbiAgICAgIDwvZGl2PlxuICAgICAgPGRpdiBjbGFzcz1cImJsb2NrXCI+XG4gICAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPkRhdGVzPC9zcGFuPlxuICAgICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgICAgICB0eXBlPVwiZGF0ZXNcIlxuICAgICAgICAgIHBsYWNlaG9sZGVyPVwiUGljayBvbmUgb3IgbW9yZSBkYXRlc1wiXG4gICAgICAgIC8+XG4gICAgICA8L2Rpdj5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwiY29udGFpbmVyXCI+XG4gICAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+WWVhcjwvc3Bhbj5cbiAgICAgICAgPGVsLWRhdGUtcGlja2VyXG4gICAgICAgICAgdi1tb2RlbD1cInZhbHVlM1wiXG4gICAgICAgICAgdHlwZT1cInllYXJcIlxuICAgICAgICAgIHBsYWNlaG9sZGVyPVwiUGljayBhIHllYXJcIlxuICAgICAgICAvPlxuICAgICAgPC9kaXY+XG4gICAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+WWVhcnM8L3NwYW4+XG4gICAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTRcIlxuICAgICAgICAgIHR5cGU9XCJ5ZWFyc1wiXG4gICAgICAgICAgcGxhY2Vob2xkZXI9XCJQaWNrIG9uZSBvciBtb3JlIHllYXJzXCJcbiAgICAgICAgLz5cbiAgICAgIDwvZGl2PlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJjb250YWluZXJcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5Nb250aDwvc3Bhbj5cbiAgICAgICAgPGVsLWRhdGUtcGlja2VyXG4gICAgICAgICAgdi1tb2RlbD1cInZhbHVlNVwiXG4gICAgICAgICAgdHlwZT1cIm1vbnRoXCJcbiAgICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSBtb250aFwiXG4gICAgICAgIC8+XG4gICAgICA8L2Rpdj5cbiAgICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5Nb250aHM8L3NwYW4+XG4gICAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTZcIlxuICAgICAgICAgIHR5cGU9XCJtb250aHNcIlxuICAgICAgICAgIHBsYWNlaG9sZGVyPVwiUGljayBvbmUgb3IgbW9yZSBtb250aHNcIlxuICAgICAgICAvPlxuICAgICAgPC9kaXY+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUxID0gcmVmKCcnKVxuY29uc3QgdmFsdWUyID0gcmVmKCcnKVxuY29uc3QgdmFsdWUzID0gcmVmKCcnKVxuY29uc3QgdmFsdWU0ID0gcmVmKCcnKVxuY29uc3QgdmFsdWU1ID0gcmVmKCcnKVxuY29uc3QgdmFsdWU2ID0gcmVmKCcnKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1kYXRlLXBpY2tlciB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIHdpZHRoOiAxMDAlO1xuICBwYWRkaW5nOiAwO1xuICBmbGV4LXdyYXA6IHdyYXA7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyIC5jb250YWluZXIge1xuICBmbGV4OiAxO1xuICBtaW4td2lkdGg6IDMwMHB4O1xuICBib3JkZXItcmlnaHQ6IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xufVxuXG4uZGVtby1kYXRlLXBpY2tlciAuY29udGFpbmVyOmxhc3QtY2hpbGQge1xuICBib3JkZXItcmlnaHQ6IG5vbmU7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyIC5ibG9jayB7XG4gIHBhZGRpbmc6IDEuNXJlbSAwO1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyIC5jb250YWluZXIgLmJsb2NrOmxhc3QtY2hpbGQge1xuICBib3JkZXItdG9wOiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbn1cblxuLmRlbW8tZGF0ZS1waWNrZXIgLmRlbW9uc3RyYXRpb24ge1xuICBkaXNwbGF5OiBibG9jaztcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbiAgZm9udC1zaXplOiAxNHB4O1xuICBtYXJnaW4tYm90dG9tOiAxcmVtO1xufVxuXG5AbWVkaWEgc2NyZWVuIGFuZCAobWF4LXdpZHRoOiA3NjhweCkge1xuICAuZGVtby1kYXRlLXBpY2tlciAuY29udGFpbmVyIHtcbiAgICBmbGV4OiAwIDAgMTAwJTtcbiAgICBtaW4td2lkdGg6IGF1dG87XG4gICAgYm9yZGVyLXJpZ2h0OiBub25lO1xuICAgIGJvcmRlci1ib3R0b206IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICB9XG5cbiAgLmRlbW8tZGF0ZS1waWNrZXIgLmNvbnRhaW5lcjpsYXN0LWNoaWxkIHtcbiAgICBib3JkZXItYm90dG9tOiBub25lO1xuICB9XG5cbiAgLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrIHtcbiAgICBwYWRkaW5nOiAxcmVtIDA7XG4gIH1cblxuICAuZGVtby1kYXRlLXBpY2tlciAuY29udGFpbmVyIC5ibG9jazpsYXN0LWNoaWxkIHtcbiAgICBib3JkZXItdG9wOiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgfVxufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/other-measurements.vue)_

vue

```
<template>
  <div class="demo-date-picker">
    <div class="container">
      <div class="block">
        <span class="demonstration">Week</span>
        <el-date-picker
          v-model="value1"
          type="week"
          format="[Week] ww"
          placeholder="Pick a week"
        />
      </div>
      <div class="block">
        <span class="demonstration">Dates</span>
        <el-date-picker
          v-model="value2"
          type="dates"
          placeholder="Pick one or more dates"
        />
      </div>
    </div>
    <div class="container">
      <div class="block">
        <span class="demonstration">Year</span>
        <el-date-picker
          v-model="value3"
          type="year"
          placeholder="Pick a year"
        />
      </div>
      <div class="block">
        <span class="demonstration">Years</span>
        <el-date-picker
          v-model="value4"
          type="years"
          placeholder="Pick one or more years"
        />
      </div>
    </div>
    <div class="container">
      <div class="block">
        <span class="demonstration">Month</span>
        <el-date-picker
          v-model="value5"
          type="month"
          placeholder="Pick a month"
        />
      </div>
      <div class="block">
        <span class="demonstration">Months</span>
        <el-date-picker
          v-model="value6"
          type="months"
          placeholder="Pick one or more months"
        />
      </div>
    </div>
  </div>
</template>

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

const value1 = ref('')
const value2 = ref('')
const value3 = ref('')
const value4 = ref('')
const value5 = ref('')
const value6 = ref('')
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}

.demo-date-picker .container {
  flex: 1;
  min-width: 300px;
  border-right: solid 1px var(--el-border-color);
}

.demo-date-picker .container:last-child {
  border-right: none;
}

.demo-date-picker .block {
  padding: 1.5rem 0;
  text-align: center;
}

.demo-date-picker .container .block:last-child {
  border-top: solid 1px var(--el-border-color);
}

.demo-date-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 1rem;
}

@media screen and (max-width: 768px) {
  .demo-date-picker .container {
    flex: 0 0 100%;
    min-width: auto;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-date-picker .container:last-child {
    border-bottom: none;
  }

  .demo-date-picker .block {
    padding: 1rem 0;
  }

  .demo-date-picker .container .block:last-child {
    border-top: solid 1px var(--el-border-color);
  }
}
</style>
```

隐藏源代码

## 选择一段时间 [​](#选择一段时间)

你可以通过如下例子来学习如何设置一个日期范围选择器。

在选择日期范围时，默认情况下左右面板会联动。 如果希望两个面板各自独立切换当前月份，可以使用 `unlink-panels` 属性解除联动。

largedefaultsmall

Default

To

With quick options

To

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInNpemVcIiBhcmlhLWxhYmVsPVwic2l6ZSBjb250cm9sXCIgY2xhc3M9XCJtYi00XCI+XG4gICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cImxhcmdlXCI+bGFyZ2U8L2VsLXJhZGlvLWJ1dHRvbj5cbiAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwiZGVmYXVsdFwiPmRlZmF1bHQ8L2VsLXJhZGlvLWJ1dHRvbj5cbiAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwic21hbGxcIj5zbWFsbDwvZWwtcmFkaW8tYnV0dG9uPlxuICA8L2VsLXJhZGlvLWdyb3VwPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+RGVmYXVsdDwvc3Bhbj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgICAgdHlwZT1cImRhdGVyYW5nZVwiXG4gICAgICAgIHJhbmdlLXNlcGFyYXRvcj1cIlRvXCJcbiAgICAgICAgc3RhcnQtcGxhY2Vob2xkZXI9XCJTdGFydCBkYXRlXCJcbiAgICAgICAgZW5kLXBsYWNlaG9sZGVyPVwiRW5kIGRhdGVcIlxuICAgICAgICA6c2l6ZT1cInNpemVcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPldpdGggcXVpY2sgb3B0aW9uczwvc3Bhbj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgICAgdHlwZT1cImRhdGVyYW5nZVwiXG4gICAgICAgIHVubGluay1wYW5lbHNcbiAgICAgICAgcmFuZ2Utc2VwYXJhdG9yPVwiVG9cIlxuICAgICAgICBzdGFydC1wbGFjZWhvbGRlcj1cIlN0YXJ0IGRhdGVcIlxuICAgICAgICBlbmQtcGxhY2Vob2xkZXI9XCJFbmQgZGF0ZVwiXG4gICAgICAgIDpzaG9ydGN1dHM9XCJzaG9ydGN1dHNcIlxuICAgICAgICA6c2l6ZT1cInNpemVcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBzaXplID0gcmVmPCdkZWZhdWx0JyB8ICdsYXJnZScgfCAnc21hbGwnPignZGVmYXVsdCcpXG5cbmNvbnN0IHZhbHVlMSA9IHJlZignJylcbmNvbnN0IHZhbHVlMiA9IHJlZignJylcblxuY29uc3Qgc2hvcnRjdXRzID0gW1xuICB7XG4gICAgdGV4dDogJ0xhc3Qgd2VlaycsXG4gICAgdmFsdWU6ICgpID0+IHtcbiAgICAgIGNvbnN0IGVuZCA9IG5ldyBEYXRlKClcbiAgICAgIGNvbnN0IHN0YXJ0ID0gbmV3IERhdGUoKVxuICAgICAgc3RhcnQuc2V0VGltZShzdGFydC5nZXRUaW1lKCkgLSAzNjAwICogMTAwMCAqIDI0ICogNylcbiAgICAgIHJldHVybiBbc3RhcnQsIGVuZF1cbiAgICB9LFxuICB9LFxuICB7XG4gICAgdGV4dDogJ0xhc3QgbW9udGgnLFxuICAgIHZhbHVlOiAoKSA9PiB7XG4gICAgICBjb25zdCBlbmQgPSBuZXcgRGF0ZSgpXG4gICAgICBjb25zdCBzdGFydCA9IG5ldyBEYXRlKClcbiAgICAgIHN0YXJ0LnNldFRpbWUoc3RhcnQuZ2V0VGltZSgpIC0gMzYwMCAqIDEwMDAgKiAyNCAqIDMwKVxuICAgICAgcmV0dXJuIFtzdGFydCwgZW5kXVxuICAgIH0sXG4gIH0sXG4gIHtcbiAgICB0ZXh0OiAnTGFzdCAzIG1vbnRocycsXG4gICAgdmFsdWU6ICgpID0+IHtcbiAgICAgIGNvbnN0IGVuZCA9IG5ldyBEYXRlKClcbiAgICAgIGNvbnN0IHN0YXJ0ID0gbmV3IERhdGUoKVxuICAgICAgc3RhcnQuc2V0VGltZShzdGFydC5nZXRUaW1lKCkgLSAzNjAwICogMTAwMCAqIDI0ICogOTApXG4gICAgICByZXR1cm4gW3N0YXJ0LCBlbmRdXG4gICAgfSxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tZGF0ZS1waWNrZXIge1xuICBkaXNwbGF5OiBmbGV4O1xuICB3aWR0aDogMTAwJTtcbiAgcGFkZGluZzogMDtcbiAgZmxleC13cmFwOiB3cmFwO1xufVxuXG4uZGVtby1kYXRlLXBpY2tlciAuYmxvY2sge1xuICBwYWRkaW5nOiAxLjVyZW0gMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBib3JkZXItcmlnaHQ6IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICBmbGV4OiAxO1xuICBtaW4td2lkdGg6IDQwMHB4O1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LWRpcmVjdGlvbjogY29sdW1uO1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xufVxuXG4uZGVtby1kYXRlLXBpY2tlciAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gIGJvcmRlci1yaWdodDogbm9uZTtcbn1cblxuLmRlbW8tZGF0ZS1waWNrZXIgLmRlbW9uc3RyYXRpb24ge1xuICBkaXNwbGF5OiBibG9jaztcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbiAgZm9udC1zaXplOiAxNHB4O1xuICBtYXJnaW4tYm90dG9tOiAxcmVtO1xufVxuXG5AbWVkaWEgc2NyZWVuIGFuZCAobWF4LXdpZHRoOiAxMjAwcHgpIHtcbiAgLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrIHtcbiAgICBmbGV4OiAwIDAgMTAwJTtcbiAgICBwYWRkaW5nOiAxcmVtIDA7XG4gICAgbWluLXdpZHRoOiBhdXRvO1xuICAgIGJvcmRlci1yaWdodDogbm9uZTtcbiAgICBib3JkZXItYm90dG9tOiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgfVxuXG4gIC5kZW1vLWRhdGUtcGlja2VyIC5ibG9jazpsYXN0LWNoaWxkIHtcbiAgICBib3JkZXItYm90dG9tOiBub25lO1xuICB9XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/date-range.vue)_

vue

```
<template>
  <el-radio-group v-model="size" aria-label="size control" class="mb-4">
    <el-radio-button value="large">large</el-radio-button>
    <el-radio-button value="default">default</el-radio-button>
    <el-radio-button value="small">small</el-radio-button>
  </el-radio-group>
  <div class="demo-date-picker">
    <div class="block">
      <span class="demonstration">Default</span>
      <el-date-picker
        v-model="value1"
        type="daterange"
        range-separator="To"
        start-placeholder="Start date"
        end-placeholder="End date"
        :size="size"
      />
    </div>
    <div class="block">
      <span class="demonstration">With quick options</span>
      <el-date-picker
        v-model="value2"
        type="daterange"
        unlink-panels
        range-separator="To"
        start-placeholder="Start date"
        end-placeholder="End date"
        :shortcuts="shortcuts"
        :size="size"
      />
    </div>
  </div>
</template>

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

const size = ref<'default' | 'large' | 'small'>('default')

const value1 = ref('')
const value2 = ref('')

const shortcuts = [
  {
    text: 'Last week',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 7)
      return [start, end]
    },
  },
  {
    text: 'Last month',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 30)
      return [start, end]
    },
  },
  {
    text: 'Last 3 months',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 90)
      return [start, end]
    },
  },
]
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}

.demo-date-picker .block {
  padding: 1.5rem 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
  min-width: 400px;
  display: flex;
  flex-direction: column;
  align-items: center;
}

.demo-date-picker .block:last-child {
  border-right: none;
}

.demo-date-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 1rem;
}

@media screen and (max-width: 1200px) {
  .demo-date-picker .block {
    flex: 0 0 100%;
    padding: 1rem 0;
    min-width: auto;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-date-picker .block:last-child {
    border-bottom: none;
  }
}
</style>
```

隐藏源代码

## 选择月份范围 [​](#选择月份范围)

你当然还可以选择一个月的范围。

在选择月份范围时，默认情况下左右面板会联动。 如果希望两个面板各自独立切换当前年份，可以使用 `unlink-panels` 属性解除联动。

Default

To

With quick options

To

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+RGVmYXVsdDwvc3Bhbj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgICAgdHlwZT1cIm1vbnRocmFuZ2VcIlxuICAgICAgICByYW5nZS1zZXBhcmF0b3I9XCJUb1wiXG4gICAgICAgIHN0YXJ0LXBsYWNlaG9sZGVyPVwiU3RhcnQgbW9udGhcIlxuICAgICAgICBlbmQtcGxhY2Vob2xkZXI9XCJFbmQgbW9udGhcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPldpdGggcXVpY2sgb3B0aW9uczwvc3Bhbj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgICAgdHlwZT1cIm1vbnRocmFuZ2VcIlxuICAgICAgICB1bmxpbmstcGFuZWxzXG4gICAgICAgIHJhbmdlLXNlcGFyYXRvcj1cIlRvXCJcbiAgICAgICAgc3RhcnQtcGxhY2Vob2xkZXI9XCJTdGFydCBtb250aFwiXG4gICAgICAgIGVuZC1wbGFjZWhvbGRlcj1cIkVuZCBtb250aFwiXG4gICAgICAgIDpzaG9ydGN1dHM9XCJzaG9ydGN1dHNcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZTEgPSByZWYoJycpXG5jb25zdCB2YWx1ZTIgPSByZWYoJycpXG5cbmNvbnN0IHNob3J0Y3V0cyA9IFtcbiAge1xuICAgIHRleHQ6ICdUaGlzIG1vbnRoJyxcbiAgICB2YWx1ZTogW25ldyBEYXRlKCksIG5ldyBEYXRlKCldLFxuICB9LFxuICB7XG4gICAgdGV4dDogJ1RoaXMgeWVhcicsXG4gICAgdmFsdWU6ICgpID0+IHtcbiAgICAgIGNvbnN0IGVuZCA9IG5ldyBEYXRlKClcbiAgICAgIGNvbnN0IHN0YXJ0ID0gbmV3IERhdGUobmV3IERhdGUoKS5nZXRGdWxsWWVhcigpLCAwKVxuICAgICAgcmV0dXJuIFtzdGFydCwgZW5kXVxuICAgIH0sXG4gIH0sXG4gIHtcbiAgICB0ZXh0OiAnTGFzdCA2IG1vbnRocycsXG4gICAgdmFsdWU6ICgpID0+IHtcbiAgICAgIGNvbnN0IGVuZCA9IG5ldyBEYXRlKClcbiAgICAgIGNvbnN0IHN0YXJ0ID0gbmV3IERhdGUoKVxuICAgICAgc3RhcnQuc2V0TW9udGgoc3RhcnQuZ2V0TW9udGgoKSAtIDYpXG4gICAgICByZXR1cm4gW3N0YXJ0LCBlbmRdXG4gICAgfSxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tZGF0ZS1waWNrZXIge1xuICBkaXNwbGF5OiBmbGV4O1xuICB3aWR0aDogMTAwJTtcbiAgcGFkZGluZzogMDtcbiAgZmxleC13cmFwOiB3cmFwO1xufVxuXG4uZGVtby1kYXRlLXBpY2tlciAuYmxvY2sge1xuICBwYWRkaW5nOiAxLjVyZW0gMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBib3JkZXItcmlnaHQ6IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICBmbGV4OiAxO1xuICBtaW4td2lkdGg6IDMwMHB4O1xufVxuXG4uZGVtby1kYXRlLXBpY2tlciAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gIGJvcmRlci1yaWdodDogbm9uZTtcbn1cblxuLmRlbW8tZGF0ZS1waWNrZXIgLmRlbW9uc3RyYXRpb24ge1xuICBkaXNwbGF5OiBibG9jaztcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbiAgZm9udC1zaXplOiAxNHB4O1xuICBtYXJnaW4tYm90dG9tOiAxcmVtO1xufVxuXG5AbWVkaWEgc2NyZWVuIGFuZCAobWF4LXdpZHRoOiA3NjhweCkge1xuICAuZGVtby1kYXRlLXBpY2tlciAuYmxvY2sge1xuICAgIGZsZXg6IDAgMCAxMDAlO1xuICAgIHBhZGRpbmc6IDFyZW0gMDtcbiAgICBtaW4td2lkdGg6IGF1dG87XG4gICAgYm9yZGVyLXJpZ2h0OiBub25lO1xuICAgIGJvcmRlci1ib3R0b206IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICB9XG5cbiAgLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrOmxhc3QtY2hpbGQge1xuICAgIGJvcmRlci1ib3R0b206IG5vbmU7XG4gIH1cbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/month-range.vue)_

vue

```
<template>
  <div class="demo-date-picker">
    <div class="block">
      <span class="demonstration">Default</span>
      <el-date-picker
        v-model="value1"
        type="monthrange"
        range-separator="To"
        start-placeholder="Start month"
        end-placeholder="End month"
      />
    </div>
    <div class="block">
      <span class="demonstration">With quick options</span>
      <el-date-picker
        v-model="value2"
        type="monthrange"
        unlink-panels
        range-separator="To"
        start-placeholder="Start month"
        end-placeholder="End month"
        :shortcuts="shortcuts"
      />
    </div>
  </div>
</template>

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

const value1 = ref('')
const value2 = ref('')

const shortcuts = [
  {
    text: 'This month',
    value: [new Date(), new Date()],
  },
  {
    text: 'This year',
    value: () => {
      const end = new Date()
      const start = new Date(new Date().getFullYear(), 0)
      return [start, end]
    },
  },
  {
    text: 'Last 6 months',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setMonth(start.getMonth() - 6)
      return [start, end]
    },
  },
]
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}

.demo-date-picker .block {
  padding: 1.5rem 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
  min-width: 300px;
}

.demo-date-picker .block:last-child {
  border-right: none;
}

.demo-date-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 1rem;
}

@media screen and (max-width: 768px) {
  .demo-date-picker .block {
    flex: 0 0 100%;
    padding: 1rem 0;
    min-width: auto;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-date-picker .block:last-child {
    border-bottom: none;
  }
}
</style>
```

隐藏源代码

## 年份范围2.8.0 [​](#年份范围)

你可以通过如下例子来学习如何设置一个年份范围选择器。

在选择范围时，默认情况下左右面板会联动。 如果希望两个面板各自独立切换当前年份，可以使用 `unlink-panels` 属性解除联动。

Default

To

With quick options

To

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+RGVmYXVsdDwvc3Bhbj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgICAgdHlwZT1cInllYXJyYW5nZVwiXG4gICAgICAgIHJhbmdlLXNlcGFyYXRvcj1cIlRvXCJcbiAgICAgICAgc3RhcnQtcGxhY2Vob2xkZXI9XCJTdGFydCBZZWFyXCJcbiAgICAgICAgZW5kLXBsYWNlaG9sZGVyPVwiRW5kIFllYXJcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPldpdGggcXVpY2sgb3B0aW9uczwvc3Bhbj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgICAgdHlwZT1cInllYXJyYW5nZVwiXG4gICAgICAgIHVubGluay1wYW5lbHNcbiAgICAgICAgcmFuZ2Utc2VwYXJhdG9yPVwiVG9cIlxuICAgICAgICBzdGFydC1wbGFjZWhvbGRlcj1cIlN0YXJ0IFllYXJcIlxuICAgICAgICBlbmQtcGxhY2Vob2xkZXI9XCJFbmQgWWVhclwiXG4gICAgICAgIDpzaG9ydGN1dHM9XCJzaG9ydGN1dHNcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZTEgPSByZWYoKVxuY29uc3QgdmFsdWUyID0gcmVmKClcblxuY29uc3Qgc2hvcnRjdXRzID0gW1xuICB7XG4gICAgdGV4dDogJ1RoaXMgWWVhcicsXG4gICAgdmFsdWU6IFtuZXcgRGF0ZSgpLCBuZXcgRGF0ZSgpXSxcbiAgfSxcbiAge1xuICAgIHRleHQ6ICdMYXN0IDEwIHllYXJzJyxcbiAgICB2YWx1ZTogKCkgPT4ge1xuICAgICAgY29uc3QgZW5kID0gbmV3IERhdGUoKVxuICAgICAgY29uc3Qgc3RhcnQgPSBuZXcgRGF0ZShcbiAgICAgICAgbmV3IERhdGUoKS5zZXRGdWxsWWVhcihuZXcgRGF0ZSgpLmdldEZ1bGxZZWFyKCkgLSAxMClcbiAgICAgIClcbiAgICAgIHJldHVybiBbc3RhcnQsIGVuZF1cbiAgICB9LFxuICB9LFxuICB7XG4gICAgdGV4dDogJ05leHQgNTAgeWVhcnMnLFxuICAgIHZhbHVlOiAoKSA9PiB7XG4gICAgICBjb25zdCBzdGFydCA9IG5ldyBEYXRlKClcbiAgICAgIGNvbnN0IGVuZCA9IG5ldyBEYXRlKFxuICAgICAgICBuZXcgRGF0ZSgpLnNldEZ1bGxZZWFyKG5ldyBEYXRlKCkuZ2V0RnVsbFllYXIoKSArIDUwKVxuICAgICAgKVxuICAgICAgcmV0dXJuIFtzdGFydCwgZW5kXVxuICAgIH0sXG4gIH0sXG5dXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWRhdGUtcGlja2VyIHtcbiAgZGlzcGxheTogZmxleDtcbiAgd2lkdGg6IDEwMCU7XG4gIHBhZGRpbmc6IDA7XG4gIGZsZXgtd3JhcDogd3JhcDtcbn1cblxuLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrIHtcbiAgcGFkZGluZzogMS41cmVtIDA7XG4gIHRleHQtYWxpZ246IGNlbnRlcjtcbiAgYm9yZGVyLXJpZ2h0OiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgZmxleDogMTtcbiAgbWluLXdpZHRoOiAzMDBweDtcbn1cblxuLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrOmxhc3QtY2hpbGQge1xuICBib3JkZXItcmlnaHQ6IG5vbmU7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyIC5kZW1vbnN0cmF0aW9uIHtcbiAgZGlzcGxheTogYmxvY2s7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG4gIGZvbnQtc2l6ZTogMTRweDtcbiAgbWFyZ2luLWJvdHRvbTogMXJlbTtcbn1cblxuQG1lZGlhIHNjcmVlbiBhbmQgKG1heC13aWR0aDogNzY4cHgpIHtcbiAgLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrIHtcbiAgICBmbGV4OiAwIDAgMTAwJTtcbiAgICBwYWRkaW5nOiAxcmVtIDA7XG4gICAgbWluLXdpZHRoOiBhdXRvO1xuICAgIGJvcmRlci1yaWdodDogbm9uZTtcbiAgICBib3JkZXItYm90dG9tOiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgfVxuXG4gIC5kZW1vLWRhdGUtcGlja2VyIC5ibG9jazpsYXN0LWNoaWxkIHtcbiAgICBib3JkZXItYm90dG9tOiBub25lO1xuICB9XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/year-range.vue)_

vue

```
<template>
  <div class="demo-date-picker">
    <div class="block">
      <span class="demonstration">Default</span>
      <el-date-picker
        v-model="value1"
        type="yearrange"
        range-separator="To"
        start-placeholder="Start Year"
        end-placeholder="End Year"
      />
    </div>
    <div class="block">
      <span class="demonstration">With quick options</span>
      <el-date-picker
        v-model="value2"
        type="yearrange"
        unlink-panels
        range-separator="To"
        start-placeholder="Start Year"
        end-placeholder="End Year"
        :shortcuts="shortcuts"
      />
    </div>
  </div>
</template>

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

const value1 = ref()
const value2 = ref()

const shortcuts = [
  {
    text: 'This Year',
    value: [new Date(), new Date()],
  },
  {
    text: 'Last 10 years',
    value: () => {
      const end = new Date()
      const start = new Date(
        new Date().setFullYear(new Date().getFullYear() - 10)
      )
      return [start, end]
    },
  },
  {
    text: 'Next 50 years',
    value: () => {
      const start = new Date()
      const end = new Date(
        new Date().setFullYear(new Date().getFullYear() + 50)
      )
      return [start, end]
    },
  },
]
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}

.demo-date-picker .block {
  padding: 1.5rem 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
  min-width: 300px;
}

.demo-date-picker .block:last-child {
  border-right: none;
}

.demo-date-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 1rem;
}

@media screen and (max-width: 768px) {
  .demo-date-picker .block {
    flex: 0 0 100%;
    padding: 1rem 0;
    min-width: auto;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-date-picker .block:last-child {
    border-bottom: none;
  }
}
</style>
```

隐藏源代码

## 单个面板 2.14.0 [​](#单个面板)

默认日期选择器范围有两个面板。 如果你想要一个面板设置 `single-panel` 属性。

date range

\-

month range

\-

year range

\-

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+ZGF0ZSByYW5nZTwvc3Bhbj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlciB2LW1vZGVsPVwidmFsdWUxXCIgdHlwZT1cImRhdGVyYW5nZVwiIHNpbmdsZS1wYW5lbCAvPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+bW9udGggcmFuZ2U8L3NwYW4+XG4gICAgICA8ZWwtZGF0ZS1waWNrZXIgdi1tb2RlbD1cInZhbHVlMlwiIHR5cGU9XCJtb250aHJhbmdlXCIgc2luZ2xlLXBhbmVsIC8+XG4gICAgPC9kaXY+XG4gICAgPGRpdiBjbGFzcz1cImJsb2NrXCI+XG4gICAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj55ZWFyIHJhbmdlPC9zcGFuPlxuICAgICAgPGVsLWRhdGUtcGlja2VyIHYtbW9kZWw9XCJ2YWx1ZTNcIiB0eXBlPVwieWVhcnJhbmdlXCIgc2luZ2xlLXBhbmVsIC8+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUxID0gcmVmKClcbmNvbnN0IHZhbHVlMiA9IHJlZigpXG5jb25zdCB2YWx1ZTMgPSByZWYoKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1kYXRlLXBpY2tlciB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIHdpZHRoOiAxMDAlO1xuICBwYWRkaW5nOiAwO1xuICBmbGV4LXdyYXA6IHdyYXA7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyIC5ibG9jayB7XG4gIHBhZGRpbmc6IDEuNXJlbSAwO1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG4gIGJvcmRlci1yaWdodDogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG4gIGZsZXg6IDE7XG4gIG1pbi13aWR0aDogMzAwcHg7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGZsZXgtZGlyZWN0aW9uOiBjb2x1bW47XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyIC5ibG9jazpsYXN0LWNoaWxkIHtcbiAgYm9yZGVyLXJpZ2h0OiBub25lO1xufVxuXG4uZGVtby1kYXRlLXBpY2tlciAuYmxvY2sgOmRlZXAoLmVsLWRhdGUtZWRpdG9yKSB7XG4gIHdpZHRoOiAzMDBweDtcbn1cblxuLmRlbW8tZGF0ZS1waWNrZXIgLmRlbW9uc3RyYXRpb24ge1xuICBkaXNwbGF5OiBibG9jaztcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbiAgZm9udC1zaXplOiAxNHB4O1xuICBtYXJnaW4tYm90dG9tOiAxcmVtO1xuICB3aWR0aDogMTAwJTtcbn1cblxuQG1lZGlhIHNjcmVlbiBhbmQgKG1heC13aWR0aDogMTIwMHB4KSB7XG4gIC5kZW1vLWRhdGUtcGlja2VyIC5ibG9jayB7XG4gICAgZmxleDogMCAwIDUwJTtcbiAgICBib3JkZXItYm90dG9tOiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgfVxuXG4gIC5kZW1vLWRhdGUtcGlja2VyIC5ibG9jazpudGgtY2hpbGQoMm4pIHtcbiAgICBib3JkZXItcmlnaHQ6IG5vbmU7XG4gIH1cblxuICAuZGVtby1kYXRlLXBpY2tlciAuYmxvY2s6bnRoLWxhc3QtY2hpbGQoLW4gKyAyKTpudGgtY2hpbGQoMm4gKyAxKSxcbiAgLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrOmxhc3QtY2hpbGQge1xuICAgIGJvcmRlci1ib3R0b206IG5vbmU7XG4gIH1cbn1cblxuQG1lZGlhIHNjcmVlbiBhbmQgKG1heC13aWR0aDogNzY4cHgpIHtcbiAgLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrIHtcbiAgICBmbGV4OiAwIDAgMTAwJTtcbiAgICBwYWRkaW5nOiAxcmVtIDA7XG4gICAgbWluLXdpZHRoOiBhdXRvO1xuICAgIGJvcmRlci1yaWdodDogbm9uZTtcbiAgICBib3JkZXItYm90dG9tOiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgfVxuXG4gIC5kZW1vLWRhdGUtcGlja2VyIC5ibG9jazpsYXN0LWNoaWxkIHtcbiAgICBib3JkZXItYm90dG9tOiBub25lO1xuICB9XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/single-panel.vue)_

vue

```
<template>
  <div class="demo-date-picker">
    <div class="block">
      <span class="demonstration">date range</span>
      <el-date-picker v-model="value1" type="daterange" single-panel />
    </div>
    <div class="block">
      <span class="demonstration">month range</span>
      <el-date-picker v-model="value2" type="monthrange" single-panel />
    </div>
    <div class="block">
      <span class="demonstration">year range</span>
      <el-date-picker v-model="value3" type="yearrange" single-panel />
    </div>
  </div>
</template>

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

const value1 = ref()
const value2 = ref()
const value3 = ref()
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}

.demo-date-picker .block {
  padding: 1.5rem 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
  min-width: 300px;
  display: flex;
  flex-direction: column;
  align-items: center;
}

.demo-date-picker .block:last-child {
  border-right: none;
}

.demo-date-picker .block :deep(.el-date-editor) {
  width: 300px;
}

.demo-date-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 1rem;
  width: 100%;
}

@media screen and (max-width: 1200px) {
  .demo-date-picker .block {
    flex: 0 0 50%;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-date-picker .block:nth-child(2n) {
    border-right: none;
  }

  .demo-date-picker .block:nth-last-child(-n + 2):nth-child(2n + 1),
  .demo-date-picker .block:last-child {
    border-bottom: none;
  }
}

@media screen and (max-width: 768px) {
  .demo-date-picker .block {
    flex: 0 0 100%;
    padding: 1rem 0;
    min-width: auto;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-date-picker .block:last-child {
    border-bottom: none;
  }
}
</style>
```

隐藏源代码

## 默认值 [​](#默认值)

日期选择器会在用户未选择任何日期的时候默认展示当天的日期。 你也可以使用 `default-value` 来修改这个默认的日期。 请注意该值需要是一个可以解析的 `new Date()` 对象。

如果类型是 `daterange`, `default-value` 则会设置左边窗口的默认值。

date

daterange

\-

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+ZGF0ZTwvc3Bhbj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgICAgdHlwZT1cImRhdGVcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSBkYXRlXCJcbiAgICAgICAgOmRlZmF1bHQtdmFsdWU9XCJuZXcgRGF0ZSgyMDEwLCA5LCAxKVwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+ZGF0ZXJhbmdlPC9zcGFuPlxuICAgICAgPGVsLWRhdGUtcGlja2VyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTJcIlxuICAgICAgICB0eXBlPVwiZGF0ZXJhbmdlXCJcbiAgICAgICAgc3RhcnQtcGxhY2Vob2xkZXI9XCJTdGFydCBEYXRlXCJcbiAgICAgICAgZW5kLXBsYWNlaG9sZGVyPVwiRW5kIERhdGVcIlxuICAgICAgICA6ZGVmYXVsdC12YWx1ZT1cIltuZXcgRGF0ZSgyMDEwLCA5LCAxKSwgbmV3IERhdGUoMjAxMCwgMTAsIDEpXVwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZignJylcbmNvbnN0IHZhbHVlMiA9IHJlZignJylcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tZGF0ZS1waWNrZXIge1xuICBkaXNwbGF5OiBmbGV4O1xuICB3aWR0aDogMTAwJTtcbiAgcGFkZGluZzogMDtcbiAgZmxleC13cmFwOiB3cmFwO1xufVxuXG4uZGVtby1kYXRlLXBpY2tlciAuYmxvY2sge1xuICBwYWRkaW5nOiAxLjVyZW0gMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBib3JkZXItcmlnaHQ6IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICBmbGV4OiAxO1xuICBtaW4td2lkdGg6IDMwMHB4O1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LWRpcmVjdGlvbjogY29sdW1uO1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xufVxuXG4uZGVtby1kYXRlLXBpY2tlciAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gIGJvcmRlci1yaWdodDogbm9uZTtcbn1cblxuLmRlbW8tZGF0ZS1waWNrZXIgLmRlbW9uc3RyYXRpb24ge1xuICBkaXNwbGF5OiBibG9jaztcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbiAgZm9udC1zaXplOiAxNHB4O1xuICBtYXJnaW4tYm90dG9tOiAxcmVtO1xufVxuXG5AbWVkaWEgc2NyZWVuIGFuZCAobWF4LXdpZHRoOiA3NjhweCkge1xuICAuZGVtby1kYXRlLXBpY2tlciAuYmxvY2sge1xuICAgIGZsZXg6IDAgMCAxMDAlO1xuICAgIHBhZGRpbmc6IDFyZW0gMDtcbiAgICBtaW4td2lkdGg6IGF1dG87XG4gICAgYm9yZGVyLXJpZ2h0OiBub25lO1xuICAgIGJvcmRlci1ib3R0b206IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICB9XG5cbiAgLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrOmxhc3QtY2hpbGQge1xuICAgIGJvcmRlci1ib3R0b206IG5vbmU7XG4gIH1cbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/default-value.vue)_

vue

```
<template>
  <div class="demo-date-picker">
    <div class="block">
      <span class="demonstration">date</span>
      <el-date-picker
        v-model="value1"
        type="date"
        placeholder="Pick a date"
        :default-value="new Date(2010, 9, 1)"
      />
    </div>
    <div class="block">
      <span class="demonstration">daterange</span>
      <el-date-picker
        v-model="value2"
        type="daterange"
        start-placeholder="Start Date"
        end-placeholder="End Date"
        :default-value="[new Date(2010, 9, 1), new Date(2010, 10, 1)]"
      />
    </div>
  </div>
</template>

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

const value1 = ref('')
const value2 = ref('')
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}

.demo-date-picker .block {
  padding: 1.5rem 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
  min-width: 300px;
  display: flex;
  flex-direction: column;
  align-items: center;
}

.demo-date-picker .block:last-child {
  border-right: none;
}

.demo-date-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 1rem;
}

@media screen and (max-width: 768px) {
  .demo-date-picker .block {
    flex: 0 0 100%;
    padding: 1rem 0;
    min-width: auto;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-date-picker .block:last-child {
    border-bottom: none;
  }
}
</style>
```

隐藏源代码

## 日期格式 [​](#日期格式)

使用`format`指定输入框的格式。 使用 `value-format` 指定绑定值的格式。

默认情况下，组件接受并返回`Date`对象。

在 [这里](https://day.js.org/docs/en/display/format#list-of-all-available-formats) 查看 Day.js 支持的所有格式。

WARNING

请一定要注意传入参数的大小写是否正确

Emits Date object

Value:

Use value-format

Value：

Timestamp

Value：

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+RW1pdHMgRGF0ZSBvYmplY3Q8L3NwYW4+XG4gICAgICA8ZGl2IGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPlZhbHVlOiB7eyB2YWx1ZTEgfX08L2Rpdj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgICAgdHlwZT1cImRhdGVcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSBEYXRlXCJcbiAgICAgICAgZm9ybWF0PVwiWVlZWS9NTS9ERFwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+VXNlIHZhbHVlLWZvcm1hdDwvc3Bhbj5cbiAgICAgIDxkaXYgY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+VmFsdWXvvJp7eyB2YWx1ZTIgfX08L2Rpdj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgICAgdHlwZT1cImRhdGVcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSBEYXRlXCJcbiAgICAgICAgZm9ybWF0PVwiWVlZWS9NTS9ERFwiXG4gICAgICAgIHZhbHVlLWZvcm1hdD1cIllZWVktTU0tRERcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPlRpbWVzdGFtcDwvc3Bhbj5cbiAgICAgIDxkaXYgY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+VmFsdWXvvJp7eyB2YWx1ZTMgfX08L2Rpdj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUzXCJcbiAgICAgICAgdHlwZT1cImRhdGVcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSBEYXRlXCJcbiAgICAgICAgZm9ybWF0PVwiWVlZWS9NTS9ERFwiXG4gICAgICAgIHZhbHVlLWZvcm1hdD1cInhcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZTEgPSByZWYoJycpXG5jb25zdCB2YWx1ZTIgPSByZWYoJycpXG5jb25zdCB2YWx1ZTMgPSByZWYoJycpXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWRhdGUtcGlja2VyIHtcbiAgZGlzcGxheTogZmxleDtcbiAgd2lkdGg6IDEwMCU7XG4gIHBhZGRpbmc6IDA7XG4gIGZsZXgtd3JhcDogd3JhcDtcbn1cblxuLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrIHtcbiAgcGFkZGluZzogMS41cmVtIDA7XG4gIHRleHQtYWxpZ246IGNlbnRlcjtcbiAgYm9yZGVyLXJpZ2h0OiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgZmxleDogMTtcbiAgbWluLXdpZHRoOiAzMDBweDtcbiAgZGlzcGxheTogZmxleDtcbiAgZmxleC1kaXJlY3Rpb246IGNvbHVtbjtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbn1cblxuLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrOmxhc3QtY2hpbGQge1xuICBib3JkZXItcmlnaHQ6IG5vbmU7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyIC5kZW1vbnN0cmF0aW9uIHtcbiAgZGlzcGxheTogYmxvY2s7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG4gIGZvbnQtc2l6ZTogMTRweDtcbiAgbWFyZ2luLWJvdHRvbTogMXJlbTtcbiAgd2lkdGg6IDEwMCU7XG59XG5cbkBtZWRpYSBzY3JlZW4gYW5kIChtYXgtd2lkdGg6IDEyMDBweCkge1xuICAuZGVtby1kYXRlLXBpY2tlciAuYmxvY2sge1xuICAgIGZsZXg6IDAgMCA1MCU7XG4gICAgYm9yZGVyLWJvdHRvbTogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG4gIH1cblxuICAuZGVtby1kYXRlLXBpY2tlciAuYmxvY2s6bnRoLWNoaWxkKDJuKSB7XG4gICAgYm9yZGVyLXJpZ2h0OiBub25lO1xuICB9XG5cbiAgLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrOm50aC1sYXN0LWNoaWxkKC1uICsgMik6bnRoLWNoaWxkKDJuICsgMSksXG4gIC5kZW1vLWRhdGUtcGlja2VyIC5ibG9jazpsYXN0LWNoaWxkIHtcbiAgICBib3JkZXItYm90dG9tOiBub25lO1xuICB9XG59XG5cbkBtZWRpYSBzY3JlZW4gYW5kIChtYXgtd2lkdGg6IDc2OHB4KSB7XG4gIC5kZW1vLWRhdGUtcGlja2VyIC5ibG9jayB7XG4gICAgZmxleDogMCAwIDEwMCU7XG4gICAgcGFkZGluZzogMXJlbSAwO1xuICAgIG1pbi13aWR0aDogYXV0bztcbiAgICBib3JkZXItcmlnaHQ6IG5vbmU7XG4gICAgYm9yZGVyLWJvdHRvbTogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG4gIH1cblxuICAuZGVtby1kYXRlLXBpY2tlciAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gICAgYm9yZGVyLWJvdHRvbTogbm9uZTtcbiAgfVxufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/date-formats.vue)_

vue

```
<template>
  <div class="demo-date-picker">
    <div class="block">
      <span class="demonstration">Emits Date object</span>
      <div class="demonstration">Value: {{ value1 }}</div>
      <el-date-picker
        v-model="value1"
        type="date"
        placeholder="Pick a Date"
        format="YYYY/MM/DD"
      />
    </div>
    <div class="block">
      <span class="demonstration">Use value-format</span>
      <div class="demonstration">Value：{{ value2 }}</div>
      <el-date-picker
        v-model="value2"
        type="date"
        placeholder="Pick a Date"
        format="YYYY/MM/DD"
        value-format="YYYY-MM-DD"
      />
    </div>
    <div class="block">
      <span class="demonstration">Timestamp</span>
      <div class="demonstration">Value：{{ value3 }}</div>
      <el-date-picker
        v-model="value3"
        type="date"
        placeholder="Pick a Date"
        format="YYYY/MM/DD"
        value-format="x"
      />
    </div>
  </div>
</template>

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

const value1 = ref('')
const value2 = ref('')
const value3 = ref('')
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}

.demo-date-picker .block {
  padding: 1.5rem 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
  min-width: 300px;
  display: flex;
  flex-direction: column;
  align-items: center;
}

.demo-date-picker .block:last-child {
  border-right: none;
}

.demo-date-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 1rem;
  width: 100%;
}

@media screen and (max-width: 1200px) {
  .demo-date-picker .block {
    flex: 0 0 50%;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-date-picker .block:nth-child(2n) {
    border-right: none;
  }

  .demo-date-picker .block:nth-last-child(-n + 2):nth-child(2n + 1),
  .demo-date-picker .block:last-child {
    border-bottom: none;
  }
}

@media screen and (max-width: 768px) {
  .demo-date-picker .block {
    flex: 0 0 100%;
    padding: 1rem 0;
    min-width: auto;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-date-picker .block:last-child {
    border-bottom: none;
  }
}
</style>
```

隐藏源代码

## 默认显示日期 [​](#默认显示日期)

在选择日期范围时，你可以指定起始日期和结束日期的默认时间。

默认情况下，开始日期和结束日期的时间部分都是选择日期当日的 `00:00:00`。 通过 `default-time` 可以分别指定开始日期和结束日期的具体时刻。 它接受最多两个日期对象的数组。 其中第一项控制起始日期的具体时刻，第二项控制结束日期的具体时刻。

Component value：

\-

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHA+Q29tcG9uZW50IHZhbHVl77yae3sgdmFsdWUgfX08L3A+XG4gICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgICAgdHlwZT1cImRhdGVyYW5nZVwiXG4gICAgICAgIHN0YXJ0LXBsYWNlaG9sZGVyPVwiU3RhcnQgZGF0ZVwiXG4gICAgICAgIGVuZC1wbGFjZWhvbGRlcj1cIkVuZCBkYXRlXCJcbiAgICAgICAgdmFsdWUtZm9ybWF0PVwiWVlZWS1NTS1ERCBISDptbTpzc1wiXG4gICAgICAgIDpkZWZhdWx0LXRpbWU9XCJkZWZhdWx0VGltZVwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKCcnKVxuY29uc3QgZGVmYXVsdFRpbWUgPSByZWY8W0RhdGUsIERhdGVdPihbXG4gIG5ldyBEYXRlKDIwMDAsIDEsIDEsIDAsIDAsIDApLFxuICBuZXcgRGF0ZSgyMDAwLCAyLCAxLCAyMywgNTksIDU5KSxcbl0pXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWRhdGUtcGlja2VyIHtcbiAgZGlzcGxheTogZmxleDtcbiAgd2lkdGg6IDEwMCU7XG4gIHBhZGRpbmc6IDA7XG4gIGZsZXgtd3JhcDogd3JhcDtcbn1cbi5kZW1vLWRhdGUtcGlja2VyIC5ibG9jayB7XG4gIHBhZGRpbmc6IDMwcHggMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBib3JkZXItcmlnaHQ6IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICBmbGV4OiAxO1xufVxuLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrOmxhc3QtY2hpbGQge1xuICBib3JkZXItcmlnaHQ6IG5vbmU7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/default-time.vue)_

vue

```
<template>
  <div class="demo-date-picker">
    <div class="block">
      <p>Component value：{{ value }}</p>
      <el-date-picker
        v-model="value"
        type="daterange"
        start-placeholder="Start date"
        end-placeholder="End date"
        value-format="YYYY-MM-DD HH:mm:ss"
        :default-time="defaultTime"
      />
    </div>
  </div>
</template>

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

const value = ref('')
const defaultTime = ref<[Date, Date]>([
  new Date(2000, 1, 1, 0, 0, 0),
  new Date(2000, 2, 1, 23, 59, 59),
])
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}
.demo-date-picker .block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
}
.demo-date-picker .block:last-child {
  border-right: none;
}
</style>
```

隐藏源代码

## 设置自定义前缀的内容 [​](#设置自定义前缀的内容)

前缀内容可以被自定义。

当你从其他vue组件或由渲染函数生成的组件中导入组件时, 你可以设置 `prefix-icon` 属性来定制前缀内容

set prefix-icon

_

pre

_

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+c2V0IHByZWZpeC1pY29uPC9zcGFuPlxuICAgICAgPGVsLWRhdGUtcGlja2VyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTFcIlxuICAgICAgICB0eXBlPVwiZGF0ZVwiXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiUGljayBhIGRheVwiXG4gICAgICAgIDpwcmVmaXgtaWNvbj1cImN1c3RvbVByZWZpeFwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBoLCByZWYsIHNoYWxsb3dSZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZignJylcblxuY29uc3QgY3VzdG9tUHJlZml4ID0gc2hhbGxvd1JlZih7XG4gIHJlbmRlcigpIHtcbiAgICByZXR1cm4gaCgncCcsICdwcmUnKVxuICB9LFxufSlcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tZGF0ZS1waWNrZXIge1xuICBkaXNwbGF5OiBmbGV4O1xuICB3aWR0aDogMTAwJTtcbiAgcGFkZGluZzogMDtcbiAgZmxleC13cmFwOiB3cmFwO1xufVxuLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrIHtcbiAgcGFkZGluZzogMzBweCAwO1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG4gIGJvcmRlci1yaWdodDogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG4gIGZsZXg6IDE7XG59XG4uZGVtby1kYXRlLXBpY2tlciAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gIGJvcmRlci1yaWdodDogbm9uZTtcbn1cbi5kZW1vLWRhdGUtcGlja2VyIC5kZW1vbnN0cmF0aW9uIHtcbiAgZGlzcGxheTogYmxvY2s7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG4gIGZvbnQtc2l6ZTogMTRweDtcbiAgbWFyZ2luLWJvdHRvbTogMjBweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/custom-prefix-icon.vue)_

vue

```
<template>
  <div class="demo-date-picker">
    <div class="block">
      <span class="demonstration">set prefix-icon</span>
      <el-date-picker
        v-model="value1"
        type="date"
        placeholder="Pick a day"
        :prefix-icon="customPrefix"
      />
    </div>
  </div>
</template>

<script lang="ts" setup>
import { h, ref, shallowRef } from 'vue'

const value1 = ref('')

const customPrefix = shallowRef({
  render() {
    return h('p', 'pre')
  },
})
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}
.demo-date-picker .block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
}
.demo-date-picker .block:last-child {
  border-right: none;
}
.demo-date-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}
</style>
```

隐藏源代码

## 自定义内容 [​](#自定义内容)

弹出框的内容是可以自定义的，在插槽内你可以获取到当前单元格的数据 请注意，自定义内容结构应与默认结构一致，否则可能风格会不一致。

value-on-clear

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgIHR5cGU9XCJkYXRlXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiUGljayBhIGRheVwiXG4gICAgICBmb3JtYXQ9XCJZWVlZL01NL0REXCJcbiAgICAgIHZhbHVlLWZvcm1hdD1cIllZWVktTU0tRERcIlxuICAgID5cbiAgICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD1cImNlbGxcIj5cbiAgICAgICAgPGRpdiBjbGFzcz1cImNlbGxcIiA6Y2xhc3M9XCJ7IGN1cnJlbnQ6IGNlbGwuaXNDdXJyZW50IH1cIj5cbiAgICAgICAgICA8c3BhbiBjbGFzcz1cInRleHRcIj57eyBjZWxsLnRleHQgfX08L3NwYW4+XG4gICAgICAgICAgPHNwYW4gdi1pZj1cImlzSG9saWRheShjZWxsKVwiIGNsYXNzPVwiaG9saWRheVwiIC8+XG4gICAgICAgIDwvZGl2PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWRhdGUtcGlja2VyPlxuICAgIDxlbC1kYXRlLXBpY2tlciB2LW1vZGVsPVwibW9udGhcIiB0eXBlPVwibW9udGhcIiBwbGFjZWhvbGRlcj1cIlBpY2sgYSBtb250aFwiPlxuICAgICAgPHRlbXBsYXRlICNkZWZhdWx0PVwiY2VsbFwiPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiZWwtZGF0ZS10YWJsZS1jZWxsXCIgOmNsYXNzPVwieyBjdXJyZW50OiBjZWxsLmlzQ3VycmVudCB9XCI+XG4gICAgICAgICAgPHNwYW4gY2xhc3M9XCJlbC1kYXRlLXRhYmxlLWNlbGxfX3RleHRcIj57eyBjZWxsLnRleHQgKyAxIH195pyfPC9zcGFuPlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1kYXRlLXBpY2tlcj5cbiAgICA8ZWwtZGF0ZS1waWNrZXIgdi1tb2RlbD1cInllYXJcIiB0eXBlPVwieWVhclwiIHBsYWNlaG9sZGVyPVwiUGljayBhIHllYXJcIj5cbiAgICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD1cImNlbGxcIj5cbiAgICAgICAgPGRpdiBjbGFzcz1cImVsLWRhdGUtdGFibGUtY2VsbFwiIDpjbGFzcz1cInsgY3VycmVudDogY2VsbC5pc0N1cnJlbnQgfVwiPlxuICAgICAgICAgIDxzcGFuIGNsYXNzPVwiZWwtZGF0ZS10YWJsZS1jZWxsX190ZXh0XCI+e3sgY2VsbC50ZXh0ICsgMSB9fXk8L3NwYW4+XG4gICAgICAgIDwvZGl2PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWRhdGUtcGlja2VyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKCcyMDIxLTEwLTI5JylcbmNvbnN0IG1vbnRoID0gcmVmKCcnKVxuY29uc3QgeWVhciA9IHJlZignJylcbmNvbnN0IGhvbGlkYXlzID0gW1xuICAnMjAyMS0xMC0wMScsXG4gICcyMDIxLTEwLTAyJyxcbiAgJzIwMjEtMTAtMDMnLFxuICAnMjAyMS0xMC0wNCcsXG4gICcyMDIxLTEwLTA1JyxcbiAgJzIwMjEtMTAtMDYnLFxuICAnMjAyMS0xMC0wNycsXG5dXG5cbmNvbnN0IGlzSG9saWRheSA9ICh7IGRheWpzIH0pID0+IHtcbiAgcmV0dXJuIGhvbGlkYXlzLmluY2x1ZGVzKGRheWpzLmZvcm1hdCgnWVlZWS1NTS1ERCcpKVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1kYXRlLXBpY2tlciB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGZsZXgtd3JhcDogd3JhcDtcbiAgZ2FwOiAxcmVtO1xufVxuXG4uZGVtby1kYXRlLXBpY2tlciA+ICoge1xuICBtYXJnaW46IDAgIWltcG9ydGFudDtcbn1cblxuLmNlbGwge1xuICBoZWlnaHQ6IDMwcHg7XG4gIHBhZGRpbmc6IDNweCAwO1xuICBib3gtc2l6aW5nOiBib3JkZXItYm94O1xufVxuXG4uY2VsbCAudGV4dCB7XG4gIHdpZHRoOiAyNHB4O1xuICBoZWlnaHQ6IDI0cHg7XG4gIGRpc3BsYXk6IGJsb2NrO1xuICBtYXJnaW46IDAgYXV0bztcbiAgbGluZS1oZWlnaHQ6IDI0cHg7XG4gIHBvc2l0aW9uOiBhYnNvbHV0ZTtcbiAgbGVmdDogNTAlO1xuICB0cmFuc2Zvcm06IHRyYW5zbGF0ZVgoLTUwJSk7XG4gIGJvcmRlci1yYWRpdXM6IDUwJTtcbn1cblxuLmNlbGwuY3VycmVudCAudGV4dCB7XG4gIGJhY2tncm91bmQ6ICM2MjZhZWY7XG4gIGNvbG9yOiAjZmZmO1xufVxuXG4uY2VsbCAuaG9saWRheSB7XG4gIHBvc2l0aW9uOiBhYnNvbHV0ZTtcbiAgd2lkdGg6IDZweDtcbiAgaGVpZ2h0OiA2cHg7XG4gIGJhY2tncm91bmQ6IHZhcigtLWVsLWNvbG9yLWRhbmdlcik7XG4gIGJvcmRlci1yYWRpdXM6IDUwJTtcbiAgYm90dG9tOiAwcHg7XG4gIGxlZnQ6IDUwJTtcbiAgdHJhbnNmb3JtOiB0cmFuc2xhdGVYKC01MCUpO1xufVxuXG5AbWVkaWEgc2NyZWVuIGFuZCAobWF4LXdpZHRoOiA3NjhweCkge1xuICAuZGVtby1kYXRlLXBpY2tlciB7XG4gICAgZ2FwOiAxLjVyZW07XG4gIH1cbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/custom-content.vue)_

vue

```
<template>
  <div class="demo-date-picker">
    <el-date-picker
      v-model="value"
      type="date"
      placeholder="Pick a day"
      format="YYYY/MM/DD"
      value-format="YYYY-MM-DD"
    >
      <template #default="cell">
        <div class="cell" :class="{ current: cell.isCurrent }">
          <span class="text">{{ cell.text }}</span>
          <span v-if="isHoliday(cell)" class="holiday" />
        </div>
      </template>
    </el-date-picker>
    <el-date-picker v-model="month" type="month" placeholder="Pick a month">
      <template #default="cell">
        <div class="el-date-table-cell" :class="{ current: cell.isCurrent }">
          <span class="el-date-table-cell__text">{{ cell.text + 1 }}期</span>
        </div>
      </template>
    </el-date-picker>
    <el-date-picker v-model="year" type="year" placeholder="Pick a year">
      <template #default="cell">
        <div class="el-date-table-cell" :class="{ current: cell.isCurrent }">
          <span class="el-date-table-cell__text">{{ cell.text + 1 }}y</span>
        </div>
      </template>
    </el-date-picker>
  </div>
</template>

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

const value = ref('2021-10-29')
const month = ref('')
const year = ref('')
const holidays = [
  '2021-10-01',
  '2021-10-02',
  '2021-10-03',
  '2021-10-04',
  '2021-10-05',
  '2021-10-06',
  '2021-10-07',
]

const isHoliday = ({ dayjs }) => {
  return holidays.includes(dayjs.format('YYYY-MM-DD'))
}
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
}

.demo-date-picker > * {
  margin: 0 !important;
}

.cell {
  height: 30px;
  padding: 3px 0;
  box-sizing: border-box;
}

.cell .text {
  width: 24px;
  height: 24px;
  display: block;
  margin: 0 auto;
  line-height: 24px;
  position: absolute;
  left: 50%;
  transform: translateX(-50%);
  border-radius: 50%;
}

.cell.current .text {
  background: #626aef;
  color: #fff;
}

.cell .holiday {
  position: absolute;
  width: 6px;
  height: 6px;
  background: var(--el-color-danger);
  border-radius: 50%;
  bottom: 0px;
  left: 50%;
  transform: translateX(-50%);
}

@media screen and (max-width: 768px) {
  .demo-date-picker {
    gap: 1.5rem;
  }
}
</style>
```

隐藏源代码

## 自定义图标 2.8.0 [​](#自定义图标)

使用插槽自定义图标。

date

date range

\-

month range

\-

year range

To

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlci1pY29uXCI+XG4gICAgPGRpdiBjbGFzcz1cImNvbnRhaW5lclwiPlxuICAgICAgPGRpdiBjbGFzcz1cImJsb2NrXCI+XG4gICAgICAgIDxkaXYgY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+ZGF0ZTwvZGl2PlxuICAgICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgICAgICB0eXBlPVwiZGF0ZVwiXG4gICAgICAgICAgcGxhY2Vob2xkZXI9XCJQaWNrIGEgZGF5XCJcbiAgICAgICAgICBmb3JtYXQ9XCJZWVlZL01NL0REXCJcbiAgICAgICAgICB2YWx1ZS1mb3JtYXQ9XCJZWVlZLU1NLUREXCJcbiAgICAgICAgPlxuICAgICAgICAgIDx0ZW1wbGF0ZSAjcHJldi1tb250aD5cbiAgICAgICAgICAgIDxlbC1pY29uPjxDYXJldExlZnQgLz48L2VsLWljb24+XG4gICAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgICA8dGVtcGxhdGUgI25leHQtbW9udGg+XG4gICAgICAgICAgICA8ZWwtaWNvbj48Q2FyZXRSaWdodCAvPjwvZWwtaWNvbj5cbiAgICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICAgIDx0ZW1wbGF0ZSAjcHJldi15ZWFyPlxuICAgICAgICAgICAgPGVsLWljb24+XG4gICAgICAgICAgICAgIDxzdmdcbiAgICAgICAgICAgICAgICB2aWV3Qm94PVwiMCAwIDIwIDIwXCJcbiAgICAgICAgICAgICAgICB2ZXJzaW9uPVwiMS4xXCJcbiAgICAgICAgICAgICAgICB4bWxucz1cImh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnXCJcbiAgICAgICAgICAgICAgPlxuICAgICAgICAgICAgICAgIDxnIHN0cm9rZS13aWR0aD1cIjFcIiBmaWxsLXJ1bGU9XCJldmVub2RkXCI+XG4gICAgICAgICAgICAgICAgICA8ZyBmaWxsPVwiY3VycmVudENvbG9yXCI+XG4gICAgICAgICAgICAgICAgICAgIDxwYXRoXG4gICAgICAgICAgICAgICAgICAgICAgZD1cIk04LjczMTcxLDE2Ljc5NDkgQzkuMDMyNjQsMTcuMDc5NSA5LjUwNzMzLDE3LjA2NjMgOS43OTE5NiwxNi43NjU0IEMxMC4wNzY2LDE2LjQ2NDQgMTAuMDYzNCwxNS45ODk3IDkuNzYyNDMsMTUuNzA1MSBMNC41MjMzOSwxMC43NSBMMTcuMjQ3MSwxMC43NSBDMTcuNjYxMywxMC43NSAxNy45OTcxLDEwLjQxNDIgMTcuOTk3MSwxMCBDMTcuOTk3MSw5LjU4NTc5IDE3LjY2MTMsOS4yNSAxNy4yNDcxLDkuMjUgTDQuNTIxMTIsOS4yNSBMOS43NjI0Myw0LjI5Mjc1IEMxMC4wNjM0LDQuMDA4MTIgMTAuMDc2NiwzLjUzMzQzIDkuNzkxOTYsMy4yMzI1IEM5LjUwNzMzLDIuOTMxNTYgOS4wMzI2NCwyLjkxODM0IDguNzMxNzEsMy4yMDI5NyBMMi4zMTQ0OSw5LjI3MjQxIEMyLjE0ODE5LDkuNDI5NyAyLjA0ODE5LDkuNjI5ODEgMi4wMTQ0OCw5LjgzODYgQzIuMDAzMDgsOS44OTA1OCAxLjk5NzA3LDkuOTQ0NTkgMS45OTcwNywxMCBDMS45OTcwNywxMC4wNTc2IDIuMDAzNTYsMTAuMTEzNyAyLjAxNTg1LDEwLjE2NzUgQzIuMDUwODQsMTAuMzczMyAyLjE1MDM5LDEwLjU3MDIgMi4zMTQ0OSwxMC43MjU0IEw4LjczMTcxLDE2Ljc5NDkgWlwiXG4gICAgICAgICAgICAgICAgICAgIC8+XG4gICAgICAgICAgICAgICAgICA8L2c+XG4gICAgICAgICAgICAgICAgPC9nPlxuICAgICAgICAgICAgICA8L3N2Zz5cbiAgICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICAgIDx0ZW1wbGF0ZSAjbmV4dC15ZWFyPlxuICAgICAgICAgICAgPGVsLWljb24+XG4gICAgICAgICAgICAgIDxzdmdcbiAgICAgICAgICAgICAgICB2aWV3Qm94PVwiMCAwIDIwIDIwXCJcbiAgICAgICAgICAgICAgICB2ZXJzaW9uPVwiMS4xXCJcbiAgICAgICAgICAgICAgICB4bWxucz1cImh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnXCJcbiAgICAgICAgICAgICAgPlxuICAgICAgICAgICAgICAgIDxnIHN0cm9rZS13aWR0aD1cIjFcIiBmaWxsLXJ1bGU9XCJldmVub2RkXCI+XG4gICAgICAgICAgICAgICAgICA8ZyBmaWxsPVwiY3VycmVudENvbG9yXCI+XG4gICAgICAgICAgICAgICAgICAgIDxwYXRoXG4gICAgICAgICAgICAgICAgICAgICAgZD1cIk0xMS4yNjU0LDMuMjA1MTEgQzEwLjk2NDQsMi45MjA0OSAxMC40ODk3LDIuOTMzNzEgMTAuMjA1MSwzLjIzNDY0IEM5LjkyMDQ5LDMuNTM1NTggOS45MzM3MSw0LjAxMDI3IDEwLjIzNDYsNC4yOTQ4OSBMMTUuNDczNyw5LjI1IEwyLjc1LDkuMjUgQzIuMzM1NzksOS4yNSAyLDkuNTg1NzkgMiwxMC4wMDAwMDEyIEMyLDEwLjQxNDIgMi4zMzU3OSwxMC43NSAyLjc1LDEwLjc1IEwxNS40NzYsMTAuNzUgTDEwLjIzNDYsMTUuNzA3MyBDOS45MzM3MSwxNS45OTE5IDkuOTIwNDksMTYuNDY2NiAxMC4yMDUxLDE2Ljc2NzUgQzEwLjQ4OTcsMTcuMDY4NCAxMC45NjQ0LDE3LjA4MTcgMTEuMjY1NCwxNi43OTcgTDE3LjY4MjYsMTAuNzI3NiBDMTcuODQ4OSwxMC41NzAzIDE3Ljk0ODksMTAuMzcwMiAxNy45ODI2LDEwLjE2MTQgQzE3Ljk5NCwxMC4xMDk0IDE4LDEwLjA1NTQgMTgsMTAuMDAwMDAxMiBDMTgsOS45NDI0MSAxNy45OTM1LDkuODg2MzMgMTcuOTgxMiw5LjgzMjQ2IEMxNy45NDYyLDkuNjI2NjcgMTcuODQ2Nyw5LjQyOTc2IDE3LjY4MjYsOS4yNzQ1NSBMMTEuMjY1NCwzLjIwNTExIFpcIlxuICAgICAgICAgICAgICAgICAgICAvPlxuICAgICAgICAgICAgICAgICAgPC9nPlxuICAgICAgICAgICAgICAgIDwvZz5cbiAgICAgICAgICAgICAgPC9zdmc+XG4gICAgICAgICAgICA8L2VsLWljb24+XG4gICAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPC9lbC1kYXRlLXBpY2tlcj5cbiAgICAgIDwvZGl2PlxuICAgICAgPGRpdiBjbGFzcz1cImxpbmVcIiAvPlxuICAgICAgPGRpdiBjbGFzcz1cImJsb2NrXCI+XG4gICAgICAgIDxkaXYgY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+ZGF0ZSByYW5nZTwvZGl2PlxuICAgICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgICAgICB0eXBlPVwiZGF0ZXJhbmdlXCJcbiAgICAgICAgICBzdGFydC1wbGFjZWhvbGRlcj1cIlN0YXJ0IGRhdGVcIlxuICAgICAgICAgIGVuZC1wbGFjZWhvbGRlcj1cIkVuZCBkYXRlXCJcbiAgICAgICAgICBmb3JtYXQ9XCJZWVlZL01NL0REXCJcbiAgICAgICAgICB2YWx1ZS1mb3JtYXQ9XCJZWVlZLU1NLUREXCJcbiAgICAgICAgICB1bmxpbmstcGFuZWxzXG4gICAgICAgID5cbiAgICAgICAgICA8dGVtcGxhdGUgI3ByZXYtbW9udGg+XG4gICAgICAgICAgICA8ZWwtaWNvbj48Q2FyZXRMZWZ0IC8+PC9lbC1pY29uPlxuICAgICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgICAgPHRlbXBsYXRlICNuZXh0LW1vbnRoPlxuICAgICAgICAgICAgPGVsLWljb24+PENhcmV0UmlnaHQgLz48L2VsLWljb24+XG4gICAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgICA8dGVtcGxhdGUgI3ByZXYteWVhcj5cbiAgICAgICAgICAgIDxlbC1pY29uPlxuICAgICAgICAgICAgICA8c3ZnXG4gICAgICAgICAgICAgICAgdmlld0JveD1cIjAgMCAyMCAyMFwiXG4gICAgICAgICAgICAgICAgdmVyc2lvbj1cIjEuMVwiXG4gICAgICAgICAgICAgICAgeG1sbnM9XCJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2Z1wiXG4gICAgICAgICAgICAgID5cbiAgICAgICAgICAgICAgICA8ZyBzdHJva2Utd2lkdGg9XCIxXCIgZmlsbC1ydWxlPVwiZXZlbm9kZFwiPlxuICAgICAgICAgICAgICAgICAgPGcgZmlsbD1cImN1cnJlbnRDb2xvclwiPlxuICAgICAgICAgICAgICAgICAgICA8cGF0aFxuICAgICAgICAgICAgICAgICAgICAgIGQ9XCJNOC43MzE3MSwxNi43OTQ5IEM5LjAzMjY0LDE3LjA3OTUgOS41MDczMywxNy4wNjYzIDkuNzkxOTYsMTYuNzY1NCBDMTAuMDc2NiwxNi40NjQ0IDEwLjA2MzQsMTUuOTg5NyA5Ljc2MjQzLDE1LjcwNTEgTDQuNTIzMzksMTAuNzUgTDE3LjI0NzEsMTAuNzUgQzE3LjY2MTMsMTAuNzUgMTcuOTk3MSwxMC40MTQyIDE3Ljk5NzEsMTAgQzE3Ljk5NzEsOS41ODU3OSAxNy42NjEzLDkuMjUgMTcuMjQ3MSw5LjI1IEw0LjUyMTEyLDkuMjUgTDkuNzYyNDMsNC4yOTI3NSBDMTAuMDYzNCw0LjAwODEyIDEwLjA3NjYsMy41MzM0MyA5Ljc5MTk2LDMuMjMyNSBDOS41MDczMywyLjkzMTU2IDkuMDMyNjQsMi45MTgzNCA4LjczMTcxLDMuMjAyOTcgTDIuMzE0NDksOS4yNzI0MSBDMi4xNDgxOSw5LjQyOTcgMi4wNDgxOSw5LjYyOTgxIDIuMDE0NDgsOS44Mzg2IEMyLjAwMzA4LDkuODkwNTggMS45OTcwNyw5Ljk0NDU5IDEuOTk3MDcsMTAgQzEuOTk3MDcsMTAuMDU3NiAyLjAwMzU2LDEwLjExMzcgMi4wMTU4NSwxMC4xNjc1IEMyLjA1MDg0LDEwLjM3MzMgMi4xNTAzOSwxMC41NzAyIDIuMzE0NDksMTAuNzI1NCBMOC43MzE3MSwxNi43OTQ5IFpcIlxuICAgICAgICAgICAgICAgICAgICAvPlxuICAgICAgICAgICAgICAgICAgPC9nPlxuICAgICAgICAgICAgICAgIDwvZz5cbiAgICAgICAgICAgICAgPC9zdmc+XG4gICAgICAgICAgICA8L2VsLWljb24+XG4gICAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgICA8dGVtcGxhdGUgI25leHQteWVhcj5cbiAgICAgICAgICAgIDxlbC1pY29uPlxuICAgICAgICAgICAgICA8c3ZnXG4gICAgICAgICAgICAgICAgdmlld0JveD1cIjAgMCAyMCAyMFwiXG4gICAgICAgICAgICAgICAgdmVyc2lvbj1cIjEuMVwiXG4gICAgICAgICAgICAgICAgeG1sbnM9XCJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2Z1wiXG4gICAgICAgICAgICAgID5cbiAgICAgICAgICAgICAgICA8ZyBzdHJva2Utd2lkdGg9XCIxXCIgZmlsbC1ydWxlPVwiZXZlbm9kZFwiPlxuICAgICAgICAgICAgICAgICAgPGcgZmlsbD1cImN1cnJlbnRDb2xvclwiPlxuICAgICAgICAgICAgICAgICAgICA8cGF0aFxuICAgICAgICAgICAgICAgICAgICAgIGQ9XCJNMTEuMjY1NCwzLjIwNTExIEMxMC45NjQ0LDIuOTIwNDkgMTAuNDg5NywyLjkzMzcxIDEwLjIwNTEsMy4yMzQ2NCBDOS45MjA0OSwzLjUzNTU4IDkuOTMzNzEsNC4wMTAyNyAxMC4yMzQ2LDQuMjk0ODkgTDE1LjQ3MzcsOS4yNSBMMi43NSw5LjI1IEMyLjMzNTc5LDkuMjUgMiw5LjU4NTc5IDIsMTAuMDAwMDAxMiBDMiwxMC40MTQyIDIuMzM1NzksMTAuNzUgMi43NSwxMC43NSBMMTUuNDc2LDEwLjc1IEwxMC4yMzQ2LDE1LjcwNzMgQzkuOTMzNzEsMTUuOTkxOSA5LjkyMDQ5LDE2LjQ2NjYgMTAuMjA1MSwxNi43Njc1IEMxMC40ODk3LDE3LjA2ODQgMTAuOTY0NCwxNy4wODE3IDExLjI2NTQsMTYuNzk3IEwxNy42ODI2LDEwLjcyNzYgQzE3Ljg0ODksMTAuNTcwMyAxNy45NDg5LDEwLjM3MDIgMTcuOTgyNiwxMC4xNjE0IEMxNy45OTQsMTAuMTA5NCAxOCwxMC4wNTU0IDE4LDEwLjAwMDAwMTIgQzE4LDkuOTQyNDEgMTcuOTkzNSw5Ljg4NjMzIDE3Ljk4MTIsOS44MzI0NiBDMTcuOTQ2Miw5LjYyNjY3IDE3Ljg0NjcsOS40Mjk3NiAxNy42ODI2LDkuMjc0NTUgTDExLjI2NTQsMy4yMDUxMSBaXCJcbiAgICAgICAgICAgICAgICAgICAgLz5cbiAgICAgICAgICAgICAgICAgIDwvZz5cbiAgICAgICAgICAgICAgICA8L2c+XG4gICAgICAgICAgICAgIDwvc3ZnPlxuICAgICAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDwvZWwtZGF0ZS1waWNrZXI+XG4gICAgICA8L2Rpdj5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwiY29udGFpbmVyXCI+XG4gICAgICA8ZGl2IGNsYXNzPVwibGluZVwiIC8+XG4gICAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgICAgPGRpdiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5tb250aCByYW5nZTwvZGl2PlxuICAgICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgICB2LW1vZGVsPVwidmFsdWUzXCJcbiAgICAgICAgICB0eXBlPVwibW9udGhyYW5nZVwiXG4gICAgICAgICAgc3RhcnQtcGxhY2Vob2xkZXI9XCJTdGFydCBkYXRlXCJcbiAgICAgICAgICBlbmQtcGxhY2Vob2xkZXI9XCJFbmQgZGF0ZVwiXG4gICAgICAgICAgZm9ybWF0PVwiWVlZWS9NTS9ERFwiXG4gICAgICAgICAgdmFsdWUtZm9ybWF0PVwiWVlZWS1NTS1ERFwiXG4gICAgICAgICAgdW5saW5rLXBhbmVsc1xuICAgICAgICA+XG4gICAgICAgICAgPHRlbXBsYXRlICNwcmV2LW1vbnRoPlxuICAgICAgICAgICAgPGVsLWljb24+PENhcmV0TGVmdCAvPjwvZWwtaWNvbj5cbiAgICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICAgIDx0ZW1wbGF0ZSAjbmV4dC1tb250aD5cbiAgICAgICAgICAgIDxlbC1pY29uPjxDYXJldFJpZ2h0IC8+PC9lbC1pY29uPlxuICAgICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgICAgPHRlbXBsYXRlICNwcmV2LXllYXI+XG4gICAgICAgICAgICA8ZWwtaWNvbj5cbiAgICAgICAgICAgICAgPHN2Z1xuICAgICAgICAgICAgICAgIHZpZXdCb3g9XCIwIDAgMjAgMjBcIlxuICAgICAgICAgICAgICAgIHZlcnNpb249XCIxLjFcIlxuICAgICAgICAgICAgICAgIHhtbG5zPVwiaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmdcIlxuICAgICAgICAgICAgICA+XG4gICAgICAgICAgICAgICAgPGcgc3Ryb2tlLXdpZHRoPVwiMVwiIGZpbGwtcnVsZT1cImV2ZW5vZGRcIj5cbiAgICAgICAgICAgICAgICAgIDxnIGZpbGw9XCJjdXJyZW50Q29sb3JcIj5cbiAgICAgICAgICAgICAgICAgICAgPHBhdGhcbiAgICAgICAgICAgICAgICAgICAgICBkPVwiTTguNzMxNzEsMTYuNzk0OSBDOS4wMzI2NCwxNy4wNzk1IDkuNTA3MzMsMTcuMDY2MyA5Ljc5MTk2LDE2Ljc2NTQgQzEwLjA3NjYsMTYuNDY0NCAxMC4wNjM0LDE1Ljk4OTcgOS43NjI0MywxNS43MDUxIEw0LjUyMzM5LDEwLjc1IEwxNy4yNDcxLDEwLjc1IEMxNy42NjEzLDEwLjc1IDE3Ljk5NzEsMTAuNDE0MiAxNy45OTcxLDEwIEMxNy45OTcxLDkuNTg1NzkgMTcuNjYxMyw5LjI1IDE3LjI0NzEsOS4yNSBMNC41MjExMiw5LjI1IEw5Ljc2MjQzLDQuMjkyNzUgQzEwLjA2MzQsNC4wMDgxMiAxMC4wNzY2LDMuNTMzNDMgOS43OTE5NiwzLjIzMjUgQzkuNTA3MzMsMi45MzE1NiA5LjAzMjY0LDIuOTE4MzQgOC43MzE3MSwzLjIwMjk3IEwyLjMxNDQ5LDkuMjcyNDEgQzIuMTQ4MTksOS40Mjk3IDIuMDQ4MTksOS42Mjk4MSAyLjAxNDQ4LDkuODM4NiBDMi4wMDMwOCw5Ljg5MDU4IDEuOTk3MDcsOS45NDQ1OSAxLjk5NzA3LDEwIEMxLjk5NzA3LDEwLjA1NzYgMi4wMDM1NiwxMC4xMTM3IDIuMDE1ODUsMTAuMTY3NSBDMi4wNTA4NCwxMC4zNzMzIDIuMTUwMzksMTAuNTcwMiAyLjMxNDQ5LDEwLjcyNTQgTDguNzMxNzEsMTYuNzk0OSBaXCJcbiAgICAgICAgICAgICAgICAgICAgLz5cbiAgICAgICAgICAgICAgICAgIDwvZz5cbiAgICAgICAgICAgICAgICA8L2c+XG4gICAgICAgICAgICAgIDwvc3ZnPlxuICAgICAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgICAgPHRlbXBsYXRlICNuZXh0LXllYXI+XG4gICAgICAgICAgICA8ZWwtaWNvbj5cbiAgICAgICAgICAgICAgPHN2Z1xuICAgICAgICAgICAgICAgIHZpZXdCb3g9XCIwIDAgMjAgMjBcIlxuICAgICAgICAgICAgICAgIHZlcnNpb249XCIxLjFcIlxuICAgICAgICAgICAgICAgIHhtbG5zPVwiaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmdcIlxuICAgICAgICAgICAgICA+XG4gICAgICAgICAgICAgICAgPGcgc3Ryb2tlLXdpZHRoPVwiMVwiIGZpbGwtcnVsZT1cImV2ZW5vZGRcIj5cbiAgICAgICAgICAgICAgICAgIDxnIGZpbGw9XCJjdXJyZW50Q29sb3JcIj5cbiAgICAgICAgICAgICAgICAgICAgPHBhdGhcbiAgICAgICAgICAgICAgICAgICAgICBkPVwiTTExLjI2NTQsMy4yMDUxMSBDMTAuOTY0NCwyLjkyMDQ5IDEwLjQ4OTcsMi45MzM3MSAxMC4yMDUxLDMuMjM0NjQgQzkuOTIwNDksMy41MzU1OCA5LjkzMzcxLDQuMDEwMjcgMTAuMjM0Niw0LjI5NDg5IEwxNS40NzM3LDkuMjUgTDIuNzUsOS4yNSBDMi4zMzU3OSw5LjI1IDIsOS41ODU3OSAyLDEwLjAwMDAwMTIgQzIsMTAuNDE0MiAyLjMzNTc5LDEwLjc1IDIuNzUsMTAuNzUgTDE1LjQ3NiwxMC43NSBMMTAuMjM0NiwxNS43MDczIEM5LjkzMzcxLDE1Ljk5MTkgOS45MjA0OSwxNi40NjY2IDEwLjIwNTEsMTYuNzY3NSBDMTAuNDg5NywxNy4wNjg0IDEwLjk2NDQsMTcuMDgxNyAxMS4yNjU0LDE2Ljc5NyBMMTcuNjgyNiwxMC43Mjc2IEMxNy44NDg5LDEwLjU3MDMgMTcuOTQ4OSwxMC4zNzAyIDE3Ljk4MjYsMTAuMTYxNCBDMTcuOTk0LDEwLjEwOTQgMTgsMTAuMDU1NCAxOCwxMC4wMDAwMDEyIEMxOCw5Ljk0MjQxIDE3Ljk5MzUsOS44ODYzMyAxNy45ODEyLDkuODMyNDYgQzE3Ljk0NjIsOS42MjY2NyAxNy44NDY3LDkuNDI5NzYgMTcuNjgyNiw5LjI3NDU1IEwxMS4yNjU0LDMuMjA1MTEgWlwiXG4gICAgICAgICAgICAgICAgICAgIC8+XG4gICAgICAgICAgICAgICAgICA8L2c+XG4gICAgICAgICAgICAgICAgPC9nPlxuICAgICAgICAgICAgICA8L3N2Zz5cbiAgICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICA8L2VsLWRhdGUtcGlja2VyPlxuICAgICAgPC9kaXY+XG4gICAgICA8ZGl2IGNsYXNzPVwibGluZVwiIC8+XG4gICAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgICAgPGRpdiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj55ZWFyIHJhbmdlPC9kaXY+XG4gICAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTRcIlxuICAgICAgICAgIHR5cGU9XCJ5ZWFycmFuZ2VcIlxuICAgICAgICAgIHJhbmdlLXNlcGFyYXRvcj1cIlRvXCJcbiAgICAgICAgICBzdGFydC1wbGFjZWhvbGRlcj1cIlN0YXJ0IFllYXJcIlxuICAgICAgICAgIGVuZC1wbGFjZWhvbGRlcj1cIkVuZCBZZWFyXCJcbiAgICAgICAgPlxuICAgICAgICAgIDx0ZW1wbGF0ZSAjcHJldi15ZWFyPlxuICAgICAgICAgICAgPGVsLWljb24+XG4gICAgICAgICAgICAgIDxzdmdcbiAgICAgICAgICAgICAgICB2aWV3Qm94PVwiMCAwIDIwIDIwXCJcbiAgICAgICAgICAgICAgICB2ZXJzaW9uPVwiMS4xXCJcbiAgICAgICAgICAgICAgICB4bWxucz1cImh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnXCJcbiAgICAgICAgICAgICAgPlxuICAgICAgICAgICAgICAgIDxnIHN0cm9rZS13aWR0aD1cIjFcIiBmaWxsLXJ1bGU9XCJldmVub2RkXCI+XG4gICAgICAgICAgICAgICAgICA8ZyBmaWxsPVwiY3VycmVudENvbG9yXCI+XG4gICAgICAgICAgICAgICAgICAgIDxwYXRoXG4gICAgICAgICAgICAgICAgICAgICAgZD1cIk04LjczMTcxLDE2Ljc5NDkgQzkuMDMyNjQsMTcuMDc5NSA5LjUwNzMzLDE3LjA2NjMgOS43OTE5NiwxNi43NjU0IEMxMC4wNzY2LDE2LjQ2NDQgMTAuMDYzNCwxNS45ODk3IDkuNzYyNDMsMTUuNzA1MSBMNC41MjMzOSwxMC43NSBMMTcuMjQ3MSwxMC43NSBDMTcuNjYxMywxMC43NSAxNy45OTcxLDEwLjQxNDIgMTcuOTk3MSwxMCBDMTcuOTk3MSw5LjU4NTc5IDE3LjY2MTMsOS4yNSAxNy4yNDcxLDkuMjUgTDQuNTIxMTIsOS4yNSBMOS43NjI0Myw0LjI5Mjc1IEMxMC4wNjM0LDQuMDA4MTIgMTAuMDc2NiwzLjUzMzQzIDkuNzkxOTYsMy4yMzI1IEM5LjUwNzMzLDIuOTMxNTYgOS4wMzI2NCwyLjkxODM0IDguNzMxNzEsMy4yMDI5NyBMMi4zMTQ0OSw5LjI3MjQxIEMyLjE0ODE5LDkuNDI5NyAyLjA0ODE5LDkuNjI5ODEgMi4wMTQ0OCw5LjgzODYgQzIuMDAzMDgsOS44OTA1OCAxLjk5NzA3LDkuOTQ0NTkgMS45OTcwNywxMCBDMS45OTcwNywxMC4wNTc2IDIuMDAzNTYsMTAuMTEzNyAyLjAxNTg1LDEwLjE2NzUgQzIuMDUwODQsMTAuMzczMyAyLjE1MDM5LDEwLjU3MDIgMi4zMTQ0OSwxMC43MjU0IEw4LjczMTcxLDE2Ljc5NDkgWlwiXG4gICAgICAgICAgICAgICAgICAgIC8+XG4gICAgICAgICAgICAgICAgICA8L2c+XG4gICAgICAgICAgICAgICAgPC9nPlxuICAgICAgICAgICAgICA8L3N2Zz5cbiAgICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICAgIDx0ZW1wbGF0ZSAjbmV4dC15ZWFyPlxuICAgICAgICAgICAgPGVsLWljb24+XG4gICAgICAgICAgICAgIDxzdmdcbiAgICAgICAgICAgICAgICB2aWV3Qm94PVwiMCAwIDIwIDIwXCJcbiAgICAgICAgICAgICAgICB2ZXJzaW9uPVwiMS4xXCJcbiAgICAgICAgICAgICAgICB4bWxucz1cImh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnXCJcbiAgICAgICAgICAgICAgPlxuICAgICAgICAgICAgICAgIDxnIHN0cm9rZS13aWR0aD1cIjFcIiBmaWxsLXJ1bGU9XCJldmVub2RkXCI+XG4gICAgICAgICAgICAgICAgICA8ZyBmaWxsPVwiY3VycmVudENvbG9yXCI+XG4gICAgICAgICAgICAgICAgICAgIDxwYXRoXG4gICAgICAgICAgICAgICAgICAgICAgZD1cIk0xMS4yNjU0LDMuMjA1MTEgQzEwLjk2NDQsMi45MjA0OSAxMC40ODk3LDIuOTMzNzEgMTAuMjA1MSwzLjIzNDY0IEM5LjkyMDQ5LDMuNTM1NTggOS45MzM3MSw0LjAxMDI3IDEwLjIzNDYsNC4yOTQ4OSBMMTUuNDczNyw5LjI1IEwyLjc1LDkuMjUgQzIuMzM1NzksOS4yNSAyLDkuNTg1NzkgMiwxMC4wMDAwMDEyIEMyLDEwLjQxNDIgMi4zMzU3OSwxMC43NSAyLjc1LDEwLjc1IEwxNS40NzYsMTAuNzUgTDEwLjIzNDYsMTUuNzA3MyBDOS45MzM3MSwxNS45OTE5IDkuOTIwNDksMTYuNDY2NiAxMC4yMDUxLDE2Ljc2NzUgQzEwLjQ4OTcsMTcuMDY4NCAxMC45NjQ0LDE3LjA4MTcgMTEuMjY1NCwxNi43OTcgTDE3LjY4MjYsMTAuNzI3NiBDMTcuODQ4OSwxMC41NzAzIDE3Ljk0ODksMTAuMzcwMiAxNy45ODI2LDEwLjE2MTQgQzE3Ljk5NCwxMC4xMDk0IDE4LDEwLjA1NTQgMTgsMTAuMDAwMDAxMiBDMTgsOS45NDI0MSAxNy45OTM1LDkuODg2MzMgMTcuOTgxMiw5LjgzMjQ2IEMxNy45NDYyLDkuNjI2NjcgMTcuODQ2Nyw5LjQyOTc2IDE3LjY4MjYsOS4yNzQ1NSBMMTEuMjY1NCwzLjIwNTExIFpcIlxuICAgICAgICAgICAgICAgICAgICAvPlxuICAgICAgICAgICAgICAgICAgPC9nPlxuICAgICAgICAgICAgICAgIDwvZz5cbiAgICAgICAgICAgICAgPC9zdmc+XG4gICAgICAgICAgICA8L2VsLWljb24+XG4gICAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPC9lbC1kYXRlLXBpY2tlcj5cbiAgICAgIDwvZGl2PlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBDYXJldExlZnQsIENhcmV0UmlnaHQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgdmFsdWUxID0gcmVmKCcnKVxuY29uc3QgdmFsdWUyID0gcmVmKCcnKVxuY29uc3QgdmFsdWUzID0gcmVmKCcnKVxuY29uc3QgdmFsdWU0ID0gcmVmKCcnKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1kYXRlLXBpY2tlci1pY29uIHtcbiAgZGlzcGxheTogZmxleDtcbiAgd2lkdGg6IDEwMCU7XG4gIHBhZGRpbmc6IDA7XG4gIGZsZXgtd3JhcDogd3JhcDtcbiAgZ2FwOiAxcHg7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyLWljb24gLmNvbnRhaW5lciB7XG4gIGZsZXg6IDE7XG4gIG1pbi13aWR0aDogNDAwcHg7XG4gIGJvcmRlci1yaWdodDogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGZsZXgtZGlyZWN0aW9uOiBjb2x1bW47XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyLWljb24gLmNvbnRhaW5lcjpsYXN0LWNoaWxkIHtcbiAgYm9yZGVyLXJpZ2h0OiBub25lO1xufVxuXG4uZGVtby1kYXRlLXBpY2tlci1pY29uIC5ibG9jayB7XG4gIHBhZGRpbmc6IDEuNXJlbSAwO1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGZsZXgtZGlyZWN0aW9uOiBjb2x1bW47XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyLWljb24gLmJsb2NrOm5vdCg6Zmlyc3QtY2hpbGQpIHtcbiAgYm9yZGVyLXRvcDogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG59XG5cbi5kZW1vLWRhdGUtcGlja2VyLWljb24gLmRlbW9uc3RyYXRpb24ge1xuICBkaXNwbGF5OiBibG9jaztcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbiAgZm9udC1zaXplOiAxNHB4O1xuICBtYXJnaW4tYm90dG9tOiAxcmVtO1xuICB3aWR0aDogMTAwJTtcbn1cblxuQG1lZGlhIHNjcmVlbiBhbmQgKG1heC13aWR0aDogMTIwMHB4KSB7XG4gIC5kZW1vLWRhdGUtcGlja2VyLWljb24ge1xuICAgIGdhcDogMDtcbiAgfVxuXG4gIC5kZW1vLWRhdGUtcGlja2VyLWljb24gLmNvbnRhaW5lciB7XG4gICAgZmxleDogMCAwIDEwMCU7XG4gICAgbWluLXdpZHRoOiBhdXRvO1xuICAgIGJvcmRlci1yaWdodDogbm9uZTtcbiAgfVxuXG4gIC5kZW1vLWRhdGUtcGlja2VyLWljb24gLmNvbnRhaW5lcjpub3QoOmxhc3QtY2hpbGQpIHtcbiAgICBib3JkZXItYm90dG9tOiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgfVxuXG4gIC5kZW1vLWRhdGUtcGlja2VyLWljb24gLmJsb2NrIHtcbiAgICBwYWRkaW5nOiAxcmVtIDA7XG4gIH1cblxuICAuZGVtby1kYXRlLXBpY2tlci1pY29uIC5ibG9jazpub3QoOmZpcnN0LWNoaWxkKSB7XG4gICAgcG9zaXRpb246IHJlbGF0aXZlO1xuICAgIG1hcmdpbi10b3A6IC0xcHg7XG4gIH1cbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/date-picker/custom-icon.vue)_

vue

```
<template>
  <div class="demo-date-picker-icon">
    <div class="container">
      <div class="block">
        <div class="demonstration">date</div>
        <el-date-picker
          v-model="value1"
          type="date"
          placeholder="Pick a day"
          format="YYYY/MM/DD"
          value-format="YYYY-MM-DD"
        >
          <template #prev-month>
            <el-icon><CaretLeft /></el-icon>
          </template>
          <template #next-month>
            <el-icon><CaretRight /></el-icon>
          </template>
          <template #prev-year>
            <el-icon>
              <svg
                viewBox="0 0 20 20"
                version="1.1"
                xmlns="http://www.w3.org/2000/svg"
              >
                <g stroke-width="1" fill-rule="evenodd">
                  <g fill="currentColor">
                    <path
                      d="M8.73171,16.7949 C9.03264,17.0795 9.50733,17.0663 9.79196,16.7654 C10.0766,16.4644 10.0634,15.9897 9.76243,15.7051 L4.52339,10.75 L17.2471,10.75 C17.6613,10.75 17.9971,10.4142 17.9971,10 C17.9971,9.58579 17.6613,9.25 17.2471,9.25 L4.52112,9.25 L9.76243,4.29275 C10.0634,4.00812 10.0766,3.53343 9.79196,3.2325 C9.50733,2.93156 9.03264,2.91834 8.73171,3.20297 L2.31449,9.27241 C2.14819,9.4297 2.04819,9.62981 2.01448,9.8386 C2.00308,9.89058 1.99707,9.94459 1.99707,10 C1.99707,10.0576 2.00356,10.1137 2.01585,10.1675 C2.05084,10.3733 2.15039,10.5702 2.31449,10.7254 L8.73171,16.7949 Z"
                    />
                  </g>
                </g>
              </svg>
            </el-icon>
          </template>
          <template #next-year>
            <el-icon>
              <svg
                viewBox="0 0 20 20"
                version="1.1"
                xmlns="http://www.w3.org/2000/svg"
              >
                <g stroke-width="1" fill-rule="evenodd">
                  <g fill="currentColor">
                    <path
                      d="M11.2654,3.20511 C10.9644,2.92049 10.4897,2.93371 10.2051,3.23464 C9.92049,3.53558 9.93371,4.01027 10.2346,4.29489 L15.4737,9.25 L2.75,9.25 C2.33579,9.25 2,9.58579 2,10.0000012 C2,10.4142 2.33579,10.75 2.75,10.75 L15.476,10.75 L10.2346,15.7073 C9.93371,15.9919 9.92049,16.4666 10.2051,16.7675 C10.4897,17.0684 10.9644,17.0817 11.2654,16.797 L17.6826,10.7276 C17.8489,10.5703 17.9489,10.3702 17.9826,10.1614 C17.994,10.1094 18,10.0554 18,10.0000012 C18,9.94241 17.9935,9.88633 17.9812,9.83246 C17.9462,9.62667 17.8467,9.42976 17.6826,9.27455 L11.2654,3.20511 Z"
                    />
                  </g>
                </g>
              </svg>
            </el-icon>
          </template>
        </el-date-picker>
      </div>
      <div class="line" />
      <div class="block">
        <div class="demonstration">date range</div>
        <el-date-picker
          v-model="value2"
          type="daterange"
          start-placeholder="Start date"
          end-placeholder="End date"
          format="YYYY/MM/DD"
          value-format="YYYY-MM-DD"
          unlink-panels
        >
          <template #prev-month>
            <el-icon><CaretLeft /></el-icon>
          </template>
          <template #next-month>
            <el-icon><CaretRight /></el-icon>
          </template>
          <template #prev-year>
            <el-icon>
              <svg
                viewBox="0 0 20 20"
                version="1.1"
                xmlns="http://www.w3.org/2000/svg"
              >
                <g stroke-width="1" fill-rule="evenodd">
                  <g fill="currentColor">
                    <path
                      d="M8.73171,16.7949 C9.03264,17.0795 9.50733,17.0663 9.79196,16.7654 C10.0766,16.4644 10.0634,15.9897 9.76243,15.7051 L4.52339,10.75 L17.2471,10.75 C17.6613,10.75 17.9971,10.4142 17.9971,10 C17.9971,9.58579 17.6613,9.25 17.2471,9.25 L4.52112,9.25 L9.76243,4.29275 C10.0634,4.00812 10.0766,3.53343 9.79196,3.2325 C9.50733,2.93156 9.03264,2.91834 8.73171,3.20297 L2.31449,9.27241 C2.14819,9.4297 2.04819,9.62981 2.01448,9.8386 C2.00308,9.89058 1.99707,9.94459 1.99707,10 C1.99707,10.0576 2.00356,10.1137 2.01585,10.1675 C2.05084,10.3733 2.15039,10.5702 2.31449,10.7254 L8.73171,16.7949 Z"
                    />
                  </g>
                </g>
              </svg>
            </el-icon>
          </template>
          <template #next-year>
            <el-icon>
              <svg
                viewBox="0 0 20 20"
                version="1.1"
                xmlns="http://www.w3.org/2000/svg"
              >
                <g stroke-width="1" fill-rule="evenodd">
                  <g fill="currentColor">
                    <path
                      d="M11.2654,3.20511 C10.9644,2.92049 10.4897,2.93371 10.2051,3.23464 C9.92049,3.53558 9.93371,4.01027 10.2346,4.29489 L15.4737,9.25 L2.75,9.25 C2.33579,9.25 2,9.58579 2,10.0000012 C2,10.4142 2.33579,10.75 2.75,10.75 L15.476,10.75 L10.2346,15.7073 C9.93371,15.9919 9.92049,16.4666 10.2051,16.7675 C10.4897,17.0684 10.9644,17.0817 11.2654,16.797 L17.6826,10.7276 C17.8489,10.5703 17.9489,10.3702 17.9826,10.1614 C17.994,10.1094 18,10.0554 18,10.0000012 C18,9.94241 17.9935,9.88633 17.9812,9.83246 C17.9462,9.62667 17.8467,9.42976 17.6826,9.27455 L11.2654,3.20511 Z"
                    />
                  </g>
                </g>
              </svg>
            </el-icon>
          </template>
        </el-date-picker>
      </div>
    </div>
    <div class="container">
      <div class="line" />
      <div class="block">
        <div class="demonstration">month range</div>
        <el-date-picker
          v-model="value3"
          type="monthrange"
          start-placeholder="Start date"
          end-placeholder="End date"
          format="YYYY/MM/DD"
          value-format="YYYY-MM-DD"
          unlink-panels
        >
          <template #prev-month>
            <el-icon><CaretLeft /></el-icon>
          </template>
          <template #next-month>
            <el-icon><CaretRight /></el-icon>
          </template>
          <template #prev-year>
            <el-icon>
              <svg
                viewBox="0 0 20 20"
                version="1.1"
                xmlns="http://www.w3.org/2000/svg"
              >
                <g stroke-width="1" fill-rule="evenodd">
                  <g fill="currentColor">
                    <path
                      d="M8.73171,16.7949 C9.03264,17.0795 9.50733,17.0663 9.79196,16.7654 C10.0766,16.4644 10.0634,15.9897 9.76243,15.7051 L4.52339,10.75 L17.2471,10.75 C17.6613,10.75 17.9971,10.4142 17.9971,10 C17.9971,9.58579 17.6613,9.25 17.2471,9.25 L4.52112,9.25 L9.76243,4.29275 C10.0634,4.00812 10.0766,3.53343 9.79196,3.2325 C9.50733,2.93156 9.03264,2.91834 8.73171,3.20297 L2.31449,9.27241 C2.14819,9.4297 2.04819,9.62981 2.01448,9.8386 C2.00308,9.89058 1.99707,9.94459 1.99707,10 C1.99707,10.0576 2.00356,10.1137 2.01585,10.1675 C2.05084,10.3733 2.15039,10.5702 2.31449,10.7254 L8.73171,16.7949 Z"
                    />
                  </g>
                </g>
              </svg>
            </el-icon>
          </template>
          <template #next-year>
            <el-icon>
              <svg
                viewBox="0 0 20 20"
                version="1.1"
                xmlns="http://www.w3.org/2000/svg"
              >
                <g stroke-width="1" fill-rule="evenodd">
                  <g fill="currentColor">
                    <path
                      d="M11.2654,3.20511 C10.9644,2.92049 10.4897,2.93371 10.2051,3.23464 C9.92049,3.53558 9.93371,4.01027 10.2346,4.29489 L15.4737,9.25 L2.75,9.25 C2.33579,9.25 2,9.58579 2,10.0000012 C2,10.4142 2.33579,10.75 2.75,10.75 L15.476,10.75 L10.2346,15.7073 C9.93371,15.9919 9.92049,16.4666 10.2051,16.7675 C10.4897,17.0684 10.9644,17.0817 11.2654,16.797 L17.6826,10.7276 C17.8489,10.5703 17.9489,10.3702 17.9826,10.1614 C17.994,10.1094 18,10.0554 18,10.0000012 C18,9.94241 17.9935,9.88633 17.9812,9.83246 C17.9462,9.62667 17.8467,9.42976 17.6826,9.27455 L11.2654,3.20511 Z"
                    />
                  </g>
                </g>
              </svg>
            </el-icon>
          </template>
        </el-date-picker>
      </div>
      <div class="line" />
      <div class="block">
        <div class="demonstration">year range</div>
        <el-date-picker
          v-model="value4"
          type="yearrange"
          range-separator="To"
          start-placeholder="Start Year"
          end-placeholder="End Year"
        >
          <template #prev-year>
            <el-icon>
              <svg
                viewBox="0 0 20 20"
                version="1.1"
                xmlns="http://www.w3.org/2000/svg"
              >
                <g stroke-width="1" fill-rule="evenodd">
                  <g fill="currentColor">
                    <path
                      d="M8.73171,16.7949 C9.03264,17.0795 9.50733,17.0663 9.79196,16.7654 C10.0766,16.4644 10.0634,15.9897 9.76243,15.7051 L4.52339,10.75 L17.2471,10.75 C17.6613,10.75 17.9971,10.4142 17.9971,10 C17.9971,9.58579 17.6613,9.25 17.2471,9.25 L4.52112,9.25 L9.76243,4.29275 C10.0634,4.00812 10.0766,3.53343 9.79196,3.2325 C9.50733,2.93156 9.03264,2.91834 8.73171,3.20297 L2.31449,9.27241 C2.14819,9.4297 2.04819,9.62981 2.01448,9.8386 C2.00308,9.89058 1.99707,9.94459 1.99707,10 C1.99707,10.0576 2.00356,10.1137 2.01585,10.1675 C2.05084,10.3733 2.15039,10.5702 2.31449,10.7254 L8.73171,16.7949 Z"
                    />
                  </g>
                </g>
              </svg>
            </el-icon>
          </template>
          <template #next-year>
            <el-icon>
              <svg
                viewBox="0 0 20 20"
                version="1.1"
                xmlns="http://www.w3.org/2000/svg"
              >
                <g stroke-width="1" fill-rule="evenodd">
                  <g fill="currentColor">
                    <path
                      d="M11.2654,3.20511 C10.9644,2.92049 10.4897,2.93371 10.2051,3.23464 C9.92049,3.53558 9.93371,4.01027 10.2346,4.29489 L15.4737,9.25 L2.75,9.25 C2.33579,9.25 2,9.58579 2,10.0000012 C2,10.4142 2.33579,10.75 2.75,10.75 L15.476,10.75 L10.2346,15.7073 C9.93371,15.9919 9.92049,16.4666 10.2051,16.7675 C10.4897,17.0684 10.9644,17.0817 11.2654,16.797 L17.6826,10.7276 C17.8489,10.5703 17.9489,10.3702 17.9826,10.1614 C17.994,10.1094 18,10.0554 18,10.0000012 C18,9.94241 17.9935,9.88633 17.9812,9.83246 C17.9462,9.62667 17.8467,9.42976 17.6826,9.27455 L11.2654,3.20511 Z"
                    />
                  </g>
                </g>
              </svg>
            </el-icon>
          </template>
        </el-date-picker>
      </div>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { CaretLeft, CaretRight } from '@element-plus/icons-vue'

const value1 = ref('')
const value2 = ref('')
const value3 = ref('')
const value4 = ref('')
</script>

<style scoped>
.demo-date-picker-icon {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
  gap: 1px;
}

.demo-date-picker-icon .container {
  flex: 1;
  min-width: 400px;
  border-right: solid 1px var(--el-border-color);
  display: flex;
  flex-direction: column;
}

.demo-date-picker-icon .container:last-child {
  border-right: none;
}

.demo-date-picker-icon .block {
  padding: 1.5rem 0;
  text-align: center;
  display: flex;
  flex-direction: column;
  align-items: center;
}

.demo-date-picker-icon .block:not(:first-child) {
  border-top: solid 1px var(--el-border-color);
}

.demo-date-picker-icon .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 1rem;
  width: 100%;
}

@media screen and (max-width: 1200px) {
  .demo-date-picker-icon {
    gap: 0;
  }

  .demo-date-picker-icon .container {
    flex: 0 0 100%;
    min-width: auto;
    border-right: none;
  }

  .demo-date-picker-icon .container:not(:last-child) {
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-date-picker-icon .block {
    padding: 1rem 0;
  }

  .demo-date-picker-icon .block:not(:first-child) {
    position: relative;
    margin-top: -1px;
  }
}
</style>
```

隐藏源代码

更详细的数据类型，请查看下表

ts

```
interface DateCell {
  column: number
  customClass: string | undefined
  disabled: boolean
  end: boolean
  inRange: boolean
  row: number
  selected: Dayjs | undefined
  isCurrent: boolean | undefined
  isSelected: boolean
  renderText: string | undefined
  start: boolean
  text: number
  timestamp: number
  date: Date
  dayjs: Dayjs
  type: 'normal' | 'today' | 'week' | 'next-month' | 'prev-month'
}
```

## 国际化 [​](#国际化)

由于 Element Plus 的默认语言为英语，如果你需要设置其它的语言，请参考[国际化](https://element-plus.org/zh-CN/guide/i18n)文档。

要注意的是：日期相关的文字（月份，每一周的第一天等等）也都是通过国际化来配置的。

## API [​](#api)

### 属性 [​](#属性)

| 属性名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| model-value / v-model | 绑定值，如果是 `range` 选择器，数组长度应为 2 | `number` / `string` / `Date` / `array` | '' |
| readonly | 只读 | `boolean` | false |
| disabled | 禁用 | `boolean` | false |
| size | 输入框尺寸 | `enum` | — |
| editable | 文本框可输入 | `boolean` | true |
| clearable | 是否显示清除按钮 | `boolean` | true |
| placeholder | 非范围选择时的占位内容 | `string` | '' |
| start-placeholder | 范围选择时开始日期的占位内容 | `string` | — |
| end-placeholder | 范围选择时结束日期的占位内容 | `string` | — |
| type | 显示类型 | `enum` | date |
| format | 显示在输入框中的格式 | `string` 参考 [日期格式](#date-formats) | YYYY-MM-DD |
| popper-class | DatePicker 下拉框的类名 | `string` | — |
| popper-style | 弹出内容的自定义样式 | `string` / `object` | — |
| popper-options | 自定义 popper 选项，更多请参考 [popper.js](https://popper.js.org/docs/v2/) | `object` | {} |
| range-separator | 选择范围时的分隔符 | `string` | '-' |
| default-value | 可选，选择器打开时默认显示的时间 | `object` | — |
| default-time | 范围选择时选中日期所使用的当日内具体时刻 | `object` | — |
| value-format | 可选，绑定值的格式。 不指定则绑定值为 Date 对象 | `string` 参考 [日期格式](#date-formats) | — |
| id | 等价于原生 input `id` 属性 | `string` / `array` | — |
| name | 等价于原生 input `name` 属性 | `string` / `array` | '' |
| unlink-panels | 在范围选择器里取消两个日期面板之间的联动 | `boolean` | false |
| single-panel 2.14.0 | 在范围选择器中只显示一个面板 | `boolean` | false |
| prefix-icon | 自定义前缀图标 如果 `type`的值是`TimeLikeType`，那么就是 `Clock`，不然就是 `Calendar` | `string` / `object` | '' |
| clear-icon | 自定义清除图标 | `string` / `object` | `CircleClose` |
| validate-event | 是否触发表单验证 | `boolean` | true |
| disabled-date | 一个用来判断该日期是否被禁用的函数，接受一个 Date 对象作为参数。 应该返回一个 Boolean 值。 | `Function` | — |
| shortcuts | 设置快捷选项，需要传入数组对象 | `array` | \[\] |
| cell-class-name | 设置自定义类名 | `Function` | — |
| teleported | 是否将 date-picker 的下拉列表插入至 body 元素 | `boolean` | true |
| empty-values 2.7.0 | 组件的空值配置， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `array` | — |
| value-on-clear 2.7.0 | 清空选项的值， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `string` / `number` / `boolean` / `Function` | — |
| fallback-placements 2.8.4 | Tooltip 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | `array` | \['bottom', 'top', 'right', 'left'\] |
| placement 2.8.4 | 下拉框出现的位置 | `Placement` | bottom |
| show-footer 2.10.5 | 是否显示 footer | `boolean` | true |
| show-confirm 2.11.0 | 是否显示确定按钮 | `boolean` | true |
| show-week-number 2.10.3 | 显示周数(除周外) | `boolean` | 你好 |
| automatic-dropdown 2.11.4 | 该属性决定在输入框获得焦点时日期选择面板是否弹出。 （在 3.0 版本中，默认值将设置为 false） | `boolean` | true |

### 事件 [​](#事件)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 当用户确认值或点击外部时触发 | `Function` |
| blur | 在组件 Input 失去焦点时触发 | `Function` |
| focus | 在组件 Input 获得焦点时触发 | `Function` |
| clear 2.7.7 | 当点击清除按钮时触发 | `Function` |
| calendar-change | 在日历所选日期更改时触发 仅用于 `range` | `Function` |
| panel-change | 当日期面板改变时触发。 | `Function` |
| visible-change | 当 DatePicker 的下拉列表出现/消失时触发 | `Function` |

### 插槽 [​](#插槽)

| 名称 | 说明 |
| --- | --- |
| default | 自定义单元格内容 |
| range-separator | 自定义范围分割符内容 |
| prev-month 2.8.0 | 上个月的图标 |
| next-month 2.8.0 | 下个月的图标 |
| prev-year 2.8.0 | 上一年图标 |
| next-year 2.8.0 | 下一年图标 |

### 暴露 [​](#暴露)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| focus | 使组件获取焦点 | `Function` |
| blur 2.8.7 | 使组件失去焦点 | `Function` |
| handleOpen 2.2.16 | 打开日期选择器弹窗 | `Function` |
| handleClose 2.2.16 | 关闭日期选择器弹窗 | `Function` |

## 类型声明 [​](#类型声明)

显示类型声明

ts

```
import type { Options as PopperOptions } from '@popperjs/core'

type TimeLikeType = 'datetime' | 'datetimerange'

type Placement =
  | 'top'
  | 'top-start'
  | 'top-end'
  | 'bottom'
  | 'bottom-start'
  | 'bottom-end'
  | 'left'
  | 'left-start'
  | 'left-end'
  | 'right'
  | 'right-start'
  | 'right-end'
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/date-picker) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/date-picker.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/date-picker.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/24290011?v=4&size=64)](https://github.com/xingyixiang)[![](https://avatars.githubusercontent.com/u/41944818?v=4&size=64)](https://github.com/CherishTheYouth)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/110156942?v=4&size=64)](https://github.com/a92126)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/22286818?v=4&size=64)](https://github.com/fratzinger)[![](https://avatars.githubusercontent.com/u/45327166?v=4&size=64)](https://github.com/jyp114110)[![](https://avatars.githubusercontent.com/u/54931083?v=4&size=64)](https://github.com/wjp980108)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/54665054?v=4&size=64)](https://github.com/lyric-zemin)[![](https://avatars.githubusercontent.com/u/6340506?v=4&size=64)](https://github.com/mdoi2)[![](https://avatars.githubusercontent.com/u/81006731?v=4&size=64)](https://github.com/Panzer-Jack)[![](https://avatars.githubusercontent.com/u/58782768?v=4&size=64)](https://github.com/dddssw)[![](https://avatars.githubusercontent.com/u/84657208?v=4&size=64)](https://github.com/xiaodong2008)[![](https://avatars.githubusercontent.com/u/31533594?v=4&size=64)](https://github.com/Gnalvin)[![](https://avatars.githubusercontent.com/u/57935341?v=4&size=64)](https://github.com/yuchenii)[![](https://avatars.githubusercontent.com/u/42532333?v=4&size=64)](https://github.com/ivan0525)[![](https://avatars.githubusercontent.com/u/1726061?v=4&size=64)](https://github.com/Justineo)[![](https://avatars.githubusercontent.com/u/108655466?v=4&size=64)](https://github.com/Karolis-Stoncius)[![](https://avatars.githubusercontent.com/u/18509404?v=4&size=64)](https://github.com/inottn)[![](https://avatars.githubusercontent.com/u/79386745?v=4&size=64)](https://github.com/kamesan012)[![](https://avatars.githubusercontent.com/u/55378595?v=4&size=64)](https://github.com/evanryuu)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/35163869?v=4&size=64)](https://github.com/Brain777777)[![](https://avatars.githubusercontent.com/u/30046649?v=4&size=64)](https://github.com/MrWeilian)[![](https://avatars.githubusercontent.com/u/26035718?v=4&size=64)](https://github.com/SnowingFox)[![](https://avatars.githubusercontent.com/u/17247526?v=4&size=64)](https://github.com/nabaonan)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/49087880?v=4&size=64)](https://github.com/pany-ang)[![](https://avatars.githubusercontent.com/u/145281501?v=4&size=64)](https://github.com/typed-sigterm)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/25458528?v=4&size=64)](https://github.com/weidehai)[![](https://avatars.githubusercontent.com/u/82928935?v=4&size=64)](https://github.com/verger-guo)[![](https://avatars.githubusercontent.com/u/4075314?v=4&size=64)](https://github.com/Giwayume)[![](https://avatars.githubusercontent.com/u/44187480?v=4&size=64)](https://github.com/banbri)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/35101675?v=4&size=64)](https://github.com/shenX-2021)[![](https://avatars.githubusercontent.com/u/19464247?v=4&size=64)](https://github.com/lily-elephant)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)

[Date Picker Panel 日期选择器面板](https://element-plus.org/zh-CN/component/date-picker-panel)

[DateTime Picker 日期时间选择器](https://element-plus.org/zh-CN/component/datetime-picker)




---
## [form/datetime-picker] DateTime Picker 日期时间选择器
> 官方文档: https://element-plus.org/zh-CN/component/datetime-picker.html

---

# DateTimePicker 日期时间选择器 [​](#datetimepicker-日期时间选择器)

更新日志待解决

3

在同一个选择器里选择日期和时间

TIP

日期时间选择器来自日期选择器和时间选择器的组合。 关于属性的更详细解释，请参阅日期选择器和时间选择器。

## 日期和时间点 [​](#日期和时间点)

通过设置`type`属性为`datetime`，即可在同一个选择器里同时进行日期和时间的选择。 快捷方式的使用方法与 Date Picker 相同。

Default

With shortcuts

With default time

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRldGltZS1waWNrZXJcIj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPkRlZmF1bHQ8L3NwYW4+XG4gICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgdi1tb2RlbD1cInZhbHVlMVwiXG4gICAgICAgIHR5cGU9XCJkYXRldGltZVwiXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiU2VsZWN0IGRhdGUgYW5kIHRpbWVcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPldpdGggc2hvcnRjdXRzPC9zcGFuPlxuICAgICAgPGVsLWRhdGUtcGlja2VyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTJcIlxuICAgICAgICB0eXBlPVwiZGF0ZXRpbWVcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlNlbGVjdCBkYXRlIGFuZCB0aW1lXCJcbiAgICAgICAgOnNob3J0Y3V0cz1cInNob3J0Y3V0c1wiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+V2l0aCBkZWZhdWx0IHRpbWU8L3NwYW4+XG4gICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgdi1tb2RlbD1cInZhbHVlM1wiXG4gICAgICAgIHR5cGU9XCJkYXRldGltZVwiXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiU2VsZWN0IGRhdGUgYW5kIHRpbWVcIlxuICAgICAgICA6ZGVmYXVsdC10aW1lPVwiZGVmYXVsdFRpbWVcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZTEgPSByZWYoJycpXG5jb25zdCB2YWx1ZTIgPSByZWYoJycpXG5jb25zdCB2YWx1ZTMgPSByZWYoJycpXG5jb25zdCBkZWZhdWx0VGltZSA9IG5ldyBEYXRlKDIwMDAsIDEsIDEsIDEyLCAwLCAwKVxuXG5jb25zdCBzaG9ydGN1dHMgPSBbXG4gIHtcbiAgICB0ZXh0OiAnVG9kYXknLFxuICAgIHZhbHVlOiBuZXcgRGF0ZSgpLFxuICB9LFxuICB7XG4gICAgdGV4dDogJ1llc3RlcmRheScsXG4gICAgdmFsdWU6ICgpID0+IHtcbiAgICAgIGNvbnN0IGRhdGUgPSBuZXcgRGF0ZSgpXG4gICAgICBkYXRlLnNldERhdGUoZGF0ZS5nZXREYXRlKCkgLSAxKVxuICAgICAgcmV0dXJuIGRhdGVcbiAgICB9LFxuICB9LFxuICB7XG4gICAgdGV4dDogJ0Egd2VlayBhZ28nLFxuICAgIHZhbHVlOiAoKSA9PiB7XG4gICAgICBjb25zdCBkYXRlID0gbmV3IERhdGUoKVxuICAgICAgZGF0ZS5zZXREYXRlKGRhdGUuZ2V0RGF0ZSgpIC0gNylcbiAgICAgIHJldHVybiBkYXRlXG4gICAgfSxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tZGF0ZXRpbWUtcGlja2VyIHtcbiAgZGlzcGxheTogZmxleDtcbiAgd2lkdGg6IDEwMCU7XG4gIHBhZGRpbmc6IDA7XG4gIGZsZXgtd3JhcDogd3JhcDtcbn1cbi5kZW1vLWRhdGV0aW1lLXBpY2tlciAuYmxvY2sge1xuICBwYWRkaW5nOiAzMHB4IDA7XG4gIHRleHQtYWxpZ246IGNlbnRlcjtcbiAgYm9yZGVyLXJpZ2h0OiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgZmxleDogMTtcbiAgbWluLXdpZHRoOiAzMDBweDtcbn1cbi5kZW1vLWRhdGV0aW1lLXBpY2tlciAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gIGJvcmRlci1yaWdodDogbm9uZTtcbn1cbi5kZW1vLWRhdGV0aW1lLXBpY2tlciAuZGVtb25zdHJhdGlvbiB7XG4gIGRpc3BsYXk6IGJsb2NrO1xuICBjb2xvcjogdmFyKC0tZWwtdGV4dC1jb2xvci1zZWNvbmRhcnkpO1xuICBmb250LXNpemU6IDE0cHg7XG4gIG1hcmdpbi1ib3R0b206IDIwcHg7XG59XG5cbkBtZWRpYSAobWF4LXdpZHRoOiA3NjhweCkge1xuICAuZGVtby1kYXRldGltZS1waWNrZXIgLmJsb2NrIHtcbiAgICBmbGV4OiAxMDAlO1xuICAgIGJvcmRlci1yaWdodDogbm9uZTtcbiAgICBib3JkZXItYm90dG9tOiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgfVxuXG4gIC5kZW1vLWRhdGV0aW1lLXBpY2tlciAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gICAgYm9yZGVyLWJvdHRvbTogbm9uZTtcbiAgfVxuXG4gIDpkZWVwKC5lbC1kYXRlLWVkaXRvci5lbC1pbnB1dCkge1xuICAgIHdpZHRoOiAxMDAlO1xuICB9XG5cbiAgOmRlZXAoLmVsLWRhdGUtZWRpdG9yLmVsLWlucHV0X193cmFwcGVyKSB7XG4gICAgd2lkdGg6IDEwMCU7XG4gICAgbWF4LXdpZHRoOiAzMDBweDtcbiAgfVxufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/datetime-picker/date-and-time.vue)_

vue

```
<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <span class="demonstration">Default</span>
      <el-date-picker
        v-model="value1"
        type="datetime"
        placeholder="Select date and time"
      />
    </div>
    <div class="block">
      <span class="demonstration">With shortcuts</span>
      <el-date-picker
        v-model="value2"
        type="datetime"
        placeholder="Select date and time"
        :shortcuts="shortcuts"
      />
    </div>
    <div class="block">
      <span class="demonstration">With default time</span>
      <el-date-picker
        v-model="value3"
        type="datetime"
        placeholder="Select date and time"
        :default-time="defaultTime"
      />
    </div>
  </div>
</template>

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

const value1 = ref('')
const value2 = ref('')
const value3 = ref('')
const defaultTime = new Date(2000, 1, 1, 12, 0, 0)

const shortcuts = [
  {
    text: 'Today',
    value: new Date(),
  },
  {
    text: 'Yesterday',
    value: () => {
      const date = new Date()
      date.setDate(date.getDate() - 1)
      return date
    },
  },
  {
    text: 'A week ago',
    value: () => {
      const date = new Date()
      date.setDate(date.getDate() - 7)
      return date
    },
  },
]
</script>

<style scoped>
.demo-datetime-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}
.demo-datetime-picker .block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
  min-width: 300px;
}
.demo-datetime-picker .block:last-child {
  border-right: none;
}
.demo-datetime-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}

@media (max-width: 768px) {
  .demo-datetime-picker .block {
    flex: 100%;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-datetime-picker .block:last-child {
    border-bottom: none;
  }

  :deep(.el-date-editor.el-input) {
    width: 100%;
  }

  :deep(.el-date-editor.el-input__wrapper) {
    width: 100%;
    max-width: 300px;
  }
}
</style>
```

隐藏源代码

## 日期时间格式 [​](#日期时间格式)

使用`format`指定输入框的格式。 使用`value-format`指定绑定值的格式。

默认情况下，组件接受并返回`Date`对象。

在 [这里](https://day.js.org/docs/en/display/format#list-of-all-available-formats) 查看 Day.js 支持的所有格式。

WARNING

请一定要注意传入参数的大小写是否正确

Emits Date object

Value:

Use value-format

Value：

Timestamp

Value：

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRldGltZS1waWNrZXJcIj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPkVtaXRzIERhdGUgb2JqZWN0PC9zcGFuPlxuICAgICAgPGRpdiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5WYWx1ZToge3sgdmFsdWUxIH19PC9kaXY+XG4gICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgdi1tb2RlbD1cInZhbHVlMVwiXG4gICAgICAgIHR5cGU9XCJkYXRldGltZVwiXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiUGljayBhIERhdGVcIlxuICAgICAgICBmb3JtYXQ9XCJZWVlZL01NL0REIEhIOm1tOnNzXCJcbiAgICAgIC8+XG4gICAgPC9kaXY+XG4gICAgPGRpdiBjbGFzcz1cImJsb2NrXCI+XG4gICAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5Vc2UgdmFsdWUtZm9ybWF0PC9zcGFuPlxuICAgICAgPGRpdiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5WYWx1Ze+8mnt7IHZhbHVlMiB9fTwvZGl2PlxuICAgICAgPGVsLWRhdGUtcGlja2VyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTJcIlxuICAgICAgICB0eXBlPVwiZGF0ZXRpbWVcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSBEYXRlXCJcbiAgICAgICAgZm9ybWF0PVwiWVlZWS9NTS9ERCBoaDptbTpzc1wiXG4gICAgICAgIHZhbHVlLWZvcm1hdD1cIllZWVktTU0tREQgaDptOnMgYVwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+VGltZXN0YW1wPC9zcGFuPlxuICAgICAgPGRpdiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5WYWx1Ze+8mnt7IHZhbHVlMyB9fTwvZGl2PlxuICAgICAgPGVsLWRhdGUtcGlja2VyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTNcIlxuICAgICAgICB0eXBlPVwiZGF0ZXRpbWVcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSBEYXRlXCJcbiAgICAgICAgZm9ybWF0PVwiWVlZWS9NTS9ERCBoaDptbTpzc1wiXG4gICAgICAgIHZhbHVlLWZvcm1hdD1cInhcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZTEgPSByZWYoJycpXG5jb25zdCB2YWx1ZTIgPSByZWYoJycpXG5jb25zdCB2YWx1ZTMgPSByZWYoJycpXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWRhdGV0aW1lLXBpY2tlciB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIHdpZHRoOiAxMDAlO1xuICBwYWRkaW5nOiAwO1xuICBmbGV4LXdyYXA6IHdyYXA7XG59XG4uZGVtby1kYXRldGltZS1waWNrZXIgLmJsb2NrIHtcbiAgcGFkZGluZzogMzBweCAwO1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG4gIGJvcmRlci1yaWdodDogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG4gIGZsZXg6IDE7XG4gIG1pbi13aWR0aDogMzAwcHg7XG59XG4uZGVtby1kYXRldGltZS1waWNrZXIgLmJsb2NrOmxhc3QtY2hpbGQge1xuICBib3JkZXItcmlnaHQ6IG5vbmU7XG59XG4uZGVtby1kYXRldGltZS1waWNrZXIgLmRlbW9uc3RyYXRpb24ge1xuICBkaXNwbGF5OiBibG9jaztcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbiAgZm9udC1zaXplOiAxNHB4O1xuICBtYXJnaW4tYm90dG9tOiAyMHB4O1xufVxuXG5AbWVkaWEgKG1heC13aWR0aDogNzY4cHgpIHtcbiAgLmRlbW8tZGF0ZXRpbWUtcGlja2VyIC5ibG9jayB7XG4gICAgZmxleDogMTAwJTtcbiAgICBib3JkZXItcmlnaHQ6IG5vbmU7XG4gICAgYm9yZGVyLWJvdHRvbTogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG4gIH1cblxuICAuZGVtby1kYXRldGltZS1waWNrZXIgLmJsb2NrOmxhc3QtY2hpbGQge1xuICAgIGJvcmRlci1ib3R0b206IG5vbmU7XG4gIH1cblxuICA6ZGVlcCguZWwtZGF0ZS1lZGl0b3IuZWwtaW5wdXQpIHtcbiAgICB3aWR0aDogMTAwJTtcbiAgfVxuXG4gIDpkZWVwKC5lbC1kYXRlLWVkaXRvci5lbC1pbnB1dF9fd3JhcHBlcikge1xuICAgIHdpZHRoOiAxMDAlO1xuICAgIG1heC13aWR0aDogMzAwcHg7XG4gIH1cbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/datetime-picker/date-and-time-formats.vue)_

vue

```
<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <span class="demonstration">Emits Date object</span>
      <div class="demonstration">Value: {{ value1 }}</div>
      <el-date-picker
        v-model="value1"
        type="datetime"
        placeholder="Pick a Date"
        format="YYYY/MM/DD HH:mm:ss"
      />
    </div>
    <div class="block">
      <span class="demonstration">Use value-format</span>
      <div class="demonstration">Value：{{ value2 }}</div>
      <el-date-picker
        v-model="value2"
        type="datetime"
        placeholder="Pick a Date"
        format="YYYY/MM/DD hh:mm:ss"
        value-format="YYYY-MM-DD h:m:s a"
      />
    </div>
    <div class="block">
      <span class="demonstration">Timestamp</span>
      <div class="demonstration">Value：{{ value3 }}</div>
      <el-date-picker
        v-model="value3"
        type="datetime"
        placeholder="Pick a Date"
        format="YYYY/MM/DD hh:mm:ss"
        value-format="x"
      />
    </div>
  </div>
</template>

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

const value1 = ref('')
const value2 = ref('')
const value3 = ref('')
</script>

<style scoped>
.demo-datetime-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}
.demo-datetime-picker .block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
  min-width: 300px;
}
.demo-datetime-picker .block:last-child {
  border-right: none;
}
.demo-datetime-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}

@media (max-width: 768px) {
  .demo-datetime-picker .block {
    flex: 100%;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-datetime-picker .block:last-child {
    border-bottom: none;
  }

  :deep(.el-date-editor.el-input) {
    width: 100%;
  }

  :deep(.el-date-editor.el-input__wrapper) {
    width: 100%;
    max-width: 300px;
  }
}
</style>
```

隐藏源代码

## 下拉列表中的日期和时间格式 [​](#下拉列表中的日期和时间格式)

使用 `date-format` 和 `time-format` 控制下拉列表面板输入框中显示的文本格式

\-

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRldGltZS1waWNrZXJcIj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxlbC1kYXRlLXBpY2tlclxuICAgICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgICAgdHlwZT1cImRhdGV0aW1lXCJcbiAgICAgICAgcGxhY2Vob2xkZXI9XCJQaWNrIGEgRGF0ZVwiXG4gICAgICAgIGZvcm1hdD1cIllZWVktTU0tREQgSEg6bW06c3NcIlxuICAgICAgICBkYXRlLWZvcm1hdD1cIk1NTSBERCwgWVlZWVwiXG4gICAgICAgIHRpbWUtZm9ybWF0PVwiSEg6bW1cIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwibGluZVwiIC8+XG4gICAgPGRpdiBjbGFzcz1cImJsb2NrXCI+XG4gICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgdi1tb2RlbD1cInZhbHVlMlwiXG4gICAgICAgIHR5cGU9XCJkYXRldGltZXJhbmdlXCJcbiAgICAgICAgc3RhcnQtcGxhY2Vob2xkZXI9XCJTdGFydCBkYXRlXCJcbiAgICAgICAgZW5kLXBsYWNlaG9sZGVyPVwiRW5kIGRhdGVcIlxuICAgICAgICBmb3JtYXQ9XCJZWVlZLU1NLUREIEhIOm1tOnNzXCJcbiAgICAgICAgZGF0ZS1mb3JtYXQ9XCJZWVlZL01NL0REIGRkZFwiXG4gICAgICAgIHRpbWUtZm9ybWF0PVwiQSBoaDptbTpzc1wiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZignJylcbmNvbnN0IHZhbHVlMiA9IHJlZignJylcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tZGF0ZXRpbWUtcGlja2VyIHtcbiAgZGlzcGxheTogZmxleDtcbiAgd2lkdGg6IDEwMCU7XG4gIHBhZGRpbmc6IDA7XG4gIGZsZXgtd3JhcDogd3JhcDtcbiAganVzdGlmeS1jb250ZW50OiBzcGFjZS1hcm91bmQ7XG4gIGFsaWduLWl0ZW1zOiBzdHJldGNoO1xufVxuLmRlbW8tZGF0ZXRpbWUtcGlja2VyIC5ibG9jayB7XG4gIHBhZGRpbmc6IDMwcHggMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBtaW4td2lkdGg6IDMwMHB4O1xuICBmbGV4OiAxO1xufVxuLmxpbmUge1xuICB3aWR0aDogMXB4O1xuICBiYWNrZ3JvdW5kLWNvbG9yOiB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xufVxuXG5AbWVkaWEgKG1heC13aWR0aDogNzY4cHgpIHtcbiAgLmRlbW8tZGF0ZXRpbWUtcGlja2VyIC5ibG9jayB7XG4gICAgZmxleDogMTAwJTtcbiAgICBib3JkZXItYm90dG9tOiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgfVxuXG4gIC5kZW1vLWRhdGV0aW1lLXBpY2tlciAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gICAgYm9yZGVyLWJvdHRvbTogbm9uZTtcbiAgfVxuXG4gIC5saW5lIHtcbiAgICBkaXNwbGF5OiBub25lO1xuICB9XG5cbiAgOmRlZXAoLmVsLWRhdGUtZWRpdG9yLmVsLWlucHV0KSB7XG4gICAgd2lkdGg6IDEwMCU7XG4gIH1cblxuICA6ZGVlcCguZWwtZGF0ZS1lZGl0b3IuZWwtaW5wdXRfX3dyYXBwZXIpIHtcbiAgICB3aWR0aDogMTAwJTtcbiAgICBtYXgtd2lkdGg6IDMwMHB4O1xuICB9XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/datetime-picker/date-and-time-formats-panel.vue)_

vue

```
<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <el-date-picker
        v-model="value1"
        type="datetime"
        placeholder="Pick a Date"
        format="YYYY-MM-DD HH:mm:ss"
        date-format="MMM DD, YYYY"
        time-format="HH:mm"
      />
    </div>
    <div class="line" />
    <div class="block">
      <el-date-picker
        v-model="value2"
        type="datetimerange"
        start-placeholder="Start date"
        end-placeholder="End date"
        format="YYYY-MM-DD HH:mm:ss"
        date-format="YYYY/MM/DD ddd"
        time-format="A hh:mm:ss"
      />
    </div>
  </div>
</template>

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

const value1 = ref('')
const value2 = ref('')
</script>

<style scoped>
.demo-datetime-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
  justify-content: space-around;
  align-items: stretch;
}
.demo-datetime-picker .block {
  padding: 30px 0;
  text-align: center;
  min-width: 300px;
  flex: 1;
}
.line {
  width: 1px;
  background-color: var(--el-border-color);
}

@media (max-width: 768px) {
  .demo-datetime-picker .block {
    flex: 100%;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-datetime-picker .block:last-child {
    border-bottom: none;
  }

  .line {
    display: none;
  }

  :deep(.el-date-editor.el-input) {
    width: 100%;
  }

  :deep(.el-date-editor.el-input__wrapper) {
    width: 100%;
    max-width: 300px;
  }
}
</style>
```

隐藏源代码

## 日期和时间范围 [​](#日期和时间范围)

设置`type`为`datetimerange`即可选择日期和时间范围

Default

To

With shortcuts

To

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRldGltZS1waWNrZXJcIj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPkRlZmF1bHQ8L3NwYW4+XG4gICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgdi1tb2RlbD1cInZhbHVlMVwiXG4gICAgICAgIHR5cGU9XCJkYXRldGltZXJhbmdlXCJcbiAgICAgICAgcmFuZ2Utc2VwYXJhdG9yPVwiVG9cIlxuICAgICAgICBzdGFydC1wbGFjZWhvbGRlcj1cIlN0YXJ0IGRhdGVcIlxuICAgICAgICBlbmQtcGxhY2Vob2xkZXI9XCJFbmQgZGF0ZVwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+V2l0aCBzaG9ydGN1dHM8L3NwYW4+XG4gICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgdi1tb2RlbD1cInZhbHVlMlwiXG4gICAgICAgIHR5cGU9XCJkYXRldGltZXJhbmdlXCJcbiAgICAgICAgOnNob3J0Y3V0cz1cInNob3J0Y3V0c1wiXG4gICAgICAgIHJhbmdlLXNlcGFyYXRvcj1cIlRvXCJcbiAgICAgICAgc3RhcnQtcGxhY2Vob2xkZXI9XCJTdGFydCBkYXRlXCJcbiAgICAgICAgZW5kLXBsYWNlaG9sZGVyPVwiRW5kIGRhdGVcIlxuICAgICAgLz5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZTEgPSByZWY8W0RhdGUsIERhdGVdPihbXG4gIG5ldyBEYXRlKDIwMDAsIDEwLCAxMCwgMTAsIDEwKSxcbiAgbmV3IERhdGUoMjAwMCwgMTAsIDExLCAxMCwgMTApLFxuXSlcbmNvbnN0IHZhbHVlMiA9IHJlZignJylcblxuY29uc3Qgc2hvcnRjdXRzID0gW1xuICB7XG4gICAgdGV4dDogJ0xhc3Qgd2VlaycsXG4gICAgdmFsdWU6ICgpID0+IHtcbiAgICAgIGNvbnN0IGVuZCA9IG5ldyBEYXRlKClcbiAgICAgIGNvbnN0IHN0YXJ0ID0gbmV3IERhdGUoKVxuICAgICAgc3RhcnQuc2V0RGF0ZShzdGFydC5nZXREYXRlKCkgLSA3KVxuICAgICAgcmV0dXJuIFtzdGFydCwgZW5kXVxuICAgIH0sXG4gIH0sXG4gIHtcbiAgICB0ZXh0OiAnTGFzdCBtb250aCcsXG4gICAgdmFsdWU6ICgpID0+IHtcbiAgICAgIGNvbnN0IGVuZCA9IG5ldyBEYXRlKClcbiAgICAgIGNvbnN0IHN0YXJ0ID0gbmV3IERhdGUoKVxuICAgICAgc3RhcnQuc2V0TW9udGgoc3RhcnQuZ2V0TW9udGgoKSAtIDEpXG4gICAgICByZXR1cm4gW3N0YXJ0LCBlbmRdXG4gICAgfSxcbiAgfSxcbiAge1xuICAgIHRleHQ6ICdMYXN0IDMgbW9udGhzJyxcbiAgICB2YWx1ZTogKCkgPT4ge1xuICAgICAgY29uc3QgZW5kID0gbmV3IERhdGUoKVxuICAgICAgY29uc3Qgc3RhcnQgPSBuZXcgRGF0ZSgpXG4gICAgICBzdGFydC5zZXRNb250aChzdGFydC5nZXRNb250aCgpIC0gMylcbiAgICAgIHJldHVybiBbc3RhcnQsIGVuZF1cbiAgICB9LFxuICB9LFxuXVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1kYXRldGltZS1waWNrZXIge1xuICBkaXNwbGF5OiBmbGV4O1xuICB3aWR0aDogMTAwJTtcbiAgcGFkZGluZzogMDtcbiAgZmxleC13cmFwOiB3cmFwO1xufVxuXG4uYmxvY2sge1xuICBwYWRkaW5nOiAzMHB4IDA7XG4gIHRleHQtYWxpZ246IGNlbnRlcjtcbiAgYm9yZGVyLXJpZ2h0OiBzb2xpZCAxcHggdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbiAgZmxleDogMTtcbiAgbWluLXdpZHRoOiAzMDBweDtcbn1cblxuLmJsb2NrOmxhc3QtY2hpbGQge1xuICBib3JkZXItcmlnaHQ6IG5vbmU7XG59XG5cbi5ibG9jayAuZGVtb25zdHJhdGlvbiB7XG4gIGRpc3BsYXk6IGJsb2NrO1xuICBjb2xvcjogdmFyKC0tZWwtdGV4dC1jb2xvci1zZWNvbmRhcnkpO1xuICBmb250LXNpemU6IDE0cHg7XG4gIG1hcmdpbi1ib3R0b206IDIwcHg7XG59XG5cbkBtZWRpYSAobWF4LXdpZHRoOiA3NjhweCkge1xuICAuYmxvY2sge1xuICAgIGZsZXg6IDEwMCU7XG4gICAgYm9yZGVyLXJpZ2h0OiBub25lO1xuICAgIGJvcmRlci1ib3R0b206IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICB9XG5cbiAgLmJsb2NrOmxhc3QtY2hpbGQge1xuICAgIGJvcmRlci1ib3R0b206IG5vbmU7XG4gIH1cblxuICA6ZGVlcCguZWwtZGF0ZS1lZGl0b3IuZWwtaW5wdXQpIHtcbiAgICB3aWR0aDogMTAwJTtcbiAgfVxuXG4gIDpkZWVwKC5lbC1kYXRlLWVkaXRvci5lbC1pbnB1dF9fd3JhcHBlcikge1xuICAgIHdpZHRoOiAxMDAlO1xuICAgIG1heC13aWR0aDogMzAwcHg7XG4gIH1cbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/datetime-picker/date-and-time-range.vue)_

vue

```
<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <span class="demonstration">Default</span>
      <el-date-picker
        v-model="value1"
        type="datetimerange"
        range-separator="To"
        start-placeholder="Start date"
        end-placeholder="End date"
      />
    </div>
    <div class="block">
      <span class="demonstration">With shortcuts</span>
      <el-date-picker
        v-model="value2"
        type="datetimerange"
        :shortcuts="shortcuts"
        range-separator="To"
        start-placeholder="Start date"
        end-placeholder="End date"
      />
    </div>
  </div>
</template>

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

const value1 = ref<[Date, Date]>([
  new Date(2000, 10, 10, 10, 10),
  new Date(2000, 10, 11, 10, 10),
])
const value2 = ref('')

const shortcuts = [
  {
    text: 'Last week',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setDate(start.getDate() - 7)
      return [start, end]
    },
  },
  {
    text: 'Last month',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setMonth(start.getMonth() - 1)
      return [start, end]
    },
  },
  {
    text: 'Last 3 months',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setMonth(start.getMonth() - 3)
      return [start, end]
    },
  },
]
</script>

<style scoped>
.demo-datetime-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}

.block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
  min-width: 300px;
}

.block:last-child {
  border-right: none;
}

.block .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}

@media (max-width: 768px) {
  .block {
    flex: 100%;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .block:last-child {
    border-bottom: none;
  }

  :deep(.el-date-editor.el-input) {
    width: 100%;
  }

  :deep(.el-date-editor.el-input__wrapper) {
    width: 100%;
    max-width: 300px;
  }
}
</style>
```

隐藏源代码

## 单个面板 2.14.0 [​](#单个面板)

默认日期选择器范围有两个面板。 如果你想要一个面板设置 `single-panel` 属性。

single-panel

\-

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRlLXBpY2tlclwiPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+c2luZ2xlLXBhbmVsPC9zcGFuPlxuICAgICAgPGVsLWRhdGUtcGlja2VyIHYtbW9kZWw9XCJ2YWx1ZTFcIiB0eXBlPVwiZGF0ZXRpbWVyYW5nZVwiIHNpbmdsZS1wYW5lbCAvPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZigpXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWRhdGUtcGlja2VyIHtcbiAgZGlzcGxheTogZmxleDtcbiAgd2lkdGg6IDEwMCU7XG4gIHBhZGRpbmc6IDA7XG4gIGZsZXgtd3JhcDogd3JhcDtcbn1cbi5kZW1vLWRhdGUtcGlja2VyIC5ibG9jayB7XG4gIHBhZGRpbmc6IDMwcHggMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBib3JkZXItcmlnaHQ6IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICBmbGV4OiAxO1xufVxuLmRlbW8tZGF0ZS1waWNrZXIgLmJsb2NrOmxhc3QtY2hpbGQge1xuICBib3JkZXItcmlnaHQ6IG5vbmU7XG59XG4uZGVtby1kYXRlLXBpY2tlciAuZGVtb25zdHJhdGlvbiB7XG4gIGRpc3BsYXk6IGJsb2NrO1xuICBjb2xvcjogdmFyKC0tZWwtdGV4dC1jb2xvci1zZWNvbmRhcnkpO1xuICBmb250LXNpemU6IDE0cHg7XG4gIG1hcmdpbi1ib3R0b206IDIwcHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/datetime-picker/single-panel.vue)_

vue

```
<template>
  <div class="demo-date-picker">
    <div class="block">
      <span class="demonstration">single-panel</span>
      <el-date-picker v-model="value1" type="datetimerange" single-panel />
    </div>
  </div>
</template>

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

const value1 = ref()
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}
.demo-date-picker .block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
}
.demo-date-picker .block:last-child {
  border-right: none;
}
.demo-date-picker .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}
</style>
```

隐藏源代码

## 默认的起始与结束时刻 [​](#默认的起始与结束时刻)

使用`datetimerange`进行范围选择时，在日期选择面板中选定起始与结束的日期，默认会使用该日期的`00:00:00`作为起始与结束的时刻；通过选项`default-time`可以控制选中起始与结束日期时所使用的具体时刻。 我们可以使用 `default-time` 属性来控制它。 `default-time`接受一个数组，其中第一项控制起始日期的具体时刻，第二项控制结束日期的具体时刻。 第一项控制开始日期的时间值，第二项控制结束日期的时间值。

Start and end date time 12:00:00

\-

Start date time 12:00:00, end date time 08:00:00

\-

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRldGltZS1waWNrZXJcIj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPlN0YXJ0IGFuZCBlbmQgZGF0ZSB0aW1lIDEyOjAwOjAwPC9zcGFuPlxuICAgICAgPGVsLWRhdGUtcGlja2VyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTFcIlxuICAgICAgICB0eXBlPVwiZGF0ZXRpbWVyYW5nZVwiXG4gICAgICAgIHN0YXJ0LXBsYWNlaG9sZGVyPVwiU3RhcnQgRGF0ZVwiXG4gICAgICAgIGVuZC1wbGFjZWhvbGRlcj1cIkVuZCBEYXRlXCJcbiAgICAgICAgOmRlZmF1bHQtdGltZT1cImRlZmF1bHRUaW1lMVwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+XG4gICAgICAgIFN0YXJ0IGRhdGUgdGltZSAxMjowMDowMCwgZW5kIGRhdGUgdGltZSAwODowMDowMFxuICAgICAgPC9zcGFuPlxuICAgICAgPGVsLWRhdGUtcGlja2VyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTJcIlxuICAgICAgICB0eXBlPVwiZGF0ZXRpbWVyYW5nZVwiXG4gICAgICAgIHN0YXJ0LXBsYWNlaG9sZGVyPVwiU3RhcnQgRGF0ZVwiXG4gICAgICAgIGVuZC1wbGFjZWhvbGRlcj1cIkVuZCBEYXRlXCJcbiAgICAgICAgOmRlZmF1bHQtdGltZT1cImRlZmF1bHRUaW1lMlwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZignJylcbmNvbnN0IHZhbHVlMiA9IHJlZignJylcblxuY29uc3QgZGVmYXVsdFRpbWUxID0gbmV3IERhdGUoMjAwMCwgMSwgMSwgMTIsIDAsIDApIC8vICcxMjowMDowMCdcbmNvbnN0IGRlZmF1bHRUaW1lMjogW0RhdGUsIERhdGVdID0gW1xuICBuZXcgRGF0ZSgyMDAwLCAxLCAxLCAxMiwgMCwgMCksXG4gIG5ldyBEYXRlKDIwMDAsIDIsIDEsIDgsIDAsIDApLFxuXSAvLyAnMTI6MDA6MDAnLCAnMDg6MDA6MDAnXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWRhdGV0aW1lLXBpY2tlciB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIHdpZHRoOiAxMDAlO1xuICBwYWRkaW5nOiAwO1xuICBmbGV4LXdyYXA6IHdyYXA7XG59XG5cbi5ibG9jayB7XG4gIHBhZGRpbmc6IDMwcHggMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBib3JkZXItcmlnaHQ6IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICBmbGV4OiAxO1xuICBtaW4td2lkdGg6IDMwMHB4O1xufVxuXG4uYmxvY2s6bGFzdC1jaGlsZCB7XG4gIGJvcmRlci1yaWdodDogbm9uZTtcbn1cblxuLmJsb2NrIC5kZW1vbnN0cmF0aW9uIHtcbiAgZGlzcGxheTogYmxvY2s7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG4gIGZvbnQtc2l6ZTogMTRweDtcbiAgbWFyZ2luLWJvdHRvbTogMjBweDtcbn1cblxuQG1lZGlhIChtYXgtd2lkdGg6IDc2OHB4KSB7XG4gIC5ibG9jayB7XG4gICAgZmxleDogMTAwJTtcbiAgICBib3JkZXItcmlnaHQ6IG5vbmU7XG4gICAgYm9yZGVyLWJvdHRvbTogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG4gIH1cblxuICAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gICAgYm9yZGVyLWJvdHRvbTogbm9uZTtcbiAgfVxuXG4gIDpkZWVwKC5lbC1kYXRlLWVkaXRvci5lbC1pbnB1dCkge1xuICAgIHdpZHRoOiAxMDAlO1xuICB9XG5cbiAgOmRlZXAoLmVsLWRhdGUtZWRpdG9yLmVsLWlucHV0X193cmFwcGVyKSB7XG4gICAgd2lkdGg6IDEwMCU7XG4gICAgbWF4LXdpZHRoOiAzMDBweDtcbiAgfVxufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/datetime-picker/default-time.vue)_

vue

```
<template>
  <div class="demo-datetime-picker">
    <div class="block">
      <span class="demonstration">Start and end date time 12:00:00</span>
      <el-date-picker
        v-model="value1"
        type="datetimerange"
        start-placeholder="Start Date"
        end-placeholder="End Date"
        :default-time="defaultTime1"
      />
    </div>
    <div class="block">
      <span class="demonstration">
        Start date time 12:00:00, end date time 08:00:00
      </span>
      <el-date-picker
        v-model="value2"
        type="datetimerange"
        start-placeholder="Start Date"
        end-placeholder="End Date"
        :default-time="defaultTime2"
      />
    </div>
  </div>
</template>

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

const value1 = ref('')
const value2 = ref('')

const defaultTime1 = new Date(2000, 1, 1, 12, 0, 0) // '12:00:00'
const defaultTime2: [Date, Date] = [
  new Date(2000, 1, 1, 12, 0, 0),
  new Date(2000, 2, 1, 8, 0, 0),
] // '12:00:00', '08:00:00'
</script>

<style scoped>
.demo-datetime-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}

.block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  flex: 1;
  min-width: 300px;
}

.block:last-child {
  border-right: none;
}

.block .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}

@media (max-width: 768px) {
  .block {
    flex: 100%;
    border-right: none;
    border-bottom: solid 1px var(--el-border-color);
  }

  .block:last-child {
    border-bottom: none;
  }

  :deep(.el-date-editor.el-input) {
    width: 100%;
  }

  :deep(.el-date-editor.el-input__wrapper) {
    width: 100%;
    max-width: 300px;
  }
}
</style>
```

隐藏源代码

## 自定义图标 2.8.0 [​](#自定义图标)

使用插槽自定义图标。

\-

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1kYXRldGltZS1waWNrZXItaWNvblwiPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPGVsLWRhdGUtcGlja2VyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTFcIlxuICAgICAgICB0eXBlPVwiZGF0ZXRpbWVcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSBEYXRlXCJcbiAgICAgICAgZm9ybWF0PVwiWVlZWS1NTS1ERCBISDptbTpzc1wiXG4gICAgICAgIGRhdGUtZm9ybWF0PVwiTU1NIERELCBZWVlZXCJcbiAgICAgICAgdGltZS1mb3JtYXQ9XCJISDptbVwiXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjcHJldi1tb250aD5cbiAgICAgICAgICA8ZWwtaWNvbj48Q2FyZXRMZWZ0IC8+PC9lbC1pY29uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICA8dGVtcGxhdGUgI25leHQtbW9udGg+XG4gICAgICAgICAgPGVsLWljb24+PENhcmV0UmlnaHQgLz48L2VsLWljb24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDx0ZW1wbGF0ZSAjcHJldi15ZWFyPlxuICAgICAgICAgIDxlbC1pY29uPlxuICAgICAgICAgICAgPHN2Z1xuICAgICAgICAgICAgICB2aWV3Qm94PVwiMCAwIDIwIDIwXCJcbiAgICAgICAgICAgICAgdmVyc2lvbj1cIjEuMVwiXG4gICAgICAgICAgICAgIHhtbG5zPVwiaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmdcIlxuICAgICAgICAgICAgPlxuICAgICAgICAgICAgICA8ZyBzdHJva2Utd2lkdGg9XCIxXCIgZmlsbC1ydWxlPVwiZXZlbm9kZFwiPlxuICAgICAgICAgICAgICAgIDxnIGZpbGw9XCJjdXJyZW50Q29sb3JcIj5cbiAgICAgICAgICAgICAgICAgIDxwYXRoXG4gICAgICAgICAgICAgICAgICAgIGQ9XCJNOC43MzE3MSwxNi43OTQ5IEM5LjAzMjY0LDE3LjA3OTUgOS41MDczMywxNy4wNjYzIDkuNzkxOTYsMTYuNzY1NCBDMTAuMDc2NiwxNi40NjQ0IDEwLjA2MzQsMTUuOTg5NyA5Ljc2MjQzLDE1LjcwNTEgTDQuNTIzMzksMTAuNzUgTDE3LjI0NzEsMTAuNzUgQzE3LjY2MTMsMTAuNzUgMTcuOTk3MSwxMC40MTQyIDE3Ljk5NzEsMTAgQzE3Ljk5NzEsOS41ODU3OSAxNy42NjEzLDkuMjUgMTcuMjQ3MSw5LjI1IEw0LjUyMTEyLDkuMjUgTDkuNzYyNDMsNC4yOTI3NSBDMTAuMDYzNCw0LjAwODEyIDEwLjA3NjYsMy41MzM0MyA5Ljc5MTk2LDMuMjMyNSBDOS41MDczMywyLjkzMTU2IDkuMDMyNjQsMi45MTgzNCA4LjczMTcxLDMuMjAyOTcgTDIuMzE0NDksOS4yNzI0MSBDMi4xNDgxOSw5LjQyOTcgMi4wNDgxOSw5LjYyOTgxIDIuMDE0NDgsOS44Mzg2IEMyLjAwMzA4LDkuODkwNTggMS45OTcwNyw5Ljk0NDU5IDEuOTk3MDcsMTAgQzEuOTk3MDcsMTAuMDU3NiAyLjAwMzU2LDEwLjExMzcgMi4wMTU4NSwxMC4xNjc1IEMyLjA1MDg0LDEwLjM3MzMgMi4xNTAzOSwxMC41NzAyIDIuMzE0NDksMTAuNzI1NCBMOC43MzE3MSwxNi43OTQ5IFpcIlxuICAgICAgICAgICAgICAgICAgLz5cbiAgICAgICAgICAgICAgICA8L2c+XG4gICAgICAgICAgICAgIDwvZz5cbiAgICAgICAgICAgIDwvc3ZnPlxuICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPHRlbXBsYXRlICNuZXh0LXllYXI+XG4gICAgICAgICAgPGVsLWljb24+XG4gICAgICAgICAgICA8c3ZnXG4gICAgICAgICAgICAgIHZpZXdCb3g9XCIwIDAgMjAgMjBcIlxuICAgICAgICAgICAgICB2ZXJzaW9uPVwiMS4xXCJcbiAgICAgICAgICAgICAgeG1sbnM9XCJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2Z1wiXG4gICAgICAgICAgICA+XG4gICAgICAgICAgICAgIDxnIHN0cm9rZS13aWR0aD1cIjFcIiBmaWxsLXJ1bGU9XCJldmVub2RkXCI+XG4gICAgICAgICAgICAgICAgPGcgZmlsbD1cImN1cnJlbnRDb2xvclwiPlxuICAgICAgICAgICAgICAgICAgPHBhdGhcbiAgICAgICAgICAgICAgICAgICAgZD1cIk0xMS4yNjU0LDMuMjA1MTEgQzEwLjk2NDQsMi45MjA0OSAxMC40ODk3LDIuOTMzNzEgMTAuMjA1MSwzLjIzNDY0IEM5LjkyMDQ5LDMuNTM1NTggOS45MzM3MSw0LjAxMDI3IDEwLjIzNDYsNC4yOTQ4OSBMMTUuNDczNyw5LjI1IEwyLjc1LDkuMjUgQzIuMzM1NzksOS4yNSAyLDkuNTg1NzkgMiwxMC4wMDAwMDEyIEMyLDEwLjQxNDIgMi4zMzU3OSwxMC43NSAyLjc1LDEwLjc1IEwxNS40NzYsMTAuNzUgTDEwLjIzNDYsMTUuNzA3MyBDOS45MzM3MSwxNS45OTE5IDkuOTIwNDksMTYuNDY2NiAxMC4yMDUxLDE2Ljc2NzUgQzEwLjQ4OTcsMTcuMDY4NCAxMC45NjQ0LDE3LjA4MTcgMTEuMjY1NCwxNi43OTcgTDE3LjY4MjYsMTAuNzI3NiBDMTcuODQ4OSwxMC41NzAzIDE3Ljk0ODksMTAuMzcwMiAxNy45ODI2LDEwLjE2MTQgQzE3Ljk5NCwxMC4xMDk0IDE4LDEwLjA1NTQgMTgsMTAuMDAwMDAxMiBDMTgsOS45NDI0MSAxNy45OTM1LDkuODg2MzMgMTcuOTgxMiw5LjgzMjQ2IEMxNy45NDYyLDkuNjI2NjcgMTcuODQ2Nyw5LjQyOTc2IDE3LjY4MjYsOS4yNzQ1NSBMMTEuMjY1NCwzLjIwNTExIFpcIlxuICAgICAgICAgICAgICAgICAgLz5cbiAgICAgICAgICAgICAgICA8L2c+XG4gICAgICAgICAgICAgIDwvZz5cbiAgICAgICAgICAgIDwvc3ZnPlxuICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtZGF0ZS1waWNrZXI+XG4gICAgPC9kaXY+XG4gICAgPGRpdiBjbGFzcz1cImxpbmVcIiAvPlxuICAgIDxkaXYgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPGVsLWRhdGUtcGlja2VyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTJcIlxuICAgICAgICB0eXBlPVwiZGF0ZXRpbWVyYW5nZVwiXG4gICAgICAgIHN0YXJ0LXBsYWNlaG9sZGVyPVwiU3RhcnQgZGF0ZVwiXG4gICAgICAgIGVuZC1wbGFjZWhvbGRlcj1cIkVuZCBkYXRlXCJcbiAgICAgICAgZm9ybWF0PVwiWVlZWS1NTS1ERCBISDptbTpzc1wiXG4gICAgICAgIGRhdGUtZm9ybWF0PVwiWVlZWS9NTS9ERCBkZGRcIlxuICAgICAgICB0aW1lLWZvcm1hdD1cIkEgaGg6bW06c3NcIlxuICAgICAgICB1bmxpbmstcGFuZWxzXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjcHJldi1tb250aD5cbiAgICAgICAgICA8ZWwtaWNvbj48Q2FyZXRMZWZ0IC8+PC9lbC1pY29uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICA8dGVtcGxhdGUgI25leHQtbW9udGg+XG4gICAgICAgICAgPGVsLWljb24+PENhcmV0UmlnaHQgLz48L2VsLWljb24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDx0ZW1wbGF0ZSAjcHJldi15ZWFyPlxuICAgICAgICAgIDxlbC1pY29uPlxuICAgICAgICAgICAgPHN2Z1xuICAgICAgICAgICAgICB2aWV3Qm94PVwiMCAwIDIwIDIwXCJcbiAgICAgICAgICAgICAgdmVyc2lvbj1cIjEuMVwiXG4gICAgICAgICAgICAgIHhtbG5zPVwiaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmdcIlxuICAgICAgICAgICAgPlxuICAgICAgICAgICAgICA8ZyBzdHJva2Utd2lkdGg9XCIxXCIgZmlsbC1ydWxlPVwiZXZlbm9kZFwiPlxuICAgICAgICAgICAgICAgIDxnIGZpbGw9XCJjdXJyZW50Q29sb3JcIj5cbiAgICAgICAgICAgICAgICAgIDxwYXRoXG4gICAgICAgICAgICAgICAgICAgIGQ9XCJNOC43MzE3MSwxNi43OTQ5IEM5LjAzMjY0LDE3LjA3OTUgOS41MDczMywxNy4wNjYzIDkuNzkxOTYsMTYuNzY1NCBDMTAuMDc2NiwxNi40NjQ0IDEwLjA2MzQsMTUuOTg5NyA5Ljc2MjQzLDE1LjcwNTEgTDQuNTIzMzksMTAuNzUgTDE3LjI0NzEsMTAuNzUgQzE3LjY2MTMsMTAuNzUgMTcuOTk3MSwxMC40MTQyIDE3Ljk5NzEsMTAgQzE3Ljk5NzEsOS41ODU3OSAxNy42NjEzLDkuMjUgMTcuMjQ3MSw5LjI1IEw0LjUyMTEyLDkuMjUgTDkuNzYyNDMsNC4yOTI3NSBDMTAuMDYzNCw0LjAwODEyIDEwLjA3NjYsMy41MzM0MyA5Ljc5MTk2LDMuMjMyNSBDOS41MDczMywyLjkzMTU2IDkuMDMyNjQsMi45MTgzNCA4LjczMTcxLDMuMjAyOTcgTDIuMzE0NDksOS4yNzI0MSBDMi4xNDgxOSw5LjQyOTcgMi4wNDgxOSw5LjYyOTgxIDIuMDE0NDgsOS44Mzg2IEMyLjAwMzA4LDkuODkwNTggMS45OTcwNyw5Ljk0NDU5IDEuOTk3MDcsMTAgQzEuOTk3MDcsMTAuMDU3NiAyLjAwMzU2LDEwLjExMzcgMi4wMTU4NSwxMC4xNjc1IEMyLjA1MDg0LDEwLjM3MzMgMi4xNTAzOSwxMC41NzAyIDIuMzE0NDksMTAuNzI1NCBMOC43MzE3MSwxNi43OTQ5IFpcIlxuICAgICAgICAgICAgICAgICAgLz5cbiAgICAgICAgICAgICAgICA8L2c+XG4gICAgICAgICAgICAgIDwvZz5cbiAgICAgICAgICAgIDwvc3ZnPlxuICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPHRlbXBsYXRlICNuZXh0LXllYXI+XG4gICAgICAgICAgPGVsLWljb24+XG4gICAgICAgICAgICA8c3ZnXG4gICAgICAgICAgICAgIHZpZXdCb3g9XCIwIDAgMjAgMjBcIlxuICAgICAgICAgICAgICB2ZXJzaW9uPVwiMS4xXCJcbiAgICAgICAgICAgICAgeG1sbnM9XCJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2Z1wiXG4gICAgICAgICAgICA+XG4gICAgICAgICAgICAgIDxnIHN0cm9rZS13aWR0aD1cIjFcIiBmaWxsLXJ1bGU9XCJldmVub2RkXCI+XG4gICAgICAgICAgICAgICAgPGcgZmlsbD1cImN1cnJlbnRDb2xvclwiPlxuICAgICAgICAgICAgICAgICAgPHBhdGhcbiAgICAgICAgICAgICAgICAgICAgZD1cIk0xMS4yNjU0LDMuMjA1MTEgQzEwLjk2NDQsMi45MjA0OSAxMC40ODk3LDIuOTMzNzEgMTAuMjA1MSwzLjIzNDY0IEM5LjkyMDQ5LDMuNTM1NTggOS45MzM3MSw0LjAxMDI3IDEwLjIzNDYsNC4yOTQ4OSBMMTUuNDczNyw5LjI1IEwyLjc1LDkuMjUgQzIuMzM1NzksOS4yNSAyLDkuNTg1NzkgMiwxMC4wMDAwMDEyIEMyLDEwLjQxNDIgMi4zMzU3OSwxMC43NSAyLjc1LDEwLjc1IEwxNS40NzYsMTAuNzUgTDEwLjIzNDYsMTUuNzA3MyBDOS45MzM3MSwxNS45OTE5IDkuOTIwNDksMTYuNDY2NiAxMC4yMDUxLDE2Ljc2NzUgQzEwLjQ4OTcsMTcuMDY4NCAxMC45NjQ0LDE3LjA4MTcgMTEuMjY1NCwxNi43OTcgTDE3LjY4MjYsMTAuNzI3NiBDMTcuODQ4OSwxMC41NzAzIDE3Ljk0ODksMTAuMzcwMiAxNy45ODI2LDEwLjE2MTQgQzE3Ljk5NCwxMC4xMDk0IDE4LDEwLjA1NTQgMTgsMTAuMDAwMDAxMiBDMTgsOS45NDI0MSAxNy45OTM1LDkuODg2MzMgMTcuOTgxMiw5LjgzMjQ2IEMxNy45NDYyLDkuNjI2NjcgMTcuODQ2Nyw5LjQyOTc2IDE3LjY4MjYsOS4yNzQ1NSBMMTEuMjY1NCwzLjIwNTExIFpcIlxuICAgICAgICAgICAgICAgICAgLz5cbiAgICAgICAgICAgICAgICA8L2c+XG4gICAgICAgICAgICAgIDwvZz5cbiAgICAgICAgICAgIDwvc3ZnPlxuICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtZGF0ZS1waWNrZXI+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IENhcmV0TGVmdCwgQ2FyZXRSaWdodCB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5jb25zdCB2YWx1ZTEgPSByZWYoJycpXG5jb25zdCB2YWx1ZTIgPSByZWYoJycpXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWRhdGV0aW1lLXBpY2tlci1pY29uIHtcbiAgZGlzcGxheTogZmxleDtcbiAgd2lkdGg6IDEwMCU7XG4gIHBhZGRpbmc6IDA7XG4gIGZsZXgtd3JhcDogd3JhcDtcbiAganVzdGlmeS1jb250ZW50OiBzcGFjZS1hcm91bmQ7XG4gIGFsaWduLWl0ZW1zOiBzdHJldGNoO1xufVxuLmRlbW8tZGF0ZXRpbWUtcGlja2VyLWljb24gLmJsb2NrIHtcbiAgcGFkZGluZzogMzBweCAwO1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG4gIG1pbi13aWR0aDogMzAwcHg7XG4gIGZsZXg6IDE7XG59XG4ubGluZSB7XG4gIHdpZHRoOiAxcHg7XG4gIGJhY2tncm91bmQtY29sb3I6IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG59XG5cbkBtZWRpYSAobWF4LXdpZHRoOiA3NjhweCkge1xuICAuZGVtby1kYXRldGltZS1waWNrZXItaWNvbiAuYmxvY2sge1xuICAgIGZsZXg6IDEwMCU7XG4gICAgYm9yZGVyLWJvdHRvbTogc29saWQgMXB4IHZhcigtLWVsLWJvcmRlci1jb2xvcik7XG4gIH1cblxuICAuZGVtby1kYXRldGltZS1waWNrZXItaWNvbiAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gICAgYm9yZGVyLWJvdHRvbTogbm9uZTtcbiAgfVxuXG4gIC5saW5lIHtcbiAgICBkaXNwbGF5OiBub25lO1xuICB9XG5cbiAgOmRlZXAoLmVsLWRhdGUtZWRpdG9yLmVsLWlucHV0KSB7XG4gICAgd2lkdGg6IDEwMCU7XG4gIH1cblxuICA6ZGVlcCguZWwtZGF0ZS1lZGl0b3IuZWwtaW5wdXRfX3dyYXBwZXIpIHtcbiAgICB3aWR0aDogMTAwJTtcbiAgICBtYXgtd2lkdGg6IDMwMHB4O1xuICB9XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/datetime-picker/custom-icon.vue)_

vue

```
<template>
  <div class="demo-datetime-picker-icon">
    <div class="block">
      <el-date-picker
        v-model="value1"
        type="datetime"
        placeholder="Pick a Date"
        format="YYYY-MM-DD HH:mm:ss"
        date-format="MMM DD, YYYY"
        time-format="HH:mm"
      >
        <template #prev-month>
          <el-icon><CaretLeft /></el-icon>
        </template>
        <template #next-month>
          <el-icon><CaretRight /></el-icon>
        </template>
        <template #prev-year>
          <el-icon>
            <svg
              viewBox="0 0 20 20"
              version="1.1"
              xmlns="http://www.w3.org/2000/svg"
            >
              <g stroke-width="1" fill-rule="evenodd">
                <g fill="currentColor">
                  <path
                    d="M8.73171,16.7949 C9.03264,17.0795 9.50733,17.0663 9.79196,16.7654 C10.0766,16.4644 10.0634,15.9897 9.76243,15.7051 L4.52339,10.75 L17.2471,10.75 C17.6613,10.75 17.9971,10.4142 17.9971,10 C17.9971,9.58579 17.6613,9.25 17.2471,9.25 L4.52112,9.25 L9.76243,4.29275 C10.0634,4.00812 10.0766,3.53343 9.79196,3.2325 C9.50733,2.93156 9.03264,2.91834 8.73171,3.20297 L2.31449,9.27241 C2.14819,9.4297 2.04819,9.62981 2.01448,9.8386 C2.00308,9.89058 1.99707,9.94459 1.99707,10 C1.99707,10.0576 2.00356,10.1137 2.01585,10.1675 C2.05084,10.3733 2.15039,10.5702 2.31449,10.7254 L8.73171,16.7949 Z"
                  />
                </g>
              </g>
            </svg>
          </el-icon>
        </template>
        <template #next-year>
          <el-icon>
            <svg
              viewBox="0 0 20 20"
              version="1.1"
              xmlns="http://www.w3.org/2000/svg"
            >
              <g stroke-width="1" fill-rule="evenodd">
                <g fill="currentColor">
                  <path
                    d="M11.2654,3.20511 C10.9644,2.92049 10.4897,2.93371 10.2051,3.23464 C9.92049,3.53558 9.93371,4.01027 10.2346,4.29489 L15.4737,9.25 L2.75,9.25 C2.33579,9.25 2,9.58579 2,10.0000012 C2,10.4142 2.33579,10.75 2.75,10.75 L15.476,10.75 L10.2346,15.7073 C9.93371,15.9919 9.92049,16.4666 10.2051,16.7675 C10.4897,17.0684 10.9644,17.0817 11.2654,16.797 L17.6826,10.7276 C17.8489,10.5703 17.9489,10.3702 17.9826,10.1614 C17.994,10.1094 18,10.0554 18,10.0000012 C18,9.94241 17.9935,9.88633 17.9812,9.83246 C17.9462,9.62667 17.8467,9.42976 17.6826,9.27455 L11.2654,3.20511 Z"
                  />
                </g>
              </g>
            </svg>
          </el-icon>
        </template>
      </el-date-picker>
    </div>
    <div class="line" />
    <div class="block">
      <el-date-picker
        v-model="value2"
        type="datetimerange"
        start-placeholder="Start date"
        end-placeholder="End date"
        format="YYYY-MM-DD HH:mm:ss"
        date-format="YYYY/MM/DD ddd"
        time-format="A hh:mm:ss"
        unlink-panels
      >
        <template #prev-month>
          <el-icon><CaretLeft /></el-icon>
        </template>
        <template #next-month>
          <el-icon><CaretRight /></el-icon>
        </template>
        <template #prev-year>
          <el-icon>
            <svg
              viewBox="0 0 20 20"
              version="1.1"
              xmlns="http://www.w3.org/2000/svg"
            >
              <g stroke-width="1" fill-rule="evenodd">
                <g fill="currentColor">
                  <path
                    d="M8.73171,16.7949 C9.03264,17.0795 9.50733,17.0663 9.79196,16.7654 C10.0766,16.4644 10.0634,15.9897 9.76243,15.7051 L4.52339,10.75 L17.2471,10.75 C17.6613,10.75 17.9971,10.4142 17.9971,10 C17.9971,9.58579 17.6613,9.25 17.2471,9.25 L4.52112,9.25 L9.76243,4.29275 C10.0634,4.00812 10.0766,3.53343 9.79196,3.2325 C9.50733,2.93156 9.03264,2.91834 8.73171,3.20297 L2.31449,9.27241 C2.14819,9.4297 2.04819,9.62981 2.01448,9.8386 C2.00308,9.89058 1.99707,9.94459 1.99707,10 C1.99707,10.0576 2.00356,10.1137 2.01585,10.1675 C2.05084,10.3733 2.15039,10.5702 2.31449,10.7254 L8.73171,16.7949 Z"
                  />
                </g>
              </g>
            </svg>
          </el-icon>
        </template>
        <template #next-year>
          <el-icon>
            <svg
              viewBox="0 0 20 20"
              version="1.1"
              xmlns="http://www.w3.org/2000/svg"
            >
              <g stroke-width="1" fill-rule="evenodd">
                <g fill="currentColor">
                  <path
                    d="M11.2654,3.20511 C10.9644,2.92049 10.4897,2.93371 10.2051,3.23464 C9.92049,3.53558 9.93371,4.01027 10.2346,4.29489 L15.4737,9.25 L2.75,9.25 C2.33579,9.25 2,9.58579 2,10.0000012 C2,10.4142 2.33579,10.75 2.75,10.75 L15.476,10.75 L10.2346,15.7073 C9.93371,15.9919 9.92049,16.4666 10.2051,16.7675 C10.4897,17.0684 10.9644,17.0817 11.2654,16.797 L17.6826,10.7276 C17.8489,10.5703 17.9489,10.3702 17.9826,10.1614 C17.994,10.1094 18,10.0554 18,10.0000012 C18,9.94241 17.9935,9.88633 17.9812,9.83246 C17.9462,9.62667 17.8467,9.42976 17.6826,9.27455 L11.2654,3.20511 Z"
                  />
                </g>
              </g>
            </svg>
          </el-icon>
        </template>
      </el-date-picker>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { CaretLeft, CaretRight } from '@element-plus/icons-vue'

const value1 = ref('')
const value2 = ref('')
</script>

<style scoped>
.demo-datetime-picker-icon {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
  justify-content: space-around;
  align-items: stretch;
}
.demo-datetime-picker-icon .block {
  padding: 30px 0;
  text-align: center;
  min-width: 300px;
  flex: 1;
}
.line {
  width: 1px;
  background-color: var(--el-border-color);
}

@media (max-width: 768px) {
  .demo-datetime-picker-icon .block {
    flex: 100%;
    border-bottom: solid 1px var(--el-border-color);
  }

  .demo-datetime-picker-icon .block:last-child {
    border-bottom: none;
  }

  .line {
    display: none;
  }

  :deep(.el-date-editor.el-input) {
    width: 100%;
  }

  :deep(.el-date-editor.el-input__wrapper) {
    width: 100%;
    max-width: 300px;
  }
}
</style>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 绑定值，如果是 `range` 选择器，数组长度应为 2 | `number` / `string` / `Date` / `array` | '' |
| readonly | 只读 | `boolean` | false |
| disabled | 禁用 | `boolean` | false |
| editable | 文本框可输入 | `boolean` | true |
| clearable | 是否显示清除按钮 | `boolean` | true |
| size | 输入框尺寸 | `enum` | default |
| placeholder | 非范围选择时的占位内容 | `string` | — |
| start-placeholder | 范围选择时开始日期的占位内容 | `string` | — |
| end-placeholder | 范围选择时结束日期的占位内容 | `string` | — |
| arrow-control | 是否使用箭头进行时间选择 | `boolean` | false |
| type | 显示类型 | `enum` | date |
| format | 显示在输入框中的格式 | `string` 参考 [日期格式](https://element-plus.org/zh-CN/component/date-picker#date-formats) | YYYY-MM-DD HH:mm:ss |
| popper-class | DateTimePicker 下拉框的类名 | `string` | — |
| popper-style | 弹出内容的自定义样式 | `string` / `object` | — |
| popper-options | 自定义 popper 选项，更多请参考 [popper.js](https://popper.js.org/docs/v2/) | `object` | {} |
| fallback-placements 2.8.4 | Tooltip 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | `array` | \['bottom', 'top', 'right', 'left'\] |
| placement 2.8.4 | 下拉框出现的位置 | `展示位置` | bottom |
| range-separator | 选择范围时的分隔符 | `string` | '-' |
| default-value | 可选，选择器打开时默认显示的时间 | `object` | — |
| default-time | 选择日期后的默认时间值。 如未指定则默认时间值为 `00:00:00` | `object` | — |
| value-format | 可选，绑定值的格式。 不指定则绑定值为 Date 对象 | `string` see [date formats](https://day.js.org/docs/en/display/format) | — |
| date-format 2.4.0 | 可选，输入框内部面板中显示的日期格式 | `string` see [date formats](https://day.js.org/docs/en/display/format) | YYYY-MM-DD |
| time-format 2.4.0 | 可选，输入框内部面板中显示的时间格式 | `string` see [date formats](https://day.js.org/docs/en/display/format) | HH:mm:ss |
| id | 等价于原生 input `id` 属性 | `string` / `array` | — |
| name | 等价于原生 input `name` 属性 | `string` | — |
| unlink-panels | 在范围选择器里取消两个日期面板之间的联动 | `boolean` | false |
| single-panel 2.14.0 | 在范围选择器中只显示一个面板 | `boolean` | false |
| prefix-icon | 自定义前缀图标组件 | `string` / `Component` | Date |
| clear-icon | 自定义清除图标 | `string` / `Component` | CircleClose |
| shortcuts | 设置快捷选项，需要传入数组对象 | `array` | — |
| disabled-date | 一个用来判断该日期是否被禁用的函数，接受一个 Date 对象作为参数。 应该返回一个 Boolean 值。 | `Function` | — |
| disabled-hours | 禁止选择部分小时选项 | `Function` | — |
| disabled-minutes | 禁止选择部分分钟选项 | `Function` | — |
| disabled-seconds | 禁止选择部分秒选项 | `Function` | — |
| cell-class-name | 设置自定义类名 | `Function` | — |
| teleported | 是否将 datetime-picker 的下拉列表插入至 body 元素 | `boolean` | true |
| empty-values 2.7.0 | 组件的空值配置， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `array` | — |
| value-on-clear 2.7.0 | 清空选项的值， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `string` / `number` / `boolean` / `Function` | — |
| show-now 2.8.7 | 是否显示 now 按钮 | `boolean` | true |
| show-footer 2.10.5 | 是否在日期选择器中显示页脚 ^\[enum\]\`'datetime' | 'datetimerange'\` | `boolean` |
| show-confirm 2.11.0 | 是否显示确定按钮 | `boolean` | true |
| show-week-number 2.10.3 | 显示周数(除周外) | `boolean` | false |

### 事件 [​](#事件)

| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| change | 当用户确认值或点击外部时触发 | `Function` |
| blur | 在组件 Input 失去焦点时触发 | `Function` |
| focus | 在组件 Input 获得焦点时触发 | `Function` |
| clear 2.7.7 | 当点击清除按钮时触发 | `Function` |
| calendar-change | 如果用户没有选择日期，那默认展示当前日的月份。 仅用于 `range` | `Function` |
| panel-change | 当日期面板改变时触发。 | `Function` |
| visible-change | 当 DateTimePicker 的下拉列表出现/消失时触发 | `Function` |

### Slots [​](#slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义单元格内容 |
| range-separator | 自定义范围分割符内容 |
| prev-month 2.8.0 | 上个月的图标 |
| next-month 2.8.0 | 下个月的图标 |
| prev-year 2.8.0 | 上一年图标 |
| next-year 2.8.0 | 下一年图标 |

### Exposes [​](#exposes)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| focus | 使组件获取焦点 | `Function` |
| blur 2.8.7 | 使组件失去焦点 | `Function` |

## Type Declarations [​](#type-declarations)

Show declarations

ts

```
type Placement =
  | 'top'
  | 'top-start'
  | 'top-end'
  | 'bottom'
  | 'bottom-start'
  | 'bottom-end'
  | 'left'
  | 'left-start'
  | 'left-end'
  | 'right'
  | 'right-start'
  | 'right-end'
```

## 源代码 [​](#源代码)

[文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/datetime-picker.md)

[Date Picker 日期选择器](https://element-plus.org/zh-CN/component/date-picker)

[Form 表单组件](https://element-plus.org/zh-CN/component/form)




---
## [form/form] Form 表单
> 官方文档: https://element-plus.org/zh-CN/component/form.html

---

# Form 表单 [​](#form-表单)

更新日志待解决

37

表单包含 `input`、`radio`、`select`、`checkbox` 等需要用户输入的组件。 使用表单，您可以收集、验证和提交数据。

TIP

Form 组件已经从 2. x 的 Float 布局升级为 Flex 布局。

## 典型表单 [​](#典型表单)

最基础的表单包括各种输入表单项，比如`input`、`select`、`radio`、`checkbox`等。

在每一个 `form` 组件中，你需要一个 `form-item` 字段作为输入项的容器，用于获取值与验证值。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZm9ybSA6bW9kZWw9XCJmb3JtXCIgbGFiZWwtd2lkdGg9XCJhdXRvXCIgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCI+XG4gICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIkFjdGl2aXR5IG5hbWVcIj5cbiAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwiZm9ybS5uYW1lXCIgLz5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiQWN0aXZpdHkgem9uZVwiPlxuICAgICAgPGVsLXNlbGVjdCB2LW1vZGVsPVwiZm9ybS5yZWdpb25cIiBwbGFjZWhvbGRlcj1cInBsZWFzZSBzZWxlY3QgeW91ciB6b25lXCI+XG4gICAgICAgIDxlbC1vcHRpb24gbGFiZWw9XCJab25lIG9uZVwiIHZhbHVlPVwic2hhbmdoYWlcIiAvPlxuICAgICAgICA8ZWwtb3B0aW9uIGxhYmVsPVwiWm9uZSB0d29cIiB2YWx1ZT1cImJlaWppbmdcIiAvPlxuICAgICAgPC9lbC1zZWxlY3Q+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIkFjdGl2aXR5IHRpbWVcIj5cbiAgICAgIDxlbC1jb2wgOnNwYW49XCIxMVwiPlxuICAgICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgICB2LW1vZGVsPVwiZm9ybS5kYXRlMVwiXG4gICAgICAgICAgdHlwZT1cImRhdGVcIlxuICAgICAgICAgIHBsYWNlaG9sZGVyPVwiUGljayBhIGRhdGVcIlxuICAgICAgICAgIHN0eWxlPVwid2lkdGg6IDEwMCVcIlxuICAgICAgICAvPlxuICAgICAgPC9lbC1jb2w+XG4gICAgICA8ZWwtY29sIDpzcGFuPVwiMlwiIGNsYXNzPVwidGV4dC1jZW50ZXJcIj5cbiAgICAgICAgPHNwYW4gY2xhc3M9XCJ0ZXh0LWdyYXktNTAwXCI+LTwvc3Bhbj5cbiAgICAgIDwvZWwtY29sPlxuICAgICAgPGVsLWNvbCA6c3Bhbj1cIjExXCI+XG4gICAgICAgIDxlbC10aW1lLXBpY2tlclxuICAgICAgICAgIHYtbW9kZWw9XCJmb3JtLmRhdGUyXCJcbiAgICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSB0aW1lXCJcbiAgICAgICAgICBzdHlsZT1cIndpZHRoOiAxMDAlXCJcbiAgICAgICAgLz5cbiAgICAgIDwvZWwtY29sPlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJJbnN0YW50IGRlbGl2ZXJ5XCI+XG4gICAgICA8ZWwtc3dpdGNoIHYtbW9kZWw9XCJmb3JtLmRlbGl2ZXJ5XCIgLz5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiQWN0aXZpdHkgdHlwZVwiPlxuICAgICAgPGVsLWNoZWNrYm94LWdyb3VwIHYtbW9kZWw9XCJmb3JtLnR5cGVcIj5cbiAgICAgICAgPGVsLWNoZWNrYm94IHZhbHVlPVwiT25saW5lIGFjdGl2aXRpZXNcIiBuYW1lPVwidHlwZVwiPlxuICAgICAgICAgIE9ubGluZSBhY3Rpdml0aWVzXG4gICAgICAgIDwvZWwtY2hlY2tib3g+XG4gICAgICAgIDxlbC1jaGVja2JveCB2YWx1ZT1cIlByb21vdGlvbiBhY3Rpdml0aWVzXCIgbmFtZT1cInR5cGVcIj5cbiAgICAgICAgICBQcm9tb3Rpb24gYWN0aXZpdGllc1xuICAgICAgICA8L2VsLWNoZWNrYm94PlxuICAgICAgICA8ZWwtY2hlY2tib3ggdmFsdWU9XCJPZmZsaW5lIGFjdGl2aXRpZXNcIiBuYW1lPVwidHlwZVwiPlxuICAgICAgICAgIE9mZmxpbmUgYWN0aXZpdGllc1xuICAgICAgICA8L2VsLWNoZWNrYm94PlxuICAgICAgICA8ZWwtY2hlY2tib3ggdmFsdWU9XCJTaW1wbGUgYnJhbmQgZXhwb3N1cmVcIiBuYW1lPVwidHlwZVwiPlxuICAgICAgICAgIFNpbXBsZSBicmFuZCBleHBvc3VyZVxuICAgICAgICA8L2VsLWNoZWNrYm94PlxuICAgICAgPC9lbC1jaGVja2JveC1ncm91cD5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiUmVzb3VyY2VzXCI+XG4gICAgICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cImZvcm0ucmVzb3VyY2VcIj5cbiAgICAgICAgPGVsLXJhZGlvIHZhbHVlPVwiU3BvbnNvclwiPlNwb25zb3I8L2VsLXJhZGlvPlxuICAgICAgICA8ZWwtcmFkaW8gdmFsdWU9XCJWZW51ZVwiPlZlbnVlPC9lbC1yYWRpbz5cbiAgICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIkFjdGl2aXR5IGZvcm1cIj5cbiAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwiZm9ybS5kZXNjXCIgdHlwZT1cInRleHRhcmVhXCIgLz5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiIEBjbGljaz1cIm9uU3VibWl0XCI+Q3JlYXRlPC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uPkNhbmNlbDwvZWwtYnV0dG9uPlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICA8L2VsLWZvcm0+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVhY3RpdmUgfSBmcm9tICd2dWUnXG5cbi8vIGRvIG5vdCB1c2Ugc2FtZSBuYW1lIHdpdGggcmVmXG5jb25zdCBmb3JtID0gcmVhY3RpdmUoe1xuICBuYW1lOiAnJyxcbiAgcmVnaW9uOiAnJyxcbiAgZGF0ZTE6ICcnLFxuICBkYXRlMjogJycsXG4gIGRlbGl2ZXJ5OiBmYWxzZSxcbiAgdHlwZTogW10sXG4gIHJlc291cmNlOiAnJyxcbiAgZGVzYzogJycsXG59KVxuXG5jb25zdCBvblN1Ym1pdCA9ICgpID0+IHtcbiAgY29uc29sZS5sb2coJ3N1Ym1pdCEnKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/form/basic-form.vue)_

vue

```
<template>
  <el-form :model="form" label-width="auto" style="max-width: 600px">
    <el-form-item label="Activity name">
      <el-input v-model="form.name" />
    </el-form-item>
    <el-form-item label="Activity zone">
      <el-select v-model="form.region" placeholder="please select your zone">
        <el-option label="Zone one" value="shanghai" />
        <el-option label="Zone two" value="beijing" />
      </el-select>
    </el-form-item>
    <el-form-item label="Activity time">
      <el-col :span="11">
        <el-date-picker
          v-model="form.date1"
          type="date"
          placeholder="Pick a date"
          style="width: 100%"
        />
      </el-col>
      <el-col :span="2" class="text-center">
        <span class="text-gray-500">-</span>
      </el-col>
      <el-col :span="11">
        <el-time-picker
          v-model="form.date2"
          placeholder="Pick a time"
          style="width: 100%"
        />
      </el-col>
    </el-form-item>
    <el-form-item label="Instant delivery">
      <el-switch v-model="form.delivery" />
    </el-form-item>
    <el-form-item label="Activity type">
      <el-checkbox-group v-model="form.type">
        <el-checkbox value="Online activities" name="type">
          Online activities
        </el-checkbox>
        <el-checkbox value="Promotion activities" name="type">
          Promotion activities
        </el-checkbox>
        <el-checkbox value="Offline activities" name="type">
          Offline activities
        </el-checkbox>
        <el-checkbox value="Simple brand exposure" name="type">
          Simple brand exposure
        </el-checkbox>
      </el-checkbox-group>
    </el-form-item>
    <el-form-item label="Resources">
      <el-radio-group v-model="form.resource">
        <el-radio value="Sponsor">Sponsor</el-radio>
        <el-radio value="Venue">Venue</el-radio>
      </el-radio-group>
    </el-form-item>
    <el-form-item label="Activity form">
      <el-input v-model="form.desc" type="textarea" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="onSubmit">Create</el-button>
      <el-button>Cancel</el-button>
    </el-form-item>
  </el-form>
</template>

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

// do not use same name with ref
const form = reactive({
  name: '',
  region: '',
  date1: '',
  date2: '',
  delivery: false,
  type: [],
  resource: '',
  desc: '',
})

const onSubmit = () => {
  console.log('submit!')
}
</script>
```

隐藏源代码

TIP

[W3C](https://www.w3.org/MarkUp/html-spec/html-spec_8.html#SEC8.2) 标准定义：

> _当一个表单中只有一个单行文本输入字段时， 浏览器应当将在此字段中按下 Enter （回车键）的行为视为提交表单的请求。_ 如果希望阻止这一默认行为，可以在 `<el-form>` 标签上添加 `@submit.prevent`。

## 行内表单 [​](#行内表单)

当垂直方向空间受限且表单较简单时，可以在一行内放置表单。

通过设置 `inline` 属性为 `true` 可以让表单域变为行内的表单域。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZm9ybSA6aW5saW5lPVwidHJ1ZVwiIDptb2RlbD1cImZvcm1JbmxpbmVcIiBjbGFzcz1cImRlbW8tZm9ybS1pbmxpbmVcIj5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiQXBwcm92ZWQgYnlcIj5cbiAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwiZm9ybUlubGluZS51c2VyXCIgcGxhY2Vob2xkZXI9XCJBcHByb3ZlZCBieVwiIGNsZWFyYWJsZSAvPlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJBY3Rpdml0eSB6b25lXCI+XG4gICAgICA8ZWwtc2VsZWN0XG4gICAgICAgIHYtbW9kZWw9XCJmb3JtSW5saW5lLnJlZ2lvblwiXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiQWN0aXZpdHkgem9uZVwiXG4gICAgICAgIGNsZWFyYWJsZVxuICAgICAgPlxuICAgICAgICA8ZWwtb3B0aW9uIGxhYmVsPVwiWm9uZSBvbmVcIiB2YWx1ZT1cInNoYW5naGFpXCIgLz5cbiAgICAgICAgPGVsLW9wdGlvbiBsYWJlbD1cIlpvbmUgdHdvXCIgdmFsdWU9XCJiZWlqaW5nXCIgLz5cbiAgICAgIDwvZWwtc2VsZWN0PlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJBY3Rpdml0eSB0aW1lXCI+XG4gICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgdi1tb2RlbD1cImZvcm1JbmxpbmUuZGF0ZVwiXG4gICAgICAgIHR5cGU9XCJkYXRlXCJcbiAgICAgICAgcGxhY2Vob2xkZXI9XCJQaWNrIGEgZGF0ZVwiXG4gICAgICAgIGNsZWFyYWJsZVxuICAgICAgLz5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiIEBjbGljaz1cIm9uU3VibWl0XCI+UXVlcnk8L2VsLWJ1dHRvbj5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgPC9lbC1mb3JtPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlYWN0aXZlIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBmb3JtSW5saW5lID0gcmVhY3RpdmUoe1xuICB1c2VyOiAnJyxcbiAgcmVnaW9uOiAnJyxcbiAgZGF0ZTogJycsXG59KVxuXG5jb25zdCBvblN1Ym1pdCA9ICgpID0+IHtcbiAgY29uc29sZS5sb2coJ3N1Ym1pdCEnKVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5kZW1vLWZvcm0taW5saW5lIC5lbC1pbnB1dCB7XG4gIC0tZWwtaW5wdXQtd2lkdGg6IDIyMHB4O1xufVxuXG4uZGVtby1mb3JtLWlubGluZSAuZWwtc2VsZWN0IHtcbiAgLS1lbC1zZWxlY3Qtd2lkdGg6IDIyMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/form/inline-form.vue)_

vue

```
<template>
  <el-form :inline="true" :model="formInline" class="demo-form-inline">
    <el-form-item label="Approved by">
      <el-input v-model="formInline.user" placeholder="Approved by" clearable />
    </el-form-item>
    <el-form-item label="Activity zone">
      <el-select
        v-model="formInline.region"
        placeholder="Activity zone"
        clearable
      >
        <el-option label="Zone one" value="shanghai" />
        <el-option label="Zone two" value="beijing" />
      </el-select>
    </el-form-item>
    <el-form-item label="Activity time">
      <el-date-picker
        v-model="formInline.date"
        type="date"
        placeholder="Pick a date"
        clearable
      />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="onSubmit">Query</el-button>
    </el-form-item>
  </el-form>
</template>

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

const formInline = reactive({
  user: '',
  region: '',
  date: '',
})

const onSubmit = () => {
  console.log('submit!')
}
</script>

<style>
.demo-form-inline .el-input {
  --el-input-width: 220px;
}

.demo-form-inline .el-select {
  --el-select-width: 220px;
}
</style>
```

隐藏源代码

## 对齐方式 [​](#对齐方式)

根据你们的设计情况，来选择最佳的标签对齐方式。

您可以分别设置 `el-form-item` 的`label-position` 2.7.7. 如果值为空, 则会使用 `el-form`的`label-position`。

通过设置 `label-position` 属性可以改变表单域标签的位置，可选值为 `top`、`left`, 当设为 `top` 时标签会置于表单域的顶部

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZm9ybVxuICAgIDpsYWJlbC1wb3NpdGlvbj1cImxhYmVsUG9zaXRpb25cIlxuICAgIGxhYmVsLXdpZHRoPVwiYXV0b1wiXG4gICAgOm1vZGVsPVwiZm9ybUxhYmVsQWxpZ25cIlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gID5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiRm9ybSBBbGlnblwiIGxhYmVsLXBvc2l0aW9uPVwicmlnaHRcIj5cbiAgICAgIDxlbC1yYWRpby1ncm91cCB2LW1vZGVsPVwibGFiZWxQb3NpdGlvblwiIGFyaWEtbGFiZWw9XCJsYWJlbCBwb3NpdGlvblwiPlxuICAgICAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwibGVmdFwiPkxlZnQ8L2VsLXJhZGlvLWJ1dHRvbj5cbiAgICAgICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cInJpZ2h0XCI+UmlnaHQ8L2VsLXJhZGlvLWJ1dHRvbj5cbiAgICAgICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cInRvcFwiPlRvcDwvZWwtcmFkaW8tYnV0dG9uPlxuICAgICAgPC9lbC1yYWRpby1ncm91cD5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiRm9ybSBJdGVtIEFsaWduXCIgbGFiZWwtcG9zaXRpb249XCJyaWdodFwiPlxuICAgICAgPGVsLXJhZGlvLWdyb3VwXG4gICAgICAgIHYtbW9kZWw9XCJpdGVtTGFiZWxQb3NpdGlvblwiXG4gICAgICAgIGFyaWEtbGFiZWw9XCJpdGVtIGxhYmVsIHBvc2l0aW9uXCJcbiAgICAgID5cbiAgICAgICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cIlwiPkVtcHR5PC9lbC1yYWRpby1idXR0b24+XG4gICAgICAgIDxlbC1yYWRpby1idXR0b24gdmFsdWU9XCJsZWZ0XCI+TGVmdDwvZWwtcmFkaW8tYnV0dG9uPlxuICAgICAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwicmlnaHRcIj5SaWdodDwvZWwtcmFkaW8tYnV0dG9uPlxuICAgICAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwidG9wXCI+VG9wPC9lbC1yYWRpby1idXR0b24+XG4gICAgICA8L2VsLXJhZGlvLWdyb3VwPlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJOYW1lXCIgOmxhYmVsLXBvc2l0aW9uPVwiaXRlbUxhYmVsUG9zaXRpb25cIj5cbiAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwiZm9ybUxhYmVsQWxpZ24ubmFtZVwiIC8+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIkFjdGl2aXR5IHpvbmVcIiA6bGFiZWwtcG9zaXRpb249XCJpdGVtTGFiZWxQb3NpdGlvblwiPlxuICAgICAgPGVsLWlucHV0IHYtbW9kZWw9XCJmb3JtTGFiZWxBbGlnbi5yZWdpb25cIiAvPlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJBY3Rpdml0eSBmb3JtXCIgOmxhYmVsLXBvc2l0aW9uPVwiaXRlbUxhYmVsUG9zaXRpb25cIj5cbiAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwiZm9ybUxhYmVsQWxpZ24udHlwZVwiIC8+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gIDwvZWwtZm9ybT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWFjdGl2ZSwgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IEZvcm1JdGVtUHJvcHMsIEZvcm1Qcm9wcyB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgbGFiZWxQb3NpdGlvbiA9IHJlZjxGb3JtUHJvcHNbJ2xhYmVsUG9zaXRpb24nXT4oJ3JpZ2h0JylcbmNvbnN0IGl0ZW1MYWJlbFBvc2l0aW9uID0gcmVmPEZvcm1JdGVtUHJvcHNbJ2xhYmVsUG9zaXRpb24nXT4oJycpXG5jb25zdCBmb3JtTGFiZWxBbGlnbiA9IHJlYWN0aXZlKHtcbiAgbmFtZTogJycsXG4gIHJlZ2lvbjogJycsXG4gIHR5cGU6ICcnLFxufSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/form/alignment.vue)_

vue

```
<template>
  <el-form
    :label-position="labelPosition"
    label-width="auto"
    :model="formLabelAlign"
    style="max-width: 600px"
  >
    <el-form-item label="Form Align" label-position="right">
      <el-radio-group v-model="labelPosition" aria-label="label position">
        <el-radio-button value="left">Left</el-radio-button>
        <el-radio-button value="right">Right</el-radio-button>
        <el-radio-button value="top">Top</el-radio-button>
      </el-radio-group>
    </el-form-item>
    <el-form-item label="Form Item Align" label-position="right">
      <el-radio-group
        v-model="itemLabelPosition"
        aria-label="item label position"
      >
        <el-radio-button value="">Empty</el-radio-button>
        <el-radio-button value="left">Left</el-radio-button>
        <el-radio-button value="right">Right</el-radio-button>
        <el-radio-button value="top">Top</el-radio-button>
      </el-radio-group>
    </el-form-item>
    <el-form-item label="Name" :label-position="itemLabelPosition">
      <el-input v-model="formLabelAlign.name" />
    </el-form-item>
    <el-form-item label="Activity zone" :label-position="itemLabelPosition">
      <el-input v-model="formLabelAlign.region" />
    </el-form-item>
    <el-form-item label="Activity form" :label-position="itemLabelPosition">
      <el-input v-model="formLabelAlign.type" />
    </el-form-item>
  </el-form>
</template>

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

import type { FormItemProps, FormProps } from 'element-plus'

const labelPosition = ref<FormProps['labelPosition']>('right')
const itemLabelPosition = ref<FormItemProps['labelPosition']>('')
const formLabelAlign = reactive({
  name: '',
  region: '',
  type: '',
})
</script>
```

隐藏源代码

## 表单校验 [​](#表单校验)

Form 组件允许你验证用户的输入是否符合规范，来帮助你找到和纠正错误。

`Form` 组件提供了表单验证的功能，只需为 `rules` 属性传入约定的验证规则，并将 `form-Item` 的 `prop` 属性设置为需要验证的特殊键值即可。 校验规则参见 [async-validator](https://github.com/yiminghe/async-validator)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZm9ybVxuICAgIHJlZj1cInJ1bGVGb3JtUmVmXCJcbiAgICBzdHlsZT1cIm1heC13aWR0aDogNjAwcHhcIlxuICAgIDptb2RlbD1cInJ1bGVGb3JtXCJcbiAgICA6cnVsZXM9XCJydWxlc1wiXG4gICAgbGFiZWwtd2lkdGg9XCJhdXRvXCJcbiAgPlxuICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJBY3Rpdml0eSBuYW1lXCIgcHJvcD1cIm5hbWVcIj5cbiAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwicnVsZUZvcm0ubmFtZVwiIC8+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIkFjdGl2aXR5IHpvbmVcIiBwcm9wPVwicmVnaW9uXCI+XG4gICAgICA8ZWwtc2VsZWN0IHYtbW9kZWw9XCJydWxlRm9ybS5yZWdpb25cIiBwbGFjZWhvbGRlcj1cIkFjdGl2aXR5IHpvbmVcIj5cbiAgICAgICAgPGVsLW9wdGlvbiBsYWJlbD1cIlpvbmUgb25lXCIgdmFsdWU9XCJzaGFuZ2hhaVwiIC8+XG4gICAgICAgIDxlbC1vcHRpb24gbGFiZWw9XCJab25lIHR3b1wiIHZhbHVlPVwiYmVpamluZ1wiIC8+XG4gICAgICA8L2VsLXNlbGVjdD5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiQWN0aXZpdHkgY291bnRcIiBwcm9wPVwiY291bnRcIj5cbiAgICAgIDxlbC1zZWxlY3QtdjJcbiAgICAgICAgdi1tb2RlbD1cInJ1bGVGb3JtLmNvdW50XCJcbiAgICAgICAgcGxhY2Vob2xkZXI9XCJBY3Rpdml0eSBjb3VudFwiXG4gICAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICAvPlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJBY3Rpdml0eSB0aW1lXCIgcmVxdWlyZWQ+XG4gICAgICA8ZWwtY29sIDpzcGFuPVwiMTFcIj5cbiAgICAgICAgPGVsLWZvcm0taXRlbSBwcm9wPVwiZGF0ZTFcIj5cbiAgICAgICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgICAgIHYtbW9kZWw9XCJydWxlRm9ybS5kYXRlMVwiXG4gICAgICAgICAgICB0eXBlPVwiZGF0ZVwiXG4gICAgICAgICAgICBhcmlhLWxhYmVsPVwiUGljayBhIGRhdGVcIlxuICAgICAgICAgICAgcGxhY2Vob2xkZXI9XCJQaWNrIGEgZGF0ZVwiXG4gICAgICAgICAgICBzdHlsZT1cIndpZHRoOiAxMDAlXCJcbiAgICAgICAgICAvPlxuICAgICAgICA8L2VsLWZvcm0taXRlbT5cbiAgICAgIDwvZWwtY29sPlxuICAgICAgPGVsLWNvbCBjbGFzcz1cInRleHQtY2VudGVyXCIgOnNwYW49XCIyXCI+XG4gICAgICAgIDxzcGFuIGNsYXNzPVwidGV4dC1ncmF5LTUwMFwiPi08L3NwYW4+XG4gICAgICA8L2VsLWNvbD5cbiAgICAgIDxlbC1jb2wgOnNwYW49XCIxMVwiPlxuICAgICAgICA8ZWwtZm9ybS1pdGVtIHByb3A9XCJkYXRlMlwiPlxuICAgICAgICAgIDxlbC10aW1lLXBpY2tlclxuICAgICAgICAgICAgdi1tb2RlbD1cInJ1bGVGb3JtLmRhdGUyXCJcbiAgICAgICAgICAgIGFyaWEtbGFiZWw9XCJQaWNrIGEgdGltZVwiXG4gICAgICAgICAgICBwbGFjZWhvbGRlcj1cIlBpY2sgYSB0aW1lXCJcbiAgICAgICAgICAgIHN0eWxlPVwid2lkdGg6IDEwMCVcIlxuICAgICAgICAgIC8+XG4gICAgICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgICAgPC9lbC1jb2w+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIkluc3RhbnQgZGVsaXZlcnlcIiBwcm9wPVwiZGVsaXZlcnlcIj5cbiAgICAgIDxlbC1zd2l0Y2ggdi1tb2RlbD1cInJ1bGVGb3JtLmRlbGl2ZXJ5XCIgLz5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiQWN0aXZpdHkgbG9jYXRpb25cIiBwcm9wPVwibG9jYXRpb25cIj5cbiAgICAgIDxlbC1zZWdtZW50ZWQgdi1tb2RlbD1cInJ1bGVGb3JtLmxvY2F0aW9uXCIgOm9wdGlvbnM9XCJsb2NhdGlvbk9wdGlvbnNcIiAvPlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJBY3Rpdml0eSB0eXBlXCIgcHJvcD1cInR5cGVcIj5cbiAgICAgIDxlbC1jaGVja2JveC1ncm91cCB2LW1vZGVsPVwicnVsZUZvcm0udHlwZVwiPlxuICAgICAgICA8ZWwtY2hlY2tib3ggdmFsdWU9XCJPbmxpbmUgYWN0aXZpdGllc1wiIG5hbWU9XCJ0eXBlXCI+XG4gICAgICAgICAgT25saW5lIGFjdGl2aXRpZXNcbiAgICAgICAgPC9lbC1jaGVja2JveD5cbiAgICAgICAgPGVsLWNoZWNrYm94IHZhbHVlPVwiUHJvbW90aW9uIGFjdGl2aXRpZXNcIiBuYW1lPVwidHlwZVwiPlxuICAgICAgICAgIFByb21vdGlvbiBhY3Rpdml0aWVzXG4gICAgICAgIDwvZWwtY2hlY2tib3g+XG4gICAgICAgIDxlbC1jaGVja2JveCB2YWx1ZT1cIk9mZmxpbmUgYWN0aXZpdGllc1wiIG5hbWU9XCJ0eXBlXCI+XG4gICAgICAgICAgT2ZmbGluZSBhY3Rpdml0aWVzXG4gICAgICAgIDwvZWwtY2hlY2tib3g+XG4gICAgICAgIDxlbC1jaGVja2JveCB2YWx1ZT1cIlNpbXBsZSBicmFuZCBleHBvc3VyZVwiIG5hbWU9XCJ0eXBlXCI+XG4gICAgICAgICAgU2ltcGxlIGJyYW5kIGV4cG9zdXJlXG4gICAgICAgIDwvZWwtY2hlY2tib3g+XG4gICAgICA8L2VsLWNoZWNrYm94LWdyb3VwPlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJSZXNvdXJjZXNcIiBwcm9wPVwicmVzb3VyY2VcIj5cbiAgICAgIDxlbC1yYWRpby1ncm91cCB2LW1vZGVsPVwicnVsZUZvcm0ucmVzb3VyY2VcIj5cbiAgICAgICAgPGVsLXJhZGlvIHZhbHVlPVwiU3BvbnNvcnNoaXBcIj5TcG9uc29yc2hpcDwvZWwtcmFkaW8+XG4gICAgICAgIDxlbC1yYWRpbyB2YWx1ZT1cIlZlbnVlXCI+VmVudWU8L2VsLXJhZGlvPlxuICAgICAgPC9lbC1yYWRpby1ncm91cD5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiQWN0aXZpdHkgZm9ybVwiIHByb3A9XCJkZXNjXCI+XG4gICAgICA8ZWwtaW5wdXQgdi1tb2RlbD1cInJ1bGVGb3JtLmRlc2NcIiB0eXBlPVwidGV4dGFyZWFcIiAvPlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDxlbC1mb3JtLWl0ZW0+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwic3VibWl0Rm9ybShydWxlRm9ybVJlZilcIj5cbiAgICAgICAgQ3JlYXRlXG4gICAgICA8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwicmVzZXRGb3JtKHJ1bGVGb3JtUmVmKVwiPlJlc2V0PC9lbC1idXR0b24+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gIDwvZWwtZm9ybT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWFjdGl2ZSwgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IEZvcm1JbnN0YW5jZSwgRm9ybVJ1bGVzIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbnRlcmZhY2UgUnVsZUZvcm0ge1xuICBuYW1lOiBzdHJpbmdcbiAgcmVnaW9uOiBzdHJpbmdcbiAgY291bnQ6IHN0cmluZ1xuICBkYXRlMTogc3RyaW5nXG4gIGRhdGUyOiBzdHJpbmdcbiAgZGVsaXZlcnk6IGJvb2xlYW5cbiAgbG9jYXRpb246IHN0cmluZ1xuICB0eXBlOiBzdHJpbmdbXVxuICByZXNvdXJjZTogc3RyaW5nXG4gIGRlc2M6IHN0cmluZ1xufVxuXG5jb25zdCBydWxlRm9ybVJlZiA9IHJlZjxGb3JtSW5zdGFuY2U+KClcbmNvbnN0IHJ1bGVGb3JtID0gcmVhY3RpdmU8UnVsZUZvcm0+KHtcbiAgbmFtZTogJ0hlbGxvJyxcbiAgcmVnaW9uOiAnJyxcbiAgY291bnQ6ICcnLFxuICBkYXRlMTogJycsXG4gIGRhdGUyOiAnJyxcbiAgZGVsaXZlcnk6IGZhbHNlLFxuICBsb2NhdGlvbjogJycsXG4gIHR5cGU6IFtdLFxuICByZXNvdXJjZTogJycsXG4gIGRlc2M6ICcnLFxufSlcblxuY29uc3QgbG9jYXRpb25PcHRpb25zID0gWydIb21lJywgJ0NvbXBhbnknLCAnU2Nob29sJ11cblxuY29uc3QgcnVsZXMgPSByZWFjdGl2ZTxGb3JtUnVsZXM8UnVsZUZvcm0+Pih7XG4gIG5hbWU6IFtcbiAgICB7IHJlcXVpcmVkOiB0cnVlLCBtZXNzYWdlOiAnUGxlYXNlIGlucHV0IEFjdGl2aXR5IG5hbWUnLCB0cmlnZ2VyOiAnYmx1cicgfSxcbiAgICB7IG1pbjogMywgbWF4OiA1LCBtZXNzYWdlOiAnTGVuZ3RoIHNob3VsZCBiZSAzIHRvIDUnLCB0cmlnZ2VyOiAnYmx1cicgfSxcbiAgXSxcbiAgcmVnaW9uOiBbXG4gICAge1xuICAgICAgcmVxdWlyZWQ6IHRydWUsXG4gICAgICBtZXNzYWdlOiAnUGxlYXNlIHNlbGVjdCBBY3Rpdml0eSB6b25lJyxcbiAgICAgIHRyaWdnZXI6ICdjaGFuZ2UnLFxuICAgIH0sXG4gIF0sXG4gIGNvdW50OiBbXG4gICAge1xuICAgICAgcmVxdWlyZWQ6IHRydWUsXG4gICAgICBtZXNzYWdlOiAnUGxlYXNlIHNlbGVjdCBBY3Rpdml0eSBjb3VudCcsXG4gICAgICB0cmlnZ2VyOiAnY2hhbmdlJyxcbiAgICB9LFxuICBdLFxuICBkYXRlMTogW1xuICAgIHtcbiAgICAgIHR5cGU6ICdkYXRlJyxcbiAgICAgIHJlcXVpcmVkOiB0cnVlLFxuICAgICAgbWVzc2FnZTogJ1BsZWFzZSBwaWNrIGEgZGF0ZScsXG4gICAgICB0cmlnZ2VyOiAnY2hhbmdlJyxcbiAgICB9LFxuICBdLFxuICBkYXRlMjogW1xuICAgIHtcbiAgICAgIHR5cGU6ICdkYXRlJyxcbiAgICAgIHJlcXVpcmVkOiB0cnVlLFxuICAgICAgbWVzc2FnZTogJ1BsZWFzZSBwaWNrIGEgdGltZScsXG4gICAgICB0cmlnZ2VyOiAnY2hhbmdlJyxcbiAgICB9LFxuICBdLFxuICBsb2NhdGlvbjogW1xuICAgIHtcbiAgICAgIHJlcXVpcmVkOiB0cnVlLFxuICAgICAgbWVzc2FnZTogJ1BsZWFzZSBzZWxlY3QgYSBsb2NhdGlvbicsXG4gICAgICB0cmlnZ2VyOiAnY2hhbmdlJyxcbiAgICB9LFxuICBdLFxuICB0eXBlOiBbXG4gICAge1xuICAgICAgdHlwZTogJ2FycmF5JyxcbiAgICAgIHJlcXVpcmVkOiB0cnVlLFxuICAgICAgbWVzc2FnZTogJ1BsZWFzZSBzZWxlY3QgYXQgbGVhc3Qgb25lIGFjdGl2aXR5IHR5cGUnLFxuICAgICAgdHJpZ2dlcjogJ2NoYW5nZScsXG4gICAgfSxcbiAgXSxcbiAgcmVzb3VyY2U6IFtcbiAgICB7XG4gICAgICByZXF1aXJlZDogdHJ1ZSxcbiAgICAgIG1lc3NhZ2U6ICdQbGVhc2Ugc2VsZWN0IGFjdGl2aXR5IHJlc291cmNlJyxcbiAgICAgIHRyaWdnZXI6ICdjaGFuZ2UnLFxuICAgIH0sXG4gIF0sXG4gIGRlc2M6IFtcbiAgICB7IHJlcXVpcmVkOiB0cnVlLCBtZXNzYWdlOiAnUGxlYXNlIGlucHV0IGFjdGl2aXR5IGZvcm0nLCB0cmlnZ2VyOiAnYmx1cicgfSxcbiAgXSxcbn0pXG5cbmNvbnN0IHN1Ym1pdEZvcm0gPSBhc3luYyAoZm9ybUVsOiBGb3JtSW5zdGFuY2UgfCB1bmRlZmluZWQpID0+IHtcbiAgaWYgKCFmb3JtRWwpIHJldHVyblxuICBhd2FpdCBmb3JtRWwudmFsaWRhdGUoKHZhbGlkLCBmaWVsZHMpID0+IHtcbiAgICBpZiAodmFsaWQpIHtcbiAgICAgIGNvbnNvbGUubG9nKCdzdWJtaXQhJylcbiAgICB9IGVsc2Uge1xuICAgICAgY29uc29sZS5sb2coJ2Vycm9yIHN1Ym1pdCEnLCBmaWVsZHMpXG4gICAgfVxuICB9KVxufVxuXG5jb25zdCByZXNldEZvcm0gPSAoZm9ybUVsOiBGb3JtSW5zdGFuY2UgfCB1bmRlZmluZWQpID0+IHtcbiAgaWYgKCFmb3JtRWwpIHJldHVyblxuICBmb3JtRWwucmVzZXRGaWVsZHMoKVxufVxuXG5jb25zdCBvcHRpb25zID0gQXJyYXkuZnJvbSh7IGxlbmd0aDogMTAwMDAgfSkubWFwKChfLCBpZHgpID0+ICh7XG4gIHZhbHVlOiBgJHtpZHggKyAxfWAsXG4gIGxhYmVsOiBgJHtpZHggKyAxfWAsXG59KSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/form/validation.vue)_

vue

```
<template>
  <el-form
    ref="ruleFormRef"
    style="max-width: 600px"
    :model="ruleForm"
    :rules="rules"
    label-width="auto"
  >
    <el-form-item label="Activity name" prop="name">
      <el-input v-model="ruleForm.name" />
    </el-form-item>
    <el-form-item label="Activity zone" prop="region">
      <el-select v-model="ruleForm.region" placeholder="Activity zone">
        <el-option label="Zone one" value="shanghai" />
        <el-option label="Zone two" value="beijing" />
      </el-select>
    </el-form-item>
    <el-form-item label="Activity count" prop="count">
      <el-select-v2
        v-model="ruleForm.count"
        placeholder="Activity count"
        :options="options"
      />
    </el-form-item>
    <el-form-item label="Activity time" required>
      <el-col :span="11">
        <el-form-item prop="date1">
          <el-date-picker
            v-model="ruleForm.date1"
            type="date"
            aria-label="Pick a date"
            placeholder="Pick a date"
            style="width: 100%"
          />
        </el-form-item>
      </el-col>
      <el-col class="text-center" :span="2">
        <span class="text-gray-500">-</span>
      </el-col>
      <el-col :span="11">
        <el-form-item prop="date2">
          <el-time-picker
            v-model="ruleForm.date2"
            aria-label="Pick a time"
            placeholder="Pick a time"
            style="width: 100%"
          />
        </el-form-item>
      </el-col>
    </el-form-item>
    <el-form-item label="Instant delivery" prop="delivery">
      <el-switch v-model="ruleForm.delivery" />
    </el-form-item>
    <el-form-item label="Activity location" prop="location">
      <el-segmented v-model="ruleForm.location" :options="locationOptions" />
    </el-form-item>
    <el-form-item label="Activity type" prop="type">
      <el-checkbox-group v-model="ruleForm.type">
        <el-checkbox value="Online activities" name="type">
          Online activities
        </el-checkbox>
        <el-checkbox value="Promotion activities" name="type">
          Promotion activities
        </el-checkbox>
        <el-checkbox value="Offline activities" name="type">
          Offline activities
        </el-checkbox>
        <el-checkbox value="Simple brand exposure" name="type">
          Simple brand exposure
        </el-checkbox>
      </el-checkbox-group>
    </el-form-item>
    <el-form-item label="Resources" prop="resource">
      <el-radio-group v-model="ruleForm.resource">
        <el-radio value="Sponsorship">Sponsorship</el-radio>
        <el-radio value="Venue">Venue</el-radio>
      </el-radio-group>
    </el-form-item>
    <el-form-item label="Activity form" prop="desc">
      <el-input v-model="ruleForm.desc" type="textarea" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submitForm(ruleFormRef)">
        Create
      </el-button>
      <el-button @click="resetForm(ruleFormRef)">Reset</el-button>
    </el-form-item>
  </el-form>
</template>

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

import type { FormInstance, FormRules } from 'element-plus'

interface RuleForm {
  name: string
  region: string
  count: string
  date1: string
  date2: string
  delivery: boolean
  location: string
  type: string[]
  resource: string
  desc: string
}

const ruleFormRef = ref<FormInstance>()
const ruleForm = reactive<RuleForm>({
  name: 'Hello',
  region: '',
  count: '',
  date1: '',
  date2: '',
  delivery: false,
  location: '',
  type: [],
  resource: '',
  desc: '',
})

const locationOptions = ['Home', 'Company', 'School']

const rules = reactive<FormRules<RuleForm>>({
  name: [
    { required: true, message: 'Please input Activity name', trigger: 'blur' },
    { min: 3, max: 5, message: 'Length should be 3 to 5', trigger: 'blur' },
  ],
  region: [
    {
      required: true,
      message: 'Please select Activity zone',
      trigger: 'change',
    },
  ],
  count: [
    {
      required: true,
      message: 'Please select Activity count',
      trigger: 'change',
    },
  ],
  date1: [
    {
      type: 'date',
      required: true,
      message: 'Please pick a date',
      trigger: 'change',
    },
  ],
  date2: [
    {
      type: 'date',
      required: true,
      message: 'Please pick a time',
      trigger: 'change',
    },
  ],
  location: [
    {
      required: true,
      message: 'Please select a location',
      trigger: 'change',
    },
  ],
  type: [
    {
      type: 'array',
      required: true,
      message: 'Please select at least one activity type',
      trigger: 'change',
    },
  ],
  resource: [
    {
      required: true,
      message: 'Please select activity resource',
      trigger: 'change',
    },
  ],
  desc: [
    { required: true, message: 'Please input activity form', trigger: 'blur' },
  ],
})

const submitForm = async (formEl: FormInstance | undefined) => {
  if (!formEl) return
  await formEl.validate((valid, fields) => {
    if (valid) {
      console.log('submit!')
    } else {
      console.log('error submit!', fields)
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.resetFields()
}

const options = Array.from({ length: 10000 }).map((_, idx) => ({
  value: `${idx + 1}`,
  label: `${idx + 1}`,
}))
</script>
```

隐藏源代码

## 自定义校验规则 [​](#自定义校验规则)

这个例子中展示了如何使用自定义验证规则来完成密码的二次验证。

本例还使用`status-icon`属性为输入框添加了表示校验结果的反馈图标。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZm9ybVxuICAgIHJlZj1cInJ1bGVGb3JtUmVmXCJcbiAgICBzdHlsZT1cIm1heC13aWR0aDogNjAwcHhcIlxuICAgIDptb2RlbD1cInJ1bGVGb3JtXCJcbiAgICBzdGF0dXMtaWNvblxuICAgIDpydWxlcz1cInJ1bGVzXCJcbiAgICBsYWJlbC13aWR0aD1cImF1dG9cIlxuICAgIGNsYXNzPVwiZGVtby1ydWxlRm9ybVwiXG4gID5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiUGFzc3dvcmRcIiBwcm9wPVwicGFzc1wiPlxuICAgICAgPGVsLWlucHV0IHYtbW9kZWw9XCJydWxlRm9ybS5wYXNzXCIgdHlwZT1cInBhc3N3b3JkXCIgYXV0b2NvbXBsZXRlPVwib2ZmXCIgLz5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiQ29uZmlybVwiIHByb3A9XCJjaGVja1Bhc3NcIj5cbiAgICAgIDxlbC1pbnB1dFxuICAgICAgICB2LW1vZGVsPVwicnVsZUZvcm0uY2hlY2tQYXNzXCJcbiAgICAgICAgdHlwZT1cInBhc3N3b3JkXCJcbiAgICAgICAgYXV0b2NvbXBsZXRlPVwib2ZmXCJcbiAgICAgIC8+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIkFnZVwiIHByb3A9XCJhZ2VcIj5cbiAgICAgIDxlbC1pbnB1dCB2LW1vZGVsLm51bWJlcj1cInJ1bGVGb3JtLmFnZVwiIC8+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbT5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBAY2xpY2s9XCJzdWJtaXRGb3JtKHJ1bGVGb3JtUmVmKVwiPlxuICAgICAgICBTdWJtaXRcbiAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJyZXNldEZvcm0ocnVsZUZvcm1SZWYpXCI+UmVzZXQ8L2VsLWJ1dHRvbj5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgPC9lbC1mb3JtPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlYWN0aXZlLCByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgRm9ybUluc3RhbmNlLCBGb3JtUnVsZXMgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHJ1bGVGb3JtUmVmID0gcmVmPEZvcm1JbnN0YW5jZT4oKVxuXG5jb25zdCBjaGVja0FnZSA9IChydWxlOiBhbnksIHZhbHVlOiBhbnksIGNhbGxiYWNrOiBhbnkpID0+IHtcbiAgaWYgKCF2YWx1ZSkge1xuICAgIHJldHVybiBjYWxsYmFjayhuZXcgRXJyb3IoJ1BsZWFzZSBpbnB1dCB0aGUgYWdlJykpXG4gIH1cbiAgc2V0VGltZW91dCgoKSA9PiB7XG4gICAgaWYgKCFOdW1iZXIuaXNJbnRlZ2VyKHZhbHVlKSkge1xuICAgICAgY2FsbGJhY2sobmV3IEVycm9yKCdQbGVhc2UgaW5wdXQgZGlnaXRzJykpXG4gICAgfSBlbHNlIHtcbiAgICAgIGlmICh2YWx1ZSA8IDE4KSB7XG4gICAgICAgIGNhbGxiYWNrKG5ldyBFcnJvcignQWdlIG11c3QgYmUgZ3JlYXRlciB0aGFuIDE4JykpXG4gICAgICB9IGVsc2Uge1xuICAgICAgICBjYWxsYmFjaygpXG4gICAgICB9XG4gICAgfVxuICB9LCAxMDAwKVxufVxuXG5jb25zdCB2YWxpZGF0ZVBhc3MgPSAocnVsZTogYW55LCB2YWx1ZTogYW55LCBjYWxsYmFjazogYW55KSA9PiB7XG4gIGlmICh2YWx1ZSA9PT0gJycpIHtcbiAgICBjYWxsYmFjayhuZXcgRXJyb3IoJ1BsZWFzZSBpbnB1dCB0aGUgcGFzc3dvcmQnKSlcbiAgfSBlbHNlIHtcbiAgICBpZiAocnVsZUZvcm0uY2hlY2tQYXNzICE9PSAnJykge1xuICAgICAgaWYgKCFydWxlRm9ybVJlZi52YWx1ZSkgcmV0dXJuXG4gICAgICBydWxlRm9ybVJlZi52YWx1ZS52YWxpZGF0ZUZpZWxkKCdjaGVja1Bhc3MnKVxuICAgIH1cbiAgICBjYWxsYmFjaygpXG4gIH1cbn1cbmNvbnN0IHZhbGlkYXRlUGFzczIgPSAocnVsZTogYW55LCB2YWx1ZTogYW55LCBjYWxsYmFjazogYW55KSA9PiB7XG4gIGlmICh2YWx1ZSA9PT0gJycpIHtcbiAgICBjYWxsYmFjayhuZXcgRXJyb3IoJ1BsZWFzZSBpbnB1dCB0aGUgcGFzc3dvcmQgYWdhaW4nKSlcbiAgfSBlbHNlIGlmICh2YWx1ZSAhPT0gcnVsZUZvcm0ucGFzcykge1xuICAgIGNhbGxiYWNrKG5ldyBFcnJvcihcIlR3byBpbnB1dHMgZG9uJ3QgbWF0Y2ghXCIpKVxuICB9IGVsc2Uge1xuICAgIGNhbGxiYWNrKClcbiAgfVxufVxuXG5jb25zdCBydWxlRm9ybSA9IHJlYWN0aXZlKHtcbiAgcGFzczogJycsXG4gIGNoZWNrUGFzczogJycsXG4gIGFnZTogJycsXG59KVxuXG5jb25zdCBydWxlcyA9IHJlYWN0aXZlPEZvcm1SdWxlczx0eXBlb2YgcnVsZUZvcm0+Pih7XG4gIHBhc3M6IFt7IHZhbGlkYXRvcjogdmFsaWRhdGVQYXNzLCB0cmlnZ2VyOiAnYmx1cicgfV0sXG4gIGNoZWNrUGFzczogW3sgdmFsaWRhdG9yOiB2YWxpZGF0ZVBhc3MyLCB0cmlnZ2VyOiAnYmx1cicgfV0sXG4gIGFnZTogW3sgdmFsaWRhdG9yOiBjaGVja0FnZSwgdHJpZ2dlcjogJ2JsdXInIH1dLFxufSlcblxuY29uc3Qgc3VibWl0Rm9ybSA9IChmb3JtRWw6IEZvcm1JbnN0YW5jZSB8IHVuZGVmaW5lZCkgPT4ge1xuICBpZiAoIWZvcm1FbCkgcmV0dXJuXG4gIGZvcm1FbC52YWxpZGF0ZSgodmFsaWQpID0+IHtcbiAgICBpZiAodmFsaWQpIHtcbiAgICAgIGNvbnNvbGUubG9nKCdzdWJtaXQhJylcbiAgICB9IGVsc2Uge1xuICAgICAgY29uc29sZS5sb2coJ2Vycm9yIHN1Ym1pdCEnKVxuICAgIH1cbiAgfSlcbn1cblxuY29uc3QgcmVzZXRGb3JtID0gKGZvcm1FbDogRm9ybUluc3RhbmNlIHwgdW5kZWZpbmVkKSA9PiB7XG4gIGlmICghZm9ybUVsKSByZXR1cm5cbiAgZm9ybUVsLnJlc2V0RmllbGRzKClcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/form/custom-validation.vue)_

vue

```
<template>
  <el-form
    ref="ruleFormRef"
    style="max-width: 600px"
    :model="ruleForm"
    status-icon
    :rules="rules"
    label-width="auto"
    class="demo-ruleForm"
  >
    <el-form-item label="Password" prop="pass">
      <el-input v-model="ruleForm.pass" type="password" autocomplete="off" />
    </el-form-item>
    <el-form-item label="Confirm" prop="checkPass">
      <el-input
        v-model="ruleForm.checkPass"
        type="password"
        autocomplete="off"
      />
    </el-form-item>
    <el-form-item label="Age" prop="age">
      <el-input v-model.number="ruleForm.age" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submitForm(ruleFormRef)">
        Submit
      </el-button>
      <el-button @click="resetForm(ruleFormRef)">Reset</el-button>
    </el-form-item>
  </el-form>
</template>

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

import type { FormInstance, FormRules } from 'element-plus'

const ruleFormRef = ref<FormInstance>()

const checkAge = (rule: any, value: any, callback: any) => {
  if (!value) {
    return callback(new Error('Please input the age'))
  }
  setTimeout(() => {
    if (!Number.isInteger(value)) {
      callback(new Error('Please input digits'))
    } else {
      if (value < 18) {
        callback(new Error('Age must be greater than 18'))
      } else {
        callback()
      }
    }
  }, 1000)
}

const validatePass = (rule: any, value: any, callback: any) => {
  if (value === '') {
    callback(new Error('Please input the password'))
  } else {
    if (ruleForm.checkPass !== '') {
      if (!ruleFormRef.value) return
      ruleFormRef.value.validateField('checkPass')
    }
    callback()
  }
}
const validatePass2 = (rule: any, value: any, callback: any) => {
  if (value === '') {
    callback(new Error('Please input the password again'))
  } else if (value !== ruleForm.pass) {
    callback(new Error("Two inputs don't match!"))
  } else {
    callback()
  }
}

const ruleForm = reactive({
  pass: '',
  checkPass: '',
  age: '',
})

const rules = reactive<FormRules<typeof ruleForm>>({
  pass: [{ validator: validatePass, trigger: 'blur' }],
  checkPass: [{ validator: validatePass2, trigger: 'blur' }],
  age: [{ validator: checkAge, trigger: 'blur' }],
})

const submitForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.validate((valid) => {
    if (valid) {
      console.log('submit!')
    } else {
      console.log('error submit!')
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.resetFields()
}
</script>
```

隐藏源代码

TIP

自定义的校验回调函数必须被调用。 校验规则参见 [async-validator](https://github.com/yiminghe/async-validator)

## 添加/删除表单项 [​](#添加-删除表单项)

除了一次通过表单组件上的所有验证规则外. 您也可以动态地通过验证规则或删除单个表单字段的规则。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZm9ybVxuICAgIHJlZj1cImZvcm1SZWZcIlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOm1vZGVsPVwiZHluYW1pY1ZhbGlkYXRlRm9ybVwiXG4gICAgbGFiZWwtd2lkdGg9XCJhdXRvXCJcbiAgICBjbGFzcz1cImRlbW8tZHluYW1pY1wiXG4gID5cbiAgICA8ZWwtZm9ybS1pdGVtXG4gICAgICBwcm9wPVwiZW1haWxcIlxuICAgICAgbGFiZWw9XCJFbWFpbFwiXG4gICAgICA6cnVsZXM9XCJbXG4gICAgICAgIHtcbiAgICAgICAgICByZXF1aXJlZDogdHJ1ZSxcbiAgICAgICAgICBtZXNzYWdlOiAnUGxlYXNlIGlucHV0IGVtYWlsIGFkZHJlc3MnLFxuICAgICAgICAgIHRyaWdnZXI6ICdibHVyJyxcbiAgICAgICAgfSxcbiAgICAgICAge1xuICAgICAgICAgIHR5cGU6ICdlbWFpbCcsXG4gICAgICAgICAgbWVzc2FnZTogJ1BsZWFzZSBpbnB1dCBjb3JyZWN0IGVtYWlsIGFkZHJlc3MnLFxuICAgICAgICAgIHRyaWdnZXI6IFsnYmx1cicsICdjaGFuZ2UnXSxcbiAgICAgICAgfSxcbiAgICAgIF1cIlxuICAgID5cbiAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwiZHluYW1pY1ZhbGlkYXRlRm9ybS5lbWFpbFwiIC8+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbVxuICAgICAgdi1mb3I9XCIoZG9tYWluLCBpbmRleCkgaW4gZHluYW1pY1ZhbGlkYXRlRm9ybS5kb21haW5zXCJcbiAgICAgIDprZXk9XCJkb21haW4ua2V5XCJcbiAgICAgIDpsYWJlbD1cIidEb21haW4nICsgaW5kZXhcIlxuICAgICAgOnByb3A9XCInZG9tYWlucy4nICsgaW5kZXggKyAnLnZhbHVlJ1wiXG4gICAgICA6cnVsZXM9XCJ7XG4gICAgICAgIHJlcXVpcmVkOiB0cnVlLFxuICAgICAgICBtZXNzYWdlOiAnZG9tYWluIGNhbiBub3QgYmUgbnVsbCcsXG4gICAgICAgIHRyaWdnZXI6ICdibHVyJyxcbiAgICAgIH1cIlxuICAgID5cbiAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwiZG9tYWluLnZhbHVlXCIgLz5cbiAgICAgIDxlbC1idXR0b24gY2xhc3M9XCJtdC0yXCIgQGNsaWNrLnByZXZlbnQ9XCJyZW1vdmVEb21haW4oZG9tYWluKVwiPlxuICAgICAgICBEZWxldGVcbiAgICAgIDwvZWwtYnV0dG9uPlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDxlbC1mb3JtLWl0ZW0+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwic3VibWl0Rm9ybShmb3JtUmVmKVwiPlN1Ym1pdDwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJhZGREb21haW5cIj5OZXcgZG9tYWluPC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIEBjbGljaz1cInJlc2V0Rm9ybShmb3JtUmVmKVwiPlJlc2V0PC9lbC1idXR0b24+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gIDwvZWwtZm9ybT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWFjdGl2ZSwgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IEZvcm1JbnN0YW5jZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgZm9ybVJlZiA9IHJlZjxGb3JtSW5zdGFuY2U+KClcbmNvbnN0IGR5bmFtaWNWYWxpZGF0ZUZvcm0gPSByZWFjdGl2ZTx7XG4gIGRvbWFpbnM6IERvbWFpbkl0ZW1bXVxuICBlbWFpbDogc3RyaW5nXG59Pih7XG4gIGRvbWFpbnM6IFtcbiAgICB7XG4gICAgICBrZXk6IDEsXG4gICAgICB2YWx1ZTogJycsXG4gICAgfSxcbiAgXSxcbiAgZW1haWw6ICcnLFxufSlcblxuaW50ZXJmYWNlIERvbWFpbkl0ZW0ge1xuICBrZXk6IG51bWJlclxuICB2YWx1ZTogc3RyaW5nXG59XG5cbmNvbnN0IHJlbW92ZURvbWFpbiA9IChpdGVtOiBEb21haW5JdGVtKSA9PiB7XG4gIGNvbnN0IGluZGV4ID0gZHluYW1pY1ZhbGlkYXRlRm9ybS5kb21haW5zLmluZGV4T2YoaXRlbSlcbiAgaWYgKGluZGV4ICE9PSAtMSkge1xuICAgIGR5bmFtaWNWYWxpZGF0ZUZvcm0uZG9tYWlucy5zcGxpY2UoaW5kZXgsIDEpXG4gIH1cbn1cblxuY29uc3QgYWRkRG9tYWluID0gKCkgPT4ge1xuICBkeW5hbWljVmFsaWRhdGVGb3JtLmRvbWFpbnMucHVzaCh7XG4gICAga2V5OiBEYXRlLm5vdygpLFxuICAgIHZhbHVlOiAnJyxcbiAgfSlcbn1cblxuY29uc3Qgc3VibWl0Rm9ybSA9IChmb3JtRWw6IEZvcm1JbnN0YW5jZSB8IHVuZGVmaW5lZCkgPT4ge1xuICBpZiAoIWZvcm1FbCkgcmV0dXJuXG4gIGZvcm1FbC52YWxpZGF0ZSgodmFsaWQpID0+IHtcbiAgICBpZiAodmFsaWQpIHtcbiAgICAgIGNvbnNvbGUubG9nKCdzdWJtaXQhJylcbiAgICB9IGVsc2Uge1xuICAgICAgY29uc29sZS5sb2coJ2Vycm9yIHN1Ym1pdCEnKVxuICAgIH1cbiAgfSlcbn1cblxuY29uc3QgcmVzZXRGb3JtID0gKGZvcm1FbDogRm9ybUluc3RhbmNlIHwgdW5kZWZpbmVkKSA9PiB7XG4gIGlmICghZm9ybUVsKSByZXR1cm5cbiAgZm9ybUVsLnJlc2V0RmllbGRzKClcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/form/form-items.vue)_

vue

```
<template>
  <el-form
    ref="formRef"
    style="max-width: 600px"
    :model="dynamicValidateForm"
    label-width="auto"
    class="demo-dynamic"
  >
    <el-form-item
      prop="email"
      label="Email"
      :rules="[
        {
          required: true,
          message: 'Please input email address',
          trigger: 'blur',
        },
        {
          type: 'email',
          message: 'Please input correct email address',
          trigger: ['blur', 'change'],
        },
      ]"
    >
      <el-input v-model="dynamicValidateForm.email" />
    </el-form-item>
    <el-form-item
      v-for="(domain, index) in dynamicValidateForm.domains"
      :key="domain.key"
      :label="'Domain' + index"
      :prop="'domains.' + index + '.value'"
      :rules="{
        required: true,
        message: 'domain can not be null',
        trigger: 'blur',
      }"
    >
      <el-input v-model="domain.value" />
      <el-button class="mt-2" @click.prevent="removeDomain(domain)">
        Delete
      </el-button>
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submitForm(formRef)">Submit</el-button>
      <el-button @click="addDomain">New domain</el-button>
      <el-button @click="resetForm(formRef)">Reset</el-button>
    </el-form-item>
  </el-form>
</template>

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

import type { FormInstance } from 'element-plus'

const formRef = ref<FormInstance>()
const dynamicValidateForm = reactive<{
  domains: DomainItem[]
  email: string
}>({
  domains: [
    {
      key: 1,
      value: '',
    },
  ],
  email: '',
})

interface DomainItem {
  key: number
  value: string
}

const removeDomain = (item: DomainItem) => {
  const index = dynamicValidateForm.domains.indexOf(item)
  if (index !== -1) {
    dynamicValidateForm.domains.splice(index, 1)
  }
}

const addDomain = () => {
  dynamicValidateForm.domains.push({
    key: Date.now(),
    value: '',
  })
}

const submitForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.validate((valid) => {
    if (valid) {
      console.log('submit!')
    } else {
      console.log('error submit!')
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.resetFields()
}
</script>
```

隐藏源代码

## 数字类型验证 [​](#数字类型验证)

数字类型的验证需要在 `v-model` 处加上 `.number` 的修饰符，这是 Vue 自身提供的用于将绑定值转化为 number 类型的修饰符。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZm9ybVxuICAgIHJlZj1cImZvcm1SZWZcIlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOm1vZGVsPVwibnVtYmVyVmFsaWRhdGVGb3JtXCJcbiAgICBsYWJlbC13aWR0aD1cImF1dG9cIlxuICAgIGNsYXNzPVwiZGVtby1ydWxlRm9ybVwiXG4gID5cbiAgICA8ZWwtZm9ybS1pdGVtXG4gICAgICBsYWJlbD1cImFnZVwiXG4gICAgICBwcm9wPVwiYWdlXCJcbiAgICAgIDpydWxlcz1cIltcbiAgICAgICAgeyByZXF1aXJlZDogdHJ1ZSwgbWVzc2FnZTogJ2FnZSBpcyByZXF1aXJlZCcgfSxcbiAgICAgICAgeyB0eXBlOiAnbnVtYmVyJywgbWVzc2FnZTogJ2FnZSBtdXN0IGJlIGEgbnVtYmVyJyB9LFxuICAgICAgXVwiXG4gICAgPlxuICAgICAgPGVsLWlucHV0XG4gICAgICAgIHYtbW9kZWwubnVtYmVyPVwibnVtYmVyVmFsaWRhdGVGb3JtLmFnZVwiXG4gICAgICAgIHR5cGU9XCJ0ZXh0XCJcbiAgICAgICAgYXV0b2NvbXBsZXRlPVwib2ZmXCJcbiAgICAgIC8+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbT5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBAY2xpY2s9XCJzdWJtaXRGb3JtKGZvcm1SZWYpXCI+U3VibWl0PC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIEBjbGljaz1cInJlc2V0Rm9ybShmb3JtUmVmKVwiPlJlc2V0PC9lbC1idXR0b24+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gIDwvZWwtZm9ybT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWFjdGl2ZSwgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IEZvcm1JbnN0YW5jZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgZm9ybVJlZiA9IHJlZjxGb3JtSW5zdGFuY2U+KClcblxuY29uc3QgbnVtYmVyVmFsaWRhdGVGb3JtID0gcmVhY3RpdmUoe1xuICBhZ2U6ICcnLFxufSlcblxuY29uc3Qgc3VibWl0Rm9ybSA9IChmb3JtRWw6IEZvcm1JbnN0YW5jZSB8IHVuZGVmaW5lZCkgPT4ge1xuICBpZiAoIWZvcm1FbCkgcmV0dXJuXG4gIGZvcm1FbC52YWxpZGF0ZSgodmFsaWQpID0+IHtcbiAgICBpZiAodmFsaWQpIHtcbiAgICAgIGNvbnNvbGUubG9nKCdzdWJtaXQhJylcbiAgICB9IGVsc2Uge1xuICAgICAgY29uc29sZS5sb2coJ2Vycm9yIHN1Ym1pdCEnKVxuICAgIH1cbiAgfSlcbn1cblxuY29uc3QgcmVzZXRGb3JtID0gKGZvcm1FbDogRm9ybUluc3RhbmNlIHwgdW5kZWZpbmVkKSA9PiB7XG4gIGlmICghZm9ybUVsKSByZXR1cm5cbiAgZm9ybUVsLnJlc2V0RmllbGRzKClcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/form/number-validate.vue)_

vue

```
<template>
  <el-form
    ref="formRef"
    style="max-width: 600px"
    :model="numberValidateForm"
    label-width="auto"
    class="demo-ruleForm"
  >
    <el-form-item
      label="age"
      prop="age"
      :rules="[
        { required: true, message: 'age is required' },
        { type: 'number', message: 'age must be a number' },
      ]"
    >
      <el-input
        v-model.number="numberValidateForm.age"
        type="text"
        autocomplete="off"
      />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submitForm(formRef)">Submit</el-button>
      <el-button @click="resetForm(formRef)">Reset</el-button>
    </el-form-item>
  </el-form>
</template>

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

import type { FormInstance } from 'element-plus'

const formRef = ref<FormInstance>()

const numberValidateForm = reactive({
  age: '',
})

const submitForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.validate((valid) => {
    if (valid) {
      console.log('submit!')
    } else {
      console.log('error submit!')
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.resetFields()
}
</script>
```

隐藏源代码

TIP

当一个 `el-form-item` 嵌套在另一个 `el-form-item` 中时，其标签宽度将为 `0`。 如果需要可以为 `el-form-item` 单独设置 `label-width` 属性。

## 尺寸控制 [​](#尺寸控制)

表单中的所有子组件都继承了该表单的 `size` 属性。 同样，form-item 也有一个 `size` 属性。

如果希望某个表单项或某个表单组件的尺寸不同于 Form 上的 `size` 属性，直接为这个表单项或表单组件设置自己的 size 属性即可。

largedefaultsmall

LeftRightTop

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1yYWRpby1ncm91cCB2LW1vZGVsPVwic2l6ZVwiIGFyaWEtbGFiZWw9XCJzaXplIGNvbnRyb2xcIj5cbiAgICAgIDxlbC1yYWRpby1idXR0b24gdmFsdWU9XCJsYXJnZVwiPmxhcmdlPC9lbC1yYWRpby1idXR0b24+XG4gICAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwiZGVmYXVsdFwiPmRlZmF1bHQ8L2VsLXJhZGlvLWJ1dHRvbj5cbiAgICAgIDxlbC1yYWRpby1idXR0b24gdmFsdWU9XCJzbWFsbFwiPnNtYWxsPC9lbC1yYWRpby1idXR0b24+XG4gICAgPC9lbC1yYWRpby1ncm91cD5cbiAgICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cImxhYmVsUG9zaXRpb25cIiBhcmlhLWxhYmVsPVwicG9zaXRpb24gY29udHJvbFwiPlxuICAgICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cImxlZnRcIj5MZWZ0PC9lbC1yYWRpby1idXR0b24+XG4gICAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwicmlnaHRcIj5SaWdodDwvZWwtcmFkaW8tYnV0dG9uPlxuICAgICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cInRvcFwiPlRvcDwvZWwtcmFkaW8tYnV0dG9uPlxuICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gIDwvZGl2PlxuICA8YnIgLz5cbiAgPGVsLWZvcm1cbiAgICBzdHlsZT1cIm1heC13aWR0aDogNjAwcHhcIlxuICAgIDptb2RlbD1cInNpemVGb3JtXCJcbiAgICBsYWJlbC13aWR0aD1cImF1dG9cIlxuICAgIDpsYWJlbC1wb3NpdGlvbj1cImxhYmVsUG9zaXRpb25cIlxuICAgIDpzaXplPVwic2l6ZVwiXG4gID5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiQWN0aXZpdHkgbmFtZVwiPlxuICAgICAgPGVsLWlucHV0IHYtbW9kZWw9XCJzaXplRm9ybS5uYW1lXCIgLz5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiQWN0aXZpdHkgem9uZVwiPlxuICAgICAgPGVsLXNlbGVjdFxuICAgICAgICB2LW1vZGVsPVwic2l6ZUZvcm0ucmVnaW9uXCJcbiAgICAgICAgcGxhY2Vob2xkZXI9XCJwbGVhc2Ugc2VsZWN0IHlvdXIgem9uZVwiXG4gICAgICA+XG4gICAgICAgIDxlbC1vcHRpb24gbGFiZWw9XCJab25lIG9uZVwiIHZhbHVlPVwic2hhbmdoYWlcIiAvPlxuICAgICAgICA8ZWwtb3B0aW9uIGxhYmVsPVwiWm9uZSB0d29cIiB2YWx1ZT1cImJlaWppbmdcIiAvPlxuICAgICAgPC9lbC1zZWxlY3Q+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIkFjdGl2aXR5IHRpbWVcIj5cbiAgICAgIDxlbC1jb2wgOnNwYW49XCIxMVwiPlxuICAgICAgICA8ZWwtZGF0ZS1waWNrZXJcbiAgICAgICAgICB2LW1vZGVsPVwic2l6ZUZvcm0uZGF0ZTFcIlxuICAgICAgICAgIHR5cGU9XCJkYXRlXCJcbiAgICAgICAgICBhcmlhLWxhYmVsPVwiUGljayBhIGRhdGVcIlxuICAgICAgICAgIHBsYWNlaG9sZGVyPVwiUGljayBhIGRhdGVcIlxuICAgICAgICAgIHN0eWxlPVwid2lkdGg6IDEwMCVcIlxuICAgICAgICAvPlxuICAgICAgPC9lbC1jb2w+XG4gICAgICA8ZWwtY29sIGNsYXNzPVwidGV4dC1jZW50ZXJcIiA6c3Bhbj1cIjFcIiBzdHlsZT1cIm1hcmdpbjogMCAwLjVyZW1cIj4tPC9lbC1jb2w+XG4gICAgICA8ZWwtY29sIDpzcGFuPVwiMTFcIj5cbiAgICAgICAgPGVsLXRpbWUtcGlja2VyXG4gICAgICAgICAgdi1tb2RlbD1cInNpemVGb3JtLmRhdGUyXCJcbiAgICAgICAgICBhcmlhLWxhYmVsPVwiUGljayBhIHRpbWVcIlxuICAgICAgICAgIHBsYWNlaG9sZGVyPVwiUGljayBhIHRpbWVcIlxuICAgICAgICAgIHN0eWxlPVwid2lkdGg6IDEwMCVcIlxuICAgICAgICAvPlxuICAgICAgPC9lbC1jb2w+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIkFjdGl2aXR5IHR5cGVcIj5cbiAgICAgIDxlbC1jaGVja2JveC1ncm91cCB2LW1vZGVsPVwic2l6ZUZvcm0udHlwZVwiPlxuICAgICAgICA8ZWwtY2hlY2tib3gtYnV0dG9uIHZhbHVlPVwiT25saW5lIGFjdGl2aXRpZXNcIiBuYW1lPVwidHlwZVwiPlxuICAgICAgICAgIE9ubGluZSBhY3Rpdml0aWVzXG4gICAgICAgIDwvZWwtY2hlY2tib3gtYnV0dG9uPlxuICAgICAgICA8ZWwtY2hlY2tib3gtYnV0dG9uIHZhbHVlPVwiUHJvbW90aW9uIGFjdGl2aXRpZXNcIiBuYW1lPVwidHlwZVwiPlxuICAgICAgICAgIFByb21vdGlvbiBhY3Rpdml0aWVzXG4gICAgICAgIDwvZWwtY2hlY2tib3gtYnV0dG9uPlxuICAgICAgPC9lbC1jaGVja2JveC1ncm91cD5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiUmVzb3VyY2VzXCI+XG4gICAgICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInNpemVGb3JtLnJlc291cmNlXCI+XG4gICAgICAgIDxlbC1yYWRpbyBib3JkZXIgdmFsdWU9XCJTcG9uc29yXCI+U3BvbnNvcjwvZWwtcmFkaW8+XG4gICAgICAgIDxlbC1yYWRpbyBib3JkZXIgdmFsdWU9XCJWZW51ZVwiPlZlbnVlPC9lbC1yYWRpbz5cbiAgICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbT5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBAY2xpY2s9XCJvblN1Ym1pdFwiPkNyZWF0ZTwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvbj5DYW5jZWw8L2VsLWJ1dHRvbj5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgPC9lbC1mb3JtPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlYWN0aXZlLCByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgQ29tcG9uZW50U2l6ZSwgRm9ybVByb3BzIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBzaXplID0gcmVmPENvbXBvbmVudFNpemU+KCdkZWZhdWx0JylcbmNvbnN0IGxhYmVsUG9zaXRpb24gPSByZWY8Rm9ybVByb3BzWydsYWJlbFBvc2l0aW9uJ10+KCdyaWdodCcpXG5cbmNvbnN0IHNpemVGb3JtID0gcmVhY3RpdmUoe1xuICBuYW1lOiAnJyxcbiAgcmVnaW9uOiAnJyxcbiAgZGF0ZTE6ICcnLFxuICBkYXRlMjogJycsXG4gIGRlbGl2ZXJ5OiBmYWxzZSxcbiAgdHlwZTogW10sXG4gIHJlc291cmNlOiAnJyxcbiAgZGVzYzogJycsXG59KVxuXG5mdW5jdGlvbiBvblN1Ym1pdCgpIHtcbiAgY29uc29sZS5sb2coJ3N1Ym1pdCEnKVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5lbC1yYWRpby1ncm91cCB7XG4gIG1hcmdpbi1yaWdodDogMTJweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/form/size-control.vue)_

vue

```
<template>
  <div>
    <el-radio-group v-model="size" aria-label="size control">
      <el-radio-button value="large">large</el-radio-button>
      <el-radio-button value="default">default</el-radio-button>
      <el-radio-button value="small">small</el-radio-button>
    </el-radio-group>
    <el-radio-group v-model="labelPosition" aria-label="position control">
      <el-radio-button value="left">Left</el-radio-button>
      <el-radio-button value="right">Right</el-radio-button>
      <el-radio-button value="top">Top</el-radio-button>
    </el-radio-group>
  </div>
  <br />
  <el-form
    style="max-width: 600px"
    :model="sizeForm"
    label-width="auto"
    :label-position="labelPosition"
    :size="size"
  >
    <el-form-item label="Activity name">
      <el-input v-model="sizeForm.name" />
    </el-form-item>
    <el-form-item label="Activity zone">
      <el-select
        v-model="sizeForm.region"
        placeholder="please select your zone"
      >
        <el-option label="Zone one" value="shanghai" />
        <el-option label="Zone two" value="beijing" />
      </el-select>
    </el-form-item>
    <el-form-item label="Activity time">
      <el-col :span="11">
        <el-date-picker
          v-model="sizeForm.date1"
          type="date"
          aria-label="Pick a date"
          placeholder="Pick a date"
          style="width: 100%"
        />
      </el-col>
      <el-col class="text-center" :span="1" style="margin: 0 0.5rem">-</el-col>
      <el-col :span="11">
        <el-time-picker
          v-model="sizeForm.date2"
          aria-label="Pick a time"
          placeholder="Pick a time"
          style="width: 100%"
        />
      </el-col>
    </el-form-item>
    <el-form-item label="Activity type">
      <el-checkbox-group v-model="sizeForm.type">
        <el-checkbox-button value="Online activities" name="type">
          Online activities
        </el-checkbox-button>
        <el-checkbox-button value="Promotion activities" name="type">
          Promotion activities
        </el-checkbox-button>
      </el-checkbox-group>
    </el-form-item>
    <el-form-item label="Resources">
      <el-radio-group v-model="sizeForm.resource">
        <el-radio border value="Sponsor">Sponsor</el-radio>
        <el-radio border value="Venue">Venue</el-radio>
      </el-radio-group>
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="onSubmit">Create</el-button>
      <el-button>Cancel</el-button>
    </el-form-item>
  </el-form>
</template>

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

import type { ComponentSize, FormProps } from 'element-plus'

const size = ref<ComponentSize>('default')
const labelPosition = ref<FormProps['labelPosition']>('right')

const sizeForm = reactive({
  name: '',
  region: '',
  date1: '',
  date2: '',
  delivery: false,
  type: [],
  resource: '',
  desc: '',
})

function onSubmit() {
  console.log('submit!')
}
</script>

<style>
.el-radio-group {
  margin-right: 12px;
}
</style>
```

隐藏源代码

## 无障碍 [​](#无障碍)

当在 `el-form-item` 内只有一个输入框（或相关的控制部件，如选择或复选框），表单项的标签将自动附加在那个输入框上。 如果 `el-form-item`内有多个 input，则表单项会被设置成 [WAI-ARIA](https://www.w3.org/WAI/standards-guidelines/aria/) [组](https://www.w3.org/TR/wai-aria/#group) 的 role。 在这种情况下，需要手动给每个 input 指定访问标签。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZm9ybSBsYWJlbC1wb3NpdGlvbj1cImxlZnRcIiBsYWJlbC13aWR0aD1cImF1dG9cIiBzdHlsZT1cIm1heC13aWR0aDogNjAwcHhcIj5cbiAgICA8ZWwtc3BhY2UgZmlsbD5cbiAgICAgIDxlbC1hbGVydCB0eXBlPVwiaW5mb1wiIHNob3ctaWNvbiA6Y2xvc2FibGU9XCJmYWxzZVwiPlxuICAgICAgICA8cD5cIkZ1bGwgTmFtZVwiIGxhYmVsIGlzIGF1dG9tYXRpY2FsbHkgYXR0YWNoZWQgdG8gdGhlIGlucHV0OjwvcD5cbiAgICAgIDwvZWwtYWxlcnQ+XG4gICAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiRnVsbCBOYW1lXCI+XG4gICAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwiZm9ybUFjY2Vzc2liaWxpdHkuZnVsbE5hbWVcIiAvPlxuICAgICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPC9lbC1zcGFjZT5cbiAgICA8ZWwtc3BhY2UgZmlsbD5cbiAgICAgIDxlbC1hbGVydCB0eXBlPVwiaW5mb1wiIHNob3ctaWNvbiA6Y2xvc2FibGU9XCJmYWxzZVwiPlxuICAgICAgICA8cD5cbiAgICAgICAgICBcIllvdXIgSW5mb3JtYXRpb25cIiBzZXJ2ZXMgYXMgYSBsYWJlbCBmb3IgdGhlIGdyb3VwIG9mIGlucHV0cy4gPGJyIC8+XG4gICAgICAgICAgWW91IG11c3Qgc3BlY2lmeSBsYWJlbHMgb24gdGhlIGluZGl2aWRhbCBpbnB1dHMuIFBsYWNlaG9sZGVycyBhcmUgbm90XG4gICAgICAgICAgcmVwbGFjZW1lbnRzIGZvciB1c2luZyB0aGUgXCJsYWJlbFwiIGF0dHJpYnV0ZS5cbiAgICAgICAgPC9wPlxuICAgICAgPC9lbC1hbGVydD5cbiAgICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJZb3VyIEluZm9ybWF0aW9uXCI+XG4gICAgICAgIDxlbC1yb3cgOmd1dHRlcj1cIjIwXCI+XG4gICAgICAgICAgPGVsLWNvbCA6c3Bhbj1cIjEyXCI+XG4gICAgICAgICAgICA8ZWwtaW5wdXRcbiAgICAgICAgICAgICAgdi1tb2RlbD1cImZvcm1BY2Nlc3NpYmlsaXR5LmZpcnN0TmFtZVwiXG4gICAgICAgICAgICAgIGFyaWEtbGFiZWw9XCJGaXJzdCBOYW1lXCJcbiAgICAgICAgICAgICAgcGxhY2Vob2xkZXI9XCJGaXJzdCBOYW1lXCJcbiAgICAgICAgICAgIC8+XG4gICAgICAgICAgPC9lbC1jb2w+XG4gICAgICAgICAgPGVsLWNvbCA6c3Bhbj1cIjEyXCI+XG4gICAgICAgICAgICA8ZWwtaW5wdXRcbiAgICAgICAgICAgICAgdi1tb2RlbD1cImZvcm1BY2Nlc3NpYmlsaXR5Lmxhc3ROYW1lXCJcbiAgICAgICAgICAgICAgYXJpYS1sYWJlbD1cIkxhc3QgTmFtZVwiXG4gICAgICAgICAgICAgIHBsYWNlaG9sZGVyPVwiTGFzdCBOYW1lXCJcbiAgICAgICAgICAgIC8+XG4gICAgICAgICAgPC9lbC1jb2w+XG4gICAgICAgIDwvZWwtcm93PlxuICAgICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPC9lbC1zcGFjZT5cbiAgPC9lbC1mb3JtPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlYWN0aXZlIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBmb3JtQWNjZXNzaWJpbGl0eSA9IHJlYWN0aXZlKHtcbiAgZnVsbE5hbWU6ICcnLFxuICBmaXJzdE5hbWU6ICcnLFxuICBsYXN0TmFtZTogJycsXG59KVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/form/accessibility.vue)_

vue

```
<template>
  <el-form label-position="left" label-width="auto" style="max-width: 600px">
    <el-space fill>
      <el-alert type="info" show-icon :closable="false">
        <p>"Full Name" label is automatically attached to the input:</p>
      </el-alert>
      <el-form-item label="Full Name">
        <el-input v-model="formAccessibility.fullName" />
      </el-form-item>
    </el-space>
    <el-space fill>
      <el-alert type="info" show-icon :closable="false">
        <p>
          "Your Information" serves as a label for the group of inputs. <br />
          You must specify labels on the individal inputs. Placeholders are not
          replacements for using the "label" attribute.
        </p>
      </el-alert>
      <el-form-item label="Your Information">
        <el-row :gutter="20">
          <el-col :span="12">
            <el-input
              v-model="formAccessibility.firstName"
              aria-label="First Name"
              placeholder="First Name"
            />
          </el-col>
          <el-col :span="12">
            <el-input
              v-model="formAccessibility.lastName"
              aria-label="Last Name"
              placeholder="Last Name"
            />
          </el-col>
        </el-row>
      </el-form-item>
    </el-space>
  </el-form>
</template>

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

const formAccessibility = reactive({
  fullName: '',
  firstName: '',
  lastName: '',
})
</script>
```

隐藏源代码

## Form API [​](#form-api)

### Form Attributes [​](#form-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model | 表单数据对象 | `object` | — |
| rules | 表单验证规则 | `object` | — |
| inline | 行内表单模式 | `boolean` | false |
| label-position | 表单域标签的位置， 当设置为 `left` 或 `right` 时，则也需要设置 `label-width` 属性 | `enum` | right |
| label-width | 标签的长度，例如 `'50px'`。 作为 Form 直接子元素的 form-item 会继承该值。 可以使用 `auto`。 | `string` / `number` | '' |
| label-suffix | 表单域标签的后缀 | `string` | '' |
| hide-required-asterisk | 是否隐藏必填字段标签旁边的红色星号。 | `boolean` | false |
| require-asterisk-position | 星号的位置。 | `enum` | left |
| show-message | 是否显示校验错误信息 | `boolean` | true |
| inline-message | 是否以行内形式展示校验信息 | `boolean` | false |
| status-icon | 是否在输入框中显示校验结果反馈图标 | `boolean` | false |
| validate-on-rule-change | 是否在 `rules` 属性改变后立即触发一次验证 | `boolean` | true |
| size | 用于控制该表单内组件的尺寸 | `enum` | — |
| disabled | 是否禁用该表单内的所有组件。 在 2.12.0 以前，如果设置为 `true`，它将覆盖内部组件的 `disabled` 属性。 在 2.12.0 之后，内部组件的配置优先。 | `boolean` | false |
| scroll-to-error | 当校验失败时，滚动到第一个错误表单项 | `boolean` | false |
| scroll-into-view-options 2.3.2 | 当校验有失败结果时，滚动到第一个失败的表单项目 可通过 [scrollIntoView](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) 配置 | `object` / `boolean` | true |

### Form Events [​](#form-events)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| validate | 任一表单项被校验后触发 | `Function` |

### Form Slots [​](#form-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | FormItem |

### Form Exposes [​](#form-exposes)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| validate | 对整个表单的内容进行验证。 接收一个回调函数，或返回 `Promise`。 | `Function` |
| validateField | 验证具体的某个字段。 | `Function` |
| resetFields | 重置该表单项，将其值重置为初始值，并移除校验结果 | `Function` |
| scrollToField | 滚动到指定的字段 | `Function` |
| clearValidate | 清理某个字段的表单验证信息。 | `Function` |
| fields 2.7.3 | 获取所有字段的 context | `array` |
| getField 2.10.2 | 获取字段的 context | `Function` |
| setInitialValues 2.13.1 | 设置表单字段的初始值。 当调用 `resetFields` 时，字段将重置为这些值。 | `Function` |

## FormItem API [​](#formitem-api)

### FormItem Attributes [​](#formitem-attributes)

| 属性名 | 说明 | 类型 | Default |
| --- | --- | --- | --- |
| prop | `model` 的键名。 它可以是属性的路径（如 `a.b.0` 或 `['a', 'b', '0']`）。 在使用了 `validate`、`resetFields` 的方法时，该属性是必填的。 | `string` / `string[]` | — |
| label | 标签文本 | `string` | — |
| label-position 2.7.7 | 表单域标签的位置， 当设置为 `left` 或 `right` 时，则也需要设置 `label-width` 属性 默认会继承 `Form`的`label-position` | `enum` | '' |
| label-width | 标签宽度，例如 `'50px'`。 可以使用 `auto`。 | `string` / `number` | — |
| required | 是否为必填项，如不设置，则会根据校验规则确认 | `boolean` | — |
| rules | 表单验证规则, 具体配置见[下表](#formitemrule), 更多内容可以参考[async-validator](https://github.com/yiminghe/async-validator) | `object` | — |
| error | 表单域验证错误时的提示信息。设置该值会导致表单验证状态变为 error，并显示该错误信息。 | `string` | — |
| show-message | 是否显示校验错误信息 | `boolean` | true |
| inline-message | 是否在行内显示校验信息 | `boolean` | false |
| size | 用于控制该表单域下组件的默认尺寸 | `enum` | — |
| for | 和原生标签相同能力 | `string` | — |
| validate-status | formitem 校验的状态 | `enum` | — |

#### FormItemRule [​](#formitemrule)

| 名称 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| trigger | 验证逻辑的触发方式 | `enum` | — |

TIP

如果您不想根据输入事件触发验证器， 在相应的输入类型组件上设置 `validate-event` 属性为 `false` (`<el-input>`, `<el-radio>`, `<el-select>`, . ……).

### FormItem Slots [​](#formitem-slots)

| 插槽名 | 说明 | 类型 |
| --- | --- | --- |
| default | 表单的内容。 | — |
| label | 标签位置显示的内容 | `object` |
| error | 验证错误信息的显示内容 | `object` |

### FormItem Exposes [​](#formitem-exposes)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| size | 表单项大小 | `object` |
| validateMessage | 校验消息 | `object` |
| validateState | 校验状态 | `object` |
| validate | 验证表单项 | `Function` |
| resetField | 对该表单项进行重置，将其值重置为初始值并移除校验结果 | `Function` |
| clearValidate | 移除该表单项的校验结果 | `Function` |
| setInitialValue 2.13.1 | 设置表单字段的初始值。 当调用 `resetFields` 时，字段将重置为这些值。 | `Function` |

## 类型声明 [​](#类型声明)

显示类型声明

ts

```
type Arrayable<T> = T | T[]

type FormValidationResult = Promise<boolean>

// ValidateFieldsError: see [async-validator](https://github.com/yiminghe/async-validator/blob/master/src/interface.ts)
type FormValidateCallback = (
  isValid: boolean,
  invalidFields?: ValidateFieldsError
) => Promise<void> | void

// RuleItem: see [async-validator](https://github.com/yiminghe/async-validator/blob/master/src/interface.ts)
interface FormItemRule extends RuleItem {
  trigger?: Arrayable<string>
}

type Primitive = null | undefined | string | number | boolean | symbol | bigint
type BrowserNativeObject = Date | FileList | File | Blob | RegExp
type IsTuple<T extends ReadonlyArray<any>> = number extends T['length']
  ? false
  : true
type ArrayMethodKey = keyof any[]
type TupleKey<T extends ReadonlyArray<any>> = Exclude<keyof T, ArrayMethodKey>
type ArrayKey = number
type PathImpl<K extends string | number, V> = V extends
  | Primitive
  | BrowserNativeObject
  ? `${K}`
  : `${K}` | `${K}.${Path<V>}`
type Path<T> =
  T extends ReadonlyArray<infer V>
    ? IsTuple<T> extends true
      ? {
          [K in TupleKey<T>]-?: PathImpl<Exclude<K, symbol>, T[K]>
        }[TupleKey<T>]
      : PathImpl<ArrayKey, V>
    : {
        [K in keyof T]-?: PathImpl<Exclude<K, symbol>, T[K]>
      }[keyof T]
type FieldPath<T> = T extends object ? Path<T> : never
// MaybeRef: see [@vueuse/core](https://github.com/vueuse/vueuse/blob/main/packages/shared/utils/types.ts)
// UnwrapRef: see [vue](https://github.com/vuejs/core/blob/main/packages/reactivity/src/ref.ts)
type FormRules<T extends MaybeRef<Record<string, any> | string> = string> =
  Partial<
    Record<
      UnwrapRef<T> extends string ? UnwrapRef<T> : FieldPath<UnwrapRef<T>>,
      Arrayable<FormItemRule>
    >
  >

type FormItemValidateState = (typeof formItemValidateStates)[number]
type FormItemProps = ExtractPropTypes<typeof formItemProps>

type FormItemContext = FormItemProps & {
  $el: HTMLDivElement | undefined
  size: ComponentSize
  validateMessage: string
  validateState: FormItemValidateState
  isGroup: boolean
  labelId: string
  inputIds: string[]
  hasLabel: boolean
  fieldValue: any
  propString: string
  addInputId: (id: string) => void
  removeInputId: (id: string) => void
  validate: (
    trigger: string,
    callback?: FormValidateCallback
  ) => FormValidationResult
  resetField(): void
  clearValidate(): void
  setInitialValue: (value: any) => void
}
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/form) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/form.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/form.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/53589602?v=4&size=64)](https://github.com/l246804)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/24290011?v=4&size=64)](https://github.com/xingyixiang)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/57785259?v=4&size=64)](https://github.com/w2xi)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/31850793?v=4&size=64)](https://github.com/ModyQyW)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/32354856?v=4&size=64)](https://github.com/baiwusanyu-c)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/20052395?v=4&size=64)](https://github.com/guizoxxv)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/52363975?v=4&size=64)](https://github.com/wangbincyzj)[![](https://avatars.githubusercontent.com/u/7877834?v=4&size=64)](https://github.com/921)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/74746021?v=4&size=64)](https://github.com/xing403)[![](https://avatars.githubusercontent.com/u/35091020?v=4&size=64)](https://github.com/zzh948498)[![](https://avatars.githubusercontent.com/u/3362033?v=4&size=64)](https://github.com/cloudcome)[![](https://avatars.githubusercontent.com/u/47593280?v=4&size=64)](https://github.com/Xaw-xu)[![](https://avatars.githubusercontent.com/u/28420052?v=4&size=64)](https://github.com/Jackie-llv)[![](https://avatars.githubusercontent.com/u/46640919?v=4&size=64)](https://github.com/tiansQAQ)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/45762373?v=4&size=64)](https://github.com/koalaniu)[![](https://avatars.githubusercontent.com/u/1744129?v=4&size=64)](https://github.com/hminghe)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/17268607?v=4&size=64)](https://github.com/LYlanfeng)[![](https://avatars.githubusercontent.com/u/22659150?v=4&size=64)](https://github.com/ntnyq)[![](https://avatars.githubusercontent.com/u/83811542?v=4&size=64)](https://github.com/duyidao)[![](https://avatars.githubusercontent.com/u/57179957?v=4&size=64)](https://github.com/yeonjulee1005)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/18051955?v=4&size=64)](https://github.com/qige2016)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/113576575?v=4&size=64)](https://github.com/lkdhy)[![](https://avatars.githubusercontent.com/u/54520846?v=4&size=64)](https://github.com/manyuemeiquqi)[![](https://avatars.githubusercontent.com/u/38113445?v=4&size=64)](https://github.com/assasin0076)[![](https://avatars.githubusercontent.com/u/19164948?v=4&size=64)](https://github.com/achin797)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/28811207?v=4&size=64)](https://github.com/fanhefeng)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/13634675?v=4&size=64)](https://github.com/virgosoy)[![](https://avatars.githubusercontent.com/u/9958583?v=4&size=64)](https://github.com/Otto-J)[![](https://avatars.githubusercontent.com/u/20987775?v=4&size=64)](https://github.com/cbbfcd)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/293591?v=4&size=64)](https://github.com/digitalkaoz)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)[![](https://avatars.githubusercontent.com/u/9622779?v=4&size=64)](https://github.com/taosher)

[DateTime Picker 日期时间选择器](https://element-plus.org/zh-CN/component/datetime-picker)

[Input 输入框](https://element-plus.org/zh-CN/component/input)




---
## [form/input] Input 输入框
> 官方文档: https://element-plus.org/zh-CN/component/input.html

---

# Input 输入框 [​](#input-输入框)

更新日志待解决

48

通过鼠标或键盘输入字符

## 基础用法 [​](#基础用法)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQgdi1tb2RlbD1cImlucHV0XCIgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIiBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBpbnB1dCA9IHJlZignJylcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/basic.vue)_

vue

```
<template>
  <el-input v-model="input" style="width: 240px" placeholder="Please input" />
</template>

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

const input = ref('')
</script>
```

隐藏源代码

## 禁用状态 [​](#禁用状态)

通过 `disabled` 属性指定是否禁用 input 组件

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXRcbiAgICB2LW1vZGVsPVwiaW5wdXRcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICBkaXNhYmxlZFxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGlucHV0ID0gcmVmKCcnKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/disabled.vue)_

vue

```
<template>
  <el-input
    v-model="input"
    style="width: 240px"
    disabled
    placeholder="Please input"
  />
</template>

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

const input = ref('')
</script>
```

隐藏源代码

## 一键清空 [​](#一键清空)

使用`clearable`属性即可得到一个可一键清空的输入框 在版本 2.13.4 之后，Input 的 textarea 类型也支持 clearable 功能。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiaW5wdXQtZ3JvdXBcIj5cbiAgICA8ZWwtaW5wdXRcbiAgICAgIHYtbW9kZWw9XCJpbnB1dFwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgICBjbGVhcmFibGVcbiAgICAvPlxuICAgIDxlbC1pbnB1dFxuICAgICAgdi1tb2RlbD1cInRleHRhcmVhSW5wdXRcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgaW5wdXRcIlxuICAgICAgdHlwZT1cInRleHRhcmVhXCJcbiAgICAgIGNsZWFyYWJsZVxuICAgIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5wdXQgPSByZWYoJycpXG5jb25zdCB0ZXh0YXJlYUlucHV0ID0gcmVmKCcnKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uaW5wdXQtZ3JvdXAge1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBnYXA6IDFlbTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/clearable.vue)_

vue

```
<template>
  <div class="input-group">
    <el-input
      v-model="input"
      style="width: 240px"
      placeholder="Please input"
      clearable
    />
    <el-input
      v-model="textareaInput"
      style="width: 240px"
      placeholder="Please input"
      type="textarea"
      clearable
    />
  </div>
</template>

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

const input = ref('')
const textareaInput = ref('')
</script>

<style scoped>
.input-group {
  display: flex;
  align-items: center;
  gap: 1em;
}
</style>
```

隐藏源代码

## 自定义清除图标2.11.0 [​](#自定义清除图标)

你可以通过`clear-icon`属性自定义清除图标

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiaW5wdXQtZ3JvdXBcIj5cbiAgICA8ZWwtaW5wdXRcbiAgICAgIHYtbW9kZWw9XCJpbnB1dFwiXG4gICAgICBjbGVhcmFibGVcbiAgICAgIDpjbGVhci1pY29uPVwiQ2xvc2VCb2xkXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiQ3VzdG9tIGNsZWFyIGljb25cIlxuICAgIC8+XG4gICAgPGVsLWlucHV0XG4gICAgICB2LW1vZGVsPVwidGV4dGFyZWFJbnB1dFwiXG4gICAgICBjbGVhcmFibGVcbiAgICAgIDpjbGVhci1pY29uPVwiQ2xvc2VCb2xkXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiQ3VzdG9tIGNsZWFyIGljb25cIlxuICAgICAgdHlwZT1cInRleHRhcmVhXCJcbiAgICAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBDbG9zZUJvbGQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgaW5wdXQgPSByZWYoJ0N1c3RvbSBjbGVhciBpY29uJylcbmNvbnN0IHRleHRhcmVhSW5wdXQgPSByZWYoJ0N1c3RvbSBjbGVhciBpY29uJylcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmlucHV0LWdyb3VwIHtcbiAgZGlzcGxheTogZmxleDtcbiAgZmxleC1kaXJlY3Rpb246IGNvbHVtbjtcbiAgZ2FwOiAxZW07XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/clear-icon.vue)_

vue

```
<template>
  <div class="input-group">
    <el-input
      v-model="input"
      clearable
      :clear-icon="CloseBold"
      placeholder="Custom clear icon"
    />
    <el-input
      v-model="textareaInput"
      clearable
      :clear-icon="CloseBold"
      placeholder="Custom clear icon"
      type="textarea"
    />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { CloseBold } from '@element-plus/icons-vue'

const input = ref('Custom clear icon')
const textareaInput = ref('Custom clear icon')
</script>

<style scoped>
.input-group {
  display: flex;
  flex-direction: column;
  gap: 1em;
}
</style>
```

隐藏源代码

## 格式化 [​](#格式化)

在 `formatter`的情况下显示值，我们通常同时使用 `parser`

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXRcbiAgICB2LW1vZGVsPVwiaW5wdXRcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgOmZvcm1hdHRlcj1cIih2YWx1ZSkgPT4gYCQgJHt2YWx1ZX1gLnJlcGxhY2UoL1xcQig/PShcXGR7M30pKyg/IVxcZCkpL2csICcsJylcIlxuICAgIDpwYXJzZXI9XCIodmFsdWUpID0+IHZhbHVlLnJlcGxhY2UoL1xcJFxccz98KCwqKS9nLCAnJylcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5wdXQgPSByZWYoJycpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/formatter.vue)_

vue

```
<template>
  <el-input
    v-model="input"
    style="width: 240px"
    placeholder="Please input"
    :formatter="(value) => `$ ${value}`.replace(/\B(?=(\d{3})+(?!\d))/g, ',')"
    :parser="(value) => value.replace(/\$\s?|(,*)/g, '')"
  />
</template>

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

const input = ref('')
</script>
```

隐藏源代码

## 密码框 [​](#密码框)

使用 `show-password` 属性即可得到一个可切换显示隐藏的密码框 自 2.13.6 起，支持使用 `password-icon` 插槽覆盖默认图标。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiaW5wdXQtZ3JvdXBcIj5cbiAgICA8ZWwtaW5wdXRcbiAgICAgIHYtbW9kZWw9XCJpbnB1dFwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICB0eXBlPVwicGFzc3dvcmRcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgaW5wdXQgcGFzc3dvcmRcIlxuICAgICAgc2hvdy1wYXNzd29yZFxuICAgIC8+XG4gICAgPGVsLWlucHV0XG4gICAgICB2LW1vZGVsPVwiaW5wdXRcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgdHlwZT1cInBhc3N3b3JkXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0IHBhc3N3b3JkXCJcbiAgICAgIHNob3ctcGFzc3dvcmRcbiAgICA+XG4gICAgICA8dGVtcGxhdGUgI3Bhc3N3b3JkLWljb249XCJ7IHZpc2libGUgfVwiPlxuICAgICAgICA8ZWwtaWNvbiA6c2l6ZT1cIjE2XCI+XG4gICAgICAgICAgPFVubG9jayB2LWlmPVwidmlzaWJsZVwiIC8+XG4gICAgICAgICAgPExvY2sgdi1lbHNlIC8+XG4gICAgICAgIDwvZWwtaWNvbj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1pbnB1dD5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgTG9jaywgVW5sb2NrIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmNvbnN0IGlucHV0ID0gcmVmKCcnKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uaW5wdXQtZ3JvdXAge1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBnYXA6IDFlbTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/password.vue)_

vue

```
<template>
  <div class="input-group">
    <el-input
      v-model="input"
      style="width: 240px"
      type="password"
      placeholder="Please input password"
      show-password
    />
    <el-input
      v-model="input"
      style="width: 240px"
      type="password"
      placeholder="Please input password"
      show-password
    >
      <template #password-icon="{ visible }">
        <el-icon :size="16">
          <Unlock v-if="visible" />
          <Lock v-else />
        </el-icon>
      </template>
    </el-input>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Lock, Unlock } from '@element-plus/icons-vue'

const input = ref('')
</script>

<style scoped>
.input-group {
  display: flex;
  align-items: center;
  gap: 1em;
}
</style>
```

隐藏源代码

## 带图标的输入框 [​](#带图标的输入框)

带有图标标记输入类型

要在输入框中添加图标，你可以简单地使用 `prefix-icon` 和 `suffix-icon` 属性。 另外， `prefix` 和 `suffix` 命名的插槽也能正常工作。

Using attributes

Using slots

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbnB1dC13aXRoLWljb25cIj5cbiAgICA8ZGl2IGNsYXNzPVwiaW5wdXQtZ3JvdXBcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwibGFiZWxcIj5Vc2luZyBhdHRyaWJ1dGVzPC9zcGFuPlxuICAgICAgPGRpdiBjbGFzcz1cImlucHV0LWNvbnRhaW5lclwiPlxuICAgICAgICA8ZWwtaW5wdXRcbiAgICAgICAgICB2LW1vZGVsPVwiaW5wdXQxXCJcbiAgICAgICAgICBjbGFzcz1cInJlc3BvbnNpdmUtaW5wdXRcIlxuICAgICAgICAgIHBsYWNlaG9sZGVyPVwiUGljayBhIGRhdGVcIlxuICAgICAgICAgIDpzdWZmaXgtaWNvbj1cIkNhbGVuZGFyXCJcbiAgICAgICAgLz5cbiAgICAgICAgPGVsLWlucHV0XG4gICAgICAgICAgdi1tb2RlbD1cImlucHV0MlwiXG4gICAgICAgICAgY2xhc3M9XCJyZXNwb25zaXZlLWlucHV0XCJcbiAgICAgICAgICBwbGFjZWhvbGRlcj1cIlR5cGUgc29tZXRoaW5nXCJcbiAgICAgICAgICA6cHJlZml4LWljb249XCJTZWFyY2hcIlxuICAgICAgICAvPlxuICAgICAgPC9kaXY+XG4gICAgPC9kaXY+XG4gICAgPGRpdiBjbGFzcz1cImlucHV0LWdyb3VwXCI+XG4gICAgICA8c3BhbiBjbGFzcz1cImxhYmVsXCI+VXNpbmcgc2xvdHM8L3NwYW4+XG4gICAgICA8ZGl2IGNsYXNzPVwiaW5wdXQtY29udGFpbmVyXCI+XG4gICAgICAgIDxlbC1pbnB1dFxuICAgICAgICAgIHYtbW9kZWw9XCJpbnB1dDNcIlxuICAgICAgICAgIGNsYXNzPVwicmVzcG9uc2l2ZS1pbnB1dFwiXG4gICAgICAgICAgcGxhY2Vob2xkZXI9XCJQaWNrIGEgZGF0ZVwiXG4gICAgICAgID5cbiAgICAgICAgICA8dGVtcGxhdGUgI3N1ZmZpeD5cbiAgICAgICAgICAgIDxlbC1pY29uIGNsYXNzPVwiZWwtaW5wdXRfX2ljb25cIj48Y2FsZW5kYXIgLz48L2VsLWljb24+XG4gICAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPC9lbC1pbnB1dD5cbiAgICAgICAgPGVsLWlucHV0XG4gICAgICAgICAgdi1tb2RlbD1cImlucHV0NFwiXG4gICAgICAgICAgY2xhc3M9XCJyZXNwb25zaXZlLWlucHV0XCJcbiAgICAgICAgICBwbGFjZWhvbGRlcj1cIlR5cGUgc29tZXRoaW5nXCJcbiAgICAgICAgPlxuICAgICAgICAgIDx0ZW1wbGF0ZSAjcHJlZml4PlxuICAgICAgICAgICAgPGVsLWljb24gY2xhc3M9XCJlbC1pbnB1dF9faWNvblwiPjxzZWFyY2ggLz48L2VsLWljb24+XG4gICAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPC9lbC1pbnB1dD5cbiAgICAgIDwvZGl2PlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBDYWxlbmRhciwgU2VhcmNoIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmNvbnN0IGlucHV0MSA9IHJlZignJylcbmNvbnN0IGlucHV0MiA9IHJlZignJylcbmNvbnN0IGlucHV0MyA9IHJlZignJylcbmNvbnN0IGlucHV0NCA9IHJlZignJylcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8taW5wdXQtd2l0aC1pY29uIHtcbiAgd2lkdGg6IDEwMCU7XG59XG5cbi5pbnB1dC1ncm91cCB7XG4gIG1hcmdpbi1ib3R0b206IDEuNXJlbTtcbn1cblxuLmxhYmVsIHtcbiAgZGlzcGxheTogYmxvY2s7XG4gIG1hcmdpbi1ib3R0b206IDFyZW07XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXJlZ3VsYXIpO1xufVxuXG4uaW5wdXQtY29udGFpbmVyIHtcbiAgZGlzcGxheTogZmxleDtcbiAgZ2FwOiAxcmVtO1xuICBmbGV4LXdyYXA6IHdyYXA7XG59XG5cbi5yZXNwb25zaXZlLWlucHV0IHtcbiAgd2lkdGg6IDI0MHB4O1xufVxuXG5AbWVkaWEgKG1heC13aWR0aDogNzY4cHgpIHtcbiAgLmlucHV0LWNvbnRhaW5lciB7XG4gICAgZmxleC1kaXJlY3Rpb246IGNvbHVtbjtcbiAgICBnYXA6IDFyZW07XG4gIH1cblxuICAucmVzcG9uc2l2ZS1pbnB1dCB7XG4gICAgd2lkdGg6IDEwMCU7XG4gIH1cbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/with-icon.vue)_

vue

```
<template>
  <div class="demo-input-with-icon">
    <div class="input-group">
      <span class="label">Using attributes</span>
      <div class="input-container">
        <el-input
          v-model="input1"
          class="responsive-input"
          placeholder="Pick a date"
          :suffix-icon="Calendar"
        />
        <el-input
          v-model="input2"
          class="responsive-input"
          placeholder="Type something"
          :prefix-icon="Search"
        />
      </div>
    </div>
    <div class="input-group">
      <span class="label">Using slots</span>
      <div class="input-container">
        <el-input
          v-model="input3"
          class="responsive-input"
          placeholder="Pick a date"
        >
          <template #suffix>
            <el-icon class="el-input__icon"><calendar /></el-icon>
          </template>
        </el-input>
        <el-input
          v-model="input4"
          class="responsive-input"
          placeholder="Type something"
        >
          <template #prefix>
            <el-icon class="el-input__icon"><search /></el-icon>
          </template>
        </el-input>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Calendar, Search } from '@element-plus/icons-vue'

const input1 = ref('')
const input2 = ref('')
const input3 = ref('')
const input4 = ref('')
</script>

<style scoped>
.demo-input-with-icon {
  width: 100%;
}

.input-group {
  margin-bottom: 1.5rem;
}

.label {
  display: block;
  margin-bottom: 1rem;
  color: var(--el-text-color-regular);
}

.input-container {
  display: flex;
  gap: 1rem;
  flex-wrap: wrap;
}

.responsive-input {
  width: 240px;
}

@media (max-width: 768px) {
  .input-container {
    flex-direction: column;
    gap: 1rem;
  }

  .responsive-input {
    width: 100%;
  }
}
</style>
```

隐藏源代码

## 文本域 [​](#文本域)

用于输入多行文本信息可缩放的输入框。 添加 `type="textarea"` 属性来将 `input` 元素转换为原生的 `textarea` 元素。

文本域高度可通过 `rows` 属性控制

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXRcbiAgICB2LW1vZGVsPVwidGV4dGFyZWFcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICA6cm93cz1cIjJcIlxuICAgIHR5cGU9XCJ0ZXh0YXJlYVwiXG4gICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgaW5wdXRcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdGV4dGFyZWEgPSByZWYoJycpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/textarea.vue)_

vue

```
<template>
  <el-input
    v-model="textarea"
    style="width: 240px"
    :rows="2"
    type="textarea"
    placeholder="Please input"
  />
</template>

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

const textarea = ref('')
</script>
```

隐藏源代码

## 自适应文本域 [​](#自适应文本域)

设置文字输入类型的 `autosize` 属性使得根据内容自动调整的高度。 你可以给 `autosize` 提供一个包含有最大和最小高度的对象，让输入框自动调整。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXRcbiAgICB2LW1vZGVsPVwidGV4dGFyZWExXCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgYXV0b3NpemVcbiAgICB0eXBlPVwidGV4dGFyZWFcIlxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgLz5cbiAgPGRpdiBzdHlsZT1cIm1hcmdpbjogMjBweCAwXCIgLz5cbiAgPGVsLWlucHV0XG4gICAgdi1tb2RlbD1cInRleHRhcmVhMlwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgIDphdXRvc2l6ZT1cInsgbWluUm93czogMiwgbWF4Um93czogNCB9XCJcbiAgICB0eXBlPVwidGV4dGFyZWFcIlxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHRleHRhcmVhMSA9IHJlZignJylcbmNvbnN0IHRleHRhcmVhMiA9IHJlZignJylcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/auto-sizing-textarea.vue)_

vue

```
<template>
  <el-input
    v-model="textarea1"
    style="width: 240px"
    autosize
    type="textarea"
    placeholder="Please input"
  />
  <div style="margin: 20px 0" />
  <el-input
    v-model="textarea2"
    style="width: 240px"
    :autosize="{ minRows: 2, maxRows: 4 }"
    type="textarea"
    placeholder="Please input"
  />
</template>

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

const textarea1 = ref('')
const textarea2 = ref('')
</script>
```

隐藏源代码

## 复合型输入框 [​](#复合型输入框)

可以在输入框中前置或后置一个元素，通常是标签或按钮。

可通过 `slot` 来指定在 Input 中分发的前置或者后置的内容。

Http://

.com

Select

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1pbnB1dFxuICAgICAgdi1tb2RlbD1cImlucHV0MVwiXG4gICAgICBzdHlsZT1cIm1heC13aWR0aDogNjAwcHhcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgaW5wdXRcIlxuICAgID5cbiAgICAgIDx0ZW1wbGF0ZSAjcHJlcGVuZD5IdHRwOi8vPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWlucHV0PlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cIm10LTRcIj5cbiAgICA8ZWwtaW5wdXRcbiAgICAgIHYtbW9kZWw9XCJpbnB1dDJcIlxuICAgICAgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgICA+XG4gICAgICA8dGVtcGxhdGUgI2FwcGVuZD4uY29tPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWlucHV0PlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cIm10LTRcIj5cbiAgICA8ZWwtaW5wdXRcbiAgICAgIHYtbW9kZWw9XCJpbnB1dDNcIlxuICAgICAgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgICAgIGNsYXNzPVwiaW5wdXQtd2l0aC1zZWxlY3RcIlxuICAgID5cbiAgICAgIDx0ZW1wbGF0ZSAjcHJlcGVuZD5cbiAgICAgICAgPGVsLXNlbGVjdCB2LW1vZGVsPVwic2VsZWN0XCIgcGxhY2Vob2xkZXI9XCJTZWxlY3RcIiBzdHlsZT1cIndpZHRoOiAxMTVweFwiPlxuICAgICAgICAgIDxlbC1vcHRpb24gbGFiZWw9XCJSZXN0YXVyYW50XCIgdmFsdWU9XCIxXCIgLz5cbiAgICAgICAgICA8ZWwtb3B0aW9uIGxhYmVsPVwiT3JkZXIgTm8uXCIgdmFsdWU9XCIyXCIgLz5cbiAgICAgICAgICA8ZWwtb3B0aW9uIGxhYmVsPVwiVGVsXCIgdmFsdWU9XCIzXCIgLz5cbiAgICAgICAgPC9lbC1zZWxlY3Q+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgPHRlbXBsYXRlICNhcHBlbmQ+XG4gICAgICAgIDxlbC1idXR0b24gOmljb249XCJTZWFyY2hcIiAvPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWlucHV0PlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cIm10LTRcIj5cbiAgICA8ZWwtaW5wdXRcbiAgICAgIHYtbW9kZWw9XCJpbnB1dDNcIlxuICAgICAgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgICAgIGNsYXNzPVwiaW5wdXQtd2l0aC1zZWxlY3RcIlxuICAgID5cbiAgICAgIDx0ZW1wbGF0ZSAjcHJlcGVuZD5cbiAgICAgICAgPGVsLWJ1dHRvbiA6aWNvbj1cIlNlYXJjaFwiIC8+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgPHRlbXBsYXRlICNhcHBlbmQ+XG4gICAgICAgIDxlbC1zZWxlY3Qgdi1tb2RlbD1cInNlbGVjdFwiIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCIgc3R5bGU9XCJ3aWR0aDogMTE1cHhcIj5cbiAgICAgICAgICA8ZWwtb3B0aW9uIGxhYmVsPVwiUmVzdGF1cmFudFwiIHZhbHVlPVwiMVwiIC8+XG4gICAgICAgICAgPGVsLW9wdGlvbiBsYWJlbD1cIk9yZGVyIE5vLlwiIHZhbHVlPVwiMlwiIC8+XG4gICAgICAgICAgPGVsLW9wdGlvbiBsYWJlbD1cIlRlbFwiIHZhbHVlPVwiM1wiIC8+XG4gICAgICAgIDwvZWwtc2VsZWN0PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWlucHV0PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBTZWFyY2ggfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgaW5wdXQxID0gcmVmKCcnKVxuY29uc3QgaW5wdXQyID0gcmVmKCcnKVxuY29uc3QgaW5wdXQzID0gcmVmKCcnKVxuY29uc3Qgc2VsZWN0ID0gcmVmKCcnKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5pbnB1dC13aXRoLXNlbGVjdCAuZWwtaW5wdXQtZ3JvdXBfX3ByZXBlbmQge1xuICBiYWNrZ3JvdW5kLWNvbG9yOiB2YXIoLS1lbC1maWxsLWNvbG9yLWJsYW5rKTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/mixed-input.vue)_

vue

```
<template>
  <div>
    <el-input
      v-model="input1"
      style="max-width: 600px"
      placeholder="Please input"
    >
      <template #prepend>Http://</template>
    </el-input>
  </div>
  <div class="mt-4">
    <el-input
      v-model="input2"
      style="max-width: 600px"
      placeholder="Please input"
    >
      <template #append>.com</template>
    </el-input>
  </div>
  <div class="mt-4">
    <el-input
      v-model="input3"
      style="max-width: 600px"
      placeholder="Please input"
      class="input-with-select"
    >
      <template #prepend>
        <el-select v-model="select" placeholder="Select" style="width: 115px">
          <el-option label="Restaurant" value="1" />
          <el-option label="Order No." value="2" />
          <el-option label="Tel" value="3" />
        </el-select>
      </template>
      <template #append>
        <el-button :icon="Search" />
      </template>
    </el-input>
  </div>
  <div class="mt-4">
    <el-input
      v-model="input3"
      style="max-width: 600px"
      placeholder="Please input"
      class="input-with-select"
    >
      <template #prepend>
        <el-button :icon="Search" />
      </template>
      <template #append>
        <el-select v-model="select" placeholder="Select" style="width: 115px">
          <el-option label="Restaurant" value="1" />
          <el-option label="Order No." value="2" />
          <el-option label="Tel" value="3" />
        </el-select>
      </template>
    </el-input>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Search } from '@element-plus/icons-vue'

const input1 = ref('')
const input2 = ref('')
const input3 = ref('')
const select = ref('')
</script>

<style>
.input-with-select .el-input-group__prepend {
  background-color: var(--el-fill-color-blank);
}
</style>
```

隐藏源代码

## 尺寸 [​](#尺寸)

使用 `size` 属性改变输入框大小。 除了默认大小外，还有另外两个选项： `large`, `small`。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtNCBtYi00IGl0ZW1zLWNlbnRlclwiPlxuICAgIDxlbC1pbnB1dFxuICAgICAgdi1tb2RlbD1cImlucHV0MVwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICBzaXplPVwibGFyZ2VcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgSW5wdXRcIlxuICAgIC8+XG4gICAgPGVsLWlucHV0XG4gICAgICB2LW1vZGVsPVwiaW5wdXQyXCJcbiAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIElucHV0XCJcbiAgICAvPlxuICAgIDxlbC1pbnB1dFxuICAgICAgdi1tb2RlbD1cImlucHV0M1wiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICBzaXplPVwic21hbGxcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgSW5wdXRcIlxuICAgIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtNCBtYi00IGl0ZW1zLWNlbnRlclwiPlxuICAgIDxlbC1pbnB1dFxuICAgICAgdi1tb2RlbD1cImlucHV0MVwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICBzaXplPVwibGFyZ2VcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgSW5wdXRcIlxuICAgICAgOnN1ZmZpeC1pY29uPVwiU2VhcmNoXCJcbiAgICAvPlxuICAgIDxlbC1pbnB1dFxuICAgICAgdi1tb2RlbD1cImlucHV0MlwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBJbnB1dFwiXG4gICAgICA6c3VmZml4LWljb249XCJTZWFyY2hcIlxuICAgIC8+XG4gICAgPGVsLWlucHV0XG4gICAgICB2LW1vZGVsPVwiaW5wdXQzXCJcbiAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICAgIHNpemU9XCJzbWFsbFwiXG4gICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBJbnB1dFwiXG4gICAgICA6c3VmZml4LWljb249XCJTZWFyY2hcIlxuICAgIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtNCBpdGVtcy1jZW50ZXJcIj5cbiAgICA8ZWwtaW5wdXRcbiAgICAgIHYtbW9kZWw9XCJpbnB1dDFcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgc2l6ZT1cImxhcmdlXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIElucHV0XCJcbiAgICAgIDpwcmVmaXgtaWNvbj1cIlNlYXJjaFwiXG4gICAgLz5cbiAgICA8ZWwtaW5wdXRcbiAgICAgIHYtbW9kZWw9XCJpbnB1dDJcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgSW5wdXRcIlxuICAgICAgOnByZWZpeC1pY29uPVwiU2VhcmNoXCJcbiAgICAvPlxuICAgIDxlbC1pbnB1dFxuICAgICAgdi1tb2RlbD1cImlucHV0M1wiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICBzaXplPVwic21hbGxcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgSW5wdXRcIlxuICAgICAgOnByZWZpeC1pY29uPVwiU2VhcmNoXCJcbiAgICAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBTZWFyY2ggfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgaW5wdXQxID0gcmVmKCcnKVxuY29uc3QgaW5wdXQyID0gcmVmKCcnKVxuY29uc3QgaW5wdXQzID0gcmVmKCcnKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/various-size.vue)_

vue

```
<template>
  <div class="flex gap-4 mb-4 items-center">
    <el-input
      v-model="input1"
      style="width: 240px"
      size="large"
      placeholder="Please Input"
    />
    <el-input
      v-model="input2"
      style="width: 240px"
      placeholder="Please Input"
    />
    <el-input
      v-model="input3"
      style="width: 240px"
      size="small"
      placeholder="Please Input"
    />
  </div>
  <div class="flex gap-4 mb-4 items-center">
    <el-input
      v-model="input1"
      style="width: 240px"
      size="large"
      placeholder="Please Input"
      :suffix-icon="Search"
    />
    <el-input
      v-model="input2"
      style="width: 240px"
      placeholder="Please Input"
      :suffix-icon="Search"
    />
    <el-input
      v-model="input3"
      style="width: 240px"
      size="small"
      placeholder="Please Input"
      :suffix-icon="Search"
    />
  </div>
  <div class="flex gap-4 items-center">
    <el-input
      v-model="input1"
      style="width: 240px"
      size="large"
      placeholder="Please Input"
      :prefix-icon="Search"
    />
    <el-input
      v-model="input2"
      style="width: 240px"
      placeholder="Please Input"
      :prefix-icon="Search"
    />
    <el-input
      v-model="input3"
      style="width: 240px"
      size="small"
      placeholder="Please Input"
      :prefix-icon="Search"
    />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Search } from '@element-plus/icons-vue'

const input1 = ref('')
const input2 = ref('')
const input3 = ref('')
</script>
```

隐藏源代码

## 输入长度限制 [​](#输入长度限制)

使用 `maxlength` 和 `minlength` 属性, 来控制输入内容的最大字数和最小字数。 "字符数"使用JavaScript字符串长度来衡量。 为文本或文本输入类型设置 `maxlength` prop可以限制输入值的长度。 允许你通过设置 `show-word-limit` 到 `true` 来显示剩余字数。 从 2.11.5 版本开始，你可以将 `word-limit-position` 设置为 `outside`，以在输入框外显示字数统计。

0 / 10

0 / 10

0 / 30

0 / 30

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXRcbiAgICB2LW1vZGVsPVwidGV4dFwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgIG1heGxlbmd0aD1cIjEwXCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgc2hvdy13b3JkLWxpbWl0XG4gICAgdHlwZT1cInRleHRcIlxuICAvPlxuICA8ZWwtaW5wdXRcbiAgICB2LW1vZGVsPVwidGV4dFwiXG4gICAgY2xhc3M9XCJtbC00XCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgbWF4bGVuZ3RoPVwiMTBcIlxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgICBzaG93LXdvcmQtbGltaXRcbiAgICB3b3JkLWxpbWl0LXBvc2l0aW9uPVwib3V0c2lkZVwiXG4gICAgdHlwZT1cInRleHRcIlxuICAvPlxuICA8ZGl2IHN0eWxlPVwibWFyZ2luOiAyMHB4IDBcIiAvPlxuICA8ZWwtaW5wdXRcbiAgICB2LW1vZGVsPVwidGV4dGFyZWFcIlxuICAgIG1heGxlbmd0aD1cIjMwXCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgaW5wdXRcIlxuICAgIHNob3ctd29yZC1saW1pdFxuICAgIHR5cGU9XCJ0ZXh0YXJlYVwiXG4gIC8+XG4gIDxlbC1pbnB1dFxuICAgIHYtbW9kZWw9XCJ0ZXh0YXJlYVwiXG4gICAgY2xhc3M9XCJtbC00XCJcbiAgICBtYXhsZW5ndGg9XCIzMFwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgICBzaG93LXdvcmQtbGltaXRcbiAgICB3b3JkLWxpbWl0LXBvc2l0aW9uPVwib3V0c2lkZVwiXG4gICAgdHlwZT1cInRleHRhcmVhXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHRleHQgPSByZWYoJycpXG5jb25zdCB0ZXh0YXJlYSA9IHJlZignJylcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/length-limiting.vue)_

vue

```
<template>
  <el-input
    v-model="text"
    style="width: 240px"
    maxlength="10"
    placeholder="Please input"
    show-word-limit
    type="text"
  />
  <el-input
    v-model="text"
    class="ml-4"
    style="width: 240px"
    maxlength="10"
    placeholder="Please input"
    show-word-limit
    word-limit-position="outside"
    type="text"
  />
  <div style="margin: 20px 0" />
  <el-input
    v-model="textarea"
    maxlength="30"
    style="width: 240px"
    placeholder="Please input"
    show-word-limit
    type="textarea"
  />
  <el-input
    v-model="textarea"
    class="ml-4"
    maxlength="30"
    style="width: 240px"
    placeholder="Please input"
    show-word-limit
    word-limit-position="outside"
    type="textarea"
  />
</template>

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

const text = ref('')
const textarea = ref('')
</script>
```

隐藏源代码

## 计数图形2.13.7 [​](#计数图形)

设置 `count-graphemes` 以计算文本长度。 如果设置了该属性，则不会使用原生的 `maxlength` 和 `minlength`。

2 / 10

2 / 20

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXRcbiAgICB2LW1vZGVsPVwidGV4dFwiXG4gICAgbWF4bGVuZ3RoPVwiMTBcIlxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgICBzaG93LXdvcmQtbGltaXRcbiAgICA6Y291bnQtZ3JhcGhlbWVzPVwiY2FsY1wiXG4gICAgdHlwZT1cInRleHRcIlxuICAvPlxuICA8ZGl2IHN0eWxlPVwibWFyZ2luOiAyMHB4IDBcIiAvPlxuICA8ZWwtaW5wdXRcbiAgICB2LW1vZGVsPVwidGV4dGFyZWFcIlxuICAgIG1heGxlbmd0aD1cIjIwXCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgc2hvdy13b3JkLWxpbWl0XG4gICAgOmNvdW50LWdyYXBoZW1lcz1cImNhbGNcIlxuICAgIHR5cGU9XCJ0ZXh0YXJlYVwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB0ZXh0ID0gcmVmKCfwn5iA8J+YgScpXG5jb25zdCB0ZXh0YXJlYSA9IHJlZign8J+YgPCfmIEnKVxuXG4vKipcbiAqIENvdW50IGZ1bmN0aW9uIGZvciBncmFwaGVtZSBjbHVzdGVyaW5nLlxuICogQ291bnRzIHRoZSBudW1iZXIgb2YgZ3JhcGhlbWVzICh2aXN1YWwgY2hhcmFjdGVycykgaW4gYSBzdHJpbmcuXG4gKlxuICogTm90ZTogVGhpcyBleGFtcGxlIHVzZXMgQXJyYXkuZnJvbSgpIGZvciBzaW1wbGljaXR5LlxuICogRm9yIHByb2R1Y3Rpb24gdXNlLCBjb25zaWRlciB1c2luZyBJbnRsLlNlZ21lbnRlciBmb3IgYmV0dGVyXG4gKiBoYW5kbGluZyBvZiBjb21wbGV4IGVtb2ppIGFuZCB1bmljb2RlIGNoYXJhY3RlcnMuXG4gKi9cbmNvbnN0IGNhbGMgPSAodmFsdWU6IHN0cmluZykgPT4ge1xuICAvLyBTaW1wbGlmaWVkIHZlcnNpb246IGNvdW50cyBjb2RlIHBvaW50cyAobm90IGZ1bGwgZ3JhcGhlbWUgY2x1c3RlcnMpXG4gIC8vIEZvciBwcm9kdWN0aW9uLCB1c2UgSW50bC5TZWdtZW50ZXIgbGlrZSB0aGUgY29tcG9uZW50IGRvZXNcbiAgcmV0dXJuIEFycmF5LmZyb20odmFsdWUpLmxlbmd0aFxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input/count-graphemes.vue)_

vue

```
<template>
  <el-input
    v-model="text"
    maxlength="10"
    placeholder="Please input"
    show-word-limit
    :count-graphemes="calc"
    type="text"
  />
  <div style="margin: 20px 0" />
  <el-input
    v-model="textarea"
    maxlength="20"
    placeholder="Please input"
    show-word-limit
    :count-graphemes="calc"
    type="textarea"
  />
</template>

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

const text = ref('😀😁')
const textarea = ref('😀😁')

/**
 * Count function for grapheme clustering.
 * Counts the number of graphemes (visual characters) in a string.
 *
 * Note: This example uses Array.from() for simplicity.
 * For production use, consider using Intl.Segmenter for better
 * handling of complex emoji and unicode characters.
 */
const calc = (value: string) => {
  // Simplified version: counts code points (not full grapheme clusters)
  // For production, use Intl.Segmenter like the component does
  return Array.from(value).length
}
</script>
```

隐藏源代码

TIP

**浏览器支持 & 回退策略**

当使用 `count-graphemes` prop时，组件使用以下方法：

-   **主要**: 使用 `Intl.Segmenter` API (Chrome 87+, Firefox 125+, Safari 14.1+) 进行适当的图形集群处理。 它能够正确处理复杂的表情符号、组合标记和0宽度连接符序列。

-   **回退**: 旧版浏览器会回退到 `Array.from()` 进行基于码点的迭代。 请注意，这可能会拆分多码点字形序列（例如，带有肤色修饰符的表情符号）。

在实现自己的 `count-graphemes` 函数时，如果需要对复杂的 unicode 字符提供强大的支持，请考虑使用 `Intl.Segmenter`。

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| type | 输入类型，更多信息请参见 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types) | `string` | text |
| model-value / v-model | 绑定值 | `string` / `number` | — |
| model-modifiers 2.11.5 | v-model 修饰符，参考 [Vue 修饰符](https://vuejs.org/guide/essentials/forms.html#modifiers) | `object` | — |
| maxlength | 同原生 `maxlength` 属性 | `string` / `number` | — |
| minlength | 原生属性，最小输入长度 | `string` / `number` | — |
| show-word-limit | 是否显示统计字数, 只在 `type` 为 'text' 或 'textarea' 的时候生效 | `boolean` | false |
| word-limit-position 2.11.5 | 字数统计的位置，仅当 `show-word-limit` 为 `true` 时生效。 | `enum` | "inside" |
| placeholder | 输入框占位文本 | `string` | — |
| clearable | 是否显示清除按钮，只有当 `type` 不是 textarea时生效 | `boolean` | false |
| clear-icon 2.11.0 | 自定义清除图标 | `string` / `object` | CircleClose |
| formatter | 指定输入值的格式。(只有当 `type` 是"text"时才能工作) | `Function` | — |
| parser | 指定从格式化器输入中提取的值。(仅当 `type` 是"text"时才起作用) | `Function` | — |
| show-password | 是否显示切换密码图标 | `boolean` | false |
| disabled | 是否禁用 | `boolean` | false |
| size | 输入框尺寸，只在 `type` 不为 'textarea' 时有效 | `enum` | — |
| prefix-icon | 自定义前缀图标 | `string` / `Component` | — |
| suffix-icon | 自定义后缀图标 | `string` / `Component` | — |
| rows | 输入框行数，仅 `type` 为 'textarea' 时有效 | `number` | 2 |
| autosize | textarea 高度是否自适应，仅 `type` 为 'textarea' 时生效。 可以接受一个对象，比如: `{ minRows: 2, maxRows: 6 }` | `boolean` / `object` | false |
| autocomplete | 原生 `autocomplete` 属性 | `string` | off |
| name | 等价于原生 input `name` 属性 | `string` | — |
| readonly | 原生 `readonly` 属性，是否只读 | `boolean` | false |
| max | 原生 `max` 属性，设置最大值 | — | — |
| min | 原生属性，设置最小值 | — | — |
| step | 原生属性，设置输入字段的合法数字间隔 | ::: | — |
| resize | 控制是否能被用户缩放 | `enum` | — |
| autofocus | 原生属性，自动获取焦点 | `boolean` | false |
| form | 原生属性 | `string` | — |
| aria-label a11y 2.7.2 | 等价于原生 input `aria-label` 属性 | `string` | — |
| tabindex | 输入框的 tabindex | `string` / `number` | — |
| validate-event | 输入时是否触发表单的校验 | `boolean` | true |
| input-style | input 元素或 textarea 元素的 style | `string` / `object` | {} |
| label a11y deprecated | 等价于原生 input `aria-label` 属性 | `string` | — |
| inputmode 2.10.3 | 等价于原生 input `inputmode` 属性 | `string` | — |
| count-graphemes 2.13.7 | 自定义函数用于计算字形；设置后，将绕过原生的 `maxlength`/`minlength` 约束。 组件使用 `Intl.Segmenter`（Chrome 87+、Firefox 125+、Safari 14.1+）进行正确的字素聚类；旧版浏览器回退到使用 `Array.from()` 进行码点迭代。 | `Function` | — |

### Events [​](#events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| blur | 当选择器的输入框失去焦点时触发 | `Function` |
| focus | 当选择器的输入框获得焦点时触发 | `Function` |
| change | 仅当 modelValue 改变时，当输入框失去焦点或用户按Enter时触发 | `Function` |
| input | 在 Input 值改变时触发 | `Function` |
| clear | 在点击由 `clearable` 属性生成的清空按钮时触发 | `Function` |
| keydown | 按下键时触发 | `Function` |
| mouseleave | 当鼠标离开输入元素时触发 | `Function` |
| mouseenter | 当鼠标进入输入元素时触发 | `Function` |
| compositionstart | 输入法输入开始时触发 | `Function` |
| compositionupdate | 输入法输入改变时触发 | `Function` |
| compositionend | 输入法输入完成时触发 | `Function` |

### Slots [​](#slots)

| 插槽名 | 说明 |
| --- | --- |
| prefix | 输入框头部内容，只对非 `type="textarea"` 有效 |
| suffix | 输入框尾部内容，只对非 `type="textarea"` 有效 |
| prepend | 输入框前置内容，只对非 `type="textarea"` 有效 |
| append | 输入框后置内容，只对非 `type="textarea"` 有效 |
| password-icon 2.13.6 | 作为输入密码图标的内容，仅在 `show-password` 为 true 时生效。 作用域变量为 `{ visible: boolean }` |

### Exposes [​](#exposes)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| blur | 使 input 失去焦点 | `Function` |
| clear | 清除 input 值 | `Function` |
| focus | 使 input 获取焦点 | `Function` |
| input | Input HTML 元素 | `object` |
| ref | HTML元素 input 或 textarea | `object` |
| resizeTextarea | 改变 textarea 大小 | `Function` |
| select | 选中 input 中的文字 | `Function` |
| textarea | HTML textarea 元素 | `object` |
| textareaStyle | textarea 的样式 | `object` |
| isComposing 2.8.0 | 是否是输入 composing 状态 | `object` |
| passwordVisible 2.13.7 | 密码是否可见 | `object` |

## 常见问题 [​](#常见问题)

#### ElInput 组件的宽度为什么在设置了 `clearable` 时会发生变化 [​](#elinput-组件的宽度为什么在设置了-clearable-时会发生变化)

典型问题： [#7287](https://github.com/element-plus/element-plus/issues/7287)

PS: 由于ElInput 组件没有默认宽度，当显示 clearable 图标时, 组件的宽度将被撑开，可以通过设置固定宽度属性来解决。

vue

```
<el-input v-model="input" clearable style="width: 200px" />
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/input) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/input.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/input.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/101238421?v=4&size=64)](https://github.com/acyza)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/5283258?v=4&size=64)](https://github.com/satrong)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/47766606?v=4&size=64)](https://github.com/ls57765867)[![](https://avatars.githubusercontent.com/u/71313168?v=4&size=64)](https://github.com/cc-hearts)[![](https://avatars.githubusercontent.com/u/49630878?v=4&size=64)](https://github.com/a869246700)[![](https://avatars.githubusercontent.com/u/22286818?v=4&size=64)](https://github.com/fratzinger)[![](https://avatars.githubusercontent.com/u/5850779?v=4&size=64)](https://github.com/IllegalCreed)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/28857867?v=4&size=64)](https://github.com/qq1037305420)[![](https://avatars.githubusercontent.com/u/6777923?v=4&size=64)](https://github.com/markpro-code)[![](https://avatars.githubusercontent.com/u/50254496?v=4&size=64)](https://github.com/LoTwT)[![](https://avatars.githubusercontent.com/u/26403700?v=4&size=64)](https://github.com/blesstosam)[![](https://avatars.githubusercontent.com/u/27912232?v=4&size=64)](https://github.com/Fuphoenixes)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/109908413?v=4&size=64)](https://github.com/sleepyShen1989)[![](https://avatars.githubusercontent.com/u/66891653?v=4&size=64)](https://github.com/YoungDan-hero)[![](https://avatars.githubusercontent.com/u/56245609?v=4&size=64)](https://github.com/pzzyf)[![](https://avatars.githubusercontent.com/u/55378595?v=4&size=64)](https://github.com/evanryuu)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/30046649?v=4&size=64)](https://github.com/MrWeilian)[![](https://avatars.githubusercontent.com/u/126545033?v=4&size=64)](https://github.com/dhj-l)[![](https://avatars.githubusercontent.com/u/57179957?v=4&size=64)](https://github.com/yeonjulee1005)[![](https://avatars.githubusercontent.com/u/48373109?v=4&size=64)](https://github.com/yuchiXiong)[![](https://avatars.githubusercontent.com/u/33423008?v=4&size=64)](https://github.com/shigma)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/28089690?v=4&size=64)](https://github.com/daonatural)[![](https://avatars.githubusercontent.com/u/4318293?v=4&size=64)](https://github.com/cn-troy)[![](https://avatars.githubusercontent.com/u/23720738?v=4&size=64)](https://github.com/kouchao)[![](https://avatars.githubusercontent.com/u/34675975?v=4&size=64)](https://github.com/dreamqyq)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/32129111?v=4&size=64)](https://github.com/Vgbire)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/22190579?v=4&size=64)](https://github.com/wangerzi)[![](https://avatars.githubusercontent.com/u/32960305?v=4&size=64)](https://github.com/KimYangOfCat)[![](https://avatars.githubusercontent.com/u/25458528?v=4&size=64)](https://github.com/weidehai)[![](https://avatars.githubusercontent.com/u/32354856?v=4&size=64)](https://github.com/baiwusanyu-c)[![](https://avatars.githubusercontent.com/u/18349295?v=4&size=64)](https://github.com/zt123123)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/45936772?v=4&size=64)](https://github.com/KawaiiZapic)[![](https://avatars.githubusercontent.com/u/39672197?v=4&size=64)](https://github.com/bchen1029)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)

[Form 表单组件](https://element-plus.org/zh-CN/component/form)

[Input Number 数字输入框](https://element-plus.org/zh-CN/component/input-number)




---
## [form/input-number] Input Number 数字输入框
> 官方文档: https://element-plus.org/zh-CN/component/input-number.html

---

# Input Number 数字输入框 [​](#input-number-数字输入框)

更新日志待解决

14

仅允许输入标准的数字值，可定义范围

## 基础用法 [​](#基础用法)

要使用它，只需要在 `<el-input-number>` 元素中使用 `v-model` 绑定变量即可，变量的初始值即为默认值。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtbnVtYmVyIHYtbW9kZWw9XCJudW1cIiA6bWluPVwiMVwiIDptYXg9XCIxMFwiIEBjaGFuZ2U9XCJoYW5kbGVDaGFuZ2VcIiAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgbnVtID0gcmVmKDEpXG5jb25zdCBoYW5kbGVDaGFuZ2UgPSAodmFsdWU6IG51bWJlciB8IHVuZGVmaW5lZCkgPT4ge1xuICBjb25zb2xlLmxvZyh2YWx1ZSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-number/basic.vue)_

vue

```
<template>
  <el-input-number v-model="num" :min="1" :max="10" @change="handleChange" />
</template>

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

const num = ref(1)
const handleChange = (value: number | undefined) => {
  console.log(value)
}
</script>
```

隐藏源代码

TIP

当输入无效的字符串到输入框时，由于错误，输入值将把 `NaN` 导入到上层

## 禁用状态 [​](#禁用状态)

`disabled`属性接受一个 `Boolean`，设置为`true`即可禁用整个组件。 ，如果你只需要控制数值在某一范围内，可以设置 `min` 属性和 `max` 属性， 默认情况下，最小值是 `Number.MIN_SAFE_INTEGER`。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtbnVtYmVyIHYtbW9kZWw9XCJudW1cIiA6ZGlzYWJsZWQ9XCJ0cnVlXCIgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IG51bSA9IHJlZigxKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-number/disabled.vue)_

vue

```
<template>
  <el-input-number v-model="num" :disabled="true" />
</template>

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

const num = ref(1)
</script>
```

隐藏源代码

## 步进 [​](#步进)

允许定义递增递减的步进控制

设置 `step` 属性可以控制步长。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtbnVtYmVyIHYtbW9kZWw9XCJudW1cIiA6c3RlcD1cIjJcIiAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgbnVtID0gcmVmKDUpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-number/steps.vue)_

vue

```
<template>
  <el-input-number v-model="num" :step="2" />
</template>

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

const num = ref(5)
</script>
```

隐藏源代码

## 严格步进 [​](#严格步进)

`step-strictly`属性接受一个`Boolean`。 如果这个属性被设置为 `true`，则只能输入步进的倍数。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtbnVtYmVyIHYtbW9kZWw9XCJudW1cIiA6c3RlcD1cIjJcIiBzdGVwLXN0cmljdGx5IC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBudW0gPSByZWYoMilcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-number/step-strictly.vue)_

vue

```
<template>
  <el-input-number v-model="num" :step="2" step-strictly />
</template>

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

const num = ref(2)
</script>
```

隐藏源代码

## 精度 [​](#精度)

设置 `precision` 属性可以控制数值精度，接收一个 `Number`。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtbnVtYmVyIHYtbW9kZWw9XCJudW1cIiA6cHJlY2lzaW9uPVwiMlwiIDpzdGVwPVwiMC4xXCIgOm1heD1cIjEwXCIgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IG51bSA9IHJlZigxKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-number/precision.vue)_

vue

```
<template>
  <el-input-number v-model="num" :precision="2" :step="0.1" :max="10" />
</template>

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

const num = ref(1)
</script>
```

隐藏源代码

TIP

`precision` 的值必须是一个非负整数，并且不能小于 `step` 的小数位数。

## 不同的输入框尺寸 [​](#不同的输入框尺寸)

使用 `size` 属性额外配置尺寸，可选的尺寸大小为：`large` 或 `small`

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgaXRlbXMtY2VudGVyIGdhcC00XCI+XG4gICAgPGVsLWlucHV0LW51bWJlciB2LW1vZGVsPVwibnVtMVwiIHNpemU9XCJsYXJnZVwiIC8+XG4gICAgPGVsLWlucHV0LW51bWJlciB2LW1vZGVsPVwibnVtMlwiIC8+XG4gICAgPGVsLWlucHV0LW51bWJlciB2LW1vZGVsPVwibnVtM1wiIHNpemU9XCJzbWFsbFwiIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgbnVtMSA9IHJlZigxKVxuY29uc3QgbnVtMiA9IHJlZigyKVxuY29uc3QgbnVtMyA9IHJlZigzKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-number/size.vue)_

vue

```
<template>
  <div class="flex flex-wrap items-center gap-4">
    <el-input-number v-model="num1" size="large" />
    <el-input-number v-model="num2" />
    <el-input-number v-model="num3" size="small" />
  </div>
</template>

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

const num1 = ref(1)
const num2 = ref(2)
const num3 = ref(3)
</script>
```

隐藏源代码

## 按钮位置 [​](#按钮位置)

设置 `controls-position` 属性可以控制按钮位置。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgaXRlbXMtY2VudGVyIGdhcC00XCI+XG4gICAgPGVsLWlucHV0LW51bWJlclxuICAgICAgdi1tb2RlbD1cIm51bVwiXG4gICAgICA6bWluPVwiMVwiXG4gICAgICA6bWF4PVwiMTBcIlxuICAgICAgY29udHJvbHMtcG9zaXRpb249XCJyaWdodFwiXG4gICAgICBzaXplPVwibGFyZ2VcIlxuICAgICAgQGNoYW5nZT1cImhhbmRsZUNoYW5nZVwiXG4gICAgLz5cbiAgICA8ZWwtaW5wdXQtbnVtYmVyXG4gICAgICB2LW1vZGVsPVwibnVtXCJcbiAgICAgIDptaW49XCIxXCJcbiAgICAgIDptYXg9XCIxMFwiXG4gICAgICBjb250cm9scy1wb3NpdGlvbj1cInJpZ2h0XCJcbiAgICAgIEBjaGFuZ2U9XCJoYW5kbGVDaGFuZ2VcIlxuICAgIC8+XG4gICAgPGVsLWlucHV0LW51bWJlclxuICAgICAgdi1tb2RlbD1cIm51bVwiXG4gICAgICA6bWluPVwiMVwiXG4gICAgICA6bWF4PVwiMTBcIlxuICAgICAgc2l6ZT1cInNtYWxsXCJcbiAgICAgIGNvbnRyb2xzLXBvc2l0aW9uPVwicmlnaHRcIlxuICAgICAgQGNoYW5nZT1cImhhbmRsZUNoYW5nZVwiXG4gICAgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBudW0gPSByZWYoMSlcbmNvbnN0IGhhbmRsZUNoYW5nZSA9ICh2YWx1ZTogbnVtYmVyIHwgdW5kZWZpbmVkKSA9PiB7XG4gIGNvbnNvbGUubG9nKHZhbHVlKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-number/controlled.vue)_

vue

```
<template>
  <div class="flex flex-wrap items-center gap-4">
    <el-input-number
      v-model="num"
      :min="1"
      :max="10"
      controls-position="right"
      size="large"
      @change="handleChange"
    />
    <el-input-number
      v-model="num"
      :min="1"
      :max="10"
      controls-position="right"
      @change="handleChange"
    />
    <el-input-number
      v-model="num"
      :min="1"
      :max="10"
      size="small"
      controls-position="right"
      @change="handleChange"
    />
  </div>
</template>

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

const num = ref(1)
const handleChange = (value: number | undefined) => {
  console.log(value)
}
</script>
```

隐藏源代码

## 自定义图标 2.6.3 [​](#自定义图标)

使用 `decrease-icon` 和 `increase-icon` 设置自定义图标。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2UgZGlyZWN0aW9uPVwidmVydGljYWxcIj5cbiAgICA8ZWwtc3BhY2U+XG4gICAgICA8ZWwtaW5wdXQtbnVtYmVyIHYtbW9kZWw9XCJudW1cIiAvPlxuICAgICAgPGVsLWlucHV0LW51bWJlciB2LW1vZGVsPVwibnVtXCI+XG4gICAgICAgIDx0ZW1wbGF0ZSAjZGVjcmVhc2UtaWNvbj5cbiAgICAgICAgICA8ZWwtaWNvbj5cbiAgICAgICAgICAgIDxBcnJvd0Rvd24gLz5cbiAgICAgICAgICA8L2VsLWljb24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDx0ZW1wbGF0ZSAjaW5jcmVhc2UtaWNvbj5cbiAgICAgICAgICA8ZWwtaWNvbj5cbiAgICAgICAgICAgIDxBcnJvd1VwIC8+XG4gICAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1pbnB1dC1udW1iZXI+XG4gICAgPC9lbC1zcGFjZT5cbiAgICA8ZWwtc3BhY2U+XG4gICAgICA8ZWwtaW5wdXQtbnVtYmVyIHYtbW9kZWw9XCJudW1cIiBjb250cm9scy1wb3NpdGlvbj1cInJpZ2h0XCIgLz5cbiAgICAgIDxlbC1pbnB1dC1udW1iZXIgdi1tb2RlbD1cIm51bVwiIGNvbnRyb2xzLXBvc2l0aW9uPVwicmlnaHRcIj5cbiAgICAgICAgPHRlbXBsYXRlICNkZWNyZWFzZS1pY29uPlxuICAgICAgICAgIDxlbC1pY29uPlxuICAgICAgICAgICAgPE1pbnVzIC8+XG4gICAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICA8dGVtcGxhdGUgI2luY3JlYXNlLWljb24+XG4gICAgICAgICAgPGVsLWljb24+XG4gICAgICAgICAgICA8UGx1cyAvPlxuICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtaW5wdXQtbnVtYmVyPlxuICAgIDwvZWwtc3BhY2U+XG4gIDwvZWwtc3BhY2U+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgQXJyb3dEb3duLCBBcnJvd1VwLCBNaW51cywgUGx1cyB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5jb25zdCBudW0gPSByZWYoMSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-number/custom.vue)_

vue

```
<template>
  <el-space direction="vertical">
    <el-space>
      <el-input-number v-model="num" />
      <el-input-number v-model="num">
        <template #decrease-icon>
          <el-icon>
            <ArrowDown />
          </el-icon>
        </template>
        <template #increase-icon>
          <el-icon>
            <ArrowUp />
          </el-icon>
        </template>
      </el-input-number>
    </el-space>
    <el-space>
      <el-input-number v-model="num" controls-position="right" />
      <el-input-number v-model="num" controls-position="right">
        <template #decrease-icon>
          <el-icon>
            <Minus />
          </el-icon>
        </template>
        <template #increase-icon>
          <el-icon>
            <Plus />
          </el-icon>
        </template>
      </el-input-number>
    </el-space>
  </el-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ArrowDown, ArrowUp, Minus, Plus } from '@element-plus/icons-vue'

const num = ref(1)
</script>
```

隐藏源代码

## 带前缀和后缀2.8.4 [​](#带前缀和后缀)

使用前缀和标名后缀。

￥

RMB

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2U+XG4gICAgPGVsLWlucHV0LW51bWJlciB2LW1vZGVsPVwibnVtXCIgOm1pbj1cIjFcIiA6bWF4PVwiMTBcIj5cbiAgICAgIDx0ZW1wbGF0ZSAjcHJlZml4PlxuICAgICAgICA8c3Bhbj7vv6U8L3NwYW4+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtaW5wdXQtbnVtYmVyPlxuICAgIDxlbC1pbnB1dC1udW1iZXIgdi1tb2RlbD1cIm51bVwiIDptaW49XCIxXCIgOm1heD1cIjEwXCI+XG4gICAgICA8dGVtcGxhdGUgI3N1ZmZpeD5cbiAgICAgICAgPHNwYW4+Uk1CPC9zcGFuPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWlucHV0LW51bWJlcj5cbiAgPC9lbC1zcGFjZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IG51bSA9IHJlZigxKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-number/with-prefix-suffix.vue)_

vue

```
<template>
  <el-space>
    <el-input-number v-model="num" :min="1" :max="10">
      <template #prefix>
        <span>￥</span>
      </template>
    </el-input-number>
    <el-input-number v-model="num" :min="1" :max="10">
      <template #suffix>
        <span>RMB</span>
      </template>
    </el-input-number>
  </el-space>
</template>

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

const num = ref(1)
</script>
```

隐藏源代码

TIP

为了确保精度，输入的数值被限制在 [Number.MIN\_SAFE\_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER) 到 [Number.MAX\_SAFE\_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER) 之间。

## Formatter 2.14.0 [​](#formatter)

使用 `formatter` 来显示值，通常会同时配合 `parser` 一起使用。

当设置了 `formatter` 时，内部输入框的 `type` 会变为 `text`，从而允许输入非数字字符。 组件内部使用 `Number.parseFloat` 处理输入：解析成功时，将解析后的数值写入 `model-value`；当解析结果为 `NaN` 时，将 `model-value` 设为 `null`。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtbnVtYmVyXG4gICAgdi1tb2RlbD1cImlucHV0XCJcbiAgICA6Zm9ybWF0dGVyPVwiKHZhbHVlKSA9PiBgJCAke3ZhbHVlfWAucmVwbGFjZSgvXFxCKD89KFxcZHszfSkrKD8hXFxkKSkvZywgJywnKVwiXG4gICAgOnBhcnNlcj1cIih2YWx1ZSkgPT4gdmFsdWUucmVwbGFjZSgvXFwkXFxzP3woLCopL2csICcnKVwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBpbnB1dCA9IHJlZigxMDAwMClcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-number/formatter.vue)_

vue

```
<template>
  <el-input-number
    v-model="input"
    :formatter="(value) => `$ ${value}`.replace(/\B(?=(\d{3})+(?!\d))/g, ',')"
    :parser="(value) => value.replace(/\$\s?|(,*)/g, '')"
  />
</template>

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

const input = ref(10000)
</script>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `number` / `null` | — |
| min | 设置计数器允许的最小值 | `number` | Number.MIN\_SAFE\_INTEGER |
| max | 设置计数器允许的最大值 | `number` | Number.MAX\_SAFE\_INTEGER |
| step | 计数器步长 | `number` | 1 |
| step-strictly | 是否只能输入 step 的倍数 | `boolean` | false |
| precision | 数值精度 | `number` | — |
| size | 计数器尺寸 | `enum` | default |
| readonly 2.2.16 | 原生 `readonly` 属性，是否只读 | `boolean` | false |
| disabled | 是否禁用状态 | `boolean` | false |
| controls | 是否使用控制按钮 | `boolean` | true |
| controls-position | 控制按钮位置 | `enum` | — |
| name | 等价于原生 input `name` 属性 | `string` | — |
| aria-label a11y 2.7.2 | 等价于原生 input `aria-label` 属性 | `string` | — |
| placeholder | 等价于原生 input `placeholder` 属性 | `string` | — |
| id | 等价于原生 input `id` 属性 | `string` | — |
| value-on-clear 2.2.0 | 当输入框被清空时显示的值 | `number` / `null` / `enum` | — |
| validate-event | 是否触发表单验证 | `boolean` | true |
| label a11y deprecated | 等价于原生 input `aria-label` 属性 | `string` | — |
| inputmode 2.10.3 | 等价于原生 input `inputmode` 属性 | `string` | — |
| align 2.10.5 | 内部输入文本对齐 | `enum` | 'center' |
| disabled-scientific 2.10.5 | 禁用科学计数法的输入（例如输入 'e'） | `boolean` | false |
| tabindex 2.14.0 | 输入框的 tabindex | `string` / `number` | 0 |
| formatter 2.14.0 | 指定输入值的格式 | `Function` | ::: |
| parser 2.14.0 | 指定从格式化输入中提取的值 | `Function` | — |

### Slots [​](#slots)

| 插槽名 | 说明 |
| --- | --- |
| decrease-icon 2.6.3 | 自定义输入框按钮减少图标 |
| increase-icon 2.6.3 | 自定义输入框按钮增加图标 |
| prefix 2.8.4 | 输入框头部内容 |
| suffix 2.8.4 | 输入框尾部内容 |

### Events [​](#events)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| change | 绑定值被改变时触发 | `Function` |
| blur | 在组件 Input 失去焦点时触发 | `Function` |
| focus | 在组件 Input 获得焦点时触发 | `Function` |

### Exposes [​](#exposes)

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| focus | 使 input 组件获得焦点 | `Function` |
| blur | 使 input 组件失去焦点 | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/input-number) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/input-number.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/input-number.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/42017165?v=4&size=64)](https://github.com/Mario34)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/7877834?v=4&size=64)](https://github.com/921)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/71313168?v=4&size=64)](https://github.com/cc-hearts)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/22286818?v=4&size=64)](https://github.com/fratzinger)[![](https://avatars.githubusercontent.com/u/119273236?v=4&size=64)](https://github.com/XL-YiBai)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/84778445?v=4&size=64)](https://github.com/yuxi-ovo)[![](https://avatars.githubusercontent.com/u/47178158?v=4&size=64)](https://github.com/Aaron-zon)[![](https://avatars.githubusercontent.com/u/80440359?v=4&size=64)](https://github.com/guze2003)[![](https://avatars.githubusercontent.com/u/30970336?v=4&size=64)](https://github.com/KESHAOYE)[![](https://avatars.githubusercontent.com/u/84954229?v=4&size=64)](https://github.com/Canroc)[![](https://avatars.githubusercontent.com/u/69418751?v=4&size=64)](https://github.com/selicens)[![](https://avatars.githubusercontent.com/u/97817985?v=4&size=64)](https://github.com/nova1751)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/108655466?v=4&size=64)](https://github.com/Karolis-Stoncius)[![](https://avatars.githubusercontent.com/u/86777555?v=4&size=64)](https://github.com/zhengsixsix)[![](https://avatars.githubusercontent.com/u/109908413?v=4&size=64)](https://github.com/sleepyShen1989)[![](https://avatars.githubusercontent.com/u/22910740?v=4&size=64)](https://github.com/StephenKe)[![](https://avatars.githubusercontent.com/u/32354856?v=4&size=64)](https://github.com/baiwusanyu-c)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/55891373?v=4&size=64)](https://github.com/so11y)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/17810772?v=4&size=64)](https://github.com/dingyuanjie)[![](https://avatars.githubusercontent.com/u/48650709?v=4&size=64)](https://github.com/MARIOMARUI)[![](https://avatars.githubusercontent.com/u/75007029?v=4&size=64)](https://github.com/yj-liuzepeng)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/26833520?v=4&size=64)](https://github.com/josonho)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/45936772?v=4&size=64)](https://github.com/KawaiiZapic)[![](https://avatars.githubusercontent.com/u/18051955?v=4&size=64)](https://github.com/qige2016)[![](https://avatars.githubusercontent.com/u/2755933?v=4&size=64)](https://github.com/BiosSun)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/8591261?v=4&size=64)](https://github.com/zeyongTsai)[![](https://avatars.githubusercontent.com/u/25502024?v=4&size=64)](https://github.com/imguolao)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)

[Input 输入框](https://element-plus.org/zh-CN/component/input)

[Input Tag 标签输入框](https://element-plus.org/zh-CN/component/input-tag)




---
## [form/input-tag] Input Tag 标签输入框
> 官方文档: https://element-plus.org/zh-CN/component/input-tag.html

---

# InputTag 标签输入框 [​](#inputtag-标签输入框)

更新日志待解决

0

InputTag 组件允许用户添加内容作为标签

## 基础用法 [​](#基础用法)

按Enter回车键添加输入内容为标签

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtdGFnXG4gICAgdi1tb2RlbD1cImlucHV0XCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgYXJpYS1sYWJlbD1cIlBsZWFzZSBjbGljayB0aGUgRW50ZXIga2V5IGFmdGVyIGlucHV0XCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGlucHV0ID0gcmVmPHN0cmluZ1tdPigpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/basic.vue)_

vue

```
<template>
  <el-input-tag
    v-model="input"
    placeholder="Please input"
    aria-label="Please click the Enter key after input"
  />
</template>

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

const input = ref<string[]>()
</script>
```

隐藏源代码

## 自定义触发器 [​](#自定义触发器)

您可以自定义用于触发输入标签的键位， 默认是Enter 回车键

Enter

Space

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1zZWdtZW50ZWQgdi1tb2RlbD1cInRyaWdnZXJcIiA6b3B0aW9ucz1cIm9wdGlvbnNcIiAvPlxuICA8L2Rpdj5cbiAgPGJyIC8+XG4gIDxlbC1pbnB1dC10YWcgdi1tb2RlbD1cImlucHV0XCIgOnRyaWdnZXI9XCJ0cmlnZ2VyXCIgcGxhY2Vob2xkZXI9XCJQbGVhc2UgaW5wdXRcIiAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVWRU5UX0NPREUgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHRyaWdnZXIgPSByZWY8J0VudGVyJyB8ICdTcGFjZSc+KCdTcGFjZScpXG5jb25zdCBpbnB1dCA9IHJlZjxzdHJpbmdbXT4oKVxuY29uc3Qgb3B0aW9ucyA9IFtFVkVOVF9DT0RFLmVudGVyLCBFVkVOVF9DT0RFLnNwYWNlXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/trigger.vue)_

vue

```
<template>
  <div>
    <el-segmented v-model="trigger" :options="options" />
  </div>
  <br />
  <el-input-tag v-model="input" :trigger="trigger" placeholder="Please input" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { EVENT_CODE } from 'element-plus'

const trigger = ref<'Enter' | 'Space'>('Space')
const input = ref<string[]>()
const options = [EVENT_CODE.enter, EVENT_CODE.space]
</script>
```

隐藏源代码

## 最大标签数 [​](#最大标签数)

您可以设置可以添加的标签数量限制。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtdGFnIHYtbW9kZWw9XCJpbnB1dFwiIDptYXg9XCIzXCIgcGxhY2Vob2xkZXI9XCJlbnRlciB1cCB0byAzIHRhZ3NcIiAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5wdXQgPSByZWY8c3RyaW5nW10+KClcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/max.vue)_

vue

```
<template>
  <el-input-tag v-model="input" :max="3" placeholder="enter up to 3 tags" />
</template>

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

const input = ref<string[]>()
</script>
```

隐藏源代码

## 折叠标签2.11.0 [​](#折叠标签)

使用折叠标签属性将它们合并成一块文本。 您可以使用折叠标签工具提示属性来启用悬停在折叠文本上的行为来显示特定的选定值。 使用折叠标签工具提示属性会使最大属性无效。

use collapse-tags

use collapse-tags-tooltip

use max-collapse-tags

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+dXNlIGNvbGxhcHNlLXRhZ3M8L3A+XG4gICAgPGVsLWlucHV0LXRhZ1xuICAgICAgdi1tb2RlbD1cImlucHV0MVwiXG4gICAgICBjb2xsYXBzZS10YWdzXG4gICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgICBhcmlhLWxhYmVsPVwiUGxlYXNlIGNsaWNrIHRoZSBFbnRlciBrZXkgYWZ0ZXIgaW5wdXRcIlxuICAgIC8+XG4gICAgPHA+dXNlIGNvbGxhcHNlLXRhZ3MtdG9vbHRpcDwvcD5cbiAgICA8ZWwtaW5wdXQtdGFnXG4gICAgICB2LW1vZGVsPVwiaW5wdXQyXCJcbiAgICAgIGNvbGxhcHNlLXRhZ3NcbiAgICAgIGNvbGxhcHNlLXRhZ3MtdG9vbHRpcFxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgaW5wdXRcIlxuICAgICAgYXJpYS1sYWJlbD1cIlBsZWFzZSBjbGljayB0aGUgRW50ZXIga2V5IGFmdGVyIGlucHV0XCJcbiAgICAvPlxuICAgIDxwPnVzZSBtYXgtY29sbGFwc2UtdGFnczwvcD5cbiAgICA8ZWwtaW5wdXQtdGFnXG4gICAgICB2LW1vZGVsPVwiaW5wdXQzXCJcbiAgICAgIGNvbGxhcHNlLXRhZ3NcbiAgICAgIGNvbGxhcHNlLXRhZ3MtdG9vbHRpcFxuICAgICAgOm1heC1jb2xsYXBzZS10YWdzPVwiM1wiXG4gICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgICBhcmlhLWxhYmVsPVwiUGxlYXNlIGNsaWNrIHRoZSBFbnRlciBrZXkgYWZ0ZXIgaW5wdXRcIlxuICAgIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5wdXQxID0gcmVmPHN0cmluZ1tdPigpXG5jb25zdCBpbnB1dDIgPSByZWY8c3RyaW5nW10+KClcbmNvbnN0IGlucHV0MyA9IHJlZjxzdHJpbmdbXT4oKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/collapse.vue)_

vue

```
<template>
  <div class="m-4">
    <p>use collapse-tags</p>
    <el-input-tag
      v-model="input1"
      collapse-tags
      placeholder="Please input"
      aria-label="Please click the Enter key after input"
    />
    <p>use collapse-tags-tooltip</p>
    <el-input-tag
      v-model="input2"
      collapse-tags
      collapse-tags-tooltip
      placeholder="Please input"
      aria-label="Please click the Enter key after input"
    />
    <p>use max-collapse-tags</p>
    <el-input-tag
      v-model="input3"
      collapse-tags
      collapse-tags-tooltip
      :max-collapse-tags="3"
      placeholder="Please input"
      aria-label="Please click the Enter key after input"
    />
  </div>
</template>

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

const input1 = ref<string[]>()
const input2 = ref<string[]>()
const input3 = ref<string[]>()
</script>
```

隐藏源代码

## 禁用状态 [​](#禁用状态)

您可以设置 InputTag 被禁用。

tag1tag2tag3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtdGFnIHYtbW9kZWw9XCJpbnB1dFwiIGRpc2FibGVkIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCIgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGlucHV0ID0gcmVmPHN0cmluZ1tdPihbJ3RhZzEnLCAndGFnMicsICd0YWczJ10pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/disabled.vue)_

vue

```
<template>
  <el-input-tag v-model="input" disabled placeholder="Please input" />
</template>

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

const input = ref<string[]>(['tag1', 'tag2', 'tag3'])
</script>
```

隐藏源代码

## 可清空 [​](#可清空)

您可以设置是否显示清除按钮。

tag1tag2tag3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtdGFnIHYtbW9kZWw9XCJpbnB1dFwiIGNsZWFyYWJsZSBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBpbnB1dCA9IHJlZjxzdHJpbmdbXT4oWyd0YWcxJywgJ3RhZzInLCAndGFnMyddKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/clearable.vue)_

vue

```
<template>
  <el-input-tag v-model="input" clearable placeholder="Please input" />
</template>

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

const input = ref<string[]>(['tag1', 'tag2', 'tag3'])
</script>
```

隐藏源代码

## 自定义清除图标2.11.0 [​](#自定义清除图标)

你可以通过`clear-icon`属性自定义清除图标

customclearicon

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtdGFnXG4gICAgdi1tb2RlbD1cImlucHV0XCJcbiAgICBjbGVhcmFibGVcbiAgICA6Y2xlYXItaWNvbj1cIkNsb3NlQm9sZFwiXG4gICAgcGxhY2Vob2xkZXI9XCJDdXN0b20gY2xlYXIgaWNvblwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgQ2xvc2VCb2xkIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmNvbnN0IGlucHV0ID0gcmVmPHN0cmluZ1tdPihbJ2N1c3RvbScsICdjbGVhcicsICdpY29uJ10pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/clear-icon.vue)_

vue

```
<template>
  <el-input-tag
    v-model="input"
    clearable
    :clear-icon="CloseBold"
    placeholder="Custom clear icon"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { CloseBold } from '@element-plus/icons-vue'

const input = ref<string[]>(['custom', 'clear', 'icon'])
</script>
```

隐藏源代码

## 可拖放 [​](#可拖放)

您可以设置是否可以拖动标签。

tag1tag2tag3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtdGFnIHYtbW9kZWw9XCJpbnB1dFwiIGRyYWdnYWJsZSBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBpbnB1dCA9IHJlZjxzdHJpbmdbXT4oWyd0YWcxJywgJ3RhZzInLCAndGFnMyddKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/draggable.vue)_

vue

```
<template>
  <el-input-tag v-model="input" draggable placeholder="Please input" />
</template>

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

const input = ref<string[]>(['tag1', 'tag2', 'tag3'])
</script>
```

隐藏源代码

## 分隔符2.9.9 [​](#分隔符)

当一个分隔符匹配时，您可以添加一个标签。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtdGFnXG4gICAgdi1tb2RlbD1cImlucHV0XCJcbiAgICBkcmFnZ2FibGVcbiAgICBwbGFjZWhvbGRlcj1cIlRyeSB0byBzZXBhcmF0ZSB3b3JkcyB3aXRoICxcIlxuICAgIGRlbGltaXRlcj1cIixcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5wdXQgPSByZWY8c3RyaW5nW10+KFtdKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/delimiter.vue)_

vue

```
<template>
  <el-input-tag
    v-model="input"
    draggable
    placeholder="Try to separate words with ,"
    delimiter=","
  />
</template>

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

const input = ref<string[]>([])
</script>
```

隐藏源代码

## 尺寸 [​](#尺寸)

使用 `size` 属性改变输入框大小。 除了默认大小外，还有另外两个选项： `large`, `small`。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtdGFnIHYtbW9kZWw9XCJpbnB1dFwiIHNpemU9XCJsYXJnZVwiIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCIgLz5cbiAgPGJyIC8+XG4gIDxlbC1pbnB1dC10YWcgdi1tb2RlbD1cImlucHV0XCIgcGxhY2Vob2xkZXI9XCJQbGVhc2UgaW5wdXRcIiAvPlxuICA8YnIgLz5cbiAgPGVsLWlucHV0LXRhZyB2LW1vZGVsPVwiaW5wdXRcIiBzaXplPVwic21hbGxcIiBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBpbnB1dCA9IHJlZjxzdHJpbmdbXT4oKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/size.vue)_

vue

```
<template>
  <el-input-tag v-model="input" size="large" placeholder="Please input" />
  <br />
  <el-input-tag v-model="input" placeholder="Please input" />
  <br />
  <el-input-tag v-model="input" size="small" placeholder="Please input" />
</template>

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

const input = ref<string[]>()
</script>
```

隐藏源代码

## 自定义标签 [​](#自定义标签)

您可以通过`tag`插槽自定义标签内容。

primary

success

info

warning

danger

light

dark

plain

tag1

tag2

tag3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1zZWdtZW50ZWQgdi1tb2RlbD1cInRhZ1R5cGVcIiA6b3B0aW9ucz1cInR5cGVcIiBjbGFzcz1cIm1yLTVcIiAvPlxuICAgIDxlbC1zZWdtZW50ZWQgdi1tb2RlbD1cInRhZ0VmZmVjdFwiIDpvcHRpb25zPVwiZWZmZWN0XCIgLz5cbiAgPC9kaXY+XG4gIDxiciAvPlxuICA8ZWwtaW5wdXQtdGFnXG4gICAgdi1tb2RlbD1cImlucHV0XCJcbiAgICA6dGFnLXR5cGU9XCJ0YWdUeXBlXCJcbiAgICA6dGFnLWVmZmVjdD1cInRhZ0VmZmVjdFwiXG4gICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgaW5wdXRcIlxuICA+XG4gICAgPHRlbXBsYXRlICN0YWc9XCJ7IHZhbHVlIH1cIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJmbGV4IGl0ZW1zLWNlbnRlclwiPlxuICAgICAgICA8ZWwtaWNvbiBjbGFzcz1cIm1yLTFcIj5cbiAgICAgICAgICA8RWxlbWVudFBsdXMgLz5cbiAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICA8c3Bhbj57eyB2YWx1ZSB9fTwvc3Bhbj5cbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtaW5wdXQtdGFnPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVsZW1lbnRQbHVzIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmltcG9ydCB0eXBlIHsgVGFnUHJvcHMgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHR5cGU6IEFycmF5PFRhZ1Byb3BzWyd0eXBlJ10+ID0gW1xuICAncHJpbWFyeScsXG4gICdzdWNjZXNzJyxcbiAgJ2luZm8nLFxuICAnd2FybmluZycsXG4gICdkYW5nZXInLFxuXVxuY29uc3QgZWZmZWN0OiBBcnJheTxUYWdQcm9wc1snZWZmZWN0J10+ID0gWydsaWdodCcsICdkYXJrJywgJ3BsYWluJ11cblxuY29uc3QgdGFnVHlwZSA9IHJlZjxUYWdQcm9wc1sndHlwZSddPigncHJpbWFyeScpXG5jb25zdCB0YWdFZmZlY3QgPSByZWY8VGFnUHJvcHNbJ2VmZmVjdCddPigncGxhaW4nKVxuY29uc3QgaW5wdXQgPSByZWY8c3RyaW5nW10+KFsndGFnMScsICd0YWcyJywgJ3RhZzMnXSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/tag.vue)_

vue

```
<template>
  <div>
    <el-segmented v-model="tagType" :options="type" class="mr-5" />
    <el-segmented v-model="tagEffect" :options="effect" />
  </div>
  <br />
  <el-input-tag
    v-model="input"
    :tag-type="tagType"
    :tag-effect="tagEffect"
    placeholder="Please input"
  >
    <template #tag="{ value }">
      <div class="flex items-center">
        <el-icon class="mr-1">
          <ElementPlus />
        </el-icon>
        <span>{{ value }}</span>
      </div>
    </template>
  </el-input-tag>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElementPlus } from '@element-plus/icons-vue'

import type { TagProps } from 'element-plus'

const type: Array<TagProps['type']> = [
  'primary',
  'success',
  'info',
  'warning',
  'danger',
]
const effect: Array<TagProps['effect']> = ['light', 'dark', 'plain']

const tagType = ref<TagProps['type']>('primary')
const tagEffect = ref<TagProps['effect']>('plain')
const input = ref<string[]>(['tag1', 'tag2', 'tag3'])
</script>
```

隐藏源代码

## 自定义前缀和后缀 [​](#自定义前缀和后缀)

您可以通过`prefix`和 `suffix` 插槽自定义 InputTag 的前缀和后缀。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXQtdGFnIHYtbW9kZWw9XCJpbnB1dFwiIGNsZWFyYWJsZSBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiPlxuICAgIDx0ZW1wbGF0ZSAjcHJlZml4PlxuICAgICAgPGVsLWljb24+PEVsZW1lbnRQbHVzIC8+PC9lbC1pY29uPlxuICAgIDwvdGVtcGxhdGU+XG4gICAgPHRlbXBsYXRlICNzdWZmaXg+XG4gICAgICA8ZWwtaWNvbj48U2VhcmNoIC8+PC9lbC1pY29uPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtaW5wdXQtdGFnPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVsZW1lbnRQbHVzLCBTZWFyY2ggfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgaW5wdXQgPSByZWY8c3RyaW5nW10+KClcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-tag/prefix-suffix.vue)_

vue

```
<template>
  <el-input-tag v-model="input" clearable placeholder="Please input">
    <template #prefix>
      <el-icon><ElementPlus /></el-icon>
    </template>
    <template #suffix>
      <el-icon><Search /></el-icon>
    </template>
  </el-input-tag>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElementPlus, Search } from '@element-plus/icons-vue'

const input = ref<string[]>()
</script>
```

隐藏源代码

## API [​](#api)

### 属性 [​](#属性)

| 名称 | 详情 | 类型 | 默认 |
| --- | --- | --- | --- |
| model-value / v-model | 绑定值 | `array` | — |
| max | 可添加标签的最大数量 | `number` | — |
| tag-type | 标签类型 | `enum` | info |
| tag-effect | 标签效果 | `enum` | light |
| effect 2.13.2 | tooltip 主题，内置了 `dark` / `light` 两种 | `enum``'dark' | 'light'` / `string` | light |
| trigger | 触发输入标签的按键 | `enum` | Enter |
| draggable | 是否可以拖动标签 | `boolean` | false |
| delimiter 2.9.9 | 在匹配分隔符时添加标签 | `string` / `regex` | — |
| size | 输入框尺寸 | `enum` | — |
| collapse-tags 2.11.0 | 多选时是否将选中值按文字的形式展示 | `boolean` | false |
| collapse-tags-tooltip 2.11.0 | 当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此功能，`collapse-tags`的值必须为true | `boolean` | false |
| save-on-blur 2.9.7 | 当输入失去焦点时是否保存输入值 | `boolean` | true |
| clearable | 是否显示清除按钮 | `boolean` | false |
| clear-icon 2.11.0 | 自定义清除图标 | `string` / `object` | CircleClose |
| disabled | 是否禁用 | `boolean` | false |
| validate-event | 是否触发表单验证 | `boolean` | true |
| readonly | 等价于原生 `readonly` 属性 | `boolean` | false |
| autofocus | 等价于原生 `autofocus` 属性 | `boolean` | false |
| id | 等价于原生 input `id` 属性 | `string` | — |
| tabindex | 等价于原生 `tabindex` 属性 | `string` / `number` | — |
| max-collapse-tags 2.11.0 | 需要显示的 Tag 的最大数量 要使用此功能，`collapse-tags`的值必须为true | `number` | 1 |
| maxlength | 等价于原生 `maxlength` 属性 | `string` / `number` | — |
| minlength | 等价于原生 `minlength` 属性 | `string` / `number` | — |
| placeholder | 输入框占位文本 | `string` | — |
| autocomplete | 等价于原生 `autocomplete` 属性 | `string` | off |
| aria-label a11y | 等价于原生 `aria-label` 属性 | `string` | — |

### 事件 [​](#事件)

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| change | 绑定值变化时触发的事件 | `Function` |
| input | 在 Input 值改变时触发 | `Function` |
| add-tag | tag 被添加时触发 | `Function` |
| remove-tag | tag 被移除时触发 | `Function` |
| drag-tag 2.11.3 | tag 被拖动时触发 | `Function` |
| focus | 在 Input 获得焦点时触发 | `Function` |
| blur | 在 Input 失去焦点时触发 | `Function` |
| clear | 点击清除图标时触发 | `Function` |

### Slots [​](#slots)

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| tag | 作为tag的内容 | `object` |
| prefix | InputTag 头部内容 | — |
| suffix | InputTag 尾部内容 | — |

### 对外暴露的方法 [​](#对外暴露的方法)

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| focus | 使 input 获取焦点 | `Function` |
| blur | 使 input 失去焦点 | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/input-tag) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/input-tag.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/input-tag.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/189838704?v=4&size=64)](https://github.com/xiaocainiao633)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/69999356?v=4&size=64)](https://github.com/ll-huihui)[![](https://avatars.githubusercontent.com/u/32569372?v=4&size=64)](https://github.com/eighty-cents)[![](https://avatars.githubusercontent.com/u/49630878?v=4&size=64)](https://github.com/a869246700)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/66454152?v=4&size=64)](https://github.com/bryqiu)

[Input Number 数字输入框](https://element-plus.org/zh-CN/component/input-number)

[Input OTP](https://element-plus.org/zh-CN/component/input-otp)




---
## [form/input-otp] Input OTP
> 官方文档: https://element-plus.org/zh-CN/component/input-otp.html

---

# InputOtp 一次性密码输入框 beta [​](#inputotp-一次性密码输入框)

更新日志待解决

0

用于输入一次性密码

## 基础用法 [​](#基础用法)

Value: 123

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1pbnB1dC1vdHAgdi1tb2RlbD1cIm90cFwiIC8+XG4gICAgPGRpdiBzdHlsZT1cIm1hcmdpbi10b3A6IDIwcHhcIj5WYWx1ZToge3sgb3RwIH19PC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3Qgb3RwID0gcmVmKCcxMjMnKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-otp/basic.vue)_

vue

```
<template>
  <div>
    <el-input-otp v-model="otp" />
    <div style="margin-top: 20px">Value: {{ otp }}</div>
  </div>
</template>

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

const otp = ref('123')
</script>
```

隐藏源代码

## 自定义长度 [​](#自定义长度)

输入字段长度可以通过设置`length`属性来自定义。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbnB1dC1vdHBcIj5cbiAgICA8ZWwtaW5wdXQtb3RwIHYtbW9kZWw9XCJvdHAxXCIgOmxlbmd0aD1cIjRcIiAvPlxuICAgIDxlbC1pbnB1dC1vdHAgdi1tb2RlbD1cIm90cDJcIiA6bGVuZ3RoPVwiOFwiIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3Qgb3RwMSA9IHJlZignJylcbmNvbnN0IG90cDIgPSByZWYoJycpXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWlucHV0LW90cCB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGZsZXgtZGlyZWN0aW9uOiBjb2x1bW47XG4gIGdhcDogMjBweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-otp/custom-length.vue)_

vue

```
<template>
  <div class="demo-input-otp">
    <el-input-otp v-model="otp1" :length="4" />
    <el-input-otp v-model="otp2" :length="8" />
  </div>
</template>

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

const otp1 = ref('')
const otp2 = ref('')
</script>

<style scoped>
.demo-input-otp {
  display: flex;
  flex-direction: column;
  gap: 20px;
}
</style>
```

隐藏源代码

## 展示类型 [​](#展示类型)

有三种类型可用：`outlined` （默认）、`filled` 和 `underlined`。

Outlined (Default)

Filled

Underlined

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbnB1dC1vdHBcIj5cbiAgICA8ZGl2PlxuICAgICAgPHA+T3V0bGluZWQgKERlZmF1bHQpPC9wPlxuICAgICAgPGVsLWlucHV0LW90cCB2LW1vZGVsPVwib3RwMVwiIHR5cGU9XCJvdXRsaW5lZFwiIC8+XG4gICAgPC9kaXY+XG4gICAgPGRpdj5cbiAgICAgIDxwPkZpbGxlZDwvcD5cbiAgICAgIDxlbC1pbnB1dC1vdHAgdi1tb2RlbD1cIm90cDJcIiB0eXBlPVwiZmlsbGVkXCIgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2PlxuICAgICAgPHA+VW5kZXJsaW5lZDwvcD5cbiAgICAgIDxlbC1pbnB1dC1vdHAgdi1tb2RlbD1cIm90cDNcIiB0eXBlPVwidW5kZXJsaW5lZFwiIC8+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3Qgb3RwMSA9IHJlZignJylcbmNvbnN0IG90cDIgPSByZWYoJycpXG5jb25zdCBvdHAzID0gcmVmKCcnKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1pbnB1dC1vdHAge1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LWRpcmVjdGlvbjogY29sdW1uO1xuICBnYXA6IDIwcHg7XG59XG5cbnAge1xuICBtYXJnaW4tYm90dG9tOiA4cHg7XG4gIGZvbnQtc2l6ZTogMTRweDtcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-otp/types.vue)_

vue

```
<template>
  <div class="demo-input-otp">
    <div>
      <p>Outlined (Default)</p>
      <el-input-otp v-model="otp1" type="outlined" />
    </div>
    <div>
      <p>Filled</p>
      <el-input-otp v-model="otp2" type="filled" />
    </div>
    <div>
      <p>Underlined</p>
      <el-input-otp v-model="otp3" type="underlined" />
    </div>
  </div>
</template>

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

const otp1 = ref('')
const otp2 = ref('')
const otp3 = ref('')
</script>

<style scoped>
.demo-input-otp {
  display: flex;
  flex-direction: column;
  gap: 20px;
}

p {
  margin-bottom: 8px;
  font-size: 14px;
  color: var(--el-text-color-secondary);
}
</style>
```

隐藏源代码

## 调整尺寸 [​](#调整尺寸)

有三个尺寸可用：`large`、`default` 和 `small`。

Large

Default

Small

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbnB1dC1vdHBcIj5cbiAgICA8ZGl2PlxuICAgICAgPHA+TGFyZ2U8L3A+XG4gICAgICA8ZWwtaW5wdXQtb3RwIHYtbW9kZWw9XCJvdHAxXCIgc2l6ZT1cImxhcmdlXCIgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2PlxuICAgICAgPHA+RGVmYXVsdDwvcD5cbiAgICAgIDxlbC1pbnB1dC1vdHAgdi1tb2RlbD1cIm90cDJcIiBzaXplPVwiZGVmYXVsdFwiIC8+XG4gICAgPC9kaXY+XG4gICAgPGRpdj5cbiAgICAgIDxwPlNtYWxsPC9wPlxuICAgICAgPGVsLWlucHV0LW90cCB2LW1vZGVsPVwib3RwM1wiIHNpemU9XCJzbWFsbFwiIC8+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3Qgb3RwMSA9IHJlZignJylcbmNvbnN0IG90cDIgPSByZWYoJycpXG5jb25zdCBvdHAzID0gcmVmKCcnKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1pbnB1dC1vdHAge1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LWRpcmVjdGlvbjogY29sdW1uO1xuICBnYXA6IDIwcHg7XG59XG5cbnAge1xuICBtYXJnaW4tYm90dG9tOiA4cHg7XG4gIGZvbnQtc2l6ZTogMTRweDtcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-otp/sizes.vue)_

vue

```
<template>
  <div class="demo-input-otp">
    <div>
      <p>Large</p>
      <el-input-otp v-model="otp1" size="large" />
    </div>
    <div>
      <p>Default</p>
      <el-input-otp v-model="otp2" size="default" />
    </div>
    <div>
      <p>Small</p>
      <el-input-otp v-model="otp3" size="small" />
    </div>
  </div>
</template>

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

const otp1 = ref('')
const otp2 = ref('')
const otp3 = ref('')
</script>

<style scoped>
.demo-input-otp {
  display: flex;
  flex-direction: column;
  gap: 20px;
}

p {
  margin-bottom: 8px;
  font-size: 14px;
  color: var(--el-text-color-secondary);
}
</style>
```

隐藏源代码

## 禁用 & 只读 [​](#禁用-只读)

支持禁用和只读状态。

Disabled

Readonly

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbnB1dC1vdHBcIj5cbiAgICA8ZGl2IGNsYXNzPVwidHlwZS13cmFwXCI+XG4gICAgICA8cD5EaXNhYmxlZDwvcD5cbiAgICAgIDxlbC1pbnB1dC1vdHAgdi1tb2RlbD1cIm90cDFcIiBkaXNhYmxlZCAvPlxuICAgICAgPGVsLWlucHV0LW90cCB2LW1vZGVsPVwib3RwMVwiIGRpc2FibGVkIHR5cGU9XCJmaWxsZWRcIiAvPlxuICAgICAgPGVsLWlucHV0LW90cCB2LW1vZGVsPVwib3RwMVwiIGRpc2FibGVkIHR5cGU9XCJ1bmRlcmxpbmVkXCIgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwidHlwZS13cmFwXCI+XG4gICAgICA8cD5SZWFkb25seTwvcD5cbiAgICAgIDxlbC1pbnB1dC1vdHAgdi1tb2RlbD1cIm90cDJcIiByZWFkb25seSAvPlxuICAgICAgPGVsLWlucHV0LW90cCB2LW1vZGVsPVwib3RwMlwiIHJlYWRvbmx5IHR5cGU9XCJmaWxsZWRcIiAvPlxuICAgICAgPGVsLWlucHV0LW90cCB2LW1vZGVsPVwib3RwMlwiIHJlYWRvbmx5IHR5cGU9XCJ1bmRlcmxpbmVkXCIgLz5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBvdHAxID0gcmVmKCcxMjMnKVxuY29uc3Qgb3RwMiA9IHJlZignNDU2Jylcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8taW5wdXQtb3RwIHtcbiAgZGlzcGxheTogZmxleDtcbiAgZmxleC1kaXJlY3Rpb246IGNvbHVtbjtcbiAgZ2FwOiAyMHB4O1xufVxuXG4udHlwZS13cmFwIHtcbiAgZGlzcGxheTogZmxleDtcbiAgZmxleC1kaXJlY3Rpb246IGNvbHVtbjtcbiAgZ2FwOiAxMnB4O1xufVxuXG5wIHtcbiAgbWFyZ2luLWJvdHRvbTogOHB4O1xuICBmb250LXNpemU6IDE0cHg7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-otp/disabled.vue)_

vue

```
<template>
  <div class="demo-input-otp">
    <div class="type-wrap">
      <p>Disabled</p>
      <el-input-otp v-model="otp1" disabled />
      <el-input-otp v-model="otp1" disabled type="filled" />
      <el-input-otp v-model="otp1" disabled type="underlined" />
    </div>
    <div class="type-wrap">
      <p>Readonly</p>
      <el-input-otp v-model="otp2" readonly />
      <el-input-otp v-model="otp2" readonly type="filled" />
      <el-input-otp v-model="otp2" readonly type="underlined" />
    </div>
  </div>
</template>

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

const otp1 = ref('123')
const otp2 = ref('456')
</script>

<style scoped>
.demo-input-otp {
  display: flex;
  flex-direction: column;
  gap: 20px;
}

.type-wrap {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

p {
  margin-bottom: 8px;
  font-size: 14px;
  color: var(--el-text-color-secondary);
}
</style>
```

隐藏源代码

## 密码模式 [​](#密码模式)

使用 `mask` 属性来隐藏输入字符。

Value: 123

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1pbnB1dC1vdHAgdi1tb2RlbD1cIm90cFwiIG1hc2sgLz5cbiAgICA8ZGl2IHN0eWxlPVwibWFyZ2luLXRvcDogMjBweFwiPlZhbHVlOiB7eyBvdHAgfX08L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBvdHAgPSByZWYoJzEyMycpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-otp/mask.vue)_

vue

```
<template>
  <div>
    <el-input-otp v-model="otp" mask />
    <div style="margin-top: 20px">Value: {{ otp }}</div>
  </div>
</template>

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

const otp = ref('123')
</script>
```

隐藏源代码

## 分隔符 [​](#分隔符)

自定义OTP字段之间的分隔符。

/////

——

•••••

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbnB1dC1vdHBcIj5cbiAgICA8ZWwtaW5wdXQtb3RwIHNlcGFyYXRvcj1cIi9cIiAvPlxuICAgIDxlbC1pbnB1dC1vdHAgOnNlcGFyYXRvcj1cImNhc3RTZXBhcmF0b3JcIiAvPlxuICAgIDxlbC1pbnB1dC1vdHA+XG4gICAgICA8dGVtcGxhdGUgI3NlcGFyYXRvcj7igKI8L3RlbXBsYXRlPlxuICAgIDwvZWwtaW5wdXQtb3RwPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+XG5pbXBvcnQgeyBoIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBjYXN0U2VwYXJhdG9yID0gKGluZGV4OiBudW1iZXIpID0+IHtcbiAgcmV0dXJuIGluZGV4ICYgMSA/IGgoJ3NwYW4nLCBudWxsLCAn4oCUJykgOiAnJ1xufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1pbnB1dC1vdHAge1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LWRpcmVjdGlvbjogY29sdW1uO1xuICBnYXA6IDIwcHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-otp/separator.vue)_

vue

```
<template>
  <div class="demo-input-otp">
    <el-input-otp separator="/" />
    <el-input-otp :separator="castSeparator" />
    <el-input-otp>
      <template #separator>•</template>
    </el-input-otp>
  </div>
</template>

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

const castSeparator = (index: number) => {
  return index & 1 ? h('span', null, '—') : ''
}
</script>

<style scoped>
.demo-input-otp {
  display: flex;
  flex-direction: column;
  gap: 20px;
}
</style>
```

隐藏源代码

## 自定义验证 [​](#自定义验证)

设置 `validator` 属性以验证输入字符，并使用 `inputmode` 指定键盘类型。

Numbers only

Letters only

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbnB1dC1vdHBcIj5cbiAgICA8ZGl2PlxuICAgICAgPHA+TnVtYmVycyBvbmx5PC9wPlxuICAgICAgPGVsLWlucHV0LW90cFxuICAgICAgICB2LW1vZGVsPVwib3RwMVwiXG4gICAgICAgIDp2YWxpZGF0b3I9XCJvbmx5QWxsb3dOdW1iZXJcIlxuICAgICAgICBpbnB1dG1vZGU9XCJudW1lcmljXCJcbiAgICAgIC8+XG4gICAgPC9kaXY+XG4gICAgPGRpdj5cbiAgICAgIDxwPkxldHRlcnMgb25seTwvcD5cbiAgICAgIDxlbC1pbnB1dC1vdHAgdi1tb2RlbD1cIm90cDJcIiA6dmFsaWRhdG9yPVwib25seUFsbG93TGV0dGVyXCIgLz5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBvdHAxID0gcmVmKCcnKVxuY29uc3Qgb3RwMiA9IHJlZignJylcblxuY29uc3Qgb25seUFsbG93TnVtYmVyID0gKHZhbHVlOiBzdHJpbmcpID0+IC9eXFxkJC8udGVzdCh2YWx1ZSlcbmNvbnN0IG9ubHlBbGxvd0xldHRlciA9ICh2YWx1ZTogc3RyaW5nKSA9PiAvXlthLXpBLVpdJC8udGVzdCh2YWx1ZSlcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8taW5wdXQtb3RwIHtcbiAgZGlzcGxheTogZmxleDtcbiAgZmxleC1kaXJlY3Rpb246IGNvbHVtbjtcbiAgZ2FwOiAyMHB4O1xufVxuXG5wIHtcbiAgbWFyZ2luLWJvdHRvbTogOHB4O1xuICBmb250LXNpemU6IDE0cHg7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/input-otp/validator.vue)_

vue

```
<template>
  <div class="demo-input-otp">
    <div>
      <p>Numbers only</p>
      <el-input-otp
        v-model="otp1"
        :validator="onlyAllowNumber"
        inputmode="numeric"
      />
    </div>
    <div>
      <p>Letters only</p>
      <el-input-otp v-model="otp2" :validator="onlyAllowLetter" />
    </div>
  </div>
</template>

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

const otp1 = ref('')
const otp2 = ref('')

const onlyAllowNumber = (value: string) => /^\d$/.test(value)
const onlyAllowLetter = (value: string) => /^[a-zA-Z]$/.test(value)
</script>

<style scoped>
.demo-input-otp {
  display: flex;
  flex-direction: column;
  gap: 20px;
}

p {
  margin-bottom: 8px;
  font-size: 14px;
  color: var(--el-text-color-secondary);
}
</style>
```

隐藏源代码

## 应用开发接口（API） [​](#应用开发接口-api)

### 属性 [​](#属性)

| 插槽名 | 详情 | 事件参数 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | OTP字段的值。 由于数字不能有前导零，`modelValue` 仅在初始化期间允许为数字。 | `string` / `number` | undefined |
| length | OTP字段长度 | `number` | 6 |
| validator | 自定义验证函数 | `Function` | () => true |
| inputmode | 原生 `inputmode` 属性 | `string` | — |
| type | OTP字段类型 | `enum` | 'outlined' |
| size | OTP字段的尺寸 | `enum` | 'default' |
| mask | 是否启用密码模式 | `boolean` | — |
| disabled | 是否禁用OTP字段 | `boolean` | undefined |
| separator | OTP字段之间的分隔符 | `string` / `VNode` / `Function` | — |
| validate-event | 是否触发表单验证 | `boolean` | true |
| readonly | 与原生输入中的 `readonly` 相同 | `boolean` | false |
| id | 原生 `id` 属性 | `string` | — |
| aria-label a11y | 原生 `aria-label` 属性 | `string` | — |

### Events [​](#events)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| update:modelValue | 值更新时触发 | `Function` |
| change | 当输入框失去焦点后且值发生变化时触发 | `Function` |
| finish | 当所有字段都已填写时触发 | `Function` |
| focus | 输入框获得焦点时触发 | `Function` |
| blur | 输入框失去焦点时触发 | `Function` |

### 插槽 [​](#插槽)

| 方法名 | 详情 | 事件参数 |
| --- | --- | --- |
| separator | OTP 字段之间的分隔符 | `object` |

### 对外暴露的方法 [​](#对外暴露的方法)

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| inputRefs | HTML 输入框元素数组 | `object` |
| focus | 聚焦OTP输入字段 | `Function` |
| blur | 失焦OTP输入字段 | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/input-otp) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/input-otp.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/input-otp.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/166777320?v=4&size=64)](https://github.com/ixyzorg)

[Input Tag 标签输入框](https://element-plus.org/zh-CN/component/input-tag)

[Mention 提及](https://element-plus.org/zh-CN/component/mention)




---
## [form/mention] Mention 提及
> 官方文档: https://element-plus.org/zh-CN/component/mention.html

---

# Mention 提及 [​](#mention-提及)

更新日志待解决

1

用于在输入中提及某人或某事。

## 基础用法 [​](#基础用法)

最简单的用法。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtbWVudGlvblxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICBzdHlsZT1cIndpZHRoOiAzMjBweFwiXG4gICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgaW5wdXRcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoJ0AnKVxuXG5jb25zdCBvcHRpb25zID0gcmVmKFtcbiAge1xuICAgIGxhYmVsOiAnRnVwaG9lbml4ZXMnLFxuICAgIHZhbHVlOiAnRnVwaG9lbml4ZXMnLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdrb29yaW9va2FtaScsXG4gICAgdmFsdWU6ICdrb29yaW9va2FtaScsXG4gIH0sXG4gIHtcbiAgICBsYWJlbDogJ0plcmVteScsXG4gICAgdmFsdWU6ICdKZXJlbXknLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdidGVhJyxcbiAgICB2YWx1ZTogJ2J0ZWEnLFxuICB9LFxuXSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/mention/basic.vue)_

vue

```
<template>
  <el-mention
    v-model="value"
    :options="options"
    style="width: 320px"
    placeholder="Please input"
  />
</template>

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

const value = ref('@')

const options = ref([
  {
    label: 'Fuphoenixes',
    value: 'Fuphoenixes',
  },
  {
    label: 'kooriookami',
    value: 'kooriookami',
  },
  {
    label: 'Jeremy',
    value: 'Jeremy',
  },
  {
    label: 'btea',
    value: 'btea',
  },
])
</script>
```

隐藏源代码

## Props 2.11.3 [​](#props)

你可以通过 `props` 属性自定义 `options` 的别名。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtbWVudGlvblxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgc3R5bGU9XCJ3aWR0aDogMzIwcHhcIlxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKCdAJylcbmNvbnN0IHByb3BzID0geyBsYWJlbDogJ25hbWUnLCB2YWx1ZTogJ2lkJywgZGlzYWJsZWQ6ICd1bmFibGUnIH1cbmNvbnN0IG9wdGlvbnMgPSByZWYoW1xuICB7XG4gICAgbmFtZTogJ0Z1cGhvZW5peGVzJyxcbiAgICBpZDogJ0Z1cGhvZW5peGVzJyxcbiAgICB1bmFibGU6IHRydWUsXG4gIH0sXG4gIHtcbiAgICBuYW1lOiAna29vcmlvb2thbWknLFxuICAgIGlkOiAna29vcmlvb2thbWknLFxuICB9LFxuICB7XG4gICAgbmFtZTogJ0plcmVteScsXG4gICAgaWQ6ICdKZXJlbXknLFxuICAgIHVuYWJsZTogdHJ1ZSxcbiAgfSxcbiAge1xuICAgIG5hbWU6ICdidGVhJyxcbiAgICBpZDogJ2J0ZWEnLFxuICB9LFxuXSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/mention/props.vue)_

vue

```
<template>
  <el-mention
    v-model="value"
    :options="options"
    :props="props"
    style="width: 320px"
    placeholder="Please input"
  />
</template>

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

const value = ref('@')
const props = { label: 'name', value: 'id', disabled: 'unable' }
const options = ref([
  {
    name: 'Fuphoenixes',
    id: 'Fuphoenixes',
    unable: true,
  },
  {
    name: 'kooriookami',
    id: 'kooriookami',
  },
  {
    name: 'Jeremy',
    id: 'Jeremy',
    unable: true,
  },
  {
    name: 'btea',
    id: 'btea',
  },
])
</script>
```

隐藏源代码

## Textarea [​](#textarea)

输入类型可以设置为 `textarea` 。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtbWVudGlvblxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgdHlwZT1cInRleHRhcmVhXCJcbiAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgIHN0eWxlPVwid2lkdGg6IDMyMHB4XCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZignJylcblxuY29uc3Qgb3B0aW9ucyA9IHJlZihbXG4gIHtcbiAgICBsYWJlbDogJ0Z1cGhvZW5peGVzJyxcbiAgICB2YWx1ZTogJ0Z1cGhvZW5peGVzJyxcbiAgfSxcbiAge1xuICAgIGxhYmVsOiAna29vcmlvb2thbWknLFxuICAgIHZhbHVlOiAna29vcmlvb2thbWknLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdKZXJlbXknLFxuICAgIHZhbHVlOiAnSmVyZW15JyxcbiAgfSxcbiAge1xuICAgIGxhYmVsOiAnYnRlYScsXG4gICAgdmFsdWU6ICdidGVhJyxcbiAgfSxcbl0pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/mention/textarea.vue)_

vue

```
<template>
  <el-mention
    v-model="value"
    type="textarea"
    :options="options"
    style="width: 320px"
    placeholder="Please input"
  />
</template>

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

const value = ref('')

const options = ref([
  {
    label: 'Fuphoenixes',
    value: 'Fuphoenixes',
  },
  {
    label: 'kooriookami',
    value: 'kooriookami',
  },
  {
    label: 'Jeremy',
    value: 'Jeremy',
  },
  {
    label: 'btea',
    value: 'btea',
  },
])
</script>
```

隐藏源代码

## 自定义标签 [​](#自定义标签)

使用 "label" 自定义标签。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtbWVudGlvblxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICBzdHlsZT1cIndpZHRoOiAzMjBweFwiXG4gICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgaW5wdXRcIlxuICA+XG4gICAgPHRlbXBsYXRlICNsYWJlbD1cInsgaXRlbSB9XCI+XG4gICAgICA8ZGl2IHN0eWxlPVwiZGlzcGxheTogZmxleDsgYWxpZ24taXRlbXM6IGNlbnRlclwiPlxuICAgICAgICA8ZWwtYXZhdGFyIDpzaXplPVwiMjRcIiA6c3JjPVwiaXRlbS5hdmF0YXJcIiAvPlxuICAgICAgICA8c3BhbiBzdHlsZT1cIm1hcmdpbi1sZWZ0OiA2cHhcIj57eyBpdGVtLnZhbHVlIH19PC9zcGFuPlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1tZW50aW9uPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoJycpXG5cbmNvbnN0IG9wdGlvbnMgPSByZWYoW1xuICB7XG4gICAgdmFsdWU6ICdGdXBob2VuaXhlcycsXG4gICAgYXZhdGFyOiAnaHR0cHM6Ly9hdmF0YXJzLmdpdGh1YnVzZXJjb250ZW50LmNvbS91LzI3OTEyMjMyJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAna29vcmlvb2thbWknLFxuICAgIGF2YXRhcjogJ2h0dHBzOi8vYXZhdGFycy5naXRodWJ1c2VyY29udGVudC5jb20vdS8zODM5MjMxNScsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ0plcmVteScsXG4gICAgYXZhdGFyOiAnaHR0cHM6Ly9hdmF0YXJzLmdpdGh1YnVzZXJjb250ZW50LmNvbS91LzE1OTc1Nzg1JyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnYnRlYScsXG4gICAgYXZhdGFyOiAnaHR0cHM6Ly9hdmF0YXJzLmdpdGh1YnVzZXJjb250ZW50LmNvbS91LzI0NTE2NjU0JyxcbiAgfSxcbl0pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/mention/label.vue)_

vue

```
<template>
  <el-mention
    v-model="value"
    :options="options"
    style="width: 320px"
    placeholder="Please input"
  >
    <template #label="{ item }">
      <div style="display: flex; align-items: center">
        <el-avatar :size="24" :src="item.avatar" />
        <span style="margin-left: 6px">{{ item.value }}</span>
      </div>
    </template>
  </el-mention>
</template>

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

const value = ref('')

const options = ref([
  {
    value: 'Fuphoenixes',
    avatar: 'https://avatars.githubusercontent.com/u/27912232',
  },
  {
    value: 'kooriookami',
    avatar: 'https://avatars.githubusercontent.com/u/38392315',
  },
  {
    value: 'Jeremy',
    avatar: 'https://avatars.githubusercontent.com/u/15975785',
  },
  {
    value: 'btea',
    avatar: 'https://avatars.githubusercontent.com/u/24516654',
  },
])
</script>
```

隐藏源代码

## 加载远程选项 [​](#加载远程选项)

异步加载选项。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtbWVudGlvblxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICA6bG9hZGluZz1cImxvYWRpbmdcIlxuICAgIHN0eWxlPVwid2lkdGg6IDMyMHB4XCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBpbnB1dFwiXG4gICAgQHNlYXJjaD1cImhhbmRsZVNlYXJjaFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgb25CZWZvcmVVbm1vdW50LCByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgTWVudGlvbk9wdGlvbiB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgdmFsdWUgPSByZWYoJycpXG5jb25zdCBsb2FkaW5nID0gcmVmKGZhbHNlKVxuY29uc3Qgb3B0aW9ucyA9IHJlZjxNZW50aW9uT3B0aW9uW10+KFtdKVxuXG5sZXQgdGltZXI6IFJldHVyblR5cGU8dHlwZW9mIHNldFRpbWVvdXQ+XG5jb25zdCBoYW5kbGVTZWFyY2ggPSAocGF0dGVybjogc3RyaW5nKSA9PiB7XG4gIGlmICh0aW1lcikgY2xlYXJUaW1lb3V0KHRpbWVyKVxuXG4gIGxvYWRpbmcudmFsdWUgPSB0cnVlXG4gIHRpbWVyID0gc2V0VGltZW91dCgoKSA9PiB7XG4gICAgb3B0aW9ucy52YWx1ZSA9IFsnRnVwaG9lbml4ZXMnLCAna29vcmlvb2thbWknLCAnSmVyZW15JywgJ2J0ZWEnXS5tYXAoXG4gICAgICAoaXRlbSkgPT4gKHtcbiAgICAgICAgbGFiZWw6IHBhdHRlcm4gKyBpdGVtLFxuICAgICAgICB2YWx1ZTogcGF0dGVybiArIGl0ZW0sXG4gICAgICB9KVxuICAgIClcbiAgICBsb2FkaW5nLnZhbHVlID0gZmFsc2VcbiAgfSwgMTUwMClcbn1cblxub25CZWZvcmVVbm1vdW50KCgpID0+IHtcbiAgaWYgKHRpbWVyKSBjbGVhclRpbWVvdXQodGltZXIpXG59KVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/mention/loading.vue)_

vue

```
<template>
  <el-mention
    v-model="value"
    :options="options"
    :loading="loading"
    style="width: 320px"
    placeholder="Please input"
    @search="handleSearch"
  />
</template>

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

import type { MentionOption } from 'element-plus'

const value = ref('')
const loading = ref(false)
const options = ref<MentionOption[]>([])

let timer: ReturnType<typeof setTimeout>
const handleSearch = (pattern: string) => {
  if (timer) clearTimeout(timer)

  loading.value = true
  timer = setTimeout(() => {
    options.value = ['Fuphoenixes', 'kooriookami', 'Jeremy', 'btea'].map(
      (item) => ({
        label: pattern + item,
        value: pattern + item,
      })
    )
    loading.value = false
  }, 1500)
}

onBeforeUnmount(() => {
  if (timer) clearTimeout(timer)
})
</script>
```

隐藏源代码

## 自定义触发字段 [​](#自定义触发字段)

通过 `prefix` 属性 自定义触发字段。 默认为 `@`, `Array<string>` 。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtbWVudGlvblxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICA6cHJlZml4PVwiWydAJywgJyMnXVwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMzIwcHhcIlxuICAgIHBsYWNlaG9sZGVyPVwiaW5wdXQgQCB0byBtZW50aW9uIHBlb3BsZSwgIyB0byBtZW50aW9uIHRhZ1wiXG4gICAgQHNlYXJjaD1cImhhbmRsZVNlYXJjaFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IE1lbnRpb25PcHRpb24gfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IE1PQ0tfREFUQTogUmVjb3JkPHN0cmluZywgc3RyaW5nW10+ID0ge1xuICAnQCc6IFsnRnVwaG9lbml4ZXMnLCAna29vcmlvb2thbWknLCAnSmVyZW15JywgJ2J0ZWEnXSxcbiAgJyMnOiBbJzEuMCcsICcyLjAnLCAnMy4wJ10sXG59XG5jb25zdCB2YWx1ZSA9IHJlZignJylcbmNvbnN0IG9wdGlvbnMgPSByZWY8TWVudGlvbk9wdGlvbltdPihbXSlcblxuY29uc3QgaGFuZGxlU2VhcmNoID0gKF86IHN0cmluZywgcHJlZml4OiBzdHJpbmcpID0+IHtcbiAgb3B0aW9ucy52YWx1ZSA9IChNT0NLX0RBVEFbcHJlZml4XSB8fCBbXSkubWFwKCh2YWx1ZSkgPT4gKHtcbiAgICB2YWx1ZSxcbiAgfSkpXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/mention/prefix.vue)_

vue

```
<template>
  <el-mention
    v-model="value"
    :options="options"
    :prefix="['@', '#']"
    style="width: 320px"
    placeholder="input @ to mention people, # to mention tag"
    @search="handleSearch"
  />
</template>

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

import type { MentionOption } from 'element-plus'

const MOCK_DATA: Record<string, string[]> = {
  '@': ['Fuphoenixes', 'kooriookami', 'Jeremy', 'btea'],
  '#': ['1.0', '2.0', '3.0'],
}
const value = ref('')
const options = ref<MentionOption[]>([])

const handleSearch = (_: string, prefix: string) => {
  options.value = (MOCK_DATA[prefix] || []).map((value) => ({
    value,
  }))
}
</script>
```

隐藏源代码

## 整体删除 [​](#整体删除)

将`whole`属性设置为 `true`，当您按下退格键时，此处的 mention 区域将作为一个整体被删除。 设置 "check-is-whole" 属性来自定义检查逻辑。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtbWVudGlvblxuICAgIHYtbW9kZWw9XCJ2YWx1ZTFcIlxuICAgIHdob2xlXG4gICAgOm9wdGlvbnM9XCJvcHRpb25zMVwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMzIwcHhcIlxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGlucHV0XCJcbiAgLz5cbiAgPGVsLWRpdmlkZXIgLz5cbiAgPGVsLW1lbnRpb25cbiAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICA6b3B0aW9ucz1cIm9wdGlvbnMyXCJcbiAgICA6cHJlZml4PVwiWydAJywgJyMnXVwiXG4gICAgd2hvbGVcbiAgICA6Y2hlY2staXMtd2hvbGU9XCJjaGVja0lzV2hvbGVcIlxuICAgIHN0eWxlPVwid2lkdGg6IDMyMHB4XCJcbiAgICBwbGFjZWhvbGRlcj1cImlucHV0IEAgdG8gbWVudGlvbiBwZW9wbGUsICMgdG8gbWVudGlvbiB0YWdcIlxuICAgIEBzZWFyY2g9XCJoYW5kbGVTZWFyY2hcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBNZW50aW9uT3B0aW9uIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBNT0NLX0RBVEE6IFJlY29yZDxzdHJpbmcsIHN0cmluZ1tdPiA9IHtcbiAgJ0AnOiBbJ0Z1cGhvZW5peGVzJywgJ2tvb3Jpb29rYW1pJywgJ0plcmVteScsICdidGVhJ10sXG4gICcjJzogWycxLjAnLCAnMi4wJywgJzMuMCddLFxufVxuY29uc3QgdmFsdWUxID0gcmVmKCcnKVxuY29uc3QgdmFsdWUyID0gcmVmKCcnKVxuY29uc3Qgb3B0aW9uczEgPSByZWY8TWVudGlvbk9wdGlvbltdPihcbiAgTU9DS19EQVRBWydAJ10ubWFwKCh2YWx1ZSkgPT4gKHsgdmFsdWUgfSkpXG4pXG5jb25zdCBvcHRpb25zMiA9IHJlZjxNZW50aW9uT3B0aW9uW10+KFtdKVxuXG5jb25zdCBoYW5kbGVTZWFyY2ggPSAoXzogc3RyaW5nLCBwcmVmaXg6IHN0cmluZykgPT4ge1xuICBvcHRpb25zMi52YWx1ZSA9IChNT0NLX0RBVEFbcHJlZml4XSB8fCBbXSkubWFwKCh2YWx1ZSkgPT4gKHtcbiAgICB2YWx1ZSxcbiAgfSkpXG59XG5cbmNvbnN0IGNoZWNrSXNXaG9sZSA9IChwYXR0ZXJuOiBzdHJpbmcsIHByZWZpeDogc3RyaW5nKSA9PiB7XG4gIHJldHVybiAoTU9DS19EQVRBW3ByZWZpeF0gfHwgW10pLmluY2x1ZGVzKHBhdHRlcm4pXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/mention/whole.vue)_

vue

```
<template>
  <el-mention
    v-model="value1"
    whole
    :options="options1"
    style="width: 320px"
    placeholder="Please input"
  />
  <el-divider />
  <el-mention
    v-model="value2"
    :options="options2"
    :prefix="['@', '#']"
    whole
    :check-is-whole="checkIsWhole"
    style="width: 320px"
    placeholder="input @ to mention people, # to mention tag"
    @search="handleSearch"
  />
</template>

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

import type { MentionOption } from 'element-plus'

const MOCK_DATA: Record<string, string[]> = {
  '@': ['Fuphoenixes', 'kooriookami', 'Jeremy', 'btea'],
  '#': ['1.0', '2.0', '3.0'],
}
const value1 = ref('')
const value2 = ref('')
const options1 = ref<MentionOption[]>(
  MOCK_DATA['@'].map((value) => ({ value }))
)
const options2 = ref<MentionOption[]>([])

const handleSearch = (_: string, prefix: string) => {
  options2.value = (MOCK_DATA[prefix] || []).map((value) => ({
    value,
  }))
}

const checkIsWhole = (pattern: string, prefix: string) => {
  return (MOCK_DATA[prefix] || []).includes(pattern)
}
</script>
```

隐藏源代码

## 在表单里使用 [​](#在表单里使用)

与 `el-form` 一起使用

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZm9ybVxuICAgIHJlZj1cInJ1bGVGb3JtUmVmXCJcbiAgICBzdHlsZT1cIm1heC13aWR0aDogNjAwcHhcIlxuICAgIDptb2RlbD1cInJ1bGVGb3JtXCJcbiAgICA6cnVsZXM9XCJydWxlc1wiXG4gID5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwibmFtZVwiIHByb3A9XCJuYW1lXCI+XG4gICAgICA8ZWwtbWVudGlvbiB2LW1vZGVsPVwicnVsZUZvcm0ubmFtZVwiIDpvcHRpb25zPVwib3B0aW9uc1wiIC8+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cImRlc2NcIiBwcm9wPVwiZGVzY1wiPlxuICAgICAgPGVsLW1lbnRpb24gdi1tb2RlbD1cInJ1bGVGb3JtLmRlc2NcIiB0eXBlPVwidGV4dGFyZWFcIiA6b3B0aW9ucz1cIm9wdGlvbnNcIiAvPlxuICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDxlbC1mb3JtLWl0ZW0+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwic3VibWl0Rm9ybShydWxlRm9ybVJlZilcIj5cbiAgICAgICAgU3VibWl0XG4gICAgICA8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwicmVzZXRGb3JtKHJ1bGVGb3JtUmVmKVwiPlJlc2V0PC9lbC1idXR0b24+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gIDwvZWwtZm9ybT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWFjdGl2ZSwgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IEZvcm1JbnN0YW5jZSwgRm9ybVJ1bGVzIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbnRlcmZhY2UgUnVsZUZvcm0ge1xuICBuYW1lOiBzdHJpbmdcbiAgZGVzYzogc3RyaW5nXG59XG5jb25zdCBydWxlRm9ybVJlZiA9IHJlZjxGb3JtSW5zdGFuY2U+KClcbmNvbnN0IHJ1bGVGb3JtID0gcmVhY3RpdmU8UnVsZUZvcm0+KHtcbiAgbmFtZTogJycsXG4gIGRlc2M6ICcnLFxufSlcblxuY29uc3Qgb3B0aW9ucyA9IHJlZihbXG4gIHtcbiAgICBsYWJlbDogJ0Z1cGhvZW5peGVzJyxcbiAgICB2YWx1ZTogJ0Z1cGhvZW5peGVzJyxcbiAgfSxcbiAge1xuICAgIGxhYmVsOiAna29vcmlvb2thbWknLFxuICAgIHZhbHVlOiAna29vcmlvb2thbWknLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdKZXJlbXknLFxuICAgIHZhbHVlOiAnSmVyZW15JyxcbiAgfSxcbiAge1xuICAgIGxhYmVsOiAnYnRlYScsXG4gICAgdmFsdWU6ICdidGVhJyxcbiAgfSxcbl0pXG5cbmNvbnN0IHJ1bGVzID0gcmVhY3RpdmU8Rm9ybVJ1bGVzPFJ1bGVGb3JtPj4oe1xuICBuYW1lOiBbeyByZXF1aXJlZDogdHJ1ZSwgbWVzc2FnZTogJ1BsZWFzZSBpbnB1dCBuYW1lJywgdHJpZ2dlcjogJ2JsdXInIH1dLFxuICBkZXNjOiBbeyByZXF1aXJlZDogdHJ1ZSwgbWVzc2FnZTogJ1BsZWFzZSBpbnB1dCBkZXNjJywgdHJpZ2dlcjogJ2JsdXInIH1dLFxufSlcblxuY29uc3Qgc3VibWl0Rm9ybSA9IGFzeW5jIChmb3JtRWw6IEZvcm1JbnN0YW5jZSB8IHVuZGVmaW5lZCkgPT4ge1xuICBpZiAoIWZvcm1FbCkgcmV0dXJuXG4gIGF3YWl0IGZvcm1FbC52YWxpZGF0ZSgodmFsaWQsIGZpZWxkcykgPT4ge1xuICAgIGlmICh2YWxpZCkge1xuICAgICAgY29uc29sZS5sb2coJ3N1Ym1pdCEnKVxuICAgIH0gZWxzZSB7XG4gICAgICBjb25zb2xlLmxvZygnZXJyb3Igc3VibWl0IScsIGZpZWxkcylcbiAgICB9XG4gIH0pXG59XG5cbmNvbnN0IHJlc2V0Rm9ybSA9IChmb3JtRWw6IEZvcm1JbnN0YW5jZSB8IHVuZGVmaW5lZCkgPT4ge1xuICBpZiAoIWZvcm1FbCkgcmV0dXJuXG4gIGZvcm1FbC5yZXNldEZpZWxkcygpXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/mention/form.vue)_

vue

```
<template>
  <el-form
    ref="ruleFormRef"
    style="max-width: 600px"
    :model="ruleForm"
    :rules="rules"
  >
    <el-form-item label="name" prop="name">
      <el-mention v-model="ruleForm.name" :options="options" />
    </el-form-item>
    <el-form-item label="desc" prop="desc">
      <el-mention v-model="ruleForm.desc" type="textarea" :options="options" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submitForm(ruleFormRef)">
        Submit
      </el-button>
      <el-button @click="resetForm(ruleFormRef)">Reset</el-button>
    </el-form-item>
  </el-form>
</template>

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

import type { FormInstance, FormRules } from 'element-plus'

interface RuleForm {
  name: string
  desc: string
}
const ruleFormRef = ref<FormInstance>()
const ruleForm = reactive<RuleForm>({
  name: '',
  desc: '',
})

const options = ref([
  {
    label: 'Fuphoenixes',
    value: 'Fuphoenixes',
  },
  {
    label: 'kooriookami',
    value: 'kooriookami',
  },
  {
    label: 'Jeremy',
    value: 'Jeremy',
  },
  {
    label: 'btea',
    value: 'btea',
  },
])

const rules = reactive<FormRules<RuleForm>>({
  name: [{ required: true, message: 'Please input name', trigger: 'blur' }],
  desc: [{ required: true, message: 'Please input desc', trigger: 'blur' }],
})

const submitForm = async (formEl: FormInstance | undefined) => {
  if (!formEl) return
  await formEl.validate((valid, fields) => {
    if (valid) {
      console.log('submit!')
    } else {
      console.log('error submit!', fields)
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.resetFields()
}
</script>
```

隐藏源代码

TIP

由于这个组件是基于[`el-input`](https://element-plus.org/zh-CN/component/input#attributes)派生的，他们的原始属性未被更改，故不在此重复。请跳转查看原组件的相应文档。

## API [​](#api)

### 属性 [​](#属性)

| 名称 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| options | 提及选项列表 | `array` | `[]` |
| props 2.11.3 | options 的配置 | `object` | `{value: 'value', label: 'label', disabled: 'disabled'}` |
| prefix | 触发字段的前缀。 字符串长度必须且只能为 1 | `string` | `array` | `'@'` |
| split | 用于拆分提及的字符。 字符串长度必须且只能为 1 | `string` | `' '` |
| filter-option | 定制筛选器选项逻辑 | `false` | `Function` | — |
| placement | 设置弹出位置 | `string` | `'bottom'` |
| show-arrow | 下拉菜单的内容是否有箭头 | `boolean` | `false` |
| offset | 下拉面板偏移量 | `number` | `0` |
| whole | 当退格键被按下做删除操作时，是否将提及部分作为整体删除 | `boolean` | `false` |
| check-is-whole | 当退格键被按下做删除操作时，检查是否将提及部分作为整体删除 | `Function` | — |
| loading | 提及的下拉面板是否处于加载状态 | `boolean` | `false` |
| model-value / v-model | 输入值 | `string` | — |
| popper-class | 自定义浮层类名 | `string` / `object` | `string` |
| popper-style 2.11.5 | 自定义浮层类名 | `string` / `object` | — |
| popper-options | [popper.js](https://popper.js.org/docs/v2/) 参数 | `object` refer to [popper.js doc](https://popper.js.org/docs/v2/) | — |
| [input props](https://element-plus.org/zh-CN/component/input#attributes) | — | — | — |

### 事件 [​](#事件)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| search | 按下触发字段时触发 | `Function` |
| select | 当用户选择选项时触发 | `Function` |
| whole-remove 2.10.4 | 当整个 mention 被移除，且 `whole` 为 `true` 或 `check-is-whole` 为 `true` 时触发。 | `Function` |
| [input events](https://element-plus.org/zh-CN/component/input#events) | — | — |

### Slots [​](#slots)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| label | 自定义标签内容 | `object` |
| loading | 自定义 loading内容 | — |
| header | 下拉列表顶部的内容 | — |
| footer | 下拉列表底部的内容 | — |
| [input slots](https://element-plus.org/zh-CN/component/input#slots) | — | — |

### Exposes [​](#exposes)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| input | el-input 组件实例 | `object` |
| tooltip | el-tooltip 组件实例 | `object` |
| dropdownVisible 2.8.5 | tooltip 显示状态 | `object` |

## 类型声明 [​](#类型声明)

显示类型声明

ts

```
type MentionOption = {
  value?: string
  label?: string
  disabled?: boolean
  [key: string]: any
}

type MentionOptionProps = {
  value?: string
  label?: string
  disabled?: string
  [key: string]: string | undefined
}
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/mention) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/mention.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/mention.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/20411966?v=4&size=64)](https://github.com/SorrowX)[![](https://avatars.githubusercontent.com/u/27912232?v=4&size=64)](https://github.com/Fuphoenixes)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/29424213?v=4&size=64)](https://github.com/56jun)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/57785259?v=4&size=64)](https://github.com/w2xi)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/145281501?v=4&size=64)](https://github.com/typed-sigterm)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)

[Input OTP](https://element-plus.org/zh-CN/component/input-otp)

[Radio 单选框](https://element-plus.org/zh-CN/component/radio)




---
## [form/radio] Radio 单选框
> 官方文档: https://element-plus.org/zh-CN/component/radio.html

---

# Radio 单选框 [​](#radio-单选框)

更新日志待解决

12

在一组备选项中进行单选

WARNING

`label` 作为 `value` 来使用已经被 **废弃**, 建议`label` 只用来表示展示的文字，这个被废弃的用法**将会在** 3.0.0 版本被移除，请考虑使用新 API 替换.

TIP

新的 API `value` 已在 2.6.0 版本添加，文档中的示例都将使用 `value`。 如果您使用的版本 **低于** 2.6.0，请参考：

vue

```
<template>
  <el-radio-group v-model="radio1">
    <!-- works when >=2.6.0, recommended ✔️ not work when <2.6.0 ❌ -->
    <el-radio value="Value 1">Option 1</el-radio>
    <!-- works when <2.6.0, deprecated act as value when >=3.0.0 -->
    <el-radio label="Label 2 & Value 2">Option 2</el-radio>
  </el-radio-group>
</template>
```

## 基础用法 [​](#基础用法)

单选框不应该有太多的可选项， 如果你有很多的可选项你应该使用选择框而不是单选框。

要使用 Radio 组件，只需要设置`v-model`绑定变量， 选中意味着变量的值为相应 Radio `value`属性的值， `value`可以是`String`、`Number` 或 `Boolean`。

Option 1Option 2

Option 1Option 2

Option 1Option 2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibWItMiBtbC00XCI+XG4gICAgPGVsLXJhZGlvLWdyb3VwIHYtbW9kZWw9XCJyYWRpbzFcIj5cbiAgICAgIDxlbC1yYWRpbyB2YWx1ZT1cIjFcIiBzaXplPVwibGFyZ2VcIj5PcHRpb24gMTwvZWwtcmFkaW8+XG4gICAgICA8ZWwtcmFkaW8gdmFsdWU9XCIyXCIgc2l6ZT1cImxhcmdlXCI+T3B0aW9uIDI8L2VsLXJhZGlvPlxuICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibXktMiBtbC00XCI+XG4gICAgPGVsLXJhZGlvLWdyb3VwIHYtbW9kZWw9XCJyYWRpbzJcIj5cbiAgICAgIDxlbC1yYWRpbyB2YWx1ZT1cIjFcIj5PcHRpb24gMTwvZWwtcmFkaW8+XG4gICAgICA8ZWwtcmFkaW8gdmFsdWU9XCIyXCI+T3B0aW9uIDI8L2VsLXJhZGlvPlxuICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibXktNCBtbC00XCI+XG4gICAgPGVsLXJhZGlvLWdyb3VwIHYtbW9kZWw9XCJyYWRpbzNcIj5cbiAgICAgIDxlbC1yYWRpbyB2YWx1ZT1cIjFcIiBzaXplPVwic21hbGxcIj5PcHRpb24gMTwvZWwtcmFkaW8+XG4gICAgICA8ZWwtcmFkaW8gdmFsdWU9XCIyXCIgc2l6ZT1cInNtYWxsXCI+T3B0aW9uIDI8L2VsLXJhZGlvPlxuICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgcmFkaW8xID0gcmVmKCcxJylcbmNvbnN0IHJhZGlvMiA9IHJlZignMScpXG5jb25zdCByYWRpbzMgPSByZWYoJzEnKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/radio/basic-usage.vue)_

vue

```
<template>
  <div class="mb-2 ml-4">
    <el-radio-group v-model="radio1">
      <el-radio value="1" size="large">Option 1</el-radio>
      <el-radio value="2" size="large">Option 2</el-radio>
    </el-radio-group>
  </div>
  <div class="my-2 ml-4">
    <el-radio-group v-model="radio2">
      <el-radio value="1">Option 1</el-radio>
      <el-radio value="2">Option 2</el-radio>
    </el-radio-group>
  </div>
  <div class="my-4 ml-4">
    <el-radio-group v-model="radio3">
      <el-radio value="1" size="small">Option 1</el-radio>
      <el-radio value="2" size="small">Option 2</el-radio>
    </el-radio-group>
  </div>
</template>

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

const radio1 = ref('1')
const radio2 = ref('1')
const radio3 = ref('1')
</script>
```

隐藏源代码

## 禁用状态 [​](#禁用状态)

`disabled` 属性可以用来控制单选框的禁用状态。

你只需要为单选框设置 `disabled` 属性就能控制其禁用状态。

Option A Option B

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8gdi1tb2RlbD1cInJhZGlvXCIgZGlzYWJsZWQgdmFsdWU9XCJkaXNhYmxlZFwiPk9wdGlvbiBBPC9lbC1yYWRpbz5cbiAgPGVsLXJhZGlvIHYtbW9kZWw9XCJyYWRpb1wiIGRpc2FibGVkIHZhbHVlPVwic2VsZWN0ZWQgYW5kIGRpc2FibGVkXCI+XG4gICAgT3B0aW9uIEJcbiAgPC9lbC1yYWRpbz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHJhZGlvID0gcmVmKCdzZWxlY3RlZCBhbmQgZGlzYWJsZWQnKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/radio/disabled.vue)_

vue

```
<template>
  <el-radio v-model="radio" disabled value="disabled">Option A</el-radio>
  <el-radio v-model="radio" disabled value="selected and disabled">
    Option B
  </el-radio>
</template>

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

const radio = ref('selected and disabled')
</script>
```

隐藏源代码

## 单选框组 [​](#单选框组)

适用于在多个互斥的选项中选择的场景

结合`el-radio-group`元素和子元素`el-radio`可以实现单选组， 为 `el-radio-group` 绑定 `v-model`，再为 每一个 `el-radio` 设置好 `label` 属性即可， 另外，还可以通过 `change` 事件来响应变化，它会传入一个参数 `value` 来表示改变之后的值。

Option AOption BOption C

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInJhZGlvXCI+XG4gICAgPGVsLXJhZGlvIDp2YWx1ZT1cIjNcIj5PcHRpb24gQTwvZWwtcmFkaW8+XG4gICAgPGVsLXJhZGlvIDp2YWx1ZT1cIjZcIj5PcHRpb24gQjwvZWwtcmFkaW8+XG4gICAgPGVsLXJhZGlvIDp2YWx1ZT1cIjlcIj5PcHRpb24gQzwvZWwtcmFkaW8+XG4gIDwvZWwtcmFkaW8tZ3JvdXA+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCByYWRpbyA9IHJlZigzKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/radio/radio-group.vue)_

vue

```
<template>
  <el-radio-group v-model="radio">
    <el-radio :value="3">Option A</el-radio>
    <el-radio :value="6">Option B</el-radio>
    <el-radio :value="9">Option C</el-radio>
  </el-radio-group>
</template>

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

const radio = ref(3)
</script>
```

隐藏源代码

## 带有边框 [​](#带有边框)

设置 `border` 属性为 true 可以渲染为带有边框的单选框。

Option AOption B

Option AOption B

Option AOption B

Option AOption B

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1yYWRpby1ncm91cCB2LW1vZGVsPVwicmFkaW8xXCI+XG4gICAgICA8ZWwtcmFkaW8gdmFsdWU9XCIxXCIgc2l6ZT1cImxhcmdlXCIgYm9yZGVyPk9wdGlvbiBBPC9lbC1yYWRpbz5cbiAgICAgIDxlbC1yYWRpbyB2YWx1ZT1cIjJcIiBzaXplPVwibGFyZ2VcIiBib3JkZXI+T3B0aW9uIEI8L2VsLXJhZGlvPlxuICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gIDwvZGl2PlxuICA8ZGl2IHN0eWxlPVwibWFyZ2luLXRvcDogMjBweFwiPlxuICAgIDxlbC1yYWRpby1ncm91cCB2LW1vZGVsPVwicmFkaW8yXCI+XG4gICAgICA8ZWwtcmFkaW8gdmFsdWU9XCIxXCIgYm9yZGVyPk9wdGlvbiBBPC9lbC1yYWRpbz5cbiAgICAgIDxlbC1yYWRpbyB2YWx1ZT1cIjJcIiBib3JkZXI+T3B0aW9uIEI8L2VsLXJhZGlvPlxuICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gIDwvZGl2PlxuICA8ZGl2IHN0eWxlPVwibWFyZ2luLXRvcDogMjBweFwiPlxuICAgIDxlbC1yYWRpby1ncm91cCB2LW1vZGVsPVwicmFkaW8zXCIgc2l6ZT1cInNtYWxsXCI+XG4gICAgICA8ZWwtcmFkaW8gdmFsdWU9XCIxXCIgYm9yZGVyPk9wdGlvbiBBPC9lbC1yYWRpbz5cbiAgICAgIDxlbC1yYWRpbyB2YWx1ZT1cIjJcIiBib3JkZXIgZGlzYWJsZWQ+T3B0aW9uIEI8L2VsLXJhZGlvPlxuICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gIDwvZGl2PlxuICA8ZGl2IHN0eWxlPVwibWFyZ2luLXRvcDogMjBweFwiPlxuICAgIDxlbC1yYWRpby1ncm91cCB2LW1vZGVsPVwicmFkaW80XCIgc2l6ZT1cInNtYWxsXCIgZGlzYWJsZWQ+XG4gICAgICA8ZWwtcmFkaW8gdmFsdWU9XCIxXCIgYm9yZGVyPk9wdGlvbiBBPC9lbC1yYWRpbz5cbiAgICAgIDxlbC1yYWRpbyB2YWx1ZT1cIjJcIiBib3JkZXI+T3B0aW9uIEI8L2VsLXJhZGlvPlxuICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgcmFkaW8xID0gcmVmKCcxJylcbmNvbnN0IHJhZGlvMiA9IHJlZignMScpXG5jb25zdCByYWRpbzMgPSByZWYoJzEnKVxuY29uc3QgcmFkaW80ID0gcmVmKCcxJylcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/radio/with-borders.vue)_

vue

```
<template>
  <div>
    <el-radio-group v-model="radio1">
      <el-radio value="1" size="large" border>Option A</el-radio>
      <el-radio value="2" size="large" border>Option B</el-radio>
    </el-radio-group>
  </div>
  <div style="margin-top: 20px">
    <el-radio-group v-model="radio2">
      <el-radio value="1" border>Option A</el-radio>
      <el-radio value="2" border>Option B</el-radio>
    </el-radio-group>
  </div>
  <div style="margin-top: 20px">
    <el-radio-group v-model="radio3" size="small">
      <el-radio value="1" border>Option A</el-radio>
      <el-radio value="2" border disabled>Option B</el-radio>
    </el-radio-group>
  </div>
  <div style="margin-top: 20px">
    <el-radio-group v-model="radio4" size="small" disabled>
      <el-radio value="1" border>Option A</el-radio>
      <el-radio value="2" border>Option B</el-radio>
    </el-radio-group>
  </div>
</template>

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

const radio1 = ref('1')
const radio2 = ref('1')
const radio3 = ref('1')
const radio4 = ref('1')
</script>
```

隐藏源代码

## Options 属性 2.11.2 [​](#options-属性)

基础用法 `el-radio-group` 的快捷示例。 您可以通过 `props` 属性自定义 `options` 的别名。

Option AOption BOption C

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInJhZGlvXCIgOm9wdGlvbnM9XCJvcHRpb25zXCIgOnByb3BzPVwicHJvcHNcIiAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgcmFkaW8gPSByZWYoMylcbmNvbnN0IHByb3BzID0geyB2YWx1ZTogJ2lkJywgbGFiZWw6ICduYW1lJywgZGlzYWJsZWQ6ICd1bmFibGUnIH1cbmNvbnN0IG9wdGlvbnMgPSBbXG4gIHtcbiAgICBpZDogMyxcbiAgICBuYW1lOiAnT3B0aW9uIEEnLFxuICB9LFxuICB7XG4gICAgaWQ6IDYsXG4gICAgbmFtZTogJ09wdGlvbiBCJyxcbiAgfSxcbiAge1xuICAgIGlkOiA5LFxuICAgIG5hbWU6ICdPcHRpb24gQycsXG4gICAgdW5hYmxlOiB0cnVlLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/radio/options.vue)_

vue

```
<template>
  <el-radio-group v-model="radio" :options="options" :props="props" />
</template>

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

const radio = ref(3)
const props = { value: 'id', label: 'name', disabled: 'unable' }
const options = [
  {
    id: 3,
    name: 'Option A',
  },
  {
    id: 6,
    name: 'Option B',
  },
  {
    id: 9,
    name: 'Option C',
    unable: true,
  },
]
</script>
```

隐藏源代码

## 单选按钮 [​](#单选按钮)

带有按钮组视觉效果的单选框

只需要把 `el-radio` 元素换成 `el-radio-button` 元素即可， :::demo 您可以使用 `填充` 和 `文本颜色` 设置按钮的样式。

New YorkWashingtonLos AngelesChicago

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1yYWRpby1ncm91cCB2LW1vZGVsPVwicmFkaW9cIiBzaXplPVwibGFyZ2VcIiBmaWxsPVwiIzQwOWVmZlwiPlxuICAgICAgPGVsLXJhZGlvLWJ1dHRvbiBsYWJlbD1cIk5ldyBZb3JrXCIgdmFsdWU9XCJOZXcgWW9ya1wiIC8+XG4gICAgICA8ZWwtcmFkaW8tYnV0dG9uIGxhYmVsPVwiV2FzaGluZ3RvblwiIHZhbHVlPVwiV2FzaGluZ3RvblwiIC8+XG4gICAgICA8ZWwtcmFkaW8tYnV0dG9uIGxhYmVsPVwiTG9zIEFuZ2VsZXNcIiB2YWx1ZT1cIkxvcyBBbmdlbGVzXCIgLz5cbiAgICAgIDxlbC1yYWRpby1idXR0b24gbGFiZWw9XCJDaGljYWdvXCIgdmFsdWU9XCJDaGljYWdvXCIgLz5cbiAgICA8L2VsLXJhZGlvLWdyb3VwPlxuICA8L2Rpdj5cbiAgPGRpdiBzdHlsZT1cIm1hcmdpbi10b3A6IDIwcHhcIj5cbiAgICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInJhZGlvXCIgdGV4dC1jb2xvcj1cIiNmZmZcIiBmaWxsPVwiIzZjNmNmZlwiPlxuICAgICAgPGVsLXJhZGlvLWJ1dHRvbiBsYWJlbD1cIk5ldyBZb3JrXCIgdmFsdWU9XCJOZXcgWW9ya1wiIC8+XG4gICAgICA8ZWwtcmFkaW8tYnV0dG9uIGxhYmVsPVwiV2FzaGluZ3RvblwiIHZhbHVlPVwiV2FzaGluZ3RvblwiIC8+XG4gICAgICA8ZWwtcmFkaW8tYnV0dG9uIGxhYmVsPVwiTG9zIEFuZ2VsZXNcIiB2YWx1ZT1cIkxvcyBBbmdlbGVzXCIgLz5cbiAgICAgIDxlbC1yYWRpby1idXR0b24gbGFiZWw9XCJDaGljYWdvXCIgdmFsdWU9XCJDaGljYWdvXCIgLz5cbiAgICA8L2VsLXJhZGlvLWdyb3VwPlxuICA8L2Rpdj5cbiAgPGRpdiBzdHlsZT1cIm1hcmdpbi10b3A6IDIwcHhcIj5cbiAgICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInJhZGlvXCIgc2l6ZT1cInNtYWxsXCI+XG4gICAgICA8ZWwtcmFkaW8tYnV0dG9uIGxhYmVsPVwiTmV3IFlvcmtcIiB2YWx1ZT1cIk5ldyBZb3JrXCIgLz5cbiAgICAgIDxlbC1yYWRpby1idXR0b24gbGFiZWw9XCJXYXNoaW5ndG9uXCIgdmFsdWU9XCJXYXNoaW5ndG9uXCIgZGlzYWJsZWQgLz5cbiAgICAgIDxlbC1yYWRpby1idXR0b24gbGFiZWw9XCJMb3MgQW5nZWxlc1wiIHZhbHVlPVwiTG9zIEFuZ2VsZXNcIiAvPlxuICAgICAgPGVsLXJhZGlvLWJ1dHRvbiBsYWJlbD1cIkNoaWNhZ29cIiB2YWx1ZT1cIkNoaWNhZ29cIiAvPlxuICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgcmFkaW8gPSByZWYoJ05ldyBZb3JrJylcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/radio/radio-button.vue)_

vue

```
<template>
  <div>
    <el-radio-group v-model="radio" size="large" fill="#409eff">
      <el-radio-button label="New York" value="New York" />
      <el-radio-button label="Washington" value="Washington" />
      <el-radio-button label="Los Angeles" value="Los Angeles" />
      <el-radio-button label="Chicago" value="Chicago" />
    </el-radio-group>
  </div>
  <div style="margin-top: 20px">
    <el-radio-group v-model="radio" text-color="#fff" fill="#6c6cff">
      <el-radio-button label="New York" value="New York" />
      <el-radio-button label="Washington" value="Washington" />
      <el-radio-button label="Los Angeles" value="Los Angeles" />
      <el-radio-button label="Chicago" value="Chicago" />
    </el-radio-group>
  </div>
  <div style="margin-top: 20px">
    <el-radio-group v-model="radio" size="small">
      <el-radio-button label="New York" value="New York" />
      <el-radio-button label="Washington" value="Washington" disabled />
      <el-radio-button label="Los Angeles" value="Los Angeles" />
      <el-radio-button label="Chicago" value="Chicago" />
    </el-radio-group>
  </div>
</template>

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

const radio = ref('New York')
</script>
```

隐藏源代码

## Radio API [​](#radio-api)

### Radio Attributes [​](#radio-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `string` / `number` / `boolean` | — |
| value 2.6.0 | 单选框的值 | `string` / `number` / `boolean` | ::: |
| label | 单选框的 label 如果`value`没有值， `label`则作为`value`使用 | `string` / `number` / `boolean` | ::: |
| disabled | 是否禁用单选框 | `boolean` | false |
| border | 是否显示边框 | `boolean` | false |
| size | 单选框的尺寸 | `enum` | — |
| name | 原始 `name` 属性 | `string` | — |

### Radio Events [​](#radio-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 绑定值变化时触发的事件 | `Function` |

### Radio Slots [​](#radio-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## RadioGroup API [​](#radiogroup-api)

### RadioGroup Attributes [​](#radiogroup-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 绑定值 | `string` / `number` / `boolean` | — |
| size | 单选框按钮或边框按钮的大小 | `string` | default |
| disabled | 是否禁用 | `boolean` | false |
| validate-event | 输入时是否触发表单的校验 | `boolean` | true |
| text-color | 按钮形式的 Radio 激活时的文本颜色 | `string` | #ffffff |
| fill | 按钮形式的 Radio 激活时的填充色和边框色 | `string` | #409eff |
| aria-label a11y 2.7.2 | 与 RadioGroup 中的 `aria-label` 属性相同 | `string` | — |
| name | 原生 `name` 属性 | `string` | — |
| id | 原生 `id` 属性 | `string` | — |
| label a11y deprecated | 与 RadioGroup 中的 `aria-label` 属性相同 | `string` | — |
| options 2.11.2 | 选项的数据源， `value` 的 key 和 `label` 和 `disabled`可以通过 `props`自定义. | `array` | — |
| props 2.11.2 | options 的配置 | `object` | `{value: 'value', label: 'label', disabled: 'disabled'}` |
| type 2.11.5 | 用于渲染选项的组件类型（例如 `'button'`） | `enum` | 'radio' |

### RadioGroup Events [​](#radiogroup-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 绑定值变化时触发的事件 | `Function` |

### RadioGroup Slots [​](#radiogroup-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | Radio / RadioButton |

## RadioButton API [​](#radiobutton-api)

### RadioButton Attributes [​](#radiobutton-attributes)

| 名称 | 详情 | 类型 | 默认 |
| --- | --- | --- | --- |
| value 2.6.0 | 单选框的值 | `string` / `number` / `boolean` | — |
| label | 单选框的 label 如果没有 value， `label`则作为`value`使用 | `string` / `number` / `boolean` | — |
| disabled | 是否禁用单选框 | `boolean` | false |
| name | 原生 name 属性 | `string` | — |

### RadioButton Slots [​](#radiobutton-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 默认插槽内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/radio) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/radio.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/radio.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/50943004?v=4&size=64)](https://github.com/cactuser-Lu)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/41461715?v=4&size=64)](https://github.com/VENI-VIDIVICI)[![](https://avatars.githubusercontent.com/u/40999116?v=4&size=64)](https://github.com/jasonren0403)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/18263998?v=4&size=64)](https://github.com/taojunnan)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/26077227?v=4&size=64)](https://github.com/OneDayOneStep)

[Mention 提及](https://element-plus.org/zh-CN/component/mention)

[Rate 评分](https://element-plus.org/zh-CN/component/rate)




---
## [form/rate] Rate 评分
> 官方文档: https://element-plus.org/zh-CN/component/rate.html

---

# Rate 评分 [​](#rate-评分)

更新日志待解决

1

用于评分

## 基础用法 [​](#基础用法)

评分默认被分为三个等级，可以利用颜色数组对分数及情感倾向进行分级（默认情况下不区分颜色）。 三个等级所对应的颜色用 `colors` 属性设置，而它们对应的两个阈值则通过 `low-threshold` 和 `high-threshold` 设定。

Default

Color for different levels

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1yYXRlLWJsb2NrXCI+XG4gICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+RGVmYXVsdDwvc3Bhbj5cbiAgICA8ZWwtcmF0ZSB2LW1vZGVsPVwidmFsdWUxXCIgLz5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJkZW1vLXJhdGUtYmxvY2tcIj5cbiAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5Db2xvciBmb3IgZGlmZmVyZW50IGxldmVsczwvc3Bhbj5cbiAgICA8ZWwtcmF0ZSB2LW1vZGVsPVwidmFsdWUyXCIgOmNvbG9ycz1cImNvbG9yc1wiIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUxID0gcmVmKDApXG5jb25zdCB2YWx1ZTIgPSByZWYoMClcbmNvbnN0IGNvbG9ycyA9IHJlZihbJyM5OUE5QkYnLCAnI0Y3QkEyQScsICcjRkY5OTAwJ10pIC8vIHNhbWUgYXMgeyAyOiAnIzk5QTlCRicsIDQ6IHsgdmFsdWU6ICcjRjdCQTJBJywgZXhjbHVkZWQ6IHRydWUgfSwgNTogJyNGRjk5MDAnIH1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tcmF0ZS1ibG9jayB7XG4gIHBhZGRpbmc6IDMwcHggMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBib3JkZXItcmlnaHQ6IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICBkaXNwbGF5OiBpbmxpbmUtYmxvY2s7XG4gIHdpZHRoOiA0OSU7XG4gIGJveC1zaXppbmc6IGJvcmRlci1ib3g7XG59XG4uZGVtby1yYXRlLWJsb2NrOmxhc3QtY2hpbGQge1xuICBib3JkZXItcmlnaHQ6IG5vbmU7XG59XG4uZGVtby1yYXRlLWJsb2NrIC5kZW1vbnN0cmF0aW9uIHtcbiAgZGlzcGxheTogYmxvY2s7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG4gIGZvbnQtc2l6ZTogMTRweDtcbiAgbWFyZ2luLWJvdHRvbTogMjBweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/rate/basic-usage.vue)_

vue

```
<template>
  <div class="demo-rate-block">
    <span class="demonstration">Default</span>
    <el-rate v-model="value1" />
  </div>
  <div class="demo-rate-block">
    <span class="demonstration">Color for different levels</span>
    <el-rate v-model="value2" :colors="colors" />
  </div>
</template>

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

const value1 = ref(0)
const value2 = ref(0)
const colors = ref(['#99A9BF', '#F7BA2A', '#FF9900']) // same as { 2: '#99A9BF', 4: { value: '#F7BA2A', excluded: true }, 5: '#FF9900' }
</script>

<style scoped>
.demo-rate-block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  display: inline-block;
  width: 49%;
  box-sizing: border-box;
}
.demo-rate-block:last-child {
  border-right: none;
}
.demo-rate-block .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}
</style>
```

隐藏源代码

## 尺寸 [​](#尺寸)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmF0ZSB2LW1vZGVsPVwidmFsdWVcIiBzaXplPVwibGFyZ2VcIiAvPlxuICA8YnIgLz5cbiAgPGVsLXJhdGUgdi1tb2RlbD1cInZhbHVlXCIgLz5cbiAgPGJyIC8+XG4gIDxlbC1yYXRlIHYtbW9kZWw9XCJ2YWx1ZVwiIHNpemU9XCJzbWFsbFwiIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZigwKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/rate/sizes.vue)_

vue

```
<template>
  <el-rate v-model="value" size="large" />
  <br />
  <el-rate v-model="value" />
  <br />
  <el-rate v-model="value" size="small" />
</template>

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

const value = ref(0)
</script>
```

隐藏源代码

## 允许半选 [​](#允许半选)

属性 `allow-half` 允许出现半星

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmF0ZSB2LW1vZGVsPVwidmFsdWVcIiBhbGxvdy1oYWxmIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZigpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/rate/allow-half.vue)_

vue

```
<template>
  <el-rate v-model="value" allow-half />
</template>

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

const value = ref()
</script>
```

隐藏源代码

## 辅助文字 [​](#辅助文字)

用辅助文字直接地表达对应分数

为组件设置 `show-text` 属性会在右侧显示辅助文字。 通过设置 `texts` 可以为每一个分值指定对应的辅助文字。 `texts` 为一个数组，长度应等于最大值 `max`。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmF0ZVxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOnRleHRzPVwiWydvb3BzJywgJ2Rpc2FwcG9pbnRlZCcsICdub3JtYWwnLCAnZ29vZCcsICdncmVhdCddXCJcbiAgICBzaG93LXRleHRcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKClcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/rate/text.vue)_

vue

```
<template>
  <el-rate
    v-model="value"
    :texts="['oops', 'disappointed', 'normal', 'good', 'great']"
    show-text
  />
</template>

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

const value = ref()
</script>
```

隐藏源代码

## 可清空 [​](#可清空)

当你再次点击相同的值时，可以将值重置为 `0`。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmF0ZSB2LW1vZGVsPVwidmFsdWVcIiBjbGVhcmFibGUgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKDMpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/rate/clearable.vue)_

vue

```
<template>
  <el-rate v-model="value" clearable />
</template>

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

const value = ref(3)
</script>
```

隐藏源代码

## 更多种类的图标 [​](#更多种类的图标)

当有多层评价时，可以用不同类型的图标区分评分层级。

设置`icons`属性可以自定义不同分段的图标。 若传入数组，共有 3 个元素，为 3 个分段所对应的类名；若传入对象，可自定义分段，键名为分段的界限值，键值为对应的类名。 本例还使用 `void-icon` 指定了未选中时的图标类名。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmF0ZVxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOmljb25zPVwiaWNvbnNcIlxuICAgIDp2b2lkLWljb249XCJDaGF0Um91bmRcIlxuICAgIDpjb2xvcnM9XCJbJyM0MDllZmYnLCAnIzY3YzIzYScsICcjRkY5OTAwJ11cIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IENoYXREb3RSb3VuZCwgQ2hhdExpbmVSb3VuZCwgQ2hhdFJvdW5kIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKClcbmNvbnN0IGljb25zID0gW0NoYXRSb3VuZCwgQ2hhdExpbmVSb3VuZCwgQ2hhdERvdFJvdW5kXSAvLyBzYW1lIGFzIHsgMjogQ2hhdFJvdW5kLCA0OiB7IHZhbHVlOiBDaGF0TGluZVJvdW5kLCBleGNsdWRlZDogdHJ1ZSB9LCA1OiBDaGF0RG90Um91bmQgfVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/rate/more-icons.vue)_

vue

```
<template>
  <el-rate
    v-model="value"
    :icons="icons"
    :void-icon="ChatRound"
    :colors="['#409eff', '#67c23a', '#FF9900']"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ChatDotRound, ChatLineRound, ChatRound } from '@element-plus/icons-vue'

const value = ref()
const icons = [ChatRound, ChatLineRound, ChatDotRound] // same as { 2: ChatRound, 4: { value: ChatLineRound, excluded: true }, 5: ChatDotRound }
</script>
```

隐藏源代码

## 只读 [​](#只读)

只读的评分用来展示分数， 允许出现半星。

为组件设置 `disabled` 属性表示组件为只读。 此时若设置 `show-score`，则会在右侧显示目前的分值。 此外，您可以使用属性 `score-template` 来提供评分模板。 模板为一个包含了 `{value}` 的字符串，`{value}` 会被替换为当前分值。

3.7 points

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmF0ZVxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgZGlzYWJsZWRcbiAgICBzaG93LXNjb3JlXG4gICAgdGV4dC1jb2xvcj1cIiNmZjk5MDBcIlxuICAgIHNjb3JlLXRlbXBsYXRlPVwie3ZhbHVlfSBwb2ludHNcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoMy43KVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/rate/readonly.vue)_

vue

```
<template>
  <el-rate
    v-model="value"
    disabled
    show-score
    text-color="#ff9900"
    score-template="{value} points"
  />
</template>

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

const value = ref(3.7)
</script>
```

隐藏源代码

## 自定义样式 [​](#自定义样式)

您可以为 rate 组件设定自定义样式。 使用 `css` 或 `scss` 改变全局或局部的颜色。 我们设置了一些全局颜色变量：`--el-rate-void-color`、`--el-rate-fill-color`、`--el-rate-disabled-void-color` 和 `--el-rate-text-color`。 您可以像这样使用：`:root { --el-rate-void-color: red; --el-rate-fill-color: blue; }`。

### 默认变量 [​](#默认变量)

| 变量 | 默认颜色 |
| --- | --- |
| \--el-rate-void-color | var(--el-border-color-darker) |
| \--el-rate-fill-color | #f7ba2a |
| \--el-rate-disabled-void-color | var(--el-fill-color) |
| \--el-rate-text-color | var(--el-text-color-primary) |

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `number` | 0 |
| max | 最大分值 | `number` | 5 |
| size | 尺寸 | `enum` | — |
| disabled | 是否为只读 | `boolean` | false |
| allow-half | 是否允许半选 | `boolean` | false |
| low-threshold | 低分和中等分数的界限值， 值本身被划分在低分中 | `number` | 2 |
| high-threshold | 高分和中等分数的界限值， 值本身被划分在高分中 | `number` | 4 |
| colors | icon 的颜色。 若传入数组，共有 3 个元素，为 3 个分段所对应的颜色；若传入对象，可自定义分段，键名为分段的界限值，键值为对应的颜色 | `array` / `object` | \['#f7ba2a', '#f7ba2a', '#f7ba2a'\] |
| void-color | 未选中 icon 的颜色 | `string` | #c6d1de |
| disabled-void-color | 只读时未选中 icon 的颜色 | `string` | #eff2f7 |
| icons | 图标组件 若传入数组，则需要传入 3 个元素，分别为 3 个部分所对应的类名；若传入对象，则可自定义分段，键名为分段的界限值，键值为对应的类名 | `array` / `object` | \[StarFilled, StarFilled, StarFilled\] |
| void-icon | 未被选中的图标组件 | `string` / `Component` | Star |
| disabled-void-icon | 禁用状态的未选择图标 | `string` / `Component` | StarFilled |
| show-text | 是否显示辅助文字，若为真，则会从 texts 数组中选取当前分数对应的文字内容 | `boolean` | false |
| show-score | 是否显示当前分数， show-score 和 show-text 不能同时为真 | `boolean` | false |
| text-color | 辅助文字的颜色 | `string` | '' |
| texts | 辅助文字数组 | `array` | \['Extremely bad', 'Disappointed', 'Fair', 'Satisfied', 'Surprise'\] |
| score-template | 分数显示模板 | `string` |  |
| clearable 2.2.18 | 是否可以重置值为 `0` | `boolean` | false |
| id | 原生 `id` 属性 | `string` | — |
| aria-label a11y 2.7.2 | 和 Rate 的 `aria-label` 属性保持一致 | `string` | — |
| label a11y deprecated | 和 Rate 的 `aria-label` 属性保持一致 | `string` | — |

### Events [​](#events)

| 事件名 | 描述说明 | 类型 |
| --- | --- | --- |
| change | 分值改变时触发 | `Function` |

### Exposes [​](#exposes)

| 名称 | 描述 | 类型 |
| --- | --- | --- |
| setCurrentValue | 设置当前值 | `Function` |
| resetCurrentValue | 重置当前值 | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/rate) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/rate.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/rate.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/71313168?v=4&size=64)](https://github.com/cc-hearts)[![](https://avatars.githubusercontent.com/u/75007029?v=4&size=64)](https://github.com/yj-liuzepeng)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/31391693?v=4&size=64)](https://github.com/Shana-AE)[![](https://avatars.githubusercontent.com/u/33497338?v=4&size=64)](https://github.com/MoConWu)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/40431305?v=4&size=64)](https://github.com/Notryag)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/33979706?v=4&size=64)](https://github.com/jizai1125)[![](https://avatars.githubusercontent.com/u/36811055?v=4&size=64)](https://github.com/iDestin)

[Radio 单选框](https://element-plus.org/zh-CN/component/radio)

[Select](https://element-plus.org/zh-CN/component/select)




---
## [form/select] Select 选择器
> 官方文档: https://element-plus.org/zh-CN/component/select.html

---

# Select 选择器 [​](#select-选择器)

更新日志待解决

89

当选项过多时，使用下拉菜单展示并选择内容。

TIP

在版本 `2.5.0`之后， `el-select` 的默认宽度更改为 `100%` 当使用内联形式时，宽度将显示异常。 为了保持显示正常, 您需要手动配置 `el-select` 的宽度 (如: [例子](https://github.com/element-plus/element-plus/issues/15834#issuecomment-1936919229)).

## 基础用法 [​](#基础用法)

适用广泛的基础单选 `v-model` 的值为当前被选中的 `el-option` 的 value 属性值

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0IHYtbW9kZWw9XCJ2YWx1ZVwiIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCIgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIj5cbiAgICA8ZWwtb3B0aW9uXG4gICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICA6a2V5PVwiaXRlbS52YWx1ZVwiXG4gICAgICA6bGFiZWw9XCJpdGVtLmxhYmVsXCJcbiAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgIC8+XG4gIDwvZWwtc2VsZWN0PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoJycpXG5cbmNvbnN0IG9wdGlvbnMgPSBbXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjEnLFxuICAgIGxhYmVsOiAnT3B0aW9uMScsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjInLFxuICAgIGxhYmVsOiAnT3B0aW9uMicsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjMnLFxuICAgIGxhYmVsOiAnT3B0aW9uMycsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjQnLFxuICAgIGxhYmVsOiAnT3B0aW9uNCcsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjUnLFxuICAgIGxhYmVsOiAnT3B0aW9uNScsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/basic-usage.vue)_

vue

```
<template>
  <el-select v-model="value" placeholder="Select" style="width: 240px">
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

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

const value = ref('')

const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>
```

隐藏源代码

## Options 属性 2.10.5 [​](#options-属性)

`el-option` 基本用法。 您可以通过 `props` 属性自定义 `options` 的别名。

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0XG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgIDpwcm9wcz1cInByb3BzXCJcbiAgICBwbGFjZWhvbGRlcj1cIlNlbGVjdFwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoJycpXG5cbmNvbnN0IHByb3BzID0ge1xuICB2YWx1ZTogJ2lkJyxcbiAgbGFiZWw6ICdsYWJlbCcsXG4gIG9wdGlvbnM6ICdvcHRpb25zJyxcbiAgZGlzYWJsZWQ6ICdkaXNhYmxlZCcsXG59XG5cbmNvbnN0IG9wdGlvbnMgPSBbXG4gIHtcbiAgICBpZDogJ09wdGlvbjEnLFxuICAgIGxhYmVsOiAnT3B0aW9uMScsXG4gIH0sXG4gIHtcbiAgICBpZDogJ09wdGlvbjInLFxuICAgIGxhYmVsOiAnT3B0aW9uMicsXG4gICAgZGlzYWJsZWQ6IHRydWUsXG4gIH0sXG4gIHtcbiAgICBpZDogJ09wdGlvbjMnLFxuICAgIGxhYmVsOiAnT3B0aW9uMycsXG4gIH0sXG4gIHtcbiAgICBpZDogJ09wdGlvbjQnLFxuICAgIGxhYmVsOiAnT3B0aW9uNCcsXG4gICAgZGlzYWJsZWQ6IHRydWUsXG4gIH0sXG4gIHtcbiAgICBpZDogJ09wdGlvbjUnLFxuICAgIGxhYmVsOiAnT3B0aW9uNScsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/options.vue)_

vue

```
<template>
  <el-select
    v-model="value"
    :options="options"
    :props="props"
    placeholder="Select"
    style="width: 240px"
  />
</template>

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

const value = ref('')

const props = {
  value: 'id',
  label: 'label',
  options: 'options',
  disabled: 'disabled',
}

const options = [
  {
    id: 'Option1',
    label: 'Option1',
  },
  {
    id: 'Option2',
    label: 'Option2',
    disabled: true,
  },
  {
    id: 'Option3',
    label: 'Option3',
  },
  {
    id: 'Option4',
    label: 'Option4',
    disabled: true,
  },
  {
    id: 'Option5',
    label: 'Option5',
  },
]
</script>
```

隐藏源代码

## 有禁用选项 [​](#有禁用选项)

在 `el-option` 中，设定 `disabled` 值为 true，即可禁用该选项

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0IHYtbW9kZWw9XCJ2YWx1ZVwiIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCIgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIj5cbiAgICA8ZWwtb3B0aW9uXG4gICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICA6a2V5PVwiaXRlbS52YWx1ZVwiXG4gICAgICA6bGFiZWw9XCJpdGVtLmxhYmVsXCJcbiAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgICAgOmRpc2FibGVkPVwiaXRlbS5kaXNhYmxlZFwiXG4gICAgLz5cbiAgPC9lbC1zZWxlY3Q+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZignJylcbmNvbnN0IG9wdGlvbnMgPSBbXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjEnLFxuICAgIGxhYmVsOiAnT3B0aW9uMScsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjInLFxuICAgIGxhYmVsOiAnT3B0aW9uMicsXG4gICAgZGlzYWJsZWQ6IHRydWUsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjMnLFxuICAgIGxhYmVsOiAnT3B0aW9uMycsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjQnLFxuICAgIGxhYmVsOiAnT3B0aW9uNCcsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjUnLFxuICAgIGxhYmVsOiAnT3B0aW9uNScsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/disabled-option.vue)_

vue

```
<template>
  <el-select v-model="value" placeholder="Select" style="width: 240px">
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
      :disabled="item.disabled"
    />
  </el-select>
</template>

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

const value = ref('')
const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
    disabled: true,
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>
```

隐藏源代码

## 禁用状态 [​](#禁用状态)

禁用整个选择器组件

为 `el-select` 设置 `disabled`属性，则整个选择器不可用。

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0IHYtbW9kZWw9XCJ2YWx1ZVwiIGRpc2FibGVkIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCIgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIj5cbiAgICA8ZWwtb3B0aW9uXG4gICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICA6a2V5PVwiaXRlbS52YWx1ZVwiXG4gICAgICA6bGFiZWw9XCJpdGVtLmxhYmVsXCJcbiAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgIC8+XG4gIDwvZWwtc2VsZWN0PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoJycpXG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6ICdPcHRpb24xJyxcbiAgICBsYWJlbDogJ09wdGlvbjEnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdPcHRpb24yJyxcbiAgICBsYWJlbDogJ09wdGlvbjInLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdPcHRpb24zJyxcbiAgICBsYWJlbDogJ09wdGlvbjMnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdPcHRpb240JyxcbiAgICBsYWJlbDogJ09wdGlvbjQnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdPcHRpb241JyxcbiAgICBsYWJlbDogJ09wdGlvbjUnLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/disabled.vue)_

vue

```
<template>
  <el-select v-model="value" disabled placeholder="Select" style="width: 240px">
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

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

const value = ref('')
const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>
```

隐藏源代码

## 可清空 [​](#可清空)

您可以使用清除图标来清除选择。

为 `el-select` 设置 `clearable` 属性，则可将选择器清空。

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0XG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICBjbGVhcmFibGVcbiAgICBwbGFjZWhvbGRlcj1cIlNlbGVjdFwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICA+XG4gICAgPGVsLW9wdGlvblxuICAgICAgdi1mb3I9XCJpdGVtIGluIG9wdGlvbnNcIlxuICAgICAgOmtleT1cIml0ZW0udmFsdWVcIlxuICAgICAgOmxhYmVsPVwiaXRlbS5sYWJlbFwiXG4gICAgICA6dmFsdWU9XCJpdGVtLnZhbHVlXCJcbiAgICAvPlxuICA8L2VsLXNlbGVjdD5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKCcnKVxuY29uc3Qgb3B0aW9ucyA9IFtcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uMScsXG4gICAgbGFiZWw6ICdPcHRpb24xJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uMicsXG4gICAgbGFiZWw6ICdPcHRpb24yJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uMycsXG4gICAgbGFiZWw6ICdPcHRpb24zJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uNCcsXG4gICAgbGFiZWw6ICdPcHRpb240JyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uNScsXG4gICAgbGFiZWw6ICdPcHRpb241JyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/clearable.vue)_

vue

```
<template>
  <el-select
    v-model="value"
    clearable
    placeholder="Select"
    style="width: 240px"
  >
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

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

const value = ref('')
const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>
```

隐藏源代码

## 尺寸 [​](#尺寸)

使用 `size` 属性改变选择器大小。 除了默认大小外，还有另外两个选项： `large`, `small`。

Select

Select

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTQgaXRlbXMtY2VudGVyXCI+XG4gICAgPGVsLXNlbGVjdFxuICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCJcbiAgICAgIHNpemU9XCJsYXJnZVwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgPlxuICAgICAgPGVsLW9wdGlvblxuICAgICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICAgIDprZXk9XCJpdGVtLnZhbHVlXCJcbiAgICAgICAgOmxhYmVsPVwiaXRlbS5sYWJlbFwiXG4gICAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgICAgLz5cbiAgICA8L2VsLXNlbGVjdD5cbiAgICA8ZWwtc2VsZWN0IHYtbW9kZWw9XCJ2YWx1ZVwiIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCIgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIj5cbiAgICAgIDxlbC1vcHRpb25cbiAgICAgICAgdi1mb3I9XCJpdGVtIGluIG9wdGlvbnNcIlxuICAgICAgICA6a2V5PVwiaXRlbS52YWx1ZVwiXG4gICAgICAgIDpsYWJlbD1cIml0ZW0ubGFiZWxcIlxuICAgICAgICA6dmFsdWU9XCJpdGVtLnZhbHVlXCJcbiAgICAgIC8+XG4gICAgPC9lbC1zZWxlY3Q+XG4gICAgPGVsLXNlbGVjdFxuICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCJcbiAgICAgIHNpemU9XCJzbWFsbFwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgPlxuICAgICAgPGVsLW9wdGlvblxuICAgICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICAgIDprZXk9XCJpdGVtLnZhbHVlXCJcbiAgICAgICAgOmxhYmVsPVwiaXRlbS5sYWJlbFwiXG4gICAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgICAgLz5cbiAgICA8L2VsLXNlbGVjdD5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZignJylcblxuY29uc3Qgb3B0aW9ucyA9IFtcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uMScsXG4gICAgbGFiZWw6ICdPcHRpb24xJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uMicsXG4gICAgbGFiZWw6ICdPcHRpb24yJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uMycsXG4gICAgbGFiZWw6ICdPcHRpb24zJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uNCcsXG4gICAgbGFiZWw6ICdPcHRpb240JyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uNScsXG4gICAgbGFiZWw6ICdPcHRpb241JyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/size.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-4 items-center">
    <el-select
      v-model="value"
      placeholder="Select"
      size="large"
      style="width: 240px"
    >
      <el-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </el-select>
    <el-select v-model="value" placeholder="Select" style="width: 240px">
      <el-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </el-select>
    <el-select
      v-model="value"
      placeholder="Select"
      size="small"
      style="width: 240px"
    >
      <el-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </el-select>
  </div>
</template>

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

const value = ref('')

const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>
```

隐藏源代码

## 基础多选 [​](#基础多选)

多选选择器使用 tag 组件来展示已选中的选项。

为 `el-select` 设置 `multiple` 属性即可启用多选， 此时 `v-model` 的值为当前选中值所组成的数组。 默认情况下选中值会以 Tag 组件的形式展现， 你也可以设置 `collapse-tags` 属性将它们合并为一段文字。 您可以使用 `collapse-tags-tooltip` 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。

default

Select

use collapse-tags

Select

use collapse-tags-tooltip

Select

use max-collapse-tags

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+ZGVmYXVsdDwvcD5cbiAgICA8ZWwtc2VsZWN0XG4gICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgIG11bHRpcGxlXG4gICAgICBwbGFjZWhvbGRlcj1cIlNlbGVjdFwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgPlxuICAgICAgPGVsLW9wdGlvblxuICAgICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICAgIDprZXk9XCJpdGVtLnZhbHVlXCJcbiAgICAgICAgOmxhYmVsPVwiaXRlbS5sYWJlbFwiXG4gICAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgICAgLz5cbiAgICA8L2VsLXNlbGVjdD5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJtLTRcIj5cbiAgICA8cD51c2UgY29sbGFwc2UtdGFnczwvcD5cbiAgICA8ZWwtc2VsZWN0XG4gICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgIG11bHRpcGxlXG4gICAgICBjb2xsYXBzZS10YWdzXG4gICAgICBwbGFjZWhvbGRlcj1cIlNlbGVjdFwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgPlxuICAgICAgPGVsLW9wdGlvblxuICAgICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICAgIDprZXk9XCJpdGVtLnZhbHVlXCJcbiAgICAgICAgOmxhYmVsPVwiaXRlbS5sYWJlbFwiXG4gICAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgICAgLz5cbiAgICA8L2VsLXNlbGVjdD5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJtLTRcIj5cbiAgICA8cD51c2UgY29sbGFwc2UtdGFncy10b29sdGlwPC9wPlxuICAgIDxlbC1zZWxlY3RcbiAgICAgIHYtbW9kZWw9XCJ2YWx1ZTNcIlxuICAgICAgbXVsdGlwbGVcbiAgICAgIGNvbGxhcHNlLXRhZ3NcbiAgICAgIGNvbGxhcHNlLXRhZ3MtdG9vbHRpcFxuICAgICAgcGxhY2Vob2xkZXI9XCJTZWxlY3RcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgID5cbiAgICAgIDxlbC1vcHRpb25cbiAgICAgICAgdi1mb3I9XCJpdGVtIGluIG9wdGlvbnNcIlxuICAgICAgICA6a2V5PVwiaXRlbS52YWx1ZVwiXG4gICAgICAgIDpsYWJlbD1cIml0ZW0ubGFiZWxcIlxuICAgICAgICA6dmFsdWU9XCJpdGVtLnZhbHVlXCJcbiAgICAgIC8+XG4gICAgPC9lbC1zZWxlY3Q+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+dXNlIG1heC1jb2xsYXBzZS10YWdzPC9wPlxuICAgIDxlbC1zZWxlY3RcbiAgICAgIHYtbW9kZWw9XCJ2YWx1ZTRcIlxuICAgICAgbXVsdGlwbGVcbiAgICAgIGNvbGxhcHNlLXRhZ3NcbiAgICAgIGNvbGxhcHNlLXRhZ3MtdG9vbHRpcFxuICAgICAgOm1heC1jb2xsYXBzZS10YWdzPVwiM1wiXG4gICAgICBwbGFjZWhvbGRlcj1cIlNlbGVjdFwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgPlxuICAgICAgPGVsLW9wdGlvblxuICAgICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICAgIDprZXk9XCJpdGVtLnZhbHVlXCJcbiAgICAgICAgOmxhYmVsPVwiaXRlbS5sYWJlbFwiXG4gICAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgICAgLz5cbiAgICA8L2VsLXNlbGVjdD5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZTEgPSByZWYoW10pXG5jb25zdCB2YWx1ZTIgPSByZWYoW10pXG5jb25zdCB2YWx1ZTMgPSByZWYoW10pXG5jb25zdCB2YWx1ZTQgPSByZWYoW10pXG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6ICdPcHRpb24xJyxcbiAgICBsYWJlbDogJ09wdGlvbjEnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdPcHRpb24yJyxcbiAgICBsYWJlbDogJ09wdGlvbjInLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdPcHRpb24zJyxcbiAgICBsYWJlbDogJ09wdGlvbjMnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdPcHRpb240JyxcbiAgICBsYWJlbDogJ09wdGlvbjQnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdPcHRpb241JyxcbiAgICBsYWJlbDogJ09wdGlvbjUnLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/multiple.vue)_

vue

```
<template>
  <div class="m-4">
    <p>default</p>
    <el-select
      v-model="value1"
      multiple
      placeholder="Select"
      style="width: 240px"
    >
      <el-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </el-select>
  </div>
  <div class="m-4">
    <p>use collapse-tags</p>
    <el-select
      v-model="value2"
      multiple
      collapse-tags
      placeholder="Select"
      style="width: 240px"
    >
      <el-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </el-select>
  </div>
  <div class="m-4">
    <p>use collapse-tags-tooltip</p>
    <el-select
      v-model="value3"
      multiple
      collapse-tags
      collapse-tags-tooltip
      placeholder="Select"
      style="width: 240px"
    >
      <el-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </el-select>
  </div>
  <div class="m-4">
    <p>use max-collapse-tags</p>
    <el-select
      v-model="value4"
      multiple
      collapse-tags
      collapse-tags-tooltip
      :max-collapse-tags="3"
      placeholder="Select"
      style="width: 240px"
    >
      <el-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </el-select>
  </div>
</template>

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

const value1 = ref([])
const value2 = ref([])
const value3 = ref([])
const value4 = ref([])
const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>
```

隐藏源代码

## 自定义模板 [​](#自定义模板)

你可以自定义如何来渲染每一个选项。

将自定义的 HTML 模板插入 `el-option` 的 slot 中即可。

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0IHYtbW9kZWw9XCJ2YWx1ZVwiIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCIgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIj5cbiAgICA8ZWwtb3B0aW9uXG4gICAgICB2LWZvcj1cIml0ZW0gaW4gY2l0aWVzXCJcbiAgICAgIDprZXk9XCJpdGVtLnZhbHVlXCJcbiAgICAgIDpsYWJlbD1cIml0ZW0ubGFiZWxcIlxuICAgICAgOnZhbHVlPVwiaXRlbS52YWx1ZVwiXG4gICAgPlxuICAgICAgPHNwYW4gc3R5bGU9XCJmbG9hdDogbGVmdFwiPnt7IGl0ZW0ubGFiZWwgfX08L3NwYW4+XG4gICAgICA8c3BhblxuICAgICAgICBzdHlsZT1cIlxuICAgICAgICAgIGZsb2F0OiByaWdodDtcbiAgICAgICAgICBjb2xvcjogdmFyKC0tZWwtdGV4dC1jb2xvci1zZWNvbmRhcnkpO1xuICAgICAgICAgIGZvbnQtc2l6ZTogMTNweDtcbiAgICAgICAgXCJcbiAgICAgID5cbiAgICAgICAge3sgaXRlbS52YWx1ZSB9fVxuICAgICAgPC9zcGFuPlxuICAgIDwvZWwtb3B0aW9uPlxuICA8L2VsLXNlbGVjdD5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKCcnKVxuY29uc3QgY2l0aWVzID0gW1xuICB7XG4gICAgdmFsdWU6ICdCZWlqaW5nJyxcbiAgICBsYWJlbDogJ0JlaWppbmcnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdTaGFuZ2hhaScsXG4gICAgbGFiZWw6ICdTaGFuZ2hhaScsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ05hbmppbmcnLFxuICAgIGxhYmVsOiAnTmFuamluZycsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ0NoZW5nZHUnLFxuICAgIGxhYmVsOiAnQ2hlbmdkdScsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ1NoZW56aGVuJyxcbiAgICBsYWJlbDogJ1NoZW56aGVuJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnR3Vhbmd6aG91JyxcbiAgICBsYWJlbDogJ0d1YW5nemhvdScsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/custom-template.vue)_

vue

```
<template>
  <el-select v-model="value" placeholder="Select" style="width: 240px">
    <el-option
      v-for="item in cities"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    >
      <span style="float: left">{{ item.label }}</span>
      <span
        style="
          float: right;
          color: var(--el-text-color-secondary);
          font-size: 13px;
        "
      >
        {{ item.value }}
      </span>
    </el-option>
  </el-select>
</template>

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

const value = ref('')
const cities = [
  {
    value: 'Beijing',
    label: 'Beijing',
  },
  {
    value: 'Shanghai',
    label: 'Shanghai',
  },
  {
    value: 'Nanjing',
    label: 'Nanjing',
  },
  {
    value: 'Chengdu',
    label: 'Chengdu',
  },
  {
    value: 'Shenzhen',
    label: 'Shenzhen',
  },
  {
    value: 'Guangzhou',
    label: 'Guangzhou',
  },
]
</script>
```

隐藏源代码

## 自定义下拉菜单的头部 2.4.3 [​](#自定义下拉菜单的头部)

您可以自定义下拉菜单的头部。

Use slot to customize the content.

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0XG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICBtdWx0aXBsZVxuICAgIGNsZWFyYWJsZVxuICAgIGNvbGxhcHNlLXRhZ3NcbiAgICBwbGFjZWhvbGRlcj1cIlNlbGVjdFwiXG4gICAgcG9wcGVyLWNsYXNzPVwiY3VzdG9tLWhlYWRlclwiXG4gICAgOm1heC1jb2xsYXBzZS10YWdzPVwiMVwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICA+XG4gICAgPHRlbXBsYXRlICNoZWFkZXI+XG4gICAgICA8ZWwtY2hlY2tib3hcbiAgICAgICAgdi1tb2RlbD1cImNoZWNrQWxsXCJcbiAgICAgICAgOmluZGV0ZXJtaW5hdGU9XCJpbmRldGVybWluYXRlXCJcbiAgICAgICAgQGNoYW5nZT1cImhhbmRsZUNoZWNrQWxsXCJcbiAgICAgID5cbiAgICAgICAgQWxsXG4gICAgICA8L2VsLWNoZWNrYm94PlxuICAgIDwvdGVtcGxhdGU+XG4gICAgPGVsLW9wdGlvblxuICAgICAgdi1mb3I9XCJpdGVtIGluIGNpdGllc1wiXG4gICAgICA6a2V5PVwiaXRlbS52YWx1ZVwiXG4gICAgICA6bGFiZWw9XCJpdGVtLmxhYmVsXCJcbiAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgIC8+XG4gIDwvZWwtc2VsZWN0PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiwgd2F0Y2ggfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgQ2hlY2tib3hWYWx1ZVR5cGUgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGNoZWNrQWxsID0gcmVmKGZhbHNlKVxuY29uc3QgaW5kZXRlcm1pbmF0ZSA9IHJlZihmYWxzZSlcbmNvbnN0IHZhbHVlID0gcmVmPENoZWNrYm94VmFsdWVUeXBlW10+KFtdKVxuY29uc3QgY2l0aWVzID0gcmVmKFtcbiAge1xuICAgIHZhbHVlOiAnQmVpamluZycsXG4gICAgbGFiZWw6ICdCZWlqaW5nJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnU2hhbmdoYWknLFxuICAgIGxhYmVsOiAnU2hhbmdoYWknLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdOYW5qaW5nJyxcbiAgICBsYWJlbDogJ05hbmppbmcnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdDaGVuZ2R1JyxcbiAgICBsYWJlbDogJ0NoZW5nZHUnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdTaGVuemhlbicsXG4gICAgbGFiZWw6ICdTaGVuemhlbicsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ0d1YW5nemhvdScsXG4gICAgbGFiZWw6ICdHdWFuZ3pob3UnLFxuICB9LFxuXSlcblxud2F0Y2godmFsdWUsICh2YWwpID0+IHtcbiAgaWYgKHZhbC5sZW5ndGggPT09IDApIHtcbiAgICBjaGVja0FsbC52YWx1ZSA9IGZhbHNlXG4gICAgaW5kZXRlcm1pbmF0ZS52YWx1ZSA9IGZhbHNlXG4gIH0gZWxzZSBpZiAodmFsLmxlbmd0aCA9PT0gY2l0aWVzLnZhbHVlLmxlbmd0aCkge1xuICAgIGNoZWNrQWxsLnZhbHVlID0gdHJ1ZVxuICAgIGluZGV0ZXJtaW5hdGUudmFsdWUgPSBmYWxzZVxuICB9IGVsc2Uge1xuICAgIGluZGV0ZXJtaW5hdGUudmFsdWUgPSB0cnVlXG4gIH1cbn0pXG5cbmNvbnN0IGhhbmRsZUNoZWNrQWxsID0gKHZhbDogQ2hlY2tib3hWYWx1ZVR5cGUpID0+IHtcbiAgaW5kZXRlcm1pbmF0ZS52YWx1ZSA9IGZhbHNlXG4gIGlmICh2YWwpIHtcbiAgICB2YWx1ZS52YWx1ZSA9IGNpdGllcy52YWx1ZS5tYXAoKF8pID0+IF8udmFsdWUpXG4gIH0gZWxzZSB7XG4gICAgdmFsdWUudmFsdWUgPSBbXVxuICB9XG59XG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLmN1c3RvbS1oZWFkZXIge1xuICAuZWwtY2hlY2tib3gge1xuICAgIGRpc3BsYXk6IGZsZXg7XG4gICAgaGVpZ2h0OiB1bnNldDtcbiAgfVxufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/custom-header.vue)_

vue

```
<template>
  <el-select
    v-model="value"
    multiple
    clearable
    collapse-tags
    placeholder="Select"
    popper-class="custom-header"
    :max-collapse-tags="1"
    style="width: 240px"
  >
    <template #header>
      <el-checkbox
        v-model="checkAll"
        :indeterminate="indeterminate"
        @change="handleCheckAll"
      >
        All
      </el-checkbox>
    </template>
    <el-option
      v-for="item in cities"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

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

import type { CheckboxValueType } from 'element-plus'

const checkAll = ref(false)
const indeterminate = ref(false)
const value = ref<CheckboxValueType[]>([])
const cities = ref([
  {
    value: 'Beijing',
    label: 'Beijing',
  },
  {
    value: 'Shanghai',
    label: 'Shanghai',
  },
  {
    value: 'Nanjing',
    label: 'Nanjing',
  },
  {
    value: 'Chengdu',
    label: 'Chengdu',
  },
  {
    value: 'Shenzhen',
    label: 'Shenzhen',
  },
  {
    value: 'Guangzhou',
    label: 'Guangzhou',
  },
])

watch(value, (val) => {
  if (val.length === 0) {
    checkAll.value = false
    indeterminate.value = false
  } else if (val.length === cities.value.length) {
    checkAll.value = true
    indeterminate.value = false
  } else {
    indeterminate.value = true
  }
})

const handleCheckAll = (val: CheckboxValueType) => {
  indeterminate.value = false
  if (val) {
    value.value = cities.value.map((_) => _.value)
  } else {
    value.value = []
  }
}
</script>

<style>
.custom-header {
  .el-checkbox {
    display: flex;
    height: unset;
  }
}
</style>
```

隐藏源代码

## 自定义下拉菜单的底部 2.4.3 [​](#自定义下拉菜单的底部)

您可以自定义下拉菜单的底部。

使用slot 自定义内容

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0IHYtbW9kZWw9XCJ2YWx1ZVwiIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCIgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIj5cbiAgICA8ZWwtb3B0aW9uXG4gICAgICB2LWZvcj1cIml0ZW0gaW4gY2l0aWVzXCJcbiAgICAgIDprZXk9XCJpdGVtLnZhbHVlXCJcbiAgICAgIDpsYWJlbD1cIml0ZW0ubGFiZWxcIlxuICAgICAgOnZhbHVlPVwiaXRlbS52YWx1ZVwiXG4gICAgLz5cbiAgICA8dGVtcGxhdGUgI2Zvb3Rlcj5cbiAgICAgIDxlbC1idXR0b24gdi1pZj1cIiFpc0FkZGluZ1wiIHRleHQgYmcgc2l6ZT1cInNtYWxsXCIgQGNsaWNrPVwib25BZGRPcHRpb25cIj5cbiAgICAgICAgQWRkIGFuIG9wdGlvblxuICAgICAgPC9lbC1idXR0b24+XG4gICAgICA8dGVtcGxhdGUgdi1lbHNlPlxuICAgICAgICA8ZWwtaW5wdXRcbiAgICAgICAgICB2LW1vZGVsPVwib3B0aW9uTmFtZVwiXG4gICAgICAgICAgY2xhc3M9XCJvcHRpb24taW5wdXRcIlxuICAgICAgICAgIHBsYWNlaG9sZGVyPVwiaW5wdXQgb3B0aW9uIG5hbWVcIlxuICAgICAgICAgIHNpemU9XCJzbWFsbFwiXG4gICAgICAgIC8+XG4gICAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBzaXplPVwic21hbGxcIiBAY2xpY2s9XCJvbkNvbmZpcm1cIj5cbiAgICAgICAgICBjb25maXJtXG4gICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgICA8ZWwtYnV0dG9uIHNpemU9XCJzbWFsbFwiIEBjbGljaz1cImNsZWFyXCI+Y2FuY2VsPC9lbC1idXR0b24+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtc2VsZWN0PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBDaGVja2JveFZhbHVlVHlwZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgaXNBZGRpbmcgPSByZWYoZmFsc2UpXG5jb25zdCB2YWx1ZSA9IHJlZjxDaGVja2JveFZhbHVlVHlwZVtdPihbXSlcbmNvbnN0IG9wdGlvbk5hbWUgPSByZWYoJycpXG5jb25zdCBjaXRpZXMgPSByZWYoW1xuICB7XG4gICAgdmFsdWU6ICdCZWlqaW5nJyxcbiAgICBsYWJlbDogJ0JlaWppbmcnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdTaGFuZ2hhaScsXG4gICAgbGFiZWw6ICdTaGFuZ2hhaScsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ05hbmppbmcnLFxuICAgIGxhYmVsOiAnTmFuamluZycsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ0NoZW5nZHUnLFxuICAgIGxhYmVsOiAnQ2hlbmdkdScsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ1NoZW56aGVuJyxcbiAgICBsYWJlbDogJ1NoZW56aGVuJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnR3Vhbmd6aG91JyxcbiAgICBsYWJlbDogJ0d1YW5nemhvdScsXG4gIH0sXG5dKVxuXG5jb25zdCBvbkFkZE9wdGlvbiA9ICgpID0+IHtcbiAgaXNBZGRpbmcudmFsdWUgPSB0cnVlXG59XG5cbmNvbnN0IG9uQ29uZmlybSA9ICgpID0+IHtcbiAgaWYgKG9wdGlvbk5hbWUudmFsdWUpIHtcbiAgICBjaXRpZXMudmFsdWUucHVzaCh7XG4gICAgICBsYWJlbDogb3B0aW9uTmFtZS52YWx1ZSxcbiAgICAgIHZhbHVlOiBvcHRpb25OYW1lLnZhbHVlLFxuICAgIH0pXG4gICAgY2xlYXIoKVxuICB9XG59XG5cbmNvbnN0IGNsZWFyID0gKCkgPT4ge1xuICBvcHRpb25OYW1lLnZhbHVlID0gJydcbiAgaXNBZGRpbmcudmFsdWUgPSBmYWxzZVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5vcHRpb24taW5wdXQge1xuICB3aWR0aDogMTAwJTtcbiAgbWFyZ2luLWJvdHRvbTogOHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/custom-footer.vue)_

vue

```
<template>
  <el-select v-model="value" placeholder="Select" style="width: 240px">
    <el-option
      v-for="item in cities"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
    <template #footer>
      <el-button v-if="!isAdding" text bg size="small" @click="onAddOption">
        Add an option
      </el-button>
      <template v-else>
        <el-input
          v-model="optionName"
          class="option-input"
          placeholder="input option name"
          size="small"
        />
        <el-button type="primary" size="small" @click="onConfirm">
          confirm
        </el-button>
        <el-button size="small" @click="clear">cancel</el-button>
      </template>
    </template>
  </el-select>
</template>

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

import type { CheckboxValueType } from 'element-plus'

const isAdding = ref(false)
const value = ref<CheckboxValueType[]>([])
const optionName = ref('')
const cities = ref([
  {
    value: 'Beijing',
    label: 'Beijing',
  },
  {
    value: 'Shanghai',
    label: 'Shanghai',
  },
  {
    value: 'Nanjing',
    label: 'Nanjing',
  },
  {
    value: 'Chengdu',
    label: 'Chengdu',
  },
  {
    value: 'Shenzhen',
    label: 'Shenzhen',
  },
  {
    value: 'Guangzhou',
    label: 'Guangzhou',
  },
])

const onAddOption = () => {
  isAdding.value = true
}

const onConfirm = () => {
  if (optionName.value) {
    cities.value.push({
      label: optionName.value,
      value: optionName.value,
    })
    clear()
  }
}

const clear = () => {
  optionName.value = ''
  isAdding.value = false
}
</script>

<style>
.option-input {
  width: 100%;
  margin-bottom: 8px;
}
</style>
```

隐藏源代码

## 将选项进行分组 [​](#将选项进行分组)

你可以为选项进行分组来区分不同的选项

使用 `el-option-group` 对备选项进行分组，它的 `label` 属性为分组名

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0IHYtbW9kZWw9XCJ2YWx1ZVwiIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCIgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIj5cbiAgICA8ZWwtb3B0aW9uLWdyb3VwXG4gICAgICB2LWZvcj1cImdyb3VwIGluIG9wdGlvbnNcIlxuICAgICAgOmtleT1cImdyb3VwLmxhYmVsXCJcbiAgICAgIDpsYWJlbD1cImdyb3VwLmxhYmVsXCJcbiAgICA+XG4gICAgICA8ZWwtb3B0aW9uXG4gICAgICAgIHYtZm9yPVwiaXRlbSBpbiBncm91cC5vcHRpb25zXCJcbiAgICAgICAgOmtleT1cIml0ZW0udmFsdWVcIlxuICAgICAgICA6bGFiZWw9XCJpdGVtLmxhYmVsXCJcbiAgICAgICAgOnZhbHVlPVwiaXRlbS52YWx1ZVwiXG4gICAgICAvPlxuICAgIDwvZWwtb3B0aW9uLWdyb3VwPlxuICA8L2VsLXNlbGVjdD5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKCcnKVxuY29uc3Qgb3B0aW9ucyA9IFtcbiAge1xuICAgIGxhYmVsOiAnUG9wdWxhciBjaXRpZXMnLFxuICAgIG9wdGlvbnM6IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdTaGFuZ2hhaScsXG4gICAgICAgIGxhYmVsOiAnU2hhbmdoYWknLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICdCZWlqaW5nJyxcbiAgICAgICAgbGFiZWw6ICdCZWlqaW5nJyxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIGxhYmVsOiAnQ2l0eSBuYW1lJyxcbiAgICBvcHRpb25zOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnQ2hlbmdkdScsXG4gICAgICAgIGxhYmVsOiAnQ2hlbmdkdScsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ1NoZW56aGVuJyxcbiAgICAgICAgbGFiZWw6ICdTaGVuemhlbicsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJ0d1YW5nemhvdScsXG4gICAgICAgIGxhYmVsOiAnR3Vhbmd6aG91JyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnRGFsaWFuJyxcbiAgICAgICAgbGFiZWw6ICdEYWxpYW4nLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/grouping.vue)_

vue

```
<template>
  <el-select v-model="value" placeholder="Select" style="width: 240px">
    <el-option-group
      v-for="group in options"
      :key="group.label"
      :label="group.label"
    >
      <el-option
        v-for="item in group.options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </el-option-group>
  </el-select>
</template>

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

const value = ref('')
const options = [
  {
    label: 'Popular cities',
    options: [
      {
        value: 'Shanghai',
        label: 'Shanghai',
      },
      {
        value: 'Beijing',
        label: 'Beijing',
      },
    ],
  },
  {
    label: 'City name',
    options: [
      {
        value: 'Chengdu',
        label: 'Chengdu',
      },
      {
        value: 'Shenzhen',
        label: 'Shenzhen',
      },
      {
        value: 'Guangzhou',
        label: 'Guangzhou',
      },
      {
        value: 'Dalian',
        label: 'Dalian',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 筛选选项 [​](#筛选选项)

可以利用筛选功能快速查找选项。

为`el-select`添加`filterable`属性即可启用搜索功能。 默认情况下，Select 会找出所有 `label` 属性包含输入值的选项。 如果希望使用其他的搜索逻辑，可以通过传入一个 `filter-method` 来实现。 `filter-method` 为一个 `Function`，它会在输入值发生变化时调用，参数为当前输入值。

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0XG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICBmaWx0ZXJhYmxlXG4gICAgcGxhY2Vob2xkZXI9XCJTZWxlY3RcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgPlxuICAgIDxlbC1vcHRpb25cbiAgICAgIHYtZm9yPVwiaXRlbSBpbiBvcHRpb25zXCJcbiAgICAgIDprZXk9XCJpdGVtLnZhbHVlXCJcbiAgICAgIDpsYWJlbD1cIml0ZW0ubGFiZWxcIlxuICAgICAgOnZhbHVlPVwiaXRlbS52YWx1ZVwiXG4gICAgLz5cbiAgPC9lbC1zZWxlY3Q+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZignJylcbmNvbnN0IG9wdGlvbnMgPSBbXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjEnLFxuICAgIGxhYmVsOiAnT3B0aW9uMScsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjInLFxuICAgIGxhYmVsOiAnT3B0aW9uMicsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjMnLFxuICAgIGxhYmVsOiAnT3B0aW9uMycsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjQnLFxuICAgIGxhYmVsOiAnT3B0aW9uNCcsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjUnLFxuICAgIGxhYmVsOiAnT3B0aW9uNScsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/filterable.vue)_

vue

```
<template>
  <el-select
    v-model="value"
    filterable
    placeholder="Select"
    style="width: 240px"
  >
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

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

const value = ref('')
const options = [
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]
</script>
```

隐藏源代码

## 远程搜索 [​](#远程搜索)

输入关键字以从远程服务器中查找数据。

从服务器搜索数据，输入关键字进行查找。为了启用远程搜索，需要将`filterable`和`remote`设置为`true`，同时传入一个`remote-method`。 `remote-method`为一个`Function`，它会在输入值发生变化时调用，参数为当前输入值。 需要注意的是，如果 `el-option` 是通过 `v-for` 指令渲染出来的，此时需要为 `el-option` 添加 `key` 属性， 且其值需具有唯一性，比如这个例子中的 `item.value`。

default

Please enter a keyword

use remote-show-suffix

Please enter a keyword

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXBcIj5cbiAgICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgICA8cD5kZWZhdWx0PC9wPlxuICAgICAgPGVsLXNlbGVjdFxuICAgICAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgICAgICBtdWx0aXBsZVxuICAgICAgICBmaWx0ZXJhYmxlXG4gICAgICAgIHJlbW90ZVxuICAgICAgICByZXNlcnZlLWtleXdvcmRcbiAgICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgZW50ZXIgYSBrZXl3b3JkXCJcbiAgICAgICAgOnJlbW90ZS1tZXRob2Q9XCJyZW1vdGVNZXRob2RcIlxuICAgICAgICA6bG9hZGluZz1cImxvYWRpbmdcIlxuICAgICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICA+XG4gICAgICAgIDxlbC1vcHRpb25cbiAgICAgICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICAgICAgOmtleT1cIml0ZW0udmFsdWVcIlxuICAgICAgICAgIDpsYWJlbD1cIml0ZW0ubGFiZWxcIlxuICAgICAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgICAgICAvPlxuICAgICAgPC9lbC1zZWxlY3Q+XG4gICAgPC9kaXY+XG4gICAgPGRpdiBjbGFzcz1cIm0tNFwiPlxuICAgICAgPHA+dXNlIHJlbW90ZS1zaG93LXN1ZmZpeDwvcD5cbiAgICAgIDxlbC1zZWxlY3RcbiAgICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgICAgbXVsdGlwbGVcbiAgICAgICAgZmlsdGVyYWJsZVxuICAgICAgICByZW1vdGVcbiAgICAgICAgcmVzZXJ2ZS1rZXl3b3JkXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGVudGVyIGEga2V5d29yZFwiXG4gICAgICAgIHJlbW90ZS1zaG93LXN1ZmZpeFxuICAgICAgICA6cmVtb3RlLW1ldGhvZD1cInJlbW90ZU1ldGhvZFwiXG4gICAgICAgIDpsb2FkaW5nPVwibG9hZGluZ1wiXG4gICAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICAgID5cbiAgICAgICAgPGVsLW9wdGlvblxuICAgICAgICAgIHYtZm9yPVwiaXRlbSBpbiBvcHRpb25zXCJcbiAgICAgICAgICA6a2V5PVwiaXRlbS52YWx1ZVwiXG4gICAgICAgICAgOmxhYmVsPVwiaXRlbS5sYWJlbFwiXG4gICAgICAgICAgOnZhbHVlPVwiaXRlbS52YWx1ZVwiXG4gICAgICAgIC8+XG4gICAgICA8L2VsLXNlbGVjdD5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgb25Nb3VudGVkLCByZWYgfSBmcm9tICd2dWUnXG5cbmludGVyZmFjZSBMaXN0SXRlbSB7XG4gIHZhbHVlOiBzdHJpbmdcbiAgbGFiZWw6IHN0cmluZ1xufVxuXG5jb25zdCBsaXN0ID0gcmVmPExpc3RJdGVtW10+KFtdKVxuY29uc3Qgb3B0aW9ucyA9IHJlZjxMaXN0SXRlbVtdPihbXSlcbmNvbnN0IHZhbHVlID0gcmVmPHN0cmluZ1tdPihbXSlcbmNvbnN0IGxvYWRpbmcgPSByZWYoZmFsc2UpXG5cbm9uTW91bnRlZCgoKSA9PiB7XG4gIGxpc3QudmFsdWUgPSBzdGF0ZXMubWFwKChpdGVtKSA9PiB7XG4gICAgcmV0dXJuIHsgdmFsdWU6IGB2YWx1ZToke2l0ZW19YCwgbGFiZWw6IGBsYWJlbDoke2l0ZW19YCB9XG4gIH0pXG59KVxuXG5jb25zdCByZW1vdGVNZXRob2QgPSAocXVlcnk6IHN0cmluZykgPT4ge1xuICBpZiAocXVlcnkpIHtcbiAgICBsb2FkaW5nLnZhbHVlID0gdHJ1ZVxuICAgIHNldFRpbWVvdXQoKCkgPT4ge1xuICAgICAgbG9hZGluZy52YWx1ZSA9IGZhbHNlXG4gICAgICBvcHRpb25zLnZhbHVlID0gbGlzdC52YWx1ZS5maWx0ZXIoKGl0ZW0pID0+IHtcbiAgICAgICAgcmV0dXJuIGl0ZW0ubGFiZWwudG9Mb3dlckNhc2UoKS5pbmNsdWRlcyhxdWVyeS50b0xvd2VyQ2FzZSgpKVxuICAgICAgfSlcbiAgICB9LCAyMDApXG4gIH0gZWxzZSB7XG4gICAgb3B0aW9ucy52YWx1ZSA9IFtdXG4gIH1cbn1cblxuY29uc3Qgc3RhdGVzID0gW1xuICAnQWxhYmFtYScsXG4gICdBbGFza2EnLFxuICAnQXJpem9uYScsXG4gICdBcmthbnNhcycsXG4gICdDYWxpZm9ybmlhJyxcbiAgJ0NvbG9yYWRvJyxcbiAgJ0Nvbm5lY3RpY3V0JyxcbiAgJ0RlbGF3YXJlJyxcbiAgJ0Zsb3JpZGEnLFxuICAnR2VvcmdpYScsXG4gICdIYXdhaWknLFxuICAnSWRhaG8nLFxuICAnSWxsaW5vaXMnLFxuICAnSW5kaWFuYScsXG4gICdJb3dhJyxcbiAgJ0thbnNhcycsXG4gICdLZW50dWNreScsXG4gICdMb3Vpc2lhbmEnLFxuICAnTWFpbmUnLFxuICAnTWFyeWxhbmQnLFxuICAnTWFzc2FjaHVzZXR0cycsXG4gICdNaWNoaWdhbicsXG4gICdNaW5uZXNvdGEnLFxuICAnTWlzc2lzc2lwcGknLFxuICAnTWlzc291cmknLFxuICAnTW9udGFuYScsXG4gICdOZWJyYXNrYScsXG4gICdOZXZhZGEnLFxuICAnTmV3IEhhbXBzaGlyZScsXG4gICdOZXcgSmVyc2V5JyxcbiAgJ05ldyBNZXhpY28nLFxuICAnTmV3IFlvcmsnLFxuICAnTm9ydGggQ2Fyb2xpbmEnLFxuICAnTm9ydGggRGFrb3RhJyxcbiAgJ09oaW8nLFxuICAnT2tsYWhvbWEnLFxuICAnT3JlZ29uJyxcbiAgJ1Blbm5zeWx2YW5pYScsXG4gICdSaG9kZSBJc2xhbmQnLFxuICAnU291dGggQ2Fyb2xpbmEnLFxuICAnU291dGggRGFrb3RhJyxcbiAgJ1Rlbm5lc3NlZScsXG4gICdUZXhhcycsXG4gICdVdGFoJyxcbiAgJ1Zlcm1vbnQnLFxuICAnVmlyZ2luaWEnLFxuICAnV2FzaGluZ3RvbicsXG4gICdXZXN0IFZpcmdpbmlhJyxcbiAgJ1dpc2NvbnNpbicsXG4gICdXeW9taW5nJyxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/remote-search.vue)_

vue

```
<template>
  <div class="flex flex-wrap">
    <div class="m-4">
      <p>default</p>
      <el-select
        v-model="value"
        multiple
        filterable
        remote
        reserve-keyword
        placeholder="Please enter a keyword"
        :remote-method="remoteMethod"
        :loading="loading"
        style="width: 240px"
      >
        <el-option
          v-for="item in options"
          :key="item.value"
          :label="item.label"
          :value="item.value"
        />
      </el-select>
    </div>
    <div class="m-4">
      <p>use remote-show-suffix</p>
      <el-select
        v-model="value"
        multiple
        filterable
        remote
        reserve-keyword
        placeholder="Please enter a keyword"
        remote-show-suffix
        :remote-method="remoteMethod"
        :loading="loading"
        style="width: 240px"
      >
        <el-option
          v-for="item in options"
          :key="item.value"
          :label="item.label"
          :value="item.value"
        />
      </el-select>
    </div>
  </div>
</template>

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

interface ListItem {
  value: string
  label: string
}

const list = ref<ListItem[]>([])
const options = ref<ListItem[]>([])
const value = ref<string[]>([])
const loading = ref(false)

onMounted(() => {
  list.value = states.map((item) => {
    return { value: `value:${item}`, label: `label:${item}` }
  })
})

const remoteMethod = (query: string) => {
  if (query) {
    loading.value = true
    setTimeout(() => {
      loading.value = false
      options.value = list.value.filter((item) => {
        return item.label.toLowerCase().includes(query.toLowerCase())
      })
    }, 200)
  } else {
    options.value = []
  }
}

const states = [
  'Alabama',
  'Alaska',
  'Arizona',
  'Arkansas',
  'California',
  'Colorado',
  'Connecticut',
  'Delaware',
  'Florida',
  'Georgia',
  'Hawaii',
  'Idaho',
  'Illinois',
  'Indiana',
  'Iowa',
  'Kansas',
  'Kentucky',
  'Louisiana',
  'Maine',
  'Maryland',
  'Massachusetts',
  'Michigan',
  'Minnesota',
  'Mississippi',
  'Missouri',
  'Montana',
  'Nebraska',
  'Nevada',
  'New Hampshire',
  'New Jersey',
  'New Mexico',
  'New York',
  'North Carolina',
  'North Dakota',
  'Ohio',
  'Oklahoma',
  'Oregon',
  'Pennsylvania',
  'Rhode Island',
  'South Carolina',
  'South Dakota',
  'Tennessee',
  'Texas',
  'Utah',
  'Vermont',
  'Virginia',
  'Washington',
  'West Virginia',
  'Wisconsin',
  'Wyoming',
]
</script>
```

隐藏源代码

## 创建新的选项 [​](#创建新的选项)

创建并选中未包含在初始选项中的条目。

通过使用 `allow-create` 属性，用户可以通过输入框创建新项目。 为了使 `allow-create` 正常工作， `filterable` 的值必须为 `true`。 本例还使用了 `default-first-option` 属性， 在该属性为 `true` 的情况下，按下回车就可以选中当前选项列表中的第一个选项，无需使用鼠标或键盘方向键进行定位。

Choose tags for your article

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0XG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICBtdWx0aXBsZVxuICAgIGZpbHRlcmFibGVcbiAgICBhbGxvdy1jcmVhdGVcbiAgICBkZWZhdWx0LWZpcnN0LW9wdGlvblxuICAgIDpyZXNlcnZlLWtleXdvcmQ9XCJmYWxzZVwiXG4gICAgcGxhY2Vob2xkZXI9XCJDaG9vc2UgdGFncyBmb3IgeW91ciBhcnRpY2xlXCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gID5cbiAgICA8ZWwtb3B0aW9uXG4gICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICA6a2V5PVwiaXRlbS52YWx1ZVwiXG4gICAgICA6bGFiZWw9XCJpdGVtLmxhYmVsXCJcbiAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgIC8+XG4gIDwvZWwtc2VsZWN0PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWY8c3RyaW5nW10+KFtdKVxuY29uc3Qgb3B0aW9ucyA9IFtcbiAge1xuICAgIHZhbHVlOiAnSFRNTCcsXG4gICAgbGFiZWw6ICdIVE1MJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnQ1NTJyxcbiAgICBsYWJlbDogJ0NTUycsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ0phdmFTY3JpcHQnLFxuICAgIGxhYmVsOiAnSmF2YVNjcmlwdCcsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/allow-create.vue)_

vue

```
<template>
  <el-select
    v-model="value"
    multiple
    filterable
    allow-create
    default-first-option
    :reserve-keyword="false"
    placeholder="Choose tags for your article"
    style="width: 240px"
  >
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

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

const value = ref<string[]>([])
const options = [
  {
    value: 'HTML',
    label: 'HTML',
  },
  {
    value: 'CSS',
    label: 'CSS',
  },
  {
    value: 'JavaScript',
    label: 'JavaScript',
  },
]
</script>
```

隐藏源代码

## 使用值键 value-key 属性 [​](#使用值键-value-key-属性)

如果 Select 的绑定值为对象类型，请务必指定 `value-key` 作为它的唯一性标识。

通过使用 `value-key` 属性，可以正确处理带有重复label的数据。 这样虽然`label` 是重复的，但任可通过 `id` 来确认唯一性。

Select

selected option's description: no select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPGVsLXNlbGVjdFxuICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgIHZhbHVlLWtleT1cImlkXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCJcbiAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICA+XG4gICAgICA8ZWwtb3B0aW9uXG4gICAgICAgIHYtZm9yPVwiaXRlbSBpbiBvcHRpb25zXCJcbiAgICAgICAgOmtleT1cIml0ZW0uaWRcIlxuICAgICAgICA6bGFiZWw9XCJpdGVtLmxhYmVsXCJcbiAgICAgICAgOnZhbHVlPVwiaXRlbVwiXG4gICAgICAvPlxuICAgIDwvZWwtc2VsZWN0PlxuICAgIDxwPlxuICAgICAgc2VsZWN0ZWQgb3B0aW9uJ3MgZGVzY3JpcHRpb246XG4gICAgICB7eyB2YWx1ZSA/IHZhbHVlLmRlc2MgOiAnbm8gc2VsZWN0JyB9fVxuICAgIDwvcD5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG50eXBlIE9wdGlvbiA9IHtcbiAgaWQ6IG51bWJlclxuICBsYWJlbDogc3RyaW5nXG4gIGRlc2M6IHN0cmluZ1xufVxuY29uc3QgdmFsdWUgPSByZWY8T3B0aW9uPigpXG5jb25zdCBvcHRpb25zID0gcmVmKFtcbiAgeyBpZDogMSwgbGFiZWw6ICdPcHRpb24gQScsIGRlc2M6ICdPcHRpb24gQSAtIDIzMDUwNicgfSxcbiAgeyBpZDogMiwgbGFiZWw6ICdPcHRpb24gQicsIGRlc2M6ICdPcHRpb24gQiAtIDIzMDUwNicgfSxcbiAgeyBpZDogMywgbGFiZWw6ICdPcHRpb24gQycsIGRlc2M6ICdPcHRpb24gQyAtIDIzMDUwNicgfSxcbiAgeyBpZDogNCwgbGFiZWw6ICdPcHRpb24gQScsIGRlc2M6ICdPcHRpb24gQSAtIDIzMDUwNycgfSxcbl0pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/value-key.vue)_

vue

```
<template>
  <div class="m-4">
    <el-select
      v-model="value"
      value-key="id"
      placeholder="Select"
      style="width: 240px"
    >
      <el-option
        v-for="item in options"
        :key="item.id"
        :label="item.label"
        :value="item"
      />
    </el-select>
    <p>
      selected option's description:
      {{ value ? value.desc : 'no select' }}
    </p>
  </div>
</template>

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

type Option = {
  id: number
  label: string
  desc: string
}
const value = ref<Option>()
const options = ref([
  { id: 1, label: 'Option A', desc: 'Option A - 230506' },
  { id: 2, label: 'Option B', desc: 'Option B - 230506' },
  { id: 3, label: 'Option C', desc: 'Option C - 230506' },
  { id: 4, label: 'Option A', desc: 'Option A - 230507' },
])
</script>
```

隐藏源代码

## 自定义标签 2.5.0 [​](#自定义标签)

您可以自定义标签。

将自定义的标签插入 `el-select` 的 slot 中即可。 `collapse-tags`, `collapse-tags-tooltip`, `max-collapse-tags` 在此模式下不生效.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0IHYtbW9kZWw9XCJ2YWx1ZVwiIG11bHRpcGxlIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCIgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIj5cbiAgICA8ZWwtb3B0aW9uXG4gICAgICB2LWZvcj1cIml0ZW0gaW4gY29sb3JzXCJcbiAgICAgIDprZXk9XCJpdGVtLnZhbHVlXCJcbiAgICAgIDpsYWJlbD1cIml0ZW0ubGFiZWxcIlxuICAgICAgOnZhbHVlPVwiaXRlbS52YWx1ZVwiXG4gICAgPlxuICAgICAgPGRpdiBjbGFzcz1cImZsZXggaXRlbXMtY2VudGVyXCI+XG4gICAgICAgIDxlbC10YWcgOmNvbG9yPVwiaXRlbS52YWx1ZVwiIHN0eWxlPVwibWFyZ2luLXJpZ2h0OiA4cHhcIiBzaXplPVwic21hbGxcIiAvPlxuICAgICAgICA8c3BhbiA6c3R5bGU9XCJ7IGNvbG9yOiBpdGVtLnZhbHVlIH1cIj57eyBpdGVtLmxhYmVsIH19PC9zcGFuPlxuICAgICAgPC9kaXY+XG4gICAgPC9lbC1vcHRpb24+XG4gICAgPHRlbXBsYXRlICN0YWc+XG4gICAgICA8ZWwtdGFnIHYtZm9yPVwiY29sb3IgaW4gdmFsdWVcIiA6a2V5PVwiY29sb3JcIiA6Y29sb3I9XCJjb2xvclwiIC8+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1zZWxlY3Q+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZjxzdHJpbmdbXT4oW10pXG5jb25zdCBjb2xvcnMgPSBbXG4gIHtcbiAgICB2YWx1ZTogJyNFNjM0MTUnLFxuICAgIGxhYmVsOiAncmVkJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnI0ZGNjYwMCcsXG4gICAgbGFiZWw6ICdvcmFuZ2UnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICcjRkZERTBBJyxcbiAgICBsYWJlbDogJ3llbGxvdycsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJyMxRUM3OUQnLFxuICAgIGxhYmVsOiAnZ3JlZW4nLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICcjMTRDQ0NDJyxcbiAgICBsYWJlbDogJ2N5YW4nLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICcjNDE2N0YwJyxcbiAgICBsYWJlbDogJ2JsdWUnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICcjNjIyMkM5JyxcbiAgICBsYWJlbDogJ3B1cnBsZScsXG4gIH0sXG5dXG5jb2xvcnMuZm9yRWFjaCgoY29sb3IpID0+IHtcbiAgdmFsdWUudmFsdWUucHVzaChjb2xvci52YWx1ZSlcbn0pXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5lbC10YWcge1xuICBib3JkZXI6IG5vbmU7XG4gIGFzcGVjdC1yYXRpbzogMTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/custom-tag.vue)_

vue

```
<template>
  <el-select v-model="value" multiple placeholder="Select" style="width: 240px">
    <el-option
      v-for="item in colors"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    >
      <div class="flex items-center">
        <el-tag :color="item.value" style="margin-right: 8px" size="small" />
        <span :style="{ color: item.value }">{{ item.label }}</span>
      </div>
    </el-option>
    <template #tag>
      <el-tag v-for="color in value" :key="color" :color="color" />
    </template>
  </el-select>
</template>

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

const value = ref<string[]>([])
const colors = [
  {
    value: '#E63415',
    label: 'red',
  },
  {
    value: '#FF6600',
    label: 'orange',
  },
  {
    value: '#FFDE0A',
    label: 'yellow',
  },
  {
    value: '#1EC79D',
    label: 'green',
  },
  {
    value: '#14CCCC',
    label: 'cyan',
  },
  {
    value: '#4167F0',
    label: 'blue',
  },
  {
    value: '#6222C9',
    label: 'purple',
  },
]
colors.forEach((color) => {
  value.value.push(color.value)
})
</script>

<style scoped>
.el-tag {
  border: none;
  aspect-ratio: 1;
}
</style>
```

隐藏源代码

## 自定义加载 2.5.2 [​](#自定义加载)

修改加载区域内容

loading icon1

Please enter a keyword

loading icon2

Please enter a keyword

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXBcIj5cbiAgICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgICA8cD5sb2FkaW5nIGljb24xPC9wPlxuICAgICAgPGVsLXNlbGVjdFxuICAgICAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgICAgICBtdWx0aXBsZVxuICAgICAgICBmaWx0ZXJhYmxlXG4gICAgICAgIHJlbW90ZVxuICAgICAgICByZXNlcnZlLWtleXdvcmRcbiAgICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgZW50ZXIgYSBrZXl3b3JkXCJcbiAgICAgICAgOnJlbW90ZS1tZXRob2Q9XCJyZW1vdGVNZXRob2RcIlxuICAgICAgICA6bG9hZGluZz1cImxvYWRpbmdcIlxuICAgICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICA+XG4gICAgICAgIDxlbC1vcHRpb25cbiAgICAgICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICAgICAgOmtleT1cIml0ZW0udmFsdWVcIlxuICAgICAgICAgIDpsYWJlbD1cIml0ZW0ubGFiZWxcIlxuICAgICAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgICAgICAvPlxuICAgICAgICA8dGVtcGxhdGUgI2xvYWRpbmc+XG4gICAgICAgICAgPHN2ZyBjbGFzcz1cImNpcmN1bGFyXCIgdmlld0JveD1cIjAgMCA1MCA1MFwiPlxuICAgICAgICAgICAgPGNpcmNsZSBjbGFzcz1cInBhdGhcIiBjeD1cIjI1XCIgY3k9XCIyNVwiIHI9XCIyMFwiIGZpbGw9XCJub25lXCIgLz5cbiAgICAgICAgICA8L3N2Zz5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtc2VsZWN0PlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJtLTRcIj5cbiAgICAgIDxwPmxvYWRpbmcgaWNvbjI8L3A+XG4gICAgICA8ZWwtc2VsZWN0XG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgICAgIG11bHRpcGxlXG4gICAgICAgIGZpbHRlcmFibGVcbiAgICAgICAgcmVtb3RlXG4gICAgICAgIHJlc2VydmUta2V5d29yZFxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBlbnRlciBhIGtleXdvcmRcIlxuICAgICAgICA6cmVtb3RlLW1ldGhvZD1cInJlbW90ZU1ldGhvZFwiXG4gICAgICAgIDpsb2FkaW5nPVwibG9hZGluZ1wiXG4gICAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICAgID5cbiAgICAgICAgPGVsLW9wdGlvblxuICAgICAgICAgIHYtZm9yPVwiaXRlbSBpbiBvcHRpb25zXCJcbiAgICAgICAgICA6a2V5PVwiaXRlbS52YWx1ZVwiXG4gICAgICAgICAgOmxhYmVsPVwiaXRlbS5sYWJlbFwiXG4gICAgICAgICAgOnZhbHVlPVwiaXRlbS52YWx1ZVwiXG4gICAgICAgIC8+XG4gICAgICAgIDx0ZW1wbGF0ZSAjbG9hZGluZz5cbiAgICAgICAgICA8ZWwtaWNvbiBjbGFzcz1cImlzLWxvYWRpbmdcIj5cbiAgICAgICAgICAgIDxzdmcgY2xhc3M9XCJjaXJjdWxhclwiIHZpZXdCb3g9XCIwIDAgMjAgMjBcIj5cbiAgICAgICAgICAgICAgPGdcbiAgICAgICAgICAgICAgICBjbGFzcz1cInBhdGgyIGxvYWRpbmctcGF0aFwiXG4gICAgICAgICAgICAgICAgc3Ryb2tlLXdpZHRoPVwiMFwiXG4gICAgICAgICAgICAgICAgc3R5bGU9XCJhbmltYXRpb246IG5vbmU7IHN0cm9rZTogbm9uZVwiXG4gICAgICAgICAgICAgID5cbiAgICAgICAgICAgICAgICA8Y2lyY2xlIHI9XCIzLjM3NVwiIGNsYXNzPVwiZG90MVwiIHJ4PVwiMFwiIHJ5PVwiMFwiIC8+XG4gICAgICAgICAgICAgICAgPGNpcmNsZSByPVwiMy4zNzVcIiBjbGFzcz1cImRvdDJcIiByeD1cIjBcIiByeT1cIjBcIiAvPlxuICAgICAgICAgICAgICAgIDxjaXJjbGUgcj1cIjMuMzc1XCIgY2xhc3M9XCJkb3Q0XCIgcng9XCIwXCIgcnk9XCIwXCIgLz5cbiAgICAgICAgICAgICAgICA8Y2lyY2xlIHI9XCIzLjM3NVwiIGNsYXNzPVwiZG90M1wiIHJ4PVwiMFwiIHJ5PVwiMFwiIC8+XG4gICAgICAgICAgICAgIDwvZz5cbiAgICAgICAgICAgIDwvc3ZnPlxuICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtc2VsZWN0PlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBvbk1vdW50ZWQsIHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW50ZXJmYWNlIExpc3RJdGVtIHtcbiAgdmFsdWU6IHN0cmluZ1xuICBsYWJlbDogc3RyaW5nXG59XG5cbmNvbnN0IGxpc3QgPSByZWY8TGlzdEl0ZW1bXT4oW10pXG5jb25zdCBvcHRpb25zID0gcmVmPExpc3RJdGVtW10+KFtdKVxuY29uc3QgdmFsdWUgPSByZWY8c3RyaW5nW10+KFtdKVxuY29uc3QgbG9hZGluZyA9IHJlZihmYWxzZSlcblxub25Nb3VudGVkKCgpID0+IHtcbiAgbGlzdC52YWx1ZSA9IHN0YXRlcy5tYXAoKGl0ZW0pID0+IHtcbiAgICByZXR1cm4geyB2YWx1ZTogYHZhbHVlOiR7aXRlbX1gLCBsYWJlbDogYGxhYmVsOiR7aXRlbX1gIH1cbiAgfSlcbn0pXG5cbmNvbnN0IHJlbW90ZU1ldGhvZCA9IChxdWVyeTogc3RyaW5nKSA9PiB7XG4gIGlmIChxdWVyeSkge1xuICAgIGxvYWRpbmcudmFsdWUgPSB0cnVlXG4gICAgc2V0VGltZW91dCgoKSA9PiB7XG4gICAgICBsb2FkaW5nLnZhbHVlID0gZmFsc2VcbiAgICAgIG9wdGlvbnMudmFsdWUgPSBsaXN0LnZhbHVlLmZpbHRlcigoaXRlbSkgPT4ge1xuICAgICAgICByZXR1cm4gaXRlbS5sYWJlbC50b0xvd2VyQ2FzZSgpLmluY2x1ZGVzKHF1ZXJ5LnRvTG93ZXJDYXNlKCkpXG4gICAgICB9KVxuICAgIH0sIDMwMDApXG4gIH0gZWxzZSB7XG4gICAgb3B0aW9ucy52YWx1ZSA9IFtdXG4gIH1cbn1cblxuY29uc3Qgc3RhdGVzID0gW1xuICAnQWxhYmFtYScsXG4gICdBbGFza2EnLFxuICAnQXJpem9uYScsXG4gICdBcmthbnNhcycsXG4gICdDYWxpZm9ybmlhJyxcbiAgJ0NvbG9yYWRvJyxcbiAgJ0Nvbm5lY3RpY3V0JyxcbiAgJ0RlbGF3YXJlJyxcbiAgJ0Zsb3JpZGEnLFxuICAnR2VvcmdpYScsXG4gICdIYXdhaWknLFxuICAnSWRhaG8nLFxuICAnSWxsaW5vaXMnLFxuICAnSW5kaWFuYScsXG4gICdJb3dhJyxcbiAgJ0thbnNhcycsXG4gICdLZW50dWNreScsXG4gICdMb3Vpc2lhbmEnLFxuICAnTWFpbmUnLFxuICAnTWFyeWxhbmQnLFxuICAnTWFzc2FjaHVzZXR0cycsXG4gICdNaWNoaWdhbicsXG4gICdNaW5uZXNvdGEnLFxuICAnTWlzc2lzc2lwcGknLFxuICAnTWlzc291cmknLFxuICAnTW9udGFuYScsXG4gICdOZWJyYXNrYScsXG4gICdOZXZhZGEnLFxuICAnTmV3IEhhbXBzaGlyZScsXG4gICdOZXcgSmVyc2V5JyxcbiAgJ05ldyBNZXhpY28nLFxuICAnTmV3IFlvcmsnLFxuICAnTm9ydGggQ2Fyb2xpbmEnLFxuICAnTm9ydGggRGFrb3RhJyxcbiAgJ09oaW8nLFxuICAnT2tsYWhvbWEnLFxuICAnT3JlZ29uJyxcbiAgJ1Blbm5zeWx2YW5pYScsXG4gICdSaG9kZSBJc2xhbmQnLFxuICAnU291dGggQ2Fyb2xpbmEnLFxuICAnU291dGggRGFrb3RhJyxcbiAgJ1Rlbm5lc3NlZScsXG4gICdUZXhhcycsXG4gICdVdGFoJyxcbiAgJ1Zlcm1vbnQnLFxuICAnVmlyZ2luaWEnLFxuICAnV2FzaGluZ3RvbicsXG4gICdXZXN0IFZpcmdpbmlhJyxcbiAgJ1dpc2NvbnNpbicsXG4gICdXeW9taW5nJyxcbl1cbjwvc2NyaXB0PlxuXG48c3R5bGU+XG4uZWwtc2VsZWN0LWRyb3Bkb3duX19sb2FkaW5nIHtcbiAgZGlzcGxheTogZmxleDtcbiAganVzdGlmeS1jb250ZW50OiBjZW50ZXI7XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG4gIGhlaWdodDogMTAwcHg7XG4gIGZvbnQtc2l6ZTogMjBweDtcbn1cblxuLmNpcmN1bGFyIHtcbiAgZGlzcGxheTogaW5saW5lO1xuICBoZWlnaHQ6IDMwcHg7XG4gIHdpZHRoOiAzMHB4O1xuICBhbmltYXRpb246IGxvYWRpbmctcm90YXRlIDJzIGxpbmVhciBpbmZpbml0ZTtcbn1cbi5wYXRoIHtcbiAgYW5pbWF0aW9uOiBsb2FkaW5nLWRhc2ggMS41cyBlYXNlLWluLW91dCBpbmZpbml0ZTtcbiAgc3Ryb2tlLWRhc2hhcnJheTogOTAsIDE1MDtcbiAgc3Ryb2tlLWRhc2hvZmZzZXQ6IDA7XG4gIHN0cm9rZS13aWR0aDogMjtcbiAgc3Ryb2tlOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbiAgc3Ryb2tlLWxpbmVjYXA6IHJvdW5kO1xufVxuLmxvYWRpbmctcGF0aCAuZG90MSB7XG4gIHRyYW5zZm9ybTogdHJhbnNsYXRlKDMuNzVweCwgMy43NXB4KTtcbiAgZmlsbDogdmFyKC0tZWwtY29sb3ItcHJpbWFyeSk7XG4gIGFuaW1hdGlvbjogY3VzdG9tLXNwaW4tbW92ZSAxcyBpbmZpbml0ZSBsaW5lYXIgYWx0ZXJuYXRlO1xuICBvcGFjaXR5OiAwLjM7XG59XG4ubG9hZGluZy1wYXRoIC5kb3QyIHtcbiAgdHJhbnNmb3JtOiB0cmFuc2xhdGUoY2FsYygxMDAlIC0gMy43NXB4KSwgMy43NXB4KTtcbiAgZmlsbDogdmFyKC0tZWwtY29sb3ItcHJpbWFyeSk7XG4gIGFuaW1hdGlvbjogY3VzdG9tLXNwaW4tbW92ZSAxcyBpbmZpbml0ZSBsaW5lYXIgYWx0ZXJuYXRlO1xuICBvcGFjaXR5OiAwLjM7XG4gIGFuaW1hdGlvbi1kZWxheTogMC40cztcbn1cbi5sb2FkaW5nLXBhdGggLmRvdDMge1xuICB0cmFuc2Zvcm06IHRyYW5zbGF0ZSgzLjc1cHgsIGNhbGMoMTAwJSAtIDMuNzVweCkpO1xuICBmaWxsOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbiAgYW5pbWF0aW9uOiBjdXN0b20tc3Bpbi1tb3ZlIDFzIGluZmluaXRlIGxpbmVhciBhbHRlcm5hdGU7XG4gIG9wYWNpdHk6IDAuMztcbiAgYW5pbWF0aW9uLWRlbGF5OiAxLjJzO1xufVxuLmxvYWRpbmctcGF0aCAuZG90NCB7XG4gIHRyYW5zZm9ybTogdHJhbnNsYXRlKGNhbGMoMTAwJSAtIDMuNzVweCksIGNhbGMoMTAwJSAtIDMuNzVweCkpO1xuICBmaWxsOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbiAgYW5pbWF0aW9uOiBjdXN0b20tc3Bpbi1tb3ZlIDFzIGluZmluaXRlIGxpbmVhciBhbHRlcm5hdGU7XG4gIG9wYWNpdHk6IDAuMztcbiAgYW5pbWF0aW9uLWRlbGF5OiAwLjhzO1xufVxuQGtleWZyYW1lcyBsb2FkaW5nLXJvdGF0ZSB7XG4gIHRvIHtcbiAgICB0cmFuc2Zvcm06IHJvdGF0ZSgzNjBkZWcpO1xuICB9XG59XG5Aa2V5ZnJhbWVzIGxvYWRpbmctZGFzaCB7XG4gIDAlIHtcbiAgICBzdHJva2UtZGFzaGFycmF5OiAxLCAyMDA7XG4gICAgc3Ryb2tlLWRhc2hvZmZzZXQ6IDA7XG4gIH1cbiAgNTAlIHtcbiAgICBzdHJva2UtZGFzaGFycmF5OiA5MCwgMTUwO1xuICAgIHN0cm9rZS1kYXNob2Zmc2V0OiAtNDBweDtcbiAgfVxuICAxMDAlIHtcbiAgICBzdHJva2UtZGFzaGFycmF5OiA5MCwgMTUwO1xuICAgIHN0cm9rZS1kYXNob2Zmc2V0OiAtMTIwcHg7XG4gIH1cbn1cbkBrZXlmcmFtZXMgY3VzdG9tLXNwaW4tbW92ZSB7XG4gIHRvIHtcbiAgICBvcGFjaXR5OiAxO1xuICB9XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/custom-loading.vue)_

vue

```
<template>
  <div class="flex flex-wrap">
    <div class="m-4">
      <p>loading icon1</p>
      <el-select
        v-model="value"
        multiple
        filterable
        remote
        reserve-keyword
        placeholder="Please enter a keyword"
        :remote-method="remoteMethod"
        :loading="loading"
        style="width: 240px"
      >
        <el-option
          v-for="item in options"
          :key="item.value"
          :label="item.label"
          :value="item.value"
        />
        <template #loading>
          <svg class="circular" viewBox="0 0 50 50">
            <circle class="path" cx="25" cy="25" r="20" fill="none" />
          </svg>
        </template>
      </el-select>
    </div>
    <div class="m-4">
      <p>loading icon2</p>
      <el-select
        v-model="value"
        multiple
        filterable
        remote
        reserve-keyword
        placeholder="Please enter a keyword"
        :remote-method="remoteMethod"
        :loading="loading"
        style="width: 240px"
      >
        <el-option
          v-for="item in options"
          :key="item.value"
          :label="item.label"
          :value="item.value"
        />
        <template #loading>
          <el-icon class="is-loading">
            <svg class="circular" viewBox="0 0 20 20">
              <g
                class="path2 loading-path"
                stroke-width="0"
                style="animation: none; stroke: none"
              >
                <circle r="3.375" class="dot1" rx="0" ry="0" />
                <circle r="3.375" class="dot2" rx="0" ry="0" />
                <circle r="3.375" class="dot4" rx="0" ry="0" />
                <circle r="3.375" class="dot3" rx="0" ry="0" />
              </g>
            </svg>
          </el-icon>
        </template>
      </el-select>
    </div>
  </div>
</template>

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

interface ListItem {
  value: string
  label: string
}

const list = ref<ListItem[]>([])
const options = ref<ListItem[]>([])
const value = ref<string[]>([])
const loading = ref(false)

onMounted(() => {
  list.value = states.map((item) => {
    return { value: `value:${item}`, label: `label:${item}` }
  })
})

const remoteMethod = (query: string) => {
  if (query) {
    loading.value = true
    setTimeout(() => {
      loading.value = false
      options.value = list.value.filter((item) => {
        return item.label.toLowerCase().includes(query.toLowerCase())
      })
    }, 3000)
  } else {
    options.value = []
  }
}

const states = [
  'Alabama',
  'Alaska',
  'Arizona',
  'Arkansas',
  'California',
  'Colorado',
  'Connecticut',
  'Delaware',
  'Florida',
  'Georgia',
  'Hawaii',
  'Idaho',
  'Illinois',
  'Indiana',
  'Iowa',
  'Kansas',
  'Kentucky',
  'Louisiana',
  'Maine',
  'Maryland',
  'Massachusetts',
  'Michigan',
  'Minnesota',
  'Mississippi',
  'Missouri',
  'Montana',
  'Nebraska',
  'Nevada',
  'New Hampshire',
  'New Jersey',
  'New Mexico',
  'New York',
  'North Carolina',
  'North Dakota',
  'Ohio',
  'Oklahoma',
  'Oregon',
  'Pennsylvania',
  'Rhode Island',
  'South Carolina',
  'South Dakota',
  'Tennessee',
  'Texas',
  'Utah',
  'Vermont',
  'Virginia',
  'Washington',
  'West Virginia',
  'Wisconsin',
  'Wyoming',
]
</script>

<style>
.el-select-dropdown__loading {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100px;
  font-size: 20px;
}

.circular {
  display: inline;
  height: 30px;
  width: 30px;
  animation: loading-rotate 2s linear infinite;
}
.path {
  animation: loading-dash 1.5s ease-in-out infinite;
  stroke-dasharray: 90, 150;
  stroke-dashoffset: 0;
  stroke-width: 2;
  stroke: var(--el-color-primary);
  stroke-linecap: round;
}
.loading-path .dot1 {
  transform: translate(3.75px, 3.75px);
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
}
.loading-path .dot2 {
  transform: translate(calc(100% - 3.75px), 3.75px);
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 0.4s;
}
.loading-path .dot3 {
  transform: translate(3.75px, calc(100% - 3.75px));
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 1.2s;
}
.loading-path .dot4 {
  transform: translate(calc(100% - 3.75px), calc(100% - 3.75px));
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 0.8s;
}
@keyframes loading-rotate {
  to {
    transform: rotate(360deg);
  }
}
@keyframes loading-dash {
  0% {
    stroke-dasharray: 1, 200;
    stroke-dashoffset: 0;
  }
  50% {
    stroke-dasharray: 90, 150;
    stroke-dashoffset: -40px;
  }
  100% {
    stroke-dasharray: 90, 150;
    stroke-dashoffset: -120px;
  }
}
@keyframes custom-spin-move {
  to {
    opacity: 1;
  }
}
</style>
```

隐藏源代码

## 空值配置2.7.0 [​](#空值配置)

若想配置如空字符串为有效值而不是空值，可以配置 `empty-values` 为 `[null, undefined]`.

如果您想要将清空值更改为 `null`, 请设置 `value-on-clear` 为 `null`

All

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0XG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICA6ZW1wdHktdmFsdWVzPVwiW251bGwsIHVuZGVmaW5lZF1cIlxuICAgIDp2YWx1ZS1vbi1jbGVhcj1cIm51bGxcIlxuICAgIGNsZWFyYWJsZVxuICAgIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgQGNsZWFyPVwiaGFuZGxlQ2xlYXJcIlxuICA+XG4gICAgPGVsLW9wdGlvblxuICAgICAgdi1mb3I9XCJpdGVtIGluIG9wdGlvbnNcIlxuICAgICAgOmtleT1cIml0ZW0udmFsdWVcIlxuICAgICAgOmxhYmVsPVwiaXRlbS5sYWJlbFwiXG4gICAgICA6dmFsdWU9XCJpdGVtLnZhbHVlXCJcbiAgICAvPlxuICA8L2VsLXNlbGVjdD5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBFbE1lc3NhZ2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHZhbHVlID0gcmVmKCcnKVxuXG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6ICcnLFxuICAgIGxhYmVsOiAnQWxsJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uMScsXG4gICAgbGFiZWw6ICdPcHRpb24xJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uMicsXG4gICAgbGFiZWw6ICdPcHRpb24yJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uMycsXG4gICAgbGFiZWw6ICdPcHRpb24zJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uNCcsXG4gICAgbGFiZWw6ICdPcHRpb240JyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uNScsXG4gICAgbGFiZWw6ICdPcHRpb241JyxcbiAgfSxcbl1cblxuY29uc3QgaGFuZGxlQ2xlYXIgPSAoKSA9PiB7XG4gIEVsTWVzc2FnZS5pbmZvKGBUaGUgY2xlYXIgdmFsdWUgaXM6ICR7dmFsdWUudmFsdWV9YClcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/empty-values.vue)_

vue

```
<template>
  <el-select
    v-model="value"
    :empty-values="[null, undefined]"
    :value-on-clear="null"
    clearable
    placeholder="Select"
    style="width: 240px"
    @clear="handleClear"
  >
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElMessage } from 'element-plus'

const value = ref('')

const options = [
  {
    value: '',
    label: 'All',
  },
  {
    value: 'Option1',
    label: 'Option1',
  },
  {
    value: 'Option2',
    label: 'Option2',
  },
  {
    value: 'Option3',
    label: 'Option3',
  },
  {
    value: 'Option4',
    label: 'Option4',
  },
  {
    value: 'Option5',
    label: 'Option5',
  },
]

const handleClear = () => {
  ElMessage.info(`The clear value is: ${value.value}`)
}
</script>
```

隐藏源代码

## 自定义标签 2.7.4 [​](#自定义标签-1)

您可以自定义标签

Label1: Option1

Label1: Option1

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTQgaXRlbXMtY2VudGVyXCI+XG4gICAgPGVsLXNlbGVjdFxuICAgICAgdi1tb2RlbD1cInZhbHVlMVwiXG4gICAgICBwbGFjZWhvbGRlcj1cIlNlbGVjdFwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICBjbGVhcmFibGVcbiAgICA+XG4gICAgICA8dGVtcGxhdGUgI2xhYmVsPVwieyBsYWJlbCwgdmFsdWUgfVwiPlxuICAgICAgICA8c3Bhbj57eyBsYWJlbCB9fTogPC9zcGFuPlxuICAgICAgICA8c3BhbiBzdHlsZT1cImZvbnQtd2VpZ2h0OiBib2xkXCI+e3sgdmFsdWUgfX08L3NwYW4+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgPGVsLW9wdGlvblxuICAgICAgICB2LWZvcj1cIml0ZW0gaW4gb3B0aW9uc1wiXG4gICAgICAgIDprZXk9XCJpdGVtLnZhbHVlXCJcbiAgICAgICAgOmxhYmVsPVwiaXRlbS5sYWJlbFwiXG4gICAgICAgIDp2YWx1ZT1cIml0ZW0udmFsdWVcIlxuICAgICAgLz5cbiAgICA8L2VsLXNlbGVjdD5cblxuICAgIDxlbC1zZWxlY3RcbiAgICAgIHYtbW9kZWw9XCJ2YWx1ZTJcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJTZWxlY3RcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgY2xlYXJhYmxlXG4gICAgICBtdWx0aXBsZVxuICAgID5cbiAgICAgIDx0ZW1wbGF0ZSAjbGFiZWw9XCJ7IGxhYmVsLCB2YWx1ZSB9XCI+XG4gICAgICAgIDxzcGFuPnt7IGxhYmVsIH19OiA8L3NwYW4+XG4gICAgICAgIDxzcGFuIHN0eWxlPVwiZm9udC13ZWlnaHQ6IGJvbGRcIj57eyB2YWx1ZSB9fTwvc3Bhbj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8ZWwtb3B0aW9uXG4gICAgICAgIHYtZm9yPVwiaXRlbSBpbiBvcHRpb25zXCJcbiAgICAgICAgOmtleT1cIml0ZW0udmFsdWVcIlxuICAgICAgICA6bGFiZWw9XCJpdGVtLmxhYmVsXCJcbiAgICAgICAgOnZhbHVlPVwiaXRlbS52YWx1ZVwiXG4gICAgICAvPlxuICAgIDwvZWwtc2VsZWN0PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZjxzdHJpbmc+KCdPcHRpb24xJylcbmNvbnN0IHZhbHVlMiA9IHJlZjxzdHJpbmdbXT4oWydPcHRpb24xJ10pXG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgdmFsdWU6ICdPcHRpb24xJyxcbiAgICBsYWJlbDogJ0xhYmVsMScsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjInLFxuICAgIGxhYmVsOiAnTGFiZWwyJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnT3B0aW9uMycsXG4gICAgbGFiZWw6ICdMYWJlbDMnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICdPcHRpb240JyxcbiAgICBsYWJlbDogJ0xhYmVsNCcsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJ09wdGlvbjUnLFxuICAgIGxhYmVsOiAnTGFiZWw1JyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select/custom-label.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-4 items-center">
    <el-select
      v-model="value1"
      placeholder="Select"
      style="width: 240px"
      clearable
    >
      <template #label="{ label, value }">
        <span>{{ label }}: </span>
        <span style="font-weight: bold">{{ value }}</span>
      </template>
      <el-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </el-select>

    <el-select
      v-model="value2"
      placeholder="Select"
      style="width: 240px"
      clearable
      multiple
    >
      <template #label="{ label, value }">
        <span>{{ label }}: </span>
        <span style="font-weight: bold">{{ value }}</span>
      </template>
      <el-option
        v-for="item in options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </el-select>
  </div>
</template>

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

const value1 = ref<string>('Option1')
const value2 = ref<string[]>(['Option1'])
const options = [
  {
    value: 'Option1',
    label: 'Label1',
  },
  {
    value: 'Option2',
    label: 'Label2',
  },
  {
    value: 'Option3',
    label: 'Label3',
  },
  {
    value: 'Option4',
    label: 'Label4',
  },
  {
    value: 'Option5',
    label: 'Label5',
  },
]
</script>

<style scoped></style>
```

隐藏源代码

## Select API [​](#select-api)

### Select Attributes [​](#select-attributes)

| 属性名 | 说明 | 类型 | Default |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `string` / `number` / `boolean` / `object` / `array` | — |
| multiple | 是否多选 | `boolean` | false |
| options 2.10.5 | 选项的数据源， `value` 的 key 和 `label` 和 `disabled`可以通过 `props`自定义. | `array` | — |
| [props](#props) 2.10.5 | options 的配置 | `object` | — |
| disabled | 是否禁用 | `boolean` | false |
| value-key | 作为 value 唯一标识的键名，绑定值为对象类型时必填 | `string` | value |
| size | 输入框尺寸 | `enum` | — |
| clearable | 是否可以清空选项 | `boolean` | false |
| collapse-tags | 多选时是否将选中值按文字的形式展示 | `boolean` | false |
| collapse-tags-tooltip 2.3.0 | 当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此属性，`collapse-tags`属性必须设定为 true | `boolean` | false |
| [tag-tooltip](#tag-tooltip) 2.13.3 | 折叠标签工具提示的配置对象。 要使用此项， `collapse-tags` 和 `collapse-tags-tooltip` 必须为 true | `object` | {} |
| multiple-limit | `multiple` 属性设置为 `true` 时，代表多选场景下用户最多可以选择的项目数， 为 0 则不限制 | `number` | 0 |
| id | 原生 input 的 id | `string` | — |
| name | Select 输入框的原生 name 属性 | `string` | — |
| effect | tooltip 主题，内置了 `dark` / `light` 两种 | `enum` / `string` | light |
| autocomplete | Select 输入框的原生 autocomplete 属性 | `string` | off |
| placeholder | 占位符，默认为“Select” | `string` | — |
| filterable | Select 组件是否可筛选 | `boolean` | false |
| allow-create | 是否允许用户创建新条目， 当`filterable`设置为 true 时才会生效 | `boolean` | false |
| filter-method | 自定义筛选方法的第一个参数是当前输入的值。 只有当 `filterable` 设置为 true 时才会生效。 | `Function` | — |
| remote | 其中的选项是否从服务器远程加载 | `boolean` | false |
| debounce 2.11.7 | 远程搜索时的防抖延迟（以毫秒为单位） | `number` | 300 |
| remote-method | 当输入值发生变化时触发的函数。 它的参数就是当前的输入值。 当`filterable`设置为 true 时才会生效 | `Function` | — |
| remote-show-suffix | 远程搜索方法显示后缀图标 | `boolean` | false |
| loading | 是否正在从远程获取数据 | `boolean` | false |
| loading-text | 从服务器加载数据时显示的文本，默认为“Loading” | `string` | — |
| no-match-text | 搜索条件无匹配时显示的文字，也可以使用 `empty` 插槽设置，默认是 “No matching data'” | `string` | — |
| no-data-text | 无选项时显示的文字，也可以使用 `empty` 插槽设置自定义内容，默认是 “No data” | `string` | — |
| popper-class | 为 Select 下拉菜单和标签提示设置自定义类名 | `string` | '' |
| popper-style 2.11.0 | 为 Select 下拉菜单和标签提示设置自定义样式 | `string` / `object` | — |
| reserve-keyword | 当 `multiple` 和 `filterable`被设置为 true 时，是否在选中一个选项后保留当前的搜索关键词 | `boolean` | true |
| default-first-option | 是否在输入框按下回车时，选择第一个匹配项。 需配合 `filterable` 或 `remote` 使用 | `boolean` | false |
| teleported | 是否使用 teleport。设置成 `true`则会被追加到 `append-to` 的位置 | `boolean` | true |
| append-to 2.8.4 | 下拉框挂载到哪个 DOM 元素 | `CSSSelector` / `HTMLElement` | — |
| persistent | 当下拉选择器未被激活并且`persistent`设置为`false`，选择器会被删除。 | `boolean` | true |
| automatic-dropdown | 对于不可搜索的 Select，是否在输入框获得焦点后自动弹出选项菜单 | `boolean` | false |
| clear-icon | 自定义清除图标 | `string` / `object` | CircleClose |
| fit-input-width | 下拉框的宽度是否与输入框相同 | `boolean` | false |
| suffix-icon | 自定义后缀图标组件 | `string` / `object` | ArrowDown |
| tag-type | 标签类型 | `enum` | info |
| tag-effect 2.7.7 | 标签效果 | `enum` | light |
| validate-event | 是否触发表单验证 | `boolean` | true |
| offset 2.8.8 | 下拉面板偏移量 | `number` | 12 |
| show-arrow 2.8.8 | 下拉菜单的内容是否有箭头 | `boolean` | true |
| placement 2.2.17 | 下拉框出现的位置 | `enum` | bottom-start |
| fallback-placements 2.5.6 | dropdown 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | `array` | \['bottom-start', 'top-start', 'right', 'left'\] |
| max-collapse-tags 2.3.0 | 需要显示的 Tag 的最大数量 只有当 `collapse-tags` 设置为 true 时才会生效。 | `number` | 1 |
| popper-options | [popper.js](https://popper.js.org/docs/v2/) 参数 | `object`refer to [popper.js](https://popper.js.org/docs/v2/) doc | {} |
| aria-label a11y | 等价于原生 input `aria-label` 属性 | `string` | — |
| empty-values 2.7.0 | 组件的空值配置， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `array` | — |
| value-on-clear 2.7.0 | 清空选项的值， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `string` / `number` / `boolean` / `Function` | — |
| suffix-transition deprecated | 下拉菜单显示/消失时后缀图标的动画 | `boolean` | true |
| tabindex 2.9.0 | input 的 tabindex | `string` / `number` | — |

WARNING

`suffix-transition` 已被 **弃用**, 并 **将会** 在2.4.0中删除, 请使用覆盖样式方案。

### Props [​](#props)

| Attribute | 说明 | Type | Default |
| --- | --- | --- | --- |
| value | 指定选项的值为选项对象的某个属性值 | `string` | value |
| label | 指定节点标签为节点对象的某个属性值 | `string` | label |
| options 2.11.0 | 指定选项的子选项为选项对象的某个属性值 | `string` | options |
| disabled | 指定选项的禁用为选项对象的某个属性值 | `string` | disabled |

### tag-tooltip 2.13.3 [​](#tag-tooltip)

备用机制

标签工具提示中的属性遵循此优先级顺序：

1.  在标签工具提示对象中明确定义的字段。
2.  从 el-select 继承的共享属性（例如 effect、popper-class、popper-style、teleported、append-to、popper-options）。
3.  底层 el-tooltip 组件的默认值。 这样，您就可以覆盖标签的特定工具提示行为，同时保持与默认的“选择”下拉菜单的一致性。

自定义容器位置

当将 Tooltip 添加到自定义容器时（通过 `append-to` 属性），应将容器配置为 `position: relative` 或 `position: absolute`，以确保准确定位。 此外，如果需要防止工具提示超出其边界，可以对容器应用 `overflow: hidden`。

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| append-to | 指示 Tooltip 的内容将附加在哪一个网页元素上 | `CSSSelector` / `HTMLElement` | — |
| placement | Tooltip 组件出现的位置 | `enum` | bottom |
| fallback-placements | Tooltip 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | `array` | \['bottom', 'top', 'right', 'left'\] |
| effect | 文字提示（Tooltip）的主题，内置`dark`和`light`两种。 | `enum` / `string` | — |
| popper-class | 为 Tooltip 的 popper 添加自定义类名 | `string` | — |
| popper-style | 为 Tooltip 的 popper 添加自定义样式 | `string` / `object` | — |
| transition | Tooltip 所应用过渡动画的名称 | `string` | — |
| teleported | 是否使用 teleport。设置成 `true`则会被追加到 `append-to` 的位置 | `boolean` | — |
| popper-options | [popper.js](https://popper.js.org/docs/v2/) 参数 | `object`refer to [popper.js](https://popper.js.org/docs/v2/) doc | — |
| show-after | 在触发后多久显示内容，单位毫秒 | `number` | — |
| hide-after | 关闭时的延迟 | `number` | — |
| auto-close | tooltip 出现后自动隐藏延时，单位毫秒 | `number` | — |
| offset | Tooltip 出现位置的偏移量 | `number` | — |

### Select Events [​](#select-events)

| 事件名 | 说明 | Type |
| --- | --- | --- |
| change | 选中值发生变化时触发 | `Function` |
| visible-change | 下拉框出现/隐藏时触发 | `Function` |
| remove-tag | 多选模式下移除tag时触发 | `Function` |
| clear | 可清空的单选模式下用户点击清空按钮时触发 | `Function` |
| blur | 当 input 失去焦点时触发 | `Function` |
| focus | 当 input 获得焦点时触发 | `Function` |
| popup-scroll 2.9.4 | 下拉滚动时触发 | `Function` |
| end-reached 2.14.0 | 下拉滚动到结束时触发器 | `Function` |

### Select Slots [​](#select-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | option 组件列表 | Option Group / Option |
| header 2.4.3 | 下拉列表顶部的内容 | — |
| footer 2.4.3 | 下拉列表底部的内容 | — |
| prefix | Select 组件头部内容 | — |
| empty | 无选项时的列表 | ::: |
| tag 2.5.0 | 作为 Select 组件的内容时，子标签 `data`、`selectDisabled` 和 `deleteTag` 是在版本 2.10.3 中新增的。 | `object` |
| loading 2.5.2 | select 组件自定义 loading内容 | — |
| label 2.7.4 | select 组件自定义标签内容 `index` 引入于2.11.2 | `object` |

### Select Exposes [​](#select-exposes)

| 方法名 | 详情 | 类型 |
| --- | --- | --- |
| focus | 使选择器的输入框获取焦点 | `Function` |
| blur | 使选择器的输入框失去焦点，并隐藏下拉框 | `Function` |
| selectedLabel 2.8.5 | 获取当前选中的标签 | `object` |

## Option Group API [​](#option-group-api)

### Option Group Attributes [​](#option-group-attributes)

| 名称 | 详情 | 类型 | 默认值 |
| --- | --- | --- | --- |
| label | 分组的名称 | `string` | — |
| disabled | 是否将该分组下所有选项置为禁用 | `boolean` | false |

### Option Group Slots [​](#option-group-slots)

| 插槽名 | 说明 | Subtags |
| --- | --- | --- |
| default | 自定义默认内容 | Option |

## Option API [​](#option-api)

### Option Attributes [​](#option-attributes)

| Name | 描述 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value | 选项的值 | `string` / `number` / `boolean` / `object` | — |
| label | 选项的标签，若不设置则默认与`value`相同 | `string` / `number` | — |
| disabled | 是否禁用该选项 | `boolean` | false |

### Option Slots [​](#option-slots)

| 名称 | 说明 |
| --- | --- |
| default | 默认插槽内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/select) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/select.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/select.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/30046649?v=4&size=64)](https://github.com/MrWeilian)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/27912232?v=4&size=64)](https://github.com/Fuphoenixes)[![](https://avatars.githubusercontent.com/u/132551120?v=4&size=64)](https://github.com/YiMo1)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/204166003?v=4&size=64)](https://github.com/Putia3)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/48341368?v=4&size=64)](https://github.com/HaceraI)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/166777320?v=4&size=64)](https://github.com/ixyzorg)[![](https://avatars.githubusercontent.com/u/24487727?v=4&size=64)](https://github.com/LostElkByte)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/58782768?v=4&size=64)](https://github.com/dddssw)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/50254496?v=4&size=64)](https://github.com/LoTwT)[![](https://avatars.githubusercontent.com/u/47178158?v=4&size=64)](https://github.com/Aaron-zon)[![](https://avatars.githubusercontent.com/u/32354856?v=4&size=64)](https://github.com/baiwusanyu-c)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/36978416?v=4&size=64)](https://github.com/SimonaliaChen)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/73086438?v=4&size=64)](https://github.com/Cheerwhy)[![](https://avatars.githubusercontent.com/u/108655466?v=4&size=64)](https://github.com/Karolis-Stoncius)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)[![](https://avatars.githubusercontent.com/u/58846658?v=4&size=64)](https://github.com/JiuRanYa)[![](https://avatars.githubusercontent.com/u/109908413?v=4&size=64)](https://github.com/sleepyShen1989)[![](https://avatars.githubusercontent.com/u/43257608?v=4&size=64)](https://github.com/Liao-js)[![](https://avatars.githubusercontent.com/u/59350883?v=4&size=64)](https://github.com/init-qy)[![](https://avatars.githubusercontent.com/u/27277138?v=4&size=64)](https://github.com/wuzhidexiaoming)[![](https://avatars.githubusercontent.com/u/1532716?v=4&size=64)](https://github.com/godxiaoji)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/178066799?v=4&size=64)](https://github.com/Yeuvoir)[![](https://avatars.githubusercontent.com/u/37976544?v=4&size=64)](https://github.com/ALypovskyi)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/41771224?v=4&size=64)](https://github.com/littlezo)[![](https://avatars.githubusercontent.com/u/201188047?v=4&size=64)](https://github.com/YXY-cell)[![](https://avatars.githubusercontent.com/u/27413795?v=4&size=64)](https://github.com/SpanManX)[![](https://avatars.githubusercontent.com/u/19580923?v=4&size=64)](https://github.com/wcttmf)[![](https://avatars.githubusercontent.com/u/42372070?v=4&size=64)](https://github.com/Map1en)[![](https://avatars.githubusercontent.com/u/33254923?v=4&size=64)](https://github.com/yicheny)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/127940123?v=4&size=64)](https://github.com/baozjj)[![](https://avatars.githubusercontent.com/u/198031266?v=4&size=64)](https://github.com/noki-maker)[![](https://avatars.githubusercontent.com/u/40554198?v=4&size=64)](https://github.com/WangYJEE)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/22659150?v=4&size=64)](https://github.com/ntnyq)[![](https://avatars.githubusercontent.com/u/57179957?v=4&size=64)](https://github.com/yeonjulee1005)[![](https://avatars.githubusercontent.com/u/10398024?v=4&size=64)](https://github.com/humorHan)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/57524062?v=4&size=64)](https://github.com/Ther-su)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/81673017?v=4&size=64)](https://github.com/RSS1102)[![](https://avatars.githubusercontent.com/u/2849255?v=4&size=64)](https://github.com/mg5566)[![](https://avatars.githubusercontent.com/u/8591261?v=4&size=64)](https://github.com/zeyongTsai)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/36811055?v=4&size=64)](https://github.com/iDestin)[![](https://avatars.githubusercontent.com/u/7065327?v=4&size=64)](https://github.com/LiuwqGit)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/65441198?v=4&size=64)](https://github.com/tyj-321)[![](https://avatars.githubusercontent.com/u/48283236?v=4&size=64)](https://github.com/raphaelbernhart)[![](https://avatars.githubusercontent.com/u/67454874?v=4&size=64)](https://github.com/nigiwen)[![](https://avatars.githubusercontent.com/u/79386745?v=4&size=64)](https://github.com/kamesan012)[![](https://avatars.githubusercontent.com/u/101374143?v=4&size=64)](https://github.com/sseinHu)[![](https://avatars.githubusercontent.com/u/18509404?v=4&size=64)](https://github.com/inottn)[![](https://avatars.githubusercontent.com/u/71313168?v=4&size=64)](https://github.com/cc-hearts)[![](https://avatars.githubusercontent.com/u/101238421?v=4&size=64)](https://github.com/acyza)[![](https://avatars.githubusercontent.com/u/31885971?v=4&size=64)](https://github.com/wonderl17)[![](https://avatars.githubusercontent.com/u/13410410?v=4&size=64)](https://github.com/jaa134)[![](https://avatars.githubusercontent.com/u/5701072?v=4&size=64)](https://github.com/Naeemo)[![](https://avatars.githubusercontent.com/u/4075314?v=4&size=64)](https://github.com/Giwayume)[![](https://avatars.githubusercontent.com/u/75945382?v=4&size=64)](https://github.com/yuanxin518)[![](https://avatars.githubusercontent.com/u/38248854?v=4&size=64)](https://github.com/Yueyanc)[![](https://avatars.githubusercontent.com/u/65154?v=4&size=64)](https://github.com/exherb)[![](https://avatars.githubusercontent.com/u/5389932?v=4&size=64)](https://github.com/muuyao)[![](https://avatars.githubusercontent.com/u/88016243?v=4&size=64)](https://github.com/wzrove)[![](https://avatars.githubusercontent.com/u/48196760?v=4&size=64)](https://github.com/eriksyuan)[![](https://avatars.githubusercontent.com/u/8401855?v=4&size=64)](https://github.com/JacBian)[![](https://avatars.githubusercontent.com/u/39672197?v=4&size=64)](https://github.com/bchen1029)

[Rate 评分](https://element-plus.org/zh-CN/component/rate)

[Virtualized Select 虚拟化选择器](https://element-plus.org/zh-CN/component/select-v2)




---
## [form/select-v2] Virtualized Select 虚拟化选择器
> 官方文档: https://element-plus.org/zh-CN/component/select-v2.html

---

# Virtualized Select 虚拟化选择器 [​](#virtualized-select-虚拟化选择器)

更新日志待解决

8

TIP

这个组件目前在测试当中，如果在使用中发现任何漏洞和问题，请在 [GitHub](https://github.com/element-plus/element-plus/issues) 中提交 issue 以便我们进行处理。

## 背景 [​](#背景)

在某些使用情况下，单个选择器可能最终加载数万行数据。 将这么多的数据渲染至 DOM 中可能会给浏览器带来负担，从而造成性能问题。 为了更好的用户和开发者体验，我们决定添加此组件。

## 基础用法 [​](#基础用法)

适用广泛的基础选择器

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIHNlbGVjdFwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5pdGlhbHMgPSBbJ2EnLCAnYicsICdjJywgJ2QnLCAnZScsICdmJywgJ2cnLCAnaCcsICdpJywgJ2onXVxuXG5jb25zdCB2YWx1ZSA9IHJlZigpXG5jb25zdCBvcHRpb25zID0gQXJyYXkuZnJvbSh7IGxlbmd0aDogMTAwMCB9KS5tYXAoKF8sIGlkeCkgPT4gKHtcbiAgdmFsdWU6IGBPcHRpb24gJHtpZHggKyAxfWAsXG4gIGxhYmVsOiBgJHtpbml0aWFsc1tpZHggJSAxMF19JHtpZHh9YCxcbn0pKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/basic-usage.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value"
    :options="options"
    placeholder="Please select"
    style="width: 240px"
  />
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value = ref()
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: `Option ${idx + 1}`,
  label: `${initials[idx % 10]}${idx}`,
}))
</script>
```

隐藏源代码

## 多选 [​](#多选)

最基础的多选选择器

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIHNlbGVjdFwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgIG11bHRpcGxlXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBpbml0aWFscyA9IFsnYScsICdiJywgJ2MnLCAnZCcsICdlJywgJ2YnLCAnZycsICdoJywgJ2knLCAnaiddXG5cbmNvbnN0IHZhbHVlID0gcmVmKFtdKVxuY29uc3Qgb3B0aW9ucyA9IHJlZihcbiAgQXJyYXkuZnJvbSh7IGxlbmd0aDogMTAwMCB9KS5tYXAoKF8sIGlkeCkgPT4gKHtcbiAgICB2YWx1ZTogYE9wdGlvbiAke2lkeCArIDF9YCxcbiAgICBsYWJlbDogYCR7aW5pdGlhbHNbaWR4ICUgMTBdfSR7aWR4fWAsXG4gIH0pKVxuKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/multiple.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value"
    :options="options"
    placeholder="Please select"
    style="width: 240px"
    multiple
  />
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value = ref([])
const options = ref(
  Array.from({ length: 1000 }).map((_, idx) => ({
    value: `Option ${idx + 1}`,
    label: `${initials[idx % 10]}${idx}`,
  }))
)
</script>
```

隐藏源代码

## 尺寸 [​](#尺寸)

使用 `size` 属性改变选择器大小。 除了默认大小外，还有另外两个选项： `large`, `small`。

Please select

Please select

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTQgaXRlbXMtY2VudGVyXCI+XG4gICAgPGVsLXNlbGVjdC12MlxuICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgICAgc2l6ZT1cImxhcmdlXCJcbiAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICAvPlxuICAgIDxlbC1zZWxlY3QtdjJcbiAgICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2Ugc2VsZWN0XCJcbiAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICAvPlxuICAgIDxlbC1zZWxlY3QtdjJcbiAgICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2Ugc2VsZWN0XCJcbiAgICAgIHNpemU9XCJzbWFsbFwiXG4gICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBpbml0aWFscyA9IFsnYScsICdiJywgJ2MnLCAnZCcsICdlJywgJ2YnLCAnZycsICdoJywgJ2knLCAnaiddXG5cbmNvbnN0IHZhbHVlID0gcmVmKClcbmNvbnN0IG9wdGlvbnMgPSBBcnJheS5mcm9tKHsgbGVuZ3RoOiAxMDAwIH0pLm1hcCgoXywgaWR4KSA9PiAoe1xuICB2YWx1ZTogYE9wdGlvbiAke2lkeCArIDF9YCxcbiAgbGFiZWw6IGAke2luaXRpYWxzW2lkeCAlIDEwXX0ke2lkeH1gLFxufSkpXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5leGFtcGxlLXNob3djYXNlIC5lbC1zZWxlY3QtdjIge1xuICBtYXJnaW4tcmlnaHQ6IDIwcHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/size.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-4 items-center">
    <el-select-v2
      v-model="value"
      :options="options"
      placeholder="Please select"
      size="large"
      style="width: 240px"
    />
    <el-select-v2
      v-model="value"
      :options="options"
      placeholder="Please select"
      style="width: 240px"
    />
    <el-select-v2
      v-model="value"
      :options="options"
      placeholder="Please select"
      size="small"
      style="width: 240px"
    />
  </div>
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value = ref()
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: `Option ${idx + 1}`,
  label: `${initials[idx % 10]}${idx}`,
}))
</script>

<style scoped>
.example-showcase .el-select-v2 {
  margin-right: 20px;
}
</style>
```

隐藏源代码

## 隐藏多余标签的多选 [​](#隐藏多余标签的多选)

默认情况下选中值会以 Tag 的形式展现，你也可以设置`collapse-tags`属性将它们合并为一段文字。 您可以使用 `collapse-tags-tooltip` 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。

use collapse-tags

Please select

use collapse-tags-tooltip

Please select

use max-collapse-tags

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+dXNlIGNvbGxhcHNlLXRhZ3M8L3A+XG4gICAgPGVsLXNlbGVjdC12MlxuICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgbXVsdGlwbGVcbiAgICAgIGNvbGxhcHNlLXRhZ3NcbiAgICAvPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cIm0tNFwiPlxuICAgIDxwPnVzZSBjb2xsYXBzZS10YWdzLXRvb2x0aXA8L3A+XG4gICAgPGVsLXNlbGVjdC12MlxuICAgICAgdi1tb2RlbD1cInZhbHVlMlwiXG4gICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2Ugc2VsZWN0XCJcbiAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICAgIG11bHRpcGxlXG4gICAgICBjb2xsYXBzZS10YWdzXG4gICAgICBjb2xsYXBzZS10YWdzLXRvb2x0aXBcbiAgICAvPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cIm0tNFwiPlxuICAgIDxwPnVzZSBtYXgtY29sbGFwc2UtdGFnczwvcD5cbiAgICA8ZWwtc2VsZWN0LXYyXG4gICAgICB2LW1vZGVsPVwidmFsdWUzXCJcbiAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgbXVsdGlwbGVcbiAgICAgIGNvbGxhcHNlLXRhZ3NcbiAgICAgIGNvbGxhcHNlLXRhZ3MtdG9vbHRpcFxuICAgICAgOm1heC1jb2xsYXBzZS10YWdzPVwiM1wiXG4gICAgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBpbml0aWFscyA9IFsnYScsICdiJywgJ2MnLCAnZCcsICdlJywgJ2YnLCAnZycsICdoJywgJ2knLCAnaiddXG5cbmNvbnN0IHZhbHVlID0gcmVmKFtdKVxuY29uc3QgdmFsdWUyID0gcmVmKFtdKVxuY29uc3QgdmFsdWUzID0gcmVmKFtdKVxuY29uc3Qgb3B0aW9ucyA9IEFycmF5LmZyb20oeyBsZW5ndGg6IDEwMDAgfSkubWFwKChfLCBpZHgpID0+ICh7XG4gIHZhbHVlOiBgT3B0aW9uICR7aWR4ICsgMX1gLFxuICBsYWJlbDogYCR7aW5pdGlhbHNbaWR4ICUgMTBdfSR7aWR4fWAsXG59KSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/hide-extra-tags.vue)_

vue

```
<template>
  <div class="m-4">
    <p>use collapse-tags</p>
    <el-select-v2
      v-model="value"
      :options="options"
      placeholder="Please select"
      style="width: 240px"
      multiple
      collapse-tags
    />
  </div>
  <div class="m-4">
    <p>use collapse-tags-tooltip</p>
    <el-select-v2
      v-model="value2"
      :options="options"
      placeholder="Please select"
      style="width: 240px"
      multiple
      collapse-tags
      collapse-tags-tooltip
    />
  </div>
  <div class="m-4">
    <p>use max-collapse-tags</p>
    <el-select-v2
      v-model="value3"
      :options="options"
      placeholder="Please select"
      style="width: 240px"
      multiple
      collapse-tags
      collapse-tags-tooltip
      :max-collapse-tags="3"
    />
  </div>
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value = ref([])
const value2 = ref([])
const value3 = ref([])
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: `Option ${idx + 1}`,
  label: `${initials[idx % 10]}${idx}`,
}))
</script>
```

隐藏源代码

## 可过滤的多选 [​](#可过滤的多选)

当选项太多时，你可以使用 `filterable` 选项来启用过滤功能来找到所需的选项。

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICBmaWx0ZXJhYmxlXG4gICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICBtdWx0aXBsZVxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5pdGlhbHMgPSBbJ2EnLCAnYicsICdjJywgJ2QnLCAnZScsICdmJywgJ2cnLCAnaCcsICdpJywgJ2onXVxuXG5jb25zdCB2YWx1ZSA9IHJlZihbXSlcbmNvbnN0IG9wdGlvbnMgPSBBcnJheS5mcm9tKHsgbGVuZ3RoOiAxMDAwIH0pLm1hcCgoXywgaWR4KSA9PiAoe1xuICB2YWx1ZTogYE9wdGlvbiR7aWR4ICsgMX1gLFxuICBsYWJlbDogYCR7aW5pdGlhbHNbaWR4ICUgMTBdfSR7aWR4fWAsXG59KSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/filterable.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value"
    filterable
    :options="options"
    placeholder="Please select"
    style="width: 240px"
    multiple
  />
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value = ref([])
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: `Option${idx + 1}`,
  label: `${initials[idx % 10]}${idx}`,
}))
</script>
```

隐藏源代码

## 禁用选择器本身或选项 [​](#禁用选择器本身或选项)

您可以选择禁用 Select 或者 Select 中的某个选项。

Please select

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICBmaWx0ZXJhYmxlXG4gICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4OyBtYXJnaW4tcmlnaHQ6IDE2cHg7IHZlcnRpY2FsLWFsaWduOiBtaWRkbGVcIlxuICAgIG11bHRpcGxlXG4gIC8+XG4gIDxlbC1zZWxlY3QtdjJcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIGRpc2FibGVkXG4gICAgZmlsdGVyYWJsZVxuICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgcGxhY2Vob2xkZXI9XCJQbGVhc2Ugc2VsZWN0XCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweDsgdmVydGljYWwtYWxpZ246IG1pZGRsZVwiXG4gICAgbXVsdGlwbGVcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGluaXRpYWxzID0gWydhJywgJ2InLCAnYycsICdkJywgJ2UnLCAnZicsICdnJywgJ2gnLCAnaScsICdqJ11cblxuY29uc3QgdmFsdWUgPSByZWYoW10pXG5jb25zdCBvcHRpb25zID0gQXJyYXkuZnJvbSh7IGxlbmd0aDogMTAwMCB9KS5tYXAoKF8sIGlkeCkgPT4gKHtcbiAgdmFsdWU6IGBPcHRpb24ke2lkeCArIDF9YCxcbiAgbGFiZWw6IGAke2luaXRpYWxzW2lkeCAlIDEwXX0ke2lkeH1gLFxuICBkaXNhYmxlZDogaWR4ICUgMTAgPT09IDAsXG59KSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/disabled.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value"
    filterable
    :options="options"
    placeholder="Please select"
    style="width: 240px; margin-right: 16px; vertical-align: middle"
    multiple
  />
  <el-select-v2
    v-model="value"
    disabled
    filterable
    :options="options"
    placeholder="Please select"
    style="width: 240px; vertical-align: middle"
    multiple
  />
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value = ref([])
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: `Option${idx + 1}`,
  label: `${initials[idx % 10]}${idx}`,
  disabled: idx % 10 === 0,
}))
</script>
```

隐藏源代码

## 给选项进行分组 [​](#给选项进行分组)

只要数据格式满足特定要求，我们就可以按照自己的意愿为选项进行分组。

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICBmaWx0ZXJhYmxlXG4gICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICBtdWx0aXBsZVxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5pdGlhbHMgPSBbJ2EnLCAnYicsICdjJywgJ2QnLCAnZScsICdmJywgJ2cnLCAnaCcsICdpJywgJ2onXVxuXG5jb25zdCB2YWx1ZSA9IHJlZihbXSlcbmNvbnN0IG9wdGlvbnMgPSBBcnJheS5mcm9tKHsgbGVuZ3RoOiAxMCB9KS5tYXAoKF8sIGlkeCkgPT4ge1xuICBjb25zdCBsYWJlbCA9IGlkeCArIDFcbiAgcmV0dXJuIHtcbiAgICB2YWx1ZTogYEdyb3VwICR7bGFiZWx9YCxcbiAgICBsYWJlbDogYEdyb3VwICR7bGFiZWx9YCxcbiAgICBvcHRpb25zOiBBcnJheS5mcm9tKHsgbGVuZ3RoOiAxMCB9KS5tYXAoKF8sIGlkeCkgPT4gKHtcbiAgICAgIHZhbHVlOiBgT3B0aW9uICR7aWR4ICsgMSArIDEwICogbGFiZWx9YCxcbiAgICAgIGxhYmVsOiBgJHtpbml0aWFsc1tpZHggJSAxMF19JHtpZHggKyAxICsgMTAgKiBsYWJlbH1gLFxuICAgIH0pKSxcbiAgfVxufSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/grouping.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value"
    filterable
    :options="options"
    placeholder="Please select"
    style="width: 240px"
    multiple
  />
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value = ref([])
const options = Array.from({ length: 10 }).map((_, idx) => {
  const label = idx + 1
  return {
    value: `Group ${label}`,
    label: `Group ${label}`,
    options: Array.from({ length: 10 }).map((_, idx) => ({
      value: `Option ${idx + 1 + 10 * label}`,
      label: `${initials[idx % 10]}${idx + 1 + 10 * label}`,
    })),
  }
})
</script>
```

隐藏源代码

## 一键清除 [​](#一键清除)

我们可以同时清除所有选定的选项。此设定也适用于单选。

Please select

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlMVwiXG4gICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4OyBtYXJnaW4tcmlnaHQ6IDE2cHg7IHZlcnRpY2FsLWFsaWduOiBtaWRkbGVcIlxuICAgIG11bHRpcGxlXG4gICAgY2xlYXJhYmxlXG4gIC8+XG4gIDxlbC1zZWxlY3QtdjJcbiAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIHNlbGVjdFwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHg7IHZlcnRpY2FsLWFsaWduOiBtaWRkbGVcIlxuICAgIGNsZWFyYWJsZVxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5pdGlhbHMgPSBbJ2EnLCAnYicsICdjJywgJ2QnLCAnZScsICdmJywgJ2cnLCAnaCcsICdpJywgJ2onXVxuXG5jb25zdCB2YWx1ZTEgPSByZWYoW10pXG5jb25zdCB2YWx1ZTIgPSByZWYoKVxuY29uc3Qgb3B0aW9ucyA9IEFycmF5LmZyb20oeyBsZW5ndGg6IDEwMDAgfSkubWFwKChfLCBpZHgpID0+ICh7XG4gIHZhbHVlOiBgT3B0aW9uICR7aWR4ICsgMX1gLFxuICBsYWJlbDogYCR7aW5pdGlhbHNbaWR4ICUgMTBdfSR7aWR4fWAsXG59KSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/clearable.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value1"
    :options="options"
    placeholder="Please select"
    style="width: 240px; margin-right: 16px; vertical-align: middle"
    multiple
    clearable
  />
  <el-select-v2
    v-model="value2"
    :options="options"
    placeholder="Please select"
    style="width: 240px; vertical-align: middle"
    clearable
  />
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value1 = ref([])
const value2 = ref()
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: `Option ${idx + 1}`,
  label: `${initials[idx % 10]}${idx}`,
}))
</script>
```

隐藏源代码

## 自定义选项的渲染模板 [​](#自定义选项的渲染模板)

我们也可以通过自定义模板来渲染自己想要的选项内容。

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICBmaWx0ZXJhYmxlXG4gICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICBtdWx0aXBsZVxuICA+XG4gICAgPHRlbXBsYXRlICNkZWZhdWx0PVwieyBpdGVtIH1cIj5cbiAgICAgIDxzcGFuIHN0eWxlPVwibWFyZ2luLXJpZ2h0OiA4cHhcIj57eyBpdGVtLmxhYmVsIH19PC9zcGFuPlxuICAgICAgPHNwYW4gc3R5bGU9XCJjb2xvcjogdmFyKC0tZWwtdGV4dC1jb2xvci1zZWNvbmRhcnkpOyBmb250LXNpemU6IDEzcHhcIj5cbiAgICAgICAge3sgaXRlbS52YWx1ZSB9fVxuICAgICAgPC9zcGFuPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtc2VsZWN0LXYyPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5pdGlhbHMgPSBbJ2EnLCAnYicsICdjJywgJ2QnLCAnZScsICdmJywgJ2cnLCAnaCcsICdpJywgJ2onXVxuXG5jb25zdCB2YWx1ZSA9IHJlZihbXSlcbmNvbnN0IG9wdGlvbnMgPSBBcnJheS5mcm9tKHsgbGVuZ3RoOiAxMDAwIH0pLm1hcCgoXywgaWR4KSA9PiAoe1xuICB2YWx1ZTogYE9wdGlvbiAke2lkeCArIDF9YCxcbiAgbGFiZWw6IGAke2luaXRpYWxzW2lkeCAlIDEwXX0ke2lkeH1gLFxufSkpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/customized-option.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value"
    filterable
    :options="options"
    placeholder="Please select"
    style="width: 240px"
    multiple
  >
    <template #default="{ item }">
      <span style="margin-right: 8px">{{ item.label }}</span>
      <span style="color: var(--el-text-color-secondary); font-size: 13px">
        {{ item.value }}
      </span>
    </template>
  </el-select-v2>
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value = ref([])
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: `Option ${idx + 1}`,
  label: `${initials[idx % 10]}${idx}`,
}))
</script>
```

隐藏源代码

## 自定义下拉菜单的头部 2.5.2 [​](#自定义下拉菜单的头部)

您可以自定义下拉菜单的头部。

使用slot 自定义内容

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgIG11bHRpcGxlXG4gICAgY2xlYXJhYmxlXG4gICAgY29sbGFwc2UtdGFnc1xuICAgIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCJcbiAgICBwb3BwZXItY2xhc3M9XCJjdXN0b20taGVhZGVyXCJcbiAgICA6bWF4LWNvbGxhcHNlLXRhZ3M9XCIxXCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gID5cbiAgICA8dGVtcGxhdGUgI2hlYWRlcj5cbiAgICAgIDxlbC1jaGVja2JveFxuICAgICAgICB2LW1vZGVsPVwiY2hlY2tBbGxcIlxuICAgICAgICA6aW5kZXRlcm1pbmF0ZT1cImluZGV0ZXJtaW5hdGVcIlxuICAgICAgICBAY2hhbmdlPVwiaGFuZGxlQ2hlY2tBbGxcIlxuICAgICAgPlxuICAgICAgICBBbGxcbiAgICAgIDwvZWwtY2hlY2tib3g+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1zZWxlY3QtdjI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmLCB3YXRjaCB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBDaGVja2JveFZhbHVlVHlwZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgaW5pdGlhbHMgPSBbJ2EnLCAnYicsICdjJywgJ2QnLCAnZScsICdmJywgJ2cnLCAnaCcsICdpJywgJ2onXVxuY29uc3QgY2hlY2tBbGwgPSByZWYoZmFsc2UpXG5jb25zdCBpbmRldGVybWluYXRlID0gcmVmKGZhbHNlKVxuY29uc3QgdmFsdWUgPSByZWY8Q2hlY2tib3hWYWx1ZVR5cGVbXT4oW10pXG5jb25zdCBvcHRpb25zID0gcmVmKFxuICBBcnJheS5mcm9tKHsgbGVuZ3RoOiAxMDAwIH0pLm1hcCgoXywgaWR4KSA9PiAoe1xuICAgIHZhbHVlOiBgT3B0aW9uICR7aWR4ICsgMX1gLFxuICAgIGxhYmVsOiBgJHtpbml0aWFsc1tpZHggJSAxMF19JHtpZHh9YCxcbiAgfSkpXG4pXG5cbndhdGNoKHZhbHVlLCAodmFsKSA9PiB7XG4gIGlmICh2YWwubGVuZ3RoID09PSAwKSB7XG4gICAgY2hlY2tBbGwudmFsdWUgPSBmYWxzZVxuICAgIGluZGV0ZXJtaW5hdGUudmFsdWUgPSBmYWxzZVxuICB9IGVsc2UgaWYgKHZhbC5sZW5ndGggPT09IG9wdGlvbnMudmFsdWUubGVuZ3RoKSB7XG4gICAgY2hlY2tBbGwudmFsdWUgPSB0cnVlXG4gICAgaW5kZXRlcm1pbmF0ZS52YWx1ZSA9IGZhbHNlXG4gIH0gZWxzZSB7XG4gICAgaW5kZXRlcm1pbmF0ZS52YWx1ZSA9IHRydWVcbiAgfVxufSlcblxuY29uc3QgaGFuZGxlQ2hlY2tBbGwgPSAodmFsOiBDaGVja2JveFZhbHVlVHlwZSkgPT4ge1xuICBpbmRldGVybWluYXRlLnZhbHVlID0gZmFsc2VcbiAgaWYgKHZhbCkge1xuICAgIHZhbHVlLnZhbHVlID0gb3B0aW9ucy52YWx1ZS5tYXAoKF8pID0+IF8udmFsdWUpXG4gIH0gZWxzZSB7XG4gICAgdmFsdWUudmFsdWUgPSBbXVxuICB9XG59XG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLmN1c3RvbS1oZWFkZXIge1xuICAuZWwtY2hlY2tib3gge1xuICAgIGRpc3BsYXk6IGZsZXg7XG4gICAgaGVpZ2h0OiB1bnNldDtcbiAgfVxufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/custom-header.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value"
    :options="options"
    multiple
    clearable
    collapse-tags
    placeholder="Select"
    popper-class="custom-header"
    :max-collapse-tags="1"
    style="width: 240px"
  >
    <template #header>
      <el-checkbox
        v-model="checkAll"
        :indeterminate="indeterminate"
        @change="handleCheckAll"
      >
        All
      </el-checkbox>
    </template>
  </el-select-v2>
</template>

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

import type { CheckboxValueType } from 'element-plus'

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']
const checkAll = ref(false)
const indeterminate = ref(false)
const value = ref<CheckboxValueType[]>([])
const options = ref(
  Array.from({ length: 1000 }).map((_, idx) => ({
    value: `Option ${idx + 1}`,
    label: `${initials[idx % 10]}${idx}`,
  }))
)

watch(value, (val) => {
  if (val.length === 0) {
    checkAll.value = false
    indeterminate.value = false
  } else if (val.length === options.value.length) {
    checkAll.value = true
    indeterminate.value = false
  } else {
    indeterminate.value = true
  }
})

const handleCheckAll = (val: CheckboxValueType) => {
  indeterminate.value = false
  if (val) {
    value.value = options.value.map((_) => _.value)
  } else {
    value.value = []
  }
}
</script>

<style>
.custom-header {
  .el-checkbox {
    display: flex;
    height: unset;
  }
}
</style>
```

隐藏源代码

## 自定义下拉菜单的底部 2.5.2 [​](#自定义下拉菜单的底部)

您可以自定义下拉菜单的底部。

使用slot 自定义内容

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgcmVmPVwic2VsZWN0XCJcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgcGxhY2Vob2xkZXI9XCJTZWxlY3RcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgPlxuICAgIDx0ZW1wbGF0ZSAjZm9vdGVyPlxuICAgICAgPGVsLWJ1dHRvbiB2LWlmPVwiIWlzQWRkaW5nXCIgdGV4dCBiZyBzaXplPVwic21hbGxcIiBAY2xpY2s9XCJvbkFkZE9wdGlvblwiPlxuICAgICAgICBBZGQgYW4gb3B0aW9uXG4gICAgICA8L2VsLWJ1dHRvbj5cbiAgICAgIDxkaXYgdi1lbHNlIGNsYXNzPVwic2VsZWN0LWZvb3RlclwiPlxuICAgICAgICA8ZWwtaW5wdXRcbiAgICAgICAgICB2LW1vZGVsPVwib3B0aW9uTmFtZVwiXG4gICAgICAgICAgY2xhc3M9XCJvcHRpb24taW5wdXRcIlxuICAgICAgICAgIHBsYWNlaG9sZGVyPVwiaW5wdXQgb3B0aW9uIG5hbWVcIlxuICAgICAgICAgIHNpemU9XCJzbWFsbFwiXG4gICAgICAgIC8+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiIHNpemU9XCJzbWFsbFwiIEBjbGljaz1cIm9uQ29uZmlybVwiPlxuICAgICAgICAgICAgY29uZmlybVxuICAgICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgICAgIDxlbC1idXR0b24gc2l6ZT1cInNtYWxsXCIgQGNsaWNrPVwiY2xlYXJcIj5jYW5jZWw8L2VsLWJ1dHRvbj5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2Rpdj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLXNlbGVjdC12Mj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBuZXh0VGljaywgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IENoZWNrYm94VmFsdWVUeXBlLCBTZWxlY3RWMkluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBpbml0aWFscyA9IFsnYScsICdiJywgJ2MnLCAnZCcsICdlJywgJ2YnLCAnZycsICdoJywgJ2knLCAnaiddXG5jb25zdCBzZWxlY3QgPSByZWY8U2VsZWN0VjJJbnN0YW5jZT4oKVxuY29uc3QgaXNBZGRpbmcgPSByZWYoZmFsc2UpXG5jb25zdCB2YWx1ZSA9IHJlZjxDaGVja2JveFZhbHVlVHlwZVtdPihbXSlcbmNvbnN0IG9wdGlvbk5hbWUgPSByZWYoJycpXG5jb25zdCBvcHRpb25zID0gcmVmKFxuICBBcnJheS5mcm9tKHsgbGVuZ3RoOiAxMDAwIH0pLm1hcCgoXywgaWR4KSA9PiAoe1xuICAgIHZhbHVlOiBgT3B0aW9uICR7aWR4ICsgMX1gLFxuICAgIGxhYmVsOiBgJHtpbml0aWFsc1tpZHggJSAxMF19JHtpZHh9YCxcbiAgfSkpXG4pXG5cbmNvbnN0IG9uQWRkT3B0aW9uID0gKCkgPT4ge1xuICBpc0FkZGluZy52YWx1ZSA9IHRydWVcbn1cblxuY29uc3Qgb25Db25maXJtID0gKCkgPT4ge1xuICBpZiAob3B0aW9uTmFtZS52YWx1ZSkge1xuICAgIG9wdGlvbnMudmFsdWUucHVzaCh7XG4gICAgICBsYWJlbDogb3B0aW9uTmFtZS52YWx1ZSxcbiAgICAgIHZhbHVlOiBvcHRpb25OYW1lLnZhbHVlLFxuICAgIH0pXG4gICAgY2xlYXIoKVxuICAgIG5leHRUaWNrKCgpID0+IHtcbiAgICAgIHNlbGVjdC52YWx1ZT8uc2Nyb2xsVG8ob3B0aW9ucy52YWx1ZS5sZW5ndGggLSAxKVxuICAgIH0pXG4gIH1cbn1cblxuY29uc3QgY2xlYXIgPSAoKSA9PiB7XG4gIG9wdGlvbk5hbWUudmFsdWUgPSAnJ1xuICBpc0FkZGluZy52YWx1ZSA9IGZhbHNlXG59XG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLnNlbGVjdC1mb290ZXIge1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LWRpcmVjdGlvbjogY29sdW1uO1xuXG4gIC5vcHRpb24taW5wdXQge1xuICAgIHdpZHRoOiAxMDAlO1xuICAgIG1hcmdpbi1ib3R0b206IDhweDtcbiAgfVxufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/custom-footer.vue)_

vue

```
<template>
  <el-select-v2
    ref="select"
    v-model="value"
    :options="options"
    placeholder="Select"
    style="width: 240px"
  >
    <template #footer>
      <el-button v-if="!isAdding" text bg size="small" @click="onAddOption">
        Add an option
      </el-button>
      <div v-else class="select-footer">
        <el-input
          v-model="optionName"
          class="option-input"
          placeholder="input option name"
          size="small"
        />
        <div>
          <el-button type="primary" size="small" @click="onConfirm">
            confirm
          </el-button>
          <el-button size="small" @click="clear">cancel</el-button>
        </div>
      </div>
    </template>
  </el-select-v2>
</template>

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

import type { CheckboxValueType, SelectV2Instance } from 'element-plus'

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']
const select = ref<SelectV2Instance>()
const isAdding = ref(false)
const value = ref<CheckboxValueType[]>([])
const optionName = ref('')
const options = ref(
  Array.from({ length: 1000 }).map((_, idx) => ({
    value: `Option ${idx + 1}`,
    label: `${initials[idx % 10]}${idx}`,
  }))
)

const onAddOption = () => {
  isAdding.value = true
}

const onConfirm = () => {
  if (optionName.value) {
    options.value.push({
      label: optionName.value,
      value: optionName.value,
    })
    clear()
    nextTick(() => {
      select.value?.scrollTo(options.value.length - 1)
    })
  }
}

const clear = () => {
  optionName.value = ''
  isAdding.value = false
}
</script>

<style>
.select-footer {
  display: flex;
  flex-direction: column;

  .option-input {
    width: 100%;
    margin-bottom: 8px;
  }
}
</style>
```

隐藏源代码

## 创建临时选项 [​](#创建临时选项)

创建并选中未包含在初始选项中的条目。

通过使用 `allow-create` 属性，用户可以通过输入框创建新项目。 为了使 `allow-create` 正常工作， `filterable` 的值必须为 `true`。 本例还使用了 `default-first-option` 属性， 在该属性为 `true` 的情况下，按下回车就可以选中当前选项列表中的第一个选项，无需使用鼠标或键盘方向键进行定位。

TIP

最好在使用 `allow-create` 属性的同时设置 `:reserve-keyword="false"`。

Please select

Please select

set reserve-keyword false

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwiZmxleDogYXV0b1wiPlxuICAgIDxkaXY+XG4gICAgICA8ZWwtc2VsZWN0LXYyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZTFcIlxuICAgICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgICAgICBzdHlsZT1cIndpZHRoOiAyNDBweDsgbWFyZ2luLXJpZ2h0OiAxNnB4OyB2ZXJ0aWNhbC1hbGlnbjogbWlkZGxlXCJcbiAgICAgICAgYWxsb3ctY3JlYXRlXG4gICAgICAgIGRlZmF1bHQtZmlyc3Qtb3B0aW9uXG4gICAgICAgIGZpbHRlcmFibGVcbiAgICAgICAgbXVsdGlwbGVcbiAgICAgICAgY2xlYXJhYmxlXG4gICAgICAvPlxuICAgICAgPGVsLXNlbGVjdC12MlxuICAgICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2Ugc2VsZWN0XCJcbiAgICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHg7IHZlcnRpY2FsLWFsaWduOiBtaWRkbGVcIlxuICAgICAgICBhbGxvdy1jcmVhdGVcbiAgICAgICAgZGVmYXVsdC1maXJzdC1vcHRpb25cbiAgICAgICAgZmlsdGVyYWJsZVxuICAgICAgICBjbGVhcmFibGVcbiAgICAgIC8+XG4gICAgPC9kaXY+XG4gICAgPGRpdj5cbiAgICAgIDxwIHN0eWxlPVwibWFyZ2luLXRvcDogMjBweDsgbWFyZ2luLWJvdHRvbTogOHB4XCI+XG4gICAgICAgIHNldCByZXNlcnZlLWtleXdvcmQgZmFsc2VcbiAgICAgIDwvcD5cbiAgICAgIDxlbC1zZWxlY3QtdjJcbiAgICAgICAgdi1tb2RlbD1cInZhbHVlM1wiXG4gICAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIHNlbGVjdFwiXG4gICAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4OyBtYXJnaW4tcmlnaHQ6IDE2cHg7IHZlcnRpY2FsLWFsaWduOiBtaWRkbGVcIlxuICAgICAgICBhbGxvdy1jcmVhdGVcbiAgICAgICAgZGVmYXVsdC1maXJzdC1vcHRpb25cbiAgICAgICAgZmlsdGVyYWJsZVxuICAgICAgICBtdWx0aXBsZVxuICAgICAgICBjbGVhcmFibGVcbiAgICAgICAgOnJlc2VydmUta2V5d29yZD1cImZhbHNlXCJcbiAgICAgIC8+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5pdGlhbHMgPSBbJ2EnLCAnYicsICdjJywgJ2QnLCAnZScsICdmJywgJ2cnLCAnaCcsICdpJywgJ2onXVxuXG5jb25zdCB2YWx1ZTEgPSByZWYoW10pXG5jb25zdCB2YWx1ZTIgPSByZWYoKVxuY29uc3QgdmFsdWUzID0gcmVmKFtdKVxuY29uc3Qgb3B0aW9ucyA9IEFycmF5LmZyb20oeyBsZW5ndGg6IDEwMDAgfSkubWFwKChfLCBpZHgpID0+ICh7XG4gIHZhbHVlOiBgT3B0aW9uICR7aWR4ICsgMX1gLFxuICBsYWJlbDogYCR7aW5pdGlhbHNbaWR4ICUgMTBdfSR7aWR4fWAsXG59KSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/allow-create.vue)_

vue

```
<template>
  <div style="flex: auto">
    <div>
      <el-select-v2
        v-model="value1"
        :options="options"
        placeholder="Please select"
        style="width: 240px; margin-right: 16px; vertical-align: middle"
        allow-create
        default-first-option
        filterable
        multiple
        clearable
      />
      <el-select-v2
        v-model="value2"
        :options="options"
        placeholder="Please select"
        style="width: 240px; vertical-align: middle"
        allow-create
        default-first-option
        filterable
        clearable
      />
    </div>
    <div>
      <p style="margin-top: 20px; margin-bottom: 8px">
        set reserve-keyword false
      </p>
      <el-select-v2
        v-model="value3"
        :options="options"
        placeholder="Please select"
        style="width: 240px; margin-right: 16px; vertical-align: middle"
        allow-create
        default-first-option
        filterable
        multiple
        clearable
        :reserve-keyword="false"
      />
    </div>
  </div>
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value1 = ref([])
const value2 = ref()
const value3 = ref([])
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: `Option ${idx + 1}`,
  label: `${initials[idx % 10]}${idx}`,
}))
</script>
```

隐藏源代码

## 远程搜索 [​](#远程搜索)

输入关键字以从远程服务器中查找数据。

从服务器搜索数据，输入关键字进行查找。为了启用远程搜索，需要将`filterable`和`remote`设置为`true`，同时传入一个`remote-method`。 `remote-method`为一个`Function`，它会在输入值发生变化时调用，参数为当前输入值。

default

Please enter a keyword

use remote-show-suffix

Please enter a keyword

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXBcIj5cbiAgICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgICA8cD5kZWZhdWx0PC9wPlxuICAgICAgPGVsLXNlbGVjdC12MlxuICAgICAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICAgIG11bHRpcGxlXG4gICAgICAgIGZpbHRlcmFibGVcbiAgICAgICAgcmVtb3RlXG4gICAgICAgIDpyZW1vdGUtbWV0aG9kPVwicmVtb3RlTWV0aG9kXCJcbiAgICAgICAgY2xlYXJhYmxlXG4gICAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICAgIDpsb2FkaW5nPVwibG9hZGluZ1wiXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGVudGVyIGEga2V5d29yZFwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJtLTRcIj5cbiAgICAgIDxwPnVzZSByZW1vdGUtc2hvdy1zdWZmaXg8L3A+XG4gICAgICA8ZWwtc2VsZWN0LXYyXG4gICAgICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICAgICAgbXVsdGlwbGVcbiAgICAgICAgZmlsdGVyYWJsZVxuICAgICAgICByZW1vdGVcbiAgICAgICAgOnJlbW90ZS1tZXRob2Q9XCJyZW1vdGVNZXRob2RcIlxuICAgICAgICByZW1vdGUtc2hvdy1zdWZmaXhcbiAgICAgICAgY2xlYXJhYmxlXG4gICAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICAgIDpsb2FkaW5nPVwibG9hZGluZ1wiXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGVudGVyIGEga2V5d29yZFwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHN0YXRlcyA9IFtcbiAgJ0FsYWJhbWEnLFxuICAnQWxhc2thJyxcbiAgJ0FyaXpvbmEnLFxuICAnQXJrYW5zYXMnLFxuICAnQ2FsaWZvcm5pYScsXG4gICdDb2xvcmFkbycsXG4gICdDb25uZWN0aWN1dCcsXG4gICdEZWxhd2FyZScsXG4gICdGbG9yaWRhJyxcbiAgJ0dlb3JnaWEnLFxuICAnSGF3YWlpJyxcbiAgJ0lkYWhvJyxcbiAgJ0lsbGlub2lzJyxcbiAgJ0luZGlhbmEnLFxuICAnSW93YScsXG4gICdLYW5zYXMnLFxuICAnS2VudHVja3knLFxuICAnTG91aXNpYW5hJyxcbiAgJ01haW5lJyxcbiAgJ01hcnlsYW5kJyxcbiAgJ01hc3NhY2h1c2V0dHMnLFxuICAnTWljaGlnYW4nLFxuICAnTWlubmVzb3RhJyxcbiAgJ01pc3Npc3NpcHBpJyxcbiAgJ01pc3NvdXJpJyxcbiAgJ01vbnRhbmEnLFxuICAnTmVicmFza2EnLFxuICAnTmV2YWRhJyxcbiAgJ05ldyBIYW1wc2hpcmUnLFxuICAnTmV3IEplcnNleScsXG4gICdOZXcgTWV4aWNvJyxcbiAgJ05ldyBZb3JrJyxcbiAgJ05vcnRoIENhcm9saW5hJyxcbiAgJ05vcnRoIERha290YScsXG4gICdPaGlvJyxcbiAgJ09rbGFob21hJyxcbiAgJ09yZWdvbicsXG4gICdQZW5uc3lsdmFuaWEnLFxuICAnUmhvZGUgSXNsYW5kJyxcbiAgJ1NvdXRoIENhcm9saW5hJyxcbiAgJ1NvdXRoIERha290YScsXG4gICdUZW5uZXNzZWUnLFxuICAnVGV4YXMnLFxuICAnVXRhaCcsXG4gICdWZXJtb250JyxcbiAgJ1ZpcmdpbmlhJyxcbiAgJ1dhc2hpbmd0b24nLFxuICAnV2VzdCBWaXJnaW5pYScsXG4gICdXaXNjb25zaW4nLFxuICAnV3lvbWluZycsXG5dXG5jb25zdCBsaXN0ID0gc3RhdGVzLm1hcCgoaXRlbSk6IExpc3RJdGVtID0+IHtcbiAgcmV0dXJuIHsgdmFsdWU6IGB2YWx1ZToke2l0ZW19YCwgbGFiZWw6IGBsYWJlbDoke2l0ZW19YCB9XG59KVxuXG5pbnRlcmZhY2UgTGlzdEl0ZW0ge1xuICB2YWx1ZTogc3RyaW5nXG4gIGxhYmVsOiBzdHJpbmdcbn1cblxuY29uc3QgdmFsdWUgPSByZWYoW10pXG5jb25zdCBvcHRpb25zID0gcmVmPExpc3RJdGVtW10+KFtdKVxuY29uc3QgbG9hZGluZyA9IHJlZihmYWxzZSlcblxuY29uc3QgcmVtb3RlTWV0aG9kID0gKHF1ZXJ5OiBzdHJpbmcpID0+IHtcbiAgaWYgKHF1ZXJ5ICE9PSAnJykge1xuICAgIGxvYWRpbmcudmFsdWUgPSB0cnVlXG4gICAgc2V0VGltZW91dCgoKSA9PiB7XG4gICAgICBsb2FkaW5nLnZhbHVlID0gZmFsc2VcbiAgICAgIG9wdGlvbnMudmFsdWUgPSBsaXN0LmZpbHRlcigoaXRlbSkgPT4ge1xuICAgICAgICByZXR1cm4gaXRlbS5sYWJlbC50b0xvd2VyQ2FzZSgpLmluY2x1ZGVzKHF1ZXJ5LnRvTG93ZXJDYXNlKCkpXG4gICAgICB9KVxuICAgIH0sIDIwMClcbiAgfSBlbHNlIHtcbiAgICBvcHRpb25zLnZhbHVlID0gW11cbiAgfVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/remote-search.vue)_

vue

```
<template>
  <div class="flex flex-wrap">
    <div class="m-4">
      <p>default</p>
      <el-select-v2
        v-model="value"
        style="width: 240px"
        multiple
        filterable
        remote
        :remote-method="remoteMethod"
        clearable
        :options="options"
        :loading="loading"
        placeholder="Please enter a keyword"
      />
    </div>
    <div class="m-4">
      <p>use remote-show-suffix</p>
      <el-select-v2
        v-model="value"
        style="width: 240px"
        multiple
        filterable
        remote
        :remote-method="remoteMethod"
        remote-show-suffix
        clearable
        :options="options"
        :loading="loading"
        placeholder="Please enter a keyword"
      />
    </div>
  </div>
</template>

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

const states = [
  'Alabama',
  'Alaska',
  'Arizona',
  'Arkansas',
  'California',
  'Colorado',
  'Connecticut',
  'Delaware',
  'Florida',
  'Georgia',
  'Hawaii',
  'Idaho',
  'Illinois',
  'Indiana',
  'Iowa',
  'Kansas',
  'Kentucky',
  'Louisiana',
  'Maine',
  'Maryland',
  'Massachusetts',
  'Michigan',
  'Minnesota',
  'Mississippi',
  'Missouri',
  'Montana',
  'Nebraska',
  'Nevada',
  'New Hampshire',
  'New Jersey',
  'New Mexico',
  'New York',
  'North Carolina',
  'North Dakota',
  'Ohio',
  'Oklahoma',
  'Oregon',
  'Pennsylvania',
  'Rhode Island',
  'South Carolina',
  'South Dakota',
  'Tennessee',
  'Texas',
  'Utah',
  'Vermont',
  'Virginia',
  'Washington',
  'West Virginia',
  'Wisconsin',
  'Wyoming',
]
const list = states.map((item): ListItem => {
  return { value: `value:${item}`, label: `label:${item}` }
})

interface ListItem {
  value: string
  label: string
}

const value = ref([])
const options = ref<ListItem[]>([])
const loading = ref(false)

const remoteMethod = (query: string) => {
  if (query !== '') {
    loading.value = true
    setTimeout(() => {
      loading.value = false
      options.value = list.filter((item) => {
        return item.label.toLowerCase().includes(query.toLowerCase())
      })
    }, 200)
  } else {
    options.value = []
  }
}
</script>
```

隐藏源代码

## 使用 value-key 键属性 [​](#使用-value-key-键属性)

当 `options.value` 是一个对象时，您应该为它设置一个唯一的标识名称

TIP

在 2.4.0 之前，`value-key`既用作所选对象的唯一值，也用作`options`中表示值的对应 key。 现在 `value-key` 仅作为所选对象的唯一值使用，选项中值的 key 是 `props.value`.

a0

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIHNlbGVjdFwiXG4gICAgdmFsdWUta2V5PVwibmFtZVwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgaW5pdGlhbHMgPSBbJ2EnLCAnYicsICdjJywgJ2QnLCAnZScsICdmJywgJ2cnLCAnaCcsICdpJywgJ2onXVxuXG5jb25zdCB2YWx1ZSA9IHJlZih7IG5hbWU6ICdPcHRpb24gMScsIHRlc3Q6ICd0ZXN0IDAnIH0pXG5jb25zdCBvcHRpb25zID0gQXJyYXkuZnJvbSh7IGxlbmd0aDogMTAwMCB9KS5tYXAoKF8sIGlkeCkgPT4gKHtcbiAgdmFsdWU6IHtcbiAgICBuYW1lOiBgT3B0aW9uICR7aWR4ICsgMX1gLFxuICAgIHRlc3Q6IGB0ZXN0ICR7aWR4ICUgM31gLFxuICB9LFxuICBsYWJlbDogYCR7aW5pdGlhbHNbaWR4ICUgMTBdfSR7aWR4fWAsXG59KSlcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmV4YW1wbGUtc2hvd2Nhc2UgLmVsLXNlbGVjdC12MiB7XG4gIG1hcmdpbi1yaWdodDogMjBweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/use-valueKey.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value"
    :options="options"
    placeholder="Please select"
    value-key="name"
    style="width: 240px"
  />
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value = ref({ name: 'Option 1', test: 'test 0' })
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: {
    name: `Option ${idx + 1}`,
    test: `test ${idx % 3}`,
  },
  label: `${initials[idx % 10]}${idx}`,
}))
</script>

<style scoped>
.example-showcase .el-select-v2 {
  margin-right: 20px;
}
</style>
```

隐藏源代码

## 自定义选项 2.4.2 [​](#自定义选项)

当您的 `options` 格式不同于默认格式 您可以通过 `props` 属性自定义 `options`

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgIDpwcm9wcz1cInByb3BzXCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICBmaWx0ZXJhYmxlXG4gICAgbXVsdGlwbGVcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGluaXRpYWxzID0gWydhJywgJ2InLCAnYycsICdkJywgJ2UnLCAnZicsICdnJywgJ2gnLCAnaScsICdqJ11cbmNvbnN0IHByb3BzID0ge1xuICBsYWJlbDogJ25hbWUnLFxuICB2YWx1ZTogJ2lkJyxcbn1cbmNvbnN0IHZhbHVlID0gcmVmKFtdKVxuY29uc3Qgb3B0aW9ucyA9IEFycmF5LmZyb20oeyBsZW5ndGg6IDEwMDAgfSkubWFwKChfLCBpZHgpID0+ICh7XG4gIGlkOiBgT3B0aW9uICR7aWR4ICsgMX1gLFxuICBuYW1lOiBgJHtpbml0aWFsc1tpZHggJSAxMF19JHtpZHh9YCxcbn0pKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/props.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value"
    :options="options"
    :props="props"
    placeholder="Please select"
    style="width: 240px"
    filterable
    multiple
  />
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']
const props = {
  label: 'name',
  value: 'id',
}
const value = ref([])
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  id: `Option ${idx + 1}`,
  name: `${initials[idx % 10]}${idx}`,
}))
</script>
```

隐藏源代码

## 自定义标签 2.5.0 [​](#自定义标签)

您可以自定义标签。

将自定义的标签插入 `el-select` 的 slot 中即可。 `collapse-tags`, `collapse-tags-tooltip`, `max-collapse-tags` 在此模式下不生效.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICBtdWx0aXBsZVxuICAgIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCJcbiAgICA6b3B0aW9ucz1cImNvbG9yc1wiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICA+XG4gICAgPHRlbXBsYXRlICNkZWZhdWx0PVwieyBpdGVtIH1cIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJmbGV4IGl0ZW1zLWNlbnRlclwiPlxuICAgICAgICA8ZWwtdGFnIDpjb2xvcj1cIml0ZW0udmFsdWVcIiBzdHlsZT1cIm1hcmdpbi1yaWdodDogOHB4XCIgc2l6ZT1cInNtYWxsXCIgLz5cbiAgICAgICAgPHNwYW4gOnN0eWxlPVwieyBjb2xvcjogaXRlbS52YWx1ZSB9XCI+e3sgaXRlbS5sYWJlbCB9fTwvc3Bhbj5cbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gICAgPHRlbXBsYXRlICN0YWc+XG4gICAgICA8ZWwtdGFnIHYtZm9yPVwiY29sb3IgaW4gdmFsdWVcIiA6a2V5PVwiY29sb3JcIiA6Y29sb3I9XCJjb2xvclwiIC8+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1zZWxlY3QtdjI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZjxzdHJpbmdbXT4oW10pXG5jb25zdCBjb2xvcnMgPSBbXG4gIHtcbiAgICB2YWx1ZTogJyNFNjM0MTUnLFxuICAgIGxhYmVsOiAncmVkJyxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnI0ZGNjYwMCcsXG4gICAgbGFiZWw6ICdvcmFuZ2UnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICcjRkZERTBBJyxcbiAgICBsYWJlbDogJ3llbGxvdycsXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJyMxRUM3OUQnLFxuICAgIGxhYmVsOiAnZ3JlZW4nLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICcjMTRDQ0NDJyxcbiAgICBsYWJlbDogJ2N5YW4nLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICcjNDE2N0YwJyxcbiAgICBsYWJlbDogJ2JsdWUnLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICcjNjIyMkM5JyxcbiAgICBsYWJlbDogJ3B1cnBsZScsXG4gIH0sXG5dXG5jb2xvcnMuZm9yRWFjaCgoY29sb3IpID0+IHtcbiAgdmFsdWUudmFsdWUucHVzaChjb2xvci52YWx1ZSlcbn0pXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5lbC10YWcge1xuICBib3JkZXI6IG5vbmU7XG4gIGFzcGVjdC1yYXRpbzogMTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/custom-tag.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value"
    multiple
    placeholder="Select"
    :options="colors"
    style="width: 240px"
  >
    <template #default="{ item }">
      <div class="flex items-center">
        <el-tag :color="item.value" style="margin-right: 8px" size="small" />
        <span :style="{ color: item.value }">{{ item.label }}</span>
      </div>
    </template>
    <template #tag>
      <el-tag v-for="color in value" :key="color" :color="color" />
    </template>
  </el-select-v2>
</template>

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

const value = ref<string[]>([])
const colors = [
  {
    value: '#E63415',
    label: 'red',
  },
  {
    value: '#FF6600',
    label: 'orange',
  },
  {
    value: '#FFDE0A',
    label: 'yellow',
  },
  {
    value: '#1EC79D',
    label: 'green',
  },
  {
    value: '#14CCCC',
    label: 'cyan',
  },
  {
    value: '#4167F0',
    label: 'blue',
  },
  {
    value: '#6222C9',
    label: 'purple',
  },
]
colors.forEach((color) => {
  value.value.push(color.value)
})
</script>

<style scoped>
.el-tag {
  border: none;
  aspect-ratio: 1;
}
</style>
```

隐藏源代码

## 自定义加载 2.5.2 [​](#自定义加载)

修改加载区域内容

loading icon1

Please enter a keyword

loading icon2

Please enter a keyword

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXBcIj5cbiAgICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgICA8cD5sb2FkaW5nIGljb24xPC9wPlxuICAgICAgPGVsLXNlbGVjdC12MlxuICAgICAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgICAgICBtdWx0aXBsZVxuICAgICAgICBmaWx0ZXJhYmxlXG4gICAgICAgIHJlbW90ZVxuICAgICAgICByZXNlcnZlLWtleXdvcmRcbiAgICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2UgZW50ZXIgYSBrZXl3b3JkXCJcbiAgICAgICAgOnJlbW90ZS1tZXRob2Q9XCJyZW1vdGVNZXRob2RcIlxuICAgICAgICA6bG9hZGluZz1cImxvYWRpbmdcIlxuICAgICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjbG9hZGluZz5cbiAgICAgICAgICA8c3ZnIGNsYXNzPVwiY2lyY3VsYXJcIiB2aWV3Qm94PVwiMCAwIDUwIDUwXCI+XG4gICAgICAgICAgICA8Y2lyY2xlIGNsYXNzPVwicGF0aFwiIGN4PVwiMjVcIiBjeT1cIjI1XCIgcj1cIjIwXCIgZmlsbD1cIm5vbmVcIiAvPlxuICAgICAgICAgIDwvc3ZnPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1zZWxlY3QtdjI+XG4gICAgPC9kaXY+XG4gICAgPGRpdiBjbGFzcz1cIm0tNFwiPlxuICAgICAgPHA+bG9hZGluZyBpY29uMjwvcD5cbiAgICAgIDxlbC1zZWxlY3QtdjJcbiAgICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgICAgbXVsdGlwbGVcbiAgICAgICAgZmlsdGVyYWJsZVxuICAgICAgICByZW1vdGVcbiAgICAgICAgcmVzZXJ2ZS1rZXl3b3JkXG4gICAgICAgIHBsYWNlaG9sZGVyPVwiUGxlYXNlIGVudGVyIGEga2V5d29yZFwiXG4gICAgICAgIDpyZW1vdGUtbWV0aG9kPVwicmVtb3RlTWV0aG9kXCJcbiAgICAgICAgOmxvYWRpbmc9XCJsb2FkaW5nXCJcbiAgICAgICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI2xvYWRpbmc+XG4gICAgICAgICAgPGVsLWljb24gY2xhc3M9XCJpcy1sb2FkaW5nXCI+XG4gICAgICAgICAgICA8c3ZnIGNsYXNzPVwiY2lyY3VsYXJcIiB2aWV3Qm94PVwiMCAwIDIwIDIwXCI+XG4gICAgICAgICAgICAgIDxnXG4gICAgICAgICAgICAgICAgY2xhc3M9XCJwYXRoMiBsb2FkaW5nLXBhdGhcIlxuICAgICAgICAgICAgICAgIHN0cm9rZS13aWR0aD1cIjBcIlxuICAgICAgICAgICAgICAgIHN0eWxlPVwiYW5pbWF0aW9uOiBub25lOyBzdHJva2U6IG5vbmVcIlxuICAgICAgICAgICAgICA+XG4gICAgICAgICAgICAgICAgPGNpcmNsZSByPVwiMy4zNzVcIiBjbGFzcz1cImRvdDFcIiByeD1cIjBcIiByeT1cIjBcIiAvPlxuICAgICAgICAgICAgICAgIDxjaXJjbGUgcj1cIjMuMzc1XCIgY2xhc3M9XCJkb3QyXCIgcng9XCIwXCIgcnk9XCIwXCIgLz5cbiAgICAgICAgICAgICAgICA8Y2lyY2xlIHI9XCIzLjM3NVwiIGNsYXNzPVwiZG90NFwiIHJ4PVwiMFwiIHJ5PVwiMFwiIC8+XG4gICAgICAgICAgICAgICAgPGNpcmNsZSByPVwiMy4zNzVcIiBjbGFzcz1cImRvdDNcIiByeD1cIjBcIiByeT1cIjBcIiAvPlxuICAgICAgICAgICAgICA8L2c+XG4gICAgICAgICAgICA8L3N2Zz5cbiAgICAgICAgICA8L2VsLWljb24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXNlbGVjdC12Mj5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgb25Nb3VudGVkLCByZWYgfSBmcm9tICd2dWUnXG5cbmludGVyZmFjZSBMaXN0SXRlbSB7XG4gIHZhbHVlOiBzdHJpbmdcbiAgbGFiZWw6IHN0cmluZ1xufVxuXG5jb25zdCBsaXN0ID0gcmVmPExpc3RJdGVtW10+KFtdKVxuY29uc3Qgb3B0aW9ucyA9IHJlZjxMaXN0SXRlbVtdPihbXSlcbmNvbnN0IHZhbHVlID0gcmVmPHN0cmluZ1tdPihbXSlcbmNvbnN0IGxvYWRpbmcgPSByZWYoZmFsc2UpXG5cbm9uTW91bnRlZCgoKSA9PiB7XG4gIGxpc3QudmFsdWUgPSBzdGF0ZXMubWFwKChpdGVtKSA9PiB7XG4gICAgcmV0dXJuIHsgdmFsdWU6IGB2YWx1ZToke2l0ZW19YCwgbGFiZWw6IGBsYWJlbDoke2l0ZW19YCB9XG4gIH0pXG59KVxuXG5jb25zdCByZW1vdGVNZXRob2QgPSAocXVlcnk6IHN0cmluZykgPT4ge1xuICBpZiAocXVlcnkpIHtcbiAgICBsb2FkaW5nLnZhbHVlID0gdHJ1ZVxuICAgIHNldFRpbWVvdXQoKCkgPT4ge1xuICAgICAgbG9hZGluZy52YWx1ZSA9IGZhbHNlXG4gICAgICBvcHRpb25zLnZhbHVlID0gbGlzdC52YWx1ZS5maWx0ZXIoKGl0ZW0pID0+IHtcbiAgICAgICAgcmV0dXJuIGl0ZW0ubGFiZWwudG9Mb3dlckNhc2UoKS5pbmNsdWRlcyhxdWVyeS50b0xvd2VyQ2FzZSgpKVxuICAgICAgfSlcbiAgICB9LCAzMDAwKVxuICB9IGVsc2Uge1xuICAgIG9wdGlvbnMudmFsdWUgPSBbXVxuICB9XG59XG5cbmNvbnN0IHN0YXRlcyA9IFtcbiAgJ0FsYWJhbWEnLFxuICAnQWxhc2thJyxcbiAgJ0FyaXpvbmEnLFxuICAnQXJrYW5zYXMnLFxuICAnQ2FsaWZvcm5pYScsXG4gICdDb2xvcmFkbycsXG4gICdDb25uZWN0aWN1dCcsXG4gICdEZWxhd2FyZScsXG4gICdGbG9yaWRhJyxcbiAgJ0dlb3JnaWEnLFxuICAnSGF3YWlpJyxcbiAgJ0lkYWhvJyxcbiAgJ0lsbGlub2lzJyxcbiAgJ0luZGlhbmEnLFxuICAnSW93YScsXG4gICdLYW5zYXMnLFxuICAnS2VudHVja3knLFxuICAnTG91aXNpYW5hJyxcbiAgJ01haW5lJyxcbiAgJ01hcnlsYW5kJyxcbiAgJ01hc3NhY2h1c2V0dHMnLFxuICAnTWljaGlnYW4nLFxuICAnTWlubmVzb3RhJyxcbiAgJ01pc3Npc3NpcHBpJyxcbiAgJ01pc3NvdXJpJyxcbiAgJ01vbnRhbmEnLFxuICAnTmVicmFza2EnLFxuICAnTmV2YWRhJyxcbiAgJ05ldyBIYW1wc2hpcmUnLFxuICAnTmV3IEplcnNleScsXG4gICdOZXcgTWV4aWNvJyxcbiAgJ05ldyBZb3JrJyxcbiAgJ05vcnRoIENhcm9saW5hJyxcbiAgJ05vcnRoIERha290YScsXG4gICdPaGlvJyxcbiAgJ09rbGFob21hJyxcbiAgJ09yZWdvbicsXG4gICdQZW5uc3lsdmFuaWEnLFxuICAnUmhvZGUgSXNsYW5kJyxcbiAgJ1NvdXRoIENhcm9saW5hJyxcbiAgJ1NvdXRoIERha290YScsXG4gICdUZW5uZXNzZWUnLFxuICAnVGV4YXMnLFxuICAnVXRhaCcsXG4gICdWZXJtb250JyxcbiAgJ1ZpcmdpbmlhJyxcbiAgJ1dhc2hpbmd0b24nLFxuICAnV2VzdCBWaXJnaW5pYScsXG4gICdXaXNjb25zaW4nLFxuICAnV3lvbWluZycsXG5dXG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLmVsLXNlbGVjdC1kcm9wZG93bl9fbG9hZGluZyB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGp1c3RpZnktY29udGVudDogY2VudGVyO1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBoZWlnaHQ6IDEwMHB4O1xuICBmb250LXNpemU6IDIwcHg7XG59XG5cbi5jaXJjdWxhciB7XG4gIGRpc3BsYXk6IGlubGluZTtcbiAgaGVpZ2h0OiAzMHB4O1xuICB3aWR0aDogMzBweDtcbiAgYW5pbWF0aW9uOiBsb2FkaW5nLXJvdGF0ZSAycyBsaW5lYXIgaW5maW5pdGU7XG59XG4ucGF0aCB7XG4gIGFuaW1hdGlvbjogbG9hZGluZy1kYXNoIDEuNXMgZWFzZS1pbi1vdXQgaW5maW5pdGU7XG4gIHN0cm9rZS1kYXNoYXJyYXk6IDkwLCAxNTA7XG4gIHN0cm9rZS1kYXNob2Zmc2V0OiAwO1xuICBzdHJva2Utd2lkdGg6IDI7XG4gIHN0cm9rZTogdmFyKC0tZWwtY29sb3ItcHJpbWFyeSk7XG4gIHN0cm9rZS1saW5lY2FwOiByb3VuZDtcbn1cbi5sb2FkaW5nLXBhdGggLmRvdDEge1xuICB0cmFuc2Zvcm06IHRyYW5zbGF0ZSgzLjc1cHgsIDMuNzVweCk7XG4gIGZpbGw6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xuICBhbmltYXRpb246IGN1c3RvbS1zcGluLW1vdmUgMXMgaW5maW5pdGUgbGluZWFyIGFsdGVybmF0ZTtcbiAgb3BhY2l0eTogMC4zO1xufVxuLmxvYWRpbmctcGF0aCAuZG90MiB7XG4gIHRyYW5zZm9ybTogdHJhbnNsYXRlKGNhbGMoMTAwJSAtIDMuNzVweCksIDMuNzVweCk7XG4gIGZpbGw6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xuICBhbmltYXRpb246IGN1c3RvbS1zcGluLW1vdmUgMXMgaW5maW5pdGUgbGluZWFyIGFsdGVybmF0ZTtcbiAgb3BhY2l0eTogMC4zO1xuICBhbmltYXRpb24tZGVsYXk6IDAuNHM7XG59XG4ubG9hZGluZy1wYXRoIC5kb3QzIHtcbiAgdHJhbnNmb3JtOiB0cmFuc2xhdGUoMy43NXB4LCBjYWxjKDEwMCUgLSAzLjc1cHgpKTtcbiAgZmlsbDogdmFyKC0tZWwtY29sb3ItcHJpbWFyeSk7XG4gIGFuaW1hdGlvbjogY3VzdG9tLXNwaW4tbW92ZSAxcyBpbmZpbml0ZSBsaW5lYXIgYWx0ZXJuYXRlO1xuICBvcGFjaXR5OiAwLjM7XG4gIGFuaW1hdGlvbi1kZWxheTogMS4ycztcbn1cbi5sb2FkaW5nLXBhdGggLmRvdDQge1xuICB0cmFuc2Zvcm06IHRyYW5zbGF0ZShjYWxjKDEwMCUgLSAzLjc1cHgpLCBjYWxjKDEwMCUgLSAzLjc1cHgpKTtcbiAgZmlsbDogdmFyKC0tZWwtY29sb3ItcHJpbWFyeSk7XG4gIGFuaW1hdGlvbjogY3VzdG9tLXNwaW4tbW92ZSAxcyBpbmZpbml0ZSBsaW5lYXIgYWx0ZXJuYXRlO1xuICBvcGFjaXR5OiAwLjM7XG4gIGFuaW1hdGlvbi1kZWxheTogMC44cztcbn1cbkBrZXlmcmFtZXMgbG9hZGluZy1yb3RhdGUge1xuICB0byB7XG4gICAgdHJhbnNmb3JtOiByb3RhdGUoMzYwZGVnKTtcbiAgfVxufVxuQGtleWZyYW1lcyBsb2FkaW5nLWRhc2gge1xuICAwJSB7XG4gICAgc3Ryb2tlLWRhc2hhcnJheTogMSwgMjAwO1xuICAgIHN0cm9rZS1kYXNob2Zmc2V0OiAwO1xuICB9XG4gIDUwJSB7XG4gICAgc3Ryb2tlLWRhc2hhcnJheTogOTAsIDE1MDtcbiAgICBzdHJva2UtZGFzaG9mZnNldDogLTQwcHg7XG4gIH1cbiAgMTAwJSB7XG4gICAgc3Ryb2tlLWRhc2hhcnJheTogOTAsIDE1MDtcbiAgICBzdHJva2UtZGFzaG9mZnNldDogLTEyMHB4O1xuICB9XG59XG5Aa2V5ZnJhbWVzIGN1c3RvbS1zcGluLW1vdmUge1xuICB0byB7XG4gICAgb3BhY2l0eTogMTtcbiAgfVxufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/custom-loading.vue)_

vue

```
<template>
  <div class="flex flex-wrap">
    <div class="m-4">
      <p>loading icon1</p>
      <el-select-v2
        v-model="value"
        multiple
        filterable
        remote
        reserve-keyword
        placeholder="Please enter a keyword"
        :remote-method="remoteMethod"
        :loading="loading"
        :options="options"
        style="width: 240px"
      >
        <template #loading>
          <svg class="circular" viewBox="0 0 50 50">
            <circle class="path" cx="25" cy="25" r="20" fill="none" />
          </svg>
        </template>
      </el-select-v2>
    </div>
    <div class="m-4">
      <p>loading icon2</p>
      <el-select-v2
        v-model="value"
        multiple
        filterable
        remote
        reserve-keyword
        placeholder="Please enter a keyword"
        :remote-method="remoteMethod"
        :loading="loading"
        :options="options"
        style="width: 240px"
      >
        <template #loading>
          <el-icon class="is-loading">
            <svg class="circular" viewBox="0 0 20 20">
              <g
                class="path2 loading-path"
                stroke-width="0"
                style="animation: none; stroke: none"
              >
                <circle r="3.375" class="dot1" rx="0" ry="0" />
                <circle r="3.375" class="dot2" rx="0" ry="0" />
                <circle r="3.375" class="dot4" rx="0" ry="0" />
                <circle r="3.375" class="dot3" rx="0" ry="0" />
              </g>
            </svg>
          </el-icon>
        </template>
      </el-select-v2>
    </div>
  </div>
</template>

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

interface ListItem {
  value: string
  label: string
}

const list = ref<ListItem[]>([])
const options = ref<ListItem[]>([])
const value = ref<string[]>([])
const loading = ref(false)

onMounted(() => {
  list.value = states.map((item) => {
    return { value: `value:${item}`, label: `label:${item}` }
  })
})

const remoteMethod = (query: string) => {
  if (query) {
    loading.value = true
    setTimeout(() => {
      loading.value = false
      options.value = list.value.filter((item) => {
        return item.label.toLowerCase().includes(query.toLowerCase())
      })
    }, 3000)
  } else {
    options.value = []
  }
}

const states = [
  'Alabama',
  'Alaska',
  'Arizona',
  'Arkansas',
  'California',
  'Colorado',
  'Connecticut',
  'Delaware',
  'Florida',
  'Georgia',
  'Hawaii',
  'Idaho',
  'Illinois',
  'Indiana',
  'Iowa',
  'Kansas',
  'Kentucky',
  'Louisiana',
  'Maine',
  'Maryland',
  'Massachusetts',
  'Michigan',
  'Minnesota',
  'Mississippi',
  'Missouri',
  'Montana',
  'Nebraska',
  'Nevada',
  'New Hampshire',
  'New Jersey',
  'New Mexico',
  'New York',
  'North Carolina',
  'North Dakota',
  'Ohio',
  'Oklahoma',
  'Oregon',
  'Pennsylvania',
  'Rhode Island',
  'South Carolina',
  'South Dakota',
  'Tennessee',
  'Texas',
  'Utah',
  'Vermont',
  'Virginia',
  'Washington',
  'West Virginia',
  'Wisconsin',
  'Wyoming',
]
</script>

<style>
.el-select-dropdown__loading {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100px;
  font-size: 20px;
}

.circular {
  display: inline;
  height: 30px;
  width: 30px;
  animation: loading-rotate 2s linear infinite;
}
.path {
  animation: loading-dash 1.5s ease-in-out infinite;
  stroke-dasharray: 90, 150;
  stroke-dashoffset: 0;
  stroke-width: 2;
  stroke: var(--el-color-primary);
  stroke-linecap: round;
}
.loading-path .dot1 {
  transform: translate(3.75px, 3.75px);
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
}
.loading-path .dot2 {
  transform: translate(calc(100% - 3.75px), 3.75px);
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 0.4s;
}
.loading-path .dot3 {
  transform: translate(3.75px, calc(100% - 3.75px));
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 1.2s;
}
.loading-path .dot4 {
  transform: translate(calc(100% - 3.75px), calc(100% - 3.75px));
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 0.8s;
}
@keyframes loading-rotate {
  to {
    transform: rotate(360deg);
  }
}
@keyframes loading-dash {
  0% {
    stroke-dasharray: 1, 200;
    stroke-dashoffset: 0;
  }
  50% {
    stroke-dasharray: 90, 150;
    stroke-dashoffset: -40px;
  }
  100% {
    stroke-dasharray: 90, 150;
    stroke-dashoffset: -120px;
  }
}
@keyframes custom-spin-move {
  to {
    opacity: 1;
  }
}
</style>
```

隐藏源代码

## 空值配置2.7.0 [​](#空值配置)

若想配置如空字符串为有效值而不是空值，可以配置 `empty-values` 为 `[null, undefined]`.

如果您想要将清空值更改为 `null`, 请设置 `value-on-clear` 为 `null`

All

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2VsZWN0LXYyXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgIDplbXB0eS12YWx1ZXM9XCJbbnVsbCwgdW5kZWZpbmVkXVwiXG4gICAgOnZhbHVlLW9uLWNsZWFyPVwibnVsbFwiXG4gICAgY2xlYXJhYmxlXG4gICAgcGxhY2Vob2xkZXI9XCJTZWxlY3RcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICBAY2xlYXI9XCJoYW5kbGVDbGVhclwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgRWxNZXNzYWdlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZignJylcblxuY29uc3QgaW5pdGlhbHMgPSBbJ2EnLCAnYicsICdjJywgJ2QnLCAnZScsICdmJywgJ2cnLCAnaCcsICdpJywgJ2onXVxuXG5jb25zdCBvcHRpb25zID0gQXJyYXkuZnJvbSh7IGxlbmd0aDogMTAwMCB9KS5tYXAoKF8sIGlkeCkgPT4gKHtcbiAgdmFsdWU6IGBPcHRpb24gJHtpZHggKyAxfWAsXG4gIGxhYmVsOiBgJHtpbml0aWFsc1tpZHggJSAxMF19JHtpZHh9YCxcbn0pKVxuXG5vcHRpb25zLnVuc2hpZnQoe1xuICB2YWx1ZTogJycsXG4gIGxhYmVsOiAnQWxsJyxcbn0pXG5cbmNvbnN0IGhhbmRsZUNsZWFyID0gKCkgPT4ge1xuICBFbE1lc3NhZ2UuaW5mbyhgVGhlIGNsZWFyIHZhbHVlIGlzOiAke3ZhbHVlLnZhbHVlfWApXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/empty-values.vue)_

vue

```
<template>
  <el-select-v2
    v-model="value"
    :options="options"
    :empty-values="[null, undefined]"
    :value-on-clear="null"
    clearable
    placeholder="Select"
    style="width: 240px"
    @clear="handleClear"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElMessage } from 'element-plus'

const value = ref('')

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: `Option ${idx + 1}`,
  label: `${initials[idx % 10]}${idx}`,
}))

options.unshift({
  value: '',
  label: 'All',
})

const handleClear = () => {
  ElMessage.info(`The clear value is: ${value.value}`)
}
</script>
```

隐藏源代码

## 自定义标签 2.7.4 [​](#自定义标签-1)

您可以自定义标签

a0: Option 1

a0: Option 1

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTQgaXRlbXMtY2VudGVyXCI+XG4gICAgPGVsLXNlbGVjdC12MlxuICAgICAgdi1tb2RlbD1cInZhbHVlMVwiXG4gICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJTZWxlY3RcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgY2xlYXJhYmxlXG4gICAgPlxuICAgICAgPHRlbXBsYXRlICNsYWJlbD1cInsgbGFiZWwsIHZhbHVlIH1cIj5cbiAgICAgICAgPHNwYW4+e3sgbGFiZWwgfX06IDwvc3Bhbj5cbiAgICAgICAgPHNwYW4gc3R5bGU9XCJmb250LXdlaWdodDogYm9sZFwiPnt7IHZhbHVlIH19PC9zcGFuPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLXNlbGVjdC12Mj5cblxuICAgIDxlbC1zZWxlY3QtdjJcbiAgICAgIHYtbW9kZWw9XCJ2YWx1ZTJcIlxuICAgICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiU2VsZWN0XCJcbiAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICAgIGNsZWFyYWJsZVxuICAgICAgbXVsdGlwbGVcbiAgICA+XG4gICAgICA8dGVtcGxhdGUgI2xhYmVsPVwieyBsYWJlbCwgdmFsdWUgfVwiPlxuICAgICAgICA8c3Bhbj57eyBsYWJlbCB9fTogPC9zcGFuPlxuICAgICAgICA8c3BhbiBzdHlsZT1cImZvbnQtd2VpZ2h0OiBib2xkXCI+e3sgdmFsdWUgfX08L3NwYW4+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtc2VsZWN0LXYyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGluaXRpYWxzID0gWydhJywgJ2InLCAnYycsICdkJywgJ2UnLCAnZicsICdnJywgJ2gnLCAnaScsICdqJ11cbmNvbnN0IHZhbHVlMSA9IHJlZjxzdHJpbmc+KCdPcHRpb24gMScpXG5jb25zdCB2YWx1ZTIgPSByZWY8c3RyaW5nW10+KFsnT3B0aW9uIDEnXSlcbmNvbnN0IG9wdGlvbnMgPSBBcnJheS5mcm9tKHsgbGVuZ3RoOiAxMDAwIH0pLm1hcCgoXywgaWR4KSA9PiAoe1xuICB2YWx1ZTogYE9wdGlvbiAke2lkeCArIDF9YCxcbiAgbGFiZWw6IGAke2luaXRpYWxzW2lkeCAlIDEwXX0ke2lkeH1gLFxufSkpXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/custom-label.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-4 items-center">
    <el-select-v2
      v-model="value1"
      :options="options"
      placeholder="Select"
      style="width: 240px"
      clearable
    >
      <template #label="{ label, value }">
        <span>{{ label }}: </span>
        <span style="font-weight: bold">{{ value }}</span>
      </template>
    </el-select-v2>

    <el-select-v2
      v-model="value2"
      :options="options"
      placeholder="Select"
      style="width: 240px"
      clearable
      multiple
    >
      <template #label="{ label, value }">
        <span>{{ label }}: </span>
        <span style="font-weight: bold">{{ value }}</span>
      </template>
    </el-select-v2>
  </div>
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']
const value1 = ref<string>('Option 1')
const value2 = ref<string[]>(['Option 1'])
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: `Option ${idx + 1}`,
  label: `${initials[idx % 10]}${idx}`,
}))
</script>

<style scoped></style>
```

隐藏源代码

## 自定义宽度 2.9.2 [​](#自定义宽度)

下拉框的宽度默认根据`label`的值计算。 如果通过`default slot`自定义下拉框选项，选项中显示的文本可能与`label`的值不相等，从而导致计算错误。 在这种情况下，可以通过设置`fit-input-width`属性为一个数字来固定其宽度。

Please select

Please select

Please select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTQgaXRlbXMtY2VudGVyXCI+XG4gICAgPGVsLXNlbGVjdC12MlxuICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgOmZpdC1pbnB1dC13aWR0aD1cImZhbHNlXCJcbiAgICAvPlxuXG4gICAgPGVsLXNlbGVjdC12MlxuICAgICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICAgIDpvcHRpb25zPVwib3B0aW9uc1wiXG4gICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3RcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgZml0LWlucHV0LXdpZHRoXG4gICAgLz5cblxuICAgIDxlbC1zZWxlY3QtdjJcbiAgICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgICA6b3B0aW9ucz1cIm9wdGlvbnNcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJQbGVhc2Ugc2VsZWN0XCJcbiAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICAgIDpmaXQtaW5wdXQtd2lkdGg9XCI0NDBcIlxuICAgID5cbiAgICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD1cInsgaXRlbSB9XCI+XG4gICAgICAgIDxzcGFuPnt7IGl0ZW0udmFsdWUgKyBpdGVtLmxhYmVsIH19PC9zcGFuPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLXNlbGVjdC12Mj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBpbml0aWFscyA9IFsnYScsICdiJywgJ2MnLCAnZCcsICdlJywgJ2YnLCAnZycsICdoJywgJ2knLCAnaiddXG5cbmNvbnN0IHZhbHVlID0gcmVmKClcbmNvbnN0IG9wdGlvbnMgPSBBcnJheS5mcm9tKHsgbGVuZ3RoOiAxMDAwIH0pLm1hcCgoXywgaWR4KSA9PiAoe1xuICB2YWx1ZTogYE9wdGlvbiAke2lkeCArIDF9YCxcbiAgbGFiZWw6IGAke2luaXRpYWxzW2lkeCAlIDEwXX0ke2lkeH0keyctJy5yZXBlYXQoTWF0aC5jZWlsKGlkeCAvIDI1KSl9YCxcbn0pKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/select-v2/custom-width.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-4 items-center">
    <el-select-v2
      v-model="value"
      :options="options"
      placeholder="Please select"
      style="width: 240px"
      :fit-input-width="false"
    />

    <el-select-v2
      v-model="value"
      :options="options"
      placeholder="Please select"
      style="width: 240px"
      fit-input-width
    />

    <el-select-v2
      v-model="value"
      :options="options"
      placeholder="Please select"
      style="width: 240px"
      :fit-input-width="440"
    >
      <template #default="{ item }">
        <span>{{ item.value + item.label }}</span>
      </template>
    </el-select-v2>
  </div>
</template>

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

const initials = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j']

const value = ref()
const options = Array.from({ length: 1000 }).map((_, idx) => ({
  value: `Option ${idx + 1}`,
  label: `${initials[idx % 10]}${idx}${'-'.repeat(Math.ceil(idx / 25))}`,
}))
</script>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `string` / `number` / `boolean` / `object` / `array` | — |
| options | 选项的数据源， `value` 的 key 和 `label` 可以通过 `props`自定义. | `array` | — |
| [props](#props) 2.4.2 | 配置选项，具体看下表 | `object` | — |
| multiple | 是否多选 | `boolean` | false |
| disabled | 是否禁用 | `boolean` | false |
| value-key | 作为 value 唯一标识的键名，绑定值为对象类型时必填 | `string` | value |
| size | 组件大小 | `enum` | '' |
| clearable | 是否可以清空选项 | `boolean` | false |
| clear-icon | 自定义清除图标 | `string` / `object` | CircleClose |
| collapse-tags | 多选时是否将选中值按文字的形式展示 | `boolean` | false |
| multiple-limit | 多选时可被选择的最大数目。 当被设置为0时，可被选择的数目不设限。 | `number` | 0 |
| id | 原生 input 的 id | `string` | — |
| name | 选择器的原生name属性 | `string` | — |
| effect | tooltip 主题，内置了 `dark` / `light` 两种 | `enum` / `string` | light |
| autocomplete | 自动完成选择输入 | `string` | off |
| placeholder | 占位文字 | `string` | Please select |
| filterable | Select 组件是否可筛选 | `boolean` | false |
| allow-create | 是否允许创建新条目， 当使用该属性时，`filterable`必须设置为`true` | `boolean` | false |
| filter-method | 自定义筛选方法的第一个参数是当前输入的值。 当`filterable`设置为 true 时才会生效 | `Function` | — |
| loading | 是否从远程加载数据 | `boolean` | false |
| loading-text | 从服务器加载数据时显示的文本，默认为“Loading” | `string` | — |
| reserve-keyword | 筛选时，是否在选择选项后保留关键字 | `boolean` | true |
| default-first-option | 是否在输入框按下回车时，选择第一个匹配项。 需配合 `filterable` 或 `remote` 使用 | `boolean` | false |
| no-match-text | 搜索条件无匹配时显示的文字，也可以使用 `empty` 插槽设置，默认是 “No matching data'” | `string` | — |
| no-data-text | 当在没有数据时显示的文字，你同时可以使用empty插槽进行设置。 | `string` | No Data |
| popper-class | Select 下拉菜单和标签提示的自定义类名 | `string` / `object` | '' |
| popper-style 2.11.0 | Select 下拉菜单和标签提示的自定义样式 | `string` / `object` | — |
| teleported | 是否使用 teleport。设置成 `true`则会被追加到 `append-to` 的位置 | `boolean` | true |
| append-to 2.8.8 | 下拉框挂载到哪个 DOM 元素 | `CSSSelector` / `HTMLElement` | — |
| persistent | 当下拉选择器未被激活并且`persistent`设置为`false`，选择器会被删除。 | `boolean` | true |
| popper-options | [popper.js](https://popper.js.org/docs/v2/) parameters | `object`refer to [popper.js](https://popper.js.org/docs/v2/) doc | {} |
| automatic-dropdown | 对于不可搜索的 Select，是否在输入框获得焦点后自动弹出选项菜单 | `boolean` | false |
| fit-input-width 2.9.2 | 无论下拉框的宽度是否与输入框相同，如果值为`number`，则宽度是固定的。 | `boolean` / `number` | true |
| suffix-icon 2.9.8 | 自定义后缀图标组件 | `string` / `object` | ArrowDown |
| height | 下拉菜单的高度，每一个选项为34px | `number` | 274 |
| item-height | 下拉项的高度 | `number` | 34 |
| 估计选项高度 | 控制虚拟列表大小模式：如果未定义，则列表使用来自 `item-height` 的固定项目高度；如果提供，则列表使用动态项目大小，并将此值作为估计的项目高度。 | `number` | — |
| scrollbar-always-on | 是否总是展示滚动条 | `boolean` | false |
| remote | 是否从服务器获取数据 | `boolean` | false |
| debounce 2.11.7 | 远程搜索时的防抖延迟（以毫秒为单位） | `number` | 300 |
| remote-method | 当输入值发生变化时触发的函数。 它的参数就是当前的输入值。 当`filterable`设置为 true 时才会生效 | `Function` | — |
|  | 远程搜索方法显示后缀图标 | `boolean` | false |
| validate-event | 是否触发表单验证 | `boolean` | true |
| offset 2.8.8 | 下拉面板偏移量 | `number` | 12 |
| show-arrow 2.8.8 | 下拉菜单的内容是否有箭头 | `boolean` | true |
| placement | 下拉框出现的位置 | `enum` | bottom-start |
| fallback-placements 2.5.6 | dropdown 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | `array` | \['bottom-start', 'top-start', 'right', 'left'\] |
| collapse-tags-tooltip 2.3.0 | 当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此功能，`collapse-tags`的值必须为true | `boolean` | false |
| [tag-tooltip](#tag-tooltip) 2.13.3 | 折叠标签工具提示的配置对象。 要使用此项， `collapse-tags` 和 `collapse-tags-tooltip` 必须为 true | `object` | {} |
| max-collapse-tags 2.3.0 | 需要显示的 Tag 的最大数量。 只有当 `collapse-tags` 设置为 true 时才会生效。 | `number` | 1 |
| tag-type 2.5.0 | 标签类型 | `enum` | info |
| tag-effect 2.7.7 | 标签效果 | `enum` | light |
| aria-label a11y 2.5.0 | 等价于原生 input `aria-label` 属性 | `string` | — |
| empty-values 2.7.0 | 组件的空值配置， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `array` | — |
| value-on-clear 2.7.0 | 清空选项的值， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `string` / `number` / `boolean` / `Function` | — |
| popper-append-to-body deprecated | 是否将弹出框插入至 body 元素 当弹出框的位置出现问题时，你可以尝试将该属性设置为false。 |  |  |
| tabindex 2.9.0 | input 的 tabindex | `string` / `number` | — |

### props [​](#props)

| Attribute | 说明 | Type | Default |
| --- | --- | --- | --- |
| value | 指定选项的值为选项对象的某个属性值 | `string` | value |
| label | 指定节点标签为节点对象的某个属性值 | `string` | label |
| options | 指定选项的子选项为选项对象的某个属性值 | `string` | options |
| disabled | 指定选项的禁用为选项对象的某个属性值 | `string` | disabled |

### tag-tooltip 2.13.3 [​](#tag-tooltip)

备用机制

标签工具提示中的属性遵循此优先级顺序：

1.  在标签工具提示对象中明确定义的字段。
2.  从 el-select 继承的共享属性（例如 effect、popper-class、popper-style、teleported、append-to、popper-options）。
3.  底层 el-tooltip 组件的默认值。 这样，您就可以覆盖标签的特定工具提示行为，同时保持与默认的“选择”下拉菜单的一致性。

自定义容器位置

当将 Tooltip 添加到自定义容器时（通过 `append-to` 属性），应将容器配置为 `position: relative` 或 `position: absolute`，以确保准确定位。 此外，如果需要防止工具提示超出其边界，可以对容器应用 `overflow: hidden`。

| 属性 | 说明 | 类型 | Default |
| --- | --- | --- | --- |
| append-to | 指示 Tooltip 的内容将附加在哪一个网页元素上 | `CSSSelector` / `HTMLElement` | — |
| placement | Tooltip 组件出现的位置 | `enum` | bottom |
| fallback-placements | Tooltip 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | `array` | \['bottom', 'top', 'right', 'left'\] |
| effect | 文字提示（Tooltip）的主题，内置`dark`和`light`两种。 | `enum` / `string` | ::: |
| popper-class | 为 Tooltip 的 popper 添加自定义类名 | `string` | — |
| popper-style | 为 Tooltip 的 popper 添加自定义样式 | `string` / `object` | — |
| transition | Tooltip 所应用过渡动画的名称 | `string` | — |
| teleported | 是否使用 teleport。设置成 `true`则会被追加到 `append-to` 的位置 | `boolean` | — |
| popper-options | [popper.js](https://popper.js.org/docs/v2/) parameters | `object`refer to [popper.js](https://popper.js.org/docs/v2/) doc | — |
| show-after | 在触发后多久显示内容，单位毫秒 | `number` | — |
| hide-after | 关闭时的延迟 | `number` | — |
| auto-close | tooltip 出现后自动隐藏延时，单位毫秒 | `number` | — |
| offset | Tooltip 出现位置的偏移量 | `number` | — |

### 事件 [​](#事件)

| 名称 | 详情 | Type |
| --- | --- | --- |
| change | 当所选值更改时触发，参数是当前选中的值 | `Function` |
| visible-change | 当下拉菜单出现/消失时触发器, 当它出现时, 参数将是 `true`, 否则将是 `false` | `Function` |
| remove-tag | 当一个标签在多个模式下被移除时触发，参数将被移除标签值 | `Function` |
| clear | 可清空的单选模式下用户点击清空按钮时触发 | `Function` |
| blur | 当选择器的输入框失去焦点时触发 | `Function` |
| focus | 当选择器的输入框获得焦点时触发 | `Function` |
| end-reached 2.14.0 | 下拉滚动到结束时触发器 | `Function` |

### Slots [​](#slots)

| 名称 | 描述 | 类型 |
| --- | --- | --- |
| default | 自定义 Option 模板 | — |
| header 2.5.2 | 下拉列表顶部的内容 | — |
| footer 2.5.2 | 下拉列表底部的内容 | — |
| empty | 自定义当选项为空时的内容 | — |
| prefix | 输入框的前缀 | ::: |
| tag 2.5.0 | 作为 Select 组件的内容时，子标签 `data`、`selectDisabled` 和 `deleteTag` 是在版本 2.10.3 中新增的。 | `object` |
| loading 2.5.2 | select 组件自定义 loading内容 | ::: |
| label 2.7.4 | select 组件自定义标签内容 `index` 引入于2.11.2 | `object` |

### Exposes [​](#exposes)

| 名称 | Description | Type |
| --- | --- | --- |
| focus | 使选择器的输入框获取焦点 | `Function` |
| blur | 使选择器的输入框失去焦点，并隐藏下拉框 | `Function` |
| selectedLabel 2.8.5 | 获取当前选中的标签 | `object` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/select-v2) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/select-v2.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/select-v2.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/43257608?v=4&size=64)](https://github.com/Liao-js)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/27912232?v=4&size=64)](https://github.com/Fuphoenixes)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/166777320?v=4&size=64)](https://github.com/ixyzorg)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/27413795?v=4&size=64)](https://github.com/SpanManX)[![](https://avatars.githubusercontent.com/u/58826012?v=4&size=64)](https://github.com/stillgg)[![](https://avatars.githubusercontent.com/u/48341368?v=4&size=64)](https://github.com/HaceraI)[![](https://avatars.githubusercontent.com/u/132551120?v=4&size=64)](https://github.com/YiMo1)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)[![](https://avatars.githubusercontent.com/u/58846658?v=4&size=64)](https://github.com/JiuRanYa)[![](https://avatars.githubusercontent.com/u/26833520?v=4&size=64)](https://github.com/josonho)[![](https://avatars.githubusercontent.com/u/178066799?v=4&size=64)](https://github.com/Yeuvoir)[![](https://avatars.githubusercontent.com/u/37976544?v=4&size=64)](https://github.com/ALypovskyi)[![](https://avatars.githubusercontent.com/u/24487727?v=4&size=64)](https://github.com/LostElkByte)[![](https://avatars.githubusercontent.com/u/201188047?v=4&size=64)](https://github.com/YXY-cell)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/52928534?v=4&size=64)](https://github.com/alonely-boy)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/127940123?v=4&size=64)](https://github.com/baozjj)[![](https://avatars.githubusercontent.com/u/14144811?v=4&size=64)](https://github.com/cn-xufei)[![](https://avatars.githubusercontent.com/u/50254496?v=4&size=64)](https://github.com/LoTwT)[![](https://avatars.githubusercontent.com/u/35138018?v=4&size=64)](https://github.com/tuskermanshu)[![](https://avatars.githubusercontent.com/u/40554198?v=4&size=64)](https://github.com/WangYJEE)[![](https://avatars.githubusercontent.com/u/28584349?v=4&size=64)](https://github.com/wangcch)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/25458528?v=4&size=64)](https://github.com/weidehai)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/23378455?v=4&size=64)](https://github.com/Dreamcreative)[![](https://avatars.githubusercontent.com/u/81673017?v=4&size=64)](https://github.com/RSS1102)[![](https://avatars.githubusercontent.com/u/22659150?v=4&size=64)](https://github.com/ntnyq)[![](https://avatars.githubusercontent.com/u/8591261?v=4&size=64)](https://github.com/zeyongTsai)[![](https://avatars.githubusercontent.com/u/57179957?v=4&size=64)](https://github.com/yeonjulee1005)[![](https://avatars.githubusercontent.com/u/31885971?v=4&size=64)](https://github.com/wonderl17)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/33799081?v=4&size=64)](https://github.com/wuyadan)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/60056876?v=4&size=64)](https://github.com/LinZhanMing)[![](https://avatars.githubusercontent.com/u/13913084?v=4&size=64)](https://github.com/YornQiu)[![](https://avatars.githubusercontent.com/u/1183991?v=4&size=64)](https://github.com/calumk)[![](https://avatars.githubusercontent.com/u/19553651?v=4&size=64)](https://github.com/GUEThe)[![](https://avatars.githubusercontent.com/u/67454874?v=4&size=64)](https://github.com/nigiwen)[![](https://avatars.githubusercontent.com/u/69580637?v=4&size=64)](https://github.com/jevin98)[![](https://avatars.githubusercontent.com/u/26295849?v=4&size=64)](https://github.com/CeceWall)[![](https://avatars.githubusercontent.com/u/5701072?v=4&size=64)](https://github.com/Naeemo)[![](https://avatars.githubusercontent.com/u/16463481?v=4&size=64)](https://github.com/hellomrbigshot)[![](https://avatars.githubusercontent.com/u/61337085?v=4&size=64)](https://github.com/wizardAEI)[![](https://avatars.githubusercontent.com/u/5389932?v=4&size=64)](https://github.com/muuyao)[![](https://avatars.githubusercontent.com/u/73569598?v=4&size=64)](https://github.com/sechi747)[![](https://avatars.githubusercontent.com/u/12935577?v=4&size=64)](https://github.com/lshunran)[![](https://avatars.githubusercontent.com/u/73086438?v=4&size=64)](https://github.com/Cheerwhy)[![](https://avatars.githubusercontent.com/u/32354856?v=4&size=64)](https://github.com/baiwusanyu-c)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/1411614?v=4&size=64)](https://github.com/spx443812507)

[Select](https://element-plus.org/zh-CN/component/select)

[Slider 滑块](https://element-plus.org/zh-CN/component/slider)




---
## [form/slider] Slider 滑块
> 官方文档: https://element-plus.org/zh-CN/component/slider.html

---

# Slider 滑块 [​](#slider-滑块)

更新日志待解决

3

通过拖动滑块在一个固定区间内进行选择

## 基础用法 [​](#基础用法)

在拖动滑块时，显示当前值

通过设置绑定值自定义滑块的初始值

Default value

Customized initial value

Hide Tooltip

Format Tooltip

Disabled

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwic2xpZGVyLWRlbW8tYmxvY2tcIj5cbiAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5EZWZhdWx0IHZhbHVlPC9zcGFuPlxuICAgIDxlbC1zbGlkZXIgdi1tb2RlbD1cInZhbHVlMVwiIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwic2xpZGVyLWRlbW8tYmxvY2tcIj5cbiAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5DdXN0b21pemVkIGluaXRpYWwgdmFsdWU8L3NwYW4+XG4gICAgPGVsLXNsaWRlciB2LW1vZGVsPVwidmFsdWUyXCIgLz5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJzbGlkZXItZGVtby1ibG9ja1wiPlxuICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPkhpZGUgVG9vbHRpcDwvc3Bhbj5cbiAgICA8ZWwtc2xpZGVyIHYtbW9kZWw9XCJ2YWx1ZTNcIiA6c2hvdy10b29sdGlwPVwiZmFsc2VcIiAvPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cInNsaWRlci1kZW1vLWJsb2NrXCI+XG4gICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+Rm9ybWF0IFRvb2x0aXA8L3NwYW4+XG4gICAgPGVsLXNsaWRlciB2LW1vZGVsPVwidmFsdWU0XCIgOmZvcm1hdC10b29sdGlwPVwiZm9ybWF0VG9vbHRpcFwiIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwic2xpZGVyLWRlbW8tYmxvY2tcIj5cbiAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5EaXNhYmxlZDwvc3Bhbj5cbiAgICA8ZWwtc2xpZGVyIHYtbW9kZWw9XCJ2YWx1ZTVcIiBkaXNhYmxlZCAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZigwKVxuY29uc3QgdmFsdWUyID0gcmVmKDApXG5jb25zdCB2YWx1ZTMgPSByZWYoMClcbmNvbnN0IHZhbHVlNCA9IHJlZigwKVxuY29uc3QgdmFsdWU1ID0gcmVmKDApXG5cbmNvbnN0IGZvcm1hdFRvb2x0aXAgPSAodmFsOiBudW1iZXIpID0+IHtcbiAgcmV0dXJuIHZhbCAvIDEwMFxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uc2xpZGVyLWRlbW8tYmxvY2sge1xuICBtYXgtd2lkdGg6IDYwMHB4O1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xufVxuLnNsaWRlci1kZW1vLWJsb2NrIC5lbC1zbGlkZXIge1xuICBtYXJnaW4tdG9wOiAwO1xuICBtYXJnaW4tbGVmdDogMTJweDtcbn1cbi5zbGlkZXItZGVtby1ibG9jayAuZGVtb25zdHJhdGlvbiB7XG4gIGZvbnQtc2l6ZTogMTRweDtcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbiAgbGluZS1oZWlnaHQ6IDQ0cHg7XG4gIGZsZXg6IDE7XG4gIG92ZXJmbG93OiBoaWRkZW47XG4gIHRleHQtb3ZlcmZsb3c6IGVsbGlwc2lzO1xuICB3aGl0ZS1zcGFjZTogbm93cmFwO1xuICBtYXJnaW4tYm90dG9tOiAwO1xufVxuLnNsaWRlci1kZW1vLWJsb2NrIC5kZW1vbnN0cmF0aW9uICsgLmVsLXNsaWRlciB7XG4gIGZsZXg6IDAgMCA3MCU7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/slider/basic-usage.vue)_

vue

```
<template>
  <div class="slider-demo-block">
    <span class="demonstration">Default value</span>
    <el-slider v-model="value1" />
  </div>
  <div class="slider-demo-block">
    <span class="demonstration">Customized initial value</span>
    <el-slider v-model="value2" />
  </div>
  <div class="slider-demo-block">
    <span class="demonstration">Hide Tooltip</span>
    <el-slider v-model="value3" :show-tooltip="false" />
  </div>
  <div class="slider-demo-block">
    <span class="demonstration">Format Tooltip</span>
    <el-slider v-model="value4" :format-tooltip="formatTooltip" />
  </div>
  <div class="slider-demo-block">
    <span class="demonstration">Disabled</span>
    <el-slider v-model="value5" disabled />
  </div>
</template>

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

const value1 = ref(0)
const value2 = ref(0)
const value3 = ref(0)
const value4 = ref(0)
const value5 = ref(0)

const formatTooltip = (val: number) => {
  return val / 100
}
</script>

<style scoped>
.slider-demo-block {
  max-width: 600px;
  display: flex;
  align-items: center;
}
.slider-demo-block .el-slider {
  margin-top: 0;
  margin-left: 12px;
}
.slider-demo-block .demonstration {
  font-size: 14px;
  color: var(--el-text-color-secondary);
  line-height: 44px;
  flex: 1;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
  margin-bottom: 0;
}
.slider-demo-block .demonstration + .el-slider {
  flex: 0 0 70%;
}
</style>
```

隐藏源代码

## 离散值 [​](#离散值)

选项可以是离散的

改变`step`的值可以改变步长， 通过设置 `show-stops` 属性可以显示间断点

Breakpoints not displayed

Breakpoints displayed

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwic2xpZGVyLWRlbW8tYmxvY2tcIj5cbiAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5CcmVha3BvaW50cyBub3QgZGlzcGxheWVkPC9zcGFuPlxuICAgIDxlbC1zbGlkZXIgdi1tb2RlbD1cInZhbHVlMVwiIDpzdGVwPVwiMTBcIiAvPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cInNsaWRlci1kZW1vLWJsb2NrXCI+XG4gICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+QnJlYWtwb2ludHMgZGlzcGxheWVkPC9zcGFuPlxuICAgIDxlbC1zbGlkZXIgdi1tb2RlbD1cInZhbHVlMlwiIDpzdGVwPVwiMTBcIiBzaG93LXN0b3BzIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUxID0gcmVmKDApXG5jb25zdCB2YWx1ZTIgPSByZWYoMClcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLnNsaWRlci1kZW1vLWJsb2NrIHtcbiAgbWF4LXdpZHRoOiA2MDBweDtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbn1cbi5zbGlkZXItZGVtby1ibG9jayAuZWwtc2xpZGVyIHtcbiAgbWFyZ2luLXRvcDogMDtcbiAgbWFyZ2luLWxlZnQ6IDEycHg7XG59XG4uc2xpZGVyLWRlbW8tYmxvY2sgLmRlbW9uc3RyYXRpb24ge1xuICBmb250LXNpemU6IDE0cHg7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG4gIGxpbmUtaGVpZ2h0OiA0NHB4O1xuICBmbGV4OiAxO1xuICBvdmVyZmxvdzogaGlkZGVuO1xuICB0ZXh0LW92ZXJmbG93OiBlbGxpcHNpcztcbiAgd2hpdGUtc3BhY2U6IG5vd3JhcDtcbiAgbWFyZ2luLWJvdHRvbTogMDtcbn1cbi5zbGlkZXItZGVtby1ibG9jayAuZGVtb25zdHJhdGlvbiArIC5lbC1zbGlkZXIge1xuICBmbGV4OiAwIDAgNzAlO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/slider/discrete-values.vue)_

vue

```
<template>
  <div class="slider-demo-block">
    <span class="demonstration">Breakpoints not displayed</span>
    <el-slider v-model="value1" :step="10" />
  </div>
  <div class="slider-demo-block">
    <span class="demonstration">Breakpoints displayed</span>
    <el-slider v-model="value2" :step="10" show-stops />
  </div>
</template>

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

const value1 = ref(0)
const value2 = ref(0)
</script>

<style scoped>
.slider-demo-block {
  max-width: 600px;
  display: flex;
  align-items: center;
}
.slider-demo-block .el-slider {
  margin-top: 0;
  margin-left: 12px;
}
.slider-demo-block .demonstration {
  font-size: 14px;
  color: var(--el-text-color-secondary);
  line-height: 44px;
  flex: 1;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
  margin-bottom: 0;
}
.slider-demo-block .demonstration + .el-slider {
  flex: 0 0 70%;
}
</style>
```

隐藏源代码

## 带有输入框的滑块 [​](#带有输入框的滑块)

通过输入框输入来改变当前的值。

设置 `show-input` 属性会在右侧显示一个输入框

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwic2xpZGVyLWRlbW8tYmxvY2tcIj5cbiAgICA8ZWwtc2xpZGVyIHYtbW9kZWw9XCJ2YWx1ZVwiIHNob3ctaW5wdXQgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZigwKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uc2xpZGVyLWRlbW8tYmxvY2sge1xuICBtYXgtd2lkdGg6IDYwMHB4O1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xufVxuLnNsaWRlci1kZW1vLWJsb2NrIC5lbC1zbGlkZXIge1xuICBtYXJnaW4tdG9wOiAwO1xuICBtYXJnaW4tbGVmdDogMTJweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/slider/slider-with-input-box.vue)_

vue

```
<template>
  <div class="slider-demo-block">
    <el-slider v-model="value" show-input />
  </div>
</template>

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

const value = ref(0)
</script>

<style scoped>
.slider-demo-block {
  max-width: 600px;
  display: flex;
  align-items: center;
}
.slider-demo-block .el-slider {
  margin-top: 0;
  margin-left: 12px;
}
</style>
```

隐藏源代码

## 不同尺寸 [​](#不同尺寸)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwic2xpZGVyLWRlbW8tYmxvY2tcIj5cbiAgICA8ZWwtc2xpZGVyIHYtbW9kZWw9XCJ2YWx1ZVwiIHNob3ctaW5wdXQgc2l6ZT1cImxhcmdlXCIgLz5cbiAgICA8ZWwtc2xpZGVyIHYtbW9kZWw9XCJ2YWx1ZVwiIHNob3ctaW5wdXQgLz5cbiAgICA8ZWwtc2xpZGVyIHYtbW9kZWw9XCJ2YWx1ZVwiIHNob3ctaW5wdXQgc2l6ZT1cInNtYWxsXCIgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZigwKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uc2xpZGVyLWRlbW8tYmxvY2sge1xuICBtYXgtd2lkdGg6IDYwMHB4O1xufVxuXG4uZWwtc2xpZGVyIHtcbiAgbWFyZ2luLXRvcDogMjBweDtcbn1cblxuLmVsLXNsaWRlcjpmaXJzdC1jaGlsZCB7XG4gIG1hcmdpbi10b3A6IDA7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/slider/sizes.vue)_

vue

```
<template>
  <div class="slider-demo-block">
    <el-slider v-model="value" show-input size="large" />
    <el-slider v-model="value" show-input />
    <el-slider v-model="value" show-input size="small" />
  </div>
</template>

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

const value = ref(0)
</script>

<style scoped>
.slider-demo-block {
  max-width: 600px;
}

.el-slider {
  margin-top: 20px;
}

.el-slider:first-child {
  margin-top: 0;
}
</style>
```

隐藏源代码

## 位置 [​](#位置)

您可以自定义 Tooltip 提示的位置。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwic2xpZGVyLWRlbW8tYmxvY2tcIj5cbiAgICA8ZWwtc2xpZGVyIHYtbW9kZWw9XCJ2YWx1ZTFcIiAvPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cInNsaWRlci1kZW1vLWJsb2NrXCI+XG4gICAgPGVsLXNsaWRlciB2LW1vZGVsPVwidmFsdWUyXCIgcGxhY2VtZW50PVwiYm90dG9tXCIgLz5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJzbGlkZXItZGVtby1ibG9ja1wiPlxuICAgIDxlbC1zbGlkZXIgdi1tb2RlbD1cInZhbHVlM1wiIHBsYWNlbWVudD1cInJpZ2h0XCIgLz5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJzbGlkZXItZGVtby1ibG9ja1wiPlxuICAgIDxlbC1zbGlkZXIgdi1tb2RlbD1cInZhbHVlNFwiIHBsYWNlbWVudD1cImxlZnRcIiAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZigwKVxuY29uc3QgdmFsdWUyID0gcmVmKDApXG5jb25zdCB2YWx1ZTMgPSByZWYoMClcbmNvbnN0IHZhbHVlNCA9IHJlZigwKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uc2xpZGVyLWRlbW8tYmxvY2sge1xuICBtYXgtd2lkdGg6IDYwMHB4O1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xufVxuLnNsaWRlci1kZW1vLWJsb2NrIC5lbC1zbGlkZXIge1xuICBtYXJnaW4tdG9wOiAwO1xuICBtYXJnaW4tbGVmdDogMTJweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/slider/placement.vue)_

vue

```
<template>
  <div class="slider-demo-block">
    <el-slider v-model="value1" />
  </div>
  <div class="slider-demo-block">
    <el-slider v-model="value2" placement="bottom" />
  </div>
  <div class="slider-demo-block">
    <el-slider v-model="value3" placement="right" />
  </div>
  <div class="slider-demo-block">
    <el-slider v-model="value4" placement="left" />
  </div>
</template>

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

const value1 = ref(0)
const value2 = ref(0)
const value3 = ref(0)
const value4 = ref(0)
</script>

<style scoped>
.slider-demo-block {
  max-width: 600px;
  display: flex;
  align-items: center;
}
.slider-demo-block .el-slider {
  margin-top: 0;
  margin-left: 12px;
}
</style>
```

隐藏源代码

## 范围选择 [​](#范围选择)

你还可以选择一个范围值

配置 `range` 属性以激活范围选择模式，该属性的绑定值是一个数组，由最小边界值和最大边界值组成。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwic2xpZGVyLWRlbW8tYmxvY2tcIj5cbiAgICA8ZWwtc2xpZGVyIHYtbW9kZWw9XCJ2YWx1ZVwiIHJhbmdlIHNob3ctc3RvcHMgOm1heD1cIjEwXCIgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZihbNCwgOF0pXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5zbGlkZXItZGVtby1ibG9jayB7XG4gIG1heC13aWR0aDogNjAwcHg7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG59XG4uc2xpZGVyLWRlbW8tYmxvY2sgLmVsLXNsaWRlciB7XG4gIG1hcmdpbi10b3A6IDA7XG4gIG1hcmdpbi1sZWZ0OiAxMnB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/slider/range-selection.vue)_

vue

```
<template>
  <div class="slider-demo-block">
    <el-slider v-model="value" range show-stops :max="10" />
  </div>
</template>

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

const value = ref([4, 8])
</script>

<style scoped>
.slider-demo-block {
  max-width: 600px;
  display: flex;
  align-items: center;
}
.slider-demo-block .el-slider {
  margin-top: 0;
  margin-left: 12px;
}
</style>
```

隐藏源代码

## 垂直模式 [​](#垂直模式)

配置 `vertical` 属性为 `true` 启用垂直模式。 在垂直模式下，必须设置 `height` 属性。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwic2xpZGVyLWRlbW8tYmxvY2tcIj5cbiAgICA8ZWwtc2xpZGVyIHYtbW9kZWw9XCJ2YWx1ZVwiIHZlcnRpY2FsIGhlaWdodD1cIjIwMHB4XCIgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZigwKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uc2xpZGVyLWRlbW8tYmxvY2sge1xuICBtYXgtd2lkdGg6IDYwMHB4O1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xufVxuLnNsaWRlci1kZW1vLWJsb2NrIC5lbC1zbGlkZXIge1xuICBtYXJnaW4tdG9wOiAwO1xuICBtYXJnaW4tbGVmdDogMTJweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/slider/vertical-mode.vue)_

vue

```
<template>
  <div class="slider-demo-block">
    <el-slider v-model="value" vertical height="200px" />
  </div>
</template>

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

const value = ref(0)
</script>

<style scoped>
.slider-demo-block {
  max-width: 600px;
  display: flex;
  align-items: center;
}
.slider-demo-block .el-slider {
  margin-top: 0;
  margin-left: 12px;
}
</style>
```

隐藏源代码

## 显示标记 [​](#显示标记)

设置 `marks` 属性可以在滑块上显示标记。

0°C

8°C

37°C

50%

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwic2xpZGVyLWRlbW8tYmxvY2tcIj5cbiAgICA8ZWwtc2xpZGVyIHYtbW9kZWw9XCJ2YWx1ZVwiIHJhbmdlIDptYXJrcz1cIm1hcmtzXCIgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVhY3RpdmUsIHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBDU1NQcm9wZXJ0aWVzIH0gZnJvbSAndnVlJ1xuXG5pbnRlcmZhY2UgTWFyayB7XG4gIHN0eWxlOiBDU1NQcm9wZXJ0aWVzXG4gIGxhYmVsOiBzdHJpbmdcbn1cblxudHlwZSBNYXJrcyA9IFJlY29yZDxudW1iZXIsIE1hcmsgfCBzdHJpbmc+XG5cbmNvbnN0IHZhbHVlID0gcmVmKFszMCwgNjBdKVxuY29uc3QgbWFya3MgPSByZWFjdGl2ZTxNYXJrcz4oe1xuICAwOiAnMMKwQycsXG4gIDg6ICc4wrBDJyxcbiAgMzc6ICczN8KwQycsXG4gIDUwOiB7XG4gICAgc3R5bGU6IHtcbiAgICAgIGNvbG9yOiAnIzE5ODlGQScsXG4gICAgfSxcbiAgICBsYWJlbDogJzUwJScsXG4gIH0sXG59KVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uc2xpZGVyLWRlbW8tYmxvY2sge1xuICBtYXgtd2lkdGg6IDYwMHB4O1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xufVxuLnNsaWRlci1kZW1vLWJsb2NrIC5lbC1zbGlkZXIge1xuICBtYXJnaW4tdG9wOiAwO1xuICBtYXJnaW4tbGVmdDogMTJweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/slider/show-marks.vue)_

vue

```
<template>
  <div class="slider-demo-block">
    <el-slider v-model="value" range :marks="marks" />
  </div>
</template>

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

import type { CSSProperties } from 'vue'

interface Mark {
  style: CSSProperties
  label: string
}

type Marks = Record<number, Mark | string>

const value = ref([30, 60])
const marks = reactive<Marks>({
  0: '0°C',
  8: '8°C',
  37: '37°C',
  50: {
    style: {
      color: '#1989FA',
    },
    label: '50%',
  },
})
</script>

<style scoped>
.slider-demo-block {
  max-width: 600px;
  display: flex;
  align-items: center;
}
.slider-demo-block .el-slider {
  margin-top: 0;
  margin-left: 12px;
}
</style>
```

隐藏源代码

## 限制值 2.13.6 [​](#限制值)

设置 `step="mark"` 以将滑块值限制为刻度。

0°C

37°C

100°C

0cm

10cm

25cm

50cm

75cm

100cm

0

13

42

58

89

100

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwic2xpZGVyLWRlbW8tYmxvY2tcIj5cbiAgICA8ZWwtc2xpZGVyXG4gICAgICB2LW1vZGVsPVwidmFsdWUxXCJcbiAgICAgIHZlcnRpY2FsXG4gICAgICBoZWlnaHQ9XCIyMDBweFwiXG4gICAgICA6bWFya3M9XCJtYXJrczFcIlxuICAgICAgcGxhY2VtZW50PVwicmlnaHRcIlxuICAgICAgOmZvcm1hdC10b29sdGlwPVwiKHYpID0+IGAke3Z9wrBDYFwiXG4gICAgICBzdGVwPVwibWFya1wiXG4gICAgLz5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJzbGlkZXItZGVtby1ibG9ja1wiPlxuICAgIDxlbC1zbGlkZXIgdi1tb2RlbD1cInZhbHVlMlwiIDptYXJrcz1cIm1hcmtzMlwiIHN0ZXA9XCJtYXJrXCIgLz5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJzbGlkZXItZGVtby1ibG9ja1wiPlxuICAgIDxlbC1zbGlkZXIgdi1tb2RlbD1cInZhbHVlM1wiIHJhbmdlIDptYXJrcz1cIm1hcmtzM1wiIHN0ZXA9XCJtYXJrXCIgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmLCBzaGFsbG93UmVhY3RpdmUgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgQ1NTUHJvcGVydGllcyB9IGZyb20gJ3Z1ZSdcblxuaW50ZXJmYWNlIE1hcmsge1xuICBzdHlsZTogQ1NTUHJvcGVydGllc1xuICBsYWJlbDogc3RyaW5nXG59XG5cbnR5cGUgTWFya3MgPSBSZWNvcmQ8bnVtYmVyLCBNYXJrIHwgc3RyaW5nPlxuXG5jb25zdCB2YWx1ZTEgPSByZWYoMzcpXG5jb25zdCBtYXJrczEgPSBzaGFsbG93UmVhY3RpdmU8TWFya3M+KHtcbiAgMDogJzDCsEMnLFxuICAzNzogJzM3wrBDJyxcbiAgMTAwOiAnMTAwwrBDJyxcbn0pXG5cbmNvbnN0IHZhbHVlMiA9IHJlZig1MClcbmNvbnN0IG1hcmtzMiA9IHNoYWxsb3dSZWFjdGl2ZTxNYXJrcz4oe1xuICAwOiAnMGNtJyxcbiAgMTA6ICcxMGNtJyxcbiAgMjU6ICcyNWNtJyxcbiAgNTA6ICc1MGNtJyxcbiAgNzU6ICc3NWNtJyxcbiAgMTAwOiAnMTAwY20nLFxufSlcbmNvbnN0IHZhbHVlMyA9IHJlZihbMTMsIDQyXSlcbmNvbnN0IG1hcmtzMyA9IHNoYWxsb3dSZWFjdGl2ZTxNYXJrcz4oe1xuICAwOiAnMCcsXG4gIDEzOiAnMTMnLFxuICA0MjogJzQyJyxcbiAgNTg6ICc1OCcsXG4gIDg5OiAnODknLFxuICAxMDA6ICcxMDAnLFxufSlcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLnNsaWRlci1kZW1vLWJsb2NrIHtcbiAgbWF4LXdpZHRoOiA2MDBweDtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbn1cbi5zbGlkZXItZGVtby1ibG9jayAuZWwtc2xpZGVyIHtcbiAgbWFyZ2luLXRvcDogMDtcbiAgbWFyZ2luLWxlZnQ6IDEycHg7XG59XG4uc2xpZGVyLWRlbW8tYmxvY2sgKyAuc2xpZGVyLWRlbW8tYmxvY2sge1xuICBtYXJnaW4tdG9wOiAyMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/slider/restrict-value.vue)_

vue

```
<template>
  <div class="slider-demo-block">
    <el-slider
      v-model="value1"
      vertical
      height="200px"
      :marks="marks1"
      placement="right"
      :format-tooltip="(v) => `${v}°C`"
      step="mark"
    />
  </div>
  <div class="slider-demo-block">
    <el-slider v-model="value2" :marks="marks2" step="mark" />
  </div>
  <div class="slider-demo-block">
    <el-slider v-model="value3" range :marks="marks3" step="mark" />
  </div>
</template>

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

import type { CSSProperties } from 'vue'

interface Mark {
  style: CSSProperties
  label: string
}

type Marks = Record<number, Mark | string>

const value1 = ref(37)
const marks1 = shallowReactive<Marks>({
  0: '0°C',
  37: '37°C',
  100: '100°C',
})

const value2 = ref(50)
const marks2 = shallowReactive<Marks>({
  0: '0cm',
  10: '10cm',
  25: '25cm',
  50: '50cm',
  75: '75cm',
  100: '100cm',
})
const value3 = ref([13, 42])
const marks3 = shallowReactive<Marks>({
  0: '0',
  13: '13',
  42: '42',
  58: '58',
  89: '89',
  100: '100',
})
</script>

<style scoped>
.slider-demo-block {
  max-width: 600px;
  display: flex;
  align-items: center;
}
.slider-demo-block .el-slider {
  margin-top: 0;
  margin-left: 12px;
}
.slider-demo-block + .slider-demo-block {
  margin-top: 20px;
}
</style>
```

隐藏源代码

## API [​](#api)

### 属性 [​](#属性)

| 属性名 | 描述 | 类型 | 默认 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `number` / `array` | 0 |
| min | 最小值 | `number` | 0 |
| max | 最大值 | `number` | 100 |
| disabled | 是否禁用 | `boolean` | false |
| step | 步长，可以是数字或 `'mark'` 2.13.6，用于将值限制为刻度。 当设置为 `'mark'` 时，必须设置 `marks` 属性。 | `number` / `string` | 1 |
| show-input | 是否显示输入框，仅在 `range` 为 false 且 `step` 不为 `'mark'` 时生效。 | `boolean` | false |
| show-input-controls | 在显示输入框的情况下，是否显示输入框的控制按钮 | `boolean` | true |
| size | slider 包装器的大小，垂直模式下该属性不可用 | `enum` | default |
| input-size | 输入框的大小，如果设置了 `size` 属性，默认值自动取 `size` | `enum` | default |
| show-stops | 是否显示间断点 | `boolean` | false |
| show-tooltip | 是否显示提示信息 | `boolean` | true |
| format-tooltip | 格式化提示信息 | `Function` | — |
| range | 是否开启选择范围 | `boolean` | false |
| vertical | 垂直模式 | `boolean` | false |
| height | 滑块高度，垂直模式必填 | `string` | — |
| aria-label a11y 2.7.2 | 原生 `aria-label`属性 | `string` | — |
| range-start-label | 当 `range` 为true时，屏幕阅读器标签开始的标记 | `string` | — |
| range-end-label | 当 `range` 为true时，屏幕阅读器标签结尾的标记 | `string` | — |
| format-value-text | 显示屏幕阅读器的 `aria-valuenow` 属性的格式 | `Function` | — |
| tooltip-class | tooltip 的自定义类名 | `string` | — |
| placement | Tooltip 出现的位置 | `enum` | top |
| marks | 标记， key 的类型必须为 `number` 且取值在闭区间 `[min, max]` 内，每个标记可以单独设置样式 | `object` | — |
| validate-event | 输入时是否触发表单的校验 | `boolean` | true |
| persistent 2.9.5 | 当 slider 的 tooltip 处于非活动状态且 `persistent` 为 `false` 时，tooltip 将被销毁。 当 `show-tooltip` 为 `false` 时，`persistent` 将始终为 `false`。 | `boolean` | true |
| label a11y deprecated | 原生 `aria-label`属性 | `string` | — |

### 事件 [​](#事件)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 值改变时触发（使用鼠标拖曳时，只在松开鼠标后触发） | `Function` |
| input | 数据改变时触发（使用鼠标拖曳时，活动过程实时触发） | `Function` |

## 类型声明 [​](#类型声明)

显示类型声明

ts

```
type SliderMarks = Record<number, string | { style: CSSProperties; label: any }>
type Arrayable<T> = T | T[]
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/slider) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/slider.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/slider.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/65441198?v=4&size=64)](https://github.com/tyj-321)[![](https://avatars.githubusercontent.com/u/105651386?v=4&size=64)](https://github.com/heappynd)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/25742988?v=4&size=64)](https://github.com/Geekhyt)[![](https://avatars.githubusercontent.com/u/26035718?v=4&size=64)](https://github.com/SnowingFox)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/1411614?v=4&size=64)](https://github.com/spx443812507)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/90810762?v=4&size=64)](https://github.com/charles-lpd)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/36978416?v=4&size=64)](https://github.com/SimonaliaChen)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/33687038?v=4&size=64)](https://github.com/guozi9999)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/140705167?v=4&size=64)](https://github.com/zhongli-kira)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/24468747?v=4&size=64)](https://github.com/hddhyq)

[Virtualized Select 虚拟化选择器](https://element-plus.org/zh-CN/component/select-v2)

[Switch 开关](https://element-plus.org/zh-CN/component/switch)




---
## [form/switch] Switch 开关
> 官方文档: https://element-plus.org/zh-CN/component/switch.html

---

# Switch 开关 [​](#switch-开关)

更新日志待解决

6

表示两种相互对立的状态间的切换，多用于触发「开/关」。

## 基础用法 [​](#基础用法)

绑定 `v-model` 到一个 `Boolean` 类型的变量。 可以使用 `--el-switch-on-color` 属性与 `--el-switch-off-color` 属性来设置开关的背景色。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoIHYtbW9kZWw9XCJ2YWx1ZTFcIiAvPlxuICA8ZWwtc3dpdGNoXG4gICAgdi1tb2RlbD1cInZhbHVlMlwiXG4gICAgY2xhc3M9XCJtbC0yXCJcbiAgICBzdHlsZT1cIi0tZWwtc3dpdGNoLW9uLWNvbG9yOiAjMTNjZTY2OyAtLWVsLXN3aXRjaC1vZmYtY29sb3I6ICNmZjQ5NDlcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUxID0gcmVmKHRydWUpXG5jb25zdCB2YWx1ZTIgPSByZWYodHJ1ZSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/switch/basic.vue)_

vue

```
<template>
  <el-switch v-model="value1" />
  <el-switch
    v-model="value2"
    class="ml-2"
    style="--el-switch-on-color: #13ce66; --el-switch-off-color: #ff4949"
  />
</template>

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

const value1 = ref(true)
const value2 = ref(true)
</script>
```

隐藏源代码

## 尺寸 [​](#尺寸)

CloseOpen

CloseOpen

CloseOpen

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoXG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICBzaXplPVwibGFyZ2VcIlxuICAgIGFjdGl2ZS10ZXh0PVwiT3BlblwiXG4gICAgaW5hY3RpdmUtdGV4dD1cIkNsb3NlXCJcbiAgLz5cbiAgPGJyIC8+XG4gIDxlbC1zd2l0Y2ggdi1tb2RlbD1cInZhbHVlXCIgYWN0aXZlLXRleHQ9XCJPcGVuXCIgaW5hY3RpdmUtdGV4dD1cIkNsb3NlXCIgLz5cbiAgPGJyIC8+XG4gIDxlbC1zd2l0Y2hcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIHNpemU9XCJzbWFsbFwiXG4gICAgYWN0aXZlLXRleHQ9XCJPcGVuXCJcbiAgICBpbmFjdGl2ZS10ZXh0PVwiQ2xvc2VcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYodHJ1ZSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/switch/sizes.vue)_

vue

```
<template>
  <el-switch
    v-model="value"
    size="large"
    active-text="Open"
    inactive-text="Close"
  />
  <br />
  <el-switch v-model="value" active-text="Open" inactive-text="Close" />
  <br />
  <el-switch
    v-model="value"
    size="small"
    active-text="Open"
    inactive-text="Close"
  />
</template>

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

const value = ref(true)
</script>
```

隐藏源代码

## 文字描述 [​](#文字描述)

使用`active-text`属性与`inactive-text`属性来设置开关的文字描述。 使用 `inline-prompt` 属性来控制文本是否显示在点内。

使用`active-text`属性与`inactive-text`属性来设置开关的文字描述。

Pay by yearPay by month

Pay by yearPay by month

是

Y

超出省略

完整展示多个内容

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoXG4gICAgdi1tb2RlbD1cInZhbHVlMVwiXG4gICAgY2xhc3M9XCJtYi0yXCJcbiAgICBhY3RpdmUtdGV4dD1cIlBheSBieSBtb250aFwiXG4gICAgaW5hY3RpdmUtdGV4dD1cIlBheSBieSB5ZWFyXCJcbiAgLz5cbiAgPGJyIC8+XG4gIDxlbC1zd2l0Y2hcbiAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICBjbGFzcz1cIm1iLTJcIlxuICAgIHN0eWxlPVwiLS1lbC1zd2l0Y2gtb24tY29sb3I6ICMxM2NlNjY7IC0tZWwtc3dpdGNoLW9mZi1jb2xvcjogI2ZmNDk0OVwiXG4gICAgYWN0aXZlLXRleHQ9XCJQYXkgYnkgbW9udGhcIlxuICAgIGluYWN0aXZlLXRleHQ9XCJQYXkgYnkgeWVhclwiXG4gIC8+XG4gIDxiciAvPlxuICA8ZWwtc3dpdGNoXG4gICAgdi1tb2RlbD1cInZhbHVlM1wiXG4gICAgaW5saW5lLXByb21wdFxuICAgIGFjdGl2ZS10ZXh0PVwi5pivXCJcbiAgICBpbmFjdGl2ZS10ZXh0PVwi5ZCmXCJcbiAgLz5cbiAgPGVsLXN3aXRjaFxuICAgIHYtbW9kZWw9XCJ2YWx1ZTRcIlxuICAgIGNsYXNzPVwibWwtMlwiXG4gICAgaW5saW5lLXByb21wdFxuICAgIHN0eWxlPVwiLS1lbC1zd2l0Y2gtb24tY29sb3I6ICMxM2NlNjY7IC0tZWwtc3dpdGNoLW9mZi1jb2xvcjogI2ZmNDk0OVwiXG4gICAgYWN0aXZlLXRleHQ9XCJZXCJcbiAgICBpbmFjdGl2ZS10ZXh0PVwiTlwiXG4gIC8+XG4gIDxlbC1zd2l0Y2hcbiAgICB2LW1vZGVsPVwidmFsdWU2XCJcbiAgICBjbGFzcz1cIm1sLTJcIlxuICAgIHdpZHRoPVwiNjBcIlxuICAgIGlubGluZS1wcm9tcHRcbiAgICBhY3RpdmUtdGV4dD1cIui2heWHuuecgeeVpVwiXG4gICAgaW5hY3RpdmUtdGV4dD1cIui2heWHuuecgeeVpVwiXG4gIC8+XG4gIDxlbC1zd2l0Y2hcbiAgICB2LW1vZGVsPVwidmFsdWU1XCJcbiAgICBjbGFzcz1cIm1sLTJcIlxuICAgIGlubGluZS1wcm9tcHRcbiAgICBzdHlsZT1cIi0tZWwtc3dpdGNoLW9uLWNvbG9yOiAjMTNjZTY2OyAtLWVsLXN3aXRjaC1vZmYtY29sb3I6ICNmZjQ5NDlcIlxuICAgIGFjdGl2ZS10ZXh0PVwi5a6M5pW05bGV56S65aSa5Liq5YaF5a65XCJcbiAgICBpbmFjdGl2ZS10ZXh0PVwi5aSa5Liq5YaF5a65XCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZih0cnVlKVxuY29uc3QgdmFsdWUyID0gcmVmKHRydWUpXG5jb25zdCB2YWx1ZTMgPSByZWYodHJ1ZSlcbmNvbnN0IHZhbHVlNCA9IHJlZih0cnVlKVxuY29uc3QgdmFsdWU1ID0gcmVmKHRydWUpXG5jb25zdCB2YWx1ZTYgPSByZWYodHJ1ZSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/switch/text-description.vue)_

vue

```
<template>
  <el-switch
    v-model="value1"
    class="mb-2"
    active-text="Pay by month"
    inactive-text="Pay by year"
  />
  <br />
  <el-switch
    v-model="value2"
    class="mb-2"
    style="--el-switch-on-color: #13ce66; --el-switch-off-color: #ff4949"
    active-text="Pay by month"
    inactive-text="Pay by year"
  />
  <br />
  <el-switch
    v-model="value3"
    inline-prompt
    active-text="是"
    inactive-text="否"
  />
  <el-switch
    v-model="value4"
    class="ml-2"
    inline-prompt
    style="--el-switch-on-color: #13ce66; --el-switch-off-color: #ff4949"
    active-text="Y"
    inactive-text="N"
  />
  <el-switch
    v-model="value6"
    class="ml-2"
    width="60"
    inline-prompt
    active-text="超出省略"
    inactive-text="超出省略"
  />
  <el-switch
    v-model="value5"
    class="ml-2"
    inline-prompt
    style="--el-switch-on-color: #13ce66; --el-switch-off-color: #ff4949"
    active-text="完整展示多个内容"
    inactive-text="多个内容"
  />
</template>

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

const value1 = ref(true)
const value2 = ref(true)
const value3 = ref(true)
const value4 = ref(true)
const value5 = ref(true)
const value6 = ref(true)
</script>
```

隐藏源代码

## 显示自定义图标 [​](#显示自定义图标)

TIP

使用 `inactive-icon` 和 `active-icon` 属性来添加图标。 您可以传递组件名称的字符串（提前注册）或组件本身是一个 SVG Vue 组件。 Element Plus 提供了一套图标，你可以在 [icon](https://element-plus.org/zh-CN/component/icon) 找到它们。

使用 `inactive-icon` 和 `active-icon` 属性来添加图标。 使用 `inline-prompt` 属性来控制图标显示在点内。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoIHYtbW9kZWw9XCJ2YWx1ZTFcIiA6YWN0aXZlLWljb249XCJDaGVja1wiIDppbmFjdGl2ZS1pY29uPVwiQ2xvc2VcIiAvPlxuICA8YnIgLz5cbiAgPGVsLXN3aXRjaFxuICAgIHYtbW9kZWw9XCJ2YWx1ZTJcIlxuICAgIGNsYXNzPVwibXQtMlwiXG4gICAgc3R5bGU9XCJtYXJnaW4tbGVmdDogMjRweFwiXG4gICAgaW5saW5lLXByb21wdFxuICAgIDphY3RpdmUtaWNvbj1cIkNoZWNrXCJcbiAgICA6aW5hY3RpdmUtaWNvbj1cIkNsb3NlXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBDaGVjaywgQ2xvc2UgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgdmFsdWUxID0gcmVmKHRydWUpXG5jb25zdCB2YWx1ZTIgPSByZWYodHJ1ZSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/switch/custom-icons.vue)_

vue

```
<template>
  <el-switch v-model="value1" :active-icon="Check" :inactive-icon="Close" />
  <br />
  <el-switch
    v-model="value2"
    class="mt-2"
    style="margin-left: 24px"
    inline-prompt
    :active-icon="Check"
    :inactive-icon="Close"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Check, Close } from '@element-plus/icons-vue'

const value1 = ref(true)
const value2 = ref(true)
</script>
```

隐藏源代码

## 扩展的 value 类型 [​](#扩展的-value-类型)

你可以设置 `active-value` 和 `inactive-value` 属性， 它们接受 `Boolean`、`String` 或 `Number` 类型的值。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdG9vbHRpcCA6Y29udGVudD1cIidTd2l0Y2ggdmFsdWU6ICcgKyB2YWx1ZVwiIHBsYWNlbWVudD1cInRvcFwiPlxuICAgIDxlbC1zd2l0Y2hcbiAgICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgICBzdHlsZT1cIi0tZWwtc3dpdGNoLW9uLWNvbG9yOiAjMTNjZTY2OyAtLWVsLXN3aXRjaC1vZmYtY29sb3I6ICNmZjQ5NDlcIlxuICAgICAgYWN0aXZlLXZhbHVlPVwiMTAwXCJcbiAgICAgIGluYWN0aXZlLXZhbHVlPVwiMFwiXG4gICAgLz5cbiAgPC9lbC10b29sdGlwPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoJzEwMCcpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/switch/extended-value-types.vue)_

vue

```
<template>
  <el-tooltip :content="'Switch value: ' + value" placement="top">
    <el-switch
      v-model="value"
      style="--el-switch-on-color: #13ce66; --el-switch-off-color: #ff4949"
      active-value="100"
      inactive-value="0"
    />
  </el-tooltip>
</template>

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

const value = ref('100')
</script>
```

隐藏源代码

## 禁用状态 [​](#禁用状态)

设置`disabled`属性，接受一个`Boolean`，设置`true`即可禁用。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoIHYtbW9kZWw9XCJ2YWx1ZTFcIiBkaXNhYmxlZCAvPlxuICA8ZWwtc3dpdGNoIHYtbW9kZWw9XCJ2YWx1ZTJcIiBjbGFzcz1cIm1sLTJcIiAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUxID0gcmVmKHRydWUpXG5jb25zdCB2YWx1ZTIgPSByZWYodHJ1ZSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/switch/disabled.vue)_

vue

```
<template>
  <el-switch v-model="value1" disabled />
  <el-switch v-model="value2" class="ml-2" />
</template>

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

const value1 = ref(true)
const value2 = ref(true)
</script>
```

隐藏源代码

## 加载状态 [​](#加载状态)

设置`loading`属性，接受一个`Boolean`，设置`true`即加载中状态。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoIHYtbW9kZWw9XCJ2YWx1ZTFcIiBsb2FkaW5nIC8+XG4gIDxlbC1zd2l0Y2ggdi1tb2RlbD1cInZhbHVlMlwiIGxvYWRpbmcgY2xhc3M9XCJtbC0yXCIgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZih0cnVlKVxuY29uc3QgdmFsdWUyID0gcmVmKGZhbHNlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/switch/loading.vue)_

vue

```
<template>
  <el-switch v-model="value1" loading />
  <el-switch v-model="value2" loading class="ml-2" />
</template>

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

const value1 = ref(true)
const value2 = ref(false)
</script>
```

隐藏源代码

## 阻止切换 [​](#阻止切换)

设置`beforeChange`属性，若返回 false 或者返回 Promise 且被 reject，则停止切换。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoXG4gICAgdi1tb2RlbD1cInZhbHVlMVwiXG4gICAgOmxvYWRpbmc9XCJsb2FkaW5nMVwiXG4gICAgOmJlZm9yZS1jaGFuZ2U9XCJiZWZvcmVDaGFuZ2UxXCJcbiAgLz5cbiAgPGVsLXN3aXRjaFxuICAgIHYtbW9kZWw9XCJ2YWx1ZTJcIlxuICAgIGNsYXNzPVwibWwtMlwiXG4gICAgOmxvYWRpbmc9XCJsb2FkaW5nMlwiXG4gICAgOmJlZm9yZS1jaGFuZ2U9XCJiZWZvcmVDaGFuZ2UyXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBFbE1lc3NhZ2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZihmYWxzZSlcbmNvbnN0IHZhbHVlMiA9IHJlZihmYWxzZSlcbmNvbnN0IGxvYWRpbmcxID0gcmVmKGZhbHNlKVxuY29uc3QgbG9hZGluZzIgPSByZWYoZmFsc2UpXG5cbmNvbnN0IGJlZm9yZUNoYW5nZTEgPSAoKTogUHJvbWlzZTxib29sZWFuPiA9PiB7XG4gIGxvYWRpbmcxLnZhbHVlID0gdHJ1ZVxuICByZXR1cm4gbmV3IFByb21pc2UoKHJlc29sdmUpID0+IHtcbiAgICBzZXRUaW1lb3V0KCgpID0+IHtcbiAgICAgIGxvYWRpbmcxLnZhbHVlID0gZmFsc2VcbiAgICAgIEVsTWVzc2FnZS5zdWNjZXNzKCdTd2l0Y2ggc3VjY2VzcycpXG4gICAgICByZXR1cm4gcmVzb2x2ZSh0cnVlKVxuICAgIH0sIDEwMDApXG4gIH0pXG59XG5cbmNvbnN0IGJlZm9yZUNoYW5nZTIgPSAoKTogUHJvbWlzZTxib29sZWFuPiA9PiB7XG4gIGxvYWRpbmcyLnZhbHVlID0gdHJ1ZVxuICByZXR1cm4gbmV3IFByb21pc2UoKF8sIHJlamVjdCkgPT4ge1xuICAgIHNldFRpbWVvdXQoKCkgPT4ge1xuICAgICAgbG9hZGluZzIudmFsdWUgPSBmYWxzZVxuICAgICAgRWxNZXNzYWdlLmVycm9yKCdTd2l0Y2ggZmFpbGVkJylcbiAgICAgIHJldHVybiByZWplY3QobmV3IEVycm9yKCdFcnJvcicpKVxuICAgIH0sIDEwMDApXG4gIH0pXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/switch/prevent-switching.vue)_

vue

```
<template>
  <el-switch
    v-model="value1"
    :loading="loading1"
    :before-change="beforeChange1"
  />
  <el-switch
    v-model="value2"
    class="ml-2"
    :loading="loading2"
    :before-change="beforeChange2"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElMessage } from 'element-plus'

const value1 = ref(false)
const value2 = ref(false)
const loading1 = ref(false)
const loading2 = ref(false)

const beforeChange1 = (): Promise<boolean> => {
  loading1.value = true
  return new Promise((resolve) => {
    setTimeout(() => {
      loading1.value = false
      ElMessage.success('Switch success')
      return resolve(true)
    }, 1000)
  })
}

const beforeChange2 = (): Promise<boolean> => {
  loading2.value = true
  return new Promise((_, reject) => {
    setTimeout(() => {
      loading2.value = false
      ElMessage.error('Switch failed')
      return reject(new Error('Error'))
    }, 1000)
  })
}
</script>
```

隐藏源代码

## 自定义动作图标 2.3.9 [​](#自定义动作图标)

使用 `inactive-action-icon` 和 `active-action-icon` 属性来添加图标。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoXG4gICAgdi1tb2RlbD1cInZhbHVlMVwiXG4gICAgOmFjdGl2ZS1hY3Rpb24taWNvbj1cIlZpZXdcIlxuICAgIDppbmFjdGl2ZS1hY3Rpb24taWNvbj1cIkhpZGVcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEhpZGUsIFZpZXcgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgdmFsdWUxID0gcmVmKHRydWUpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/switch/custom-action-icon.vue)_

vue

```
<template>
  <el-switch
    v-model="value1"
    :active-action-icon="View"
    :inactive-action-icon="Hide"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Hide, View } from '@element-plus/icons-vue'

const value1 = ref(true)
</script>
```

隐藏源代码

## 自定义操作图标 2.4.4 [​](#自定义操作图标)

使用 `active-action` 和 `inactive-action` 属性来添加图标。

T

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoIHYtbW9kZWw9XCJ2YWx1ZTFcIj5cbiAgICA8dGVtcGxhdGUgI2FjdGl2ZS1hY3Rpb24+XG4gICAgICA8c3BhbiBjbGFzcz1cImN1c3RvbS1hY3RpdmUtYWN0aW9uXCI+VDwvc3Bhbj5cbiAgICA8L3RlbXBsYXRlPlxuICAgIDx0ZW1wbGF0ZSAjaW5hY3RpdmUtYWN0aW9uPlxuICAgICAgPHNwYW4gY2xhc3M9XCJjdXN0b20taW5hY3RpdmUtYWN0aW9uXCI+Rjwvc3Bhbj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLXN3aXRjaD5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZih0cnVlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/switch/custom-action-slot.vue)_

vue

```
<template>
  <el-switch v-model="value1">
    <template #active-action>
      <span class="custom-active-action">T</span>
    </template>
    <template #inactive-action>
      <span class="custom-inactive-action">F</span>
    </template>
  </el-switch>
</template>

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

const value1 = ref(true)
</script>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | Default |
| --- | --- | --- | --- |
| model-value / v-model | 绑定值，必须等于 `active-value` 或 `inactive-value`，默认为 `Boolean` 类型 | `boolean` / `string` / `number` | false |
| disabled | 是否禁用 | `boolean` | false |
| loading | 是否显示加载中 | `boolean` | false |
| size | switch 的大小 | `enum` | '' |
| width | switch 的宽度 | `number` / `string` | '' |
| inline-prompt | 无论图标或文本是否显示在点内，只会呈现文本的第一个字符 | `boolean` | false |
| active-icon | switch 状态为 `on` 时所显示图标，设置此项会忽略 `active-text` | `string` / `Component` | — |
| inactive-icon | switch 状态为 `off` 时所显示图标，设置此项会忽略 `inactive-text` | `string` / `Component` | — |
| active-action-icon 2.3.9 | `on`状态下显示的图标组件 | `string` / `Component` | — |
| inactive-action-icon 2.3.9 | `off`状态下显示的图标组件 | `string` / `Component` | — |
| active-text | switch 打开时的文字描述 | `string` | '' |
| inactive-text | switch 的状态为 `off` 时的文字描述 | `string` | '' |
| active-value | switch 状态为 `on` 时的值 | `boolean` / `string` / `number` | true |
| inactive-value | switch的状态为 `off` 时的值 | `boolean` / `string` / `number` | false |
| name | switch 对应的 name 属性 | `string` | '' |
| validate-event | 是否触发表单验证 | `boolean` | true |
| before-change | switch 状态改变前的钩子， 返回 `false` 或者返回 `Promise` 且被 reject 则停止切换 | `Function` | — |
| id | input 的 id | `string` | — |
| tabindex | input 的 tabindex | `string` / `number` | — |
| aria-label a11y 2.7.2 | 等价于原生 input `aria-label` 属性 | `string` | — |
| active-color deprecated | 当在 `on` 状态时的背景颜色(推荐使用 CSS var `--el-switch-on-color` ) | `string` | '' |
| inactive-color deprecated | `off` 状态时的背景颜色(推荐使用 CSS var `--el-switch-off-color` ) | `string` | '' |
| border-color deprecated | 开关的边框颜色 ( 推荐使用 CSS var `--el-switch-border-color` ) | `string` | '' |
| label a11y deprecated | 等价于原生 input `aria-label` 属性 | `string` | — |

### 事件 [​](#事件)

| 事件名 | 说明 | Type |
| --- | --- | --- |
| change | switch 状态发生变化时的回调函数 | `Function` |

### Switch Slots [​](#switch-slots)

| 名称 | 说明 |
| --- | --- |
| active-action 2.4.4 | 自定义 active 行为 |
| inactive-action 2.4.4 | 自定义 inactive 行为 |
| active 2.13.0 | 自定义 on 状态的内容 |
| inactive 2.13.0 | 自定义 off 状态的内容 |

### Exposes [​](#exposes)

| 方法 | 详情 | Type |
| --- | --- | --- |
| focus | 手动 focus 到 switch 组件 | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/switch) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/switch.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/switch.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/62818957?v=4&size=64)](https://github.com/ZacharyBear)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/74746021?v=4&size=64)](https://github.com/xing403)[![](https://avatars.githubusercontent.com/u/108655466?v=4&size=64)](https://github.com/Karolis-Stoncius)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/57086651?v=4&size=64)](https://github.com/Simon-He95)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/26833520?v=4&size=64)](https://github.com/josonho)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/22695767?v=4&size=64)](https://github.com/deepthan)[![](https://avatars.githubusercontent.com/u/36007710?v=4&size=64)](https://github.com/sleepyfive)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/23232655?v=4&size=64)](https://github.com/MBearo)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/57524062?v=4&size=64)](https://github.com/Ther-su)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)

[Slider 滑块](https://element-plus.org/zh-CN/component/slider)

[Time Picker 时间选择器](https://element-plus.org/zh-CN/component/time-picker)




---
## [form/time-picker] Time Picker 时间选择器
> 官方文档: https://element-plus.org/zh-CN/component/time-picker.html

---

# TimePicker 时间选择器 [​](#timepicker-时间选择器)

更新日志待解决

15

用于选择或输入日期

## 任意时间点 [​](#任意时间点)

可以选择任意时间

提供了两种交互方式：默认情况下通过鼠标滚轮进行选择，打开`arrow-control`属性则通过界面上的箭头进行选择。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZXhhbXBsZS1iYXNpY1wiPlxuICAgIDxlbC10aW1lLXBpY2tlciB2LW1vZGVsPVwidmFsdWUxXCIgcGxhY2Vob2xkZXI9XCJBcmJpdHJhcnkgdGltZVwiIC8+XG4gICAgPGVsLXRpbWUtcGlja2VyXG4gICAgICB2LW1vZGVsPVwidmFsdWUyXCJcbiAgICAgIGFycm93LWNvbnRyb2xcbiAgICAgIHBsYWNlaG9sZGVyPVwiQXJiaXRyYXJ5IHRpbWVcIlxuICAgIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUxID0gcmVmKClcbmNvbnN0IHZhbHVlMiA9IHJlZigpXG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLmV4YW1wbGUtYmFzaWMgLmVsLWRhdGUtZWRpdG9yIHtcbiAgbWFyZ2luOiA4cHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/time-picker/basic.vue)_

vue

```
<template>
  <div class="example-basic">
    <el-time-picker v-model="value1" placeholder="Arbitrary time" />
    <el-time-picker
      v-model="value2"
      arrow-control
      placeholder="Arbitrary time"
    />
  </div>
</template>

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

const value1 = ref()
const value2 = ref()
</script>

<style>
.example-basic .el-date-editor {
  margin: 8px;
}
</style>
```

隐藏源代码

## 限制时间选择范围 [​](#限制时间选择范围)

您也可以限制时间选择范围。

通过 `disabledHours`，`disabledMinutes` 和 `disabledSeconds` 限制可选时间范围。,

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZXhhbXBsZS1iYXNpY1wiPlxuICAgIDxlbC10aW1lLXBpY2tlclxuICAgICAgdi1tb2RlbD1cInZhbHVlMVwiXG4gICAgICA6ZGlzYWJsZWQtaG91cnM9XCJkaXNhYmxlZEhvdXJzXCJcbiAgICAgIDpkaXNhYmxlZC1taW51dGVzPVwiZGlzYWJsZWRNaW51dGVzXCJcbiAgICAgIDpkaXNhYmxlZC1zZWNvbmRzPVwiZGlzYWJsZWRTZWNvbmRzXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiQXJiaXRyYXJ5IHRpbWVcIlxuICAgIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUxID0gcmVmKG5ldyBEYXRlKDIwMTYsIDksIDEwLCAxOCwgMzApKVxuXG5jb25zdCBtYWtlUmFuZ2UgPSAoc3RhcnQ6IG51bWJlciwgZW5kOiBudW1iZXIpID0+IHtcbiAgY29uc3QgcmVzdWx0OiBudW1iZXJbXSA9IFtdXG4gIGZvciAobGV0IGkgPSBzdGFydDsgaSA8PSBlbmQ7IGkrKykge1xuICAgIHJlc3VsdC5wdXNoKGkpXG4gIH1cbiAgcmV0dXJuIHJlc3VsdFxufVxuY29uc3QgZGlzYWJsZWRIb3VycyA9ICgpID0+IHtcbiAgcmV0dXJuIG1ha2VSYW5nZSgwLCAxNikuY29uY2F0KG1ha2VSYW5nZSgxOSwgMjMpKVxufVxuY29uc3QgZGlzYWJsZWRNaW51dGVzID0gKGhvdXI6IG51bWJlcikgPT4ge1xuICBpZiAoaG91ciA9PT0gMTcpIHtcbiAgICByZXR1cm4gbWFrZVJhbmdlKDAsIDI5KVxuICB9XG4gIGlmIChob3VyID09PSAxOCkge1xuICAgIHJldHVybiBtYWtlUmFuZ2UoMzEsIDU5KVxuICB9XG4gIHJldHVybiBbXVxufVxuY29uc3QgZGlzYWJsZWRTZWNvbmRzID0gKGhvdXI6IG51bWJlciwgbWludXRlOiBudW1iZXIpID0+IHtcbiAgaWYgKGhvdXIgPT09IDE4ICYmIG1pbnV0ZSA9PT0gMzApIHtcbiAgICByZXR1cm4gbWFrZVJhbmdlKDEsIDU5KVxuICB9XG4gIHJldHVybiBbXVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5leGFtcGxlLWJhc2ljIC5lbC1kYXRlLWVkaXRvciB7XG4gIG1hcmdpbjogOHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/time-picker/basic-range.vue)_

vue

```
<template>
  <div class="example-basic">
    <el-time-picker
      v-model="value1"
      :disabled-hours="disabledHours"
      :disabled-minutes="disabledMinutes"
      :disabled-seconds="disabledSeconds"
      placeholder="Arbitrary time"
    />
  </div>
</template>

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

const value1 = ref(new Date(2016, 9, 10, 18, 30))

const makeRange = (start: number, end: number) => {
  const result: number[] = []
  for (let i = start; i <= end; i++) {
    result.push(i)
  }
  return result
}
const disabledHours = () => {
  return makeRange(0, 16).concat(makeRange(19, 23))
}
const disabledMinutes = (hour: number) => {
  if (hour === 17) {
    return makeRange(0, 29)
  }
  if (hour === 18) {
    return makeRange(31, 59)
  }
  return []
}
const disabledSeconds = (hour: number, minute: number) => {
  if (hour === 18 && minute === 30) {
    return makeRange(1, 59)
  }
  return []
}
</script>

<style>
.example-basic .el-date-editor {
  margin: 8px;
}
</style>
```

隐藏源代码

## 任意时间范围 [​](#任意时间范围)

可选择任意的时间范围

添加`is-range`属性即可选择时间范围。 同样支持 `arrow-control` 属性。

To

To

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1yYW5nZVwiPlxuICAgIDxlbC10aW1lLXBpY2tlclxuICAgICAgdi1tb2RlbD1cInZhbHVlMVwiXG4gICAgICBpcy1yYW5nZVxuICAgICAgcmFuZ2Utc2VwYXJhdG9yPVwiVG9cIlxuICAgICAgc3RhcnQtcGxhY2Vob2xkZXI9XCJTdGFydCB0aW1lXCJcbiAgICAgIGVuZC1wbGFjZWhvbGRlcj1cIkVuZCB0aW1lXCJcbiAgICAvPlxuICAgIDxlbC10aW1lLXBpY2tlclxuICAgICAgdi1tb2RlbD1cInZhbHVlMlwiXG4gICAgICBpcy1yYW5nZVxuICAgICAgYXJyb3ctY29udHJvbFxuICAgICAgcmFuZ2Utc2VwYXJhdG9yPVwiVG9cIlxuICAgICAgc3RhcnQtcGxhY2Vob2xkZXI9XCJTdGFydCB0aW1lXCJcbiAgICAgIGVuZC1wbGFjZWhvbGRlcj1cIkVuZCB0aW1lXCJcbiAgICAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlMSA9IHJlZjxbRGF0ZSwgRGF0ZV0+KFtcbiAgbmV3IERhdGUoMjAxNiwgOSwgMTAsIDgsIDQwKSxcbiAgbmV3IERhdGUoMjAxNiwgOSwgMTAsIDksIDQwKSxcbl0pXG5jb25zdCB2YWx1ZTIgPSByZWY8W0RhdGUsIERhdGVdPihbXG4gIG5ldyBEYXRlKDIwMTYsIDksIDEwLCA4LCA0MCksXG4gIG5ldyBEYXRlKDIwMTYsIDksIDEwLCA5LCA0MCksXG5dKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5kZW1vLXJhbmdlIC5lbC1kYXRlLWVkaXRvciB7XG4gIG1hcmdpbjogOHB4O1xufVxuXG4uZGVtby1yYW5nZSAuZWwtcmFuZ2Utc2VwYXJhdG9yIHtcbiAgYm94LXNpemluZzogY29udGVudC1ib3g7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/time-picker/range.vue)_

vue

```
<template>
  <div class="demo-range">
    <el-time-picker
      v-model="value1"
      is-range
      range-separator="To"
      start-placeholder="Start time"
      end-placeholder="End time"
    />
    <el-time-picker
      v-model="value2"
      is-range
      arrow-control
      range-separator="To"
      start-placeholder="Start time"
      end-placeholder="End time"
    />
  </div>
</template>

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

const value1 = ref<[Date, Date]>([
  new Date(2016, 9, 10, 8, 40),
  new Date(2016, 9, 10, 9, 40),
])
const value2 = ref<[Date, Date]>([
  new Date(2016, 9, 10, 8, 40),
  new Date(2016, 9, 10, 9, 40),
])
</script>

<style>
.demo-range .el-date-editor {
  margin: 8px;
}

.demo-range .el-range-separator {
  box-sizing: content-box;
}
</style>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| model-value / v-model | 绑定值，如果它是数组，长度应该是 2 | `number` / `string` / `object` | '' |
| readonly | 完全只读 | `boolean` | false |
| disabled | 禁用 | `boolean` | false |
| editable | 文本框可输入 | `boolean` | true |
| clearable | 是否显示清除按钮 | `boolean` | true |
| size | 输入框尺寸 | `enum` | — |
| placeholder | 非范围选择时的占位内容 | `string` | '' |
| start-placeholder | 范围选择时开始日期的占位内容 | `string` | — |
| end-placeholder | 范围选择时结束日期的占位内容 | `string` | — |
| is-range | 是否为时间范围选择 | `boolean` | false |
| arrow-control | 是否使用箭头进行时间选择 | `boolean` | false |
| popper-class | TimePicker 下拉框的类名 | `string` | '' |
| popper-style | 为 TimePicke 的下拉菜单自定义样式 | `string` / `object` | — |
| popper-options | 自定义 popper 选项，更多请参考 [popper.js](https://popper.js.org/docs/v2/) | `object` | {} |
| fallback-placements 2.8.4 | Tooltip 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | `array` | \['bottom', 'top', 'right', 'left'\] |
| placement 2.8.4 | 下拉框出现的位置 | `展示位置` | bottom |
| range-separator | 选择范围时的分隔符 | `string` | '-' |
| format | 显示在输入框中的格式 | `string` 参考 [日期格式](https://element-plus.org/zh-CN/component/date-picker#date-formats) | — |
| default-value | 可选，选择器打开时默认显示的时间 | `Date` / `array` | — |
| value-format | 可选，绑定值的格式。 不指定则绑定值为 Date 对象 | `string` 参考 [日期格式](https://element-plus.org/zh-CN/component/date-picker#date-formats) | — |
| id | 等价于原生 input `id` 属性 | `string` / `array` | — |
| name | 等价于原生 input `name` 属性 | `string` | '' |
| aria-label a11y 2.7.2 | 等价于原生 input `aria-label` 属性 | `string` | — |
| prefix-icon | 自定义前缀图标 | `string` / `Component` | Clock |
| clear-icon | 自定义清除图标 | `string` / `Component` | CircleClose |
| disabled-hours | 禁止选择部分小时选项 | `Function` | — |
| disabled-minutes | 禁止选择部分分钟选项 | `Function` | — |
| disabled-seconds | 禁止选择部分秒选项 | `Function` | — |
| teleported | 是否将 popover 的下拉列表镜像至 body 元素 | `boolean` | true |
| tabindex | 输入框的 tabindex | `string` / `number` | 0 |
| empty-values 2.7.0 | 组件的空值配置， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `array` | — |
| value-on-clear 2.7.0 | 清空选项的值， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `string` / `number` / `boolean` / `Function` | — |
| save-on-blur 2.13.4 | 当未选择任何值时，是否在获得焦点时自动填充为当前时间。 | `boolean` | true |
| label a11y deprecated | 等价于原生 input `aria-label` 属性 | `string` | — |

### 事件 [​](#事件)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 用户确认选定的值时触发 | `Function` |
| blur | 在组件 Input 失去焦点时触发 | `Function` |
| focus | 在组件 Input 获得焦点时触发 | `Function` |
| clear 2.7.7 | 可清空的模式下用户点击清空按钮时触发 | `Function` |
| visible-change | 当 TimePicker 的下拉列表出现/消失时触发 | `Function` |

### 暴露 [​](#暴露)

| 名称 | 说明 | Type |
| --- | --- | --- |
| focus | 使组件获取焦点 | `Function` |
| blur | 使组件失去焦点 | `Function` |
| handleOpen 2.2.16 | 打开时间选择器弹窗 | `Function` |
| handleClose 2.2.16 | 关闭时间选择器弹窗 | `Function` |

## Type Declarations [​](#type-declarations)

Show declarations

ts

```
type Placement =
  | 'top'
  | 'top-start'
  | 'top-end'
  | 'bottom'
  | 'bottom-start'
  | 'bottom-end'
  | 'left'
  | 'left-start'
  | 'left-end'
  | 'right'
  | 'right-start'
  | 'right-end'
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/time-picker) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/time-picker.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/time-picker.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/41944818?v=4&size=64)](https://github.com/CherishTheYouth)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/4075314?v=4&size=64)](https://github.com/Giwayume)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/147961575?v=4&size=64)](https://github.com/IceMooncake)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/24540820?v=4&size=64)](https://github.com/catanswer)[![](https://avatars.githubusercontent.com/u/126545033?v=4&size=64)](https://github.com/dhj-l)[![](https://avatars.githubusercontent.com/u/22286818?v=4&size=64)](https://github.com/fratzinger)[![](https://avatars.githubusercontent.com/u/19428473?v=4&size=64)](https://github.com/sheepzh)[![](https://avatars.githubusercontent.com/u/24290011?v=4&size=64)](https://github.com/xingyixiang)[![](https://avatars.githubusercontent.com/u/22910740?v=4&size=64)](https://github.com/StephenKe)[![](https://avatars.githubusercontent.com/u/35426360?v=4&size=64)](https://github.com/Jungzl)[![](https://avatars.githubusercontent.com/u/78132554?v=4&size=64)](https://github.com/momei-LJM)[![](https://avatars.githubusercontent.com/u/7897937?v=4&size=64)](https://github.com/myronliu347)[![](https://avatars.githubusercontent.com/u/81006731?v=4&size=64)](https://github.com/Panzer-Jack)[![](https://avatars.githubusercontent.com/u/57935341?v=4&size=64)](https://github.com/yuchenii)[![](https://avatars.githubusercontent.com/u/55378595?v=4&size=64)](https://github.com/evanryuu)[![](https://avatars.githubusercontent.com/u/86777555?v=4&size=64)](https://github.com/zhengsixsix)[![](https://avatars.githubusercontent.com/u/22659150?v=4&size=64)](https://github.com/ntnyq)[![](https://avatars.githubusercontent.com/u/24601590?v=4&size=64)](https://github.com/konata33)[![](https://avatars.githubusercontent.com/u/32354856?v=4&size=64)](https://github.com/baiwusanyu-c)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/169252980?v=4&size=64)](https://github.com/xiaochenchen-igg-com)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/49087880?v=4&size=64)](https://github.com/pany-ang)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/28811207?v=4&size=64)](https://github.com/fanhefeng)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/48023419?v=4&size=64)](https://github.com/uncledrewzhaopeng)[![](https://avatars.githubusercontent.com/u/25458528?v=4&size=64)](https://github.com/weidehai)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/19464247?v=4&size=64)](https://github.com/lily-elephant)[![](https://avatars.githubusercontent.com/u/22429236?v=4&size=64)](https://github.com/zongzi531)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)

[Switch 开关](https://element-plus.org/zh-CN/component/switch)

[Time Select 时间选择](https://element-plus.org/zh-CN/component/time-select)




---
## [form/time-select] Time Select 时间选择
> 官方文档: https://element-plus.org/zh-CN/component/time-select.html

---

# TimeSelect 时间选择 [​](#timeselect-时间选择)

更新日志待解决

3

用于选择或输入日期

可用时间范围是 00:00-23:59

## 固定时间点 [​](#固定时间点)

提供几个固定的时间点供用户选择

使用 `el-time-select` 标签，然后通过`start`、`end`和`step`指定起始时间，结束时间和步长。

Select time

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGltZS1zZWxlY3RcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICBzdGFydD1cIjA4OjMwXCJcbiAgICBzdGVwPVwiMDA6MTVcIlxuICAgIGVuZD1cIjE4OjMwXCJcbiAgICBwbGFjZWhvbGRlcj1cIlNlbGVjdCB0aW1lXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKCcnKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/time-select/basic.vue)_

vue

```
<template>
  <el-time-select
    v-model="value"
    style="width: 240px"
    start="08:30"
    step="00:15"
    end="18:30"
    placeholder="Select time"
  />
</template>

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

const value = ref('')
</script>
```

隐藏源代码

## 时间格式 [​](#时间格式)

使用 `format` 属性来控制时间格式 (小时以及分钟)。

在 [这里](https://day.js.org/docs/zh-CN/display/format) 查看 Day.js 支持的 format 参数。

WARNING

请一定要注意传入参数的大小写是否正确

Select time

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGltZS1zZWxlY3RcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICBzdGFydD1cIjAwOjAwXCJcbiAgICBzdGVwPVwiMDA6MzBcIlxuICAgIGVuZD1cIjIzOjU5XCJcbiAgICBwbGFjZWhvbGRlcj1cIlNlbGVjdCB0aW1lXCJcbiAgICBmb3JtYXQ9XCJoaDptbSBBXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKCcnKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/time-select/time-formats.vue)_

vue

```
<template>
  <el-time-select
    v-model="value"
    style="width: 240px"
    start="00:00"
    step="00:30"
    end="23:59"
    placeholder="Select time"
    format="hh:mm A"
  />
</template>

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

const value = ref('')
</script>
```

隐藏源代码

## 固定时间范围 [​](#固定时间范围)

如果先选中了开始（或结束）时间，则结束（或开始）时间的状态也将会随之改变。

Start time

End time

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby10aW1lLXJhbmdlIGZsZXggZmxleC13cmFwIGdhcC00XCI+XG4gICAgPGVsLXRpbWUtc2VsZWN0XG4gICAgICB2LW1vZGVsPVwic3RhcnRUaW1lXCJcbiAgICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICAgIDptYXgtdGltZT1cImVuZFRpbWVcIlxuICAgICAgcGxhY2Vob2xkZXI9XCJTdGFydCB0aW1lXCJcbiAgICAgIHN0YXJ0PVwiMDg6MzBcIlxuICAgICAgc3RlcD1cIjAwOjE1XCJcbiAgICAgIGVuZD1cIjE4OjMwXCJcbiAgICAvPlxuICAgIDxlbC10aW1lLXNlbGVjdFxuICAgICAgdi1tb2RlbD1cImVuZFRpbWVcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgOm1pbi10aW1lPVwic3RhcnRUaW1lXCJcbiAgICAgIHBsYWNlaG9sZGVyPVwiRW5kIHRpbWVcIlxuICAgICAgc3RhcnQ9XCIwODozMFwiXG4gICAgICBzdGVwPVwiMDA6MTVcIlxuICAgICAgZW5kPVwiMTg6MzBcIlxuICAgIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3Qgc3RhcnRUaW1lID0gcmVmKCcnKVxuY29uc3QgZW5kVGltZSA9IHJlZignJylcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/time-select/time-range.vue)_

vue

```
<template>
  <div class="demo-time-range flex flex-wrap gap-4">
    <el-time-select
      v-model="startTime"
      style="width: 240px"
      :max-time="endTime"
      placeholder="Start time"
      start="08:30"
      step="00:15"
      end="18:30"
    />
    <el-time-select
      v-model="endTime"
      style="width: 240px"
      :min-time="startTime"
      placeholder="End time"
      start="08:30"
      step="00:15"
      end="18:30"
    />
  </div>
</template>

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

const startTime = ref('')
const endTime = ref('')
</script>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `string` | — |
| disabled | 禁用状态 | `boolean` | false |
| editable | 文本框可输入 | `boolean` | true |
| clearable | 是否显示清除按钮 | `boolean` | true |
| include-end-time 2.9.3 | 是否在选项中包含`end` | `boolean` | false |
| size | 输入框尺寸 | `enum` | default |
| placeholder | 非范围选择时的占位内容 | `string` | — |
| name 2.13.3 | 原生属性 | `string` | — |
| effect | Tooltip 主题，内置了 `dark` / `light` 两种主题 | `string` / `enum` | light |
| prefix-icon | 自定义前缀图标 | `string` / `Component` | Clock |
| clear-icon | 自定义清除图标 | `string` / `Component` | CircleClose |
| start | 开始时间 | `string` | 09:00 |
| end | 结束时间 | `string` | 18:00 |
| step | 间隔时间 | `string` | 00:30 |
| min-time | 最早时间点，早于该时间的时间段将被禁用 | `string` | — |
| max-time | 最晚时间点，晚于该时间的时间段将被禁用 | `string` | — |
| format | 设置时间格式 | `string` see [formats](https://day.js.org/docs/en/display/format#list-of-all-available-formats) | HH:mm |
| empty-values 2.7.0 | 组件的空值配置， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `array` | — |
| value-on-clear 2.7.0 | 清空选项的值， [参考config-provider](https://element-plus.org/zh-CN/component/config-provider#empty-values-configurations) | `string` / `number` / `boolean` / `Function` | — |
| popper-class 2.11.4 | 为 TimeSelect 下拉面板设置自定义类名 | `string` | '' |
| popper-style 2.11.4 | 为 TimeSelect 下拉面板设置自定义样式 | `string` / `object` | — |

### Events [​](#events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 用户确认选定的值时触发 | `Function` |
| blur | 在组件 Input 失去焦点时触发 | `Function` |
| focus | 在组件 Input 获得焦点时触发 | `Function` |
| clear 2.7.7 | 可清空的单选模式下用户点击清空按钮时触发 | `Function` |

### Exposes [​](#exposes)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| focus | 使 input 获取焦点 | `Function` |
| blur | 使 input 失去焦点 | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/time-select) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/time-select.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/time-select.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/33687038?v=4&size=64)](https://github.com/guozi9999)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/19790546?v=4&size=64)](https://github.com/cleaverlove)[![](https://avatars.githubusercontent.com/u/47178158?v=4&size=64)](https://github.com/Aaron-zon)[![](https://avatars.githubusercontent.com/u/33000154?v=4&size=64)](https://github.com/l-x-f)[![](https://avatars.githubusercontent.com/u/58846658?v=4&size=64)](https://github.com/JiuRanYa)[![](https://avatars.githubusercontent.com/u/102006695?v=4&size=64)](https://github.com/cuongle-hdwebsoft)[![](https://avatars.githubusercontent.com/u/5559812?v=4&size=64)](https://github.com/metanas)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/17247526?v=4&size=64)](https://github.com/nabaonan)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)

[Time Picker 时间选择器](https://element-plus.org/zh-CN/component/time-picker)

[Transfer 穿梭框](https://element-plus.org/zh-CN/component/transfer)




---
## [form/transfer] Transfer 穿梭框
> 官方文档: https://element-plus.org/zh-CN/component/transfer.html

---

# Transfer 穿梭框 [​](#transfer-穿梭框)

更新日志待解决

4

## 基础用法 [​](#基础用法)

Transfer 的数据通过 `data` 属性传入。 数据需要是一个对象数组，每个对象有以下属性：`key` 为数据的唯一性标识，`label` 为显示文本，`disabled` 表示该项数据是否禁止被操作。 目标列表中的数据项会同步到绑定至 `v-model` 的变量，值为数据项的 `key` 所组成的数组。 当然，如果希望在初始状态时目标列表不为空，可以像本例一样为 `v-model` 绑定的变量赋予一个初始值。

List 10/15

Option 1Option 2Option 3Option 4Option 5Option 6Option 7Option 8Option 9Option 10Option 11Option 12Option 13Option 14Option 15

No data

List 20/0

No data

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJhbnNmZXIgdi1tb2RlbD1cInZhbHVlXCIgOmRhdGE9XCJkYXRhXCIgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmludGVyZmFjZSBPcHRpb24ge1xuICBrZXk6IG51bWJlclxuICBsYWJlbDogc3RyaW5nXG4gIGRpc2FibGVkOiBib29sZWFuXG59XG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9ICgpID0+IHtcbiAgY29uc3QgZGF0YTogT3B0aW9uW10gPSBbXVxuICBmb3IgKGxldCBpID0gMTsgaSA8PSAxNTsgaSsrKSB7XG4gICAgZGF0YS5wdXNoKHtcbiAgICAgIGtleTogaSxcbiAgICAgIGxhYmVsOiBgT3B0aW9uICR7aX1gLFxuICAgICAgZGlzYWJsZWQ6IGkgJSA0ID09PSAwLFxuICAgIH0pXG4gIH1cbiAgcmV0dXJuIGRhdGFcbn1cblxuY29uc3QgZGF0YSA9IHJlZjxPcHRpb25bXT4oZ2VuZXJhdGVEYXRhKCkpXG5jb25zdCB2YWx1ZSA9IHJlZihbXSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/transfer/basic.vue)_

vue

```
<template>
  <el-transfer v-model="value" :data="data" />
</template>

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

interface Option {
  key: number
  label: string
  disabled: boolean
}

const generateData = () => {
  const data: Option[] = []
  for (let i = 1; i <= 15; i++) {
    data.push({
      key: i,
      label: `Option ${i}`,
      disabled: i % 4 === 0,
    })
  }
  return data
}

const data = ref<Option[]>(generateData())
const value = ref([])
</script>
```

隐藏源代码

## 可搜索过滤 [​](#可搜索过滤)

在数据很多的情况下，可以对数据进行搜索和过滤。

设置 `filterable` 为 `true` 即可开启搜索模式。 默认情况下，若数据项的 `label` 属性包含搜索关键字，则会在搜索结果中显示。 你也可以使用 `filter-method` 定义自己的搜索逻辑。 `filter-method` 接收一个方法，当搜索关键字变化时，会将当前的关键字和每个数据项传给该方法。 若方法返回 `true`，则会在搜索结果中显示对应的数据项。

List 10/7

CaliforniaIllinoisMarylandTexasFloridaColoradoConnecticut

No data

List 20/0

No data

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJhbnNmZXJcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIGZpbHRlcmFibGVcbiAgICA6ZmlsdGVyLW1ldGhvZD1cImZpbHRlck1ldGhvZFwiXG4gICAgZmlsdGVyLXBsYWNlaG9sZGVyPVwiU3RhdGUgQWJicmV2aWF0aW9uc1wiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmludGVyZmFjZSBPcHRpb24ge1xuICBrZXk6IG51bWJlclxuICBsYWJlbDogc3RyaW5nXG4gIGluaXRpYWw6IHN0cmluZ1xufVxuXG5jb25zdCBnZW5lcmF0ZURhdGEgPSAoKSA9PiB7XG4gIGNvbnN0IGRhdGE6IE9wdGlvbltdID0gW11cbiAgY29uc3Qgc3RhdGVzID0gW1xuICAgICdDYWxpZm9ybmlhJyxcbiAgICAnSWxsaW5vaXMnLFxuICAgICdNYXJ5bGFuZCcsXG4gICAgJ1RleGFzJyxcbiAgICAnRmxvcmlkYScsXG4gICAgJ0NvbG9yYWRvJyxcbiAgICAnQ29ubmVjdGljdXQgJyxcbiAgXVxuICBjb25zdCBpbml0aWFscyA9IFsnQ0EnLCAnSUwnLCAnTUQnLCAnVFgnLCAnRkwnLCAnQ08nLCAnQ1QnXVxuICBzdGF0ZXMuZm9yRWFjaCgoY2l0eSwgaW5kZXgpID0+IHtcbiAgICBkYXRhLnB1c2goe1xuICAgICAgbGFiZWw6IGNpdHksXG4gICAgICBrZXk6IGluZGV4LFxuICAgICAgaW5pdGlhbDogaW5pdGlhbHNbaW5kZXhdLFxuICAgIH0pXG4gIH0pXG4gIHJldHVybiBkYXRhXG59XG5cbmNvbnN0IGRhdGEgPSByZWY8T3B0aW9uW10+KGdlbmVyYXRlRGF0YSgpKVxuY29uc3QgdmFsdWUgPSByZWYoW10pXG5cbmNvbnN0IGZpbHRlck1ldGhvZCA9IChxdWVyeSwgaXRlbSkgPT4ge1xuICByZXR1cm4gaXRlbS5pbml0aWFsLnRvTG93ZXJDYXNlKCkuaW5jbHVkZXMocXVlcnkudG9Mb3dlckNhc2UoKSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/transfer/filterable.vue)_

vue

```
<template>
  <el-transfer
    v-model="value"
    filterable
    :filter-method="filterMethod"
    filter-placeholder="State Abbreviations"
    :data="data"
  />
</template>

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

interface Option {
  key: number
  label: string
  initial: string
}

const generateData = () => {
  const data: Option[] = []
  const states = [
    'California',
    'Illinois',
    'Maryland',
    'Texas',
    'Florida',
    'Colorado',
    'Connecticut ',
  ]
  const initials = ['CA', 'IL', 'MD', 'TX', 'FL', 'CO', 'CT']
  states.forEach((city, index) => {
    data.push({
      label: city,
      key: index,
      initial: initials[index],
    })
  })
  return data
}

const data = ref<Option[]>(generateData())
const value = ref([])

const filterMethod = (query, item) => {
  return item.initial.toLowerCase().includes(query.toLowerCase())
}
</script>
```

隐藏源代码

## 自定义 [​](#自定义)

可以对列表标题文案、按钮文案、数据项的渲染函数、列表底部的勾选状态文案、列表底部的内容区等进行自定义。

可以使用 `titles`、`button-texts`、`render-content` 和 `format` 属性分别对列表标题文案、按钮文案、数据项的渲染函数和列表顶部的勾选状态文案进行自定义。 数据项的渲染还可以使用 `scoped-slot` 进行自定义。 对于列表底部的内容区，提供了两个具名 slot：`left-footer` 和 `right-footer`。 此外，如果希望某些数据项在初始化时就被勾选，可以使用 `left-default-checked` 和 `right-default-checked` 属性。 最后，本例还展示了 `change` 事件的用法。 注意，由于 JSFiddle 不支持 JSX 语法，故该示例无法在 JSFiddle 运行。 但是在实际的项目中，只要正确地配置了相关依赖，就可以正常运行。

Customize data items using render-content

Source2/14

Option 2Option 3Option 4Option 5Option 6Option 7Option 8Option 9Option 10Option 11Option 12Option 13Option 14Option 15

No data

Operation

To leftTo right

Target1/1

Option 1

No data

Operation

Customize data items using scoped slot

Source2/14

2 - Option 23 - Option 34 - Option 45 - Option 56 - Option 67 - Option 78 - Option 89 - Option 910 - Option 1011 - Option 1112 - Option 1213 - Option 1314 - Option 1415 - Option 15

No data

Operation

To leftTo right

Target1/1

1 - Option 1

No data

Operation

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8cCBzdHlsZT1cInRleHQtYWxpZ246IGNlbnRlcjsgbWFyZ2luOiAwIDAgMjBweFwiPlxuICAgIEN1c3RvbWl6ZSBkYXRhIGl0ZW1zIHVzaW5nIHJlbmRlci1jb250ZW50XG4gIDwvcD5cbiAgPGRpdiBzdHlsZT1cInRleHQtYWxpZ246IGNlbnRlclwiPlxuICAgIDxlbC10cmFuc2ZlclxuICAgICAgdi1tb2RlbD1cImxlZnRWYWx1ZVwiXG4gICAgICBzdHlsZT1cInRleHQtYWxpZ246IGxlZnQ7IGRpc3BsYXk6IGlubGluZS1ibG9ja1wiXG4gICAgICBmaWx0ZXJhYmxlXG4gICAgICA6bGVmdC1kZWZhdWx0LWNoZWNrZWQ9XCJbMiwgM11cIlxuICAgICAgOnJpZ2h0LWRlZmF1bHQtY2hlY2tlZD1cIlsxXVwiXG4gICAgICA6cmVuZGVyLWNvbnRlbnQ9XCJyZW5kZXJGdW5jXCJcbiAgICAgIDp0aXRsZXM9XCJbJ1NvdXJjZScsICdUYXJnZXQnXVwiXG4gICAgICA6YnV0dG9uLXRleHRzPVwiWydUbyBsZWZ0JywgJ1RvIHJpZ2h0J11cIlxuICAgICAgOmZvcm1hdD1cIntcbiAgICAgICAgbm9DaGVja2VkOiAnJHt0b3RhbH0nLFxuICAgICAgICBoYXNDaGVja2VkOiAnJHtjaGVja2VkfS8ke3RvdGFsfScsXG4gICAgICB9XCJcbiAgICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgICBAY2hhbmdlPVwiaGFuZGxlQ2hhbmdlXCJcbiAgICA+XG4gICAgICA8dGVtcGxhdGUgI2xlZnQtZm9vdGVyPlxuICAgICAgICA8ZWwtYnV0dG9uIGNsYXNzPVwidHJhbnNmZXItZm9vdGVyXCIgc2l6ZT1cInNtYWxsXCI+T3BlcmF0aW9uPC9lbC1idXR0b24+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgPHRlbXBsYXRlICNyaWdodC1mb290ZXI+XG4gICAgICAgIDxlbC1idXR0b24gY2xhc3M9XCJ0cmFuc2Zlci1mb290ZXJcIiBzaXplPVwic21hbGxcIj5PcGVyYXRpb248L2VsLWJ1dHRvbj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC10cmFuc2Zlcj5cbiAgICA8cCBzdHlsZT1cInRleHQtYWxpZ246IGNlbnRlcjsgbWFyZ2luOiA1MHB4IDAgMjBweFwiPlxuICAgICAgQ3VzdG9taXplIGRhdGEgaXRlbXMgdXNpbmcgc2NvcGVkIHNsb3RcbiAgICA8L3A+XG4gICAgPGRpdiBzdHlsZT1cInRleHQtYWxpZ246IGNlbnRlclwiPlxuICAgICAgPGVsLXRyYW5zZmVyXG4gICAgICAgIHYtbW9kZWw9XCJyaWdodFZhbHVlXCJcbiAgICAgICAgc3R5bGU9XCJ0ZXh0LWFsaWduOiBsZWZ0OyBkaXNwbGF5OiBpbmxpbmUtYmxvY2tcIlxuICAgICAgICBmaWx0ZXJhYmxlXG4gICAgICAgIDpsZWZ0LWRlZmF1bHQtY2hlY2tlZD1cIlsyLCAzXVwiXG4gICAgICAgIDpyaWdodC1kZWZhdWx0LWNoZWNrZWQ9XCJbMV1cIlxuICAgICAgICA6dGl0bGVzPVwiWydTb3VyY2UnLCAnVGFyZ2V0J11cIlxuICAgICAgICA6YnV0dG9uLXRleHRzPVwiWydUbyBsZWZ0JywgJ1RvIHJpZ2h0J11cIlxuICAgICAgICA6Zm9ybWF0PVwie1xuICAgICAgICAgIG5vQ2hlY2tlZDogJyR7dG90YWx9JyxcbiAgICAgICAgICBoYXNDaGVja2VkOiAnJHtjaGVja2VkfS8ke3RvdGFsfScsXG4gICAgICAgIH1cIlxuICAgICAgICA6ZGF0YT1cImRhdGFcIlxuICAgICAgICBAY2hhbmdlPVwiaGFuZGxlQ2hhbmdlXCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNkZWZhdWx0PVwieyBvcHRpb24gfVwiPlxuICAgICAgICAgIDxzcGFuPnt7IG9wdGlvbi5rZXkgfX0gLSB7eyBvcHRpb24ubGFiZWwgfX08L3NwYW4+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDx0ZW1wbGF0ZSAjbGVmdC1mb290ZXI+XG4gICAgICAgICAgPGVsLWJ1dHRvbiBjbGFzcz1cInRyYW5zZmVyLWZvb3RlclwiIHNpemU9XCJzbWFsbFwiPk9wZXJhdGlvbjwvZWwtYnV0dG9uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICA8dGVtcGxhdGUgI3JpZ2h0LWZvb3Rlcj5cbiAgICAgICAgICA8ZWwtYnV0dG9uIGNsYXNzPVwidHJhbnNmZXItZm9vdGVyXCIgc2l6ZT1cInNtYWxsXCI+T3BlcmF0aW9uPC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXRyYW5zZmVyPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHtcbiAgVHJhbnNmZXJEaXJlY3Rpb24sXG4gIFRyYW5zZmVyS2V5LFxuICByZW5kZXJDb250ZW50LFxufSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmludGVyZmFjZSBPcHRpb24ge1xuICBrZXk6IG51bWJlclxuICBsYWJlbDogc3RyaW5nXG4gIGRpc2FibGVkOiBib29sZWFuXG59XG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9ICgpOiBPcHRpb25bXSA9PiB7XG4gIGNvbnN0IGRhdGE6IE9wdGlvbltdID0gW11cbiAgZm9yIChsZXQgaSA9IDE7IGkgPD0gMTU7IGkrKykge1xuICAgIGRhdGEucHVzaCh7XG4gICAgICBrZXk6IGksXG4gICAgICBsYWJlbDogYE9wdGlvbiAke2l9YCxcbiAgICAgIGRpc2FibGVkOiBpICUgNCA9PT0gMCxcbiAgICB9KVxuICB9XG4gIHJldHVybiBkYXRhXG59XG5cbmNvbnN0IGRhdGEgPSByZWYoZ2VuZXJhdGVEYXRhKCkpXG5jb25zdCByaWdodFZhbHVlID0gcmVmKFsxXSlcbmNvbnN0IGxlZnRWYWx1ZSA9IHJlZihbMV0pXG5cbmNvbnN0IHJlbmRlckZ1bmM6IHJlbmRlckNvbnRlbnQgPSAoaCwgb3B0aW9uKSA9PiBoKCdzcGFuJywgbnVsbCwgb3B0aW9uLmxhYmVsKVxuXG5jb25zdCBoYW5kbGVDaGFuZ2UgPSAoXG4gIHZhbHVlOiBUcmFuc2ZlcktleVtdLFxuICBkaXJlY3Rpb246IFRyYW5zZmVyRGlyZWN0aW9uLFxuICBtb3ZlZEtleXM6IFRyYW5zZmVyS2V5W11cbikgPT4ge1xuICBjb25zb2xlLmxvZyh2YWx1ZSwgZGlyZWN0aW9uLCBtb3ZlZEtleXMpXG59XG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLnRyYW5zZmVyLWZvb3RlciB7XG4gIG1hcmdpbi1sZWZ0OiAxNXB4O1xuICBwYWRkaW5nOiA2cHggNXB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/transfer/customizable.vue)_

vue

```
<template>
  <p style="text-align: center; margin: 0 0 20px">
    Customize data items using render-content
  </p>
  <div style="text-align: center">
    <el-transfer
      v-model="leftValue"
      style="text-align: left; display: inline-block"
      filterable
      :left-default-checked="[2, 3]"
      :right-default-checked="[1]"
      :render-content="renderFunc"
      :titles="['Source', 'Target']"
      :button-texts="['To left', 'To right']"
      :format="{
        noChecked: '${total}',
        hasChecked: '${checked}/${total}',
      }"
      :data="data"
      @change="handleChange"
    >
      <template #left-footer>
        <el-button class="transfer-footer" size="small">Operation</el-button>
      </template>
      <template #right-footer>
        <el-button class="transfer-footer" size="small">Operation</el-button>
      </template>
    </el-transfer>
    <p style="text-align: center; margin: 50px 0 20px">
      Customize data items using scoped slot
    </p>
    <div style="text-align: center">
      <el-transfer
        v-model="rightValue"
        style="text-align: left; display: inline-block"
        filterable
        :left-default-checked="[2, 3]"
        :right-default-checked="[1]"
        :titles="['Source', 'Target']"
        :button-texts="['To left', 'To right']"
        :format="{
          noChecked: '${total}',
          hasChecked: '${checked}/${total}',
        }"
        :data="data"
        @change="handleChange"
      >
        <template #default="{ option }">
          <span>{{ option.key }} - {{ option.label }}</span>
        </template>
        <template #left-footer>
          <el-button class="transfer-footer" size="small">Operation</el-button>
        </template>
        <template #right-footer>
          <el-button class="transfer-footer" size="small">Operation</el-button>
        </template>
      </el-transfer>
    </div>
  </div>
</template>

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

import type {
  TransferDirection,
  TransferKey,
  renderContent,
} from 'element-plus'

interface Option {
  key: number
  label: string
  disabled: boolean
}

const generateData = (): Option[] => {
  const data: Option[] = []
  for (let i = 1; i <= 15; i++) {
    data.push({
      key: i,
      label: `Option ${i}`,
      disabled: i % 4 === 0,
    })
  }
  return data
}

const data = ref(generateData())
const rightValue = ref([1])
const leftValue = ref([1])

const renderFunc: renderContent = (h, option) => h('span', null, option.label)

const handleChange = (
  value: TransferKey[],
  direction: TransferDirection,
  movedKeys: TransferKey[]
) => {
  console.log(value, direction, movedKeys)
}
</script>

<style>
.transfer-footer {
  margin-left: 15px;
  padding: 6px 5px;
}
</style>
```

隐藏源代码

## 自定义空内容 2.9.0 [​](#自定义空内容)

您可以自定义列表为空或未找到筛选结果时显示的内容。

使用 `left-empty` 和 `right-empty` 插槽来自定义每个面板的空内容。

List 10/15

Option 1Option 2Option 3Option 4Option 5Option 6Option 7Option 8Option 9Option 10Option 11Option 12Option 13Option 14Option 15

No data

List 20/0

No data

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJhbnNmZXIgdi1tb2RlbD1cInZhbHVlXCIgOmRhdGE9XCJkYXRhXCI+XG4gICAgPHRlbXBsYXRlICNsZWZ0LWVtcHR5PlxuICAgICAgPGVsLWVtcHR5IDppbWFnZS1zaXplPVwiNjBcIiBkZXNjcmlwdGlvbj1cIk5vIGRhdGFcIiAvPlxuICAgIDwvdGVtcGxhdGU+XG4gICAgPHRlbXBsYXRlICNyaWdodC1lbXB0eT5cbiAgICAgIDxlbC1lbXB0eSA6aW1hZ2Utc2l6ZT1cIjYwXCIgZGVzY3JpcHRpb249XCJObyBkYXRhXCIgLz5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLXRyYW5zZmVyPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW50ZXJmYWNlIERhdGFJdGVtIHtcbiAga2V5OiBudW1iZXJcbiAgbGFiZWw6IHN0cmluZ1xuICBkaXNhYmxlZDogYm9vbGVhblxufVxuY29uc3QgZ2VuZXJhdGVEYXRhID0gKCk6IERhdGFJdGVtW10gPT4ge1xuICBjb25zdCBkYXRhOiBEYXRhSXRlbVtdID0gW11cbiAgZm9yIChsZXQgaSA9IDE7IGkgPD0gMTU7IGkrKykge1xuICAgIGRhdGEucHVzaCh7XG4gICAgICBrZXk6IGksXG4gICAgICBsYWJlbDogYE9wdGlvbiAke2l9YCxcbiAgICAgIGRpc2FibGVkOiBpICUgNCA9PT0gMCxcbiAgICB9KVxuICB9XG4gIHJldHVybiBkYXRhXG59XG5cbmNvbnN0IGRhdGEgPSByZWYoZ2VuZXJhdGVEYXRhKCkpXG5jb25zdCB2YWx1ZSA9IHJlZihbXSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/transfer/empty-content.vue)_

vue

```
<template>
  <el-transfer v-model="value" :data="data">
    <template #left-empty>
      <el-empty :image-size="60" description="No data" />
    </template>
    <template #right-empty>
      <el-empty :image-size="60" description="No data" />
    </template>
  </el-transfer>
</template>

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

interface DataItem {
  key: number
  label: string
  disabled: boolean
}
const generateData = (): DataItem[] => {
  const data: DataItem[] = []
  for (let i = 1; i <= 15; i++) {
    data.push({
      key: i,
      label: `Option ${i}`,
      disabled: i % 4 === 0,
    })
  }
  return data
}

const data = ref(generateData())
const value = ref([])
</script>
```

隐藏源代码

## 数据项属性别名 [​](#数据项属性别名)

默认情况下，Transfer 仅能识别数据项中的 `key`、`label` 和 `disabled` 字段。 如果你的数据的字段名不同，可以使用 `props` 属性为它们设置别名。

本例中的数据源没有 `key` 和 `label` 字段，在功能上与它们相同的字段名为 `value` 和 `desc`。 因此可以使用`props` 属性为 `key` 和 `label` 设置别名。

List 10/15

Option 1Option 2Option 3Option 4Option 5Option 6Option 7Option 8Option 9Option 10Option 11Option 12Option 13Option 14Option 15

No data

List 20/0

No data

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJhbnNmZXJcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIDpwcm9wcz1cIntcbiAgICAgIGtleTogJ3ZhbHVlJyxcbiAgICAgIGxhYmVsOiAnZGVzYycsXG4gICAgfVwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmludGVyZmFjZSBPcHRpb24ge1xuICB2YWx1ZTogbnVtYmVyXG4gIGRlc2M6IHN0cmluZ1xuICBkaXNhYmxlZDogYm9vbGVhblxufVxuXG5jb25zdCBnZW5lcmF0ZURhdGEgPSAoKSA9PiB7XG4gIGNvbnN0IGRhdGE6IE9wdGlvbltdID0gW11cbiAgZm9yIChsZXQgaSA9IDE7IGkgPD0gMTU7IGkrKykge1xuICAgIGRhdGEucHVzaCh7XG4gICAgICB2YWx1ZTogaSxcbiAgICAgIGRlc2M6IGBPcHRpb24gJHtpfWAsXG4gICAgICBkaXNhYmxlZDogaSAlIDQgPT09IDAsXG4gICAgfSlcbiAgfVxuICByZXR1cm4gZGF0YVxufVxuXG5jb25zdCBkYXRhID0gcmVmPE9wdGlvbltdPihnZW5lcmF0ZURhdGEoKSlcbmNvbnN0IHZhbHVlID0gcmVmKFtdKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/transfer/prop-alias.vue)_

vue

```
<template>
  <el-transfer
    v-model="value"
    :props="{
      key: 'value',
      label: 'desc',
    }"
    :data="data"
  />
</template>

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

interface Option {
  value: number
  desc: string
  disabled: boolean
}

const generateData = () => {
  const data: Option[] = []
  for (let i = 1; i <= 15; i++) {
    data.push({
      value: i,
      desc: `Option ${i}`,
      disabled: i % 4 === 0,
    })
  }
  return data
}

const data = ref<Option[]>(generateData())
const value = ref([])
</script>
```

隐藏源代码

## Transfer API [​](#transfer-api)

### Transfer Attributes [​](#transfer-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `array` | \[\] |
| data | Transfer 的数据源 | `array` | \[\] |
| filterable | 是否可搜索 | `boolean` | false |
| filter-placeholder | 搜索框占位符 | `string` | — |
| filter-method | 自定义搜索方法 | `Function` | — |
| target-order | 右侧列表元素的排序策略： 若为 `original`，则保持与数据源相同的顺序； 若为 `push`，则新加入的元素排在最后； 若为 `unshift`，则新加入的元素排在最前 | `enum` | original |
| titles | 自定义列表标题 | `array` | \[\] |
| button-texts | 自定义按钮文案 | `array` | \[\] |
| render-content | 自定义数据项渲染函数 | `object` | — |
| format | 列表顶部勾选状态文案 | `object` | {} |
| [props](#type-declarations) | 数据源的字段别名 | `object` | — |
| left-default-checked | 初始状态下左侧列表的已勾选项的 key 数组 | `array` | \[\] |
| right-default-checked | 初始状态下右侧列表的已勾选项的 key 数组 | `array` | \[\] |
| validate-event | 是否触发表单验证 | `boolean` | true |

### Transfer Events [​](#transfer-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 右侧列表元素变化时触发 | `Function` |
| left-check-change | 左侧列表元素被用户选中 / 取消选中时触发 | `Function` |
| right-check-change | 右侧列表元素被用户选中 / 取消选中时触发 | `Function` |

### Transfer Slots [​](#transfer-slots)

| 插槽名 | 说明 | 类型 |
| --- | --- | --- |
| default | 自定义数据项的内容， | `object` |
| left-footer | 左侧列表底部的内容 | — |
| right-footer | 右侧列表底部的内容 | — |
| left-empty 2.9.0 | 左侧面板为空或没有数据符合筛选条件时的内容 | — |
| right-empty 2.9.0 | 右侧面板为空或没有数据符合筛选条件时的内容 | — |

### Transfer Exposes [​](#transfer-exposes)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| clearQuery | 清空某个面板的搜索关键词 | `Function` |
| leftPanel | 左侧面板 ref | `object` |
| rightPanel | 右侧面板 ref | `object` |

## Transfer Panel API [​](#transfer-panel-api)

### Transfer Panel Exposes [​](#transfer-panel-exposes)

| 名称 | 描述 | Type |
| --- | --- | --- |
| query | 过滤关键词 | `string` |

## Type Declarations [​](#type-declarations)

显示类型声明

ts

```
import type { h as H, VNode } from 'vue'

type TransferKey = string | number

type TransferDirection = 'left' | 'right'

type TransferDataItem = Record<string, any>

type renderContent<T extends TransferDataItem = TransferDataItem> = (
  h: typeof H,
  option: T
) => VNode | VNode[]

interface TransferFormat {
  noChecked?: string
  hasChecked?: string
}

interface TransferPropsAlias {
  label?: string
  key?: string
  disabled?: string
}
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/transfer) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/transfer.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/transfer.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/50254496?v=4&size=64)](https://github.com/LoTwT)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/22429236?v=4&size=64)](https://github.com/zongzi531)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/54931083?v=4&size=64)](https://github.com/wjp980108)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/80675236?v=4&size=64)](https://github.com/evan2306)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/134276765?v=4&size=64)](https://github.com/zwgwf)[![](https://avatars.githubusercontent.com/u/19986739?v=4&size=64)](https://github.com/wjw-gavin)[![](https://avatars.githubusercontent.com/u/2755933?v=4&size=64)](https://github.com/BiosSun)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/54823984?v=4&size=64)](https://github.com/gezhiheng)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)

[Time Select 时间选择](https://element-plus.org/zh-CN/component/time-select)

[TreeSelect 树形选择](https://element-plus.org/zh-CN/component/tree-select)




---
## [form/tree-select] TreeSelect 树形选择
> 官方文档: https://element-plus.org/zh-CN/component/tree-select.html

---

# TreeSelect 树形选择 [​](#treeselect-树形选择)

更新日志待解决

22

含有下拉菜单的树形选择器，结合了 `el-tree` 和 `el-select` 两个组件的功能。

## 基础用法 [​](#基础用法)

树状选择器

Select

show checkbox:

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS1zZWxlY3RcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgOnJlbmRlci1hZnRlci1leHBhbmQ9XCJmYWxzZVwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAvPlxuICA8ZWwtZGl2aWRlciAvPlxuICBzaG93IGNoZWNrYm94OlxuICA8ZWwtdHJlZS1zZWxlY3RcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgOnJlbmRlci1hZnRlci1leHBhbmQ9XCJmYWxzZVwiXG4gICAgc2hvdy1jaGVja2JveFxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKClcblxuY29uc3QgZGF0YSA9IFtcbiAge1xuICAgIHZhbHVlOiAnMScsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICcxLTEnLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAxLTEnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnMS0xLTEnLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAxLTEtMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnMicsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMicsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICcyLTEnLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAyLTEnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnMi0xLTEnLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAyLTEtMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnMi0yJyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0yJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJzItMi0xJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMi0yLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJzMnLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDMnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnMy0xJyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJzMtMS0xJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMy0xLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJzMtMicsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDMtMicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICczLTItMScsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMi0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-select/basic.vue)_

vue

```
<template>
  <el-tree-select
    v-model="value"
    :data="data"
    :render-after-expand="false"
    style="width: 240px"
  />
  <el-divider />
  show checkbox:
  <el-tree-select
    v-model="value"
    :data="data"
    :render-after-expand="false"
    show-checkbox
    style="width: 240px"
  />
</template>

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

const value = ref()

const data = [
  {
    value: '1',
    label: 'Level one 1',
    children: [
      {
        value: '1-1',
        label: 'Level two 1-1',
        children: [
          {
            value: '1-1-1',
            label: 'Level three 1-1-1',
          },
        ],
      },
    ],
  },
  {
    value: '2',
    label: 'Level one 2',
    children: [
      {
        value: '2-1',
        label: 'Level two 2-1',
        children: [
          {
            value: '2-1-1',
            label: 'Level three 2-1-1',
          },
        ],
      },
      {
        value: '2-2',
        label: 'Level two 2-2',
        children: [
          {
            value: '2-2-1',
            label: 'Level three 2-2-1',
          },
        ],
      },
    ],
  },
  {
    value: '3',
    label: 'Level one 3',
    children: [
      {
        value: '3-1',
        label: 'Level two 3-1',
        children: [
          {
            value: '3-1-1',
            label: 'Level three 3-1-1',
          },
        ],
      },
      {
        value: '3-2',
        label: 'Level two 3-2',
        children: [
          {
            value: '3-2-1',
            label: 'Level three 3-2-1',
          },
        ],
      },
    ],
  },
]
</script>
```

隐藏源代码

## 选择任意级别 [​](#选择任意级别)

当属性 `check-strictly=true` 时，任何节点都可以被选择，否则只有子节点可被选择。

TIP

当使用 `show-checkbox`时，由于 `check-on-click-node` 默认值是 false，这时候只能通过 checkbox 来选中，当然您也可以将其设置成 true，这样点击整个 node 都可以用来完成选择

Select

show checkbox:

Select

show checkbox with \`check-on-click-node\`:

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS1zZWxlY3RcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgY2hlY2stc3RyaWN0bHlcbiAgICA6cmVuZGVyLWFmdGVyLWV4cGFuZD1cImZhbHNlXCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gIC8+XG4gIDxlbC1kaXZpZGVyIC8+XG4gIHNob3cgY2hlY2tib3g6XG4gIDxlbC10cmVlLXNlbGVjdFxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICBjaGVjay1zdHJpY3RseVxuICAgIDpyZW5kZXItYWZ0ZXItZXhwYW5kPVwiZmFsc2VcIlxuICAgIHNob3ctY2hlY2tib3hcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gIC8+XG4gIDxlbC1kaXZpZGVyIC8+XG4gIHNob3cgY2hlY2tib3ggd2l0aCBgY2hlY2stb24tY2xpY2stbm9kZWA6XG4gIDxlbC10cmVlLXNlbGVjdFxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICBjaGVjay1zdHJpY3RseVxuICAgIDpyZW5kZXItYWZ0ZXItZXhwYW5kPVwiZmFsc2VcIlxuICAgIHNob3ctY2hlY2tib3hcbiAgICBjaGVjay1vbi1jbGljay1ub2RlXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoKVxuXG5jb25zdCBkYXRhID0gW1xuICB7XG4gICAgdmFsdWU6ICcxJyxcbiAgICBsYWJlbDogJ0xldmVsIG9uZSAxJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogJzEtMScsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDEtMScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICcxLTEtMScsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDEtMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICcyJyxcbiAgICBsYWJlbDogJ0xldmVsIG9uZSAyJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogJzItMScsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDItMScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICcyLTEtMScsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDItMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICcyLTInLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAyLTInLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnMi0yLTEnLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAyLTItMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnMycsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMycsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICczLTEnLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAzLTEnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnMy0xLTEnLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAzLTEtMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnMy0yJyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0yJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJzMtMi0xJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMy0yLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-select/check-strictly.vue)_

vue

```
<template>
  <el-tree-select
    v-model="value"
    :data="data"
    check-strictly
    :render-after-expand="false"
    style="width: 240px"
  />
  <el-divider />
  show checkbox:
  <el-tree-select
    v-model="value"
    :data="data"
    check-strictly
    :render-after-expand="false"
    show-checkbox
    style="width: 240px"
  />
  <el-divider />
  show checkbox with `check-on-click-node`:
  <el-tree-select
    v-model="value"
    :data="data"
    check-strictly
    :render-after-expand="false"
    show-checkbox
    check-on-click-node
    style="width: 240px"
  />
</template>

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

const value = ref()

const data = [
  {
    value: '1',
    label: 'Level one 1',
    children: [
      {
        value: '1-1',
        label: 'Level two 1-1',
        children: [
          {
            value: '1-1-1',
            label: 'Level three 1-1-1',
          },
        ],
      },
    ],
  },
  {
    value: '2',
    label: 'Level one 2',
    children: [
      {
        value: '2-1',
        label: 'Level two 2-1',
        children: [
          {
            value: '2-1-1',
            label: 'Level three 2-1-1',
          },
        ],
      },
      {
        value: '2-2',
        label: 'Level two 2-2',
        children: [
          {
            value: '2-2-1',
            label: 'Level three 2-2-1',
          },
        ],
      },
    ],
  },
  {
    value: '3',
    label: 'Level one 3',
    children: [
      {
        value: '3-1',
        label: 'Level two 3-1',
        children: [
          {
            value: '3-1-1',
            label: 'Level three 3-1-1',
          },
        ],
      },
      {
        value: '3-2',
        label: 'Level two 3-2',
        children: [
          {
            value: '3-2-1',
            label: 'Level three 3-2-1',
          },
        ],
      },
    ],
  },
]
</script>
```

隐藏源代码

WARNING

在使用 show-checkbox 时，因为 `check-on-click-leaf` 默认值为 true， 最后一个树节点可以通过点击节点进行勾选。

## 多选 [​](#多选)

通过点击或复选框选择多个选项。

Select

show checkbox:

Select

show checkbox with \`check-strictly\`:

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS1zZWxlY3RcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgbXVsdGlwbGVcbiAgICA6cmVuZGVyLWFmdGVyLWV4cGFuZD1cImZhbHNlXCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gIC8+XG4gIDxlbC1kaXZpZGVyIC8+XG4gIHNob3cgY2hlY2tib3g6XG4gIDxlbC10cmVlLXNlbGVjdFxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICBtdWx0aXBsZVxuICAgIDpyZW5kZXItYWZ0ZXItZXhwYW5kPVwiZmFsc2VcIlxuICAgIHNob3ctY2hlY2tib3hcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gIC8+XG4gIDxlbC1kaXZpZGVyIC8+XG4gIHNob3cgY2hlY2tib3ggd2l0aCBgY2hlY2stc3RyaWN0bHlgOlxuICA8ZWwtdHJlZS1zZWxlY3RcbiAgICB2LW1vZGVsPVwidmFsdWVTdHJpY3RseVwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICBtdWx0aXBsZVxuICAgIDpyZW5kZXItYWZ0ZXItZXhwYW5kPVwiZmFsc2VcIlxuICAgIHNob3ctY2hlY2tib3hcbiAgICBjaGVjay1zdHJpY3RseVxuICAgIGNoZWNrLW9uLWNsaWNrLW5vZGVcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZigpXG5jb25zdCB2YWx1ZVN0cmljdGx5ID0gcmVmKClcblxuY29uc3QgZGF0YSA9IFtcbiAge1xuICAgIHZhbHVlOiAnMScsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICcxLTEnLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAxLTEnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnMS0xLTEnLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAxLTEtMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnMicsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMicsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICcyLTEnLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAyLTEnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnMi0xLTEnLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAyLTEtMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnMi0yJyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0yJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJzItMi0xJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMi0yLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJzMnLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDMnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnMy0xJyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJzMtMS0xJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMy0xLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJzMtMicsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDMtMicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICczLTItMScsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMi0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-select/multiple.vue)_

vue

```
<template>
  <el-tree-select
    v-model="value"
    :data="data"
    multiple
    :render-after-expand="false"
    style="width: 240px"
  />
  <el-divider />
  show checkbox:
  <el-tree-select
    v-model="value"
    :data="data"
    multiple
    :render-after-expand="false"
    show-checkbox
    style="width: 240px"
  />
  <el-divider />
  show checkbox with `check-strictly`:
  <el-tree-select
    v-model="valueStrictly"
    :data="data"
    multiple
    :render-after-expand="false"
    show-checkbox
    check-strictly
    check-on-click-node
    style="width: 240px"
  />
</template>

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

const value = ref()
const valueStrictly = ref()

const data = [
  {
    value: '1',
    label: 'Level one 1',
    children: [
      {
        value: '1-1',
        label: 'Level two 1-1',
        children: [
          {
            value: '1-1-1',
            label: 'Level three 1-1-1',
          },
        ],
      },
    ],
  },
  {
    value: '2',
    label: 'Level one 2',
    children: [
      {
        value: '2-1',
        label: 'Level two 2-1',
        children: [
          {
            value: '2-1-1',
            label: 'Level three 2-1-1',
          },
        ],
      },
      {
        value: '2-2',
        label: 'Level two 2-2',
        children: [
          {
            value: '2-2-1',
            label: 'Level three 2-2-1',
          },
        ],
      },
    ],
  },
  {
    value: '3',
    label: 'Level one 3',
    children: [
      {
        value: '3-1',
        label: 'Level two 3-1',
        children: [
          {
            value: '3-1-1',
            label: 'Level three 3-1-1',
          },
        ],
      },
      {
        value: '3-2',
        label: 'Level two 3-2',
        children: [
          {
            value: '3-2-1',
            label: 'Level three 3-2-1',
          },
        ],
      },
    ],
  },
]
</script>
```

隐藏源代码

## 禁用选项 [​](#禁用选项)

使用 disabled 字段禁用选项。

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS1zZWxlY3Qgdi1tb2RlbD1cInZhbHVlXCIgOmRhdGE9XCJkYXRhXCIgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIiAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoKVxuXG5jb25zdCBkYXRhID0gW1xuICB7XG4gICAgdmFsdWU6ICcxJyxcbiAgICBsYWJlbDogJ0xldmVsIG9uZSAxJyxcbiAgICBkaXNhYmxlZDogdHJ1ZSxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogJzEtMScsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDEtMScsXG4gICAgICAgIGRpc2FibGVkOiB0cnVlLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIGRpc2FibGVkOiB0cnVlLFxuICAgICAgICAgICAgdmFsdWU6ICcxLTEtMScsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDEtMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICcyJyxcbiAgICBsYWJlbDogJ0xldmVsIG9uZSAyJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogJzItMScsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDItMScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICcyLTEtMScsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDItMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICcyLTInLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAyLTInLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnMi0yLTEnLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAyLTItMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnMycsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMycsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICczLTEnLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAzLTEnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnMy0xLTEnLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAzLTEtMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnMy0yJyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0yJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJzMtMi0xJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMy0yLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-select/disabled.vue)_

vue

```
<template>
  <el-tree-select v-model="value" :data="data" style="width: 240px" />
</template>

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

const value = ref()

const data = [
  {
    value: '1',
    label: 'Level one 1',
    disabled: true,
    children: [
      {
        value: '1-1',
        label: 'Level two 1-1',
        disabled: true,
        children: [
          {
            disabled: true,
            value: '1-1-1',
            label: 'Level three 1-1-1',
          },
        ],
      },
    ],
  },
  {
    value: '2',
    label: 'Level one 2',
    children: [
      {
        value: '2-1',
        label: 'Level two 2-1',
        children: [
          {
            value: '2-1-1',
            label: 'Level three 2-1-1',
          },
        ],
      },
      {
        value: '2-2',
        label: 'Level two 2-2',
        children: [
          {
            value: '2-2-1',
            label: 'Level three 2-2-1',
          },
        ],
      },
    ],
  },
  {
    value: '3',
    label: 'Level one 3',
    children: [
      {
        value: '3-1',
        label: 'Level two 3-1',
        children: [
          {
            value: '3-1-1',
            label: 'Level three 3-1-1',
          },
        ],
      },
      {
        value: '3-2',
        label: 'Level two 3-2',
        children: [
          {
            value: '3-2-1',
            label: 'Level three 3-2-1',
          },
        ],
      },
    ],
  },
]
</script>
```

隐藏源代码

## 可筛选 [​](#可筛选)

使用关键字筛选或自定义筛选方法。 `filterMethod`可以自定义数据筛选的方法， `filterNodeMethod`可以自定义节点数据筛选的方法。

Select

filter method:

Select

filter node method:

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS1zZWxlY3RcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgZmlsdGVyYWJsZVxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgLz5cbiAgPGVsLWRpdmlkZXIgLz5cbiAgZmlsdGVyIG1ldGhvZDpcbiAgPGVsLXRyZWUtc2VsZWN0XG4gICAgdi1tb2RlbD1cInZhbHVlXCJcbiAgICA6ZGF0YT1cImRhdGFcIlxuICAgIDpmaWx0ZXItbWV0aG9kPVwiZmlsdGVyTWV0aG9kXCJcbiAgICBmaWx0ZXJhYmxlXG4gICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAvPlxuICA8ZWwtZGl2aWRlciAvPlxuICBmaWx0ZXIgbm9kZSBtZXRob2Q6XG4gIDxlbC10cmVlLXNlbGVjdFxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6ZmlsdGVyLW5vZGUtbWV0aG9kPVwiZmlsdGVyTm9kZU1ldGhvZFwiXG4gICAgZmlsdGVyYWJsZVxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKClcblxuY29uc3Qgc291cmNlRGF0YSA9IFtcbiAge1xuICAgIHZhbHVlOiAnMScsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICcxLTEnLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAxLTEnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnMS0xLTEnLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAxLTEtMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIHZhbHVlOiAnMicsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMicsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICcyLTEnLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAyLTEnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnMi0xLTEnLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAyLTEtMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnMi0yJyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0yJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJzItMi0xJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMi0yLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJzMnLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDMnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnMy0xJyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJzMtMS0xJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMy0xLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJzMtMicsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDMtMicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICczLTItMScsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMi0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuY29uc3QgZGF0YSA9IHJlZihzb3VyY2VEYXRhKVxuXG5jb25zdCBmaWx0ZXJNZXRob2QgPSAodmFsdWUpID0+IHtcbiAgZGF0YS52YWx1ZSA9IFsuLi5zb3VyY2VEYXRhXS5maWx0ZXIoKGl0ZW0pID0+IGl0ZW0ubGFiZWwuaW5jbHVkZXModmFsdWUpKVxufVxuXG5jb25zdCBmaWx0ZXJOb2RlTWV0aG9kID0gKHZhbHVlLCBkYXRhKSA9PiBkYXRhLmxhYmVsLmluY2x1ZGVzKHZhbHVlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-select/filterable.vue)_

vue

```
<template>
  <el-tree-select
    v-model="value"
    :data="data"
    filterable
    style="width: 240px"
  />
  <el-divider />
  filter method:
  <el-tree-select
    v-model="value"
    :data="data"
    :filter-method="filterMethod"
    filterable
    style="width: 240px"
  />
  <el-divider />
  filter node method:
  <el-tree-select
    v-model="value"
    :data="data"
    :filter-node-method="filterNodeMethod"
    filterable
    style="width: 240px"
  />
</template>

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

const value = ref()

const sourceData = [
  {
    value: '1',
    label: 'Level one 1',
    children: [
      {
        value: '1-1',
        label: 'Level two 1-1',
        children: [
          {
            value: '1-1-1',
            label: 'Level three 1-1-1',
          },
        ],
      },
    ],
  },
  {
    value: '2',
    label: 'Level one 2',
    children: [
      {
        value: '2-1',
        label: 'Level two 2-1',
        children: [
          {
            value: '2-1-1',
            label: 'Level three 2-1-1',
          },
        ],
      },
      {
        value: '2-2',
        label: 'Level two 2-2',
        children: [
          {
            value: '2-2-1',
            label: 'Level three 2-2-1',
          },
        ],
      },
    ],
  },
  {
    value: '3',
    label: 'Level one 3',
    children: [
      {
        value: '3-1',
        label: 'Level two 3-1',
        children: [
          {
            value: '3-1-1',
            label: 'Level three 3-1-1',
          },
        ],
      },
      {
        value: '3-2',
        label: 'Level two 3-2',
        children: [
          {
            value: '3-2-1',
            label: 'Level three 3-2-1',
          },
        ],
      },
    ],
  },
]
const data = ref(sourceData)

const filterMethod = (value) => {
  data.value = [...sourceData].filter((item) => item.label.includes(value))
}

const filterNodeMethod = (value, data) => data.label.includes(value)
</script>
```

隐藏源代码

## 自定义内容 [​](#自定义内容)

自定义树节点的内容。

Select

use render content:

Select

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS1zZWxlY3Qgdi1tb2RlbD1cInZhbHVlXCIgOmRhdGE9XCJkYXRhXCIgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIj5cbiAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJ7IGRhdGE6IHsgbGFiZWwgfSB9XCI+XG4gICAgICB7eyBsYWJlbCB9fTxzcGFuIHN0eWxlPVwiY29sb3I6IGdyYXlcIj4oc3VmZml4KTwvc3Bhbj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLXRyZWUtc2VsZWN0PlxuICA8ZWwtZGl2aWRlciAvPlxuICB1c2UgcmVuZGVyIGNvbnRlbnQ6XG4gIDxlbC10cmVlLXNlbGVjdFxuICAgIHYtbW9kZWw9XCJ2YWx1ZVwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6cmVuZGVyLWNvbnRlbnQ9XCJyZW5kZXJDb250ZW50XCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZigpXG5cbmNvbnN0IHJlbmRlckNvbnRlbnQgPSAoaCwgeyBkYXRhIH0pID0+IHtcbiAgcmV0dXJuIGgoXG4gICAgJ3NwYW4nLFxuICAgIHtcbiAgICAgIHN0eWxlOiB7XG4gICAgICAgIGNvbG9yOiAnIzYyNkFFRicsXG4gICAgICB9LFxuICAgIH0sXG4gICAgZGF0YS5sYWJlbFxuICApXG59XG5cbmNvbnN0IGRhdGEgPSBbXG4gIHtcbiAgICB2YWx1ZTogJzEnLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDEnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnMS0xJyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMS0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJzEtMS0xJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMS0xLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICB2YWx1ZTogJzInLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDInLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiAnMi0xJyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICB2YWx1ZTogJzItMS0xJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMi0xLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICB2YWx1ZTogJzItMicsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDItMicsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICcyLTItMScsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDItMi0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgdmFsdWU6ICczJyxcbiAgICBsYWJlbDogJ0xldmVsIG9uZSAzJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogJzMtMScsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDMtMScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgdmFsdWU6ICczLTEtMScsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgdmFsdWU6ICczLTInLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAzLTInLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIHZhbHVlOiAnMy0yLTEnLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAzLTItMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-select/slots.vue)_

vue

```
<template>
  <el-tree-select v-model="value" :data="data" style="width: 240px">
    <template #default="{ data: { label } }">
      {{ label }}<span style="color: gray">(suffix)</span>
    </template>
  </el-tree-select>
  <el-divider />
  use render content:
  <el-tree-select
    v-model="value"
    :data="data"
    :render-content="renderContent"
    style="width: 240px"
  />
</template>

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

const value = ref()

const renderContent = (h, { data }) => {
  return h(
    'span',
    {
      style: {
        color: '#626AEF',
      },
    },
    data.label
  )
}

const data = [
  {
    value: '1',
    label: 'Level one 1',
    children: [
      {
        value: '1-1',
        label: 'Level two 1-1',
        children: [
          {
            value: '1-1-1',
            label: 'Level three 1-1-1',
          },
        ],
      },
    ],
  },
  {
    value: '2',
    label: 'Level one 2',
    children: [
      {
        value: '2-1',
        label: 'Level two 2-1',
        children: [
          {
            value: '2-1-1',
            label: 'Level three 2-1-1',
          },
        ],
      },
      {
        value: '2-2',
        label: 'Level two 2-2',
        children: [
          {
            value: '2-2-1',
            label: 'Level three 2-2-1',
          },
        ],
      },
    ],
  },
  {
    value: '3',
    label: 'Level one 3',
    children: [
      {
        value: '3-1',
        label: 'Level two 3-1',
        children: [
          {
            value: '3-1-1',
            label: 'Level three 3-1-1',
          },
        ],
      },
      {
        value: '3-2',
        label: 'Level two 3-2',
        children: [
          {
            value: '3-2-1',
            label: 'Level three 3-2-1',
          },
        ],
      },
    ],
  },
]
</script>
```

隐藏源代码

## 懒加载 [​](#懒加载)

树节点懒加载，更加适合于数据量大的列表。

Select

2.2.26 show lazy load label:

lazy load node5

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS1zZWxlY3RcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIGxhenlcbiAgICA6bG9hZD1cImxvYWRcIlxuICAgIDpwcm9wcz1cInByb3BzXCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gIC8+XG4gIDxlbC1kaXZpZGVyIC8+XG4gIDxWZXJzaW9uVGFnIHZlcnNpb249XCIyLjIuMjZcIiAvPiBzaG93IGxhenkgbG9hZCBsYWJlbDpcbiAgPGVsLXRyZWUtc2VsZWN0XG4gICAgdi1tb2RlbD1cInZhbHVlMlwiXG4gICAgbGF6eVxuICAgIDpsb2FkPVwibG9hZFwiXG4gICAgOnByb3BzPVwicHJvcHNcIlxuICAgIDpjYWNoZS1kYXRhPVwiY2FjaGVEYXRhXCJcbiAgICBzdHlsZT1cIndpZHRoOiAyNDBweFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZigpXG5jb25zdCB2YWx1ZTIgPSByZWYoNSlcblxuY29uc3QgY2FjaGVEYXRhID0gW3sgdmFsdWU6IDUsIGxhYmVsOiAnbGF6eSBsb2FkIG5vZGU1JyB9XVxuXG5jb25zdCBwcm9wcyA9IHtcbiAgbGFiZWw6ICdsYWJlbCcsXG4gIGNoaWxkcmVuOiAnY2hpbGRyZW4nLFxuICBpc0xlYWY6ICdpc0xlYWYnLFxufVxuXG5sZXQgaWQgPSAwXG5cbmNvbnN0IGxvYWQgPSAobm9kZSwgcmVzb2x2ZSkgPT4ge1xuICBpZiAobm9kZS5pc0xlYWYpIHJldHVybiByZXNvbHZlKFtdKVxuXG4gIHNldFRpbWVvdXQoKCkgPT4ge1xuICAgIHJlc29sdmUoW1xuICAgICAge1xuICAgICAgICB2YWx1ZTogKytpZCxcbiAgICAgICAgbGFiZWw6IGBsYXp5IGxvYWQgbm9kZSR7aWR9YCxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIHZhbHVlOiArK2lkLFxuICAgICAgICBsYWJlbDogYGxhenkgbG9hZCBub2RlJHtpZH1gLFxuICAgICAgICBpc0xlYWY6IHRydWUsXG4gICAgICB9LFxuICAgIF0pXG4gIH0sIDQwMClcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-select/lazy.vue)_

vue

```
<template>
  <el-tree-select
    v-model="value"
    lazy
    :load="load"
    :props="props"
    style="width: 240px"
  />
  <el-divider />
  <VersionTag version="2.2.26" /> show lazy load label:
  <el-tree-select
    v-model="value2"
    lazy
    :load="load"
    :props="props"
    :cache-data="cacheData"
    style="width: 240px"
  />
</template>

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

const value = ref()
const value2 = ref(5)

const cacheData = [{ value: 5, label: 'lazy load node5' }]

const props = {
  label: 'label',
  children: 'children',
  isLeaf: 'isLeaf',
}

let id = 0

const load = (node, resolve) => {
  if (node.isLeaf) return resolve([])

  setTimeout(() => {
    resolve([
      {
        value: ++id,
        label: `lazy load node${id}`,
      },
      {
        value: ++id,
        label: `lazy load node${id}`,
        isLeaf: true,
      },
    ])
  }, 400)
}
</script>
```

隐藏源代码

## 使用 node-key 属性 [​](#使用-node-key-属性)

默认情况下，`modelValue` 会查找 `value` 键。 对于其他数据结构，必须提供 `node-key` 才能正常工作。

TIP

1.  `node-key` 在整个树中应该是唯一的。
2.  `value-key` 与 `node-key` 具有相同的目标。
3.  与 select 组件相反，tree-select 不能检索对象值。

value-on-clear

Level two 1-1

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS1zZWxlY3RcbiAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICA6ZGF0YT1cImRhdGFcIlxuICAgIG5vZGUta2V5PVwiaWRcIlxuICAgIHNob3ctY2hlY2tib3hcbiAgICBtdWx0aXBsZVxuICAgIGRlZmF1bHQtZXhwYW5kLWFsbFxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoWzJdKVxuY29uc3QgZGF0YSA9IFtcbiAge1xuICAgIGlkOiAxLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDEnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIGlkOiAyLFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAxLTEnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IDMsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDEtMicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-select/node-key.vue)_

vue

```
<template>
  <el-tree-select
    v-model="value"
    style="width: 240px"
    :data="data"
    node-key="id"
    show-checkbox
    multiple
    default-expand-all
  />
</template>

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

const value = ref([2])
const data = [
  {
    id: 1,
    label: 'Level one 1',
    children: [
      {
        id: 2,
        label: 'Level two 1-1',
      },
      {
        id: 3,
        label: 'Level two 1-2',
      },
    ],
  },
]
</script>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

由于这个组件是`el-tree`和`el-select`的结合体，他们的原始属性未被更改，故不在此重复。请跳转查看原组件的相应文档。

| 属性 | 对外暴露的方法 | 事件 | 插槽 |
| --- | --- | --- | --- |
| [tree](https://element-plus.org/zh-CN/component/tree#attributes) | [tree](https://element-plus.org/zh-CN/component/tree#exposes) | [tree](https://element-plus.org/zh-CN/component/tree#events) | [tree](https://element-plus.org/zh-CN/component/tree#slots) |
| [select](https://element-plus.org/zh-CN/component/select#select-attributes) | [select](https://element-plus.org/zh-CN/component/select#select-exposes) | [select](https://element-plus.org/zh-CN/component/select#select-events) | [select](https://element-plus.org/zh-CN/component/select#select-slots) |

#### Own Attributes [​](#own-attributes)

| 属性名 | 详情 | 类型 | 默认值 |
| --- | --- | --- | --- |
| cache-data 2.2.26 | 懒加载节点的缓存数据，结构与数据相同，用于获取未加载数据的标签 | `array` | \[\] |

### 对外暴露的方法 [​](#对外暴露的方法)

WARNING

在 Tree 和 Select 组件下暴露方法的方式已被 **弃用**，并将于 3.0.0 中 **移除**，请在各自的组件层级下使用这些方法：`tree` 和 `select`。

| 事件名 | 详情 | Type |
| --- | --- | --- |
| treeRef 2.11.3 | Tree 组件实例 | `TreeInstance` |
| selectRef 2.11.3 | Select 组件实例 | `SelectInstance` |
| filter deprecated | 过滤所有树节点，过滤后的节点将被隐藏 | 接收一个参数并指定为 filter-node-method 属性的第一个参数 |
| updateKeyChildren deprecated | 为节点设置新数据，只有当设置 `node-key` 属性的时候才可用 | (key, data) 接收两个参数: 1. 节点的 key 2. 新数据 |
| getCheckedNodes deprecated | 如果节点可以被选中，(`show-checkbox` 为 `true`), 本方法将返回当前选中节点的数组 | (leafOnly, includeHalfChecked) 接收两个布尔类型参数: 1. 默认值为 `false`. 若参数为 `true`, 它将返回当前选中节点的子节点 2. 默认值为 `false`. 如果参数为 `true`, 返回值包含半选中节点数据 |
| setCheckedNodes deprecated | 设置目前选中的节点，使用此方法必须设置 `node-key` 属性 | 要选中的节点构成的数组 |
| getCheckedKeys deprecated | 若节点可用被选中 (`show-checkbox` 为 `true`), 它将返回当前选中节点 key 的数组 | (leafOnly) 接收一个布尔类型参数，默认为 `false`. 若参数为 `true`, 它将返回当前选中节点的子节点 |
| setCheckedKeys deprecated | 设置目前选中的节点，使用此方法必须设置 `node-key` 属性 | (keys, leafOnly) 接收两个参数: 1. 一个需要被选中的多节点 key 的数组 2. 布尔类型的值 如果设置为 `true`，将只设置选中的叶子节点状态。 默认值是 `false`. |
| setChecked deprecated | 设置节点是否被选中, 使用此方法必须设置 `node-key` 属性 | (key/data, checked, deep) 接收三个参数: 1. 要选中的节点的 key 或者数据 2. 一个布尔类型参数表明是否选中. 3. 一个布尔类型参数，用于指示是否递归选中/取消选中子节点（自 2.14.0 起，无论 `check-strictly` 设置如何，该行为均有效）。 |
| getHalfCheckedNodes deprecated | 如果节点可用被选中 (`show-checkbox` 为 `true`), 它将返回当前半选中的节点组成的数组 | ::: |
| getHalfCheckedKeys deprecated | 若节点可被选中(`show-checkbox` 为 `true`)，则返回目前半选中的节点的 key 所组成的数组 | ::: |
| getCurrentKey deprecated | 返回当前被选中节点的数据 (如果没有则返回 null) | ::: |
| getCurrentNode deprecated | 返回当前被选中节点的数据 (如果没有则返回 null) | ::: |
| setCurrentKey deprecated | 通过 key 设置某个节点的当前选中状态，使用此方法必须设置 `node-key` 属性 | (key, shouldAutoExpandParent=true) 1. 待被选节点的 key， 如果为 `null`, 取消当前选中的节点 2. 是否展开父节点 |
| setCurrentNode deprecated | 设置节点为选中状态，使用此方法必须设置 `node-key` 属性 | (node, shouldAutoExpandParent=true) 1. 待被选中的节点 2. 是否展开父节点 |
| getNode deprecated | 根据 data 或者 key 拿到 Tree 组件中的 node | (data) 节点的 data 或 key |
| remove deprecated | 删除 Tree 中的一个节点，使用此方法必须设置 node-key 属性 | (data) 要删除的节点的 data 或者 node 对象 |
| append deprecated | 为 Tree 中的一个节点追加一个子节点 | (data, parentNode) 1. 要追加的子节点的 data 2. 父节点的 data, key 或 node |
| insertBefore deprecated | 在 Tree 中给定节点前插入一个节点 | (data, refNode) 1. 要增加的节点的 data 2. 参考节点的 data, key 或 node |
| insertAfter deprecated | 在 Tree 中给定节点后插入一个节点 | (data, refNode) 1. 要增加的节点的 data 2. 参考节点的 data, key 或 node |
| focus deprecated | 使选择器的输入框获取焦点 | `Function` |
| blur deprecated | 使选择器的输入框失去焦点，并隐藏下拉框 | `Function` |
| selectedLabel 2.8.5 deprecated | 获取当前选中的标签 | `object` |

## 类型声明 [​](#类型声明)

显示类型声明

ts

```
type CacheOption = {
  value: string | number | boolean | object
  currentLabel: string | number
  isDisabled: boolean
}
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/tree-select) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/tree-select.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/tree-select.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/20787785?v=4&size=64)](https://github.com/yujinpan)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/33254923?v=4&size=64)](https://github.com/yicheny)[![](https://avatars.githubusercontent.com/u/27413795?v=4&size=64)](https://github.com/SpanManX)[![](https://avatars.githubusercontent.com/u/24290011?v=4&size=64)](https://github.com/xingyixiang)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/36940267?v=4&size=64)](https://github.com/gaoxuan-haxibiao)[![](https://avatars.githubusercontent.com/u/27912232?v=4&size=64)](https://github.com/Fuphoenixes)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/16463481?v=4&size=64)](https://github.com/hellomrbigshot)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/36811055?v=4&size=64)](https://github.com/iDestin)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/54303040?v=4&size=64)](https://github.com/7086cmd)[![](https://avatars.githubusercontent.com/u/48147837?v=4&size=64)](https://github.com/kcmeven)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/53589602?v=4&size=64)](https://github.com/l246804)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)

[Transfer 穿梭框](https://element-plus.org/zh-CN/component/transfer)

[Upload 上传器](https://element-plus.org/zh-CN/component/upload)




---
## [form/upload] Upload 上传
> 官方文档: https://element-plus.org/zh-CN/component/upload.html

---

# Upload 上传 [​](#upload-上传)

更新日志待解决

11

通过点击或者拖拽上传文件。

## 基础用法 [​](#基础用法)

通过 `slot` 你可以传入自定义的上传按钮类型和文字提示。 可通过设置 `limit` 和 `on-exceed` 来限制上传文件的个数和定义超出限制时的行为。 可通过设置 `before-remove` 来阻止文件移除操作。

Click to upload

jpg/png files with a size less than 500KB.

-   element-plus-logo.svg

    _press delete to remove_
-   element-plus-logo2.svg

    _press delete to remove_

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdXBsb2FkXG4gICAgdi1tb2RlbDpmaWxlLWxpc3Q9XCJmaWxlTGlzdFwiXG4gICAgY2xhc3M9XCJ1cGxvYWQtZGVtb1wiXG4gICAgYWN0aW9uPVwiaHR0cHM6Ly9ydW4ubW9ja3kuaW8vdjMvOWQwNTliZjktNDY2MC00NWYyLTkyNWQtY2U4MGFkNmM0ZDE1XCJcbiAgICBtdWx0aXBsZVxuICAgIDpvbi1wcmV2aWV3PVwiaGFuZGxlUHJldmlld1wiXG4gICAgOm9uLXJlbW92ZT1cImhhbmRsZVJlbW92ZVwiXG4gICAgOmJlZm9yZS1yZW1vdmU9XCJiZWZvcmVSZW1vdmVcIlxuICAgIDpsaW1pdD1cIjNcIlxuICAgIDpvbi1leGNlZWQ9XCJoYW5kbGVFeGNlZWRcIlxuICA+XG4gICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiPkNsaWNrIHRvIHVwbG9hZDwvZWwtYnV0dG9uPlxuICAgIDx0ZW1wbGF0ZSAjdGlwPlxuICAgICAgPGRpdiBjbGFzcz1cImVsLXVwbG9hZF9fdGlwXCI+XG4gICAgICAgIGpwZy9wbmcgZmlsZXMgd2l0aCBhIHNpemUgbGVzcyB0aGFuIDUwMEtCLlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC11cGxvYWQ+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgRWxNZXNzYWdlLCBFbE1lc3NhZ2VCb3ggfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmltcG9ydCB0eXBlIHsgVXBsb2FkUHJvcHMsIFVwbG9hZFVzZXJGaWxlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBmaWxlTGlzdCA9IHJlZjxVcGxvYWRVc2VyRmlsZVtdPihbXG4gIHtcbiAgICBuYW1lOiAnZWxlbWVudC1wbHVzLWxvZ28uc3ZnJyxcbiAgICB1cmw6ICdodHRwczovL2VsZW1lbnQtcGx1cy5vcmcvaW1hZ2VzL2VsZW1lbnQtcGx1cy1sb2dvLnN2ZycsXG4gIH0sXG4gIHtcbiAgICBuYW1lOiAnZWxlbWVudC1wbHVzLWxvZ28yLnN2ZycsXG4gICAgdXJsOiAnaHR0cHM6Ly9lbGVtZW50LXBsdXMub3JnL2ltYWdlcy9lbGVtZW50LXBsdXMtbG9nby5zdmcnLFxuICB9LFxuXSlcblxuY29uc3QgaGFuZGxlUmVtb3ZlOiBVcGxvYWRQcm9wc1snb25SZW1vdmUnXSA9IChmaWxlLCB1cGxvYWRGaWxlcykgPT4ge1xuICBjb25zb2xlLmxvZyhmaWxlLCB1cGxvYWRGaWxlcylcbn1cblxuY29uc3QgaGFuZGxlUHJldmlldzogVXBsb2FkUHJvcHNbJ29uUHJldmlldyddID0gKHVwbG9hZEZpbGUpID0+IHtcbiAgY29uc29sZS5sb2codXBsb2FkRmlsZSlcbn1cblxuY29uc3QgaGFuZGxlRXhjZWVkOiBVcGxvYWRQcm9wc1snb25FeGNlZWQnXSA9IChmaWxlcywgdXBsb2FkRmlsZXMpID0+IHtcbiAgRWxNZXNzYWdlLndhcm5pbmcoXG4gICAgYFRoZSBsaW1pdCBpcyAzLCB5b3Ugc2VsZWN0ZWQgJHtmaWxlcy5sZW5ndGh9IGZpbGVzIHRoaXMgdGltZSwgYWRkIHVwIHRvICR7XG4gICAgICBmaWxlcy5sZW5ndGggKyB1cGxvYWRGaWxlcy5sZW5ndGhcbiAgICB9IHRvdGFsbHlgXG4gIClcbn1cblxuY29uc3QgYmVmb3JlUmVtb3ZlOiBVcGxvYWRQcm9wc1snYmVmb3JlUmVtb3ZlJ10gPSAodXBsb2FkRmlsZSwgdXBsb2FkRmlsZXMpID0+IHtcbiAgcmV0dXJuIEVsTWVzc2FnZUJveC5jb25maXJtKFxuICAgIGBDYW5jZWwgdGhlIHRyYW5zZmVyIG9mICR7dXBsb2FkRmlsZS5uYW1lfSA/YFxuICApLnRoZW4oXG4gICAgKCkgPT4gdHJ1ZSxcbiAgICAoKSA9PiBmYWxzZVxuICApXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/upload/basic.vue)_

vue

```
<template>
  <el-upload
    v-model:file-list="fileList"
    class="upload-demo"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    multiple
    :on-preview="handlePreview"
    :on-remove="handleRemove"
    :before-remove="beforeRemove"
    :limit="3"
    :on-exceed="handleExceed"
  >
    <el-button type="primary">Click to upload</el-button>
    <template #tip>
      <div class="el-upload__tip">
        jpg/png files with a size less than 500KB.
      </div>
    </template>
  </el-upload>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElMessage, ElMessageBox } from 'element-plus'

import type { UploadProps, UploadUserFile } from 'element-plus'

const fileList = ref<UploadUserFile[]>([
  {
    name: 'element-plus-logo.svg',
    url: 'https://element-plus.org/images/element-plus-logo.svg',
  },
  {
    name: 'element-plus-logo2.svg',
    url: 'https://element-plus.org/images/element-plus-logo.svg',
  },
])

const handleRemove: UploadProps['onRemove'] = (file, uploadFiles) => {
  console.log(file, uploadFiles)
}

const handlePreview: UploadProps['onPreview'] = (uploadFile) => {
  console.log(uploadFile)
}

const handleExceed: UploadProps['onExceed'] = (files, uploadFiles) => {
  ElMessage.warning(
    `The limit is 3, you selected ${files.length} files this time, add up to ${
      files.length + uploadFiles.length
    } totally`
  )
}

const beforeRemove: UploadProps['beforeRemove'] = (uploadFile, uploadFiles) => {
  return ElMessageBox.confirm(
    `Cancel the transfer of ${uploadFile.name} ?`
  ).then(
    () => true,
    () => false
  )
}
</script>
```

隐藏源代码

## 覆盖前一个文件 [​](#覆盖前一个文件)

设置 `limit` 和 `on-exceed` 可以在选中时自动替换上一个文件。

select file

upload to server

limit 1 file, new file will cover the old file

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdXBsb2FkXG4gICAgcmVmPVwidXBsb2FkXCJcbiAgICBjbGFzcz1cInVwbG9hZC1kZW1vXCJcbiAgICBhY3Rpb249XCJodHRwczovL3J1bi5tb2NreS5pby92My85ZDA1OWJmOS00NjYwLTQ1ZjItOTI1ZC1jZTgwYWQ2YzRkMTVcIlxuICAgIDpsaW1pdD1cIjFcIlxuICAgIDpvbi1leGNlZWQ9XCJoYW5kbGVFeGNlZWRcIlxuICAgIDphdXRvLXVwbG9hZD1cImZhbHNlXCJcbiAgPlxuICAgIDx0ZW1wbGF0ZSAjdHJpZ2dlcj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIj5zZWxlY3QgZmlsZTwvZWwtYnV0dG9uPlxuICAgIDwvdGVtcGxhdGU+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIm1sLTNcIiB0eXBlPVwic3VjY2Vzc1wiIEBjbGljaz1cInN1Ym1pdFVwbG9hZFwiPlxuICAgICAgdXBsb2FkIHRvIHNlcnZlclxuICAgIDwvZWwtYnV0dG9uPlxuICAgIDx0ZW1wbGF0ZSAjdGlwPlxuICAgICAgPGRpdiBjbGFzcz1cImVsLXVwbG9hZF9fdGlwIHRleHQtcmVkXCI+XG4gICAgICAgIGxpbWl0IDEgZmlsZSwgbmV3IGZpbGUgd2lsbCBjb3ZlciB0aGUgb2xkIGZpbGVcbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtdXBsb2FkPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IGdlbkZpbGVJZCB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuaW1wb3J0IHR5cGUgeyBVcGxvYWRJbnN0YW5jZSwgVXBsb2FkUHJvcHMsIFVwbG9hZFJhd0ZpbGUgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHVwbG9hZCA9IHJlZjxVcGxvYWRJbnN0YW5jZT4oKVxuXG5jb25zdCBoYW5kbGVFeGNlZWQ6IFVwbG9hZFByb3BzWydvbkV4Y2VlZCddID0gKGZpbGVzKSA9PiB7XG4gIHVwbG9hZC52YWx1ZSEuY2xlYXJGaWxlcygpXG4gIGNvbnN0IGZpbGUgPSBmaWxlc1swXSBhcyBVcGxvYWRSYXdGaWxlXG4gIGZpbGUudWlkID0gZ2VuRmlsZUlkKClcbiAgdXBsb2FkLnZhbHVlIS5oYW5kbGVTdGFydChmaWxlKVxufVxuXG5jb25zdCBzdWJtaXRVcGxvYWQgPSAoKSA9PiB7XG4gIHVwbG9hZC52YWx1ZSEuc3VibWl0KClcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/upload/limit-cover.vue)_

vue

```
<template>
  <el-upload
    ref="upload"
    class="upload-demo"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    :limit="1"
    :on-exceed="handleExceed"
    :auto-upload="false"
  >
    <template #trigger>
      <el-button type="primary">select file</el-button>
    </template>
    <el-button class="ml-3" type="success" @click="submitUpload">
      upload to server
    </el-button>
    <template #tip>
      <div class="el-upload__tip text-red">
        limit 1 file, new file will cover the old file
      </div>
    </template>
  </el-upload>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { genFileId } from 'element-plus'

import type { UploadInstance, UploadProps, UploadRawFile } from 'element-plus'

const upload = ref<UploadInstance>()

const handleExceed: UploadProps['onExceed'] = (files) => {
  upload.value!.clearFiles()
  const file = files[0] as UploadRawFile
  file.uid = genFileId()
  upload.value!.handleStart(file)
}

const submitUpload = () => {
  upload.value!.submit()
}
</script>
```

隐藏源代码

## 用户头像 [​](#用户头像)

在 `before-upload` 钩子中限制用户上传文件的格式和大小。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdXBsb2FkXG4gICAgY2xhc3M9XCJhdmF0YXItdXBsb2FkZXJcIlxuICAgIGFjdGlvbj1cImh0dHBzOi8vcnVuLm1vY2t5LmlvL3YzLzlkMDU5YmY5LTQ2NjAtNDVmMi05MjVkLWNlODBhZDZjNGQxNVwiXG4gICAgOnNob3ctZmlsZS1saXN0PVwiZmFsc2VcIlxuICAgIDpvbi1zdWNjZXNzPVwiaGFuZGxlQXZhdGFyU3VjY2Vzc1wiXG4gICAgOmJlZm9yZS11cGxvYWQ9XCJiZWZvcmVBdmF0YXJVcGxvYWRcIlxuICA+XG4gICAgPGltZyB2LWlmPVwiaW1hZ2VVcmxcIiA6c3JjPVwiaW1hZ2VVcmxcIiBjbGFzcz1cImF2YXRhclwiIC8+XG4gICAgPGVsLWljb24gdi1lbHNlIGNsYXNzPVwiYXZhdGFyLXVwbG9hZGVyLWljb25cIj48UGx1cyAvPjwvZWwtaWNvbj5cbiAgPC9lbC11cGxvYWQ+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgRWxNZXNzYWdlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuaW1wb3J0IHsgUGx1cyB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5pbXBvcnQgdHlwZSB7IFVwbG9hZFByb3BzIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBpbWFnZVVybCA9IHJlZignJylcblxuY29uc3QgaGFuZGxlQXZhdGFyU3VjY2VzczogVXBsb2FkUHJvcHNbJ29uU3VjY2VzcyddID0gKFxuICByZXNwb25zZSxcbiAgdXBsb2FkRmlsZVxuKSA9PiB7XG4gIGltYWdlVXJsLnZhbHVlID0gVVJMLmNyZWF0ZU9iamVjdFVSTCh1cGxvYWRGaWxlLnJhdyEpXG59XG5cbmNvbnN0IGJlZm9yZUF2YXRhclVwbG9hZDogVXBsb2FkUHJvcHNbJ2JlZm9yZVVwbG9hZCddID0gKHJhd0ZpbGUpID0+IHtcbiAgaWYgKHJhd0ZpbGUudHlwZSAhPT0gJ2ltYWdlL2pwZWcnKSB7XG4gICAgRWxNZXNzYWdlLmVycm9yKCdBdmF0YXIgcGljdHVyZSBtdXN0IGJlIEpQRyBmb3JtYXQhJylcbiAgICByZXR1cm4gZmFsc2VcbiAgfSBlbHNlIGlmIChyYXdGaWxlLnNpemUgLyAxMDI0IC8gMTAyNCA+IDIpIHtcbiAgICBFbE1lc3NhZ2UuZXJyb3IoJ0F2YXRhciBwaWN0dXJlIHNpemUgY2FuIG5vdCBleGNlZWQgMk1CIScpXG4gICAgcmV0dXJuIGZhbHNlXG4gIH1cbiAgcmV0dXJuIHRydWVcbn1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmF2YXRhci11cGxvYWRlciAuYXZhdGFyIHtcbiAgd2lkdGg6IDE3OHB4O1xuICBoZWlnaHQ6IDE3OHB4O1xuICBkaXNwbGF5OiBibG9jaztcbn1cbjwvc3R5bGU+XG5cbjxzdHlsZT5cbi5hdmF0YXItdXBsb2FkZXIgLmVsLXVwbG9hZCB7XG4gIGJvcmRlcjogMXB4IGRhc2hlZCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICBib3JkZXItcmFkaXVzOiA2cHg7XG4gIGN1cnNvcjogcG9pbnRlcjtcbiAgcG9zaXRpb246IHJlbGF0aXZlO1xuICBvdmVyZmxvdzogaGlkZGVuO1xuICB0cmFuc2l0aW9uOiB2YXIoLS1lbC10cmFuc2l0aW9uLWR1cmF0aW9uLWZhc3QpO1xufVxuXG4uYXZhdGFyLXVwbG9hZGVyIC5lbC11cGxvYWQ6aG92ZXIge1xuICBib3JkZXItY29sb3I6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xufVxuXG4uZWwtaWNvbi5hdmF0YXItdXBsb2FkZXItaWNvbiB7XG4gIGZvbnQtc2l6ZTogMjhweDtcbiAgY29sb3I6ICM4YzkzOWQ7XG4gIHdpZHRoOiAxNzhweDtcbiAgaGVpZ2h0OiAxNzhweDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/upload/avatar.vue)_

vue

```
<template>
  <el-upload
    class="avatar-uploader"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    :show-file-list="false"
    :on-success="handleAvatarSuccess"
    :before-upload="beforeAvatarUpload"
  >
    <img v-if="imageUrl" :src="imageUrl" class="avatar" />
    <el-icon v-else class="avatar-uploader-icon"><Plus /></el-icon>
  </el-upload>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { Plus } from '@element-plus/icons-vue'

import type { UploadProps } from 'element-plus'

const imageUrl = ref('')

const handleAvatarSuccess: UploadProps['onSuccess'] = (
  response,
  uploadFile
) => {
  imageUrl.value = URL.createObjectURL(uploadFile.raw!)
}

const beforeAvatarUpload: UploadProps['beforeUpload'] = (rawFile) => {
  if (rawFile.type !== 'image/jpeg') {
    ElMessage.error('Avatar picture must be JPG format!')
    return false
  } else if (rawFile.size / 1024 / 1024 > 2) {
    ElMessage.error('Avatar picture size can not exceed 2MB!')
    return false
  }
  return true
}
</script>

<style scoped>
.avatar-uploader .avatar {
  width: 178px;
  height: 178px;
  display: block;
}
</style>

<style>
.avatar-uploader .el-upload {
  border: 1px dashed var(--el-border-color);
  border-radius: 6px;
  cursor: pointer;
  position: relative;
  overflow: hidden;
  transition: var(--el-transition-duration-fast);
}

.avatar-uploader .el-upload:hover {
  border-color: var(--el-color-primary);
}

.el-icon.avatar-uploader-icon {
  font-size: 28px;
  color: #8c939d;
  width: 178px;
  height: 178px;
  text-align: center;
}
</style>
```

隐藏源代码

## 照片墙 [​](#照片墙)

使用 `list-type` 属性来设定文件列表的样式。

-   ![](https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100)_press delete to remove_
-   ![](https://element-plus.org/images/plant-1.png)_press delete to remove_
-   ![](https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100)_press delete to remove_
-   ![](https://element-plus.org/images/plant-2.png)_press delete to remove_
-   ![](https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100)_press delete to remove_
-   ![](https://element-plus.org/images/figure-1.png)_press delete to remove_
-   ![](https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100)_press delete to remove_
-   ![](https://element-plus.org/images/figure-2.png)_press delete to remove_

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdXBsb2FkXG4gICAgdi1tb2RlbDpmaWxlLWxpc3Q9XCJmaWxlTGlzdFwiXG4gICAgYWN0aW9uPVwiaHR0cHM6Ly9ydW4ubW9ja3kuaW8vdjMvOWQwNTliZjktNDY2MC00NWYyLTkyNWQtY2U4MGFkNmM0ZDE1XCJcbiAgICBsaXN0LXR5cGU9XCJwaWN0dXJlLWNhcmRcIlxuICAgIDpvbi1wcmV2aWV3PVwiaGFuZGxlUGljdHVyZUNhcmRQcmV2aWV3XCJcbiAgICA6b24tcmVtb3ZlPVwiaGFuZGxlUmVtb3ZlXCJcbiAgPlxuICAgIDxlbC1pY29uPjxQbHVzIC8+PC9lbC1pY29uPlxuICA8L2VsLXVwbG9hZD5cblxuICA8ZWwtZGlhbG9nIHYtbW9kZWw9XCJkaWFsb2dWaXNpYmxlXCI+XG4gICAgPGltZyB3LWZ1bGwgOnNyYz1cImRpYWxvZ0ltYWdlVXJsXCIgYWx0PVwiUHJldmlldyBJbWFnZVwiIC8+XG4gIDwvZWwtZGlhbG9nPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IFBsdXMgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuaW1wb3J0IHR5cGUgeyBVcGxvYWRQcm9wcywgVXBsb2FkVXNlckZpbGUgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGZpbGVMaXN0ID0gcmVmPFVwbG9hZFVzZXJGaWxlW10+KFtcbiAge1xuICAgIG5hbWU6ICdmb29kLmpwZWcnLFxuICAgIHVybDogJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8zLzYzLzRlN2YzYTE1NDI5YmZkYTk5YmNlNDJhMThjZGQxanBlZy5qcGVnP2ltYWdlTW9ncjIvdGh1bWJuYWlsLzM2MHgzNjAvZm9ybWF0L3dlYnAvcXVhbGl0eS8xMDAnLFxuICB9LFxuICB7XG4gICAgbmFtZTogJ3BsYW50LTEucG5nJyxcbiAgICB1cmw6ICcvaW1hZ2VzL3BsYW50LTEucG5nJyxcbiAgfSxcbiAge1xuICAgIG5hbWU6ICdmb29kLmpwZWcnLFxuICAgIHVybDogJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8zLzYzLzRlN2YzYTE1NDI5YmZkYTk5YmNlNDJhMThjZGQxanBlZy5qcGVnP2ltYWdlTW9ncjIvdGh1bWJuYWlsLzM2MHgzNjAvZm9ybWF0L3dlYnAvcXVhbGl0eS8xMDAnLFxuICB9LFxuICB7XG4gICAgbmFtZTogJ3BsYW50LTIucG5nJyxcbiAgICB1cmw6ICcvaW1hZ2VzL3BsYW50LTIucG5nJyxcbiAgfSxcbiAge1xuICAgIG5hbWU6ICdmb29kLmpwZWcnLFxuICAgIHVybDogJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8zLzYzLzRlN2YzYTE1NDI5YmZkYTk5YmNlNDJhMThjZGQxanBlZy5qcGVnP2ltYWdlTW9ncjIvdGh1bWJuYWlsLzM2MHgzNjAvZm9ybWF0L3dlYnAvcXVhbGl0eS8xMDAnLFxuICB9LFxuICB7XG4gICAgbmFtZTogJ2ZpZ3VyZS0xLnBuZycsXG4gICAgdXJsOiAnL2ltYWdlcy9maWd1cmUtMS5wbmcnLFxuICB9LFxuICB7XG4gICAgbmFtZTogJ2Zvb2QuanBlZycsXG4gICAgdXJsOiAnaHR0cHM6Ly9mdXNzMTAuZWxlbWVjZG4uY29tLzMvNjMvNGU3ZjNhMTU0MjliZmRhOTliY2U0MmExOGNkZDFqcGVnLmpwZWc/aW1hZ2VNb2dyMi90aHVtYm5haWwvMzYweDM2MC9mb3JtYXQvd2VicC9xdWFsaXR5LzEwMCcsXG4gIH0sXG4gIHtcbiAgICBuYW1lOiAnZmlndXJlLTIucG5nJyxcbiAgICB1cmw6ICcvaW1hZ2VzL2ZpZ3VyZS0yLnBuZycsXG4gIH0sXG5dKVxuXG5jb25zdCBkaWFsb2dJbWFnZVVybCA9IHJlZignJylcbmNvbnN0IGRpYWxvZ1Zpc2libGUgPSByZWYoZmFsc2UpXG5cbmNvbnN0IGhhbmRsZVJlbW92ZTogVXBsb2FkUHJvcHNbJ29uUmVtb3ZlJ10gPSAodXBsb2FkRmlsZSwgdXBsb2FkRmlsZXMpID0+IHtcbiAgY29uc29sZS5sb2codXBsb2FkRmlsZSwgdXBsb2FkRmlsZXMpXG59XG5cbmNvbnN0IGhhbmRsZVBpY3R1cmVDYXJkUHJldmlldzogVXBsb2FkUHJvcHNbJ29uUHJldmlldyddID0gKHVwbG9hZEZpbGUpID0+IHtcbiAgZGlhbG9nSW1hZ2VVcmwudmFsdWUgPSB1cGxvYWRGaWxlLnVybCFcbiAgZGlhbG9nVmlzaWJsZS52YWx1ZSA9IHRydWVcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/upload/photo-wall.vue)_

vue

```
<template>
  <el-upload
    v-model:file-list="fileList"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    list-type="picture-card"
    :on-preview="handlePictureCardPreview"
    :on-remove="handleRemove"
  >
    <el-icon><Plus /></el-icon>
  </el-upload>

  <el-dialog v-model="dialogVisible">
    <img w-full :src="dialogImageUrl" alt="Preview Image" />
  </el-dialog>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Plus } from '@element-plus/icons-vue'

import type { UploadProps, UploadUserFile } from 'element-plus'

const fileList = ref<UploadUserFile[]>([
  {
    name: 'food.jpeg',
    url: 'https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100',
  },
  {
    name: 'plant-1.png',
    url: '/images/plant-1.png',
  },
  {
    name: 'food.jpeg',
    url: 'https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100',
  },
  {
    name: 'plant-2.png',
    url: '/images/plant-2.png',
  },
  {
    name: 'food.jpeg',
    url: 'https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100',
  },
  {
    name: 'figure-1.png',
    url: '/images/figure-1.png',
  },
  {
    name: 'food.jpeg',
    url: 'https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100',
  },
  {
    name: 'figure-2.png',
    url: '/images/figure-2.png',
  },
])

const dialogImageUrl = ref('')
const dialogVisible = ref(false)

const handleRemove: UploadProps['onRemove'] = (uploadFile, uploadFiles) => {
  console.log(uploadFile, uploadFiles)
}

const handlePictureCardPreview: UploadProps['onPreview'] = (uploadFile) => {
  dialogImageUrl.value = uploadFile.url!
  dialogVisible.value = true
}
</script>
```

隐藏源代码

## 自定义缩略图 [​](#自定义缩略图)

使用 `scoped-slot` 属性来改变默认的缩略图模板样式。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdXBsb2FkIGFjdGlvbj1cIiNcIiBsaXN0LXR5cGU9XCJwaWN0dXJlLWNhcmRcIiA6YXV0by11cGxvYWQ9XCJmYWxzZVwiPlxuICAgIDxlbC1pY29uPjxQbHVzIC8+PC9lbC1pY29uPlxuXG4gICAgPHRlbXBsYXRlICNmaWxlPVwieyBmaWxlIH1cIj5cbiAgICAgIDxkaXY+XG4gICAgICAgIDxpbWcgY2xhc3M9XCJlbC11cGxvYWQtbGlzdF9faXRlbS10aHVtYm5haWxcIiA6c3JjPVwiZmlsZS51cmxcIiBhbHQ9XCJcIiAvPlxuICAgICAgICA8c3BhbiBjbGFzcz1cImVsLXVwbG9hZC1saXN0X19pdGVtLWFjdGlvbnNcIj5cbiAgICAgICAgICA8c3BhblxuICAgICAgICAgICAgY2xhc3M9XCJlbC11cGxvYWQtbGlzdF9faXRlbS1wcmV2aWV3XCJcbiAgICAgICAgICAgIEBjbGljaz1cImhhbmRsZVBpY3R1cmVDYXJkUHJldmlldyhmaWxlKVwiXG4gICAgICAgICAgPlxuICAgICAgICAgICAgPGVsLWljb24+PHpvb20taW4gLz48L2VsLWljb24+XG4gICAgICAgICAgPC9zcGFuPlxuICAgICAgICAgIDxzcGFuXG4gICAgICAgICAgICB2LWlmPVwiIWRpc2FibGVkXCJcbiAgICAgICAgICAgIGNsYXNzPVwiZWwtdXBsb2FkLWxpc3RfX2l0ZW0tZGVsZXRlXCJcbiAgICAgICAgICAgIEBjbGljaz1cImhhbmRsZURvd25sb2FkKGZpbGUpXCJcbiAgICAgICAgICA+XG4gICAgICAgICAgICA8ZWwtaWNvbj48RG93bmxvYWQgLz48L2VsLWljb24+XG4gICAgICAgICAgPC9zcGFuPlxuICAgICAgICAgIDxzcGFuXG4gICAgICAgICAgICB2LWlmPVwiIWRpc2FibGVkXCJcbiAgICAgICAgICAgIGNsYXNzPVwiZWwtdXBsb2FkLWxpc3RfX2l0ZW0tZGVsZXRlXCJcbiAgICAgICAgICAgIEBjbGljaz1cImhhbmRsZVJlbW92ZShmaWxlKVwiXG4gICAgICAgICAgPlxuICAgICAgICAgICAgPGVsLWljb24+PERlbGV0ZSAvPjwvZWwtaWNvbj5cbiAgICAgICAgICA8L3NwYW4+XG4gICAgICAgIDwvc3Bhbj5cbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtdXBsb2FkPlxuXG4gIDxlbC1kaWFsb2cgdi1tb2RlbD1cImRpYWxvZ1Zpc2libGVcIj5cbiAgICA8aW1nIHctZnVsbCA6c3JjPVwiZGlhbG9nSW1hZ2VVcmxcIiBhbHQ9XCJQcmV2aWV3IEltYWdlXCIgLz5cbiAgPC9lbC1kaWFsb2c+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgRGVsZXRlLCBEb3dubG9hZCwgUGx1cywgWm9vbUluIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmltcG9ydCB0eXBlIHsgVXBsb2FkRmlsZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgZGlhbG9nSW1hZ2VVcmwgPSByZWYoJycpXG5jb25zdCBkaWFsb2dWaXNpYmxlID0gcmVmKGZhbHNlKVxuY29uc3QgZGlzYWJsZWQgPSByZWYoZmFsc2UpXG5cbmNvbnN0IGhhbmRsZVJlbW92ZSA9IChmaWxlOiBVcGxvYWRGaWxlKSA9PiB7XG4gIGNvbnNvbGUubG9nKGZpbGUpXG59XG5cbmNvbnN0IGhhbmRsZVBpY3R1cmVDYXJkUHJldmlldyA9IChmaWxlOiBVcGxvYWRGaWxlKSA9PiB7XG4gIGRpYWxvZ0ltYWdlVXJsLnZhbHVlID0gZmlsZS51cmwhXG4gIGRpYWxvZ1Zpc2libGUudmFsdWUgPSB0cnVlXG59XG5cbmNvbnN0IGhhbmRsZURvd25sb2FkID0gKGZpbGU6IFVwbG9hZEZpbGUpID0+IHtcbiAgY29uc29sZS5sb2coZmlsZSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/upload/custom-thumbnail.vue)_

vue

```
<template>
  <el-upload action="#" list-type="picture-card" :auto-upload="false">
    <el-icon><Plus /></el-icon>

    <template #file="{ file }">
      <div>
        <img class="el-upload-list__item-thumbnail" :src="file.url" alt="" />
        <span class="el-upload-list__item-actions">
          <span
            class="el-upload-list__item-preview"
            @click="handlePictureCardPreview(file)"
          >
            <el-icon><zoom-in /></el-icon>
          </span>
          <span
            v-if="!disabled"
            class="el-upload-list__item-delete"
            @click="handleDownload(file)"
          >
            <el-icon><Download /></el-icon>
          </span>
          <span
            v-if="!disabled"
            class="el-upload-list__item-delete"
            @click="handleRemove(file)"
          >
            <el-icon><Delete /></el-icon>
          </span>
        </span>
      </div>
    </template>
  </el-upload>

  <el-dialog v-model="dialogVisible">
    <img w-full :src="dialogImageUrl" alt="Preview Image" />
  </el-dialog>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Delete, Download, Plus, ZoomIn } from '@element-plus/icons-vue'

import type { UploadFile } from 'element-plus'

const dialogImageUrl = ref('')
const dialogVisible = ref(false)
const disabled = ref(false)

const handleRemove = (file: UploadFile) => {
  console.log(file)
}

const handlePictureCardPreview = (file: UploadFile) => {
  dialogImageUrl.value = file.url!
  dialogVisible.value = true
}

const handleDownload = (file: UploadFile) => {
  console.log(file)
}
</script>
```

隐藏源代码

## 图片列表缩略图 [​](#图片列表缩略图)

Click to upload

jpg/png files with a size less than 500kb

-   ![](https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100)

    food.jpeg

    _press delete to remove_
-   ![](https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100)

    food2.jpeg

    _press delete to remove_

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdXBsb2FkXG4gICAgdi1tb2RlbDpmaWxlLWxpc3Q9XCJmaWxlTGlzdFwiXG4gICAgY2xhc3M9XCJ1cGxvYWQtZGVtb1wiXG4gICAgYWN0aW9uPVwiaHR0cHM6Ly9ydW4ubW9ja3kuaW8vdjMvOWQwNTliZjktNDY2MC00NWYyLTkyNWQtY2U4MGFkNmM0ZDE1XCJcbiAgICA6b24tcHJldmlldz1cImhhbmRsZVByZXZpZXdcIlxuICAgIDpvbi1yZW1vdmU9XCJoYW5kbGVSZW1vdmVcIlxuICAgIGxpc3QtdHlwZT1cInBpY3R1cmVcIlxuICA+XG4gICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiPkNsaWNrIHRvIHVwbG9hZDwvZWwtYnV0dG9uPlxuICAgIDx0ZW1wbGF0ZSAjdGlwPlxuICAgICAgPGRpdiBjbGFzcz1cImVsLXVwbG9hZF9fdGlwXCI+XG4gICAgICAgIGpwZy9wbmcgZmlsZXMgd2l0aCBhIHNpemUgbGVzcyB0aGFuIDUwMGtiXG4gICAgICA8L2Rpdj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLXVwbG9hZD5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgVXBsb2FkUHJvcHMsIFVwbG9hZFVzZXJGaWxlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBmaWxlTGlzdCA9IHJlZjxVcGxvYWRVc2VyRmlsZVtdPihbXG4gIHtcbiAgICBuYW1lOiAnZm9vZC5qcGVnJyxcbiAgICB1cmw6ICdodHRwczovL2Z1c3MxMC5lbGVtZWNkbi5jb20vMy82My80ZTdmM2ExNTQyOWJmZGE5OWJjZTQyYTE4Y2RkMWpwZWcuanBlZz9pbWFnZU1vZ3IyL3RodW1ibmFpbC8zNjB4MzYwL2Zvcm1hdC93ZWJwL3F1YWxpdHkvMTAwJyxcbiAgfSxcbiAge1xuICAgIG5hbWU6ICdmb29kMi5qcGVnJyxcbiAgICB1cmw6ICdodHRwczovL2Z1c3MxMC5lbGVtZWNkbi5jb20vMy82My80ZTdmM2ExNTQyOWJmZGE5OWJjZTQyYTE4Y2RkMWpwZWcuanBlZz9pbWFnZU1vZ3IyL3RodW1ibmFpbC8zNjB4MzYwL2Zvcm1hdC93ZWJwL3F1YWxpdHkvMTAwJyxcbiAgfSxcbl0pXG5cbmNvbnN0IGhhbmRsZVJlbW92ZTogVXBsb2FkUHJvcHNbJ29uUmVtb3ZlJ10gPSAodXBsb2FkRmlsZSwgdXBsb2FkRmlsZXMpID0+IHtcbiAgY29uc29sZS5sb2codXBsb2FkRmlsZSwgdXBsb2FkRmlsZXMpXG59XG5cbmNvbnN0IGhhbmRsZVByZXZpZXc6IFVwbG9hZFByb3BzWydvblByZXZpZXcnXSA9IChmaWxlKSA9PiB7XG4gIGNvbnNvbGUubG9nKGZpbGUpXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/upload/file-list-with-thumbnail.vue)_

vue

```
<template>
  <el-upload
    v-model:file-list="fileList"
    class="upload-demo"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    :on-preview="handlePreview"
    :on-remove="handleRemove"
    list-type="picture"
  >
    <el-button type="primary">Click to upload</el-button>
    <template #tip>
      <div class="el-upload__tip">
        jpg/png files with a size less than 500kb
      </div>
    </template>
  </el-upload>
</template>

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

import type { UploadProps, UploadUserFile } from 'element-plus'

const fileList = ref<UploadUserFile[]>([
  {
    name: 'food.jpeg',
    url: 'https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100',
  },
  {
    name: 'food2.jpeg',
    url: 'https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100',
  },
])

const handleRemove: UploadProps['onRemove'] = (uploadFile, uploadFiles) => {
  console.log(uploadFile, uploadFiles)
}

const handlePreview: UploadProps['onPreview'] = (file) => {
  console.log(file)
}
</script>
```

隐藏源代码

## 上传文件列表控制 [​](#上传文件列表控制)

通过 `on-change` 钩子函数来对上传文件的列表进行控制。

Click to upload

jpg/png files with a size less than 500kb

-   food.jpeg

    _press delete to remove_
-   food2.jpeg

    _press delete to remove_

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdXBsb2FkXG4gICAgdi1tb2RlbDpmaWxlLWxpc3Q9XCJmaWxlTGlzdFwiXG4gICAgY2xhc3M9XCJ1cGxvYWQtZGVtb1wiXG4gICAgYWN0aW9uPVwiaHR0cHM6Ly9ydW4ubW9ja3kuaW8vdjMvOWQwNTliZjktNDY2MC00NWYyLTkyNWQtY2U4MGFkNmM0ZDE1XCJcbiAgICA6b24tY2hhbmdlPVwiaGFuZGxlQ2hhbmdlXCJcbiAgPlxuICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIj5DbGljayB0byB1cGxvYWQ8L2VsLWJ1dHRvbj5cbiAgICA8dGVtcGxhdGUgI3RpcD5cbiAgICAgIDxkaXYgY2xhc3M9XCJlbC11cGxvYWRfX3RpcFwiPlxuICAgICAgICBqcGcvcG5nIGZpbGVzIHdpdGggYSBzaXplIGxlc3MgdGhhbiA1MDBrYlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC11cGxvYWQ+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IFVwbG9hZFByb3BzLCBVcGxvYWRVc2VyRmlsZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgZmlsZUxpc3QgPSByZWY8VXBsb2FkVXNlckZpbGVbXT4oW1xuICB7XG4gICAgbmFtZTogJ2Zvb2QuanBlZycsXG4gICAgdXJsOiAnaHR0cHM6Ly9mdXNzMTAuZWxlbWVjZG4uY29tLzMvNjMvNGU3ZjNhMTU0MjliZmRhOTliY2U0MmExOGNkZDFqcGVnLmpwZWc/aW1hZ2VNb2dyMi90aHVtYm5haWwvMzYweDM2MC9mb3JtYXQvd2VicC9xdWFsaXR5LzEwMCcsXG4gIH0sXG4gIHtcbiAgICBuYW1lOiAnZm9vZDIuanBlZycsXG4gICAgdXJsOiAnaHR0cHM6Ly9mdXNzMTAuZWxlbWVjZG4uY29tLzMvNjMvNGU3ZjNhMTU0MjliZmRhOTliY2U0MmExOGNkZDFqcGVnLmpwZWc/aW1hZ2VNb2dyMi90aHVtYm5haWwvMzYweDM2MC9mb3JtYXQvd2VicC9xdWFsaXR5LzEwMCcsXG4gIH0sXG5dKVxuXG5jb25zdCBoYW5kbGVDaGFuZ2U6IFVwbG9hZFByb3BzWydvbkNoYW5nZSddID0gKHVwbG9hZEZpbGUsIHVwbG9hZEZpbGVzKSA9PiB7XG4gIGZpbGVMaXN0LnZhbHVlID0gZmlsZUxpc3QudmFsdWUuc2xpY2UoLTMpXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/upload/file-list.vue)_

vue

```
<template>
  <el-upload
    v-model:file-list="fileList"
    class="upload-demo"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    :on-change="handleChange"
  >
    <el-button type="primary">Click to upload</el-button>
    <template #tip>
      <div class="el-upload__tip">
        jpg/png files with a size less than 500kb
      </div>
    </template>
  </el-upload>
</template>

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

import type { UploadProps, UploadUserFile } from 'element-plus'

const fileList = ref<UploadUserFile[]>([
  {
    name: 'food.jpeg',
    url: 'https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100',
  },
  {
    name: 'food2.jpeg',
    url: 'https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100',
  },
])

const handleChange: UploadProps['onChange'] = (uploadFile, uploadFiles) => {
  fileList.value = fileList.value.slice(-3)
}
</script>
```

隐藏源代码

## 拖拽上传 [​](#拖拽上传)

你可以将文件拖拽到特定区域以进行上传。

Drop file here or _click to upload_

jpg/png files with a size less than 500kb

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdXBsb2FkXG4gICAgY2xhc3M9XCJ1cGxvYWQtZGVtb1wiXG4gICAgZHJhZ1xuICAgIGFjdGlvbj1cImh0dHBzOi8vcnVuLm1vY2t5LmlvL3YzLzlkMDU5YmY5LTQ2NjAtNDVmMi05MjVkLWNlODBhZDZjNGQxNVwiXG4gICAgbXVsdGlwbGVcbiAgPlxuICAgIDxlbC1pY29uIGNsYXNzPVwiZWwtaWNvbi0tdXBsb2FkXCI+PHVwbG9hZC1maWxsZWQgLz48L2VsLWljb24+XG4gICAgPGRpdiBjbGFzcz1cImVsLXVwbG9hZF9fdGV4dFwiPlxuICAgICAgRHJvcCBmaWxlIGhlcmUgb3IgPGVtPmNsaWNrIHRvIHVwbG9hZDwvZW0+XG4gICAgPC9kaXY+XG4gICAgPHRlbXBsYXRlICN0aXA+XG4gICAgICA8ZGl2IGNsYXNzPVwiZWwtdXBsb2FkX190aXBcIj5cbiAgICAgICAganBnL3BuZyBmaWxlcyB3aXRoIGEgc2l6ZSBsZXNzIHRoYW4gNTAwa2JcbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtdXBsb2FkPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IFVwbG9hZEZpbGxlZCB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/upload/drag-and-drop.vue)_

vue

```
<template>
  <el-upload
    class="upload-demo"
    drag
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    multiple
  >
    <el-icon class="el-icon--upload"><upload-filled /></el-icon>
    <div class="el-upload__text">
      Drop file here or <em>click to upload</em>
    </div>
    <template #tip>
      <div class="el-upload__tip">
        jpg/png files with a size less than 500kb
      </div>
    </template>
  </el-upload>
</template>

<script setup lang="ts">
import { UploadFilled } from '@element-plus/icons-vue'
</script>
```

隐藏源代码

## 上传目录 2.13.1 [​](#上传目录)

通过 `directory` 属性启用文件夹上传。

启用后，只能选择文件夹；选择文件夹后，文件夹内的文件将被扁平化处理。

Drop directory here or _click to upload_

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdXBsb2FkXG4gICAgY2xhc3M9XCJ1cGxvYWQtZGVtb1wiXG4gICAgZHJhZ1xuICAgIGFjdGlvbj1cImh0dHBzOi8vcnVuLm1vY2t5LmlvL3YzLzlkMDU5YmY5LTQ2NjAtNDVmMi05MjVkLWNlODBhZDZjNGQxNVwiXG4gICAgZGlyZWN0b3J5XG4gICAgbXVsdGlwbGVcbiAgICA6b24tY2hhbmdlPVwiaGFuZGxlQ2hhbmdlXCJcbiAgPlxuICAgIDxlbC1pY29uIGNsYXNzPVwiZWwtaWNvbi0tdXBsb2FkXCI+PHVwbG9hZC1maWxsZWQgLz48L2VsLWljb24+XG4gICAgPGRpdiBjbGFzcz1cImVsLXVwbG9hZF9fdGV4dFwiPlxuICAgICAgRHJvcCBkaXJlY3RvcnkgaGVyZSBvciA8ZW0+Y2xpY2sgdG8gdXBsb2FkPC9lbT5cbiAgICA8L2Rpdj5cbiAgPC9lbC11cGxvYWQ+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgVXBsb2FkRmlsbGVkIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmltcG9ydCB0eXBlIHsgVXBsb2FkRmlsZSwgVXBsb2FkRmlsZXMgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGhhbmRsZUNoYW5nZSA9ICh1cGxvYWRGaWxlOiBVcGxvYWRGaWxlLCB1cGxvYWRGaWxlczogVXBsb2FkRmlsZXMpID0+IHtcbiAgY29uc29sZS5sb2codXBsb2FkRmlsZSwgdXBsb2FkRmlsZXMpXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/upload/directory.vue)_

vue

```
<template>
  <el-upload
    class="upload-demo"
    drag
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    directory
    multiple
    :on-change="handleChange"
  >
    <el-icon class="el-icon--upload"><upload-filled /></el-icon>
    <div class="el-upload__text">
      Drop directory here or <em>click to upload</em>
    </div>
  </el-upload>
</template>

<script setup lang="ts">
import { UploadFilled } from '@element-plus/icons-vue'

import type { UploadFile, UploadFiles } from 'element-plus'

const handleChange = (uploadFile: UploadFile, uploadFiles: UploadFiles) => {
  console.log(uploadFile, uploadFiles)
}
</script>
```

隐藏源代码

## 手动上传 [​](#手动上传)

select file

upload to server

jpg/png files with a size less than 500kb

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdXBsb2FkXG4gICAgcmVmPVwidXBsb2FkUmVmXCJcbiAgICBjbGFzcz1cInVwbG9hZC1kZW1vXCJcbiAgICBhY3Rpb249XCJodHRwczovL3J1bi5tb2NreS5pby92My85ZDA1OWJmOS00NjYwLTQ1ZjItOTI1ZC1jZTgwYWQ2YzRkMTVcIlxuICAgIDphdXRvLXVwbG9hZD1cImZhbHNlXCJcbiAgPlxuICAgIDx0ZW1wbGF0ZSAjdHJpZ2dlcj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIj5zZWxlY3QgZmlsZTwvZWwtYnV0dG9uPlxuICAgIDwvdGVtcGxhdGU+XG5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwibWwtM1wiIHR5cGU9XCJzdWNjZXNzXCIgQGNsaWNrPVwic3VibWl0VXBsb2FkXCI+XG4gICAgICB1cGxvYWQgdG8gc2VydmVyXG4gICAgPC9lbC1idXR0b24+XG5cbiAgICA8dGVtcGxhdGUgI3RpcD5cbiAgICAgIDxkaXYgY2xhc3M9XCJlbC11cGxvYWRfX3RpcFwiPlxuICAgICAgICBqcGcvcG5nIGZpbGVzIHdpdGggYSBzaXplIGxlc3MgdGhhbiA1MDBrYlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC11cGxvYWQ+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IFVwbG9hZEluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCB1cGxvYWRSZWYgPSByZWY8VXBsb2FkSW5zdGFuY2U+KClcblxuY29uc3Qgc3VibWl0VXBsb2FkID0gKCkgPT4ge1xuICB1cGxvYWRSZWYudmFsdWUhLnN1Ym1pdCgpXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/upload/manual.vue)_

vue

```
<template>
  <el-upload
    ref="uploadRef"
    class="upload-demo"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    :auto-upload="false"
  >
    <template #trigger>
      <el-button type="primary">select file</el-button>
    </template>

    <el-button class="ml-3" type="success" @click="submitUpload">
      upload to server
    </el-button>

    <template #tip>
      <div class="el-upload__tip">
        jpg/png files with a size less than 500kb
      </div>
    </template>
  </el-upload>
</template>

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

import type { UploadInstance } from 'element-plus'

const uploadRef = ref<UploadInstance>()

const submitUpload = () => {
  uploadRef.value!.submit()
}
</script>
```

隐藏源代码

## API [​](#api)

### 属性 [​](#属性)

| 名称 | 描述 | 类型 | 默认值 |
| --- | --- | --- | --- |
| action required | 请求 URL | `string` | # |
| headers | 设置上传的请求头部 | `object` | — |
| method | 设置上传请求方法 | `string` | post |
| multiple | 是否支持多选文件 | `boolean` | false |
| data | 上传时附带的额外参数 从 v2.3.13 支持 `Awaitable` 数据，和 `Function` | `object` / `Function` | {} |
| name | 上传的文件字段名 | `string` | file |
| with-credentials | 支持发送 cookie 凭证信息 | `boolean` | false |
| show-file-list | 是否显示已上传文件列表 | `boolean` | true |
| drag | 是否启用拖拽上传 | `boolean` | false |
| accept | 接受上传的[文件类型](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-accept)（thumbnail-mode 模式下此参数无效） | `string` | '' |
| crossorigin | 原生属性 [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) | `enum` | — |
| on-preview | 点击文件列表中已上传的文件时的钩子 | `Function` | — |
| on-remove | 文件列表移除文件时的钩子 | `Function` | — |
| on-success | 文件上传成功时的钩子 | `Function` | — |
| on-error | 文件上传失败时的钩子 | `Function` | — |
| on-progress | 文件上传时的钩子 | `Function` | — |
| on-change | 文件状态改变时的钩子，添加文件、上传成功和上传失败时都会被调用 | `Function` | — |
| on-exceed | 当超出限制时，执行的钩子函数 | `Function` | — |
| before-upload | 上传文件之前的钩子，参数为上传的文件， 若返回`false`或者返回 `Promise` 且被 reject，则停止上传。 | `Function` | — |
| before-remove | 删除文件之前的钩子，参数为上传的文件和文件列表， 若返回 `false` 或者返回 `Promise` 且被 reject，则停止删除。 | `Function` | — |
| file-list / v-model:file-list | 默认上传文件 | `array` | \[\] |
| list-type | 文件列表的类型 | `enum` | text |
| auto-upload | 是否自动上传文件 | `boolean` | true |
| http-request | 覆盖默认的 Xhr 行为，允许自行实现上传文件的请求 | `Function` | [请参考ajaxUpload](https://github.com/element-plus/element-plus/blob/dev/packages/components/upload/src/ajax.ts#L55) |
| disabled | 是否禁用上传 | `boolean` | false |
| limit | 允许上传文件的最大数量 | `number` | — |
| directory 2.13.1 | 是否支持上传文件夹。 启用后，只能选择文件夹；选择文件夹后，文件夹内的文件将被扁平化处理。 | `boolean` | false |

### 插槽 [​](#插槽)

| 名称 | 描述 | 类型 |
| --- | --- | --- |
| default | 自定义默认内容 | \- |
| trigger | 触发文件选择框的内容 | \- |
| tip | 提示说明文字 | \- |
| file | 缩略图模板的内容 | `object` |

### 外部方法 [​](#外部方法)

| 名称 | 描述 | 类型 |
| --- | --- | --- |
| abort | 取消上传请求。 当指定了文件时，中止相应的待上传文件；当未指定文件时，中止所有待上传文件。 | `Function` |
| submit | 手动上传文件列表 | `Function` |
| clearFiles | 清空已上传的文件列表（该方法不支持在 `before-upload` 中调用） | `Function` |
| handleStart | 手动选择文件 | `Function` |
| handleRemove | 手动移除文件。 `file` 和`rawFile` 已被合并。 `rawFile` 将在 `v2.2.0` 中移除 | `Function` |

## 类型声明 [​](#类型声明)

显示类型声明

ts

```
type UploadFiles = UploadFile[]

type UploadUserFile = Omit<UploadFile, 'status' | 'uid'> &
  Partial<Pick<UploadFile, 'status' | 'uid'>>

type UploadStatus = 'ready' | 'uploading' | 'success' | 'fail'

type Awaitable<T> = Promise<T> | T

type Mutable<T> = { -readonly [P in keyof T]: T[P] }

interface UploadFile {
  name: string
  percentage?: number
  status: UploadStatus
  size?: number
  response?: unknown
  uid: number
  url?: string
  raw?: UploadRawFile
}

interface UploadProgressEvent extends ProgressEvent {
  percent: number
}

interface UploadRawFile extends File {
  uid: number
  isDirectory?: boolean
}

interface UploadRequestOptions {
  action: string
  method: string
  data: Record<string, string | Blob | [string | Blob, string] | string[]>
  filename: string
  file: UploadRawFile
  headers: Headers | Record<string, string | number | null | undefined>
  onError: (evt: UploadAjaxError) => void
  onProgress: (evt: UploadProgressEvent) => void
  onSuccess: (response: any) => void
  withCredentials: boolean
}
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/upload) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/upload.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/upload.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/26833520?v=4&size=64)](https://github.com/josonho)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/33646534?v=4&size=64)](https://github.com/SevenDreamYang)[![](https://avatars.githubusercontent.com/u/49601167?v=4&size=64)](https://github.com/jianjunyuu)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/54931083?v=4&size=64)](https://github.com/wjp980108)[![](https://avatars.githubusercontent.com/u/33254923?v=4&size=64)](https://github.com/yicheny)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/69418751?v=4&size=64)](https://github.com/selicens)[![](https://avatars.githubusercontent.com/u/186382194?v=4&size=64)](https://github.com/ly-yewu)[![](https://avatars.githubusercontent.com/u/35426360?v=4&size=64)](https://github.com/Jungzl)[![](https://avatars.githubusercontent.com/u/43257608?v=4&size=64)](https://github.com/Liao-js)[![](https://avatars.githubusercontent.com/u/126888254?v=4&size=64)](https://github.com/zhuchaoling)[![](https://avatars.githubusercontent.com/u/62926576?v=4&size=64)](https://github.com/ma-shuo)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/10903843?v=4&size=64)](https://github.com/klren0312)[![](https://avatars.githubusercontent.com/u/63360587?v=4&size=64)](https://github.com/wkasunsampath)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/3642589?v=4&size=64)](https://github.com/youpinyao)[![](https://avatars.githubusercontent.com/u/1442212?v=4&size=64)](https://github.com/hhucqian)[![](https://avatars.githubusercontent.com/u/39689863?v=4&size=64)](https://github.com/GenerQAQ)[![](https://avatars.githubusercontent.com/u/101238421?v=4&size=64)](https://github.com/acyza)[![](https://avatars.githubusercontent.com/u/59350883?v=4&size=64)](https://github.com/init-qy)[![](https://avatars.githubusercontent.com/u/169252980?v=4&size=64)](https://github.com/xiaochenchen-igg-com)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/17268607?v=4&size=64)](https://github.com/LYlanfeng)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/65154?v=4&size=64)](https://github.com/exherb)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/3841747?v=4&size=64)](https://github.com/sumy7)[![](https://avatars.githubusercontent.com/u/13826607?v=4&size=64)](https://github.com/wxyong)[![](https://avatars.githubusercontent.com/u/17539193?v=4&size=64)](https://github.com/gaoyia)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/1181011?v=4&size=64)](https://github.com/qdechochen)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/145281501?v=4&size=64)](https://github.com/typed-sigterm)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/31885971?v=4&size=64)](https://github.com/wonderl17)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/28811207?v=4&size=64)](https://github.com/fanhefeng)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/37203836?v=4&size=64)](https://github.com/PikiLee)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/1836701?v=4&size=64)](https://github.com/HADB)[![](https://avatars.githubusercontent.com/u/41336612?v=4&size=64)](https://github.com/liulinboyi)[![](https://avatars.githubusercontent.com/u/33344586?v=4&size=64)](https://github.com/Meglody)[![](https://avatars.githubusercontent.com/u/30743104?v=4&size=64)](https://github.com/marcovelarde)

[TreeSelect 树形选择](https://element-plus.org/zh-CN/component/tree-select)

[Avatar 头像](https://element-plus.org/zh-CN/component/avatar)




---

<!-- ============================================ -->
<!-- 类别: 数据展示 -->
<!-- ============================================ -->

## [data/avatar] Avatar 头像
> 官方文档: https://element-plus.org/zh-CN/component/avatar.html

---

# Avatar 头像 [​](#avatar-头像)

更新日志待解决

0

Avatar 组件可以用来代表人物或对象， 支持使用图片、图标或者文字作为 Avatar。

## 基础用法 [​](#基础用法)

使用 `shape` 和 `size` 属性来设置 Avatar 的形状和大小。

circle

![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)

![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)

![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)

![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)

square

![](https://cube.elemecdn.com/9/c2/f0ee8a3c7c9638a54940382568c9dpng.png)

![](https://cube.elemecdn.com/9/c2/f0ee8a3c7c9638a54940382568c9dpng.png)

![](https://cube.elemecdn.com/9/c2/f0ee8a3c7c9638a54940382568c9dpng.png)

![](https://cube.elemecdn.com/9/c2/f0ee8a3c7c9638a54940382568c9dpng.png)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IGNsYXNzPVwiZGVtby1hdmF0YXIgZGVtby1iYXNpY1wiPlxuICAgIDxlbC1jb2wgOmxnPVwiMTJcIiA6bWQ9XCIxMlwiPlxuICAgICAgPGRpdiBjbGFzcz1cInN1Yi10aXRsZVwiPmNpcmNsZTwvZGl2PlxuICAgICAgPGRpdiBjbGFzcz1cImRlbW8tYmFzaWMtLWNpcmNsZVwiPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgICAgICA8ZWwtYXZhdGFyIDpzaXplPVwiNTBcIiA6c3JjPVwiY2lyY2xlVXJsXCIgLz5cbiAgICAgICAgPC9kaXY+XG4gICAgICAgIDxkaXYgdi1mb3I9XCJzaXplIGluIHNpemVMaXN0XCIgOmtleT1cInNpemVcIiBjbGFzcz1cImJsb2NrXCI+XG4gICAgICAgICAgPGVsLWF2YXRhciA6c2l6ZT1cInNpemVcIiA6c3JjPVwiY2lyY2xlVXJsXCIgLz5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2Rpdj5cbiAgICA8L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpsZz1cIjEyXCIgOm1kPVwiMTJcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJzdWItdGl0bGVcIj5zcXVhcmU8L2Rpdj5cbiAgICAgIDxkaXYgY2xhc3M9XCJkZW1vLWJhc2ljLS1jaXJjbGVcIj5cbiAgICAgICAgPGRpdiBjbGFzcz1cImJsb2NrXCI+XG4gICAgICAgICAgPGVsLWF2YXRhciBzaGFwZT1cInNxdWFyZVwiIDpzaXplPVwiNTBcIiA6c3JjPVwic3F1YXJlVXJsXCIgLz5cbiAgICAgICAgPC9kaXY+XG4gICAgICAgIDxkaXYgdi1mb3I9XCJzaXplIGluIHNpemVMaXN0XCIgOmtleT1cInNpemVcIiBjbGFzcz1cImJsb2NrXCI+XG4gICAgICAgICAgPGVsLWF2YXRhciBzaGFwZT1cInNxdWFyZVwiIDpzaXplPVwic2l6ZVwiIDpzcmM9XCJzcXVhcmVVcmxcIiAvPlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZGl2PlxuICAgIDwvZWwtY29sPlxuICA8L2VsLXJvdz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWFjdGl2ZSwgdG9SZWZzIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBzdGF0ZSA9IHJlYWN0aXZlKHtcbiAgY2lyY2xlVXJsOlxuICAgICdodHRwczovL2N1YmUuZWxlbWVjZG4uY29tLzMvN2MvM2VhNmJlZWM2NDM2OWMyNjQyYjkyYzY3MjZmMWVwbmcucG5nJyxcbiAgc3F1YXJlVXJsOlxuICAgICdodHRwczovL2N1YmUuZWxlbWVjZG4uY29tLzkvYzIvZjBlZThhM2M3Yzk2MzhhNTQ5NDAzODI1NjhjOWRwbmcucG5nJyxcbiAgc2l6ZUxpc3Q6IFsnc21hbGwnLCAnJywgJ2xhcmdlJ10gYXMgY29uc3QsXG59KVxuXG5jb25zdCB7IGNpcmNsZVVybCwgc3F1YXJlVXJsLCBzaXplTGlzdCB9ID0gdG9SZWZzKHN0YXRlKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1iYXNpYyB7XG4gIHRleHQtYWxpZ246IGNlbnRlcjtcbn1cbi5kZW1vLWJhc2ljIC5zdWItdGl0bGUge1xuICBtYXJnaW4tYm90dG9tOiAxMHB4O1xuICBmb250LXNpemU6IDE0cHg7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG59XG4uZGVtby1iYXNpYyAuZGVtby1iYXNpYy0tY2lyY2xlLFxuLmRlbW8tYmFzaWMgLmRlbW8tYmFzaWMtLXNxdWFyZSB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGp1c3RpZnktY29udGVudDogc3BhY2UtYmV0d2VlbjtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbn1cbi5kZW1vLWJhc2ljIC5ibG9jazpub3QoOmxhc3QtY2hpbGQpIHtcbiAgYm9yZGVyLXJpZ2h0OiAxcHggc29saWQgdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbn1cbi5kZW1vLWJhc2ljIC5ibG9jayB7XG4gIGZsZXg6IDE7XG59XG4uZGVtby1iYXNpYyAuZWwtY29sOm5vdCg6bGFzdC1jaGlsZCkge1xuICBib3JkZXItcmlnaHQ6IDFweCBzb2xpZCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xufVxuQG1lZGlhIHNjcmVlbiBhbmQgKG1heC13aWR0aDogOTkycHgpIHtcbiAgLmRlbW8tYmFzaWMgLmVsLWNvbDpub3QoOmxhc3QtY2hpbGQpIHtcbiAgICBib3JkZXItcmlnaHQ6IG5vbmU7XG4gIH1cbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/avatar/basic.vue)_

vue

```
<template>
  <el-row class="demo-avatar demo-basic">
    <el-col :lg="12" :md="12">
      <div class="sub-title">circle</div>
      <div class="demo-basic--circle">
        <div class="block">
          <el-avatar :size="50" :src="circleUrl" />
        </div>
        <div v-for="size in sizeList" :key="size" class="block">
          <el-avatar :size="size" :src="circleUrl" />
        </div>
      </div>
    </el-col>
    <el-col :lg="12" :md="12">
      <div class="sub-title">square</div>
      <div class="demo-basic--circle">
        <div class="block">
          <el-avatar shape="square" :size="50" :src="squareUrl" />
        </div>
        <div v-for="size in sizeList" :key="size" class="block">
          <el-avatar shape="square" :size="size" :src="squareUrl" />
        </div>
      </div>
    </el-col>
  </el-row>
</template>

<script lang="ts" setup>
import { reactive, toRefs } from 'vue'

const state = reactive({
  circleUrl:
    'https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png',
  squareUrl:
    'https://cube.elemecdn.com/9/c2/f0ee8a3c7c9638a54940382568c9dpng.png',
  sizeList: ['small', '', 'large'] as const,
})

const { circleUrl, squareUrl, sizeList } = toRefs(state)
</script>

<style scoped>
.demo-basic {
  text-align: center;
}
.demo-basic .sub-title {
  margin-bottom: 10px;
  font-size: 14px;
  color: var(--el-text-color-secondary);
}
.demo-basic .demo-basic--circle,
.demo-basic .demo-basic--square {
  display: flex;
  justify-content: space-between;
  align-items: center;
}
.demo-basic .block:not(:last-child) {
  border-right: 1px solid var(--el-border-color);
}
.demo-basic .block {
  flex: 1;
}
.demo-basic .el-col:not(:last-child) {
  border-right: 1px solid var(--el-border-color);
}
@media screen and (max-width: 992px) {
  .demo-basic .el-col:not(:last-child) {
    border-right: none;
  }
}
</style>
```

隐藏源代码

## 展示类型 [​](#展示类型)

支持使用图片，图标或者文字作为 Avatar。

![](https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png)

user

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby10eXBlXCI+XG4gICAgPGRpdj5cbiAgICAgIDxlbC1hdmF0YXIgOmljb249XCJVc2VyRmlsbGVkXCIgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2PlxuICAgICAgPGVsLWF2YXRhclxuICAgICAgICBzcmM9XCJodHRwczovL2N1YmUuZWxlbWVjZG4uY29tLzAvODgvMDNiMGQzOTU4M2Y0ODIwNjc2OGE3NTM0ZTU1YmNwbmcucG5nXCJcbiAgICAgIC8+XG4gICAgPC9kaXY+XG4gICAgPGRpdj5cbiAgICAgIDxlbC1hdmF0YXI+IHVzZXIgPC9lbC1hdmF0YXI+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IFVzZXJGaWxsZWQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tdHlwZSB7XG4gIGRpc3BsYXk6IGZsZXg7XG59XG4uZGVtby10eXBlID4gZGl2IHtcbiAgZmxleDogMTtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xufVxuXG4uZGVtby10eXBlID4gZGl2Om5vdCg6bGFzdC1jaGlsZCkge1xuICBib3JkZXItcmlnaHQ6IDFweCBzb2xpZCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/avatar/types.vue)_

vue

```
<template>
  <div class="demo-type">
    <div>
      <el-avatar :icon="UserFilled" />
    </div>
    <div>
      <el-avatar
        src="https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png"
      />
    </div>
    <div>
      <el-avatar> user </el-avatar>
    </div>
  </div>
</template>

<script setup lang="ts">
import { UserFilled } from '@element-plus/icons-vue'
</script>

<style scoped>
.demo-type {
  display: flex;
}
.demo-type > div {
  flex: 1;
  text-align: center;
}

.demo-type > div:not(:last-child) {
  border-right: 1px solid var(--el-border-color);
}
</style>
```

隐藏源代码

## 回退行为 [​](#回退行为)

图片加载失败时的回退行为。

![](https://empty/)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby10eXBlXCI+XG4gICAgPGVsLWF2YXRhciA6c2l6ZT1cIjYwXCIgc3JjPVwiaHR0cHM6Ly9lbXB0eVwiIEBlcnJvcj1cImVycm9ySGFuZGxlclwiPlxuICAgICAgPGltZ1xuICAgICAgICBzcmM9XCJodHRwczovL2N1YmUuZWxlbWVjZG4uY29tL2UvZmQvMGZjN2QyMDUzMmZkYWY3NjlhMjU2ODM2MTc3MTFwbmcucG5nXCJcbiAgICAgIC8+XG4gICAgPC9lbC1hdmF0YXI+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IGVycm9ySGFuZGxlciA9ICgpID0+IHRydWVcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/avatar/fallback.vue)_

vue

```
<template>
  <div class="demo-type">
    <el-avatar :size="60" src="https://empty" @error="errorHandler">
      <img
        src="https://cube.elemecdn.com/e/fd/0fc7d20532fdaf769a25683617711png.png"
      />
    </el-avatar>
  </div>
</template>

<script lang="ts" setup>
const errorHandler = () => true
</script>
```

隐藏源代码

## 适应容器 [​](#适应容器)

当使用图片作为用户头像时，设置该图片如何在容器中展示。与 [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) 属性一致

fill![](https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg)

contain![](https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg)

cover![](https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg)

none![](https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg)

scale-down![](https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1maXRcIj5cbiAgICA8ZGl2IHYtZm9yPVwiZml0IGluIGZpdHNcIiA6a2V5PVwiZml0XCIgY2xhc3M9XCJibG9ja1wiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJ0aXRsZVwiPnt7IGZpdCB9fTwvc3Bhbj5cbiAgICAgIDxlbC1hdmF0YXIgc2hhcGU9XCJzcXVhcmVcIiA6c2l6ZT1cIjEwMFwiIDpmaXQ9XCJmaXRcIiA6c3JjPVwidXJsXCIgLz5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVhY3RpdmUsIHRvUmVmcyB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBDU1NQcm9wZXJ0aWVzIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBzdGF0ZSA9IHJlYWN0aXZlKHtcbiAgZml0czogW1xuICAgICdmaWxsJyxcbiAgICAnY29udGFpbicsXG4gICAgJ2NvdmVyJyxcbiAgICAnbm9uZScsXG4gICAgJ3NjYWxlLWRvd24nLFxuICBdIGFzIENTU1Byb3BlcnRpZXNbJ29iamVjdC1maXQnXVtdLFxuICB1cmw6ICdodHRwczovL2Z1c3MxMC5lbGVtZWNkbi5jb20vZS81ZC80YTczMWE5MDU5NGE0YWY1NDRjMGMyNTk0MTE3MWpwZWcuanBlZycsXG59KVxuXG5jb25zdCB7IGZpdHMsIHVybCB9ID0gdG9SZWZzKHN0YXRlKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1maXQge1xuICBkaXNwbGF5OiBmbGV4O1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG4gIGp1c3RpZnktY29udGVudDogc3BhY2UtYmV0d2Vlbjtcbn1cbi5kZW1vLWZpdCAuYmxvY2sge1xuICBmbGV4OiAxO1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LWRpcmVjdGlvbjogY29sdW1uO1xuICBmbGV4LWdyb3c6IDA7XG59XG5cbi5kZW1vLWZpdCAudGl0bGUge1xuICBtYXJnaW4tYm90dG9tOiAxMHB4O1xuICBmb250LXNpemU6IDE0cHg7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/avatar/fit.vue)_

vue

```
<template>
  <div class="demo-fit">
    <div v-for="fit in fits" :key="fit" class="block">
      <span class="title">{{ fit }}</span>
      <el-avatar shape="square" :size="100" :fit="fit" :src="url" />
    </div>
  </div>
</template>

<script lang="ts" setup>
import { reactive, toRefs } from 'vue'

import type { CSSProperties } from 'vue'

const state = reactive({
  fits: [
    'fill',
    'contain',
    'cover',
    'none',
    'scale-down',
  ] as CSSProperties['object-fit'][],
  url: 'https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg',
})

const { fits, url } = toRefs(state)
</script>

<style scoped>
.demo-fit {
  display: flex;
  text-align: center;
  justify-content: space-between;
}
.demo-fit .block {
  flex: 1;
  display: flex;
  flex-direction: column;
  flex-grow: 0;
}

.demo-fit .title {
  margin-bottom: 10px;
  font-size: 14px;
  color: var(--el-text-color-secondary);
}
</style>
```

隐藏源代码

## 头像组 2.13.1 [​](#头像组)

显示为头像组

使用标签 `<el-avatar-group>` 来分组您的头像。

default

![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)

use collapse-avatars

![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)\+ 4

use collapse-class and collapse-style

![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)\+ 4

use max-collapse-avatars

![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)\+ 2

use collapse-avatars-tooltip

![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)![](https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png)\+ 2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibS00XCI+XG4gICAgPHA+ZGVmYXVsdDwvcD5cbiAgICA8ZWwtYXZhdGFyLWdyb3VwPlxuICAgICAgPGVsLWF2YXRhciB2LWZvcj1cIm51bWJlciBpbiA1XCIgOmtleT1cIm51bWJlclwiIDpzcmM9XCJjaXJjbGVVcmxcIiAvPlxuICAgIDwvZWwtYXZhdGFyLWdyb3VwPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cIm0tNFwiPlxuICAgIDxwPnVzZSBjb2xsYXBzZS1hdmF0YXJzPC9wPlxuICAgIDxlbC1hdmF0YXItZ3JvdXAgY29sbGFwc2UtYXZhdGFycz5cbiAgICAgIDxlbC1hdmF0YXIgdi1mb3I9XCJudW1iZXIgaW4gNVwiIDprZXk9XCJudW1iZXJcIiA6c3JjPVwiY2lyY2xlVXJsXCIgLz5cbiAgICA8L2VsLWF2YXRhci1ncm91cD5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJtLTRcIj5cbiAgICA8cD51c2UgY29sbGFwc2UtY2xhc3MgYW5kIGNvbGxhcHNlLXN0eWxlPC9wPlxuICAgIDxlbC1hdmF0YXItZ3JvdXBcbiAgICAgIGNvbGxhcHNlLWF2YXRhcnNcbiAgICAgIDpjb2xsYXBzZS1zdHlsZT1cInsgJ2JhY2tncm91bmQtY29sb3InOiAnI2Q5ZWNmZicgfVwiXG4gICAgICBjb2xsYXBzZS1jbGFzcz1cIm15LWNvbGxhcHNlLWF2YXRhclwiXG4gICAgPlxuICAgICAgPGVsLWF2YXRhciB2LWZvcj1cIm51bWJlciBpbiA1XCIgOmtleT1cIm51bWJlclwiIDpzcmM9XCJjaXJjbGVVcmxcIiAvPlxuICAgIDwvZWwtYXZhdGFyLWdyb3VwPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cIm0tNFwiPlxuICAgIDxwPnVzZSBtYXgtY29sbGFwc2UtYXZhdGFyczwvcD5cbiAgICA8ZWwtYXZhdGFyLWdyb3VwIGNvbGxhcHNlLWF2YXRhcnMgOm1heC1jb2xsYXBzZS1hdmF0YXJzPVwiM1wiPlxuICAgICAgPGVsLWF2YXRhciB2LWZvcj1cIm51bWJlciBpbiA1XCIgOmtleT1cIm51bWJlclwiIDpzcmM9XCJjaXJjbGVVcmxcIiAvPlxuICAgIDwvZWwtYXZhdGFyLWdyb3VwPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cIm0tNFwiPlxuICAgIDxwPnVzZSBjb2xsYXBzZS1hdmF0YXJzLXRvb2x0aXA8L3A+XG4gICAgPGVsLWF2YXRhci1ncm91cFxuICAgICAgY29sbGFwc2UtYXZhdGFyc1xuICAgICAgOm1heC1jb2xsYXBzZS1hdmF0YXJzPVwiM1wiXG4gICAgICBjb2xsYXBzZS1hdmF0YXJzLXRvb2x0aXBcbiAgICA+XG4gICAgICA8ZWwtYXZhdGFyIHYtZm9yPVwibnVtYmVyIGluIDVcIiA6a2V5PVwibnVtYmVyXCIgOnNyYz1cImNpcmNsZVVybFwiIC8+XG4gICAgPC9lbC1hdmF0YXItZ3JvdXA+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IGNpcmNsZVVybCA9XG4gICdodHRwczovL2N1YmUuZWxlbWVjZG4uY29tLzMvN2MvM2VhNmJlZWM2NDM2OWMyNjQyYjkyYzY3MjZmMWVwbmcucG5nJ1xuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5teS1jb2xsYXBzZS1hdmF0YXIge1xuICBjb2xvcjogIzQwOWVmZjtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/avatar/group.vue)_

vue

```
<template>
  <div class="m-4">
    <p>default</p>
    <el-avatar-group>
      <el-avatar v-for="number in 5" :key="number" :src="circleUrl" />
    </el-avatar-group>
  </div>
  <div class="m-4">
    <p>use collapse-avatars</p>
    <el-avatar-group collapse-avatars>
      <el-avatar v-for="number in 5" :key="number" :src="circleUrl" />
    </el-avatar-group>
  </div>
  <div class="m-4">
    <p>use collapse-class and collapse-style</p>
    <el-avatar-group
      collapse-avatars
      :collapse-style="{ 'background-color': '#d9ecff' }"
      collapse-class="my-collapse-avatar"
    >
      <el-avatar v-for="number in 5" :key="number" :src="circleUrl" />
    </el-avatar-group>
  </div>
  <div class="m-4">
    <p>use max-collapse-avatars</p>
    <el-avatar-group collapse-avatars :max-collapse-avatars="3">
      <el-avatar v-for="number in 5" :key="number" :src="circleUrl" />
    </el-avatar-group>
  </div>
  <div class="m-4">
    <p>use collapse-avatars-tooltip</p>
    <el-avatar-group
      collapse-avatars
      :max-collapse-avatars="3"
      collapse-avatars-tooltip
    >
      <el-avatar v-for="number in 5" :key="number" :src="circleUrl" />
    </el-avatar-group>
  </div>
</template>

<script lang="ts" setup>
const circleUrl =
  'https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png'
</script>

<style>
.my-collapse-avatar {
  color: #409eff;
}
</style>
```

隐藏源代码

## Avatar API [​](#avatar-api)

### Avatar 属性 [​](#avatar-属性)

| 名称 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| icon | 设置 Avatar 的图标类型，具体参考 Icon 组件 | `string` / `Component` | — |
| size | Avatar 大小 | `number` / `enum` | — |
| shape | Avatar 形状 | `enum` | — |
| src | Avatar 图片的源地址 | `string` | — |
| src-set | 图片 Avatar 的原生 `srcset` 属性 | `string` | string |
| alt | 图片 Avatar 的原生 `alt` 属性 | `string` | — |
| fit | 当展示类型为图片的时候，设置图片如何适应容器 | `enum` | cover |

### Avatar 事件 [​](#avatar-事件)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| error | 图片加载失败时触发 | `Function` |

### Avatar 插槽 [​](#avatar-插槽)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义头像展示内容 |

## AvatarGroup API 2.13.1 [​](#avatargroup-api)

### AvatarGroup Attributes [​](#avatargroup-attributes)

| 方法名 | 详情 | Type | 默认 |
| --- | --- | --- | --- |
| size | 控制头像组中的头像大小 | `number` / `enum` | — |
| shape | 控制头像组中的头像形状 | `enum` | — |
| collapse-avatars | 是否折叠头像 | `boolean` | false |
| collapse-avatars-tooltip | 是否在鼠标悬停折叠头像的文字时显示所有折叠头像。 若要使用此功能， `collapse-avatars` 必须为 true | `boolean` | false |
| max-collapse-avatars | 需要显示的头像的最大数量 若要使用此功能， `collapse-avatars` 必须为 true | `number` | 1 |
| effect | tooltip 主题，内置了 `dark` / `light` 两种 | `enum` / `string` | light |
| placement | tooltip 的位置 | `enum` | top |
| popper-class | tooltip 的自定义类名 | `string` | '' |
| popper-style | tooltip 的自定义样式 | `string` / `object` | — |
| collapse-class | collapse-avatar 的自定义类名 | `string` | '' |
| collapse-style | collapse-avatar 的自定义样式 | `string` / `object` | — |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/avatar) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/avatar.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/avatar.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)[![](https://avatars.githubusercontent.com/u/49899455?v=4&size=64)](https://github.com/zhuige)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/75007029?v=4&size=64)](https://github.com/yj-liuzepeng)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)

[Upload 上传器](https://element-plus.org/zh-CN/component/upload)

[Badge 徽章](https://element-plus.org/zh-CN/component/badge)




---
## [data/badge] Badge 标记
> 官方文档: https://element-plus.org/zh-CN/component/badge.html

---

# Badge 徽章 [​](#badge-徽章)

更新日志待解决

2

按钮和图标上的数字或状态标记。

## 基础用法 [​](#基础用法)

可以用来展示新消息的数量。

数量值可接受 Number 或 String。

comments12

replies3

comments1

replies2

custom background1

Click Me

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYmFkZ2UgOnZhbHVlPVwiMTJcIiBjbGFzcz1cIml0ZW1cIj5cbiAgICA8ZWwtYnV0dG9uPmNvbW1lbnRzPC9lbC1idXR0b24+XG4gIDwvZWwtYmFkZ2U+XG4gIDxlbC1iYWRnZSA6dmFsdWU9XCIzXCIgY2xhc3M9XCJpdGVtXCI+XG4gICAgPGVsLWJ1dHRvbj5yZXBsaWVzPC9lbC1idXR0b24+XG4gIDwvZWwtYmFkZ2U+XG4gIDxlbC1iYWRnZSA6dmFsdWU9XCIxXCIgY2xhc3M9XCJpdGVtXCIgdHlwZT1cInByaW1hcnlcIj5cbiAgICA8ZWwtYnV0dG9uPmNvbW1lbnRzPC9lbC1idXR0b24+XG4gIDwvZWwtYmFkZ2U+XG4gIDxlbC1iYWRnZSA6dmFsdWU9XCIyXCIgY2xhc3M9XCJpdGVtXCIgdHlwZT1cIndhcm5pbmdcIj5cbiAgICA8ZWwtYnV0dG9uPnJlcGxpZXM8L2VsLWJ1dHRvbj5cbiAgPC9lbC1iYWRnZT5cbiAgPGVsLWJhZGdlIDp2YWx1ZT1cIjFcIiBjbGFzcz1cIml0ZW1cIiBjb2xvcj1cImdyZWVuXCI+XG4gICAgPGVsLWJ1dHRvbj5jdXN0b20gYmFja2dyb3VuZDwvZWwtYnV0dG9uPlxuICA8L2VsLWJhZGdlPlxuICA8ZWwtZHJvcGRvd24gdHJpZ2dlcj1cImNsaWNrXCI+XG4gICAgPHNwYW4gY2xhc3M9XCJlbC1kcm9wZG93bi1saW5rXCI+XG4gICAgICBDbGljayBNZVxuICAgICAgPGVsLWljb24gY2xhc3M9XCJlbC1pY29uLS1yaWdodFwiPjxjYXJldC1ib3R0b20gLz48L2VsLWljb24+XG4gICAgPC9zcGFuPlxuICAgIDx0ZW1wbGF0ZSAjZHJvcGRvd24+XG4gICAgICA8ZWwtZHJvcGRvd24tbWVudT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gY2xhc3M9XCJjbGVhcmZpeFwiPlxuICAgICAgICAgIGNvbW1lbnRzXG4gICAgICAgICAgPGVsLWJhZGdlIGNsYXNzPVwibWFya1wiIDp2YWx1ZT1cIjEyXCIgLz5cbiAgICAgICAgPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSBjbGFzcz1cImNsZWFyZml4XCI+XG4gICAgICAgICAgcmVwbGllc1xuICAgICAgICAgIDxlbC1iYWRnZSBjbGFzcz1cIm1hcmtcIiA6dmFsdWU9XCIzXCIgLz5cbiAgICAgICAgPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgPC9lbC1kcm9wZG93bi1tZW51PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtZHJvcGRvd24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgQ2FyZXRCb3R0b20gfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLml0ZW0ge1xuICBtYXJnaW4tdG9wOiAxMHB4O1xuICBtYXJnaW4tcmlnaHQ6IDMwcHg7XG59XG5cbi5lbC1kcm9wZG93biB7XG4gIG1hcmdpbi10b3A6IDEuMXJlbTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/badge/basic.vue)_

vue

```
<template>
  <el-badge :value="12" class="item">
    <el-button>comments</el-button>
  </el-badge>
  <el-badge :value="3" class="item">
    <el-button>replies</el-button>
  </el-badge>
  <el-badge :value="1" class="item" type="primary">
    <el-button>comments</el-button>
  </el-badge>
  <el-badge :value="2" class="item" type="warning">
    <el-button>replies</el-button>
  </el-badge>
  <el-badge :value="1" class="item" color="green">
    <el-button>custom background</el-button>
  </el-badge>
  <el-dropdown trigger="click">
    <span class="el-dropdown-link">
      Click Me
      <el-icon class="el-icon--right"><caret-bottom /></el-icon>
    </span>
    <template #dropdown>
      <el-dropdown-menu>
        <el-dropdown-item class="clearfix">
          comments
          <el-badge class="mark" :value="12" />
        </el-dropdown-item>
        <el-dropdown-item class="clearfix">
          replies
          <el-badge class="mark" :value="3" />
        </el-dropdown-item>
      </el-dropdown-menu>
    </template>
  </el-dropdown>
</template>

<script lang="ts" setup>
import { CaretBottom } from '@element-plus/icons-vue'
</script>

<style scoped>
.item {
  margin-top: 10px;
  margin-right: 30px;
}

.el-dropdown {
  margin-top: 1.1rem;
}
</style>
```

隐藏源代码

## 最大值 [​](#最大值)

你还可以自定义最大值

由 max 属性定义，接受 Number 值。 请注意，仅在值也是 Number 时起作用。

comments99+

replies10+

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYmFkZ2UgOnZhbHVlPVwiMjAwXCIgOm1heD1cIjk5XCIgY2xhc3M9XCJpdGVtXCI+XG4gICAgPGVsLWJ1dHRvbj5jb21tZW50czwvZWwtYnV0dG9uPlxuICA8L2VsLWJhZGdlPlxuICA8ZWwtYmFkZ2UgOnZhbHVlPVwiMTAwXCIgOm1heD1cIjEwXCIgY2xhc3M9XCJpdGVtXCI+XG4gICAgPGVsLWJ1dHRvbj5yZXBsaWVzPC9lbC1idXR0b24+XG4gIDwvZWwtYmFkZ2U+XG48L3RlbXBsYXRlPlxuXG48c3R5bGUgc2NvcGVkPlxuLml0ZW0ge1xuICBtYXJnaW4tdG9wOiAxMHB4O1xuICBtYXJnaW4tcmlnaHQ6IDQwcHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/badge/max.vue)_

vue

```
<template>
  <el-badge :value="200" :max="99" class="item">
    <el-button>comments</el-button>
  </el-badge>
  <el-badge :value="100" :max="10" class="item">
    <el-button>replies</el-button>
  </el-badge>
</template>

<style scoped>
.item {
  margin-top: 10px;
  margin-right: 40px;
}
</style>
```

隐藏源代码

## 自定义显示内容 [​](#自定义显示内容)

你也可以展示除数字以外你想要展示的任何值。 或者您可以使用 `content` 栏位自定义内容。

当 value 是 String 时，可以显示自定义文字。 或者使用 `content` 插槽。

commentsnew

replieshot

share

99

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYmFkZ2UgdmFsdWU9XCJuZXdcIiBjbGFzcz1cIml0ZW1cIj5cbiAgICA8ZWwtYnV0dG9uPmNvbW1lbnRzPC9lbC1idXR0b24+XG4gIDwvZWwtYmFkZ2U+XG4gIDxlbC1iYWRnZSB2YWx1ZT1cImhvdFwiIGNsYXNzPVwiaXRlbVwiPlxuICAgIDxlbC1idXR0b24+cmVwbGllczwvZWwtYnV0dG9uPlxuICA8L2VsLWJhZGdlPlxuICA8ZWwtYmFkZ2UgdmFsdWU9XCI5OVwiIGNsYXNzPVwiaXRlbVwiPlxuICAgIDxlbC1idXR0b24+c2hhcmU8L2VsLWJ1dHRvbj5cbiAgICA8dGVtcGxhdGUgI2NvbnRlbnQ9XCJ7IHZhbHVlIH1cIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJjdXN0b20tY29udGVudFwiPlxuICAgICAgICA8ZWwtaWNvbj5cbiAgICAgICAgICA8TWVzc2FnZSAvPlxuICAgICAgICA8L2VsLWljb24+XG4gICAgICAgIDxzcGFuPnt7IHZhbHVlIH19PC9zcGFuPlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1iYWRnZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+XG5pbXBvcnQgeyBNZXNzYWdlIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5pdGVtIHtcbiAgbWFyZ2luLXRvcDogMTBweDtcbiAgbWFyZ2luLXJpZ2h0OiA0MHB4O1xufVxuXG4uY3VzdG9tLWNvbnRlbnQge1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBqdXN0aWZ5LWNvbnRlbnQ6IGNlbnRlcjtcbiAgZ2FwOiA0cHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/badge/customize.vue)_

vue

```
<template>
  <el-badge value="new" class="item">
    <el-button>comments</el-button>
  </el-badge>
  <el-badge value="hot" class="item">
    <el-button>replies</el-button>
  </el-badge>
  <el-badge value="99" class="item">
    <el-button>share</el-button>
    <template #content="{ value }">
      <div class="custom-content">
        <el-icon>
          <Message />
        </el-icon>
        <span>{{ value }}</span>
      </div>
    </template>
  </el-badge>
</template>

<script setup lang="ts">
import { Message } from '@element-plus/icons-vue'
</script>

<style scoped>
.item {
  margin-top: 10px;
  margin-right: 40px;
}

.custom-content {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 4px;
}
</style>
```

隐藏源代码

## 小红点 [​](#小红点)

通过一个小红点标记来告知用户有新内容。

使用 `is-dot` 属性。 是个布尔值。

query

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYmFkZ2UgaXMtZG90IGNsYXNzPVwiaXRlbVwiPnF1ZXJ5PC9lbC1iYWRnZT5cbiAgPGVsLWJhZGdlIGlzLWRvdCBjbGFzcz1cIml0ZW1cIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwic2hhcmUtYnV0dG9uXCIgOmljb249XCJTaGFyZVwiIHR5cGU9XCJwcmltYXJ5XCIgLz5cbiAgPC9lbC1iYWRnZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBTaGFyZSB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uaXRlbSB7XG4gIG1hcmdpbi10b3A6IDEwcHg7XG4gIG1hcmdpbi1yaWdodDogNDBweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/badge/dot.vue)_

vue

```
<template>
  <el-badge is-dot class="item">query</el-badge>
  <el-badge is-dot class="item">
    <el-button class="share-button" :icon="Share" type="primary" />
  </el-badge>
</template>

<script lang="ts" setup>
import { Share } from '@element-plus/icons-vue'
</script>

<style scoped>
.item {
  margin-top: 10px;
  margin-right: 40px;
}
</style>
```

隐藏源代码

## 偏移量 2.7.0 [​](#偏移量)

设置徽章点的偏移，格式是\[左，顶部\]， 代表状态点从左侧和默认位置顶部的偏移。

offset1

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYmFkZ2UgY2xhc3M9XCJpdGVtXCIgOnZhbHVlPVwiMVwiIDpvZmZzZXQ9XCJbMTAsIDVdXCI+XG4gICAgPGVsLWJ1dHRvbj4gb2Zmc2V0PC9lbC1idXR0b24+XG4gIDwvZWwtYmFkZ2U+XG48L3RlbXBsYXRlPlxuXG48c3R5bGUgc2NvcGVkPlxuLml0ZW0ge1xuICBtYXJnaW4tdG9wOiAxMHB4O1xuICBtYXJnaW4tcmlnaHQ6IDMwcHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/badge/offset.vue)_

vue

```
<template>
  <el-badge class="item" :value="1" :offset="[10, 5]">
    <el-button> offset</el-button>
  </el-badge>
</template>

<style scoped>
.item {
  margin-top: 10px;
  margin-right: 30px;
}
</style>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value | 显示值 | `string` / `number` | '' |
| max | 最大值，超过最大值会显示 `{max}+`。 只有当 value 是数字类型时起作用。 | `number` | 99 |
| is-dot | 是否显示小圆点。 | `boolean` | false |
| hidden | 是否隐藏 Badge。 | `boolean` | false |
| type | badge 类型。 | `enum` | danger |
| show-zero 2.6.0 | 值为零时是否显示 Badge | `boolean` | true |
| color 2.6.3 | 背景色 | `string` |  |
| offset 2.7.0 | badge 的偏移量 | `array` | \[0, 0\] |
| badge-style 2.7.1 | 自定义 badge 样式 | `object` | — |
| badge-class 2.7.1 | 自定义 badge 类名 | `string` | — |

### Slots [​](#slots)

| 插槽名 | 说明 | 类型 |
| --- | --- | --- |
| default | 自定义默认内容 | \- |
| content 2.9.1 | 自定义显示内容 | `object` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/badge) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/badge.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/badge.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/19898669?v=4&size=64)](https://github.com/lxw15337674)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/74746021?v=4&size=64)](https://github.com/xing403)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/66096254?v=4&size=64)](https://github.com/IceyWu)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/134276765?v=4&size=64)](https://github.com/zwgwf)[![](https://avatars.githubusercontent.com/u/2755933?v=4&size=64)](https://github.com/BiosSun)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/39764402?v=4&size=64)](https://github.com/LyyZzzz)[![](https://avatars.githubusercontent.com/u/1532716?v=4&size=64)](https://github.com/godxiaoji)

[Avatar 头像](https://element-plus.org/zh-CN/component/avatar)

[Calendar 日历](https://element-plus.org/zh-CN/component/calendar)




---
## [data/calendar] Calendar 日历
> 官方文档: https://element-plus.org/zh-CN/component/calendar.html

---

# Calendar 日历 [​](#calendar-日历)

更新日志待解决

2

显示日期

## 基础用法 [​](#基础用法)

设置 `value` 来指定当前显示的月份。 如果 `value` 未指定，则显示当月。 `value` 支持 `v-model` 双向绑定。

2026 June

Previous MonthTodayNext Month

| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
| --- | --- | --- | --- | --- | --- | --- |
|
31

 |

1

 |

2

 |

3

 |

4

 |

5

 |

6

 |
|

7

 |

8

 |

9

 |

10

 |

11

 |

12

 |

13

 |
|

14

 |

15

 |

16

 |

17

 |

18

 |

19

 |

20

 |
|

21

 |

22

 |

23

 |

24

 |

25

 |

26

 |

27

 |
|

28

 |

29

 |

30

 |

1

 |

2

 |

3

 |

4

 |

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FsZW5kYXIgdi1tb2RlbD1cInZhbHVlXCIgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKG5ldyBEYXRlKCkpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/calendar/basic.vue)_

vue

```
<template>
  <el-calendar v-model="value" />
</template>

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

const value = ref(new Date())
</script>
```

隐藏源代码

## 控制器类型 2.13.1 [​](#控制器类型)

您可以设置日历头部的控制器类型。 设置 `select`时，您可以使用 `formatter` 自定义 `label`。

selectbutton

2026 June

2026

6

Today

| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
| --- | --- | --- | --- | --- | --- | --- |
|
31

 |

1

 |

2

 |

3

 |

4

 |

5

 |

6

 |
|

7

 |

8

 |

9

 |

10

 |

11

 |

12

 |

13

 |
|

14

 |

15

 |

16

 |

17

 |

18

 |

19

 |

20

 |
|

21

 |

22

 |

23

 |

24

 |

25

 |

26

 |

27

 |
|

28

 |

29

 |

30

 |

1

 |

2

 |

3

 |

4

 |

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cImNvbnRyb2xsZXJUeXBlXCI+XG4gICAgPGVsLXJhZGlvLWJ1dHRvbiBsYWJlbD1cInNlbGVjdFwiIHZhbHVlPVwic2VsZWN0XCIgLz5cbiAgICA8ZWwtcmFkaW8tYnV0dG9uIGxhYmVsPVwiYnV0dG9uXCIgdmFsdWU9XCJidXR0b25cIiAvPlxuICA8L2VsLXJhZGlvLWdyb3VwPlxuXG4gIDxlbC1jYWxlbmRhciB2LW1vZGVsPVwidmFsdWVcIiA6Y29udHJvbGxlci10eXBlPVwiY29udHJvbGxlclR5cGVcIiAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgY29udHJvbGxlclR5cGUgPSByZWY8J3NlbGVjdCcgfCAnYnV0dG9uJz4oJ3NlbGVjdCcpXG5jb25zdCB2YWx1ZSA9IHJlZihuZXcgRGF0ZSgpKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/calendar/controller-type.vue)_

vue

```
<template>
  <el-radio-group v-model="controllerType">
    <el-radio-button label="select" value="select" />
    <el-radio-button label="button" value="button" />
  </el-radio-group>

  <el-calendar v-model="value" :controller-type="controllerType" />
</template>

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

const controllerType = ref<'select' | 'button'>('select')
const value = ref(new Date())
</script>
```

隐藏源代码

## 自定义内容 [​](#自定义内容)

通过设置名为 `date-cell` 的 `scoped-slot` 来自定义日历单元格中显示的内容。 在 `scoped-slot` 可以获取到 date（当前单元格的日期）, data（包括 type，isSelected，day 属性）。 详情解释参考下方的 API 文档。

2026 June

Previous MonthTodayNext Month

| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
| --- | --- | --- | --- | --- | --- | --- |
|
05-31

 |

06-01

 |

06-02

 |

06-03

 |

06-04

 |

06-05

 |

06-06

 |
|

06-07

 |

06-08

 |

06-09

 |

06-10

 |

06-11

 |

06-12

 |

06-13

 |
|

06-14

 |

06-15

 |

06-16

 |

06-17

 |

06-18

 |

06-19

 |

06-20

 |
|

06-21

 |

06-22

 |

06-23

 |

06-24

 |

06-25

 |

06-26

 |

06-27

 |
|

06-28

 |

06-29

 |

06-30

 |

07-01

 |

07-02

 |

07-03

 |

07-04

 |

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FsZW5kYXI+XG4gICAgPHRlbXBsYXRlICNkYXRlLWNlbGw9XCJ7IGRhdGEgfVwiPlxuICAgICAgPHAgOmNsYXNzPVwiZGF0YS5pc1NlbGVjdGVkID8gJ2lzLXNlbGVjdGVkJyA6ICcnXCI+XG4gICAgICAgIHt7IGRhdGEuZGF5LnNwbGl0KCctJykuc2xpY2UoMSkuam9pbignLScpIH19XG4gICAgICAgIHt7IGRhdGEuaXNTZWxlY3RlZCA/ICfinJTvuI8nIDogJycgfX1cbiAgICAgIDwvcD5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLWNhbGVuZGFyPlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlPlxuLmlzLXNlbGVjdGVkIHtcbiAgY29sb3I6ICMxOTg5ZmE7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/calendar/customize.vue)_

vue

```
<template>
  <el-calendar>
    <template #date-cell="{ data }">
      <p :class="data.isSelected ? 'is-selected' : ''">
        {{ data.day.split('-').slice(1).join('-') }}
        {{ data.isSelected ? '✔️' : '' }}
      </p>
    </template>
  </el-calendar>
</template>

<style>
.is-selected {
  color: #1989fa;
}
</style>
```

隐藏源代码

## 范围 [​](#范围)

设置 `range` 属性指定日历的显示范围。 开始时间必须是周起始日，结束时间必须是周结束日，且时间跨度不能超过两个月。

2019 March

| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
| --- | --- | --- | --- | --- | --- | --- |
|
3

 |

4

 |

5

 |

6

 |

7

 |

8

 |

9

 |
|

10

 |

11

 |

12

 |

13

 |

14

 |

15

 |

16

 |
|

17

 |

18

 |

19

 |

20

 |

21

 |

22

 |

23

 |
|

24

 |

25

 |

26

 |

27

 |

28

 |

29

 |

30

 |

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FsZW5kYXIgOnJhbmdlPVwiW25ldyBEYXRlKDIwMTksIDIsIDQpLCBuZXcgRGF0ZSgyMDE5LCAyLCAyNCldXCIgLz5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/calendar/range.vue)_

vue

```
<template>
  <el-calendar :range="[new Date(2019, 2, 4), new Date(2019, 2, 24)]" />
</template>
```

隐藏源代码

## 自定义日历头部 [​](#自定义日历头部)

Custom header content2026 June

Previous Year Previous Month Today Next Month Next Year

| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
| --- | --- | --- | --- | --- | --- | --- |
|
31

 |

1

 |

2

 |

3

 |

4

 |

5

 |

6

 |
|

7

 |

8

 |

9

 |

10

 |

11

 |

12

 |

13

 |
|

14

 |

15

 |

16

 |

17

 |

18

 |

19

 |

20

 |
|

21

 |

22

 |

23

 |

24

 |

25

 |

26

 |

27

 |
|

28

 |

29

 |

30

 |

1

 |

2

 |

3

 |

4

 |

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FsZW5kYXIgcmVmPVwiY2FsZW5kYXJcIj5cbiAgICA8dGVtcGxhdGUgI2hlYWRlcj1cInsgZGF0ZSB9XCI+XG4gICAgICA8c3Bhbj5DdXN0b20gaGVhZGVyIGNvbnRlbnQ8L3NwYW4+XG4gICAgICA8c3Bhbj57eyBkYXRlIH19PC9zcGFuPlxuICAgICAgPGVsLWJ1dHRvbi1ncm91cD5cbiAgICAgICAgPGVsLWJ1dHRvbiBzaXplPVwic21hbGxcIiBAY2xpY2s9XCJzZWxlY3REYXRlKCdwcmV2LXllYXInKVwiPlxuICAgICAgICAgIFByZXZpb3VzIFllYXJcbiAgICAgICAgPC9lbC1idXR0b24+XG4gICAgICAgIDxlbC1idXR0b24gc2l6ZT1cInNtYWxsXCIgQGNsaWNrPVwic2VsZWN0RGF0ZSgncHJldi1tb250aCcpXCI+XG4gICAgICAgICAgUHJldmlvdXMgTW9udGhcbiAgICAgICAgPC9lbC1idXR0b24+XG4gICAgICAgIDxlbC1idXR0b24gc2l6ZT1cInNtYWxsXCIgQGNsaWNrPVwic2VsZWN0RGF0ZSgndG9kYXknKVwiPlRvZGF5PC9lbC1idXR0b24+XG4gICAgICAgIDxlbC1idXR0b24gc2l6ZT1cInNtYWxsXCIgQGNsaWNrPVwic2VsZWN0RGF0ZSgnbmV4dC1tb250aCcpXCI+XG4gICAgICAgICAgTmV4dCBNb250aFxuICAgICAgICA8L2VsLWJ1dHRvbj5cbiAgICAgICAgPGVsLWJ1dHRvbiBzaXplPVwic21hbGxcIiBAY2xpY2s9XCJzZWxlY3REYXRlKCduZXh0LXllYXInKVwiPlxuICAgICAgICAgIE5leHQgWWVhclxuICAgICAgICA8L2VsLWJ1dHRvbj5cbiAgICAgIDwvZWwtYnV0dG9uLWdyb3VwPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtY2FsZW5kYXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IENhbGVuZGFyRGF0ZVR5cGUsIENhbGVuZGFySW5zdGFuY2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGNhbGVuZGFyID0gcmVmPENhbGVuZGFySW5zdGFuY2U+KClcbmNvbnN0IHNlbGVjdERhdGUgPSAodmFsOiBDYWxlbmRhckRhdGVUeXBlKSA9PiB7XG4gIGlmICghY2FsZW5kYXIudmFsdWUpIHJldHVyblxuICBjYWxlbmRhci52YWx1ZS5zZWxlY3REYXRlKHZhbClcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/calendar/header.vue)_

vue

```
<template>
  <el-calendar ref="calendar">
    <template #header="{ date }">
      <span>Custom header content</span>
      <span>{{ date }}</span>
      <el-button-group>
        <el-button size="small" @click="selectDate('prev-year')">
          Previous Year
        </el-button>
        <el-button size="small" @click="selectDate('prev-month')">
          Previous Month
        </el-button>
        <el-button size="small" @click="selectDate('today')">Today</el-button>
        <el-button size="small" @click="selectDate('next-month')">
          Next Month
        </el-button>
        <el-button size="small" @click="selectDate('next-year')">
          Next Year
        </el-button>
      </el-button-group>
    </template>
  </el-calendar>
</template>

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

import type { CalendarDateType, CalendarInstance } from 'element-plus'

const calendar = ref<CalendarInstance>()
const selectDate = (val: CalendarDateType) => {
  if (!calendar.value) return
  calendar.value.selectDate(val)
}
</script>
```

隐藏源代码

## 国际化 [​](#国际化)

由于 Element Plus 的默认语言为英语，如果你需要设置其它的语言，请参考[国际化](https://element-plus.org/zh-CN/guide/i18n)文档。

要注意的是：日期相关的文字（月份，每一周的第一天等等）也都是通过国际化来配置的。

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 选中项绑定值 | `Date` | — |
| range | 时间范围，包括开始时间与结束时间。 开始时间必须是周起始日，结束时间必须是周结束日，且时间跨度不能超过两个月。 | `array` | — |
| controller-type 2.13.1 | 日历头部的控制器类型 | `enum` | button |
| formatter 2.13.1 | 当 `controller-type` 为“select”时的格式标签 | `Function` | — |

### Slots [​](#slots)

| 插槽名 | 说明 | 类型 |
| --- | --- | --- |
| date-cell | `type` 表示该日期的所属月份，可选值有 prev-month、current-month 和 next-month；`isSelected` 标明该日期是否被选中；`day` 是格式化的日期，格式为 `yyyy-MM-dd`；`date` 是单元格的日期 | `object` |
| header | 卡片标题内容 | `object` |

### Exposes [​](#exposes)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| selectedDay | 当前已选日期 | `object` |
| pickDay | 选择一个具体日期 | `Function` |
| selectDate | 选择日期 | `Function` |
| calculateValidatedDateRange | 根据开始与结束日期计算验证日期范围 | `Function` |

## 类型声明 [​](#类型声明)

显示类型声明

ts

```
type CalendarDateType =
  | 'prev-month'
  | 'next-month'
  | 'prev-year'
  | 'next-year'
  | 'today'
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/calendar) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/calendar.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/calendar.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/33687038?v=4&size=64)](https://github.com/guozi9999)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/140705167?v=4&size=64)](https://github.com/zhongli-kira)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/35426360?v=4&size=64)](https://github.com/Jungzl)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/31850793?v=4&size=64)](https://github.com/ModyQyW)[![](https://avatars.githubusercontent.com/u/16495064?v=4&size=64)](https://github.com/sunyuu)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/59350883?v=4&size=64)](https://github.com/init-qy)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/23378455?v=4&size=64)](https://github.com/Dreamcreative)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/38106851?v=4&size=64)](https://github.com/LAMMUpro)

[Badge 徽章](https://element-plus.org/zh-CN/component/badge)

[Card 卡片](https://element-plus.org/zh-CN/component/card)




---
## [data/card] Card 卡片
> 官方文档: https://element-plus.org/zh-CN/component/card.html

---

# Card 卡片 [​](#card-卡片)

更新日志待解决

2

将信息聚合在卡片容器中展示。

## 基础用法 [​](#基础用法)

卡片包含标题，内容以及操作区域。

Card 组件由 `header` `body` 和 `footer`组成。 `header` 和 `footer`是可选的，其内容取决于一个具名的 slot。

Card name

List item 1

List item 2

List item 3

List item 4

Footer content

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FyZCBzdHlsZT1cIm1heC13aWR0aDogNDgwcHhcIj5cbiAgICA8dGVtcGxhdGUgI2hlYWRlcj5cbiAgICAgIDxkaXYgY2xhc3M9XCJjYXJkLWhlYWRlclwiPlxuICAgICAgICA8c3Bhbj5DYXJkIG5hbWU8L3NwYW4+XG4gICAgICA8L2Rpdj5cbiAgICA8L3RlbXBsYXRlPlxuICAgIDxwIHYtZm9yPVwibyBpbiA0XCIgOmtleT1cIm9cIiBjbGFzcz1cInRleHQgaXRlbVwiPnt7ICdMaXN0IGl0ZW0gJyArIG8gfX08L3A+XG4gICAgPHRlbXBsYXRlICNmb290ZXI+Rm9vdGVyIGNvbnRlbnQ8L3RlbXBsYXRlPlxuICA8L2VsLWNhcmQ+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/card/basic.vue)_

vue

```
<template>
  <el-card style="max-width: 480px">
    <template #header>
      <div class="card-header">
        <span>Card name</span>
      </div>
    </template>
    <p v-for="o in 4" :key="o" class="text item">{{ 'List item ' + o }}</p>
    <template #footer>Footer content</template>
  </el-card>
</template>
```

隐藏源代码

## 简单卡片 [​](#简单卡片)

卡片可以只有内容区域。

List item 1

List item 2

List item 3

List item 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FyZCBzdHlsZT1cIm1heC13aWR0aDogNDgwcHhcIj5cbiAgICA8cCB2LWZvcj1cIm8gaW4gNFwiIDprZXk9XCJvXCIgY2xhc3M9XCJ0ZXh0IGl0ZW1cIj57eyAnTGlzdCBpdGVtICcgKyBvIH19PC9wPlxuICA8L2VsLWNhcmQ+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/card/simple.vue)_

vue

```
<template>
  <el-card style="max-width: 480px">
    <p v-for="o in 4" :key="o" class="text item">{{ 'List item ' + o }}</p>
  </el-card>
</template>
```

隐藏源代码

## 有图片内容的卡片 [​](#有图片内容的卡片)

可配置定义更丰富的内容展示。

配置 `body-style` 属性来自定义 `body` 部分的样式。

Yummy hamburger

![](https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FyZCBzdHlsZT1cIm1heC13aWR0aDogNDgwcHhcIj5cbiAgICA8dGVtcGxhdGUgI2hlYWRlcj5ZdW1teSBoYW1idXJnZXI8L3RlbXBsYXRlPlxuICAgIDxpbWdcbiAgICAgIHNyYz1cImh0dHBzOi8vc2hhZG93LmVsZW1lY2RuLmNvbS9hcHAvZWxlbWVudC9oYW1idXJnZXIuOWNmN2IwOTEtNTVlOS0xMWU5LWE5NzYtN2Y0ZDBiMDdlZWY2LnBuZ1wiXG4gICAgICBzdHlsZT1cIndpZHRoOiAxMDAlXCJcbiAgICAvPlxuICA8L2VsLWNhcmQ+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/card/with-images.vue)_

vue

```
<template>
  <el-card style="max-width: 480px">
    <template #header>Yummy hamburger</template>
    <img
      src="https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png"
      style="width: 100%"
    />
  </el-card>
</template>
```

隐藏源代码

## 带有阴影效果的卡片 [​](#带有阴影效果的卡片)

你可以定义什么时候展示卡片的阴影效果。

通过 `shadow` 属性设置卡片阴影出现的时机。 该属性的值可以是：`always`、`hover` 或 `never`。

Always

Hover

Never

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTRcIj5cbiAgICA8ZWwtY2FyZCBzdHlsZT1cIndpZHRoOiA0ODBweFwiIHNoYWRvdz1cImFsd2F5c1wiPkFsd2F5czwvZWwtY2FyZD5cbiAgICA8ZWwtY2FyZCBzdHlsZT1cIndpZHRoOiA0ODBweFwiIHNoYWRvdz1cImhvdmVyXCI+SG92ZXI8L2VsLWNhcmQ+XG4gICAgPGVsLWNhcmQgc3R5bGU9XCJ3aWR0aDogNDgwcHhcIiBzaGFkb3c9XCJuZXZlclwiPk5ldmVyPC9lbC1jYXJkPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/card/shadow.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-4">
    <el-card style="width: 480px" shadow="always">Always</el-card>
    <el-card style="width: 480px" shadow="hover">Hover</el-card>
    <el-card style="width: 480px" shadow="never">Never</el-card>
  </div>
</template>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| header | 卡片的标题 你既可以通过设置 header 来修改标题，也可以通过 `slot#header` 传入 DOM 节点 | `string` | — |
| footer 2.4.3 | 卡片页脚。 你既可以通过设置 footer 来修改卡片底部内容，也可以通过 `slot#footer` 传入 DOM 节点 | `string` | — |
| body-style | body 的 CSS 样式 | `object` | — |
| header-class 2.9.8 | card header 的自定义类名 | `string` | — |
| body-class 2.3.10 | body 的自定义类名 | `string` | — |
| footer-class 2.9.8 | footer 的自定义类名 | `string` | — |
| shadow | 卡片阴影显示时机 | `enum` | always |

### Slots [​](#slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |
| header | 卡片标题内容 |
| footer | 卡片页脚内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/card) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/card.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/card.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/140705167?v=4&size=64)](https://github.com/zhongli-kira)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/87003751?v=4&size=64)](https://github.com/faga295)[![](https://avatars.githubusercontent.com/u/110730129?v=4&size=64)](https://github.com/uxuip)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/30256102?v=4&size=64)](https://github.com/leon-kfd)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/75007029?v=4&size=64)](https://github.com/yj-liuzepeng)[![](https://avatars.githubusercontent.com/u/101238421?v=4&size=64)](https://github.com/acyza)[![](https://avatars.githubusercontent.com/u/22659150?v=4&size=64)](https://github.com/ntnyq)

[Calendar 日历](https://element-plus.org/zh-CN/component/calendar)

[Carousel 走马灯](https://element-plus.org/zh-CN/component/carousel)




---
## [data/carousel] Carousel 走马灯
> 官方文档: https://element-plus.org/zh-CN/component/carousel.html

---

# Carousel 走马灯 [​](#carousel-走马灯)

更新日志待解决

7

在有限空间内，循环播放同一类型的图片、文字等内容

## 基础用法 [​](#基础用法)

结合使用 `el-carousel` 和 `el-carousel-item` 标签就得到了一个走马灯。 每一个页面的内容是完全可定制的，把你想要展示的内容放在 `el-carousel-item` 标签内。 默认情况下，在鼠标 hover 底部的指示器时就会触发切换。 通过设置 `trigger` 属性为 `click`，可以达到点击触发的效果。

Switch when indicator is hovered (default)

### 1

### 2

### 3

### 4

Switch when indicator is clicked

### 1

### 2

### 3

### 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiYmxvY2sgdGV4dC1jZW50ZXJcIj5cbiAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5cbiAgICAgIFN3aXRjaCB3aGVuIGluZGljYXRvciBpcyBob3ZlcmVkIChkZWZhdWx0KVxuICAgIDwvc3Bhbj5cbiAgICA8ZWwtY2Fyb3VzZWwgaGVpZ2h0PVwiMTUwcHhcIj5cbiAgICAgIDxlbC1jYXJvdXNlbC1pdGVtIHYtZm9yPVwiaXRlbSBpbiA0XCIgOmtleT1cIml0ZW1cIj5cbiAgICAgICAgPGgzIGNsYXNzPVwic21hbGwganVzdGlmeS1jZW50ZXJcIiB0ZXh0PVwiMnhsXCI+e3sgaXRlbSB9fTwvaDM+XG4gICAgICA8L2VsLWNhcm91c2VsLWl0ZW0+XG4gICAgPC9lbC1jYXJvdXNlbD5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJibG9jayB0ZXh0LWNlbnRlclwiIG09XCJ0LTRcIj5cbiAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5Td2l0Y2ggd2hlbiBpbmRpY2F0b3IgaXMgY2xpY2tlZDwvc3Bhbj5cbiAgICA8ZWwtY2Fyb3VzZWwgdHJpZ2dlcj1cImNsaWNrXCIgaGVpZ2h0PVwiMTUwcHhcIj5cbiAgICAgIDxlbC1jYXJvdXNlbC1pdGVtIHYtZm9yPVwiaXRlbSBpbiA0XCIgOmtleT1cIml0ZW1cIj5cbiAgICAgICAgPGgzIGNsYXNzPVwic21hbGwganVzdGlmeS1jZW50ZXJcIiB0ZXh0PVwiMnhsXCI+e3sgaXRlbSB9fTwvaDM+XG4gICAgICA8L2VsLWNhcm91c2VsLWl0ZW0+XG4gICAgPC9lbC1jYXJvdXNlbD5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW9uc3RyYXRpb24ge1xuICBjb2xvcjogdmFyKC0tZWwtdGV4dC1jb2xvci1zZWNvbmRhcnkpO1xufVxuXG4uZWwtY2Fyb3VzZWxfX2l0ZW0gaDMge1xuICBjb2xvcjogIzQ3NTY2OTtcbiAgb3BhY2l0eTogMC43NTtcbiAgbGluZS1oZWlnaHQ6IDE1MHB4O1xuICBtYXJnaW46IDA7XG4gIHRleHQtYWxpZ246IGNlbnRlcjtcbn1cblxuLmVsLWNhcm91c2VsX19pdGVtOm50aC1jaGlsZCgybikge1xuICBiYWNrZ3JvdW5kLWNvbG9yOiAjOTlhOWJmO1xufVxuXG4uZWwtY2Fyb3VzZWxfX2l0ZW06bnRoLWNoaWxkKDJuICsgMSkge1xuICBiYWNrZ3JvdW5kLWNvbG9yOiAjZDNkY2U2O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/carousel/basic.vue)_

vue

```
<template>
  <div class="block text-center">
    <span class="demonstration">
      Switch when indicator is hovered (default)
    </span>
    <el-carousel height="150px">
      <el-carousel-item v-for="item in 4" :key="item">
        <h3 class="small justify-center" text="2xl">{{ item }}</h3>
      </el-carousel-item>
    </el-carousel>
  </div>
  <div class="block text-center" m="t-4">
    <span class="demonstration">Switch when indicator is clicked</span>
    <el-carousel trigger="click" height="150px">
      <el-carousel-item v-for="item in 4" :key="item">
        <h3 class="small justify-center" text="2xl">{{ item }}</h3>
      </el-carousel-item>
    </el-carousel>
  </div>
</template>

<style scoped>
.demonstration {
  color: var(--el-text-color-secondary);
}

.el-carousel__item h3 {
  color: #475669;
  opacity: 0.75;
  line-height: 150px;
  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>
```

隐藏源代码

## 动态模糊 2.6.0 [​](#动态模糊)

添加动态模糊以给走马灯注入活力和流畅性。

启用动态模糊增强了走马灯的活力和流畅性。 `motion-blur` 的默认值是 `false`，手动激活此功能即可提供视觉感受上的提升。

Motion blur the switch (default)

### 1

### 2

### 3

### 4

Vertical effect

### 1

### 2

### 3

### 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiYmxvY2sgdGV4dC1jZW50ZXJcIj5cbiAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5Nb3Rpb24gYmx1ciB0aGUgc3dpdGNoIChkZWZhdWx0KTwvc3Bhbj5cbiAgICA8ZWwtY2Fyb3VzZWwgaGVpZ2h0PVwiMjAwcHhcIiBtb3Rpb24tYmx1cj5cbiAgICAgIDxlbC1jYXJvdXNlbC1pdGVtIHYtZm9yPVwiaXRlbSBpbiA0XCIgOmtleT1cIml0ZW1cIj5cbiAgICAgICAgPGgzIGNsYXNzPVwic21hbGwganVzdGlmeS1jZW50ZXJcIiB0ZXh0PVwiMnhsXCI+e3sgaXRlbSB9fTwvaDM+XG4gICAgICA8L2VsLWNhcm91c2VsLWl0ZW0+XG4gICAgPC9lbC1jYXJvdXNlbD5cbiAgPC9kaXY+XG4gIDxwIGNsYXNzPVwidGV4dC1jZW50ZXIgZGVtb25zdHJhdGlvblwiPlZlcnRpY2FsIGVmZmVjdDwvcD5cbiAgPGVsLWNhcm91c2VsXG4gICAgaGVpZ2h0PVwiMjAwcHhcIlxuICAgIGRpcmVjdGlvbj1cInZlcnRpY2FsXCJcbiAgICBtb3Rpb24tYmx1clxuICAgIDphdXRvcGxheT1cImZhbHNlXCJcbiAgPlxuICAgIDxlbC1jYXJvdXNlbC1pdGVtIHYtZm9yPVwiaXRlbSBpbiA0XCIgOmtleT1cIml0ZW1cIj5cbiAgICAgIDxoMyB0ZXh0PVwiMnhsXCIganVzdGlmeT1cImNlbnRlclwiPnt7IGl0ZW0gfX08L2gzPlxuICAgIDwvZWwtY2Fyb3VzZWwtaXRlbT5cbiAgPC9lbC1jYXJvdXNlbD5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtb25zdHJhdGlvbiB7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG59XG5cbi5lbC1jYXJvdXNlbF9faXRlbSBoMyB7XG4gIGNvbG9yOiAjNDc1NjY5O1xuICBvcGFjaXR5OiAwLjc1O1xuICBsaW5lLWhlaWdodDogMjAwcHg7XG4gIG1hcmdpbjogMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xufVxuXG4uZWwtY2Fyb3VzZWxfX2l0ZW06bnRoLWNoaWxkKDJuKSB7XG4gIGJhY2tncm91bmQtY29sb3I6ICM5OWE5YmY7XG59XG5cbi5lbC1jYXJvdXNlbF9faXRlbTpudGgtY2hpbGQoMm4gKyAxKSB7XG4gIGJhY2tncm91bmQtY29sb3I6ICNkM2RjZTY7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/carousel/motion-blur.vue)_

vue

```
<template>
  <div class="block text-center">
    <span class="demonstration">Motion blur the switch (default)</span>
    <el-carousel height="200px" motion-blur>
      <el-carousel-item v-for="item in 4" :key="item">
        <h3 class="small justify-center" text="2xl">{{ item }}</h3>
      </el-carousel-item>
    </el-carousel>
  </div>
  <p class="text-center demonstration">Vertical effect</p>
  <el-carousel
    height="200px"
    direction="vertical"
    motion-blur
    :autoplay="false"
  >
    <el-carousel-item v-for="item in 4" :key="item">
      <h3 text="2xl" justify="center">{{ item }}</h3>
    </el-carousel-item>
  </el-carousel>
</template>

<style scoped>
.demonstration {
  color: var(--el-text-color-secondary);
}

.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>
```

隐藏源代码

## 指示器 [​](#指示器)

可以将指示器的显示位置设置在容器外部

`indicator-position` 属性定义了指示器的位置。 默认情况下，它会显示在走马灯内部，设置为 `outside` 则会显示在外部；设置为 `none` 则不会显示指示器。

### 1

### 2

### 3

### 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2Fyb3VzZWwgaW5kaWNhdG9yLXBvc2l0aW9uPVwib3V0c2lkZVwiPlxuICAgIDxlbC1jYXJvdXNlbC1pdGVtIHYtZm9yPVwiaXRlbSBpbiA0XCIgOmtleT1cIml0ZW1cIj5cbiAgICAgIDxoMyB0ZXh0PVwiMnhsXCIganVzdGlmeT1cImNlbnRlclwiPnt7IGl0ZW0gfX08L2gzPlxuICAgIDwvZWwtY2Fyb3VzZWwtaXRlbT5cbiAgPC9lbC1jYXJvdXNlbD5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZWwtY2Fyb3VzZWxfX2l0ZW0gaDMge1xuICBkaXNwbGF5OiBmbGV4O1xuICBjb2xvcjogIzQ3NTY2OTtcbiAgb3BhY2l0eTogMC43NTtcbiAgbGluZS1oZWlnaHQ6IDMwMHB4O1xuICBtYXJnaW46IDA7XG59XG5cbi5lbC1jYXJvdXNlbF9faXRlbTpudGgtY2hpbGQoMm4pIHtcbiAgYmFja2dyb3VuZC1jb2xvcjogIzk5YTliZjtcbn1cblxuLmVsLWNhcm91c2VsX19pdGVtOm50aC1jaGlsZCgybiArIDEpIHtcbiAgYmFja2dyb3VuZC1jb2xvcjogI2QzZGNlNjtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/carousel/indicator.vue)_

vue

```
<template>
  <el-carousel indicator-position="outside">
    <el-carousel-item v-for="item in 4" :key="item">
      <h3 text="2xl" justify="center">{{ item }}</h3>
    </el-carousel-item>
  </el-carousel>
</template>

<style scoped>
.el-carousel__item h3 {
  display: flex;
  color: #475669;
  opacity: 0.75;
  line-height: 300px;
  margin: 0;
}

.el-carousel__item:nth-child(2n) {
  background-color: #99a9bf;
}

.el-carousel__item:nth-child(2n + 1) {
  background-color: #d3dce6;
}
</style>
```

隐藏源代码

## 切换箭头 [​](#切换箭头)

可以设置切换箭头的显示时机

`arrow` 属性定义了切换箭头的显示时机。 默认情况下，切换箭头只有在鼠标 hover 到走马灯上时才会显示。 若将 `arrow` 设置为 `always`，则会一直显示；设置为 `never`，则会一直隐藏。

### 1

### 2

### 3

### 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2Fyb3VzZWwgOmludGVydmFsPVwiNTAwMFwiIGFycm93PVwiYWx3YXlzXCI+XG4gICAgPGVsLWNhcm91c2VsLWl0ZW0gdi1mb3I9XCJpdGVtIGluIDRcIiA6a2V5PVwiaXRlbVwiPlxuICAgICAgPGgzIHRleHQ9XCIyeGxcIiBqdXN0aWZ5PVwiY2VudGVyXCI+e3sgaXRlbSB9fTwvaDM+XG4gICAgPC9lbC1jYXJvdXNlbC1pdGVtPlxuICA8L2VsLWNhcm91c2VsPlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlIHNjb3BlZD5cbi5lbC1jYXJvdXNlbF9faXRlbSBoMyB7XG4gIGNvbG9yOiAjNDc1NjY5O1xuICBvcGFjaXR5OiAwLjc1O1xuICBsaW5lLWhlaWdodDogMzAwcHg7XG4gIG1hcmdpbjogMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xufVxuXG4uZWwtY2Fyb3VzZWxfX2l0ZW06bnRoLWNoaWxkKDJuKSB7XG4gIGJhY2tncm91bmQtY29sb3I6ICM5OWE5YmY7XG59XG5cbi5lbC1jYXJvdXNlbF9faXRlbTpudGgtY2hpbGQoMm4gKyAxKSB7XG4gIGJhY2tncm91bmQtY29sb3I6ICNkM2RjZTY7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/carousel/arrows.vue)_

vue

```
<template>
  <el-carousel :interval="5000" arrow="always">
    <el-carousel-item v-for="item in 4" :key="item">
      <h3 text="2xl" justify="center">{{ item }}</h3>
    </el-carousel-item>
  </el-carousel>
</template>

<style scoped>
.el-carousel__item h3 {
  color: #475669;
  opacity: 0.75;
  line-height: 300px;
  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>
```

隐藏源代码

## 自动高度 [​](#自动高度)

当 `carousel` 的 `height` 设置为 `auto`时， `carousel` 的高度将根据子内容的高度自动设置

each carousel-item has a different height

### height 100px

### height 200px

### height 300px

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiYmxvY2sgdGV4dC1jZW50ZXJcIiBzdHlsZT1cImhlaWdodDogMzAwcHhcIj5cbiAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5lYWNoIGNhcm91c2VsLWl0ZW0gaGFzIGEgZGlmZmVyZW50IGhlaWdodDwvc3Bhbj5cbiAgICA8ZWwtY2Fyb3VzZWwgaGVpZ2h0PVwiYXV0b1wiIGF1dG9wbGF5PlxuICAgICAgPGVsLWNhcm91c2VsLWl0ZW0gc3R5bGU9XCJoZWlnaHQ6IDEwMHB4XCI+XG4gICAgICAgIDxoMyBjbGFzcz1cInNtYWxsIGp1c3RpZnktY2VudGVyXCIgdGV4dD1cIjJ4bFwiPmhlaWdodCAxMDBweDwvaDM+XG4gICAgICA8L2VsLWNhcm91c2VsLWl0ZW0+XG4gICAgICA8ZWwtY2Fyb3VzZWwtaXRlbSBzdHlsZT1cImhlaWdodDogMjAwcHhcIj5cbiAgICAgICAgPGgzIGNsYXNzPVwic21hbGwganVzdGlmeS1jZW50ZXJcIiB0ZXh0PVwiMnhsXCI+aGVpZ2h0IDIwMHB4PC9oMz5cbiAgICAgIDwvZWwtY2Fyb3VzZWwtaXRlbT5cbiAgICAgIDxlbC1jYXJvdXNlbC1pdGVtIHN0eWxlPVwiaGVpZ2h0OiAzMDBweFwiPlxuICAgICAgICA8aDMgY2xhc3M9XCJzbWFsbCBqdXN0aWZ5LWNlbnRlclwiIHRleHQ9XCIyeGxcIj5oZWlnaHQgMzAwcHg8L2gzPlxuICAgICAgPC9lbC1jYXJvdXNlbC1pdGVtPlxuICAgIDwvZWwtY2Fyb3VzZWw+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlIHNjb3BlZD5cbi5jYXJvdXNlbC1pdGVtIHtcbiAgY29sb3I6ICM0NzU2Njk7XG4gIG9wYWNpdHk6IDAuNzU7XG4gIG1hcmdpbjogMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xufVxuXG4uZWwtY2Fyb3VzZWxfX2l0ZW0gaDMge1xuICBjb2xvcjogIzQ3NTY2OTtcbiAgb3BhY2l0eTogMC43NTtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbiAgbWFyZ2luOiAwO1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG4gIGhlaWdodDogMTAwJTtcbn1cblxuLmVsLWNhcm91c2VsX19pdGVtOm50aC1jaGlsZCgybikge1xuICBiYWNrZ3JvdW5kLWNvbG9yOiAjOTlhOWJmO1xufVxuXG4uZWwtY2Fyb3VzZWxfX2l0ZW06bnRoLWNoaWxkKDJuICsgMSkge1xuICBiYWNrZ3JvdW5kLWNvbG9yOiAjZDNkY2U2O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/carousel/auto-height.vue)_

vue

```
<template>
  <div class="block text-center" style="height: 300px">
    <span class="demonstration">each carousel-item has a different height</span>
    <el-carousel height="auto" autoplay>
      <el-carousel-item style="height: 100px">
        <h3 class="small justify-center" text="2xl">height 100px</h3>
      </el-carousel-item>
      <el-carousel-item style="height: 200px">
        <h3 class="small justify-center" text="2xl">height 200px</h3>
      </el-carousel-item>
      <el-carousel-item style="height: 300px">
        <h3 class="small justify-center" text="2xl">height 300px</h3>
      </el-carousel-item>
    </el-carousel>
  </div>
</template>

<style scoped>
.carousel-item {
  color: #475669;
  opacity: 0.75;
  margin: 0;
  text-align: center;
}

.el-carousel__item h3 {
  color: #475669;
  opacity: 0.75;
  display: flex;
  align-items: center;
  margin: 0;
  text-align: center;
  height: 100%;
}

.el-carousel__item:nth-child(2n) {
  background-color: #99a9bf;
}

.el-carousel__item:nth-child(2n + 1) {
  background-color: #d3dce6;
}
</style>
```

隐藏源代码

## 卡片模式 [​](#卡片模式)

当页面宽度方向空间空余，但高度方向空间匮乏时，可使用卡片风格

将 `type` 属性设置为 `card` 即可启用卡片模式。 从交互上来说，卡片模式和一般模式的最大区别在于，卡片模式可以通过直接点击两侧的幻灯片进行切换。

### 1

### 2

### 3

### 4

### 5

### 6

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2Fyb3VzZWwgOmludGVydmFsPVwiNDAwMFwiIHR5cGU9XCJjYXJkXCIgaGVpZ2h0PVwiMjAwcHhcIj5cbiAgICA8ZWwtY2Fyb3VzZWwtaXRlbSB2LWZvcj1cIml0ZW0gaW4gNlwiIDprZXk9XCJpdGVtXCI+XG4gICAgICA8aDMgdGV4dD1cIjJ4bFwiIGp1c3RpZnk9XCJjZW50ZXJcIj57eyBpdGVtIH19PC9oMz5cbiAgICA8L2VsLWNhcm91c2VsLWl0ZW0+XG4gIDwvZWwtY2Fyb3VzZWw+XG48L3RlbXBsYXRlPlxuXG48c3R5bGUgc2NvcGVkPlxuLmVsLWNhcm91c2VsX19pdGVtIGgzIHtcbiAgY29sb3I6ICM0NzU2Njk7XG4gIG9wYWNpdHk6IDAuNzU7XG4gIGxpbmUtaGVpZ2h0OiAyMDBweDtcbiAgbWFyZ2luOiAwO1xuICB0ZXh0LWFsaWduOiBjZW50ZXI7XG59XG5cbi5lbC1jYXJvdXNlbF9faXRlbTpudGgtY2hpbGQoMm4pIHtcbiAgYmFja2dyb3VuZC1jb2xvcjogIzk5YTliZjtcbn1cblxuLmVsLWNhcm91c2VsX19pdGVtOm50aC1jaGlsZCgybiArIDEpIHtcbiAgYmFja2dyb3VuZC1jb2xvcjogI2QzZGNlNjtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/carousel/card.vue)_

vue

```
<template>
  <el-carousel :interval="4000" type="card" height="200px">
    <el-carousel-item v-for="item in 6" :key="item">
      <h3 text="2xl" justify="center">{{ item }}</h3>
    </el-carousel-item>
  </el-carousel>
</template>

<style scoped>
.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>
```

隐藏源代码

## 垂直排列 [​](#垂直排列)

默认情况下，方向 `direction` 为 水平 `horizontal`。 通过设置 `direction` 为 `vertical` 来让走马灯在垂直方向上显示。

normal vertical layout

### 1

### 2

### 3

### 4

card vertical layout

### 1

### 2

### 3

### 4

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8cCBjbGFzcz1cInRleHQtY2VudGVyIGRlbW9uc3RyYXRpb25cIj5ub3JtYWwgdmVydGljYWwgbGF5b3V0PC9wPlxuICA8ZWwtY2Fyb3VzZWwgaGVpZ2h0PVwiMjAwcHhcIiBkaXJlY3Rpb249XCJ2ZXJ0aWNhbFwiIDphdXRvcGxheT1cImZhbHNlXCI+XG4gICAgPGVsLWNhcm91c2VsLWl0ZW0gdi1mb3I9XCJpdGVtIGluIDRcIiA6a2V5PVwiaXRlbVwiPlxuICAgICAgPGgzIHRleHQ9XCIyeGxcIiBqdXN0aWZ5PVwiY2VudGVyXCI+e3sgaXRlbSB9fTwvaDM+XG4gICAgPC9lbC1jYXJvdXNlbC1pdGVtPlxuICA8L2VsLWNhcm91c2VsPlxuICA8cCBjbGFzcz1cInRleHQtY2VudGVyIGRlbW9uc3RyYXRpb25cIj5jYXJkIHZlcnRpY2FsIGxheW91dDwvcD5cbiAgPGVsLWNhcm91c2VsXG4gICAgaGVpZ2h0PVwiNDAwcHhcIlxuICAgIGRpcmVjdGlvbj1cInZlcnRpY2FsXCJcbiAgICB0eXBlPVwiY2FyZFwiXG4gICAgOmF1dG9wbGF5PVwiZmFsc2VcIlxuICA+XG4gICAgPGVsLWNhcm91c2VsLWl0ZW0gdi1mb3I9XCJpdGVtIGluIDRcIiA6a2V5PVwiaXRlbVwiPlxuICAgICAgPGgzIHRleHQ9XCIyeGxcIiBqdXN0aWZ5PVwiY2VudGVyXCI+e3sgaXRlbSB9fTwvaDM+XG4gICAgPC9lbC1jYXJvdXNlbC1pdGVtPlxuICA8L2VsLWNhcm91c2VsPlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlIHNjb3BlZD5cbi5lbC1jYXJvdXNlbF9faXRlbSBoMyB7XG4gIGNvbG9yOiAjNDc1NjY5O1xuICBvcGFjaXR5OiAwLjc1O1xuICBsaW5lLWhlaWdodDogMjAwcHg7XG4gIG1hcmdpbjogMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xufVxuXG4uZWwtY2Fyb3VzZWxfX2l0ZW06bnRoLWNoaWxkKDJuKSB7XG4gIGJhY2tncm91bmQtY29sb3I6ICM5OWE5YmY7XG59XG5cbi5lbC1jYXJvdXNlbF9faXRlbTpudGgtY2hpbGQoMm4gKyAxKSB7XG4gIGJhY2tncm91bmQtY29sb3I6ICNkM2RjZTY7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/carousel/vertical.vue)_

vue

```
<template>
  <p class="text-center demonstration">normal vertical layout</p>
  <el-carousel height="200px" direction="vertical" :autoplay="false">
    <el-carousel-item v-for="item in 4" :key="item">
      <h3 text="2xl" justify="center">{{ item }}</h3>
    </el-carousel-item>
  </el-carousel>
  <p class="text-center demonstration">card vertical layout</p>
  <el-carousel
    height="400px"
    direction="vertical"
    type="card"
    :autoplay="false"
  >
    <el-carousel-item v-for="item in 4" :key="item">
      <h3 text="2xl" justify="center">{{ item }}</h3>
    </el-carousel-item>
  </el-carousel>
</template>

<style scoped>
.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>
```

隐藏源代码

## Carousel API [​](#carousel-api)

### Carousel Attributes [​](#carousel-attributes)

| 属性名 | 说明 | 类型 | Default |
| --- | --- | --- | --- |
| height | carousel 的高度 | `string` | '' |
| initial-index | 初始状态激活的幻灯片的索引，从 0 开始 | `number` | 0 |
| trigger | 指示器的触发方式 | `enum` | hover |
| autoplay | 是否自动切换 | `boolean` | true |
| interval | 自动切换的时间间隔，单位为毫秒 | `number` | 3000 |
| indicator-position | 指示器的位置 | `enum` | '' |
| arrow | 切换箭头的显示时机 | `enum` | hover |
| type | carousel 的类型 | `enum` | '' |
| card-scale 2.7.8 | 当 type 为 card时，二级卡的缩放大小 | `number` | 0.83 |
| loop | 是否循环显示 | `boolean` | true |
| direction | 展示的方向 | `enum` | horizontal |
| pause-on-hover | 鼠标悬浮时暂停自动切换 | `boolean` | true |
| motion-blur 2.6.0 | 添加动态模糊以给走马灯注入活力和流畅性。 | `boolean` | false |

### Carousel Events [​](#carousel-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 当前展示的幻灯片切换时触发，它有两个参数， 一个是新幻灯片的索引，另一个是旧幻灯片的索引 | `Function` |

### Carousel Slots [​](#carousel-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | Carousel-Item |

### Carousel Exposes [​](#carousel-exposes)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| activeIndex 2.7.8 | 当前幻灯片的索引 | `number` |
| setActiveItem | 手动切换幻灯片，传入需要切换的幻灯片的索引，从 0 开始；或相应 `el-carousel-item` 的 `name` 属性值 | `Function` |
| prev | 切换至上一张幻灯片 | `Function` |
| next | 切换至下一张幻灯片 | `Function` |

## Carousel-Item API [​](#carousel-item-api)

### Carousel-Item Attributes [​](#carousel-item-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| name | 幻灯片的名字，可用作 `setActiveItem` 的参数 | `string` | '' |
| label | 该幻灯片所对应指示器的文本 | `string` / `number` | '' |

### Carousel-Item Slots [​](#carousel-item-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/carousel) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/carousel.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/carousel.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/69580637?v=4&size=64)](https://github.com/jevin98)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/57785259?v=4&size=64)](https://github.com/w2xi)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/78132554?v=4&size=64)](https://github.com/momei-LJM)[![](https://avatars.githubusercontent.com/u/26403700?v=4&size=64)](https://github.com/blesstosam)[![](https://avatars.githubusercontent.com/u/44160015?v=4&size=64)](https://github.com/JedediahXu)[![](https://avatars.githubusercontent.com/u/31238760?v=4&size=64)](https://github.com/cloydlau)[![](https://avatars.githubusercontent.com/u/102006695?v=4&size=64)](https://github.com/cuongle-hdwebsoft)[![](https://avatars.githubusercontent.com/u/30046649?v=4&size=64)](https://github.com/MrWeilian)[![](https://avatars.githubusercontent.com/u/73547598?v=4&size=64)](https://github.com/SaberA1ter)[![](https://avatars.githubusercontent.com/u/26755049?v=4&size=64)](https://github.com/qq282126990)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/39959340?v=4&size=64)](https://github.com/yonghui-wang)[![](https://avatars.githubusercontent.com/u/134276765?v=4&size=64)](https://github.com/zwgwf)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/45936772?v=4&size=64)](https://github.com/KawaiiZapic)[![](https://avatars.githubusercontent.com/u/2755933?v=4&size=64)](https://github.com/BiosSun)[![](https://avatars.githubusercontent.com/u/36007710?v=4&size=64)](https://github.com/sleepyfive)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/33687038?v=4&size=64)](https://github.com/guozi9999)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)

[Card 卡片](https://element-plus.org/zh-CN/component/card)

[Collapse 折叠面板](https://element-plus.org/zh-CN/component/collapse)




---
## [data/collapse] Collapse 折叠面板
> 官方文档: https://element-plus.org/zh-CN/component/collapse.html

---

# Collapse 折叠面板 [​](#collapse-折叠面板)

更新日志待解决

12

通过折叠面板收纳内容区域

## 基础用法 [​](#基础用法)

可同时展开多个面板，面板之间不影响

Consistency

Consistent with real life: in line with the process and logic of real life, and comply with languages and habits that the users are used to;

Consistent within interface: all elements should be consistent, such as: design style, icons and texts, position of elements, etc.

Feedback

Operation feedback: enable the users to clearly perceive their operations by style updates and interactive effects;

Visual feedback: reflect current state by updating or rearranging elements of the page.

Efficiency

Simplify the process: keep operating process simple and intuitive;

Definite and clear: enunciate your intentions clearly so that the users can quickly understand and make decisions;

Easy to identify: the interface should be straightforward, which helps the users to identify and frees them from memorizing and recalling.

Controllability

Decision making: giving advice about operations is acceptable, but do not make decisions for the users;

Controlled consequences: users should be granted the freedom to operate, including canceling, aborting or terminating current operation.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1jb2xsYXBzZVwiPlxuICAgIDxlbC1jb2xsYXBzZSB2LW1vZGVsPVwiYWN0aXZlTmFtZXNcIiBAY2hhbmdlPVwiaGFuZGxlQ2hhbmdlXCI+XG4gICAgICA8ZWwtY29sbGFwc2UtaXRlbSB0aXRsZT1cIkNvbnNpc3RlbmN5XCIgbmFtZT1cIjFcIj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBDb25zaXN0ZW50IHdpdGggcmVhbCBsaWZlOiBpbiBsaW5lIHdpdGggdGhlIHByb2Nlc3MgYW5kIGxvZ2ljIG9mIHJlYWxcbiAgICAgICAgICBsaWZlLCBhbmQgY29tcGx5IHdpdGggbGFuZ3VhZ2VzIGFuZCBoYWJpdHMgdGhhdCB0aGUgdXNlcnMgYXJlIHVzZWQgdG87XG4gICAgICAgIDwvZGl2PlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIENvbnNpc3RlbnQgd2l0aGluIGludGVyZmFjZTogYWxsIGVsZW1lbnRzIHNob3VsZCBiZSBjb25zaXN0ZW50LCBzdWNoXG4gICAgICAgICAgYXM6IGRlc2lnbiBzdHlsZSwgaWNvbnMgYW5kIHRleHRzLCBwb3NpdGlvbiBvZiBlbGVtZW50cywgZXRjLlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZWwtY29sbGFwc2UtaXRlbT5cbiAgICAgIDxlbC1jb2xsYXBzZS1pdGVtIHRpdGxlPVwiRmVlZGJhY2tcIiBuYW1lPVwiMlwiPlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIE9wZXJhdGlvbiBmZWVkYmFjazogZW5hYmxlIHRoZSB1c2VycyB0byBjbGVhcmx5IHBlcmNlaXZlIHRoZWlyXG4gICAgICAgICAgb3BlcmF0aW9ucyBieSBzdHlsZSB1cGRhdGVzIGFuZCBpbnRlcmFjdGl2ZSBlZmZlY3RzO1xuICAgICAgICA8L2Rpdj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBWaXN1YWwgZmVlZGJhY2s6IHJlZmxlY3QgY3VycmVudCBzdGF0ZSBieSB1cGRhdGluZyBvciByZWFycmFuZ2luZ1xuICAgICAgICAgIGVsZW1lbnRzIG9mIHRoZSBwYWdlLlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZWwtY29sbGFwc2UtaXRlbT5cbiAgICAgIDxlbC1jb2xsYXBzZS1pdGVtIHRpdGxlPVwiRWZmaWNpZW5jeVwiIG5hbWU9XCIzXCI+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgU2ltcGxpZnkgdGhlIHByb2Nlc3M6IGtlZXAgb3BlcmF0aW5nIHByb2Nlc3Mgc2ltcGxlIGFuZCBpbnR1aXRpdmU7XG4gICAgICAgIDwvZGl2PlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIERlZmluaXRlIGFuZCBjbGVhcjogZW51bmNpYXRlIHlvdXIgaW50ZW50aW9ucyBjbGVhcmx5IHNvIHRoYXQgdGhlXG4gICAgICAgICAgdXNlcnMgY2FuIHF1aWNrbHkgdW5kZXJzdGFuZCBhbmQgbWFrZSBkZWNpc2lvbnM7XG4gICAgICAgIDwvZGl2PlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIEVhc3kgdG8gaWRlbnRpZnk6IHRoZSBpbnRlcmZhY2Ugc2hvdWxkIGJlIHN0cmFpZ2h0Zm9yd2FyZCwgd2hpY2ggaGVscHNcbiAgICAgICAgICB0aGUgdXNlcnMgdG8gaWRlbnRpZnkgYW5kIGZyZWVzIHRoZW0gZnJvbSBtZW1vcml6aW5nIGFuZCByZWNhbGxpbmcuXG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jb2xsYXBzZS1pdGVtPlxuICAgICAgPGVsLWNvbGxhcHNlLWl0ZW0gdGl0bGU9XCJDb250cm9sbGFiaWxpdHlcIiBuYW1lPVwiNFwiPlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIERlY2lzaW9uIG1ha2luZzogZ2l2aW5nIGFkdmljZSBhYm91dCBvcGVyYXRpb25zIGlzIGFjY2VwdGFibGUsIGJ1dCBkb1xuICAgICAgICAgIG5vdCBtYWtlIGRlY2lzaW9ucyBmb3IgdGhlIHVzZXJzO1xuICAgICAgICA8L2Rpdj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBDb250cm9sbGVkIGNvbnNlcXVlbmNlczogdXNlcnMgc2hvdWxkIGJlIGdyYW50ZWQgdGhlIGZyZWVkb20gdG9cbiAgICAgICAgICBvcGVyYXRlLCBpbmNsdWRpbmcgY2FuY2VsaW5nLCBhYm9ydGluZyBvciB0ZXJtaW5hdGluZyBjdXJyZW50XG4gICAgICAgICAgb3BlcmF0aW9uLlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZWwtY29sbGFwc2UtaXRlbT5cbiAgICA8L2VsLWNvbGxhcHNlPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgQ29sbGFwc2VNb2RlbFZhbHVlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBhY3RpdmVOYW1lcyA9IHJlZihbJzEnXSlcbmNvbnN0IGhhbmRsZUNoYW5nZSA9ICh2YWw6IENvbGxhcHNlTW9kZWxWYWx1ZSkgPT4ge1xuICBjb25zb2xlLmxvZyh2YWwpXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/collapse/basic.vue)_

vue

```
<template>
  <div class="demo-collapse">
    <el-collapse v-model="activeNames" @change="handleChange">
      <el-collapse-item title="Consistency" name="1">
        <div>
          Consistent with real life: in line with the process and logic of real
          life, and comply with languages and habits that the users are used to;
        </div>
        <div>
          Consistent within interface: all elements should be consistent, such
          as: design style, icons and texts, position of elements, etc.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Feedback" name="2">
        <div>
          Operation feedback: enable the users to clearly perceive their
          operations by style updates and interactive effects;
        </div>
        <div>
          Visual feedback: reflect current state by updating or rearranging
          elements of the page.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Efficiency" name="3">
        <div>
          Simplify the process: keep operating process simple and intuitive;
        </div>
        <div>
          Definite and clear: enunciate your intentions clearly so that the
          users can quickly understand and make decisions;
        </div>
        <div>
          Easy to identify: the interface should be straightforward, which helps
          the users to identify and frees them from memorizing and recalling.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Controllability" name="4">
        <div>
          Decision making: giving advice about operations is acceptable, but do
          not make decisions for the users;
        </div>
        <div>
          Controlled consequences: users should be granted the freedom to
          operate, including canceling, aborting or terminating current
          operation.
        </div>
      </el-collapse-item>
    </el-collapse>
  </div>
</template>

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

import type { CollapseModelValue } from 'element-plus'

const activeNames = ref(['1'])
const handleChange = (val: CollapseModelValue) => {
  console.log(val)
}
</script>
```

隐藏源代码

## 手风琴效果 [​](#手风琴效果)

每次只能展开一个面板

通过 `accordion` 属性来设置是否以手风琴模式显示。

Consistency

Consistent with real life: in line with the process and logic of real life, and comply with languages and habits that the users are used to;

Consistent within interface: all elements should be consistent, such as: design style, icons and texts, position of elements, etc.

Feedback

Operation feedback: enable the users to clearly perceive their operations by style updates and interactive effects;

Visual feedback: reflect current state by updating or rearranging elements of the page.

Efficiency

Simplify the process: keep operating process simple and intuitive;

Definite and clear: enunciate your intentions clearly so that the users can quickly understand and make decisions;

Easy to identify: the interface should be straightforward, which helps the users to identify and frees them from memorizing and recalling.

Controllability

Decision making: giving advices about operations is acceptable, but do not make decisions for the users;

Controlled consequences: users should be granted the freedom to operate, including canceling, aborting or terminating current operation.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1jb2xsYXBzZVwiPlxuICAgIDxlbC1jb2xsYXBzZSB2LW1vZGVsPVwiYWN0aXZlTmFtZVwiIGFjY29yZGlvbj5cbiAgICAgIDxlbC1jb2xsYXBzZS1pdGVtIHRpdGxlPVwiQ29uc2lzdGVuY3lcIiBuYW1lPVwiMVwiPlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIENvbnNpc3RlbnQgd2l0aCByZWFsIGxpZmU6IGluIGxpbmUgd2l0aCB0aGUgcHJvY2VzcyBhbmQgbG9naWMgb2YgcmVhbFxuICAgICAgICAgIGxpZmUsIGFuZCBjb21wbHkgd2l0aCBsYW5ndWFnZXMgYW5kIGhhYml0cyB0aGF0IHRoZSB1c2VycyBhcmUgdXNlZCB0bztcbiAgICAgICAgPC9kaXY+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgQ29uc2lzdGVudCB3aXRoaW4gaW50ZXJmYWNlOiBhbGwgZWxlbWVudHMgc2hvdWxkIGJlIGNvbnNpc3RlbnQsIHN1Y2hcbiAgICAgICAgICBhczogZGVzaWduIHN0eWxlLCBpY29ucyBhbmQgdGV4dHMsIHBvc2l0aW9uIG9mIGVsZW1lbnRzLCBldGMuXG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jb2xsYXBzZS1pdGVtPlxuICAgICAgPGVsLWNvbGxhcHNlLWl0ZW0gdGl0bGU9XCJGZWVkYmFja1wiIG5hbWU9XCIyXCI+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgT3BlcmF0aW9uIGZlZWRiYWNrOiBlbmFibGUgdGhlIHVzZXJzIHRvIGNsZWFybHkgcGVyY2VpdmUgdGhlaXJcbiAgICAgICAgICBvcGVyYXRpb25zIGJ5IHN0eWxlIHVwZGF0ZXMgYW5kIGludGVyYWN0aXZlIGVmZmVjdHM7XG4gICAgICAgIDwvZGl2PlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIFZpc3VhbCBmZWVkYmFjazogcmVmbGVjdCBjdXJyZW50IHN0YXRlIGJ5IHVwZGF0aW5nIG9yIHJlYXJyYW5naW5nXG4gICAgICAgICAgZWxlbWVudHMgb2YgdGhlIHBhZ2UuXG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jb2xsYXBzZS1pdGVtPlxuICAgICAgPGVsLWNvbGxhcHNlLWl0ZW0gdGl0bGU9XCJFZmZpY2llbmN5XCIgbmFtZT1cIjNcIj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBTaW1wbGlmeSB0aGUgcHJvY2Vzczoga2VlcCBvcGVyYXRpbmcgcHJvY2VzcyBzaW1wbGUgYW5kIGludHVpdGl2ZTtcbiAgICAgICAgPC9kaXY+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgRGVmaW5pdGUgYW5kIGNsZWFyOiBlbnVuY2lhdGUgeW91ciBpbnRlbnRpb25zIGNsZWFybHkgc28gdGhhdCB0aGVcbiAgICAgICAgICB1c2VycyBjYW4gcXVpY2tseSB1bmRlcnN0YW5kIGFuZCBtYWtlIGRlY2lzaW9ucztcbiAgICAgICAgPC9kaXY+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgRWFzeSB0byBpZGVudGlmeTogdGhlIGludGVyZmFjZSBzaG91bGQgYmUgc3RyYWlnaHRmb3J3YXJkLCB3aGljaCBoZWxwc1xuICAgICAgICAgIHRoZSB1c2VycyB0byBpZGVudGlmeSBhbmQgZnJlZXMgdGhlbSBmcm9tIG1lbW9yaXppbmcgYW5kIHJlY2FsbGluZy5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2VsLWNvbGxhcHNlLWl0ZW0+XG4gICAgICA8ZWwtY29sbGFwc2UtaXRlbSB0aXRsZT1cIkNvbnRyb2xsYWJpbGl0eVwiIG5hbWU9XCI0XCI+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgRGVjaXNpb24gbWFraW5nOiBnaXZpbmcgYWR2aWNlcyBhYm91dCBvcGVyYXRpb25zIGlzIGFjY2VwdGFibGUsIGJ1dCBkb1xuICAgICAgICAgIG5vdCBtYWtlIGRlY2lzaW9ucyBmb3IgdGhlIHVzZXJzO1xuICAgICAgICA8L2Rpdj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBDb250cm9sbGVkIGNvbnNlcXVlbmNlczogdXNlcnMgc2hvdWxkIGJlIGdyYW50ZWQgdGhlIGZyZWVkb20gdG9cbiAgICAgICAgICBvcGVyYXRlLCBpbmNsdWRpbmcgY2FuY2VsaW5nLCBhYm9ydGluZyBvciB0ZXJtaW5hdGluZyBjdXJyZW50XG4gICAgICAgICAgb3BlcmF0aW9uLlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZWwtY29sbGFwc2UtaXRlbT5cbiAgICA8L2VsLWNvbGxhcHNlPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGFjdGl2ZU5hbWUgPSByZWYoJzEnKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/collapse/accordion.vue)_

vue

```
<template>
  <div class="demo-collapse">
    <el-collapse v-model="activeName" accordion>
      <el-collapse-item title="Consistency" name="1">
        <div>
          Consistent with real life: in line with the process and logic of real
          life, and comply with languages and habits that the users are used to;
        </div>
        <div>
          Consistent within interface: all elements should be consistent, such
          as: design style, icons and texts, position of elements, etc.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Feedback" name="2">
        <div>
          Operation feedback: enable the users to clearly perceive their
          operations by style updates and interactive effects;
        </div>
        <div>
          Visual feedback: reflect current state by updating or rearranging
          elements of the page.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Efficiency" name="3">
        <div>
          Simplify the process: keep operating process simple and intuitive;
        </div>
        <div>
          Definite and clear: enunciate your intentions clearly so that the
          users can quickly understand and make decisions;
        </div>
        <div>
          Easy to identify: the interface should be straightforward, which helps
          the users to identify and frees them from memorizing and recalling.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Controllability" name="4">
        <div>
          Decision making: giving advices about operations is acceptable, but do
          not make decisions for the users;
        </div>
        <div>
          Controlled consequences: users should be granted the freedom to
          operate, including canceling, aborting or terminating current
          operation.
        </div>
      </el-collapse-item>
    </el-collapse>
  </div>
</template>

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

const activeName = ref('1')
</script>
```

隐藏源代码

## 自定义面板标题 [​](#自定义面板标题)

除了可以通过 `title` 属性以外，还可以通过具名 `slot` 来实现自定义面板的标题内容，以实现增加图标等效果。

TIP

从版本 2.9.10开始， `title` 插槽提供一个 `isActive` 属性，显示当前折叠项是否活跃。

Consistency

Consistent with real life: in line with the process and logic of real life, and comply with languages and habits that the users are used to;

Consistent within interface: all elements should be consistent, such as: design style, icons and texts, position of elements, etc.

Feedback

Operation feedback: enable the users to clearly perceive their operations by style updates and interactive effects;

Visual feedback: reflect current state by updating or rearranging elements of the page.

Efficiency

Simplify the process: keep operating process simple and intuitive;

Definite and clear: enunciate your intentions clearly so that the users can quickly understand and make decisions;

Easy to identify: the interface should be straightforward, which helps the users to identify and frees them from memorizing and recalling.

Controllability

Decision making: giving advices about operations is acceptable, but do not make decisions for the users;

Controlled consequences: users should be granted the freedom to operate, including canceling, aborting or terminating current operation.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1jb2xsYXBzZVwiPlxuICAgIDxlbC1jb2xsYXBzZSBhY2NvcmRpb24+XG4gICAgICA8ZWwtY29sbGFwc2UtaXRlbSBuYW1lPVwiMVwiPlxuICAgICAgICA8dGVtcGxhdGUgI3RpdGxlPVwieyBpc0FjdGl2ZSB9XCI+XG4gICAgICAgICAgPGRpdiA6Y2xhc3M9XCJbJ3RpdGxlLXdyYXBwZXInLCB7ICdpcy1hY3RpdmUnOiBpc0FjdGl2ZSB9XVwiPlxuICAgICAgICAgICAgQ29uc2lzdGVuY3lcbiAgICAgICAgICAgIDxlbC1pY29uIGNsYXNzPVwiaGVhZGVyLWljb25cIj5cbiAgICAgICAgICAgICAgPGluZm8tZmlsbGVkIC8+XG4gICAgICAgICAgICA8L2VsLWljb24+XG4gICAgICAgICAgPC9kaXY+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgQ29uc2lzdGVudCB3aXRoIHJlYWwgbGlmZTogaW4gbGluZSB3aXRoIHRoZSBwcm9jZXNzIGFuZCBsb2dpYyBvZiByZWFsXG4gICAgICAgICAgbGlmZSwgYW5kIGNvbXBseSB3aXRoIGxhbmd1YWdlcyBhbmQgaGFiaXRzIHRoYXQgdGhlIHVzZXJzIGFyZSB1c2VkIHRvO1xuICAgICAgICA8L2Rpdj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBDb25zaXN0ZW50IHdpdGhpbiBpbnRlcmZhY2U6IGFsbCBlbGVtZW50cyBzaG91bGQgYmUgY29uc2lzdGVudCwgc3VjaFxuICAgICAgICAgIGFzOiBkZXNpZ24gc3R5bGUsIGljb25zIGFuZCB0ZXh0cywgcG9zaXRpb24gb2YgZWxlbWVudHMsIGV0Yy5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2VsLWNvbGxhcHNlLWl0ZW0+XG4gICAgICA8ZWwtY29sbGFwc2UtaXRlbSB0aXRsZT1cIkZlZWRiYWNrXCIgbmFtZT1cIjJcIj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBPcGVyYXRpb24gZmVlZGJhY2s6IGVuYWJsZSB0aGUgdXNlcnMgdG8gY2xlYXJseSBwZXJjZWl2ZSB0aGVpclxuICAgICAgICAgIG9wZXJhdGlvbnMgYnkgc3R5bGUgdXBkYXRlcyBhbmQgaW50ZXJhY3RpdmUgZWZmZWN0cztcbiAgICAgICAgPC9kaXY+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgVmlzdWFsIGZlZWRiYWNrOiByZWZsZWN0IGN1cnJlbnQgc3RhdGUgYnkgdXBkYXRpbmcgb3IgcmVhcnJhbmdpbmdcbiAgICAgICAgICBlbGVtZW50cyBvZiB0aGUgcGFnZS5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2VsLWNvbGxhcHNlLWl0ZW0+XG4gICAgICA8ZWwtY29sbGFwc2UtaXRlbSB0aXRsZT1cIkVmZmljaWVuY3lcIiBuYW1lPVwiM1wiPlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIFNpbXBsaWZ5IHRoZSBwcm9jZXNzOiBrZWVwIG9wZXJhdGluZyBwcm9jZXNzIHNpbXBsZSBhbmQgaW50dWl0aXZlO1xuICAgICAgICA8L2Rpdj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBEZWZpbml0ZSBhbmQgY2xlYXI6IGVudW5jaWF0ZSB5b3VyIGludGVudGlvbnMgY2xlYXJseSBzbyB0aGF0IHRoZVxuICAgICAgICAgIHVzZXJzIGNhbiBxdWlja2x5IHVuZGVyc3RhbmQgYW5kIG1ha2UgZGVjaXNpb25zO1xuICAgICAgICA8L2Rpdj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBFYXN5IHRvIGlkZW50aWZ5OiB0aGUgaW50ZXJmYWNlIHNob3VsZCBiZSBzdHJhaWdodGZvcndhcmQsIHdoaWNoIGhlbHBzXG4gICAgICAgICAgdGhlIHVzZXJzIHRvIGlkZW50aWZ5IGFuZCBmcmVlcyB0aGVtIGZyb20gbWVtb3JpemluZyBhbmQgcmVjYWxsaW5nLlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZWwtY29sbGFwc2UtaXRlbT5cbiAgICAgIDxlbC1jb2xsYXBzZS1pdGVtIHRpdGxlPVwiQ29udHJvbGxhYmlsaXR5XCIgbmFtZT1cIjRcIj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBEZWNpc2lvbiBtYWtpbmc6IGdpdmluZyBhZHZpY2VzIGFib3V0IG9wZXJhdGlvbnMgaXMgYWNjZXB0YWJsZSwgYnV0IGRvXG4gICAgICAgICAgbm90IG1ha2UgZGVjaXNpb25zIGZvciB0aGUgdXNlcnM7XG4gICAgICAgIDwvZGl2PlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIENvbnRyb2xsZWQgY29uc2VxdWVuY2VzOiB1c2VycyBzaG91bGQgYmUgZ3JhbnRlZCB0aGUgZnJlZWRvbSB0b1xuICAgICAgICAgIG9wZXJhdGUsIGluY2x1ZGluZyBjYW5jZWxpbmcsIGFib3J0aW5nIG9yIHRlcm1pbmF0aW5nIGN1cnJlbnRcbiAgICAgICAgICBvcGVyYXRpb24uXG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jb2xsYXBzZS1pdGVtPlxuICAgIDwvZWwtY29sbGFwc2U+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IEluZm9GaWxsZWQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLnRpdGxlLXdyYXBwZXIge1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBnYXA6IDRweDtcbn1cblxuLnRpdGxlLXdyYXBwZXIuaXMtYWN0aXZlIHtcbiAgY29sb3I6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/collapse/customization.vue)_

vue

```
<template>
  <div class="demo-collapse">
    <el-collapse accordion>
      <el-collapse-item name="1">
        <template #title="{ isActive }">
          <div :class="['title-wrapper', { 'is-active': isActive }]">
            Consistency
            <el-icon class="header-icon">
              <info-filled />
            </el-icon>
          </div>
        </template>
        <div>
          Consistent with real life: in line with the process and logic of real
          life, and comply with languages and habits that the users are used to;
        </div>
        <div>
          Consistent within interface: all elements should be consistent, such
          as: design style, icons and texts, position of elements, etc.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Feedback" name="2">
        <div>
          Operation feedback: enable the users to clearly perceive their
          operations by style updates and interactive effects;
        </div>
        <div>
          Visual feedback: reflect current state by updating or rearranging
          elements of the page.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Efficiency" name="3">
        <div>
          Simplify the process: keep operating process simple and intuitive;
        </div>
        <div>
          Definite and clear: enunciate your intentions clearly so that the
          users can quickly understand and make decisions;
        </div>
        <div>
          Easy to identify: the interface should be straightforward, which helps
          the users to identify and frees them from memorizing and recalling.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Controllability" name="4">
        <div>
          Decision making: giving advices about operations is acceptable, but do
          not make decisions for the users;
        </div>
        <div>
          Controlled consequences: users should be granted the freedom to
          operate, including canceling, aborting or terminating current
          operation.
        </div>
      </el-collapse-item>
    </el-collapse>
  </div>
</template>

<script setup lang="ts">
import { InfoFilled } from '@element-plus/icons-vue'
</script>

<style scoped>
.title-wrapper {
  display: flex;
  align-items: center;
  gap: 4px;
}

.title-wrapper.is-active {
  color: var(--el-color-primary);
}
</style>
```

隐藏源代码

## 自定义图标 2.8.3 [​](#自定义图标)

除了使用 `icon` 属性外，您还可以自定义面板项目图标，从而添加自定义内容。

Consistency

Consistent with real life: in line with the process and logic of real life, and comply with languages and habits that the users are used to;

Consistent within interface: all elements should be consistent, such as: design style, icons and texts, position of elements, etc.

FeedbackCollapsed

Operation feedback: enable the users to clearly perceive their operations by style updates and interactive effects;

Visual feedback: reflect current state by updating or rearranging elements of the page.

Efficiency

Simplify the process: keep operating process simple and intuitive;

Definite and clear: enunciate your intentions clearly so that the users can quickly understand and make decisions;

Easy to identify: the interface should be straightforward, which helps the users to identify and frees them from memorizing and recalling.

Controllability

Decision making: giving advices about operations is acceptable, but do not make decisions for the users;

Controlled consequences: users should be granted the freedom to operate, including canceling, aborting or terminating current operation.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1jb2xsYXBzZVwiPlxuICAgIDxlbC1jb2xsYXBzZSB2LW1vZGVsPVwiYWN0aXZlTmFtZXNcIiBAY2hhbmdlPVwiaGFuZGxlQ2hhbmdlXCI+XG4gICAgICA8ZWwtY29sbGFwc2UtaXRlbSB0aXRsZT1cIkNvbnNpc3RlbmN5XCIgbmFtZT1cIjFcIiA6aWNvbj1cIkNhcmV0UmlnaHRcIj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBDb25zaXN0ZW50IHdpdGggcmVhbCBsaWZlOiBpbiBsaW5lIHdpdGggdGhlIHByb2Nlc3MgYW5kIGxvZ2ljIG9mIHJlYWxcbiAgICAgICAgICBsaWZlLCBhbmQgY29tcGx5IHdpdGggbGFuZ3VhZ2VzIGFuZCBoYWJpdHMgdGhhdCB0aGUgdXNlcnMgYXJlIHVzZWQgdG87XG4gICAgICAgIDwvZGl2PlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIENvbnNpc3RlbnQgd2l0aGluIGludGVyZmFjZTogYWxsIGVsZW1lbnRzIHNob3VsZCBiZSBjb25zaXN0ZW50LCBzdWNoXG4gICAgICAgICAgYXM6IGRlc2lnbiBzdHlsZSwgaWNvbnMgYW5kIHRleHRzLCBwb3NpdGlvbiBvZiBlbGVtZW50cywgZXRjLlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZWwtY29sbGFwc2UtaXRlbT5cbiAgICAgIDxlbC1jb2xsYXBzZS1pdGVtIHRpdGxlPVwiRmVlZGJhY2tcIiBuYW1lPVwiMlwiPlxuICAgICAgICA8dGVtcGxhdGUgI2ljb249XCJ7IGlzQWN0aXZlIH1cIj5cbiAgICAgICAgICA8c3BhbiBjbGFzcz1cImljb24tZWxlXCI+XG4gICAgICAgICAgICB7eyBpc0FjdGl2ZSA/ICdFeHBhbmRlZCcgOiAnQ29sbGFwc2VkJyB9fVxuICAgICAgICAgIDwvc3Bhbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBPcGVyYXRpb24gZmVlZGJhY2s6IGVuYWJsZSB0aGUgdXNlcnMgdG8gY2xlYXJseSBwZXJjZWl2ZSB0aGVpclxuICAgICAgICAgIG9wZXJhdGlvbnMgYnkgc3R5bGUgdXBkYXRlcyBhbmQgaW50ZXJhY3RpdmUgZWZmZWN0cztcbiAgICAgICAgPC9kaXY+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgVmlzdWFsIGZlZWRiYWNrOiByZWZsZWN0IGN1cnJlbnQgc3RhdGUgYnkgdXBkYXRpbmcgb3IgcmVhcnJhbmdpbmdcbiAgICAgICAgICBlbGVtZW50cyBvZiB0aGUgcGFnZS5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2VsLWNvbGxhcHNlLWl0ZW0+XG4gICAgICA8ZWwtY29sbGFwc2UtaXRlbSB0aXRsZT1cIkVmZmljaWVuY3lcIiBuYW1lPVwiM1wiPlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIFNpbXBsaWZ5IHRoZSBwcm9jZXNzOiBrZWVwIG9wZXJhdGluZyBwcm9jZXNzIHNpbXBsZSBhbmQgaW50dWl0aXZlO1xuICAgICAgICA8L2Rpdj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBEZWZpbml0ZSBhbmQgY2xlYXI6IGVudW5jaWF0ZSB5b3VyIGludGVudGlvbnMgY2xlYXJseSBzbyB0aGF0IHRoZVxuICAgICAgICAgIHVzZXJzIGNhbiBxdWlja2x5IHVuZGVyc3RhbmQgYW5kIG1ha2UgZGVjaXNpb25zO1xuICAgICAgICA8L2Rpdj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBFYXN5IHRvIGlkZW50aWZ5OiB0aGUgaW50ZXJmYWNlIHNob3VsZCBiZSBzdHJhaWdodGZvcndhcmQsIHdoaWNoIGhlbHBzXG4gICAgICAgICAgdGhlIHVzZXJzIHRvIGlkZW50aWZ5IGFuZCBmcmVlcyB0aGVtIGZyb20gbWVtb3JpemluZyBhbmQgcmVjYWxsaW5nLlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZWwtY29sbGFwc2UtaXRlbT5cbiAgICAgIDxlbC1jb2xsYXBzZS1pdGVtIHRpdGxlPVwiQ29udHJvbGxhYmlsaXR5XCIgbmFtZT1cIjRcIj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBEZWNpc2lvbiBtYWtpbmc6IGdpdmluZyBhZHZpY2VzIGFib3V0IG9wZXJhdGlvbnMgaXMgYWNjZXB0YWJsZSwgYnV0IGRvXG4gICAgICAgICAgbm90IG1ha2UgZGVjaXNpb25zIGZvciB0aGUgdXNlcnM7XG4gICAgICAgIDwvZGl2PlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIENvbnRyb2xsZWQgY29uc2VxdWVuY2VzOiB1c2VycyBzaG91bGQgYmUgZ3JhbnRlZCB0aGUgZnJlZWRvbSB0b1xuICAgICAgICAgIG9wZXJhdGUsIGluY2x1ZGluZyBjYW5jZWxpbmcsIGFib3J0aW5nIG9yIHRlcm1pbmF0aW5nIGN1cnJlbnRcbiAgICAgICAgICBvcGVyYXRpb24uXG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jb2xsYXBzZS1pdGVtPlxuICAgIDwvZWwtY29sbGFwc2U+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IENhcmV0UmlnaHQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuaW1wb3J0IHR5cGUgeyBDb2xsYXBzZU1vZGVsVmFsdWUgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGFjdGl2ZU5hbWVzID0gcmVmKFsnMSddKVxuY29uc3QgaGFuZGxlQ2hhbmdlID0gKHZhbDogQ29sbGFwc2VNb2RlbFZhbHVlKSA9PiB7XG4gIGNvbnNvbGUubG9nKHZhbClcbn1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmljb24tZWxlIHtcbiAgbWFyZ2luOiAwIDhweCAwIGF1dG87XG4gIGNvbG9yOiAjNDA5ZWZmO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/collapse/custom-icon.vue)_

vue

```
<template>
  <div class="demo-collapse">
    <el-collapse v-model="activeNames" @change="handleChange">
      <el-collapse-item title="Consistency" name="1" :icon="CaretRight">
        <div>
          Consistent with real life: in line with the process and logic of real
          life, and comply with languages and habits that the users are used to;
        </div>
        <div>
          Consistent within interface: all elements should be consistent, such
          as: design style, icons and texts, position of elements, etc.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Feedback" name="2">
        <template #icon="{ isActive }">
          <span class="icon-ele">
            {{ isActive ? 'Expanded' : 'Collapsed' }}
          </span>
        </template>
        <div>
          Operation feedback: enable the users to clearly perceive their
          operations by style updates and interactive effects;
        </div>
        <div>
          Visual feedback: reflect current state by updating or rearranging
          elements of the page.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Efficiency" name="3">
        <div>
          Simplify the process: keep operating process simple and intuitive;
        </div>
        <div>
          Definite and clear: enunciate your intentions clearly so that the
          users can quickly understand and make decisions;
        </div>
        <div>
          Easy to identify: the interface should be straightforward, which helps
          the users to identify and frees them from memorizing and recalling.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Controllability" name="4">
        <div>
          Decision making: giving advices about operations is acceptable, but do
          not make decisions for the users;
        </div>
        <div>
          Controlled consequences: users should be granted the freedom to
          operate, including canceling, aborting or terminating current
          operation.
        </div>
      </el-collapse-item>
    </el-collapse>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { CaretRight } from '@element-plus/icons-vue'

import type { CollapseModelValue } from 'element-plus'

const activeNames = ref(['1'])
const handleChange = (val: CollapseModelValue) => {
  console.log(val)
}
</script>

<style scoped>
.icon-ele {
  margin: 0 8px 0 auto;
  color: #409eff;
}
</style>
```

隐藏源代码

## 自定义图标位置 2.9.10 [​](#自定义图标位置)

使用 `expand-icon-position` 属性，您可以自定义图标位置。

expand icon position:

leftright

Consistency

Consistent with real life: in line with the process and logic of real life, and comply with languages and habits that the users are used to;

Consistent within interface: all elements should be consistent, such as: design style, icons and texts, position of elements, etc.

Feedback

Operation feedback: enable the users to clearly perceive their operations by style updates and interactive effects;

Visual feedback: reflect current state by updating or rearranging elements of the page.

Efficiency

Simplify the process: keep operating process simple and intuitive;

Definite and clear: enunciate your intentions clearly so that the users can quickly understand and make decisions;

Easy to identify: the interface should be straightforward, which helps the users to identify and frees them from memorizing and recalling.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1jb2xsYXBzZS1wb3NpdGlvblwiPlxuICAgIDxkaXYgY2xhc3M9XCJmbGV4IGl0ZW1zLWNlbnRlciBtYi00XCI+XG4gICAgICA8c3BhbiBjbGFzcz1cIm1yLTRcIj5leHBhbmQgaWNvbiBwb3NpdGlvbjogPC9zcGFuPlxuICAgICAgPGVsLXN3aXRjaFxuICAgICAgICB2LW1vZGVsPVwicG9zaXRpb25cIlxuICAgICAgICBpbmFjdGl2ZS12YWx1ZT1cImxlZnRcIlxuICAgICAgICBhY3RpdmUtdmFsdWU9XCJyaWdodFwiXG4gICAgICAgIGluYWN0aXZlLXRleHQ9XCJsZWZ0XCJcbiAgICAgICAgYWN0aXZlLXRleHQ9XCJyaWdodFwiXG4gICAgICAgIHN0eWxlPVwiLS1lbC1zd2l0Y2gtb2ZmLWNvbG9yOiAjODhiOGZlXCJcbiAgICAgIC8+XG4gICAgPC9kaXY+XG5cbiAgICA8ZWwtY29sbGFwc2UgOmV4cGFuZC1pY29uLXBvc2l0aW9uPVwicG9zaXRpb25cIj5cbiAgICAgIDxlbC1jb2xsYXBzZS1pdGVtIHRpdGxlPVwiQ29uc2lzdGVuY3lcIiBuYW1lPVwiMVwiPlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIENvbnNpc3RlbnQgd2l0aCByZWFsIGxpZmU6IGluIGxpbmUgd2l0aCB0aGUgcHJvY2VzcyBhbmQgbG9naWMgb2YgcmVhbFxuICAgICAgICAgIGxpZmUsIGFuZCBjb21wbHkgd2l0aCBsYW5ndWFnZXMgYW5kIGhhYml0cyB0aGF0IHRoZSB1c2VycyBhcmUgdXNlZCB0bztcbiAgICAgICAgPC9kaXY+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgQ29uc2lzdGVudCB3aXRoaW4gaW50ZXJmYWNlOiBhbGwgZWxlbWVudHMgc2hvdWxkIGJlIGNvbnNpc3RlbnQsIHN1Y2hcbiAgICAgICAgICBhczogZGVzaWduIHN0eWxlLCBpY29ucyBhbmQgdGV4dHMsIHBvc2l0aW9uIG9mIGVsZW1lbnRzLCBldGMuXG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jb2xsYXBzZS1pdGVtPlxuICAgICAgPGVsLWNvbGxhcHNlLWl0ZW0gdGl0bGU9XCJGZWVkYmFja1wiIG5hbWU9XCIyXCI+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgT3BlcmF0aW9uIGZlZWRiYWNrOiBlbmFibGUgdGhlIHVzZXJzIHRvIGNsZWFybHkgcGVyY2VpdmUgdGhlaXJcbiAgICAgICAgICBvcGVyYXRpb25zIGJ5IHN0eWxlIHVwZGF0ZXMgYW5kIGludGVyYWN0aXZlIGVmZmVjdHM7XG4gICAgICAgIDwvZGl2PlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIFZpc3VhbCBmZWVkYmFjazogcmVmbGVjdCBjdXJyZW50IHN0YXRlIGJ5IHVwZGF0aW5nIG9yIHJlYXJyYW5naW5nXG4gICAgICAgICAgZWxlbWVudHMgb2YgdGhlIHBhZ2UuXG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jb2xsYXBzZS1pdGVtPlxuICAgICAgPGVsLWNvbGxhcHNlLWl0ZW0gdGl0bGU9XCJFZmZpY2llbmN5XCIgbmFtZT1cIjNcIj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBTaW1wbGlmeSB0aGUgcHJvY2Vzczoga2VlcCBvcGVyYXRpbmcgcHJvY2VzcyBzaW1wbGUgYW5kIGludHVpdGl2ZTtcbiAgICAgICAgPC9kaXY+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgRGVmaW5pdGUgYW5kIGNsZWFyOiBlbnVuY2lhdGUgeW91ciBpbnRlbnRpb25zIGNsZWFybHkgc28gdGhhdCB0aGVcbiAgICAgICAgICB1c2VycyBjYW4gcXVpY2tseSB1bmRlcnN0YW5kIGFuZCBtYWtlIGRlY2lzaW9ucztcbiAgICAgICAgPC9kaXY+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgRWFzeSB0byBpZGVudGlmeTogdGhlIGludGVyZmFjZSBzaG91bGQgYmUgc3RyYWlnaHRmb3J3YXJkLCB3aGljaCBoZWxwc1xuICAgICAgICAgIHRoZSB1c2VycyB0byBpZGVudGlmeSBhbmQgZnJlZXMgdGhlbSBmcm9tIG1lbW9yaXppbmcgYW5kIHJlY2FsbGluZy5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2VsLWNvbGxhcHNlLWl0ZW0+XG4gICAgPC9lbC1jb2xsYXBzZT5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IENvbGxhcHNlSWNvblBvc2l0aW9uVHlwZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgcG9zaXRpb24gPSByZWY8Q29sbGFwc2VJY29uUG9zaXRpb25UeXBlPignbGVmdCcpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/collapse/custom-icon-position.vue)_

vue

```
<template>
  <div class="demo-collapse-position">
    <div class="flex items-center mb-4">
      <span class="mr-4">expand icon position: </span>
      <el-switch
        v-model="position"
        inactive-value="left"
        active-value="right"
        inactive-text="left"
        active-text="right"
        style="--el-switch-off-color: #88b8fe"
      />
    </div>

    <el-collapse :expand-icon-position="position">
      <el-collapse-item title="Consistency" name="1">
        <div>
          Consistent with real life: in line with the process and logic of real
          life, and comply with languages and habits that the users are used to;
        </div>
        <div>
          Consistent within interface: all elements should be consistent, such
          as: design style, icons and texts, position of elements, etc.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Feedback" name="2">
        <div>
          Operation feedback: enable the users to clearly perceive their
          operations by style updates and interactive effects;
        </div>
        <div>
          Visual feedback: reflect current state by updating or rearranging
          elements of the page.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Efficiency" name="3">
        <div>
          Simplify the process: keep operating process simple and intuitive;
        </div>
        <div>
          Definite and clear: enunciate your intentions clearly so that the
          users can quickly understand and make decisions;
        </div>
        <div>
          Easy to identify: the interface should be straightforward, which helps
          the users to identify and frees them from memorizing and recalling.
        </div>
      </el-collapse-item>
    </el-collapse>
  </div>
</template>

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

import type { CollapseIconPositionType } from 'element-plus'

const position = ref<CollapseIconPositionType>('left')
</script>
```

隐藏源代码

## 阻止折叠 2.9.11 [​](#阻止折叠)

设置 `beforeChange` 属性，若返回 false 或者返回 `Promise` 且被 `reject` ，则停止切换。

before collapse return:

falsetrue

Consistency

Consistent with real life: in line with the process and logic of real life, and comply with languages and habits that the users are used to;

Consistent within interface: all elements should be consistent, such as: design style, icons and texts, position of elements, etc.

Feedback

Operation feedback: enable the users to clearly perceive their operations by style updates and interactive effects;

Visual feedback: reflect current state by updating or rearranging elements of the page.

Efficiency

Simplify the process: keep operating process simple and intuitive;

Definite and clear: enunciate your intentions clearly so that the users can quickly understand and make decisions;

Easy to identify: the interface should be straightforward, which helps the users to identify and frees them from memorizing and recalling.

Controllability

Decision making: giving advices about operations is acceptable, but do not make decisions for the users;

Controlled consequences: users should be granted the freedom to operate, including canceling, aborting or terminating current operation.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHYtbG9hZGluZz1cImxvYWRpbmdcIiBjbGFzcz1cImRlbW8tY29sbGFwc2VcIj5cbiAgICA8ZGl2IGNsYXNzPVwiZmxleCBpdGVtcy1jZW50ZXIgbWItNFwiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJtci00XCI+YmVmb3JlIGNvbGxhcHNlIHJldHVybjogPC9zcGFuPlxuICAgICAgPGVsLXN3aXRjaFxuICAgICAgICB2LW1vZGVsPVwiYmVmb3JlXCJcbiAgICAgICAgOmluYWN0aXZlLXZhbHVlPVwiZmFsc2VcIlxuICAgICAgICA6YWN0aXZlLXZhbHVlPVwidHJ1ZVwiXG4gICAgICAgIGluYWN0aXZlLXRleHQ9XCJmYWxzZVwiXG4gICAgICAgIGFjdGl2ZS10ZXh0PVwidHJ1ZVwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuXG4gICAgPGVsLWNvbGxhcHNlIHYtbW9kZWw9XCJhY3RpdmVOYW1lc1wiIDpiZWZvcmUtY29sbGFwc2U9XCJiZWZvcmVDb2xsYXBzZVwiPlxuICAgICAgPGVsLWNvbGxhcHNlLWl0ZW0gdGl0bGU9XCJDb25zaXN0ZW5jeVwiIG5hbWU9XCIxXCI+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgQ29uc2lzdGVudCB3aXRoIHJlYWwgbGlmZTogaW4gbGluZSB3aXRoIHRoZSBwcm9jZXNzIGFuZCBsb2dpYyBvZiByZWFsXG4gICAgICAgICAgbGlmZSwgYW5kIGNvbXBseSB3aXRoIGxhbmd1YWdlcyBhbmQgaGFiaXRzIHRoYXQgdGhlIHVzZXJzIGFyZSB1c2VkIHRvO1xuICAgICAgICA8L2Rpdj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBDb25zaXN0ZW50IHdpdGhpbiBpbnRlcmZhY2U6IGFsbCBlbGVtZW50cyBzaG91bGQgYmUgY29uc2lzdGVudCwgc3VjaFxuICAgICAgICAgIGFzOiBkZXNpZ24gc3R5bGUsIGljb25zIGFuZCB0ZXh0cywgcG9zaXRpb24gb2YgZWxlbWVudHMsIGV0Yy5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2VsLWNvbGxhcHNlLWl0ZW0+XG4gICAgICA8ZWwtY29sbGFwc2UtaXRlbSB0aXRsZT1cIkZlZWRiYWNrXCIgbmFtZT1cIjJcIj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBPcGVyYXRpb24gZmVlZGJhY2s6IGVuYWJsZSB0aGUgdXNlcnMgdG8gY2xlYXJseSBwZXJjZWl2ZSB0aGVpclxuICAgICAgICAgIG9wZXJhdGlvbnMgYnkgc3R5bGUgdXBkYXRlcyBhbmQgaW50ZXJhY3RpdmUgZWZmZWN0cztcbiAgICAgICAgPC9kaXY+XG4gICAgICAgIDxkaXY+XG4gICAgICAgICAgVmlzdWFsIGZlZWRiYWNrOiByZWZsZWN0IGN1cnJlbnQgc3RhdGUgYnkgdXBkYXRpbmcgb3IgcmVhcnJhbmdpbmdcbiAgICAgICAgICBlbGVtZW50cyBvZiB0aGUgcGFnZS5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2VsLWNvbGxhcHNlLWl0ZW0+XG4gICAgICA8ZWwtY29sbGFwc2UtaXRlbSB0aXRsZT1cIkVmZmljaWVuY3lcIiBuYW1lPVwiM1wiPlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIFNpbXBsaWZ5IHRoZSBwcm9jZXNzOiBrZWVwIG9wZXJhdGluZyBwcm9jZXNzIHNpbXBsZSBhbmQgaW50dWl0aXZlO1xuICAgICAgICA8L2Rpdj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBEZWZpbml0ZSBhbmQgY2xlYXI6IGVudW5jaWF0ZSB5b3VyIGludGVudGlvbnMgY2xlYXJseSBzbyB0aGF0IHRoZVxuICAgICAgICAgIHVzZXJzIGNhbiBxdWlja2x5IHVuZGVyc3RhbmQgYW5kIG1ha2UgZGVjaXNpb25zO1xuICAgICAgICA8L2Rpdj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBFYXN5IHRvIGlkZW50aWZ5OiB0aGUgaW50ZXJmYWNlIHNob3VsZCBiZSBzdHJhaWdodGZvcndhcmQsIHdoaWNoIGhlbHBzXG4gICAgICAgICAgdGhlIHVzZXJzIHRvIGlkZW50aWZ5IGFuZCBmcmVlcyB0aGVtIGZyb20gbWVtb3JpemluZyBhbmQgcmVjYWxsaW5nLlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZWwtY29sbGFwc2UtaXRlbT5cbiAgICAgIDxlbC1jb2xsYXBzZS1pdGVtIHRpdGxlPVwiQ29udHJvbGxhYmlsaXR5XCIgbmFtZT1cIjRcIj5cbiAgICAgICAgPGRpdj5cbiAgICAgICAgICBEZWNpc2lvbiBtYWtpbmc6IGdpdmluZyBhZHZpY2VzIGFib3V0IG9wZXJhdGlvbnMgaXMgYWNjZXB0YWJsZSwgYnV0IGRvXG4gICAgICAgICAgbm90IG1ha2UgZGVjaXNpb25zIGZvciB0aGUgdXNlcnM7XG4gICAgICAgIDwvZGl2PlxuICAgICAgICA8ZGl2PlxuICAgICAgICAgIENvbnRyb2xsZWQgY29uc2VxdWVuY2VzOiB1c2VycyBzaG91bGQgYmUgZ3JhbnRlZCB0aGUgZnJlZWRvbSB0b1xuICAgICAgICAgIG9wZXJhdGUsIGluY2x1ZGluZyBjYW5jZWxpbmcsIGFib3J0aW5nIG9yIHRlcm1pbmF0aW5nIGN1cnJlbnRcbiAgICAgICAgICBvcGVyYXRpb24uXG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jb2xsYXBzZS1pdGVtPlxuICAgIDwvZWwtY29sbGFwc2U+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgYmVmb3JlID0gcmVmKHRydWUpXG5jb25zdCBhY3RpdmVOYW1lcyA9IHJlZihbJzEnXSlcbmNvbnN0IGxvYWRpbmcgPSByZWYoZmFsc2UpXG5cbmNvbnN0IGJlZm9yZUNvbGxhcHNlID0gKCk6IFByb21pc2U8Ym9vbGVhbj4gPT4ge1xuICBsb2FkaW5nLnZhbHVlID0gdHJ1ZVxuICByZXR1cm4gbmV3IFByb21pc2UoKHJlc29sdmUpID0+IHtcbiAgICBzZXRUaW1lb3V0KCgpID0+IHtcbiAgICAgIGxvYWRpbmcudmFsdWUgPSBmYWxzZVxuICAgICAgcmV0dXJuIHJlc29sdmUoYmVmb3JlLnZhbHVlKVxuICAgIH0sIDEwMDApXG4gIH0pXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/collapse/prevent-collapsing.vue)_

vue

```
<template>
  <div v-loading="loading" class="demo-collapse">
    <div class="flex items-center mb-4">
      <span class="mr-4">before collapse return: </span>
      <el-switch
        v-model="before"
        :inactive-value="false"
        :active-value="true"
        inactive-text="false"
        active-text="true"
      />
    </div>

    <el-collapse v-model="activeNames" :before-collapse="beforeCollapse">
      <el-collapse-item title="Consistency" name="1">
        <div>
          Consistent with real life: in line with the process and logic of real
          life, and comply with languages and habits that the users are used to;
        </div>
        <div>
          Consistent within interface: all elements should be consistent, such
          as: design style, icons and texts, position of elements, etc.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Feedback" name="2">
        <div>
          Operation feedback: enable the users to clearly perceive their
          operations by style updates and interactive effects;
        </div>
        <div>
          Visual feedback: reflect current state by updating or rearranging
          elements of the page.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Efficiency" name="3">
        <div>
          Simplify the process: keep operating process simple and intuitive;
        </div>
        <div>
          Definite and clear: enunciate your intentions clearly so that the
          users can quickly understand and make decisions;
        </div>
        <div>
          Easy to identify: the interface should be straightforward, which helps
          the users to identify and frees them from memorizing and recalling.
        </div>
      </el-collapse-item>
      <el-collapse-item title="Controllability" name="4">
        <div>
          Decision making: giving advices about operations is acceptable, but do
          not make decisions for the users;
        </div>
        <div>
          Controlled consequences: users should be granted the freedom to
          operate, including canceling, aborting or terminating current
          operation.
        </div>
      </el-collapse-item>
    </el-collapse>
  </div>
</template>

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

const before = ref(true)
const activeNames = ref(['1'])
const loading = ref(false)

const beforeCollapse = (): Promise<boolean> => {
  loading.value = true
  return new Promise((resolve) => {
    setTimeout(() => {
      loading.value = false
      return resolve(before.value)
    }, 1000)
  })
}
</script>
```

隐藏源代码

## Collapse API [​](#collapse-api)

### Collapse Attributes [​](#collapse-attributes)

| 属性名 | 详情 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 当前活动面板，在手风琴模式下其类型是`string`，在其他模式下是`array` | `string` / `array` | \[\] |
| accordion | 是否手风琴模式 | `boolean` | false |
| expand-icon-position 2.9.10 | 设置展开图标位置 | `enum` | right |
| before-collapse 2.9.11 | 折叠状态更改之前的折叠钩子。 返回 `false` 或者返回 `Promise` 且被 reject 则停止切换 | `Function` | — |

### Collapse Events [​](#collapse-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 切换当前活动面板，在手风琴模式下其类型是`string`，在其他模式下是`array` | `Function` |

### Collapse Slots [​](#collapse-slots)

| 插槽名 | Description | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | Collapse Item |

### Collapse Exposes [​](#collapse-exposes)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| activeNames | 当前活动的面板名称 | `object` |
| setActiveNames | 设置活动面板名称 | `Function` |

## Collapse Item API [​](#collapse-item-api)

### Collapse Item Attributes [​](#collapse-item-attributes)

| 属性名 | 说明 | Type | 默认值 |
| --- | --- | --- | --- |
| name | 唯一标志符 | `string` / `number` | — |
| title | 面板标题 | `string` | '' |
| icon 2.8.3 | 折叠项目的图标 | `string` / `Component` | ArrowRight |
| disabled | 是否禁用 | `boolean` | false |

### Collapse Item Slot [​](#collapse-item-slot)

| Name | Description | Type |
| --- | --- | --- |
| default | Collapse Item 的内容 | — |
| title | Collapse Item 的标题 | `object` |
| icon 2.8.3 | 折叠项目图标的内容 | `object` |

### Collapse Item Exposes [​](#collapse-item-exposes)

| Name | Description | Type |
| --- | --- | --- |
| isActive | 当前折叠项是否激活 | `object` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/collapse) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/collapse.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/collapse.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/57785259?v=4&size=64)](https://github.com/w2xi)[![](https://avatars.githubusercontent.com/u/108655466?v=4&size=64)](https://github.com/Karolis-Stoncius)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/154399795?v=4&size=64)](https://github.com/rhodi2436)[![](https://avatars.githubusercontent.com/u/43257608?v=4&size=64)](https://github.com/Liao-js)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/32761502?v=4&size=64)](https://github.com/kimverchan)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/103868381?v=4&size=64)](https://github.com/kinggq)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)

[Carousel 走马灯](https://element-plus.org/zh-CN/component/carousel)

[Descriptions 描述列表](https://element-plus.org/zh-CN/component/descriptions)




---
## [data/descriptions] Descriptions 描述列表
> 官方文档: https://element-plus.org/zh-CN/component/descriptions.html

---

# Descriptions 描述列表 [​](#descriptions-描述列表)

更新日志待解决

9

列表形式展示多个字段。

## 基础用法 [​](#基础用法)

User Info

<table class="el-descriptions__table"><tbody><tr><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Username</span><span class="el-descriptions__content">kooriookami</span></td><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Telephone</span><span class="el-descriptions__content">18100000000</span></td><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Place</span><span class="el-descriptions__content">Suzhou</span></td></tr><tr><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Remarks</span><span class="el-descriptions__content"><span class="el-tag el-tag--primary el-tag--small el-tag--light" style=""><span class="el-tag__content">School</span></span></span></td><td style="width:;min-width:;" class="el-descriptions__cell" colspan="2"><span style="" class="el-descriptions__label">Address</span><span class="el-descriptions__content"> No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province</span></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZGVzY3JpcHRpb25zIHRpdGxlPVwiVXNlciBJbmZvXCI+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiVXNlcm5hbWVcIj5rb29yaW9va2FtaTwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiVGVsZXBob25lXCI+MTgxMDAwMDAwMDA8L2VsLWRlc2NyaXB0aW9ucy1pdGVtPlxuICAgIDxlbC1kZXNjcmlwdGlvbnMtaXRlbSBsYWJlbD1cIlBsYWNlXCI+U3V6aG91PC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJSZW1hcmtzXCI+XG4gICAgICA8ZWwtdGFnIHNpemU9XCJzbWFsbFwiPlNjaG9vbDwvZWwtdGFnPlxuICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiQWRkcmVzc1wiPlxuICAgICAgTm8uMTE4OCwgV3V6aG9uZyBBdmVudWUsIFd1emhvbmcgRGlzdHJpY3QsIFN1emhvdSwgSmlhbmdzdSBQcm92aW5jZVxuICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gIDwvZWwtZGVzY3JpcHRpb25zPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/descriptions/basic-usage.vue)_

vue

```
<template>
  <el-descriptions title="User Info">
    <el-descriptions-item label="Username">kooriookami</el-descriptions-item>
    <el-descriptions-item label="Telephone">18100000000</el-descriptions-item>
    <el-descriptions-item label="Place">Suzhou</el-descriptions-item>
    <el-descriptions-item label="Remarks">
      <el-tag size="small">School</el-tag>
    </el-descriptions-item>
    <el-descriptions-item label="Address">
      No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province
    </el-descriptions-item>
  </el-descriptions>
</template>
```

隐藏源代码

## 不同尺寸 [​](#不同尺寸)

LargeDefaultSmall

With border

Operation

<table class="el-descriptions__table is-bordered"><tbody><tr><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label" colspan="1"><div class="cell-item" data-v-6630171f=""><i class="el-icon" style="margin-right:6px;" data-v-6630171f=""><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" data-v-6630171f=""><path fill="currentColor" d="M512 512a192 192 0 1 0 0-384 192 192 0 0 0 0 384m0 64a256 256 0 1 1 0-512 256 256 0 0 1 0 512m320 320v-96a96 96 0 0 0-96-96H288a96 96 0 0 0-96 96v96a32 32 0 1 1-64 0v-96a160 160 0 0 1 160-160h448a160 160 0 0 1 160 160v96a32 32 0 1 1-64 0"></path></svg></i>Username</div></td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content" colspan="NaN">kooriookami</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label" colspan="1"><div class="cell-item" data-v-6630171f=""><i class="el-icon" style="margin-right:6px;" data-v-6630171f=""><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" data-v-6630171f=""><path fill="currentColor" d="M224 768v96.064a64 64 0 0 0 64 64h448a64 64 0 0 0 64-64V768zm0-64h576V160a64 64 0 0 0-64-64H288a64 64 0 0 0-64 64zm32 288a96 96 0 0 1-96-96V128a96 96 0 0 1 96-96h512a96 96 0 0 1 96 96v768a96 96 0 0 1-96 96zm304-144a48 48 0 1 1-96 0 48 48 0 0 1 96 0"></path></svg></i>Telephone</div></td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content" colspan="NaN">18100000000</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label" colspan="1"><div class="cell-item" data-v-6630171f=""><i class="el-icon" style="margin-right:6px;" data-v-6630171f=""><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" data-v-6630171f=""><path fill="currentColor" d="M800 416a288 288 0 1 0-576 0c0 118.144 94.528 272.128 288 456.576C705.472 688.128 800 534.144 800 416M512 960C277.312 746.688 160 565.312 160 416a352 352 0 0 1 704 0c0 149.312-117.312 330.688-352 544"></path><path fill="currentColor" d="M512 512a96 96 0 1 0 0-192 96 96 0 0 0 0 192m0 64a160 160 0 1 1 0-320 160 160 0 0 1 0 320"></path></svg></i>Place</div></td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content" colspan="NaN">Suzhou</td></tr><tr><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label" colspan="1"><div class="cell-item" data-v-6630171f=""><i class="el-icon" style="margin-right:6px;" data-v-6630171f=""><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" data-v-6630171f=""><path fill="currentColor" d="M192 128v768h640V128zm-32-64h704a32 32 0 0 1 32 32v832a32 32 0 0 1-32 32H160a32 32 0 0 1-32-32V96a32 32 0 0 1 32-32m160 448h384v64H320zm0-192h192v64H320zm0 384h384v64H320z"></path></svg></i>Remarks</div></td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content" colspan="NaN"><span class="el-tag el-tag--primary el-tag--small el-tag--light" style="" data-v-6630171f=""><span class="el-tag__content">School</span></span></td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label" colspan="1"><div class="cell-item" data-v-6630171f=""><i class="el-icon" style="margin-right:6px;" data-v-6630171f=""><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" data-v-6630171f=""><path fill="currentColor" d="M192 128v704h384V128zm-32-64h448a32 32 0 0 1 32 32v768a32 32 0 0 1-32 32H160a32 32 0 0 1-32-32V96a32 32 0 0 1 32-32"></path><path fill="currentColor" d="M256 256h256v64H256zm0 192h256v64H256zm0 192h256v64H256zm384-128h128v64H640zm0 128h128v64H640zM64 832h896v64H64z"></path><path fill="currentColor" d="M640 384v448h192V384zm-32-64h256a32 32 0 0 1 32 32v512a32 32 0 0 1-32 32H608a32 32 0 0 1-32-32V352a32 32 0 0 1 32-32"></path></svg></i>Address</div></td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content" colspan="3">No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province</td></tr></tbody></table>

Without border

Operation

<table class="el-descriptions__table"><tbody><tr><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Username</span><span class="el-descriptions__content">kooriookami</span></td><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Telephone</span><span class="el-descriptions__content">18100000000</span></td><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Place</span><span class="el-descriptions__content">Suzhou</span></td></tr><tr><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Remarks</span><span class="el-descriptions__content"><span class="el-tag el-tag--primary el-tag--small el-tag--light" style="" data-v-6630171f=""><span class="el-tag__content">School</span></span></span></td><td style="width:;min-width:;" class="el-descriptions__cell" colspan="2"><span style="" class="el-descriptions__label">Address</span><span class="el-descriptions__content"> No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province</span></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInNpemVcIj5cbiAgICA8ZWwtcmFkaW8gdmFsdWU9XCJsYXJnZVwiPkxhcmdlPC9lbC1yYWRpbz5cbiAgICA8ZWwtcmFkaW8gdmFsdWU9XCJkZWZhdWx0XCI+RGVmYXVsdDwvZWwtcmFkaW8+XG4gICAgPGVsLXJhZGlvIHZhbHVlPVwic21hbGxcIj5TbWFsbDwvZWwtcmFkaW8+XG4gIDwvZWwtcmFkaW8tZ3JvdXA+XG5cbiAgPGVsLWRlc2NyaXB0aW9uc1xuICAgIGNsYXNzPVwibWFyZ2luLXRvcFwiXG4gICAgdGl0bGU9XCJXaXRoIGJvcmRlclwiXG4gICAgOmNvbHVtbj1cIjNcIlxuICAgIDpzaXplPVwic2l6ZVwiXG4gICAgYm9yZGVyXG4gID5cbiAgICA8dGVtcGxhdGUgI2V4dHJhPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiPk9wZXJhdGlvbjwvZWwtYnV0dG9uPlxuICAgIDwvdGVtcGxhdGU+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtPlxuICAgICAgPHRlbXBsYXRlICNsYWJlbD5cbiAgICAgICAgPGRpdiBjbGFzcz1cImNlbGwtaXRlbVwiPlxuICAgICAgICAgIDxlbC1pY29uIDpzdHlsZT1cImljb25TdHlsZVwiPlxuICAgICAgICAgICAgPHVzZXIgLz5cbiAgICAgICAgICA8L2VsLWljb24+XG4gICAgICAgICAgVXNlcm5hbWVcbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAga29vcmlvb2thbWlcbiAgICA8L2VsLWRlc2NyaXB0aW9ucy1pdGVtPlxuICAgIDxlbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICAgIDx0ZW1wbGF0ZSAjbGFiZWw+XG4gICAgICAgIDxkaXYgY2xhc3M9XCJjZWxsLWl0ZW1cIj5cbiAgICAgICAgICA8ZWwtaWNvbiA6c3R5bGU9XCJpY29uU3R5bGVcIj5cbiAgICAgICAgICAgIDxpcGhvbmUgLz5cbiAgICAgICAgICA8L2VsLWljb24+XG4gICAgICAgICAgVGVsZXBob25lXG4gICAgICAgIDwvZGl2PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDE4MTAwMDAwMDAwXG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgICA8dGVtcGxhdGUgI2xhYmVsPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiY2VsbC1pdGVtXCI+XG4gICAgICAgICAgPGVsLWljb24gOnN0eWxlPVwiaWNvblN0eWxlXCI+XG4gICAgICAgICAgICA8bG9jYXRpb24gLz5cbiAgICAgICAgICA8L2VsLWljb24+XG4gICAgICAgICAgUGxhY2VcbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgU3V6aG91XG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgICA8dGVtcGxhdGUgI2xhYmVsPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiY2VsbC1pdGVtXCI+XG4gICAgICAgICAgPGVsLWljb24gOnN0eWxlPVwiaWNvblN0eWxlXCI+XG4gICAgICAgICAgICA8dGlja2V0cyAvPlxuICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgICBSZW1hcmtzXG4gICAgICAgIDwvZGl2PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDxlbC10YWcgc2l6ZT1cInNtYWxsXCI+U2Nob29sPC9lbC10YWc+XG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgICA8dGVtcGxhdGUgI2xhYmVsPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiY2VsbC1pdGVtXCI+XG4gICAgICAgICAgPGVsLWljb24gOnN0eWxlPVwiaWNvblN0eWxlXCI+XG4gICAgICAgICAgICA8b2ZmaWNlLWJ1aWxkaW5nIC8+XG4gICAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICAgIEFkZHJlc3NcbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgTm8uMTE4OCwgV3V6aG9uZyBBdmVudWUsIFd1emhvbmcgRGlzdHJpY3QsIFN1emhvdSwgSmlhbmdzdSBQcm92aW5jZVxuICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gIDwvZWwtZGVzY3JpcHRpb25zPlxuXG4gIDxlbC1kZXNjcmlwdGlvbnNcbiAgICBjbGFzcz1cIm1hcmdpbi10b3BcIlxuICAgIHRpdGxlPVwiV2l0aG91dCBib3JkZXJcIlxuICAgIDpjb2x1bW49XCIzXCJcbiAgICA6c2l6ZT1cInNpemVcIlxuICAgIDpzdHlsZT1cImJsb2NrTWFyZ2luXCJcbiAgPlxuICAgIDx0ZW1wbGF0ZSAjZXh0cmE+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCI+T3BlcmF0aW9uPC9lbC1idXR0b24+XG4gICAgPC90ZW1wbGF0ZT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJVc2VybmFtZVwiPmtvb3Jpb29rYW1pPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJUZWxlcGhvbmVcIj4xODEwMDAwMDAwMDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiUGxhY2VcIj5TdXpob3U8L2VsLWRlc2NyaXB0aW9ucy1pdGVtPlxuICAgIDxlbC1kZXNjcmlwdGlvbnMtaXRlbSBsYWJlbD1cIlJlbWFya3NcIj5cbiAgICAgIDxlbC10YWcgc2l6ZT1cInNtYWxsXCI+U2Nob29sPC9lbC10YWc+XG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJBZGRyZXNzXCI+XG4gICAgICBOby4xMTg4LCBXdXpob25nIEF2ZW51ZSwgV3V6aG9uZyBEaXN0cmljdCwgU3V6aG91LCBKaWFuZ3N1IFByb3ZpbmNlXG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgPC9lbC1kZXNjcmlwdGlvbnM+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgY29tcHV0ZWQsIHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7XG4gIElwaG9uZSxcbiAgTG9jYXRpb24sXG4gIE9mZmljZUJ1aWxkaW5nLFxuICBUaWNrZXRzLFxuICBVc2VyLFxufSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuaW1wb3J0IHR5cGUgeyBDb21wb25lbnRTaXplIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBzaXplID0gcmVmPENvbXBvbmVudFNpemU+KCdkZWZhdWx0JylcblxuY29uc3QgaWNvblN0eWxlID0gY29tcHV0ZWQoKCkgPT4ge1xuICBjb25zdCBtYXJnaW5NYXAgPSB7XG4gICAgbGFyZ2U6ICc4cHgnLFxuICAgIGRlZmF1bHQ6ICc2cHgnLFxuICAgIHNtYWxsOiAnNHB4JyxcbiAgfVxuICByZXR1cm4ge1xuICAgIG1hcmdpblJpZ2h0OiBtYXJnaW5NYXBbc2l6ZS52YWx1ZV0gfHwgbWFyZ2luTWFwLmRlZmF1bHQsXG4gIH1cbn0pXG5jb25zdCBibG9ja01hcmdpbiA9IGNvbXB1dGVkKCgpID0+IHtcbiAgY29uc3QgbWFyZ2luTWFwID0ge1xuICAgIGxhcmdlOiAnMzJweCcsXG4gICAgZGVmYXVsdDogJzI4cHgnLFxuICAgIHNtYWxsOiAnMjRweCcsXG4gIH1cbiAgcmV0dXJuIHtcbiAgICBtYXJnaW5Ub3A6IG1hcmdpbk1hcFtzaXplLnZhbHVlXSB8fCBtYXJnaW5NYXAuZGVmYXVsdCxcbiAgfVxufSlcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmVsLWRlc2NyaXB0aW9ucyB7XG4gIG1hcmdpbi10b3A6IDIwcHg7XG59XG4uY2VsbC1pdGVtIHtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbn1cbi5tYXJnaW4tdG9wIHtcbiAgbWFyZ2luLXRvcDogMjBweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/descriptions/sizes.vue)_

vue

```
<template>
  <el-radio-group v-model="size">
    <el-radio value="large">Large</el-radio>
    <el-radio value="default">Default</el-radio>
    <el-radio value="small">Small</el-radio>
  </el-radio-group>

  <el-descriptions
    class="margin-top"
    title="With border"
    :column="3"
    :size="size"
    border
  >
    <template #extra>
      <el-button type="primary">Operation</el-button>
    </template>
    <el-descriptions-item>
      <template #label>
        <div class="cell-item">
          <el-icon :style="iconStyle">
            <user />
          </el-icon>
          Username
        </div>
      </template>
      kooriookami
    </el-descriptions-item>
    <el-descriptions-item>
      <template #label>
        <div class="cell-item">
          <el-icon :style="iconStyle">
            <iphone />
          </el-icon>
          Telephone
        </div>
      </template>
      18100000000
    </el-descriptions-item>
    <el-descriptions-item>
      <template #label>
        <div class="cell-item">
          <el-icon :style="iconStyle">
            <location />
          </el-icon>
          Place
        </div>
      </template>
      Suzhou
    </el-descriptions-item>
    <el-descriptions-item>
      <template #label>
        <div class="cell-item">
          <el-icon :style="iconStyle">
            <tickets />
          </el-icon>
          Remarks
        </div>
      </template>
      <el-tag size="small">School</el-tag>
    </el-descriptions-item>
    <el-descriptions-item>
      <template #label>
        <div class="cell-item">
          <el-icon :style="iconStyle">
            <office-building />
          </el-icon>
          Address
        </div>
      </template>
      No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province
    </el-descriptions-item>
  </el-descriptions>

  <el-descriptions
    class="margin-top"
    title="Without border"
    :column="3"
    :size="size"
    :style="blockMargin"
  >
    <template #extra>
      <el-button type="primary">Operation</el-button>
    </template>
    <el-descriptions-item label="Username">kooriookami</el-descriptions-item>
    <el-descriptions-item label="Telephone">18100000000</el-descriptions-item>
    <el-descriptions-item label="Place">Suzhou</el-descriptions-item>
    <el-descriptions-item label="Remarks">
      <el-tag size="small">School</el-tag>
    </el-descriptions-item>
    <el-descriptions-item label="Address">
      No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province
    </el-descriptions-item>
  </el-descriptions>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue'
import {
  Iphone,
  Location,
  OfficeBuilding,
  Tickets,
  User,
} from '@element-plus/icons-vue'

import type { ComponentSize } from 'element-plus'

const size = ref<ComponentSize>('default')

const iconStyle = computed(() => {
  const marginMap = {
    large: '8px',
    default: '6px',
    small: '4px',
  }
  return {
    marginRight: marginMap[size.value] || marginMap.default,
  }
})
const blockMargin = computed(() => {
  const marginMap = {
    large: '32px',
    default: '28px',
    small: '24px',
  }
  return {
    marginTop: marginMap[size.value] || marginMap.default,
  }
})
</script>

<style scoped>
.el-descriptions {
  margin-top: 20px;
}
.cell-item {
  display: flex;
  align-items: center;
}
.margin-top {
  margin-top: 20px;
}
</style>
```

隐藏源代码

## 垂直列表 [​](#垂直列表)

LargeDefaultSmall

Vertical list with border

| Username | Telephone | Place |
| --- | --- | --- |
| kooriookami | 18100000000 | Suzhou |
| Remarks | Address |
| School | No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province |

Vertical list without border

| Username | Telephone | Place |
| --- | --- | --- |
| kooriookami | 18100000000 | Suzhou |
| Remarks | Address |
| School | No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province |

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInNpemVcIj5cbiAgICA8ZWwtcmFkaW8gdmFsdWU9XCJsYXJnZVwiPkxhcmdlPC9lbC1yYWRpbz5cbiAgICA8ZWwtcmFkaW8gdmFsdWU9XCJkZWZhdWx0XCI+RGVmYXVsdDwvZWwtcmFkaW8+XG4gICAgPGVsLXJhZGlvIHZhbHVlPVwic21hbGxcIj5TbWFsbDwvZWwtcmFkaW8+XG4gIDwvZWwtcmFkaW8tZ3JvdXA+XG5cbiAgPGVsLWRlc2NyaXB0aW9uc1xuICAgIHRpdGxlPVwiVmVydGljYWwgbGlzdCB3aXRoIGJvcmRlclwiXG4gICAgZGlyZWN0aW9uPVwidmVydGljYWxcIlxuICAgIDpjb2x1bW49XCI0XCJcbiAgICA6c2l6ZT1cInNpemVcIlxuICAgIGJvcmRlclxuICA+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiVXNlcm5hbWVcIj5rb29yaW9va2FtaTwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiVGVsZXBob25lXCI+MTgxMDAwMDAwMDA8L2VsLWRlc2NyaXB0aW9ucy1pdGVtPlxuICAgIDxlbC1kZXNjcmlwdGlvbnMtaXRlbSBsYWJlbD1cIlBsYWNlXCIgOnNwYW49XCIyXCI+U3V6aG91PC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJSZW1hcmtzXCI+XG4gICAgICA8ZWwtdGFnIHNpemU9XCJzbWFsbFwiPlNjaG9vbDwvZWwtdGFnPlxuICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiQWRkcmVzc1wiPlxuICAgICAgTm8uMTE4OCwgV3V6aG9uZyBBdmVudWUsIFd1emhvbmcgRGlzdHJpY3QsIFN1emhvdSwgSmlhbmdzdSBQcm92aW5jZVxuICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gIDwvZWwtZGVzY3JpcHRpb25zPlxuXG4gIDxlbC1kZXNjcmlwdGlvbnNcbiAgICB0aXRsZT1cIlZlcnRpY2FsIGxpc3Qgd2l0aG91dCBib3JkZXJcIlxuICAgIDpjb2x1bW49XCI0XCJcbiAgICA6c2l6ZT1cInNpemVcIlxuICAgIGRpcmVjdGlvbj1cInZlcnRpY2FsXCJcbiAgICA6c3R5bGU9XCJibG9ja01hcmdpblwiXG4gID5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJVc2VybmFtZVwiPmtvb3Jpb29rYW1pPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJUZWxlcGhvbmVcIj4xODEwMDAwMDAwMDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiUGxhY2VcIiA6c3Bhbj1cIjJcIj5TdXpob3U8L2VsLWRlc2NyaXB0aW9ucy1pdGVtPlxuICAgIDxlbC1kZXNjcmlwdGlvbnMtaXRlbSBsYWJlbD1cIlJlbWFya3NcIj5cbiAgICAgIDxlbC10YWcgc2l6ZT1cInNtYWxsXCI+U2Nob29sPC9lbC10YWc+XG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJBZGRyZXNzXCI+XG4gICAgICBOby4xMTg4LCBXdXpob25nIEF2ZW51ZSwgV3V6aG9uZyBEaXN0cmljdCwgU3V6aG91LCBKaWFuZ3N1IFByb3ZpbmNlXG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgPC9lbC1kZXNjcmlwdGlvbnM+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgY29tcHV0ZWQsIHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBDb21wb25lbnRTaXplIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBzaXplID0gcmVmPENvbXBvbmVudFNpemU+KCdkZWZhdWx0JylcblxuY29uc3QgYmxvY2tNYXJnaW4gPSBjb21wdXRlZCgoKSA9PiB7XG4gIGNvbnN0IG1hcmdpbk1hcCA9IHtcbiAgICBsYXJnZTogJzMycHgnLFxuICAgIGRlZmF1bHQ6ICcyOHB4JyxcbiAgICBzbWFsbDogJzI0cHgnLFxuICB9XG4gIHJldHVybiB7XG4gICAgbWFyZ2luVG9wOiBtYXJnaW5NYXBbc2l6ZS52YWx1ZV0gfHwgbWFyZ2luTWFwLmRlZmF1bHQsXG4gIH1cbn0pXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5lbC1kZXNjcmlwdGlvbnMge1xuICBtYXJnaW4tdG9wOiAyMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/descriptions/vertical-list.vue)_

vue

```
<template>
  <el-radio-group v-model="size">
    <el-radio value="large">Large</el-radio>
    <el-radio value="default">Default</el-radio>
    <el-radio value="small">Small</el-radio>
  </el-radio-group>

  <el-descriptions
    title="Vertical list with border"
    direction="vertical"
    :column="4"
    :size="size"
    border
  >
    <el-descriptions-item label="Username">kooriookami</el-descriptions-item>
    <el-descriptions-item label="Telephone">18100000000</el-descriptions-item>
    <el-descriptions-item label="Place" :span="2">Suzhou</el-descriptions-item>
    <el-descriptions-item label="Remarks">
      <el-tag size="small">School</el-tag>
    </el-descriptions-item>
    <el-descriptions-item label="Address">
      No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province
    </el-descriptions-item>
  </el-descriptions>

  <el-descriptions
    title="Vertical list without border"
    :column="4"
    :size="size"
    direction="vertical"
    :style="blockMargin"
  >
    <el-descriptions-item label="Username">kooriookami</el-descriptions-item>
    <el-descriptions-item label="Telephone">18100000000</el-descriptions-item>
    <el-descriptions-item label="Place" :span="2">Suzhou</el-descriptions-item>
    <el-descriptions-item label="Remarks">
      <el-tag size="small">School</el-tag>
    </el-descriptions-item>
    <el-descriptions-item label="Address">
      No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province
    </el-descriptions-item>
  </el-descriptions>
</template>

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

import type { ComponentSize } from 'element-plus'

const size = ref<ComponentSize>('default')

const blockMargin = computed(() => {
  const marginMap = {
    large: '32px',
    default: '28px',
    small: '24px',
  }
  return {
    marginTop: marginMap[size.value] || marginMap.default,
  }
})
</script>

<style scoped>
.el-descriptions {
  margin-top: 20px;
}
</style>
```

隐藏源代码

## 单元格跨行 2.8.1 [​](#单元格跨行)

Width horizontal list

<table class="el-descriptions__table is-bordered"><tbody><tr><td style="width:140px;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label is-center" colspan="1" rowspan="2">Photo</td><td style="width:140px;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content is-center" colspan="NaN" rowspan="2"><div style="width:100px;height:100px;" class="el-image"><img src="https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png" class="el-image__inner"></div></td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label" colspan="1">Username</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content" colspan="NaN">kooriookami</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label" colspan="1">Telephone</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content" colspan="NaN">18100000000</td></tr><tr><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label" colspan="1">Place</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content" colspan="NaN">Suzhou</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label" colspan="1">Remarks</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content" colspan="NaN"><span class="el-tag el-tag--primary el-tag--small el-tag--light" style=""><span class="el-tag__content">School</span></span></td></tr><tr><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label" colspan="1">Address</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content" colspan="5">No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province</td></tr></tbody></table>

Width vertical list

| Photo | Username | Telephone |
| --- | --- | --- |
|
![](https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png)

 | kooriookami | 18100000000 |
| Place | Remarks |
| Suzhou | School |
| Address |
| No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province |

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZGVzY3JpcHRpb25zIHRpdGxlPVwiV2lkdGggaG9yaXpvbnRhbCBsaXN0XCIgYm9yZGVyPlxuICAgIDxlbC1kZXNjcmlwdGlvbnMtaXRlbVxuICAgICAgOnJvd3NwYW49XCIyXCJcbiAgICAgIDp3aWR0aD1cIjE0MFwiXG4gICAgICBsYWJlbD1cIlBob3RvXCJcbiAgICAgIGFsaWduPVwiY2VudGVyXCJcbiAgICA+XG4gICAgICA8ZWwtaW1hZ2VcbiAgICAgICAgc3R5bGU9XCJ3aWR0aDogMTAwcHg7IGhlaWdodDogMTAwcHhcIlxuICAgICAgICBzcmM9XCJodHRwczovL2N1YmUuZWxlbWVjZG4uY29tLzAvODgvMDNiMGQzOTU4M2Y0ODIwNjc2OGE3NTM0ZTU1YmNwbmcucG5nXCJcbiAgICAgIC8+XG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJVc2VybmFtZVwiPmtvb3Jpb29rYW1pPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJUZWxlcGhvbmVcIj4xODEwMDAwMDAwMDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiUGxhY2VcIj5TdXpob3U8L2VsLWRlc2NyaXB0aW9ucy1pdGVtPlxuICAgIDxlbC1kZXNjcmlwdGlvbnMtaXRlbSBsYWJlbD1cIlJlbWFya3NcIj5cbiAgICAgIDxlbC10YWcgc2l6ZT1cInNtYWxsXCI+U2Nob29sPC9lbC10YWc+XG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJBZGRyZXNzXCI+XG4gICAgICBOby4xMTg4LCBXdXpob25nIEF2ZW51ZSwgV3V6aG9uZyBEaXN0cmljdCwgU3V6aG91LCBKaWFuZ3N1IFByb3ZpbmNlXG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgPC9lbC1kZXNjcmlwdGlvbnM+XG5cbiAgPGVsLWRlc2NyaXB0aW9uc1xuICAgIHRpdGxlPVwiV2lkdGggdmVydGljYWwgbGlzdFwiXG4gICAgZGlyZWN0aW9uPVwidmVydGljYWxcIlxuICAgIGJvcmRlclxuICAgIHN0eWxlPVwibWFyZ2luLXRvcDogMjBweFwiXG4gID5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW1cbiAgICAgIDpyb3dzcGFuPVwiMlwiXG4gICAgICA6d2lkdGg9XCIxNDBcIlxuICAgICAgbGFiZWw9XCJQaG90b1wiXG4gICAgICBhbGlnbj1cImNlbnRlclwiXG4gICAgPlxuICAgICAgPGVsLWltYWdlXG4gICAgICAgIHN0eWxlPVwid2lkdGg6IDEwMHB4OyBoZWlnaHQ6IDEwMHB4XCJcbiAgICAgICAgc3JjPVwiaHR0cHM6Ly9jdWJlLmVsZW1lY2RuLmNvbS8wLzg4LzAzYjBkMzk1ODNmNDgyMDY3NjhhNzUzNGU1NWJjcG5nLnBuZ1wiXG4gICAgICAvPlxuICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiVXNlcm5hbWVcIj5rb29yaW9va2FtaTwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiVGVsZXBob25lXCI+MTgxMDAwMDAwMDA8L2VsLWRlc2NyaXB0aW9ucy1pdGVtPlxuICAgIDxlbC1kZXNjcmlwdGlvbnMtaXRlbSBsYWJlbD1cIlBsYWNlXCI+U3V6aG91PC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJSZW1hcmtzXCI+XG4gICAgICA8ZWwtdGFnIHNpemU9XCJzbWFsbFwiPlNjaG9vbDwvZWwtdGFnPlxuICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiQWRkcmVzc1wiPlxuICAgICAgTm8uMTE4OCwgV3V6aG9uZyBBdmVudWUsIFd1emhvbmcgRGlzdHJpY3QsIFN1emhvdSwgSmlhbmdzdSBQcm92aW5jZVxuICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gIDwvZWwtZGVzY3JpcHRpb25zPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/descriptions/rowspan.vue)_

vue

```
<template>
  <el-descriptions title="Width horizontal list" border>
    <el-descriptions-item
      :rowspan="2"
      :width="140"
      label="Photo"
      align="center"
    >
      <el-image
        style="width: 100px; height: 100px"
        src="https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png"
      />
    </el-descriptions-item>
    <el-descriptions-item label="Username">kooriookami</el-descriptions-item>
    <el-descriptions-item label="Telephone">18100000000</el-descriptions-item>
    <el-descriptions-item label="Place">Suzhou</el-descriptions-item>
    <el-descriptions-item label="Remarks">
      <el-tag size="small">School</el-tag>
    </el-descriptions-item>
    <el-descriptions-item label="Address">
      No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province
    </el-descriptions-item>
  </el-descriptions>

  <el-descriptions
    title="Width vertical list"
    direction="vertical"
    border
    style="margin-top: 20px"
  >
    <el-descriptions-item
      :rowspan="2"
      :width="140"
      label="Photo"
      align="center"
    >
      <el-image
        style="width: 100px; height: 100px"
        src="https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png"
      />
    </el-descriptions-item>
    <el-descriptions-item label="Username">kooriookami</el-descriptions-item>
    <el-descriptions-item label="Telephone">18100000000</el-descriptions-item>
    <el-descriptions-item label="Place">Suzhou</el-descriptions-item>
    <el-descriptions-item label="Remarks">
      <el-tag size="small">School</el-tag>
    </el-descriptions-item>
    <el-descriptions-item label="Address">
      No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province
    </el-descriptions-item>
  </el-descriptions>
</template>
```

隐藏源代码

## 自定义样式 [​](#自定义样式)

Customized style list

<table class="el-descriptions__table is-bordered"><tbody><tr><td style="width:150px;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label is-right my-label" colspan="1">Username</td><td style="width:150px;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content is-center my-content" colspan="NaN">kooriookami</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label is-right" colspan="1">Telephone</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content is-center" colspan="NaN">18100000000</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label is-right" colspan="1">Place</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content is-center" colspan="NaN">Suzhou</td></tr><tr><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label is-right" colspan="1">Remarks</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content is-center" colspan="NaN"><span class="el-tag el-tag--primary el-tag--small el-tag--light" style="" data-v-caa66925=""><span class="el-tag__content">School</span></span></td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__label is-bordered-label is-right" colspan="1">Address</td><td style="width:;min-width:;" class="el-descriptions__cell el-descriptions__content is-bordered-content is-center" colspan="3">No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province</td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZGVzY3JpcHRpb25zIHRpdGxlPVwiQ3VzdG9taXplZCBzdHlsZSBsaXN0XCIgOmNvbHVtbj1cIjNcIiBib3JkZXI+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtXG4gICAgICBsYWJlbD1cIlVzZXJuYW1lXCJcbiAgICAgIGxhYmVsLWFsaWduPVwicmlnaHRcIlxuICAgICAgYWxpZ249XCJjZW50ZXJcIlxuICAgICAgbGFiZWwtY2xhc3MtbmFtZT1cIm15LWxhYmVsXCJcbiAgICAgIGNsYXNzLW5hbWU9XCJteS1jb250ZW50XCJcbiAgICAgIHdpZHRoPVwiMTUwcHhcIlxuICAgID5cbiAgICAgIGtvb3Jpb29rYW1pXG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJUZWxlcGhvbmVcIiBsYWJlbC1hbGlnbj1cInJpZ2h0XCIgYWxpZ249XCJjZW50ZXJcIj5cbiAgICAgIDE4MTAwMDAwMDAwXG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJQbGFjZVwiIGxhYmVsLWFsaWduPVwicmlnaHRcIiBhbGlnbj1cImNlbnRlclwiPlxuICAgICAgU3V6aG91XG4gICAgPC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJSZW1hcmtzXCIgbGFiZWwtYWxpZ249XCJyaWdodFwiIGFsaWduPVwiY2VudGVyXCI+XG4gICAgICA8ZWwtdGFnIHNpemU9XCJzbWFsbFwiPlNjaG9vbDwvZWwtdGFnPlxuICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiQWRkcmVzc1wiIGxhYmVsLWFsaWduPVwicmlnaHRcIiBhbGlnbj1cImNlbnRlclwiPlxuICAgICAgTm8uMTE4OCwgV3V6aG9uZyBBdmVudWUsIFd1emhvbmcgRGlzdHJpY3QsIFN1emhvdSwgSmlhbmdzdSBQcm92aW5jZVxuICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gIDwvZWwtZGVzY3JpcHRpb25zPlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlIHNjb3BlZD5cbjpkZWVwKC5teS1sYWJlbCkge1xuICBiYWNrZ3JvdW5kOiB2YXIoLS1lbC1jb2xvci1zdWNjZXNzLWxpZ2h0LTkpICFpbXBvcnRhbnQ7XG59XG46ZGVlcCgubXktY29udGVudCkge1xuICBiYWNrZ3JvdW5kOiB2YXIoLS1lbC1jb2xvci1kYW5nZXItbGlnaHQtOSk7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/descriptions/customized-style.vue)_

vue

```
<template>
  <el-descriptions title="Customized style list" :column="3" border>
    <el-descriptions-item
      label="Username"
      label-align="right"
      align="center"
      label-class-name="my-label"
      class-name="my-content"
      width="150px"
    >
      kooriookami
    </el-descriptions-item>
    <el-descriptions-item label="Telephone" label-align="right" align="center">
      18100000000
    </el-descriptions-item>
    <el-descriptions-item label="Place" label-align="right" align="center">
      Suzhou
    </el-descriptions-item>
    <el-descriptions-item label="Remarks" label-align="right" align="center">
      <el-tag size="small">School</el-tag>
    </el-descriptions-item>
    <el-descriptions-item label="Address" label-align="right" align="center">
      No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province
    </el-descriptions-item>
  </el-descriptions>
</template>

<style scoped>
:deep(.my-label) {
  background: var(--el-color-success-light-9) !important;
}
:deep(.my-content) {
  background: var(--el-color-danger-light-9);
}
</style>
```

隐藏源代码

## Descriptions API [​](#descriptions-api)

### Descriptions Attributes [​](#descriptions-attributes)

| 属性名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| border | 是否带有边框 | `boolean` | false |
| column | 一行 `Descriptions Item` 的数量 | `number` | 3 |
| direction | 排列的方向 | `enum` | horizontal |
| size | 列表的尺寸 | `enum` | — |
| title | 标题文本，显示在左上方 | `string` | '' |
| extra | 操作区文本，显示在右上方 | `string` | '' |
| label-width 2.8.8 | 每一列的标签宽度 | `string` / `number` | — |

### Descriptions Slots [​](#descriptions-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | Descriptions Item |
| title | 自定义标题，显示在左上方 | — |
| extra | 自定义操作区，显示在右上方 | — |

## DescriptionsItem API [​](#descriptionsitem-api)

### DescriptionsItem Attributes [​](#descriptionsitem-attributes)

| 属性名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| label | 标签文本 | `string` | '' |
| span | 列的数量 | `number` | 1 |
| rowspan 2.8.1 | 单元格应该跨越的行数 | `number` | 1 |
| width | 列的宽度，不同行相同列的宽度按最大值设定（如无 `border` ，宽度包含标签与内容） | `string` / `number` | '' |
| min-width | 列的最小宽度，与 `width` 的区别是 `width` 是固定的，`min-width` 会把剩余宽度按比例分配给设置了 `min-width` 的列（如无 `border`，宽度包含标签与内容） | `string` / `number` | '' |
| label-width 2.8.8 | 列标签宽，如果未设置，它将与列宽度相同。 比 `Descriptions` 的 `label-width` 优先级高 | `string` / `number` | — |
| align | 列的内容对齐方式（如无 `border`，对标签和内容均生效） | `enum` | left |
| label-align | 列的标签对齐方式，若不设置该项，则使用内容的对齐方式（如无 `border`，请使用 `align` 参数） | `enum` | — |
| class-name | 列的内容自定义类名 | `string` | '' |
| label-class-name | column label custom class name | `string` | '' |

### DescriptionsItem Slots [​](#descriptionsitem-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |
| label | 自定义标签 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/descriptions) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/descriptions.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/descriptions.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/33646534?v=4&size=64)](https://github.com/SevenDreamYang)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/34190570?v=4&size=64)](https://github.com/Lakphy)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/80440359?v=4&size=64)](https://github.com/guze2003)[![](https://avatars.githubusercontent.com/u/22659150?v=4&size=64)](https://github.com/ntnyq)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/35091020?v=4&size=64)](https://github.com/zzh948498)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/28584349?v=4&size=64)](https://github.com/wangcch)[![](https://avatars.githubusercontent.com/u/5701072?v=4&size=64)](https://github.com/Naeemo)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)

[Collapse 折叠面板](https://element-plus.org/zh-CN/component/collapse)

[Empty 空状态](https://element-plus.org/zh-CN/component/empty)




---
## [data/empty] Empty 空状态
> 官方文档: https://element-plus.org/zh-CN/component/empty.html

---

# Empty 空状态 [​](#empty-空状态)

更新日志待解决

5

空状态时的占位提示。

## 基础用法 [​](#基础用法)

description

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZW1wdHkgZGVzY3JpcHRpb249XCJkZXNjcmlwdGlvblwiIC8+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/empty/basic-usage.vue)_

vue

```
<template>
  <el-empty description="description" />
</template>
```

隐藏源代码

## 自定义图片 [​](#自定义图片)

通过设置 `image` 属性传入图片 URL。

![](https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png)

No Data

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZW1wdHlcbiAgICBpbWFnZT1cImh0dHBzOi8vc2hhZG93LmVsZW1lY2RuLmNvbS9hcHAvZWxlbWVudC9oYW1idXJnZXIuOWNmN2IwOTEtNTVlOS0xMWU5LWE5NzYtN2Y0ZDBiMDdlZWY2LnBuZ1wiXG4gIC8+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/empty/custom-image.vue)_

vue

```
<template>
  <el-empty
    image="https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png"
  />
</template>
```

隐藏源代码

## 图片尺寸 [​](#图片尺寸)

通过使用 `image-size` 属性来控制图片大小。

No Data

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZW1wdHkgOmltYWdlLXNpemU9XCIyMDBcIiAvPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/empty/image-size.vue)_

vue

```
<template>
  <el-empty :image-size="200" />
</template>
```

隐藏源代码

## 底部内容 [​](#底部内容)

使用默认插槽可在底部插入内容。

No Data

Button

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZW1wdHk+XG4gICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiPkJ1dHRvbjwvZWwtYnV0dG9uPlxuICA8L2VsLWVtcHR5PlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/empty/bottom-content.vue)_

vue

```
<template>
  <el-empty>
    <el-button type="primary">Button</el-button>
  </el-empty>
</template>
```

隐藏源代码

## 自定义样式 [​](#自定义样式)

您可以为empty组件设置自定义样式。 使用 `css/scss` 语言来更改全局或局部颜色。 我们设置了一些全局颜色变量：`--el-empty-fill-color-0`、`--el-empty-fill-color-1`、`--el-empty-fill-color-2`、……、`--el-empty-fill-color-9`。 您可以使用类似 `:root { --el-empty-fill-color-0: red; --el-empty-fill-color-1: blue; }` 等变量。 但通常，如果你想要更改样式，你需要更改所有颜色，因为这些颜色是一个组合。

### 默认变量 [​](#默认变量)

| 变量 | 颜色 |
| --- | --- |
| \--el-empty-fill-color-0 | var(--el-color-white) |
| \--el-empty-fill-color-1 | #fcfcfd |
| \--el-empty-fill-color-2 | #f8f9fb |
| \--el-empty-fill-color-3 | #f7f8fc |
| \--el-empty-fill-color-4 | #eeeff3 |
| \--el-empty-fill-color-5 | #edeef2 |
| \--el-empty-fill-color-6 | #e9ebef |
| \--el-empty-fill-color-7 | #e5e7e9 |
| \--el-empty-fill-color-8 | #e0e3e9 |
| \--el-empty-fill-color-9 | #d5d7de |

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| image | empty 组件的图像地址 | `string` | '' |
| image-size | empty 组件的图像尺寸（宽度） | `number` | — |
| description | empty 组件的描述信息 | `string` | '' |

### 插槽 [​](#插槽)

| 插槽名 | 描述说明 |
| --- | --- |
| default | 作为底部内容的内容 |
| image | 作为图像的内容 |
| description | 作为描述的内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/empty) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/empty.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/empty.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/100674?v=4&size=64)](https://github.com/d--j)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/33497338?v=4&size=64)](https://github.com/MoConWu)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)

[Descriptions 描述列表](https://element-plus.org/zh-CN/component/descriptions)

[Image 图片](https://element-plus.org/zh-CN/component/image)




---
## [data/image] Image 图片
> 官方文档: https://element-plus.org/zh-CN/component/image.html

---

# Image 图片 [​](#image-图片)

更新日志待解决

5

图片容器，在保留所有原生 img 的特性下，支持懒加载，自定义占位、加载失败等

## 基础用法 [​](#基础用法)

可通过`fit`确定图片如何适应到容器框，同原生 [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit)。

fill

![](https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg)

contain

![](https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg)

cover

![](https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg)

none

![](https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg)

scale-down

![](https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbWFnZVwiPlxuICAgIDxkaXYgdi1mb3I9XCJmaXQgaW4gZml0c1wiIDprZXk9XCJmaXRcIiBjbGFzcz1cImJsb2NrXCI+XG4gICAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj57eyBmaXQgfX08L3NwYW4+XG4gICAgICA8ZWwtaW1hZ2Ugc3R5bGU9XCJ3aWR0aDogMTAwcHg7IGhlaWdodDogMTAwcHhcIiA6c3JjPVwidXJsXCIgOmZpdD1cImZpdFwiIC8+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB0eXBlIHsgSW1hZ2VQcm9wcyB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgZml0cyA9IFtcbiAgJ2ZpbGwnLFxuICAnY29udGFpbicsXG4gICdjb3ZlcicsXG4gICdub25lJyxcbiAgJ3NjYWxlLWRvd24nLFxuXSBhcyBJbWFnZVByb3BzWydmaXQnXVtdXG5jb25zdCB1cmwgPVxuICAnaHR0cHM6Ly9mdXNzMTAuZWxlbWVjZG4uY29tL2UvNWQvNGE3MzFhOTA1OTRhNGFmNTQ0YzBjMjU5NDExNzFqcGVnLmpwZWcnXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWltYWdlIC5ibG9jayB7XG4gIHBhZGRpbmc6IDMwcHggMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBib3JkZXItcmlnaHQ6IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICBkaXNwbGF5OiBpbmxpbmUtYmxvY2s7XG4gIHdpZHRoOiAyMCU7XG4gIG1pbi13aWR0aDogMTAwcHg7XG4gIGJveC1zaXppbmc6IGJvcmRlci1ib3g7XG4gIHZlcnRpY2FsLWFsaWduOiB0b3A7XG59XG4uZGVtby1pbWFnZSAuYmxvY2s6bGFzdC1jaGlsZCB7XG4gIGJvcmRlci1yaWdodDogbm9uZTtcbn1cbi5kZW1vLWltYWdlIC5kZW1vbnN0cmF0aW9uIHtcbiAgZGlzcGxheTogYmxvY2s7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG4gIGZvbnQtc2l6ZTogMTRweDtcbiAgbWFyZ2luLWJvdHRvbTogMjBweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/image/basic-usage.vue)_

vue

```
<template>
  <div class="demo-image">
    <div v-for="fit in fits" :key="fit" class="block">
      <span class="demonstration">{{ fit }}</span>
      <el-image style="width: 100px; height: 100px" :src="url" :fit="fit" />
    </div>
  </div>
</template>

<script lang="ts" setup>
import type { ImageProps } from 'element-plus'

const fits = [
  'fill',
  'contain',
  'cover',
  'none',
  'scale-down',
] as ImageProps['fit'][]
const url =
  'https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg'
</script>

<style scoped>
.demo-image .block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  display: inline-block;
  width: 20%;
  min-width: 100px;
  box-sizing: border-box;
  vertical-align: top;
}
.demo-image .block:last-child {
  border-right: none;
}
.demo-image .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}
</style>
```

隐藏源代码

## 占位内容 [​](#占位内容)

可通过`slot = placeholder`可自定义占位内容

Default

![](https://cube.elemecdn.com/6/94/4d3ea53c084bad6931a56d5158a48jpeg.jpeg)

Custom

![](https://cube.elemecdn.com/6/94/4d3ea53c084bad6931a56d5158a48jpeg.jpeg)

Loading...

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbWFnZV9fcGxhY2Vob2xkZXJcIj5cbiAgICA8ZGl2IGNsYXNzPVwiYmxvY2tcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPkRlZmF1bHQ8L3NwYW4+XG4gICAgICA8ZWwtaW1hZ2UgOnNyYz1cInNyY1wiIC8+XG4gICAgPC9kaXY+XG4gICAgPGRpdiBjbGFzcz1cImJsb2NrXCI+XG4gICAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5DdXN0b208L3NwYW4+XG4gICAgICA8ZWwtaW1hZ2UgOnNyYz1cInNyY1wiPlxuICAgICAgICA8dGVtcGxhdGUgI3BsYWNlaG9sZGVyPlxuICAgICAgICAgIDxkaXYgY2xhc3M9XCJpbWFnZS1zbG90XCI+TG9hZGluZzxzcGFuIGNsYXNzPVwiZG90XCI+Li4uPC9zcGFuPjwvZGl2PlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1pbWFnZT5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuY29uc3Qgc3JjID1cbiAgJ2h0dHBzOi8vY3ViZS5lbGVtZWNkbi5jb20vNi85NC80ZDNlYTUzYzA4NGJhZDY5MzFhNTZkNTE1OGE0OGpwZWcuanBlZydcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8taW1hZ2VfX3BsYWNlaG9sZGVyIC5ibG9jayB7XG4gIHBhZGRpbmc6IDMwcHggMDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xuICBib3JkZXItcmlnaHQ6IHNvbGlkIDFweCB2YXIoLS1lbC1ib3JkZXItY29sb3IpO1xuICBkaXNwbGF5OiBpbmxpbmUtYmxvY2s7XG4gIHdpZHRoOiA0OSU7XG4gIGJveC1zaXppbmc6IGJvcmRlci1ib3g7XG4gIHZlcnRpY2FsLWFsaWduOiB0b3A7XG59XG4uZGVtby1pbWFnZV9fcGxhY2Vob2xkZXIgLmRlbW9uc3RyYXRpb24ge1xuICBkaXNwbGF5OiBibG9jaztcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbiAgZm9udC1zaXplOiAxNHB4O1xuICBtYXJnaW4tYm90dG9tOiAyMHB4O1xufVxuLmRlbW8taW1hZ2VfX3BsYWNlaG9sZGVyIC5lbC1pbWFnZSB7XG4gIHBhZGRpbmc6IDAgNXB4O1xuICBtYXgtd2lkdGg6IDMwMHB4O1xuICBtYXgtaGVpZ2h0OiAyMDBweDtcbn1cblxuLmRlbW8taW1hZ2VfX3BsYWNlaG9sZGVyLmltYWdlLXNsb3Qge1xuICBkaXNwbGF5OiBmbGV4O1xuICBqdXN0aWZ5LWNvbnRlbnQ6IGNlbnRlcjtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbiAgd2lkdGg6IDEwMCU7XG4gIGhlaWdodDogMTAwJTtcbiAgYmFja2dyb3VuZDogdmFyKC0tZWwtZmlsbC1jb2xvci1saWdodCk7XG4gIGNvbG9yOiB2YXIoLS1lbC10ZXh0LWNvbG9yLXNlY29uZGFyeSk7XG4gIGZvbnQtc2l6ZTogMTRweDtcbn1cbi5kZW1vLWltYWdlX19wbGFjZWhvbGRlciAuZG90IHtcbiAgYW5pbWF0aW9uOiBkb3QgMnMgaW5maW5pdGUgc3RlcHMoMywgc3RhcnQpO1xuICBvdmVyZmxvdzogaGlkZGVuO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/image/placeholder.vue)_

vue

```
<template>
  <div class="demo-image__placeholder">
    <div class="block">
      <span class="demonstration">Default</span>
      <el-image :src="src" />
    </div>
    <div class="block">
      <span class="demonstration">Custom</span>
      <el-image :src="src">
        <template #placeholder>
          <div class="image-slot">Loading<span class="dot">...</span></div>
        </template>
      </el-image>
    </div>
  </div>
</template>

<script lang="ts" setup>
const src =
  'https://cube.elemecdn.com/6/94/4d3ea53c084bad6931a56d5158a48jpeg.jpeg'
</script>

<style scoped>
.demo-image__placeholder .block {
  padding: 30px 0;
  text-align: center;
  border-right: solid 1px var(--el-border-color);
  display: inline-block;
  width: 49%;
  box-sizing: border-box;
  vertical-align: top;
}
.demo-image__placeholder .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}
.demo-image__placeholder .el-image {
  padding: 0 5px;
  max-width: 300px;
  max-height: 200px;
}

.demo-image__placeholder.image-slot {
  display: flex;
  justify-content: center;
  align-items: center;
  width: 100%;
  height: 100%;
  background: var(--el-fill-color-light);
  color: var(--el-text-color-secondary);
  font-size: 14px;
}
.demo-image__placeholder .dot {
  animation: dot 2s infinite steps(3, start);
  overflow: hidden;
}
</style>
```

隐藏源代码

## 加载失败 [​](#加载失败)

通过 `slot = error` and `slot = viewer-error`自定义图像加载错误时的内容。

FAILED

![](https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg)

preview controlled

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbWFnZV9fZXJyb3JcIiBmbGV4IGdhcC0yPlxuICAgIDxlbC1pbWFnZSAvPlxuICAgIDxlbC1pbWFnZT5cbiAgICAgIDx0ZW1wbGF0ZSAjZXJyb3I+XG4gICAgICAgIDxkaXYgY2xhc3M9XCJpbWFnZS12aWV3ZXItc2xvdCBpbWFnZS1zbG90XCI+XG4gICAgICAgICAgPGVsLWljb24+PGljb24tcGljdHVyZSAvPjwvZWwtaWNvbj5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtaW1hZ2U+XG4gICAgPGVsLWltYWdlIDpzcmM9XCJ1cmxcIiA6cHJldmlldy1zcmMtbGlzdD1cInNyY0xpc3RcIiBzaG93LXByb2dyZXNzPlxuICAgICAgPHRlbXBsYXRlICN2aWV3ZXItZXJyb3I9XCJ7IGFjdGl2ZUluZGV4LCBzcmMgfVwiPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiaW1hZ2Utc2xvdCB2aWV3ZXItZXJyb3JcIj5cbiAgICAgICAgICA8ZWwtaWNvbj48aWNvbi1waWN0dXJlIC8+PC9lbC1pY29uPlxuICAgICAgICAgIDxzcGFuPlxuICAgICAgICAgICAgdGhpcyBpcyB2aWV3ZXItZXJyb3Igc2xvdC4gY3VycmVudCBpbmRleDoge3sgYWN0aXZlSW5kZXggfX0uIHNyYzpcbiAgICAgICAgICAgIHt7IHNyYyB9fVxuICAgICAgICAgIDwvc3Bhbj5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtaW1hZ2U+XG4gICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJzaG93UHJldmlldyA9IHRydWVcIj4gcHJldmlldyBjb250cm9sbGVkIDwvZWwtYnV0dG9uPlxuXG4gICAgPGVsLWltYWdlLXZpZXdlclxuICAgICAgdi1pZj1cInNob3dQcmV2aWV3XCJcbiAgICAgIHNob3ctcHJvZ3Jlc3NcbiAgICAgIDp1cmwtbGlzdD1cInNyY0xpc3RcIlxuICAgICAgQGNsb3NlPVwic2hvd1ByZXZpZXcgPSBmYWxzZVwiXG4gICAgPlxuICAgICAgPHRlbXBsYXRlICN2aWV3ZXItZXJyb3I9XCJ7IGFjdGl2ZUluZGV4LCBzcmMgfVwiPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiaW1hZ2Utc2xvdCB2aWV3ZXItZXJyb3JcIj5cbiAgICAgICAgICA8ZWwtaWNvbj48aWNvbi1waWN0dXJlIC8+PC9lbC1pY29uPlxuICAgICAgICAgIDxzcGFuPlxuICAgICAgICAgICAgdGhpcyBpcyB2aWV3ZXItZXJyb3Igc2xvdC4gY3VycmVudCBpbmRleDoge3sgYWN0aXZlSW5kZXggfX0uIHNyYzpcbiAgICAgICAgICAgIHt7IHNyYyB9fVxuICAgICAgICAgIDwvc3Bhbj5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtaW1hZ2Utdmlld2VyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBQaWN0dXJlIGFzIEljb25QaWN0dXJlIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmNvbnN0IHNob3dQcmV2aWV3ID0gcmVmKGZhbHNlKVxuXG5jb25zdCBzcmNMaXN0ID0gW1xuICAnaHR0cHM6Ly9mdXNzMTAuZWxlbWVjZG4uY29tL2EvM2YvMzMwMmU1OGY5YTE4MWQyNTA5ZjNkYzBmYTY4YjBqcGVnLmpwZWcnLFxuICAnaHR0cHM6Ly9lcnJvclNyYycsXG5dXG5jb25zdCB1cmwgPVxuICAnaHR0cHM6Ly9mdXNzMTAuZWxlbWVjZG4uY29tL2EvM2YvMzMwMmU1OGY5YTE4MWQyNTA5ZjNkYzBmYTY4YjBqcGVnLmpwZWcnXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWltYWdlX19lcnJvciAuZWwtaW1hZ2Uge1xuICBtYXgtd2lkdGg6IDMwMHB4O1xuICBtYXgtaGVpZ2h0OiAyMDBweDtcbiAgd2lkdGg6IDEwMCU7XG59XG5cbi5kZW1vLWltYWdlX19lcnJvciAuaW1hZ2Utc2xvdCB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGp1c3RpZnktY29udGVudDogY2VudGVyO1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBmbGV4LWRpcmVjdGlvbjogY29sdW1uO1xuICBmb250LXNpemU6IDMwcHg7XG4gIGhlaWdodDogMjAwcHg7XG4gIGJhY2tncm91bmQ6ICNmZmY7XG59XG4uZGVtby1pbWFnZV9fZXJyb3IgLmltYWdlLXNsb3QgLmVsLWljb24ge1xuICBmb250LXNpemU6IDMwcHg7XG59XG4uaW1hZ2Utdmlld2VyLXNsb3Qge1xuICBiYWNrZ3JvdW5kOiB2YXIoLS1lbC1maWxsLWNvbG9yLWxpZ2h0KTtcbn1cbi52aWV3ZXItZXJyb3Ige1xuICBjb2xvcjogIzAwMDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/image/load-failed.vue)_

vue

```
<template>
  <div class="demo-image__error" flex gap-2>
    <el-image />
    <el-image>
      <template #error>
        <div class="image-viewer-slot image-slot">
          <el-icon><icon-picture /></el-icon>
        </div>
      </template>
    </el-image>
    <el-image :src="url" :preview-src-list="srcList" show-progress>
      <template #viewer-error="{ activeIndex, src }">
        <div class="image-slot viewer-error">
          <el-icon><icon-picture /></el-icon>
          <span>
            this is viewer-error slot. current index: {{ activeIndex }}. src:
            {{ src }}
          </span>
        </div>
      </template>
    </el-image>
    <el-button @click="showPreview = true"> preview controlled </el-button>

    <el-image-viewer
      v-if="showPreview"
      show-progress
      :url-list="srcList"
      @close="showPreview = false"
    >
      <template #viewer-error="{ activeIndex, src }">
        <div class="image-slot viewer-error">
          <el-icon><icon-picture /></el-icon>
          <span>
            this is viewer-error slot. current index: {{ activeIndex }}. src:
            {{ src }}
          </span>
        </div>
      </template>
    </el-image-viewer>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Picture as IconPicture } from '@element-plus/icons-vue'

const showPreview = ref(false)

const srcList = [
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg',
  'https://errorSrc',
]
const url =
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg'
</script>

<style scoped>
.demo-image__error .el-image {
  max-width: 300px;
  max-height: 200px;
  width: 100%;
}

.demo-image__error .image-slot {
  display: flex;
  justify-content: center;
  align-items: center;
  flex-direction: column;
  font-size: 30px;
  height: 200px;
  background: #fff;
}
.demo-image__error .image-slot .el-icon {
  font-size: 30px;
}
.image-viewer-slot {
  background: var(--el-fill-color-light);
}
.viewer-error {
  color: #000;
}
</style>
```

隐藏源代码

## 懒加载 [​](#懒加载)

TIP

浏览器原生支持的 `loading`属性在 2.2.3版本加入。 您可以使用 `loading="lazy"` 替换之前的`lazy= true`。

如果当前浏览器支持原生图片延迟加载，则先使用原生能力，否则将使用滚动监听实现相同效果。

可通过`lazy`开启懒加载功能， 当图片滚动到可视范围内才会加载。 可通过 `scroll-container` 来设置滚动容器， 若未定义，则为最近一个 overflow 值为 auto 或 scroll 的父元素。

![](https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg)

![](https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbWFnZV9fbGF6eVwiPlxuICAgIDxlbC1pbWFnZSB2LWZvcj1cInVybCBpbiB1cmxzXCIgOmtleT1cInVybFwiIDpzcmM9XCJ1cmxcIiBsYXp5IC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IHVybHMgPSBbXG4gICdodHRwczovL2Z1c3MxMC5lbGVtZWNkbi5jb20vYS8zZi8zMzAyZTU4ZjlhMTgxZDI1MDlmM2RjMGZhNjhiMGpwZWcuanBlZycsXG4gICdodHRwczovL2Z1c3MxMC5lbGVtZWNkbi5jb20vMS8zNC8xOWFhOThiMWZjYjI3ODFjNGZiYTMzZDg1MDU0OWpwZWcuanBlZycsXG4gICdodHRwczovL2Z1c3MxMC5lbGVtZWNkbi5jb20vMC82Zi9lMzVmZjM3NTgxMmU2YjAwMjBiNmI0ZThmOTU4M2pwZWcuanBlZycsXG4gICdodHRwczovL2Z1c3MxMC5lbGVtZWNkbi5jb20vOS9iYi9lMjc4NThlOTczZjVkN2QzOTA0ODM1ZjQ2YWJiZGpwZWcuanBlZycsXG4gICdodHRwczovL2Z1c3MxMC5lbGVtZWNkbi5jb20vZC9lNi9jNGQ5M2EzODA1YjNjZTNmMzIzZjc5NzRlNmY3OGpwZWcuanBlZycsXG4gICdodHRwczovL2Z1c3MxMC5lbGVtZWNkbi5jb20vMy8yOC9iYmY4OTNmNzkyZjAzYTU0NDA4YjNiN2E3ZWJmMGpwZWcuanBlZycsXG4gICdodHRwczovL2Z1c3MxMC5lbGVtZWNkbi5jb20vMi8xMS82NTM1YmNmYjI2ZTRjNzliNDhkZGRlNDRmNGI2ZmpwZWcuanBlZycsXG5dXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLWltYWdlX19sYXp5IHtcbiAgaGVpZ2h0OiA0MDBweDtcbiAgb3ZlcmZsb3cteTogYXV0bztcbn1cbi5kZW1vLWltYWdlX19sYXp5IC5lbC1pbWFnZSB7XG4gIGRpc3BsYXk6IGJsb2NrO1xuICBtaW4taGVpZ2h0OiAyMDBweDtcbiAgbWFyZ2luLWJvdHRvbTogMTBweDtcbn1cbi5kZW1vLWltYWdlX19sYXp5IC5lbC1pbWFnZTpsYXN0LWNoaWxkIHtcbiAgbWFyZ2luLWJvdHRvbTogMDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/image/lazy-load.vue)_

vue

```
<template>
  <div class="demo-image__lazy">
    <el-image v-for="url in urls" :key="url" :src="url" lazy />
  </div>
</template>

<script lang="ts" setup>
const urls = [
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg',
  'https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg',
  'https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg',
  'https://fuss10.elemecdn.com/9/bb/e27858e973f5d7d3904835f46abbdjpeg.jpeg',
  'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
  'https://fuss10.elemecdn.com/3/28/bbf893f792f03a54408b3b7a7ebf0jpeg.jpeg',
  'https://fuss10.elemecdn.com/2/11/6535bcfb26e4c79b48ddde44f4b6fjpeg.jpeg',
]
</script>

<style scoped>
.demo-image__lazy {
  height: 400px;
  overflow-y: auto;
}
.demo-image__lazy .el-image {
  display: block;
  min-height: 200px;
  margin-bottom: 10px;
}
.demo-image__lazy .el-image:last-child {
  margin-bottom: 0;
}
</style>
```

隐藏源代码

## 图片预览 [​](#图片预览)

可通过 `previewSrcList` 开启预览大图的功能。 你可以通过 `initial-index` 初始化第一张预览图片的位置。 默认初始位置为 0。

![](https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbWFnZV9fcHJldmlld1wiPlxuICAgIDxlbC1pbWFnZVxuICAgICAgc3R5bGU9XCJ3aWR0aDogMTAwcHg7IGhlaWdodDogMTAwcHhcIlxuICAgICAgOnNyYz1cInVybFwiXG4gICAgICA6em9vbS1yYXRlPVwiMS4yXCJcbiAgICAgIDptYXgtc2NhbGU9XCI3XCJcbiAgICAgIDptaW4tc2NhbGU9XCIwLjJcIlxuICAgICAgOnByZXZpZXctc3JjLWxpc3Q9XCJzcmNMaXN0XCJcbiAgICAgIHNob3ctcHJvZ3Jlc3NcbiAgICAgIDppbml0aWFsLWluZGV4PVwiNFwiXG4gICAgICBmaXQ9XCJjb3ZlclwiXG4gICAgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuY29uc3QgdXJsID1cbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9hLzNmLzMzMDJlNThmOWExODFkMjUwOWYzZGMwZmE2OGIwanBlZy5qcGVnJ1xuY29uc3Qgc3JjTGlzdCA9IFtcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9hLzNmLzMzMDJlNThmOWExODFkMjUwOWYzZGMwZmE2OGIwanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8xLzM0LzE5YWE5OGIxZmNiMjc4MWM0ZmJhMzNkODUwNTQ5anBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8wLzZmL2UzNWZmMzc1ODEyZTZiMDAyMGI2YjRlOGY5NTgzanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS85L2JiL2UyNzg1OGU5NzNmNWQ3ZDM5MDQ4MzVmNDZhYmJkanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9kL2U2L2M0ZDkzYTM4MDViM2NlM2YzMjNmNzk3NGU2Zjc4anBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8zLzI4L2JiZjg5M2Y3OTJmMDNhNTQ0MDhiM2I3YTdlYmYwanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8yLzExLzY1MzViY2ZiMjZlNGM3OWI0OGRkZGU0NGY0YjZmanBlZy5qcGVnJyxcbl1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8taW1hZ2VfX2Vycm9yIC5pbWFnZS1zbG90IHtcbiAgZm9udC1zaXplOiAzMHB4O1xufVxuLmRlbW8taW1hZ2VfX2Vycm9yIC5pbWFnZS1zbG90IC5lbC1pY29uIHtcbiAgZm9udC1zaXplOiAzMHB4O1xufVxuLmRlbW8taW1hZ2VfX2Vycm9yIC5lbC1pbWFnZSB7XG4gIHdpZHRoOiAxMDAlO1xuICBoZWlnaHQ6IDIwMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/image/image-preview.vue)_

vue

```
<template>
  <div class="demo-image__preview">
    <el-image
      style="width: 100px; height: 100px"
      :src="url"
      :zoom-rate="1.2"
      :max-scale="7"
      :min-scale="0.2"
      :preview-src-list="srcList"
      show-progress
      :initial-index="4"
      fit="cover"
    />
  </div>
</template>

<script lang="ts" setup>
const url =
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg'
const srcList = [
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg',
  'https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg',
  'https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg',
  'https://fuss10.elemecdn.com/9/bb/e27858e973f5d7d3904835f46abbdjpeg.jpeg',
  'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
  'https://fuss10.elemecdn.com/3/28/bbf893f792f03a54408b3b7a7ebf0jpeg.jpeg',
  'https://fuss10.elemecdn.com/2/11/6535bcfb26e4c79b48ddde44f4b6fjpeg.jpeg',
]
</script>

<style scoped>
.demo-image__error .image-slot {
  font-size: 30px;
}
.demo-image__error .image-slot .el-icon {
  font-size: 30px;
}
.demo-image__error .el-image {
  width: 100%;
  height: 200px;
}
</style>
```

隐藏源代码

## 手动打开预览 2.9.4 [​](#手动打开预览)

openPreview with showPreview method

![](https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg)

preview controlled

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtMTJcIj5cbiAgICA8ZGl2IGNsYXNzPVwiZ3JpZCBnYXAtM1wiPlxuICAgICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJoYW5kbGVDbGlja1wiPlxuICAgICAgICBvcGVuUHJldmlldyB3aXRoIHNob3dQcmV2aWV3IG1ldGhvZFxuICAgICAgPC9lbC1idXR0b24+XG4gICAgICA8ZWwtaW1hZ2VcbiAgICAgICAgcmVmPVwiaW1hZ2VSZWZcIlxuICAgICAgICBzdHlsZT1cIndpZHRoOiAxMDBweDsgaGVpZ2h0OiAxMDBweFwiXG4gICAgICAgIDpzcmM9XCJ1cmxcIlxuICAgICAgICBzaG93LXByb2dyZXNzXG4gICAgICAgIDpwcmV2aWV3LXNyYy1saXN0PVwic3JjTGlzdFwiXG4gICAgICAgIGZpdD1cImNvdmVyXCJcbiAgICAgIC8+XG4gICAgPC9kaXY+XG4gICAgPGRpdj5cbiAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwic2hvd1ByZXZpZXcgPSB0cnVlXCI+IHByZXZpZXcgY29udHJvbGxlZCA8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1pbWFnZS12aWV3ZXJcbiAgICAgICAgdi1pZj1cInNob3dQcmV2aWV3XCJcbiAgICAgICAgOnVybC1saXN0PVwic3JjTGlzdFwiXG4gICAgICAgIHNob3ctcHJvZ3Jlc3NcbiAgICAgICAgOmluaXRpYWwtaW5kZXg9XCI0XCJcbiAgICAgICAgQGNsb3NlPVwic2hvd1ByZXZpZXcgPSBmYWxzZVwiXG4gICAgICAvPlxuICAgIDwvZGl2PlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgSW1hZ2VJbnN0YW5jZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgdXJsID1cbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9hLzNmLzMzMDJlNThmOWExODFkMjUwOWYzZGMwZmE2OGIwanBlZy5qcGVnJ1xuY29uc3Qgc3JjTGlzdCA9IFtcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9hLzNmLzMzMDJlNThmOWExODFkMjUwOWYzZGMwZmE2OGIwanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8xLzM0LzE5YWE5OGIxZmNiMjc4MWM0ZmJhMzNkODUwNTQ5anBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8wLzZmL2UzNWZmMzc1ODEyZTZiMDAyMGI2YjRlOGY5NTgzanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS85L2JiL2UyNzg1OGU5NzNmNWQ3ZDM5MDQ4MzVmNDZhYmJkanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9kL2U2L2M0ZDkzYTM4MDViM2NlM2YzMjNmNzk3NGU2Zjc4anBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8zLzI4L2JiZjg5M2Y3OTJmMDNhNTQ0MDhiM2I3YTdlYmYwanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8yLzExLzY1MzViY2ZiMjZlNGM3OWI0OGRkZGU0NGY0YjZmanBlZy5qcGVnJyxcbl1cblxuY29uc3QgaW1hZ2VSZWYgPSByZWY8SW1hZ2VJbnN0YW5jZT4oKVxuY29uc3Qgc2hvd1ByZXZpZXcgPSByZWYoZmFsc2UpXG5cbmNvbnN0IGhhbmRsZUNsaWNrID0gKCkgPT4ge1xuICBpbWFnZVJlZi52YWx1ZSEuc2hvd1ByZXZpZXcoKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/image/manually-preview.vue)_

vue

```
<template>
  <div class="flex gap-12">
    <div class="grid gap-3">
      <el-button @click="handleClick">
        openPreview with showPreview method
      </el-button>
      <el-image
        ref="imageRef"
        style="width: 100px; height: 100px"
        :src="url"
        show-progress
        :preview-src-list="srcList"
        fit="cover"
      />
    </div>
    <div>
      <el-button @click="showPreview = true"> preview controlled </el-button>
      <el-image-viewer
        v-if="showPreview"
        :url-list="srcList"
        show-progress
        :initial-index="4"
        @close="showPreview = false"
      />
    </div>
  </div>
</template>

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

import type { ImageInstance } from 'element-plus'

const url =
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg'
const srcList = [
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg',
  'https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg',
  'https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg',
  'https://fuss10.elemecdn.com/9/bb/e27858e973f5d7d3904835f46abbdjpeg.jpeg',
  'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
  'https://fuss10.elemecdn.com/3/28/bbf893f792f03a54408b3b7a7ebf0jpeg.jpeg',
  'https://fuss10.elemecdn.com/2/11/6535bcfb26e4c79b48ddde44f4b6fjpeg.jpeg',
]

const imageRef = ref<ImageInstance>()
const showPreview = ref(false)

const handleClick = () => {
  imageRef.value!.showPreview()
}
</script>
```

隐藏源代码

## 自定义工具栏2.9.4 [​](#自定义工具栏)

可通过 `toolbar` 插槽自定义工具栏内容，自版本 2.9.7 起，插槽中添加了 `setActiveItem` 方法，用于根据索引切换图片。

![](https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbWFnZV9fY3VzdG9tLXRvb2xiYXJcIj5cbiAgICA8ZWwtaW1hZ2VcbiAgICAgIHN0eWxlPVwid2lkdGg6IDEwMHB4OyBoZWlnaHQ6IDEwMHB4XCJcbiAgICAgIDpzcmM9XCJ1cmxcIlxuICAgICAgOnByZXZpZXctc3JjLWxpc3Q9XCJzcmNMaXN0XCJcbiAgICAgIGZpdD1cImNvdmVyXCJcbiAgICAgIHNob3ctcHJvZ3Jlc3NcbiAgICA+XG4gICAgICA8dGVtcGxhdGVcbiAgICAgICAgI3Rvb2xiYXI9XCJ7IGFjdGlvbnMsIHByZXYsIG5leHQsIHJlc2V0LCBhY3RpdmVJbmRleCwgc2V0QWN0aXZlSXRlbSB9XCJcbiAgICAgID5cbiAgICAgICAgPGVsLWljb24gQGNsaWNrPVwicHJldlwiPjxCYWNrIC8+PC9lbC1pY29uPlxuICAgICAgICA8ZWwtaWNvbiBAY2xpY2s9XCJuZXh0XCI+PFJpZ2h0IC8+PC9lbC1pY29uPlxuICAgICAgICA8ZWwtaWNvbiBAY2xpY2s9XCJzZXRBY3RpdmVJdGVtKHNyY0xpc3QubGVuZ3RoIC0gMSlcIj5cbiAgICAgICAgICA8REFycm93UmlnaHQgLz5cbiAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICA8ZWwtaWNvbiBAY2xpY2s9XCJhY3Rpb25zKCd6b29tT3V0JylcIj48Wm9vbU91dCAvPjwvZWwtaWNvbj5cbiAgICAgICAgPGVsLWljb25cbiAgICAgICAgICBAY2xpY2s9XCJhY3Rpb25zKCd6b29tSW4nLCB7IGVuYWJsZVRyYW5zaXRpb246IGZhbHNlLCB6b29tUmF0ZTogMiB9KVwiXG4gICAgICAgID5cbiAgICAgICAgICA8Wm9vbUluIC8+XG4gICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgPGVsLWljb25cbiAgICAgICAgICBAY2xpY2s9XCJcbiAgICAgICAgICAgIGFjdGlvbnMoJ2Nsb2Nrd2lzZScsIHsgcm90YXRlRGVnOiAxODAsIGVuYWJsZVRyYW5zaXRpb246IGZhbHNlIH0pXG4gICAgICAgICAgXCJcbiAgICAgICAgPlxuICAgICAgICAgIDxSZWZyZXNoUmlnaHQgLz5cbiAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICA8ZWwtaWNvbiBAY2xpY2s9XCJhY3Rpb25zKCdhbnRpY2xvY2t3aXNlJylcIj48UmVmcmVzaExlZnQgLz48L2VsLWljb24+XG4gICAgICAgIDxlbC1pY29uIEBjbGljaz1cInJlc2V0XCI+PFJlZnJlc2ggLz48L2VsLWljb24+XG4gICAgICAgIDxlbC1pY29uIEBjbGljaz1cImRvd25sb2FkKGFjdGl2ZUluZGV4KVwiPjxEb3dubG9hZCAvPjwvZWwtaWNvbj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1pbWFnZT5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRWxJY29uIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuaW1wb3J0IHtcbiAgQmFjayxcbiAgREFycm93UmlnaHQsXG4gIERvd25sb2FkLFxuICBSZWZyZXNoLFxuICBSZWZyZXNoTGVmdCxcbiAgUmVmcmVzaFJpZ2h0LFxuICBSaWdodCxcbiAgWm9vbUluLFxuICBab29tT3V0LFxufSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgdXJsID1cbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9hLzNmLzMzMDJlNThmOWExODFkMjUwOWYzZGMwZmE2OGIwanBlZy5qcGVnJ1xuY29uc3Qgc3JjTGlzdCA9IFtcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9hLzNmLzMzMDJlNThmOWExODFkMjUwOWYzZGMwZmE2OGIwanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8xLzM0LzE5YWE5OGIxZmNiMjc4MWM0ZmJhMzNkODUwNTQ5anBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8wLzZmL2UzNWZmMzc1ODEyZTZiMDAyMGI2YjRlOGY5NTgzanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS85L2JiL2UyNzg1OGU5NzNmNWQ3ZDM5MDQ4MzVmNDZhYmJkanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9kL2U2L2M0ZDkzYTM4MDViM2NlM2YzMjNmNzk3NGU2Zjc4anBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8zLzI4L2JiZjg5M2Y3OTJmMDNhNTQ0MDhiM2I3YTdlYmYwanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8yLzExLzY1MzViY2ZiMjZlNGM3OWI0OGRkZGU0NGY0YjZmanBlZy5qcGVnJyxcbl1cblxuY29uc3QgZG93bmxvYWQgPSAoaW5kZXg6IG51bWJlcikgPT4ge1xuICBjb25zdCB1cmwgPSBzcmNMaXN0W2luZGV4XVxuICBjb25zdCBzdWZmaXggPSB1cmwuc2xpY2UodXJsLmxhc3RJbmRleE9mKCcuJykpXG4gIGNvbnN0IGZpbGVuYW1lID0gRGF0ZS5ub3coKSArIHN1ZmZpeFxuXG4gIGZldGNoKHVybClcbiAgICAudGhlbigocmVzcG9uc2UpID0+IHJlc3BvbnNlLmJsb2IoKSlcbiAgICAudGhlbigoYmxvYikgPT4ge1xuICAgICAgY29uc3QgYmxvYlVybCA9IFVSTC5jcmVhdGVPYmplY3RVUkwobmV3IEJsb2IoW2Jsb2JdKSlcbiAgICAgIGNvbnN0IGxpbmsgPSBkb2N1bWVudC5jcmVhdGVFbGVtZW50KCdhJylcbiAgICAgIGxpbmsuaHJlZiA9IGJsb2JVcmxcbiAgICAgIGxpbmsuZG93bmxvYWQgPSBmaWxlbmFtZVxuICAgICAgZG9jdW1lbnQuYm9keS5hcHBlbmRDaGlsZChsaW5rKVxuICAgICAgbGluay5jbGljaygpXG4gICAgICBVUkwucmV2b2tlT2JqZWN0VVJMKGJsb2JVcmwpXG4gICAgICBsaW5rLnJlbW92ZSgpXG4gICAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/image/custom-toolbar.vue)_

vue

```
<template>
  <div class="demo-image__custom-toolbar">
    <el-image
      style="width: 100px; height: 100px"
      :src="url"
      :preview-src-list="srcList"
      fit="cover"
      show-progress
    >
      <template
        #toolbar="{ actions, prev, next, reset, activeIndex, setActiveItem }"
      >
        <el-icon @click="prev"><Back /></el-icon>
        <el-icon @click="next"><Right /></el-icon>
        <el-icon @click="setActiveItem(srcList.length - 1)">
          <DArrowRight />
        </el-icon>
        <el-icon @click="actions('zoomOut')"><ZoomOut /></el-icon>
        <el-icon
          @click="actions('zoomIn', { enableTransition: false, zoomRate: 2 })"
        >
          <ZoomIn />
        </el-icon>
        <el-icon
          @click="
            actions('clockwise', { rotateDeg: 180, enableTransition: false })
          "
        >
          <RefreshRight />
        </el-icon>
        <el-icon @click="actions('anticlockwise')"><RefreshLeft /></el-icon>
        <el-icon @click="reset"><Refresh /></el-icon>
        <el-icon @click="download(activeIndex)"><Download /></el-icon>
      </template>
    </el-image>
  </div>
</template>

<script lang="ts" setup>
import { ElIcon } from 'element-plus'
import {
  Back,
  DArrowRight,
  Download,
  Refresh,
  RefreshLeft,
  RefreshRight,
  Right,
  ZoomIn,
  ZoomOut,
} from '@element-plus/icons-vue'

const url =
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg'
const srcList = [
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg',
  'https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg',
  'https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg',
  'https://fuss10.elemecdn.com/9/bb/e27858e973f5d7d3904835f46abbdjpeg.jpeg',
  'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
  'https://fuss10.elemecdn.com/3/28/bbf893f792f03a54408b3b7a7ebf0jpeg.jpeg',
  'https://fuss10.elemecdn.com/2/11/6535bcfb26e4c79b48ddde44f4b6fjpeg.jpeg',
]

const download = (index: number) => {
  const url = srcList[index]
  const suffix = url.slice(url.lastIndexOf('.'))
  const filename = Date.now() + suffix

  fetch(url)
    .then((response) => response.blob())
    .then((blob) => {
      const blobUrl = URL.createObjectURL(new Blob([blob]))
      const link = document.createElement('a')
      link.href = blobUrl
      link.download = filename
      document.body.appendChild(link)
      link.click()
      URL.revokeObjectURL(blobUrl)
      link.remove()
    })
}
</script>
```

隐藏源代码

## 自定义进度条 2.9.4 [​](#自定义进度条)

可通过 `show-progress` 控制是否在预览图片时显示进度条。 自版本 2.9.8 起，进度条会在使用 `progress` 插槽时显示。

![](https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1pbWFnZV9fY3VzdG9tLXRvb2xiYXJcIj5cbiAgICA8ZWwtaW1hZ2VcbiAgICAgIHN0eWxlPVwid2lkdGg6IDEwMHB4OyBoZWlnaHQ6IDEwMHB4XCJcbiAgICAgIDpzcmM9XCJ1cmxcIlxuICAgICAgOnByZXZpZXctc3JjLWxpc3Q9XCJzcmNMaXN0XCJcbiAgICAgIGZpdD1cImNvdmVyXCJcbiAgICA+XG4gICAgICA8dGVtcGxhdGUgI3Byb2dyZXNzPVwieyBhY3RpdmVJbmRleCwgdG90YWwgfVwiPlxuICAgICAgICA8c3Bhbj57eyBhY3RpdmVJbmRleCArIDEgKyAnLScgKyB0b3RhbCB9fTwvc3Bhbj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1pbWFnZT5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuY29uc3QgdXJsID1cbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9hLzNmLzMzMDJlNThmOWExODFkMjUwOWYzZGMwZmE2OGIwanBlZy5qcGVnJ1xuY29uc3Qgc3JjTGlzdCA9IFtcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9hLzNmLzMzMDJlNThmOWExODFkMjUwOWYzZGMwZmE2OGIwanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8xLzM0LzE5YWE5OGIxZmNiMjc4MWM0ZmJhMzNkODUwNTQ5anBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8wLzZmL2UzNWZmMzc1ODEyZTZiMDAyMGI2YjRlOGY5NTgzanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS85L2JiL2UyNzg1OGU5NzNmNWQ3ZDM5MDQ4MzVmNDZhYmJkanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS9kL2U2L2M0ZDkzYTM4MDViM2NlM2YzMjNmNzk3NGU2Zjc4anBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8zLzI4L2JiZjg5M2Y3OTJmMDNhNTQ0MDhiM2I3YTdlYmYwanBlZy5qcGVnJyxcbiAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8yLzExLzY1MzViY2ZiMjZlNGM3OWI0OGRkZGU0NGY0YjZmanBlZy5qcGVnJyxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/image/custom-progress.vue)_

vue

```
<template>
  <div class="demo-image__custom-toolbar">
    <el-image
      style="width: 100px; height: 100px"
      :src="url"
      :preview-src-list="srcList"
      fit="cover"
    >
      <template #progress="{ activeIndex, total }">
        <span>{{ activeIndex + 1 + '-' + total }}</span>
      </template>
    </el-image>
  </div>
</template>

<script lang="ts" setup>
const url =
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg'
const srcList = [
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg',
  'https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg',
  'https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg',
  'https://fuss10.elemecdn.com/9/bb/e27858e973f5d7d3904835f46abbdjpeg.jpeg',
  'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
  'https://fuss10.elemecdn.com/3/28/bbf893f792f03a54408b3b7a7ebf0jpeg.jpeg',
  'https://fuss10.elemecdn.com/2/11/6535bcfb26e4c79b48ddde44f4b6fjpeg.jpeg',
]
</script>
```

隐藏源代码

## Image API [​](#image-api)

### Image Attributes [​](#image-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| src | 图片源地址，同原生属性一致 | `string` | '' |
| fit | 确定图片如何适应容器框，同原生 [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) | `enum` | '' |
| hide-on-click-modal | 当开启 preview 功能时，是否可以通过点击遮罩层关闭 preview | `boolean` | false |
| loading 2.2.3 | 浏览器加载图像的策略，和 [浏览器原生](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading)能力一致 | `enum` | — |
| lazy | 是否使用懒加载 | `boolean` | false |
| scroll-container | 开启懒加载功能后，监听 scroll 事件的容器 默认情况下，开启懒加载功能后，监听 scroll 事件的容器 | `string` / `object` | — |
| alt | 原生属性 `alt` | `string` | — |
| referrerpolicy | 原生属性 [referrerPolicy](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/referrerPolicy)。 | `string` | — |
| crossorigin | 原生属性 [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) | `enum` | — |
| preview-src-list | 开启图片预览功能 | `array` | \[\] |
| z-index | 设置图片预览的 z-index | `number` | — |
| initial-index | 初始预览图像索引，小于 `url-list` 的长度 | `number` | 0 |
| close-on-press-escape | 是否可以通过按下 ESC 关闭 Image Viewer | `boolean` | true |
| preview-teleported | image-viewer 是否插入至 body 元素上。 嵌套的父元素属性会发生修改时应该将此属性设置为 `true` | `boolean` | false |
| infinite | 是否可以无限循环预览 | `boolean` | true |
| zoom-rate | 图像查看器缩放事件的缩放速率。 | `number` | 1.2 |
| scale 2.11.3 | 预览图像缩放。 | `number` | 1 |
| min-scale 2.4.0 | 图像查看器缩放事件的最小缩放比例 | `number` | 0.2 |
| max-scale 2.4.0 | 图像查看器缩放事件的最大缩放比例 | `number` | 7 |
| show-progress 2.9.4 | 是否在预览图片时显示进度条 | `boolean` | false |

### Image Events [​](#image-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| load | 图片加载成功触发 | `Function` |
| error | 图片加载失败触发 | `Function` |
| switch | 切换图像时触发。 | `Function` |
| close | 当点击 X 按钮或者在`hide-on-click-modal`为 true 时点击遮罩层时触发 | `Function` |
| show | 当 Viewer 显示时触发 | `Function` |

### Image Slots [​](#image-slots)

| 插槽名 | 说明 | 类型 |
| --- | --- | --- |
| placeholder | 当图像尚未加载时，自定义的占位符内容 | \- |
| error | 自定义图像加载失败的内容 | \- |
| [\[image viewer slots\](#image-viewer-slots)](#image-viewer-slots) | 当你允许大的图像预览时，可以使用图像预览的插槽。 | \- |

### Image Exposes [​](#image-exposes)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| showPreview 2.9.4 | 手动打开大图预览 | `Function` |

## Image Viewer API [​](#image-viewer-api)

### Image Viewer Attributes [​](#image-viewer-attributes)

| 事件名 | 说明 | Type | 默认值 |
| --- | --- | --- | --- |
| url-list | 用于预览的图片链接列表 | `array` | \[\] |
| z-index | 预览时遮罩层的 z-index | `number` / `string` | — |
| initial-index | 初始预览图像索引，小于 `url-list` 的长度 | `number` | 0 |
| infinite | 是否可以无限循环预览 | `boolean` | true |
| hide-on-click-modal | 是否可以通过点击遮罩层关闭预览 | `boolean` | false |
| teleported | image 自身是否插入至 body 元素上。 嵌套的父元素属性会发生修改时应该将此属性设置为 `true` | `boolean` | false |
| zoom-rate 2.2.27 | 图像查看器缩放事件的缩放速率。 | `number` | 1.2 |
| scale 2.11.3 | 预览图像缩放。 | `number` | 1 |
| min-scale 2.4.0 | 图像查看器缩放事件的最小缩放比例 | `number` | 0.2 |
| max-scale 2.4.0 | 图像查看器缩放事件的最大缩放比例 | `number` | 7 |
| close-on-press-escape | 是否可以通过按下 ESC 关闭 Image Viewer | `boolean` | true |
| show-progress 2.9.4 | 是否显示预览图片的进度条内容 | `boolean` | false |

### Image Viewer Events [​](#image-viewer-events)

| Name | 说明 | 类型 |
| --- | --- | --- |
| close | 当点击 X 按钮或者在`hide-on-click-modal`为 true 时点击遮罩层时触发 | `Function` |
| error 2.11.3 | 图片加载失败触发 | `Function` |
| switch | 切换图像时触发。 | `Function` |
| rotate 2.3.13 | 旋转图像时触发。 | `Function` |

### Image Viewer Slots [​](#image-viewer-slots)

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| viewer | 自定义内容 | \- |
| progress 2.9.4 | 自定义进度内容 (优先级高于 `show-progress` prop) | `object` |
| toolbar 2.9.4 | 自定义工具栏内容 | `object` |
| viewer-error 2.11.3 | 自定义图像加载失败的内容 | `object` |

### Image Viewer Exposes [​](#image-viewer-exposes)

| Name | Description | Type |
| --- | --- | --- |
| setActiveItem | 手动切换图片 | `Function` |

## 类型声明 [​](#类型声明)

Show declarations

ts

```
type ImageViewerAction = 'zoomIn' | 'zoomOut' | 'clockwise' | 'anticlockwise'
type ImageViewerActionOptions = {
  enableTransition?: boolean
  zoomRate?: number
  rotateDeg?: number
}
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/image) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/image.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/image.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/24540820?v=4&size=64)](https://github.com/catanswer)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/57785259?v=4&size=64)](https://github.com/w2xi)[![](https://avatars.githubusercontent.com/u/55419399?v=4&size=64)](https://github.com/declanchiu)[![](https://avatars.githubusercontent.com/u/33775809?v=4&size=64)](https://github.com/besscroft)[![](https://avatars.githubusercontent.com/u/63360587?v=4&size=64)](https://github.com/wkasunsampath)[![](https://avatars.githubusercontent.com/u/66096254?v=4&size=64)](https://github.com/IceyWu)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/27653885?v=4&size=64)](https://github.com/cicada-ah)[![](https://avatars.githubusercontent.com/u/49704630?v=4&size=64)](https://github.com/ljf1834)[![](https://avatars.githubusercontent.com/u/16984236?v=4&size=64)](https://github.com/JiatLn)[![](https://avatars.githubusercontent.com/u/26266181?v=4&size=64)](https://github.com/wydingez)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/8347286?v=4&size=64)](https://github.com/holynewbie)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/27729870?v=4&size=64)](https://github.com/zycoJamie)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)[![](https://avatars.githubusercontent.com/u/96148681?v=4&size=64)](https://github.com/cregis0073)[![](https://avatars.githubusercontent.com/u/442927?v=4&size=64)](https://github.com/EstebanFuentealba)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/27677166?v=4&size=64)](https://github.com/hickiy)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/57179957?v=4&size=64)](https://github.com/yeonjulee1005)[![](https://avatars.githubusercontent.com/u/1836701?v=4&size=64)](https://github.com/HADB)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/75007029?v=4&size=64)](https://github.com/yj-liuzepeng)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)

[Empty 空状态](https://element-plus.org/zh-CN/component/empty)

[Infinite Scroll 无限滚动](https://element-plus.org/zh-CN/component/infinite-scroll)




---
## [data/infinite-scroll] Infinite Scroll 无限滚动
> 官方文档: https://element-plus.org/zh-CN/component/infinite-scroll.html

---

废弃的 directive

我们将不再维护这个 directive。 会在 3.0.0 **被移除**，请使用 [el-scrollbar infinite scroll](https://element-plus.org/zh-CN/component/scrollbar#infinite-scroll) 作为代替。

# Infinite Scroll 无限滚动 [​](#infinite-scroll-无限滚动)

更新日志待解决

3

滚动至底部时，加载更多数据。

## 基础用法 [​](#基础用法)

在要实现滚动加载的列表上添加`v-infinite-scroll`，并赋值相应的加载方法，可实现滚动到底部时自动执行加载方法。

-   1
-   2
-   3
-   4
-   5
-   6

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8dWwgdi1pbmZpbml0ZS1zY3JvbGw9XCJsb2FkXCIgY2xhc3M9XCJpbmZpbml0ZS1saXN0XCIgc3R5bGU9XCJvdmVyZmxvdzogYXV0b1wiPlxuICAgIDxsaSB2LWZvcj1cImkgaW4gY291bnRcIiA6a2V5PVwiaVwiIGNsYXNzPVwiaW5maW5pdGUtbGlzdC1pdGVtXCI+e3sgaSB9fTwvbGk+XG4gIDwvdWw+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBjb3VudCA9IHJlZigwKVxuY29uc3QgbG9hZCA9ICgpID0+IHtcbiAgY291bnQudmFsdWUgKz0gMlxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5pbmZpbml0ZS1saXN0IHtcbiAgaGVpZ2h0OiAzMDBweDtcbiAgcGFkZGluZzogMDtcbiAgbWFyZ2luOiAwO1xuICBsaXN0LXN0eWxlOiBub25lO1xufVxuLmluZmluaXRlLWxpc3QgLmluZmluaXRlLWxpc3QtaXRlbSB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG4gIGp1c3RpZnktY29udGVudDogY2VudGVyO1xuICBoZWlnaHQ6IDUwcHg7XG4gIGJhY2tncm91bmQ6IHZhcigtLWVsLWNvbG9yLXByaW1hcnktbGlnaHQtOSk7XG4gIG1hcmdpbjogMTBweDtcbiAgY29sb3I6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xufVxuLmluZmluaXRlLWxpc3QgLmluZmluaXRlLWxpc3QtaXRlbSArIC5saXN0LWl0ZW0ge1xuICBtYXJnaW4tdG9wOiAxMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/infinite-scroll/basic.vue)_

vue

```
<template>
  <ul v-infinite-scroll="load" class="infinite-list" style="overflow: auto">
    <li v-for="i in count" :key="i" class="infinite-list-item">{{ i }}</li>
  </ul>
</template>

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

const count = ref(0)
const load = () => {
  count.value += 2
}
</script>

<style>
.infinite-list {
  height: 300px;
  padding: 0;
  margin: 0;
  list-style: none;
}
.infinite-list .infinite-list-item {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 50px;
  background: var(--el-color-primary-light-9);
  margin: 10px;
  color: var(--el-color-primary);
}
.infinite-list .infinite-list-item + .list-item {
  margin-top: 10px;
}
</style>
```

隐藏源代码

## 禁用加载 [​](#禁用加载)

-   1
-   2
-   3
-   4
-   5
-   6
-   7
-   8
-   9
-   10

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiaW5maW5pdGUtbGlzdC13cmFwcGVyXCIgc3R5bGU9XCJvdmVyZmxvdzogYXV0b1wiPlxuICAgIDx1bFxuICAgICAgdi1pbmZpbml0ZS1zY3JvbGw9XCJsb2FkXCJcbiAgICAgIGNsYXNzPVwibGlzdFwiXG4gICAgICA6aW5maW5pdGUtc2Nyb2xsLWRpc2FibGVkPVwiZGlzYWJsZWRcIlxuICAgID5cbiAgICAgIDxsaSB2LWZvcj1cImkgaW4gY291bnRcIiA6a2V5PVwiaVwiIGNsYXNzPVwibGlzdC1pdGVtXCI+e3sgaSB9fTwvbGk+XG4gICAgPC91bD5cbiAgICA8cCB2LWlmPVwibG9hZGluZ1wiPkxvYWRpbmcuLi48L3A+XG4gICAgPHAgdi1pZj1cIm5vTW9yZVwiPk5vIG1vcmU8L3A+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IGNvbXB1dGVkLCByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGNvdW50ID0gcmVmKDEwKVxuY29uc3QgbG9hZGluZyA9IHJlZihmYWxzZSlcbmNvbnN0IG5vTW9yZSA9IGNvbXB1dGVkKCgpID0+IGNvdW50LnZhbHVlID49IDIwKVxuY29uc3QgZGlzYWJsZWQgPSBjb21wdXRlZCgoKSA9PiBsb2FkaW5nLnZhbHVlIHx8IG5vTW9yZS52YWx1ZSlcbmNvbnN0IGxvYWQgPSAoKSA9PiB7XG4gIGxvYWRpbmcudmFsdWUgPSB0cnVlXG4gIHNldFRpbWVvdXQoKCkgPT4ge1xuICAgIGNvdW50LnZhbHVlICs9IDJcbiAgICBsb2FkaW5nLnZhbHVlID0gZmFsc2VcbiAgfSwgMjAwMClcbn1cbjwvc2NyaXB0PlxuXG48c3R5bGU+XG4uaW5maW5pdGUtbGlzdC13cmFwcGVyIHtcbiAgaGVpZ2h0OiAzMDBweDtcbiAgdGV4dC1hbGlnbjogY2VudGVyO1xufVxuLmluZmluaXRlLWxpc3Qtd3JhcHBlciAubGlzdCB7XG4gIHBhZGRpbmc6IDA7XG4gIG1hcmdpbjogMDtcbiAgbGlzdC1zdHlsZTogbm9uZTtcbn1cblxuLmluZmluaXRlLWxpc3Qtd3JhcHBlciAubGlzdC1pdGVtIHtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbiAganVzdGlmeS1jb250ZW50OiBjZW50ZXI7XG4gIGhlaWdodDogNTBweDtcbiAgYmFja2dyb3VuZDogdmFyKC0tZWwtY29sb3ItZGFuZ2VyLWxpZ2h0LTkpO1xuICBjb2xvcjogdmFyKC0tZWwtY29sb3ItZGFuZ2VyKTtcbn1cbi5pbmZpbml0ZS1saXN0LXdyYXBwZXIgLmxpc3QtaXRlbSArIC5saXN0LWl0ZW0ge1xuICBtYXJnaW4tdG9wOiAxMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/infinite-scroll/disable-loading.vue)_

vue

```
<template>
  <div class="infinite-list-wrapper" style="overflow: auto">
    <ul
      v-infinite-scroll="load"
      class="list"
      :infinite-scroll-disabled="disabled"
    >
      <li v-for="i in count" :key="i" class="list-item">{{ i }}</li>
    </ul>
    <p v-if="loading">Loading...</p>
    <p v-if="noMore">No more</p>
  </div>
</template>

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

const count = ref(10)
const loading = ref(false)
const noMore = computed(() => count.value >= 20)
const disabled = computed(() => loading.value || noMore.value)
const load = () => {
  loading.value = true
  setTimeout(() => {
    count.value += 2
    loading.value = false
  }, 2000)
}
</script>

<style>
.infinite-list-wrapper {
  height: 300px;
  text-align: center;
}
.infinite-list-wrapper .list {
  padding: 0;
  margin: 0;
  list-style: none;
}

.infinite-list-wrapper .list-item {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 50px;
  background: var(--el-color-danger-light-9);
  color: var(--el-color-danger);
}
.infinite-list-wrapper .list-item + .list-item {
  margin-top: 10px;
}
</style>
```

隐藏源代码

## 指令 [​](#指令)

| 属性 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| v-infinite-scroll | 滚动到底部时，加载更多数据 | `Function` | — |
| infinite-scroll-disabled | 是否禁用 | `boolean` | false |
| infinite-scroll-delay | 节流时延，单位为ms | `number` | 200 |
| infinite-scroll-distance | 触发加载的距离阈值，单位为px | `number` | 0 |
| infinite-scroll-immediate | 是否立即执行加载方法，以防初始状态下内容无法撑满容器。 | `boolean` | true |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/infinite-scroll) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/infinite-scroll.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/infinite-scroll.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/132551120?v=4&size=64)](https://github.com/YiMo1)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/48023419?v=4&size=64)](https://github.com/uncledrewzhaopeng)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)

[Image 图片](https://element-plus.org/zh-CN/component/image)

[Pagination 分页](https://element-plus.org/zh-CN/component/pagination)




---
## [data/pagination] Pagination 分页
> 官方文档: https://element-plus.org/zh-CN/component/pagination.html

---

# Pagination 分页 [​](#pagination-分页)

更新日志待解决

9

当数据量过多时，使用分页分解数据。

## 基础用法 [​](#基础用法)

设置`layout`，表示需要显示的内容，用逗号分隔，布局元素会依次显示。 分页元素包括：`prev`（跳转到上一页的按钮）、`next`（跳转到下一页的按钮）、`pager`（页码列表）、`jumper`（跳转输入框）、`total`（总条目数）、`sizes`（用于设置每页条数的选择器）以及 `->`（该符号之后的所有元素将被靠右对齐）。

When you have few pages

-   1
-   2
-   3
-   4
-   5

When you have more than 7 pages

-   1
-   2
-   3
-   4
-   5
-   6

-   100

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZXhhbXBsZS1wYWdpbmF0aW9uLWJsb2NrXCI+XG4gICAgPGRpdiBjbGFzcz1cImV4YW1wbGUtZGVtb25zdHJhdGlvblwiPldoZW4geW91IGhhdmUgZmV3IHBhZ2VzPC9kaXY+XG4gICAgPGVsLXBhZ2luYXRpb24gbGF5b3V0PVwicHJldiwgcGFnZXIsIG5leHRcIiA6dG90YWw9XCI1MFwiIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwiZXhhbXBsZS1wYWdpbmF0aW9uLWJsb2NrXCI+XG4gICAgPGRpdiBjbGFzcz1cImV4YW1wbGUtZGVtb25zdHJhdGlvblwiPldoZW4geW91IGhhdmUgbW9yZSB0aGFuIDcgcGFnZXM8L2Rpdj5cbiAgICA8ZWwtcGFnaW5hdGlvbiBsYXlvdXQ9XCJwcmV2LCBwYWdlciwgbmV4dFwiIDp0b3RhbD1cIjEwMDBcIiAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZXhhbXBsZS1wYWdpbmF0aW9uLWJsb2NrICsgLmV4YW1wbGUtcGFnaW5hdGlvbi1ibG9jayB7XG4gIG1hcmdpbi10b3A6IDEwcHg7XG59XG4uZXhhbXBsZS1wYWdpbmF0aW9uLWJsb2NrIC5leGFtcGxlLWRlbW9uc3RyYXRpb24ge1xuICBtYXJnaW4tYm90dG9tOiAxNnB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/pagination/basic-usage.vue)_

vue

```
<template>
  <div class="example-pagination-block">
    <div class="example-demonstration">When you have few pages</div>
    <el-pagination layout="prev, pager, next" :total="50" />
  </div>
  <div class="example-pagination-block">
    <div class="example-demonstration">When you have more than 7 pages</div>
    <el-pagination layout="prev, pager, next" :total="1000" />
  </div>
</template>

<style scoped>
.example-pagination-block + .example-pagination-block {
  margin-top: 10px;
}
.example-pagination-block .example-demonstration {
  margin-bottom: 16px;
}
</style>
```

隐藏源代码

## 设置最大页码按钮数 [​](#设置最大页码按钮数)

默认情况下，当总页数超过 7 页时，Pagination 会折叠多余的页码按钮。 通过 `pager-count` 属性可以设置最大页码按钮数。

-   1
-   2
-   3
-   4
-   5
-   6
-   7
-   8
-   9
-   10

-   50

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcGFnaW5hdGlvblxuICAgIDpwYWdlLXNpemU9XCIyMFwiXG4gICAgOnBhZ2VyLWNvdW50PVwiMTFcIlxuICAgIGxheW91dD1cInByZXYsIHBhZ2VyLCBuZXh0XCJcbiAgICA6dG90YWw9XCIxMDAwXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/pagination/number-of-pagers.vue)_

vue

```
<template>
  <el-pagination
    :page-size="20"
    :pager-count="11"
    layout="prev, pager, next"
    :total="1000"
  />
</template>
```

隐藏源代码

## 带有背景色的分页 [​](#带有背景色的分页)

设置`background`属性可以为分页按钮添加背景色。

-   1
-   2
-   3
-   4
-   5
-   6

-   100

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcGFnaW5hdGlvbiBiYWNrZ3JvdW5kIGxheW91dD1cInByZXYsIHBhZ2VyLCBuZXh0XCIgOnRvdGFsPVwiMTAwMFwiIC8+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/pagination/background-color.vue)_

vue

```
<template>
  <el-pagination background layout="prev, pager, next" :total="1000" />
</template>
```

隐藏源代码

## 小型分页 [​](#小型分页)

在空间有限的情况下，可以使用简单的小型分页。

通过`size`更改大小 这是个 `small`的例子

-   1
-   2
-   3
-   4
-   5

-   1
-   2
-   3
-   4
-   5

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcGFnaW5hdGlvbiBzaXplPVwic21hbGxcIiBsYXlvdXQ9XCJwcmV2LCBwYWdlciwgbmV4dFwiIDp0b3RhbD1cIjUwXCIgLz5cbiAgPGVsLXBhZ2luYXRpb25cbiAgICBzaXplPVwic21hbGxcIlxuICAgIGJhY2tncm91bmRcbiAgICBsYXlvdXQ9XCJwcmV2LCBwYWdlciwgbmV4dFwiXG4gICAgOnRvdGFsPVwiNTBcIlxuICAgIGNsYXNzPVwibXQtNFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/pagination/small-pagination.vue)_

vue

```
<template>
  <el-pagination size="small" layout="prev, pager, next" :total="50" />
  <el-pagination
    size="small"
    background
    layout="prev, pager, next"
    :total="50"
    class="mt-4"
  />
</template>
```

隐藏源代码

## 当只有一页时隐藏分页 [​](#当只有一页时隐藏分页)

当只有一页时，通过设置 `hide-on-single-page` 属性来隐藏分页。

* * *

-   1

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1zd2l0Y2ggdi1tb2RlbD1cInZhbHVlXCIgLz5cbiAgICA8aHIgY2xhc3M9XCJteS00XCIgLz5cbiAgICA8ZWwtcGFnaW5hdGlvblxuICAgICAgOmhpZGUtb24tc2luZ2xlLXBhZ2U9XCJ2YWx1ZVwiXG4gICAgICA6dG90YWw9XCI1XCJcbiAgICAgIGxheW91dD1cInByZXYsIHBhZ2VyLCBuZXh0XCJcbiAgICAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKGZhbHNlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/pagination/auto-hide-pagination.vue)_

vue

```
<template>
  <div>
    <el-switch v-model="value" />
    <hr class="my-4" />
    <el-pagination
      :hide-on-single-page="value"
      :total="5"
      layout="prev, pager, next"
    />
  </div>
</template>

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

const value = ref(false)
</script>
```

隐藏源代码

## 附加功能 [​](#附加功能)

根据场景需要，可以添加其他功能模块。

此示例是一个完整的用例。 使用了 `size-change` 和 `current-change` 事件来处理页码大小和当前页变动时候触发的事件。 `page-sizes`接受一个整数类型的数组，数组元素为展示的选择每页显示个数的选项，`[100, 200, 300, 400]` 表示四个选项，每页显示 100 个，200 个，300 个或者 400 个。

defaultlargesmall

background:

disabled:

* * *

Total item count

Total 1000

-   1

-   3
-   4
-   5
-   6
-   7

-   10

Change page size

100/page

-   1

-   3
-   4
-   5
-   6
-   7

-   10

Jump to

-   1

-   3
-   4
-   5
-   6
-   7

-   10

Go to

All combined

Total 400

100/page

-   1
-   2
-   3
-   4

Go to

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBpdGVtcy1jZW50ZXIgbWItNFwiPlxuICAgIDxlbC1yYWRpby1ncm91cCB2LW1vZGVsPVwic2l6ZVwiIGNsYXNzPVwibXItNFwiPlxuICAgICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cImRlZmF1bHRcIj5kZWZhdWx0PC9lbC1yYWRpby1idXR0b24+XG4gICAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwibGFyZ2VcIj5sYXJnZTwvZWwtcmFkaW8tYnV0dG9uPlxuXG4gICAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwic21hbGxcIj5zbWFsbDwvZWwtcmFkaW8tYnV0dG9uPlxuICAgIDwvZWwtcmFkaW8tZ3JvdXA+XG4gICAgPGRpdj5cbiAgICAgIGJhY2tncm91bmQ6XG4gICAgICA8ZWwtc3dpdGNoIHYtbW9kZWw9XCJiYWNrZ3JvdW5kXCIgY2xhc3M9XCJtbC0yXCIgLz5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwibWwtNFwiPlxuICAgICAgZGlzYWJsZWQ6IDxlbC1zd2l0Y2ggdi1tb2RlbD1cImRpc2FibGVkXCIgY2xhc3M9XCJtbC0yXCIgLz5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG5cbiAgPGhyIGNsYXNzPVwibXktNFwiIC8+XG5cbiAgPGRpdiBjbGFzcz1cImRlbW8tcGFnaW5hdGlvbi1ibG9ja1wiPlxuICAgIDxkaXYgY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+VG90YWwgaXRlbSBjb3VudDwvZGl2PlxuICAgIDxlbC1wYWdpbmF0aW9uXG4gICAgICB2LW1vZGVsOmN1cnJlbnQtcGFnZT1cImN1cnJlbnRQYWdlMVwiXG4gICAgICA6cGFnZS1zaXplPVwiMTAwXCJcbiAgICAgIDpzaXplPVwic2l6ZVwiXG4gICAgICA6ZGlzYWJsZWQ9XCJkaXNhYmxlZFwiXG4gICAgICA6YmFja2dyb3VuZD1cImJhY2tncm91bmRcIlxuICAgICAgbGF5b3V0PVwidG90YWwsIHByZXYsIHBhZ2VyLCBuZXh0XCJcbiAgICAgIDp0b3RhbD1cIjEwMDBcIlxuICAgICAgQHNpemUtY2hhbmdlPVwiaGFuZGxlU2l6ZUNoYW5nZVwiXG4gICAgICBAY3VycmVudC1jaGFuZ2U9XCJoYW5kbGVDdXJyZW50Q2hhbmdlXCJcbiAgICAvPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cImRlbW8tcGFnaW5hdGlvbi1ibG9ja1wiPlxuICAgIDxkaXYgY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+Q2hhbmdlIHBhZ2Ugc2l6ZTwvZGl2PlxuICAgIDxlbC1wYWdpbmF0aW9uXG4gICAgICB2LW1vZGVsOmN1cnJlbnQtcGFnZT1cImN1cnJlbnRQYWdlMlwiXG4gICAgICB2LW1vZGVsOnBhZ2Utc2l6ZT1cInBhZ2VTaXplMlwiXG4gICAgICA6cGFnZS1zaXplcz1cIlsxMDAsIDIwMCwgMzAwLCA0MDBdXCJcbiAgICAgIDpzaXplPVwic2l6ZVwiXG4gICAgICA6ZGlzYWJsZWQ9XCJkaXNhYmxlZFwiXG4gICAgICA6YmFja2dyb3VuZD1cImJhY2tncm91bmRcIlxuICAgICAgbGF5b3V0PVwic2l6ZXMsIHByZXYsIHBhZ2VyLCBuZXh0XCJcbiAgICAgIDp0b3RhbD1cIjEwMDBcIlxuICAgICAgQHNpemUtY2hhbmdlPVwiaGFuZGxlU2l6ZUNoYW5nZVwiXG4gICAgICBAY3VycmVudC1jaGFuZ2U9XCJoYW5kbGVDdXJyZW50Q2hhbmdlXCJcbiAgICAvPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cImRlbW8tcGFnaW5hdGlvbi1ibG9ja1wiPlxuICAgIDxkaXYgY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+SnVtcCB0bzwvZGl2PlxuICAgIDxlbC1wYWdpbmF0aW9uXG4gICAgICB2LW1vZGVsOmN1cnJlbnQtcGFnZT1cImN1cnJlbnRQYWdlM1wiXG4gICAgICB2LW1vZGVsOnBhZ2Utc2l6ZT1cInBhZ2VTaXplM1wiXG4gICAgICA6c2l6ZT1cInNpemVcIlxuICAgICAgOmRpc2FibGVkPVwiZGlzYWJsZWRcIlxuICAgICAgOmJhY2tncm91bmQ9XCJiYWNrZ3JvdW5kXCJcbiAgICAgIGxheW91dD1cInByZXYsIHBhZ2VyLCBuZXh0LCBqdW1wZXJcIlxuICAgICAgOnRvdGFsPVwiMTAwMFwiXG4gICAgICBAc2l6ZS1jaGFuZ2U9XCJoYW5kbGVTaXplQ2hhbmdlXCJcbiAgICAgIEBjdXJyZW50LWNoYW5nZT1cImhhbmRsZUN1cnJlbnRDaGFuZ2VcIlxuICAgIC8+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwiZGVtby1wYWdpbmF0aW9uLWJsb2NrXCI+XG4gICAgPGRpdiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5BbGwgY29tYmluZWQ8L2Rpdj5cbiAgICA8ZWwtcGFnaW5hdGlvblxuICAgICAgdi1tb2RlbDpjdXJyZW50LXBhZ2U9XCJjdXJyZW50UGFnZTRcIlxuICAgICAgdi1tb2RlbDpwYWdlLXNpemU9XCJwYWdlU2l6ZTRcIlxuICAgICAgOnBhZ2Utc2l6ZXM9XCJbMTAwLCAyMDAsIDMwMCwgNDAwXVwiXG4gICAgICA6c2l6ZT1cInNpemVcIlxuICAgICAgOmRpc2FibGVkPVwiZGlzYWJsZWRcIlxuICAgICAgOmJhY2tncm91bmQ9XCJiYWNrZ3JvdW5kXCJcbiAgICAgIGxheW91dD1cInRvdGFsLCBzaXplcywgcHJldiwgcGFnZXIsIG5leHQsIGp1bXBlclwiXG4gICAgICA6dG90YWw9XCI0MDBcIlxuICAgICAgQHNpemUtY2hhbmdlPVwiaGFuZGxlU2l6ZUNoYW5nZVwiXG4gICAgICBAY3VycmVudC1jaGFuZ2U9XCJoYW5kbGVDdXJyZW50Q2hhbmdlXCJcbiAgICAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgQ29tcG9uZW50U2l6ZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgY3VycmVudFBhZ2UxID0gcmVmKDUpXG5jb25zdCBjdXJyZW50UGFnZTIgPSByZWYoNSlcbmNvbnN0IGN1cnJlbnRQYWdlMyA9IHJlZig1KVxuY29uc3QgY3VycmVudFBhZ2U0ID0gcmVmKDQpXG5jb25zdCBwYWdlU2l6ZTIgPSByZWYoMTAwKVxuY29uc3QgcGFnZVNpemUzID0gcmVmKDEwMClcbmNvbnN0IHBhZ2VTaXplNCA9IHJlZigxMDApXG5jb25zdCBzaXplID0gcmVmPENvbXBvbmVudFNpemU+KCdkZWZhdWx0JylcbmNvbnN0IGJhY2tncm91bmQgPSByZWYoZmFsc2UpXG5jb25zdCBkaXNhYmxlZCA9IHJlZihmYWxzZSlcblxuY29uc3QgaGFuZGxlU2l6ZUNoYW5nZSA9ICh2YWw6IG51bWJlcikgPT4ge1xuICBjb25zb2xlLmxvZyhgJHt2YWx9IGl0ZW1zIHBlciBwYWdlYClcbn1cbmNvbnN0IGhhbmRsZUN1cnJlbnRDaGFuZ2UgPSAodmFsOiBudW1iZXIpID0+IHtcbiAgY29uc29sZS5sb2coYGN1cnJlbnQgcGFnZTogJHt2YWx9YClcbn1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tcGFnaW5hdGlvbi1ibG9jayArIC5kZW1vLXBhZ2luYXRpb24tYmxvY2sge1xuICBtYXJnaW4tdG9wOiAxMHB4O1xufVxuLmRlbW8tcGFnaW5hdGlvbi1ibG9jayAuZGVtb25zdHJhdGlvbiB7XG4gIG1hcmdpbi1ib3R0b206IDE2cHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/pagination/more-elements.vue)_

vue

```
<template>
  <div class="flex items-center mb-4">
    <el-radio-group v-model="size" class="mr-4">
      <el-radio-button value="default">default</el-radio-button>
      <el-radio-button value="large">large</el-radio-button>

      <el-radio-button value="small">small</el-radio-button>
    </el-radio-group>
    <div>
      background:
      <el-switch v-model="background" class="ml-2" />
    </div>
    <div class="ml-4">
      disabled: <el-switch v-model="disabled" class="ml-2" />
    </div>
  </div>

  <hr class="my-4" />

  <div class="demo-pagination-block">
    <div class="demonstration">Total item count</div>
    <el-pagination
      v-model:current-page="currentPage1"
      :page-size="100"
      :size="size"
      :disabled="disabled"
      :background="background"
      layout="total, prev, pager, next"
      :total="1000"
      @size-change="handleSizeChange"
      @current-change="handleCurrentChange"
    />
  </div>
  <div class="demo-pagination-block">
    <div class="demonstration">Change page size</div>
    <el-pagination
      v-model:current-page="currentPage2"
      v-model:page-size="pageSize2"
      :page-sizes="[100, 200, 300, 400]"
      :size="size"
      :disabled="disabled"
      :background="background"
      layout="sizes, prev, pager, next"
      :total="1000"
      @size-change="handleSizeChange"
      @current-change="handleCurrentChange"
    />
  </div>
  <div class="demo-pagination-block">
    <div class="demonstration">Jump to</div>
    <el-pagination
      v-model:current-page="currentPage3"
      v-model:page-size="pageSize3"
      :size="size"
      :disabled="disabled"
      :background="background"
      layout="prev, pager, next, jumper"
      :total="1000"
      @size-change="handleSizeChange"
      @current-change="handleCurrentChange"
    />
  </div>
  <div class="demo-pagination-block">
    <div class="demonstration">All combined</div>
    <el-pagination
      v-model:current-page="currentPage4"
      v-model:page-size="pageSize4"
      :page-sizes="[100, 200, 300, 400]"
      :size="size"
      :disabled="disabled"
      :background="background"
      layout="total, sizes, prev, pager, next, jumper"
      :total="400"
      @size-change="handleSizeChange"
      @current-change="handleCurrentChange"
    />
  </div>
</template>

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

import type { ComponentSize } from 'element-plus'

const currentPage1 = ref(5)
const currentPage2 = ref(5)
const currentPage3 = ref(5)
const currentPage4 = ref(4)
const pageSize2 = ref(100)
const pageSize3 = ref(100)
const pageSize4 = ref(100)
const size = ref<ComponentSize>('default')
const background = ref(false)
const disabled = ref(false)

const handleSizeChange = (val: number) => {
  console.log(`${val} items per page`)
}
const handleCurrentChange = (val: number) => {
  console.log(`current page: ${val}`)
}
</script>

<style scoped>
.demo-pagination-block + .demo-pagination-block {
  margin-top: 10px;
}
.demo-pagination-block .demonstration {
  margin-bottom: 16px;
}
</style>
```

隐藏源代码

## API [​](#api)

### 属性 [​](#属性)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| size 2.7.6 | 分页大小 | `enum` | 'default' |
| background | 是否为分页按钮添加背景色 | `boolean` | false |
| page-size / v-model:page-size | 每页显示条目个数 | `number` | — |
| default-page-size | 每页默认的条目个数，不设置时默认为10 | `number` | — |
| total | 总条目数 | `number` | — |
| page-count | 总页数， `total` 和 `page-count` 设置任意一个就可以达到显示页码的功能；如果要支持 `page-sizes` 的更改，则需要使用 `total` 属性 | `number` | — |
| pager-count | 设置最大页码按钮数。 页码按钮的数量，当总页数超过该值时会折叠 | `number` | 7 |
| current-page / v-model:current-page | 当前页数 | `number` | — |
| default-current-page | 当前页数的默认初始值，不设置时默认为 1 | `number` | — |
| layout | 组件布局，子组件名用逗号分隔 | `string` | prev, pager, next, jumper, ->, total |
| page-sizes | 每页显示个数选择器的选项设置 | `array` | \[10, 20, 30, 40, 50, 100\] |
| append-size-to 2.8.4 | 下拉框挂载到哪个 DOM 元素 | `string` | — |
| popper-class | 每页显示个数选择器的下拉框类名 | `string` | '' |
| popper-style 2.11.5 | 每页显示个数选择器的下拉框样式 | `string` / `object` | aaa |
| prev-text | 替代图标显示的上一页文字 | `string` | '' |
| prev-icon | 上一页的图标， 比 `prev-text` 优先级更高 | `string` / `Component` | ArrowLeft |
| next-text | 替代图标显示的下一页文字 | `string` | '' |
| next-icon | 下一页的图标， 比 `next-text` 优先级更低 | `string` / `Component` | ArrowRight |
| disabled | 是否禁用分页 | `boolean` | false |
| teleported 2.3.13 | 是否将下拉菜单teleport至 body | `boolean` | true |
| hide-on-single-page | 只有一页时是否隐藏 | `boolean` | false |
| small deprecated | 是否使用小型分页样式 | `boolean` | false |

WARNING

我们现在会检查一些不合理的用法，如果发现分页器未显示，可以核对是否违反以下情形：

-   `total` 和 `page-count` 必须传一个，不然组件无法判断总页数；优先使用 `page-count`;
-   如果传入了 `current-page`，必须监听 `current-page` 变更的事件（`@update:current-page`），否则分页切换不起作用；
-   如果传入了 `page-size`，且布局包含 page-size 选择器（即 `layout` 包含 `sizes`），必须监听 `page-size` 变更的事件（`@update:page-size`），否则分页大小的变化将不起作用。

### 事件 [​](#事件)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| size-change | `page-size` 改变时触发 | `Function` |
| current-change | `current-page` 改变时触发 | `Function` |
| change 2.4.4 | `current-page` 或 `page-size` 更改时触发 | `Function` |
| prev-click | 用户点击上一页按钮改变当前页时触发 | `Function` |
| next-click | 用户点击下一页按钮改变当前页时触发 | `Function` |

WARNING

以上事件不推荐使用（但由于兼容的原因仍然支持，在以后的版本中将会被删除）；如果要监听 current-page 和 page-size 的改变，使用 `v-model` 双向绑定是个更好的选择。

### 插槽 [​](#插槽)

| 名称 | 说明 |
| --- | --- |
| default | 自定义内容 设置文案，需要在 `layout` 中列出 `slot` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/pagination) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/pagination.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/pagination.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/5559812?v=4&size=64)](https://github.com/metanas)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/30883395?v=4&size=64)](https://github.com/webvs2)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/3898898?v=4&size=64)](https://github.com/ioslh)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/35400818?v=4&size=64)](https://github.com/ToyCat93)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/108655466?v=4&size=64)](https://github.com/Karolis-Stoncius)[![](https://avatars.githubusercontent.com/u/43257608?v=4&size=64)](https://github.com/Liao-js)[![](https://avatars.githubusercontent.com/u/24290011?v=4&size=64)](https://github.com/xingyixiang)[![](https://avatars.githubusercontent.com/u/37095891?v=4&size=64)](https://github.com/boomboy4)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/20925158?v=4&size=64)](https://github.com/fzq1998)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/134276765?v=4&size=64)](https://github.com/zwgwf)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/10475770?v=4&size=64)](https://github.com/DarkHighness)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/20411966?v=4&size=64)](https://github.com/SorrowX)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/26358323?v=4&size=64)](https://github.com/wangyuhuiever)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/145281501?v=4&size=64)](https://github.com/typed-sigterm)[![](https://avatars.githubusercontent.com/u/105651386?v=4&size=64)](https://github.com/heappynd)[![](https://avatars.githubusercontent.com/u/35426360?v=4&size=64)](https://github.com/Jungzl)

[Infinite Scroll 无限滚动](https://element-plus.org/zh-CN/component/infinite-scroll)

[Progress 进度条](https://element-plus.org/zh-CN/component/progress)




---
## [data/progress] Progress 进度条
> 官方文档: https://element-plus.org/zh-CN/component/progress.html

---

# Progress 进度条 [​](#progress-进度条)

更新日志待解决

1

用于展示操作进度，告知用户当前状态和预期。

## 直线进度条 [​](#直线进度条)

Progress 组件设置 `percentage` 属性即可，表示进度条对应的百分比。 该属性**必填**，并且必须在 `0-100` 的范围内。 你可以通过设置 `format` 来自定义文字显示的格式。

50%

Full

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1wcm9ncmVzc1wiPlxuICAgIDxlbC1wcm9ncmVzcyA6cGVyY2VudGFnZT1cIjUwXCIgLz5cbiAgICA8ZWwtcHJvZ3Jlc3MgOnBlcmNlbnRhZ2U9XCIxMDBcIiA6Zm9ybWF0PVwiZm9ybWF0XCIgLz5cbiAgICA8ZWwtcHJvZ3Jlc3MgOnBlcmNlbnRhZ2U9XCIxMDBcIiBzdGF0dXM9XCJzdWNjZXNzXCIgLz5cbiAgICA8ZWwtcHJvZ3Jlc3MgOnBlcmNlbnRhZ2U9XCIxMDBcIiBzdGF0dXM9XCJ3YXJuaW5nXCIgLz5cbiAgICA8ZWwtcHJvZ3Jlc3MgOnBlcmNlbnRhZ2U9XCI1MFwiIHN0YXR1cz1cImV4Y2VwdGlvblwiIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IGZvcm1hdCA9IChwZXJjZW50YWdlKSA9PiAocGVyY2VudGFnZSA9PT0gMTAwID8gJ0Z1bGwnIDogYCR7cGVyY2VudGFnZX0lYClcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tcHJvZ3Jlc3MgLmVsLXByb2dyZXNzLS1saW5lIHtcbiAgbWFyZ2luLWJvdHRvbTogMTVweDtcbiAgbWF4LXdpZHRoOiA2MDBweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/progress/linear-progress-bar.vue)_

vue

```
<template>
  <div class="demo-progress">
    <el-progress :percentage="50" />
    <el-progress :percentage="100" :format="format" />
    <el-progress :percentage="100" status="success" />
    <el-progress :percentage="100" status="warning" />
    <el-progress :percentage="50" status="exception" />
  </div>
</template>

<script lang="ts" setup>
const format = (percentage) => (percentage === 100 ? 'Full' : `${percentage}%`)
</script>

<style scoped>
.demo-progress .el-progress--line {
  margin-bottom: 15px;
  max-width: 600px;
}
</style>
```

隐藏源代码

## 进度条内显示百分比标识 [​](#进度条内显示百分比标识)

百分比不占用额外空间，适用于文件上传等场景。

Progress 组件可通过 `stroke-width` 属性更改进度条的高度，并可通过 `text-inside` 属性来改变进度条内部的文字。

70%

100%

80%

50%

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1wcm9ncmVzc1wiPlxuICAgIDxlbC1wcm9ncmVzcyA6dGV4dC1pbnNpZGU9XCJ0cnVlXCIgOnN0cm9rZS13aWR0aD1cIjI2XCIgOnBlcmNlbnRhZ2U9XCI3MFwiIC8+XG4gICAgPGVsLXByb2dyZXNzXG4gICAgICA6dGV4dC1pbnNpZGU9XCJ0cnVlXCJcbiAgICAgIDpzdHJva2Utd2lkdGg9XCIyNFwiXG4gICAgICA6cGVyY2VudGFnZT1cIjEwMFwiXG4gICAgICBzdGF0dXM9XCJzdWNjZXNzXCJcbiAgICAvPlxuICAgIDxlbC1wcm9ncmVzc1xuICAgICAgOnRleHQtaW5zaWRlPVwidHJ1ZVwiXG4gICAgICA6c3Ryb2tlLXdpZHRoPVwiMjJcIlxuICAgICAgOnBlcmNlbnRhZ2U9XCI4MFwiXG4gICAgICBzdGF0dXM9XCJ3YXJuaW5nXCJcbiAgICAvPlxuICAgIDxlbC1wcm9ncmVzc1xuICAgICAgOnRleHQtaW5zaWRlPVwidHJ1ZVwiXG4gICAgICA6c3Ryb2tlLXdpZHRoPVwiMjBcIlxuICAgICAgOnBlcmNlbnRhZ2U9XCI1MFwiXG4gICAgICBzdGF0dXM9XCJleGNlcHRpb25cIlxuICAgIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLXByb2dyZXNzIC5lbC1wcm9ncmVzcy0tbGluZSB7XG4gIG1hcmdpbi1ib3R0b206IDE1cHg7XG4gIG1heC13aWR0aDogNjAwcHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/progress/internal-percentage.vue)_

vue

```
<template>
  <div class="demo-progress">
    <el-progress :text-inside="true" :stroke-width="26" :percentage="70" />
    <el-progress
      :text-inside="true"
      :stroke-width="24"
      :percentage="100"
      status="success"
    />
    <el-progress
      :text-inside="true"
      :stroke-width="22"
      :percentage="80"
      status="warning"
    />
    <el-progress
      :text-inside="true"
      :stroke-width="20"
      :percentage="50"
      status="exception"
    />
  </div>
</template>

<style scoped>
.demo-progress .el-progress--line {
  margin-bottom: 15px;
  max-width: 600px;
}
</style>
```

隐藏源代码

## 自定义进度条的颜色 [​](#自定义进度条的颜色)

可以通过 `color` 属性来设置进度条的颜色。 该属性可以接受十六进制颜色值，函数和数组。

20%

20%

20%

20%

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1wcm9ncmVzc1wiPlxuICAgIDxlbC1wcm9ncmVzcyA6cGVyY2VudGFnZT1cInBlcmNlbnRhZ2VcIiA6Y29sb3I9XCJjdXN0b21Db2xvclwiIC8+XG5cbiAgICA8ZWwtcHJvZ3Jlc3MgOnBlcmNlbnRhZ2U9XCJwZXJjZW50YWdlXCIgOmNvbG9yPVwiY3VzdG9tQ29sb3JNZXRob2RcIiAvPlxuXG4gICAgPGVsLXByb2dyZXNzIDpwZXJjZW50YWdlPVwicGVyY2VudGFnZVwiIDpjb2xvcj1cImN1c3RvbUNvbG9yc1wiIC8+XG4gICAgPGVsLXByb2dyZXNzIDpwZXJjZW50YWdlPVwicGVyY2VudGFnZVwiIDpjb2xvcj1cImN1c3RvbUNvbG9yc1wiIC8+XG4gICAgPGRpdj5cbiAgICAgIDxlbC1idXR0b24tZ3JvdXA+XG4gICAgICAgIDxlbC1idXR0b24gOmljb249XCJNaW51c1wiIEBjbGljaz1cImRlY3JlYXNlXCIgLz5cbiAgICAgICAgPGVsLWJ1dHRvbiA6aWNvbj1cIlBsdXNcIiBAY2xpY2s9XCJpbmNyZWFzZVwiIC8+XG4gICAgICA8L2VsLWJ1dHRvbi1ncm91cD5cbiAgICA8L2Rpdj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgTWludXMsIFBsdXMgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgcGVyY2VudGFnZSA9IHJlZigyMClcbmNvbnN0IGN1c3RvbUNvbG9yID0gcmVmKCcjNDA5ZWZmJylcblxuY29uc3QgY3VzdG9tQ29sb3JzID0gW1xuICB7IGNvbG9yOiAnI2Y1NmM2YycsIHBlcmNlbnRhZ2U6IDIwIH0sXG4gIHsgY29sb3I6ICcjZTZhMjNjJywgcGVyY2VudGFnZTogNDAgfSxcbiAgeyBjb2xvcjogJyM1Y2I4N2EnLCBwZXJjZW50YWdlOiA2MCB9LFxuICB7IGNvbG9yOiAnIzE5ODlmYScsIHBlcmNlbnRhZ2U6IDgwIH0sXG4gIHsgY29sb3I6ICcjNmY3YWQzJywgcGVyY2VudGFnZTogMTAwIH0sXG5dXG5cbmNvbnN0IGN1c3RvbUNvbG9yTWV0aG9kID0gKHBlcmNlbnRhZ2U6IG51bWJlcikgPT4ge1xuICBpZiAocGVyY2VudGFnZSA8IDMwKSB7XG4gICAgcmV0dXJuICcjOTA5Mzk5J1xuICB9XG4gIGlmIChwZXJjZW50YWdlIDwgNzApIHtcbiAgICByZXR1cm4gJyNlNmEyM2MnXG4gIH1cbiAgcmV0dXJuICcjNjdjMjNhJ1xufVxuY29uc3QgaW5jcmVhc2UgPSAoKSA9PiB7XG4gIHBlcmNlbnRhZ2UudmFsdWUgKz0gMTBcbiAgaWYgKHBlcmNlbnRhZ2UudmFsdWUgPiAxMDApIHtcbiAgICBwZXJjZW50YWdlLnZhbHVlID0gMTAwXG4gIH1cbn1cbmNvbnN0IGRlY3JlYXNlID0gKCkgPT4ge1xuICBwZXJjZW50YWdlLnZhbHVlIC09IDEwXG4gIGlmIChwZXJjZW50YWdlLnZhbHVlIDwgMCkge1xuICAgIHBlcmNlbnRhZ2UudmFsdWUgPSAwXG4gIH1cbn1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmRlbW8tcHJvZ3Jlc3MgLmVsLXByb2dyZXNzLS1saW5lIHtcbiAgbWFyZ2luLWJvdHRvbTogMTVweDtcbiAgbWF4LXdpZHRoOiA2MDBweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/progress/custom-color.vue)_

vue

```
<template>
  <div class="demo-progress">
    <el-progress :percentage="percentage" :color="customColor" />

    <el-progress :percentage="percentage" :color="customColorMethod" />

    <el-progress :percentage="percentage" :color="customColors" />
    <el-progress :percentage="percentage" :color="customColors" />
    <div>
      <el-button-group>
        <el-button :icon="Minus" @click="decrease" />
        <el-button :icon="Plus" @click="increase" />
      </el-button-group>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Minus, Plus } from '@element-plus/icons-vue'

const percentage = ref(20)
const customColor = ref('#409eff')

const customColors = [
  { color: '#f56c6c', percentage: 20 },
  { color: '#e6a23c', percentage: 40 },
  { color: '#5cb87a', percentage: 60 },
  { color: '#1989fa', percentage: 80 },
  { color: '#6f7ad3', percentage: 100 },
]

const customColorMethod = (percentage: number) => {
  if (percentage < 30) {
    return '#909399'
  }
  if (percentage < 70) {
    return '#e6a23c'
  }
  return '#67c23a'
}
const increase = () => {
  percentage.value += 10
  if (percentage.value > 100) {
    percentage.value = 100
  }
}
const decrease = () => {
  percentage.value -= 10
  if (percentage.value < 0) {
    percentage.value = 0
  }
}
</script>

<style scoped>
.demo-progress .el-progress--line {
  margin-bottom: 15px;
  max-width: 600px;
}
</style>
```

隐藏源代码

## 环形进度条 [​](#环形进度条)

Progress 组件可通过 `type` 属性来指定使用环形进度条，在环形进度条中，还可以通过 `width` 属性来设置其大小。

0%

25%

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1wcm9ncmVzc1wiPlxuICAgIDxlbC1wcm9ncmVzcyB0eXBlPVwiY2lyY2xlXCIgOnBlcmNlbnRhZ2U9XCIwXCIgLz5cbiAgICA8ZWwtcHJvZ3Jlc3MgdHlwZT1cImNpcmNsZVwiIDpwZXJjZW50YWdlPVwiMjVcIiAvPlxuICAgIDxlbC1wcm9ncmVzcyB0eXBlPVwiY2lyY2xlXCIgOnBlcmNlbnRhZ2U9XCIxMDBcIiBzdGF0dXM9XCJzdWNjZXNzXCIgLz5cbiAgICA8ZWwtcHJvZ3Jlc3MgdHlwZT1cImNpcmNsZVwiIDpwZXJjZW50YWdlPVwiNzBcIiBzdGF0dXM9XCJ3YXJuaW5nXCIgLz5cbiAgICA8ZWwtcHJvZ3Jlc3MgdHlwZT1cImNpcmNsZVwiIDpwZXJjZW50YWdlPVwiNTBcIiBzdGF0dXM9XCJleGNlcHRpb25cIiAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1wcm9ncmVzcyAuZWwtcHJvZ3Jlc3MtLWNpcmNsZSB7XG4gIG1hcmdpbi1yaWdodDogMTVweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/progress/circular-progress-bar.vue)_

vue

```
<template>
  <div class="demo-progress">
    <el-progress type="circle" :percentage="0" />
    <el-progress type="circle" :percentage="25" />
    <el-progress type="circle" :percentage="100" status="success" />
    <el-progress type="circle" :percentage="70" status="warning" />
    <el-progress type="circle" :percentage="50" status="exception" />
  </div>
</template>

<style scoped>
.demo-progress .el-progress--circle {
  margin-right: 15px;
}
</style>
```

隐藏源代码

## 仪表盘形进度条 [​](#仪表盘形进度条)

您也可以指定 `type` 属性到 `dashboard` 使用控制面板进度栏。

10%

70%

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1wcm9ncmVzc1wiPlxuICAgIDxlbC1wcm9ncmVzcyB0eXBlPVwiZGFzaGJvYXJkXCIgOnBlcmNlbnRhZ2U9XCJwZXJjZW50YWdlXCIgOmNvbG9yPVwiY29sb3JzXCIgLz5cbiAgICA8ZWwtcHJvZ3Jlc3MgdHlwZT1cImRhc2hib2FyZFwiIDpwZXJjZW50YWdlPVwicGVyY2VudGFnZTJcIiA6Y29sb3I9XCJjb2xvcnNcIiAvPlxuICAgIDxkaXY+XG4gICAgICA8ZWwtYnV0dG9uLWdyb3VwPlxuICAgICAgICA8ZWwtYnV0dG9uIDppY29uPVwiTWludXNcIiBAY2xpY2s9XCJkZWNyZWFzZVwiIC8+XG4gICAgICAgIDxlbC1idXR0b24gOmljb249XCJQbHVzXCIgQGNsaWNrPVwiaW5jcmVhc2VcIiAvPlxuICAgICAgPC9lbC1idXR0b24tZ3JvdXA+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IG9uTW91bnRlZCwgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgTWludXMsIFBsdXMgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgcGVyY2VudGFnZSA9IHJlZigxMClcbmNvbnN0IHBlcmNlbnRhZ2UyID0gcmVmKDApXG5cbmNvbnN0IGNvbG9ycyA9IFtcbiAgeyBjb2xvcjogJyNmNTZjNmMnLCBwZXJjZW50YWdlOiAyMCB9LFxuICB7IGNvbG9yOiAnI2U2YTIzYycsIHBlcmNlbnRhZ2U6IDQwIH0sXG4gIHsgY29sb3I6ICcjNWNiODdhJywgcGVyY2VudGFnZTogNjAgfSxcbiAgeyBjb2xvcjogJyMxOTg5ZmEnLCBwZXJjZW50YWdlOiA4MCB9LFxuICB7IGNvbG9yOiAnIzZmN2FkMycsIHBlcmNlbnRhZ2U6IDEwMCB9LFxuXVxuXG5jb25zdCBpbmNyZWFzZSA9ICgpID0+IHtcbiAgcGVyY2VudGFnZS52YWx1ZSArPSAxMFxuICBpZiAocGVyY2VudGFnZS52YWx1ZSA+IDEwMCkge1xuICAgIHBlcmNlbnRhZ2UudmFsdWUgPSAxMDBcbiAgfVxufVxuY29uc3QgZGVjcmVhc2UgPSAoKSA9PiB7XG4gIHBlcmNlbnRhZ2UudmFsdWUgLT0gMTBcbiAgaWYgKHBlcmNlbnRhZ2UudmFsdWUgPCAwKSB7XG4gICAgcGVyY2VudGFnZS52YWx1ZSA9IDBcbiAgfVxufVxub25Nb3VudGVkKCgpID0+IHtcbiAgc2V0SW50ZXJ2YWwoKCkgPT4ge1xuICAgIHBlcmNlbnRhZ2UyLnZhbHVlID0gKHBlcmNlbnRhZ2UyLnZhbHVlICUgMTAwKSArIDEwXG4gIH0sIDUwMClcbn0pXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLXByb2dyZXNzIC5lbC1wcm9ncmVzcy0tbGluZSB7XG4gIG1hcmdpbi1ib3R0b206IDE1cHg7XG4gIG1heC13aWR0aDogNjAwcHg7XG59XG4uZGVtby1wcm9ncmVzcyAuZWwtcHJvZ3Jlc3MtLWNpcmNsZSB7XG4gIG1hcmdpbi1yaWdodDogMTVweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/progress/dashboard-progress-bar.vue)_

vue

```
<template>
  <div class="demo-progress">
    <el-progress type="dashboard" :percentage="percentage" :color="colors" />
    <el-progress type="dashboard" :percentage="percentage2" :color="colors" />
    <div>
      <el-button-group>
        <el-button :icon="Minus" @click="decrease" />
        <el-button :icon="Plus" @click="increase" />
      </el-button-group>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { onMounted, ref } from 'vue'
import { Minus, Plus } from '@element-plus/icons-vue'

const percentage = ref(10)
const percentage2 = ref(0)

const colors = [
  { color: '#f56c6c', percentage: 20 },
  { color: '#e6a23c', percentage: 40 },
  { color: '#5cb87a', percentage: 60 },
  { color: '#1989fa', percentage: 80 },
  { color: '#6f7ad3', percentage: 100 },
]

const increase = () => {
  percentage.value += 10
  if (percentage.value > 100) {
    percentage.value = 100
  }
}
const decrease = () => {
  percentage.value -= 10
  if (percentage.value < 0) {
    percentage.value = 0
  }
}
onMounted(() => {
  setInterval(() => {
    percentage2.value = (percentage2.value % 100) + 10
  }, 500)
})
</script>

<style scoped>
.demo-progress .el-progress--line {
  margin-bottom: 15px;
  max-width: 600px;
}
.demo-progress .el-progress--circle {
  margin-right: 15px;
}
</style>
```

隐藏源代码

## 自定义内容 [​](#自定义内容)

通过默认插槽添加自定义内容。

Content

Content

80%Progressing

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1wcm9ncmVzc1wiPlxuICAgIDxlbC1wcm9ncmVzcyA6cGVyY2VudGFnZT1cIjUwXCI+XG4gICAgICA8ZWwtYnV0dG9uIHRleHQ+Q29udGVudDwvZWwtYnV0dG9uPlxuICAgIDwvZWwtcHJvZ3Jlc3M+XG4gICAgPGVsLXByb2dyZXNzXG4gICAgICA6dGV4dC1pbnNpZGU9XCJ0cnVlXCJcbiAgICAgIDpzdHJva2Utd2lkdGg9XCIyMFwiXG4gICAgICA6cGVyY2VudGFnZT1cIjUwXCJcbiAgICAgIHN0YXR1cz1cImV4Y2VwdGlvblwiXG4gICAgPlxuICAgICAgPHNwYW4+Q29udGVudDwvc3Bhbj5cbiAgICA8L2VsLXByb2dyZXNzPlxuICAgIDxlbC1wcm9ncmVzcyB0eXBlPVwiY2lyY2xlXCIgOnBlcmNlbnRhZ2U9XCIxMDBcIiBzdGF0dXM9XCJzdWNjZXNzXCI+XG4gICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJzdWNjZXNzXCIgOmljb249XCJDaGVja1wiIGNpcmNsZSAvPlxuICAgIDwvZWwtcHJvZ3Jlc3M+XG4gICAgPGVsLXByb2dyZXNzIHR5cGU9XCJkYXNoYm9hcmRcIiA6cGVyY2VudGFnZT1cIjgwXCI+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJ7IHBlcmNlbnRhZ2UgfVwiPlxuICAgICAgICA8c3BhbiBjbGFzcz1cInBlcmNlbnRhZ2UtdmFsdWVcIj57eyBwZXJjZW50YWdlIH19JTwvc3Bhbj5cbiAgICAgICAgPHNwYW4gY2xhc3M9XCJwZXJjZW50YWdlLWxhYmVsXCI+UHJvZ3Jlc3Npbmc8L3NwYW4+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtcHJvZ3Jlc3M+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IENoZWNrIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5wZXJjZW50YWdlLXZhbHVlIHtcbiAgZGlzcGxheTogYmxvY2s7XG4gIG1hcmdpbi10b3A6IDEwcHg7XG4gIGZvbnQtc2l6ZTogMjhweDtcbn1cbi5wZXJjZW50YWdlLWxhYmVsIHtcbiAgZGlzcGxheTogYmxvY2s7XG4gIG1hcmdpbi10b3A6IDEwcHg7XG4gIGZvbnQtc2l6ZTogMTJweDtcbn1cbi5kZW1vLXByb2dyZXNzIC5lbC1wcm9ncmVzcy0tbGluZSB7XG4gIG1hcmdpbi1ib3R0b206IDE1cHg7XG4gIG1heC13aWR0aDogNjAwcHg7XG59XG4uZGVtby1wcm9ncmVzcyAuZWwtcHJvZ3Jlc3MtLWNpcmNsZSB7XG4gIG1hcmdpbi1yaWdodDogMTVweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/progress/customized-content.vue)_

vue

```
<template>
  <div class="demo-progress">
    <el-progress :percentage="50">
      <el-button text>Content</el-button>
    </el-progress>
    <el-progress
      :text-inside="true"
      :stroke-width="20"
      :percentage="50"
      status="exception"
    >
      <span>Content</span>
    </el-progress>
    <el-progress type="circle" :percentage="100" status="success">
      <el-button type="success" :icon="Check" circle />
    </el-progress>
    <el-progress type="dashboard" :percentage="80">
      <template #default="{ percentage }">
        <span class="percentage-value">{{ percentage }}%</span>
        <span class="percentage-label">Progressing</span>
      </template>
    </el-progress>
  </div>
</template>

<script lang="ts" setup>
import { Check } from '@element-plus/icons-vue'
</script>

<style scoped>
.percentage-value {
  display: block;
  margin-top: 10px;
  font-size: 28px;
}
.percentage-label {
  display: block;
  margin-top: 10px;
  font-size: 12px;
}
.demo-progress .el-progress--line {
  margin-bottom: 15px;
  max-width: 600px;
}
.demo-progress .el-progress--circle {
  margin-right: 15px;
}
</style>
```

隐藏源代码

## 动画进度条 [​](#动画进度条)

使用 `indeterminate` 属性来设置不确定的进度， `duration` 来控制动画持续时间。

50%

Full

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1wcm9ncmVzc1wiPlxuICAgIDxlbC1wcm9ncmVzcyA6cGVyY2VudGFnZT1cIjUwXCIgOmluZGV0ZXJtaW5hdGU9XCJ0cnVlXCIgLz5cbiAgICA8ZWwtcHJvZ3Jlc3MgOnBlcmNlbnRhZ2U9XCIxMDBcIiA6Zm9ybWF0PVwiZm9ybWF0XCIgOmluZGV0ZXJtaW5hdGU9XCJ0cnVlXCIgLz5cbiAgICA8ZWwtcHJvZ3Jlc3NcbiAgICAgIDpwZXJjZW50YWdlPVwiMTAwXCJcbiAgICAgIHN0YXR1cz1cInN1Y2Nlc3NcIlxuICAgICAgOmluZGV0ZXJtaW5hdGU9XCJ0cnVlXCJcbiAgICAgIDpkdXJhdGlvbj1cIjVcIlxuICAgIC8+XG4gICAgPGVsLXByb2dyZXNzXG4gICAgICA6cGVyY2VudGFnZT1cIjEwMFwiXG4gICAgICBzdGF0dXM9XCJ3YXJuaW5nXCJcbiAgICAgIDppbmRldGVybWluYXRlPVwidHJ1ZVwiXG4gICAgICA6ZHVyYXRpb249XCIxXCJcbiAgICAvPlxuICAgIDxlbC1wcm9ncmVzcyA6cGVyY2VudGFnZT1cIjUwXCIgc3RhdHVzPVwiZXhjZXB0aW9uXCIgOmluZGV0ZXJtaW5hdGU9XCJ0cnVlXCIgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuY29uc3QgZm9ybWF0ID0gKHBlcmNlbnRhZ2UpID0+IChwZXJjZW50YWdlID09PSAxMDAgPyAnRnVsbCcgOiBgJHtwZXJjZW50YWdlfSVgKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZGVtby1wcm9ncmVzcyAuZWwtcHJvZ3Jlc3MtLWxpbmUge1xuICBtYXJnaW4tYm90dG9tOiAxNXB4O1xuICBtYXgtd2lkdGg6IDYwMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/progress/indeterminate-progress.vue)_

vue

```
<template>
  <div class="demo-progress">
    <el-progress :percentage="50" :indeterminate="true" />
    <el-progress :percentage="100" :format="format" :indeterminate="true" />
    <el-progress
      :percentage="100"
      status="success"
      :indeterminate="true"
      :duration="5"
    />
    <el-progress
      :percentage="100"
      status="warning"
      :indeterminate="true"
      :duration="1"
    />
    <el-progress :percentage="50" status="exception" :indeterminate="true" />
  </div>
</template>

<script lang="ts" setup>
const format = (percentage) => (percentage === 100 ? 'Full' : `${percentage}%`)
</script>

<style scoped>
.demo-progress .el-progress--line {
  margin-bottom: 15px;
  max-width: 600px;
}
</style>
```

隐藏源代码

## 条纹进度条 [​](#条纹进度条)

通过设置 `striped` 属性获取条纹进度条。 也可以使用 `striped-flow` 属性来使条纹流动起来。 使用`duration` 属性来控制条纹流动的速度。

50%

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZGVtby1wcm9ncmVzc1wiPlxuICAgIDxlbC1wcm9ncmVzcyA6cGVyY2VudGFnZT1cIjUwXCIgOnN0cm9rZS13aWR0aD1cIjE1XCIgc3RyaXBlZCAvPlxuICAgIDxlbC1wcm9ncmVzc1xuICAgICAgOnBlcmNlbnRhZ2U9XCIzMFwiXG4gICAgICA6c3Ryb2tlLXdpZHRoPVwiMTVcIlxuICAgICAgc3RhdHVzPVwid2FybmluZ1wiXG4gICAgICBzdHJpcGVkXG4gICAgICBzdHJpcGVkLWZsb3dcbiAgICAvPlxuICAgIDxlbC1wcm9ncmVzc1xuICAgICAgOnBlcmNlbnRhZ2U9XCIxMDBcIlxuICAgICAgOnN0cm9rZS13aWR0aD1cIjE1XCJcbiAgICAgIHN0YXR1cz1cInN1Y2Nlc3NcIlxuICAgICAgc3RyaXBlZFxuICAgICAgc3RyaXBlZC1mbG93XG4gICAgICA6ZHVyYXRpb249XCIxMFwiXG4gICAgLz5cbiAgICA8ZWwtcHJvZ3Jlc3NcbiAgICAgIDpwZXJjZW50YWdlPVwicGVyY2VudGFnZVwiXG4gICAgICA6c3Ryb2tlLXdpZHRoPVwiMTVcIlxuICAgICAgc3RhdHVzPVwiZXhjZXB0aW9uXCJcbiAgICAgIHN0cmlwZWRcbiAgICAgIHN0cmlwZWQtZmxvd1xuICAgICAgOmR1cmF0aW9uPVwiZHVyYXRpb25cIlxuICAgIC8+XG4gICAgPGVsLWJ1dHRvbi1ncm91cD5cbiAgICAgIDxlbC1idXR0b24gOmljb249XCJNaW51c1wiIEBjbGljaz1cImRlY3JlYXNlXCIgLz5cbiAgICAgIDxlbC1idXR0b24gOmljb249XCJQbHVzXCIgQGNsaWNrPVwiaW5jcmVhc2VcIiAvPlxuICAgIDwvZWwtYnV0dG9uLWdyb3VwPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBjb21wdXRlZCwgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgTWludXMsIFBsdXMgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgcGVyY2VudGFnZSA9IHJlZjxudW1iZXI+KDcwKVxuY29uc3QgZHVyYXRpb24gPSBjb21wdXRlZCgoKSA9PiBNYXRoLmZsb29yKHBlcmNlbnRhZ2UudmFsdWUgLyAxMCkpXG5cbmNvbnN0IGluY3JlYXNlID0gKCkgPT4ge1xuICBwZXJjZW50YWdlLnZhbHVlICs9IDEwXG4gIGlmIChwZXJjZW50YWdlLnZhbHVlID4gMTAwKSB7XG4gICAgcGVyY2VudGFnZS52YWx1ZSA9IDEwMFxuICB9XG59XG5jb25zdCBkZWNyZWFzZSA9ICgpID0+IHtcbiAgcGVyY2VudGFnZS52YWx1ZSAtPSAxMFxuICBpZiAocGVyY2VudGFnZS52YWx1ZSA8IDApIHtcbiAgICBwZXJjZW50YWdlLnZhbHVlID0gMFxuICB9XG59XG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5kZW1vLXByb2dyZXNzIC5lbC1wcm9ncmVzcy0tbGluZSB7XG4gIG1hcmdpbi1ib3R0b206IDE1cHg7XG4gIG1heC13aWR0aDogNjAwcHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/progress/striped-progress.vue)_

vue

```
<template>
  <div class="demo-progress">
    <el-progress :percentage="50" :stroke-width="15" striped />
    <el-progress
      :percentage="30"
      :stroke-width="15"
      status="warning"
      striped
      striped-flow
    />
    <el-progress
      :percentage="100"
      :stroke-width="15"
      status="success"
      striped
      striped-flow
      :duration="10"
    />
    <el-progress
      :percentage="percentage"
      :stroke-width="15"
      status="exception"
      striped
      striped-flow
      :duration="duration"
    />
    <el-button-group>
      <el-button :icon="Minus" @click="decrease" />
      <el-button :icon="Plus" @click="increase" />
    </el-button-group>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'
import { Minus, Plus } from '@element-plus/icons-vue'

const percentage = ref<number>(70)
const duration = computed(() => Math.floor(percentage.value / 10))

const increase = () => {
  percentage.value += 10
  if (percentage.value > 100) {
    percentage.value = 100
  }
}
const decrease = () => {
  percentage.value -= 10
  if (percentage.value < 0) {
    percentage.value = 0
  }
}
</script>

<style scoped>
.demo-progress .el-progress--line {
  margin-bottom: 15px;
  max-width: 600px;
}
</style>
```

隐藏源代码

## API [​](#api)

### 属性 [​](#属性)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| percentage required | percentage | `number` | 0 |
| type | 进度条类型 | `enum` | line |
| stroke-width | 进度条的宽度 | `number` | 6 |
| text-inside | 进度条显示文字内置在进度条内（仅 `type` 为 'line' 时可用） | `boolean` | false |
| status | 进度条当前状态 | `enum` | — |
| indeterminate | 是否为动画进度条 | `boolean` | false |
| duration | 控制动画进度条速度和条纹进度条流动速度 | `number` | 3 |
| color | 进度条背景色 （会覆盖 `status` 状态颜色） | `string` / `function` / `Array` | '' |
| width | 环形进度条画布宽度（只在 type 为 circle 或 dashboard 时可用） | `number` | 126 |
| show-text | 是否显示进度条文字内容 | `boolean` | true |
| stroke-linecap | circle/dashboard 类型路径两端的形状 | `enum` | round |
| format | 指定进度条文字内容 | `Function` | — |
| striped 2.3.4 | 在进度条上增加条纹 | `boolean` | false |
| striped-flow 2.3.4 | 让进度条上的条纹流动起来 | `boolean` | false |

### Slots [​](#slots)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| default | 自定义内容 | `object` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/progress) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/progress.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/progress.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/82307113?v=4&size=64)](https://github.com/754664196)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/9958583?v=4&size=64)](https://github.com/Otto-J)[![](https://avatars.githubusercontent.com/u/12029924?v=4&size=64)](https://github.com/rottenpen)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/33799081?v=4&size=64)](https://github.com/wuyadan)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/50621078?v=4&size=64)](https://github.com/HYzihong)

[Pagination 分页](https://element-plus.org/zh-CN/component/pagination)

[Result 结果](https://element-plus.org/zh-CN/component/result)




---
## [data/result] Result 结果
> 官方文档: https://element-plus.org/zh-CN/component/result.html

---

# Result 结果 [​](#result-结果)

更新日志待解决

4

用于对用户的操作结果或者异常状态做反馈。

## 基础用法 [​](#基础用法)

`primary` 已被添加到2.9.11。

Primary Tip

Please follow the instructions

Back

Success Tip

Please follow the instructions

Back

Warning Tip

Please follow the instructions

Back

Error Tip

Please follow the instructions

Back

Info Tip

Using slot as subtitle

Back

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93PlxuICAgIDxlbC1jb2wgOnNtPVwiMTJcIiA6bGc9XCI2XCIgOnhsPVwiNFwiPlxuICAgICAgPGVsLXJlc3VsdFxuICAgICAgICBpY29uPVwicHJpbWFyeVwiXG4gICAgICAgIHRpdGxlPVwiUHJpbWFyeSBUaXBcIlxuICAgICAgICBzdWItdGl0bGU9XCJQbGVhc2UgZm9sbG93IHRoZSBpbnN0cnVjdGlvbnNcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI2V4dHJhPlxuICAgICAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIj5CYWNrPC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXJlc3VsdD5cbiAgICA8L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpzbT1cIjEyXCIgOmxnPVwiNlwiIDp4bD1cIjRcIj5cbiAgICAgIDxlbC1yZXN1bHRcbiAgICAgICAgaWNvbj1cInN1Y2Nlc3NcIlxuICAgICAgICB0aXRsZT1cIlN1Y2Nlc3MgVGlwXCJcbiAgICAgICAgc3ViLXRpdGxlPVwiUGxlYXNlIGZvbGxvdyB0aGUgaW5zdHJ1Y3Rpb25zXCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNleHRyYT5cbiAgICAgICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCI+QmFjazwvZWwtYnV0dG9uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1yZXN1bHQ+XG4gICAgPC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c209XCIxMlwiIDpsZz1cIjZcIiA6eGw9XCI0XCI+XG4gICAgICA8ZWwtcmVzdWx0XG4gICAgICAgIGljb249XCJ3YXJuaW5nXCJcbiAgICAgICAgdGl0bGU9XCJXYXJuaW5nIFRpcFwiXG4gICAgICAgIHN1Yi10aXRsZT1cIlBsZWFzZSBmb2xsb3cgdGhlIGluc3RydWN0aW9uc1wiXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjZXh0cmE+XG4gICAgICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiPkJhY2s8L2VsLWJ1dHRvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtcmVzdWx0PlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNtPVwiMTJcIiA6bGc9XCI2XCIgOnhsPVwiNFwiPlxuICAgICAgPGVsLXJlc3VsdFxuICAgICAgICBpY29uPVwiZXJyb3JcIlxuICAgICAgICB0aXRsZT1cIkVycm9yIFRpcFwiXG4gICAgICAgIHN1Yi10aXRsZT1cIlBsZWFzZSBmb2xsb3cgdGhlIGluc3RydWN0aW9uc1wiXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjZXh0cmE+XG4gICAgICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiPkJhY2s8L2VsLWJ1dHRvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtcmVzdWx0PlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNtPVwiMTJcIiA6bGc9XCI2XCIgOnhsPVwiNFwiPlxuICAgICAgPGVsLXJlc3VsdCBpY29uPVwiaW5mb1wiIHRpdGxlPVwiSW5mbyBUaXBcIj5cbiAgICAgICAgPHRlbXBsYXRlICNzdWItdGl0bGU+XG4gICAgICAgICAgPHA+VXNpbmcgc2xvdCBhcyBzdWJ0aXRsZTwvcD5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPHRlbXBsYXRlICNleHRyYT5cbiAgICAgICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCI+QmFjazwvZWwtYnV0dG9uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1yZXN1bHQ+XG4gICAgPC9lbC1jb2w+XG4gIDwvZWwtcm93PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/result/basic-usage.vue)_

vue

```
<template>
  <el-row>
    <el-col :sm="12" :lg="6" :xl="4">
      <el-result
        icon="primary"
        title="Primary Tip"
        sub-title="Please follow the instructions"
      >
        <template #extra>
          <el-button type="primary">Back</el-button>
        </template>
      </el-result>
    </el-col>
    <el-col :sm="12" :lg="6" :xl="4">
      <el-result
        icon="success"
        title="Success Tip"
        sub-title="Please follow the instructions"
      >
        <template #extra>
          <el-button type="primary">Back</el-button>
        </template>
      </el-result>
    </el-col>
    <el-col :sm="12" :lg="6" :xl="4">
      <el-result
        icon="warning"
        title="Warning Tip"
        sub-title="Please follow the instructions"
      >
        <template #extra>
          <el-button type="primary">Back</el-button>
        </template>
      </el-result>
    </el-col>
    <el-col :sm="12" :lg="6" :xl="4">
      <el-result
        icon="error"
        title="Error Tip"
        sub-title="Please follow the instructions"
      >
        <template #extra>
          <el-button type="primary">Back</el-button>
        </template>
      </el-result>
    </el-col>
    <el-col :sm="12" :lg="6" :xl="4">
      <el-result icon="info" title="Info Tip">
        <template #sub-title>
          <p>Using slot as subtitle</p>
        </template>
        <template #extra>
          <el-button type="primary">Back</el-button>
        </template>
      </el-result>
    </el-col>
  </el-row>
</template>

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

隐藏源代码

## 自定义内容 [​](#自定义内容)

![](https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png)

404

Sorry, request error

Back

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmVzdWx0IHRpdGxlPVwiNDA0XCIgc3ViLXRpdGxlPVwiU29ycnksIHJlcXVlc3QgZXJyb3JcIj5cbiAgICA8dGVtcGxhdGUgI2ljb24+XG4gICAgICA8ZWwtaW1hZ2VcbiAgICAgICAgc3JjPVwiaHR0cHM6Ly9zaGFkb3cuZWxlbWVjZG4uY29tL2FwcC9lbGVtZW50L2hhbWJ1cmdlci45Y2Y3YjA5MS01NWU5LTExZTktYTk3Ni03ZjRkMGIwN2VlZjYucG5nXCJcbiAgICAgIC8+XG4gICAgPC90ZW1wbGF0ZT5cbiAgICA8dGVtcGxhdGUgI2V4dHJhPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiPkJhY2s8L2VsLWJ1dHRvbj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLXJlc3VsdD5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/result/customized-content.vue)_

vue

```
<template>
  <el-result title="404" sub-title="Sorry, request error">
    <template #icon>
      <el-image
        src="https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png"
      />
    </template>
    <template #extra>
      <el-button type="primary">Back</el-button>
    </template>
  </el-result>
</template>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| title | result 组件的标题 | `string` | '' |
| sub-title | result 组件的副标题 | `string` | '' |
| icon | result 组件的图标类型 | `enum` | info |

### 插槽 [​](#插槽)

| 名称 | 说明 |
| --- | --- |
| icon | icon 内容 |
| title | result title 的内容 |
| sub-title | sub title 的内容 |
| extra | 内容额外区域的内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/result) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/result.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/result.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/20151622?v=4&size=64)](https://github.com/william-xue)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)

[Progress 进度条](https://element-plus.org/zh-CN/component/progress)

[Skeleton 骨架屏](https://element-plus.org/zh-CN/component/skeleton)




---
## [data/skeleton] Skeleton 骨架屏
> 官方文档: https://element-plus.org/zh-CN/component/skeleton.html

---

# Skeleton 骨架屏 [​](#skeleton-骨架屏)

更新日志待解决

1

在需要等待加载内容的位置设置一个骨架屏，某些场景下比 Loading 的视觉效果更好。

## 基础用法 [​](#基础用法)

基础的骨架效果。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2tlbGV0b24gLz5cbiAgPGJyIC8+XG4gIDxlbC1za2VsZXRvbiBzdHlsZT1cIi0tZWwtc2tlbGV0b24tY2lyY2xlLXNpemU6IDEwMHB4XCI+XG4gICAgPHRlbXBsYXRlICN0ZW1wbGF0ZT5cbiAgICAgIDxlbC1za2VsZXRvbi1pdGVtIHZhcmlhbnQ9XCJjaXJjbGVcIiAvPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtc2tlbGV0b24+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/skeleton/basic-usage.vue)_

vue

```
<template>
  <el-skeleton />
  <br />
  <el-skeleton style="--el-skeleton-circle-size: 100px">
    <template #template>
      <el-skeleton-item variant="circle" />
    </template>
  </el-skeleton>
</template>
```

隐藏源代码

## 更多参数 [​](#更多参数)

可以配置骨架屏段落数量，以便更接近真实渲染效果。显示的数量会比传入的数量多 1，首行会被渲染一个长度 33% 的段首。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2tlbGV0b24gOnJvd3M9XCI1XCIgLz5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/skeleton/configurable-rows.vue)_

vue

```
<template>
  <el-skeleton :rows="5" />
</template>
```

隐藏源代码

## 动画效果 [​](#动画效果)

我们提供了一个开关标志，表明是否显示加载动画， 调用 `animated` 如果真是这样，所有的 `el-skeleton` 的子节点将显示动画。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2tlbGV0b24gOnJvd3M9XCI1XCIgYW5pbWF0ZWQgLz5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/skeleton/animation.vue)_

vue

```
<template>
  <el-skeleton :rows="5" animated />
</template>
```

隐藏源代码

## 自定义样式 [​](#自定义样式)

Element Plus 提供的排版模式有时候并不满足要求，当您想要用自己定义的模板时，可以通过一个具名 Slot `template` 来自己设定模板。

我们提供了不同的模板单元可供使用，具体可选值请看 API 详细描述。 另外，在构建您自己自定义的骨架时，您应该尽可能更接近于真正的DOM。 避免DOM因高度差而发生抖动。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc2tlbGV0b24gc3R5bGU9XCJ3aWR0aDogMjQwcHhcIj5cbiAgICA8dGVtcGxhdGUgI3RlbXBsYXRlPlxuICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cImltYWdlXCIgc3R5bGU9XCJ3aWR0aDogMjQwcHg7IGhlaWdodDogMjQwcHhcIiAvPlxuICAgICAgPGRpdiBzdHlsZT1cInBhZGRpbmc6IDE0cHhcIj5cbiAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cInBcIiBzdHlsZT1cIndpZHRoOiA1MCVcIiAvPlxuICAgICAgICA8ZGl2XG4gICAgICAgICAgc3R5bGU9XCJcbiAgICAgICAgICAgIGRpc3BsYXk6IGZsZXg7XG4gICAgICAgICAgICBhbGlnbi1pdGVtczogY2VudGVyO1xuICAgICAgICAgICAganVzdGlmeS1pdGVtczogc3BhY2UtYmV0d2VlbjtcbiAgICAgICAgICBcIlxuICAgICAgICA+XG4gICAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cInRleHRcIiBzdHlsZT1cIm1hcmdpbi1yaWdodDogMTZweFwiIC8+XG4gICAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cInRleHRcIiBzdHlsZT1cIndpZHRoOiAzMCVcIiAvPlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtc2tlbGV0b24+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/skeleton/customized-template.vue)_

vue

```
<template>
  <el-skeleton style="width: 240px">
    <template #template>
      <el-skeleton-item variant="image" style="width: 240px; height: 240px" />
      <div style="padding: 14px">
        <el-skeleton-item variant="p" style="width: 50%" />
        <div
          style="
            display: flex;
            align-items: center;
            justify-items: space-between;
          "
        >
          <el-skeleton-item variant="text" style="margin-right: 16px" />
          <el-skeleton-item variant="text" style="width: 30%" />
        </div>
      </div>
    </template>
  </el-skeleton>
</template>
```

隐藏源代码

## 加载状态 [​](#加载状态)

当 `Loading` 结束之后，我们往往需要显示真实的 UI， 可以通过 `loading` 属性的值来控制是否显示加载后的 DOM。 也可以通过具名插槽 `default` 来构建 loading 结束之后需要展示的真实 DOM 元素结构。

Switch Loading

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2UgZGlyZWN0aW9uPVwidmVydGljYWxcIiBhbGlnbm1lbnQ9XCJmbGV4LXN0YXJ0XCI+XG4gICAgPGRpdj5cbiAgICAgIDxsYWJlbCBzdHlsZT1cIm1hcmdpbi1yaWdodDogMTZweFwiPlN3aXRjaCBMb2FkaW5nPC9sYWJlbD5cbiAgICAgIDxlbC1zd2l0Y2ggdi1tb2RlbD1cImxvYWRpbmdcIiAvPlxuICAgIDwvZGl2PlxuICAgIDxlbC1za2VsZXRvbiBzdHlsZT1cIndpZHRoOiAyNDBweFwiIDpsb2FkaW5nPVwibG9hZGluZ1wiIGFuaW1hdGVkPlxuICAgICAgPHRlbXBsYXRlICN0ZW1wbGF0ZT5cbiAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cImltYWdlXCIgc3R5bGU9XCJ3aWR0aDogMjQwcHg7IGhlaWdodDogMjQwcHhcIiAvPlxuICAgICAgICA8ZGl2IHN0eWxlPVwicGFkZGluZzogMTRweFwiPlxuICAgICAgICAgIDxlbC1za2VsZXRvbi1pdGVtIHZhcmlhbnQ9XCJoM1wiIHN0eWxlPVwid2lkdGg6IDUwJVwiIC8+XG4gICAgICAgICAgPGRpdlxuICAgICAgICAgICAgc3R5bGU9XCJcbiAgICAgICAgICAgICAgZGlzcGxheTogZmxleDtcbiAgICAgICAgICAgICAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbiAgICAgICAgICAgICAganVzdGlmeS1pdGVtczogc3BhY2UtYmV0d2VlbjtcbiAgICAgICAgICAgICAgbWFyZ2luLXRvcDogMTZweDtcbiAgICAgICAgICAgICAgaGVpZ2h0OiAxNnB4O1xuICAgICAgICAgICAgXCJcbiAgICAgICAgICA+XG4gICAgICAgICAgICA8ZWwtc2tlbGV0b24taXRlbSB2YXJpYW50PVwidGV4dFwiIHN0eWxlPVwibWFyZ2luLXJpZ2h0OiAxNnB4XCIgLz5cbiAgICAgICAgICAgIDxlbC1za2VsZXRvbi1pdGVtIHZhcmlhbnQ9XCJ0ZXh0XCIgc3R5bGU9XCJ3aWR0aDogMzAlXCIgLz5cbiAgICAgICAgICA8L2Rpdj5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgPHRlbXBsYXRlICNkZWZhdWx0PlxuICAgICAgICA8ZWwtY2FyZCA6Ym9keS1zdHlsZT1cInsgcGFkZGluZzogJzBweCcsIG1hcmdpbkJvdHRvbTogJzFweCcgfVwiPlxuICAgICAgICAgIDxpbWdcbiAgICAgICAgICAgIHNyYz1cImh0dHBzOi8vc2hhZG93LmVsZW1lY2RuLmNvbS9hcHAvZWxlbWVudC9oYW1idXJnZXIuOWNmN2IwOTEtNTVlOS0xMWU5LWE5NzYtN2Y0ZDBiMDdlZWY2LnBuZ1wiXG4gICAgICAgICAgICBjbGFzcz1cImltYWdlXCJcbiAgICAgICAgICAvPlxuICAgICAgICAgIDxkaXYgc3R5bGU9XCJwYWRkaW5nOiAxNHB4XCI+XG4gICAgICAgICAgICA8c3Bhbj5EZWxpY2lvdXMgaGFtYnVyZ2VyPC9zcGFuPlxuICAgICAgICAgICAgPGRpdiBjbGFzcz1cImJvdHRvbSBjYXJkLWhlYWRlclwiPlxuICAgICAgICAgICAgICA8ZGl2IGNsYXNzPVwidGltZVwiPnt7IGN1cnJlbnREYXRlIH19PC9kaXY+XG4gICAgICAgICAgICAgIDxlbC1idXR0b24gdGV4dCBjbGFzcz1cImJ1dHRvblwiPk9wZXJhdGlvbiBidXR0b248L2VsLWJ1dHRvbj5cbiAgICAgICAgICAgIDwvZGl2PlxuICAgICAgICAgIDwvZGl2PlxuICAgICAgICA8L2VsLWNhcmQ+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtc2tlbGV0b24+XG4gIDwvZWwtc3BhY2U+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBsb2FkaW5nID0gcmVmKHRydWUpXG5jb25zdCBjdXJyZW50RGF0ZSA9IG5ldyBEYXRlKCkudG9EYXRlU3RyaW5nKClcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/skeleton/loading-state.vue)_

vue

```
<template>
  <el-space direction="vertical" alignment="flex-start">
    <div>
      <label style="margin-right: 16px">Switch Loading</label>
      <el-switch v-model="loading" />
    </div>
    <el-skeleton style="width: 240px" :loading="loading" animated>
      <template #template>
        <el-skeleton-item variant="image" style="width: 240px; height: 240px" />
        <div style="padding: 14px">
          <el-skeleton-item variant="h3" style="width: 50%" />
          <div
            style="
              display: flex;
              align-items: center;
              justify-items: space-between;
              margin-top: 16px;
              height: 16px;
            "
          >
            <el-skeleton-item variant="text" style="margin-right: 16px" />
            <el-skeleton-item variant="text" style="width: 30%" />
          </div>
        </div>
      </template>
      <template #default>
        <el-card :body-style="{ padding: '0px', marginBottom: '1px' }">
          <img
            src="https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png"
            class="image"
          />
          <div style="padding: 14px">
            <span>Delicious hamburger</span>
            <div class="bottom card-header">
              <div class="time">{{ currentDate }}</div>
              <el-button text class="button">Operation button</el-button>
            </div>
          </div>
        </el-card>
      </template>
    </el-skeleton>
  </el-space>
</template>

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

const loading = ref(true)
const currentDate = new Date().toDateString()
</script>
```

隐藏源代码

## 渲染多条数据 [​](#渲染多条数据)

大多时候, 骨架屏都被用来渲染列表, 当我们需要在从服务器获取数据的时候来渲染一个假的 UI。 利用 `count` 这个属性就能控制渲染多少条假的数据在页面上

TIP

我们不推荐在浏览器中渲染过多的虚假 UI 元素，这样会消耗更多时间销毁骨架元素，从而引起性能问题。 为了用户体验，请尽量将 `count` 值保持在小一点的数值。

Click me to reload

![](https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg)

Deer

Wed Jun 24 2026

Operation button

![](https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg)

Horse

Wed Jun 24 2026

Operation button

![](https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg)

Mountain Lion

Wed Jun 24 2026

Operation button

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2Ugc3R5bGU9XCJ3aWR0aDogMTAwJVwiIGZpbGw+XG4gICAgPGRpdj5cbiAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwic2V0TG9hZGluZ1wiPkNsaWNrIG1lIHRvIHJlbG9hZDwvZWwtYnV0dG9uPlxuICAgIDwvZGl2PlxuICAgIDxlbC1za2VsZXRvblxuICAgICAgc3R5bGU9XCJkaXNwbGF5OiBmbGV4OyBnYXA6IDhweFwiXG4gICAgICA6bG9hZGluZz1cImxvYWRpbmdcIlxuICAgICAgYW5pbWF0ZWRcbiAgICAgIDpjb3VudD1cIjNcIlxuICAgID5cbiAgICAgIDx0ZW1wbGF0ZSAjdGVtcGxhdGU+XG4gICAgICAgIDxkaXYgc3R5bGU9XCJmbGV4OiAxXCI+XG4gICAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cImltYWdlXCIgc3R5bGU9XCJoZWlnaHQ6IDI0MHB4XCIgLz5cbiAgICAgICAgICA8ZGl2IHN0eWxlPVwicGFkZGluZzogMTRweFwiPlxuICAgICAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cImgzXCIgc3R5bGU9XCJ3aWR0aDogNTAlXCIgLz5cbiAgICAgICAgICAgIDxkaXZcbiAgICAgICAgICAgICAgc3R5bGU9XCJcbiAgICAgICAgICAgICAgICBkaXNwbGF5OiBmbGV4O1xuICAgICAgICAgICAgICAgIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG4gICAgICAgICAgICAgICAganVzdGlmeS1pdGVtczogc3BhY2UtYmV0d2VlbjtcbiAgICAgICAgICAgICAgICBtYXJnaW4tdG9wOiAxNnB4O1xuICAgICAgICAgICAgICAgIGhlaWdodDogMTZweDtcbiAgICAgICAgICAgICAgXCJcbiAgICAgICAgICAgID5cbiAgICAgICAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cInRleHRcIiBzdHlsZT1cIm1hcmdpbi1yaWdodDogMTZweFwiIC8+XG4gICAgICAgICAgICAgIDxlbC1za2VsZXRvbi1pdGVtIHZhcmlhbnQ9XCJ0ZXh0XCIgc3R5bGU9XCJ3aWR0aDogMzAlXCIgLz5cbiAgICAgICAgICAgIDwvZGl2PlxuICAgICAgICAgIDwvZGl2PlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ+XG4gICAgICAgIDxlbC1jYXJkXG4gICAgICAgICAgdi1mb3I9XCJpdGVtIGluIGxpc3RzXCJcbiAgICAgICAgICA6a2V5PVwiaXRlbS5uYW1lXCJcbiAgICAgICAgICA6Ym9keS1zdHlsZT1cInsgcGFkZGluZzogJzBweCcsIG1hcmdpbkJvdHRvbTogJzFweCcgfVwiXG4gICAgICAgID5cbiAgICAgICAgICA8aW1nXG4gICAgICAgICAgICA6c3JjPVwiaXRlbS5pbWdVcmxcIlxuICAgICAgICAgICAgY2xhc3M9XCJpbWFnZSBtdWx0aS1jb250ZW50XCJcbiAgICAgICAgICAgIHN0eWxlPVwibWF4LXdpZHRoOiAxMDAlXCJcbiAgICAgICAgICAvPlxuICAgICAgICAgIDxkaXYgc3R5bGU9XCJwYWRkaW5nOiAxNHB4XCI+XG4gICAgICAgICAgICA8c3Bhbj57eyBpdGVtLm5hbWUgfX08L3NwYW4+XG4gICAgICAgICAgICA8ZGl2IGNsYXNzPVwiYm90dG9tIGNhcmQtaGVhZGVyXCI+XG4gICAgICAgICAgICAgIDxkaXYgY2xhc3M9XCJ0aW1lXCI+e3sgY3VycmVudERhdGUgfX08L2Rpdj5cbiAgICAgICAgICAgICAgPGVsLWJ1dHRvbiB0ZXh0IGNsYXNzPVwiYnV0dG9uXCI+T3BlcmF0aW9uIGJ1dHRvbjwvZWwtYnV0dG9uPlxuICAgICAgICAgICAgPC9kaXY+XG4gICAgICAgICAgPC9kaXY+XG4gICAgICAgIDwvZWwtY2FyZD5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1za2VsZXRvbj5cbiAgPC9lbC1zcGFjZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBvbk1vdW50ZWQsIHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW50ZXJmYWNlIExpc3RJdGVtIHtcbiAgaW1nVXJsOiBzdHJpbmdcbiAgbmFtZTogc3RyaW5nXG59XG5cbmNvbnN0IGxvYWRpbmcgPSByZWYodHJ1ZSlcbmNvbnN0IGxpc3RzID0gcmVmPExpc3RJdGVtW10+KFtdKVxuY29uc3QgY3VycmVudERhdGUgPSBuZXcgRGF0ZSgpLnRvRGF0ZVN0cmluZygpXG5cbmNvbnN0IHNldExvYWRpbmcgPSAoKSA9PiB7XG4gIGxvYWRpbmcudmFsdWUgPSB0cnVlXG4gIHNldFRpbWVvdXQoKCkgPT4ge1xuICAgIGxvYWRpbmcudmFsdWUgPSBmYWxzZVxuICB9LCAyMDAwKVxufVxuXG5vbk1vdW50ZWQoKCkgPT4ge1xuICBsb2FkaW5nLnZhbHVlID0gZmFsc2VcbiAgbGlzdHMudmFsdWUgPSBbXG4gICAge1xuICAgICAgaW1nVXJsOlxuICAgICAgICAnaHR0cHM6Ly9mdXNzMTAuZWxlbWVjZG4uY29tL2EvM2YvMzMwMmU1OGY5YTE4MWQyNTA5ZjNkYzBmYTY4YjBqcGVnLmpwZWcnLFxuICAgICAgbmFtZTogJ0RlZXInLFxuICAgIH0sXG4gICAge1xuICAgICAgaW1nVXJsOlxuICAgICAgICAnaHR0cHM6Ly9mdXNzMTAuZWxlbWVjZG4uY29tLzEvMzQvMTlhYTk4YjFmY2IyNzgxYzRmYmEzM2Q4NTA1NDlqcGVnLmpwZWcnLFxuICAgICAgbmFtZTogJ0hvcnNlJyxcbiAgICB9LFxuICAgIHtcbiAgICAgIGltZ1VybDpcbiAgICAgICAgJ2h0dHBzOi8vZnVzczEwLmVsZW1lY2RuLmNvbS8wLzZmL2UzNWZmMzc1ODEyZTZiMDAyMGI2YjRlOGY5NTgzanBlZy5qcGVnJyxcbiAgICAgIG5hbWU6ICdNb3VudGFpbiBMaW9uJyxcbiAgICB9LFxuICBdXG59KVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/skeleton/rendering-with-data.vue)_

vue

```
<template>
  <el-space style="width: 100%" fill>
    <div>
      <el-button @click="setLoading">Click me to reload</el-button>
    </div>
    <el-skeleton
      style="display: flex; gap: 8px"
      :loading="loading"
      animated
      :count="3"
    >
      <template #template>
        <div style="flex: 1">
          <el-skeleton-item variant="image" style="height: 240px" />
          <div style="padding: 14px">
            <el-skeleton-item variant="h3" style="width: 50%" />
            <div
              style="
                display: flex;
                align-items: center;
                justify-items: space-between;
                margin-top: 16px;
                height: 16px;
              "
            >
              <el-skeleton-item variant="text" style="margin-right: 16px" />
              <el-skeleton-item variant="text" style="width: 30%" />
            </div>
          </div>
        </div>
      </template>
      <template #default>
        <el-card
          v-for="item in lists"
          :key="item.name"
          :body-style="{ padding: '0px', marginBottom: '1px' }"
        >
          <img
            :src="item.imgUrl"
            class="image multi-content"
            style="max-width: 100%"
          />
          <div style="padding: 14px">
            <span>{{ item.name }}</span>
            <div class="bottom card-header">
              <div class="time">{{ currentDate }}</div>
              <el-button text class="button">Operation button</el-button>
            </div>
          </div>
        </el-card>
      </template>
    </el-skeleton>
  </el-space>
</template>

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

interface ListItem {
  imgUrl: string
  name: string
}

const loading = ref(true)
const lists = ref<ListItem[]>([])
const currentDate = new Date().toDateString()

const setLoading = () => {
  loading.value = true
  setTimeout(() => {
    loading.value = false
  }, 2000)
}

onMounted(() => {
  loading.value = false
  lists.value = [
    {
      imgUrl:
        'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg',
      name: 'Deer',
    },
    {
      imgUrl:
        'https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg',
      name: 'Horse',
    },
    {
      imgUrl:
        'https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg',
      name: 'Mountain Lion',
    },
  ]
})
</script>
```

隐藏源代码

## 防止渲染抖动 [​](#防止渲染抖动)

有的时候，API 的请求回来的特别快，往往骨架占位刚刚被渲染，真实的数据就已经回来了，用户的界面会突然一闪， 此时为了避免这种情况，就需要通过 `throttle` 属性来避免这个问题。

TIP

2.8.8版本里， `throtle` 属性支持两个值： `number` 和 `object`。 当通过 `number`时，它相当于 `{leading: xxx}`，控制骨架屏幕显示的节奏。 当然，您也可以通过传递 `{trailing: xxx}` 来控制骨架屏消失的节奏。

Switch Loading

![](https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png)

Delicious hamburger

Wed Jun 24 2026

operation button

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2UgZGlyZWN0aW9uPVwidmVydGljYWxcIiBhbGlnbm1lbnQ9XCJmbGV4LXN0YXJ0XCI+XG4gICAgPGRpdj5cbiAgICAgIDxsYWJlbCBzdHlsZT1cIm1hcmdpbi1yaWdodDogMTZweFwiPlN3aXRjaCBMb2FkaW5nPC9sYWJlbD5cbiAgICAgIDxlbC1zd2l0Y2ggdi1tb2RlbD1cImxvYWRpbmdcIiAvPlxuICAgIDwvZGl2PlxuICAgIDxlbC1za2VsZXRvblxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgOmxvYWRpbmc9XCJsb2FkaW5nXCJcbiAgICAgIGFuaW1hdGVkXG4gICAgICA6dGhyb3R0bGU9XCI1MDBcIlxuICAgID5cbiAgICAgIDx0ZW1wbGF0ZSAjdGVtcGxhdGU+XG4gICAgICAgIDxlbC1za2VsZXRvbi1pdGVtIHZhcmlhbnQ9XCJpbWFnZVwiIHN0eWxlPVwid2lkdGg6IDI0MHB4OyBoZWlnaHQ6IDI2NXB4XCIgLz5cbiAgICAgICAgPGRpdiBzdHlsZT1cInBhZGRpbmc6IDE0cHhcIj5cbiAgICAgICAgICA8ZWwtc2tlbGV0b24taXRlbSB2YXJpYW50PVwiaDNcIiBzdHlsZT1cIndpZHRoOiA1MCVcIiAvPlxuICAgICAgICAgIDxkaXZcbiAgICAgICAgICAgIHN0eWxlPVwiXG4gICAgICAgICAgICAgIGRpc3BsYXk6IGZsZXg7XG4gICAgICAgICAgICAgIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG4gICAgICAgICAgICAgIGp1c3RpZnktaXRlbXM6IHNwYWNlLWJldHdlZW47XG4gICAgICAgICAgICAgIG1hcmdpbi10b3A6IDE2cHg7XG4gICAgICAgICAgICAgIGhlaWdodDogMTZweDtcbiAgICAgICAgICAgIFwiXG4gICAgICAgICAgPlxuICAgICAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cInRleHRcIiBzdHlsZT1cIm1hcmdpbi1yaWdodDogMTZweFwiIC8+XG4gICAgICAgICAgICA8ZWwtc2tlbGV0b24taXRlbSB2YXJpYW50PVwidGV4dFwiIHN0eWxlPVwid2lkdGg6IDMwJVwiIC8+XG4gICAgICAgICAgPC9kaXY+XG4gICAgICAgIDwvZGl2PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD5cbiAgICAgICAgPGVsLWNhcmQgOmJvZHktc3R5bGU9XCJ7IHBhZGRpbmc6ICcwcHgnLCBtYXJnaW5Cb3R0b206ICcxcHgnIH1cIj5cbiAgICAgICAgICA8aW1nXG4gICAgICAgICAgICBzcmM9XCJodHRwczovL3NoYWRvdy5lbGVtZWNkbi5jb20vYXBwL2VsZW1lbnQvaGFtYnVyZ2VyLjljZjdiMDkxLTU1ZTktMTFlOS1hOTc2LTdmNGQwYjA3ZWVmNi5wbmdcIlxuICAgICAgICAgICAgY2xhc3M9XCJpbWFnZVwiXG4gICAgICAgICAgLz5cbiAgICAgICAgICA8ZGl2IHN0eWxlPVwicGFkZGluZzogMTRweFwiPlxuICAgICAgICAgICAgPHNwYW4+RGVsaWNpb3VzIGhhbWJ1cmdlcjwvc3Bhbj5cbiAgICAgICAgICAgIDxkaXYgY2xhc3M9XCJib3R0b20gY2FyZC1oZWFkZXJcIj5cbiAgICAgICAgICAgICAgPGRpdiBjbGFzcz1cInRpbWVcIj57eyBjdXJyZW50RGF0ZSB9fTwvZGl2PlxuICAgICAgICAgICAgICA8ZWwtYnV0dG9uIHRleHQgY2xhc3M9XCJidXR0b25cIj5vcGVyYXRpb24gYnV0dG9uPC9lbC1idXR0b24+XG4gICAgICAgICAgICA8L2Rpdj5cbiAgICAgICAgICA8L2Rpdj5cbiAgICAgICAgPC9lbC1jYXJkPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLXNrZWxldG9uPlxuICA8L2VsLXNwYWNlPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgbG9hZGluZyA9IHJlZihmYWxzZSlcbmNvbnN0IGN1cnJlbnREYXRlID0gbmV3IERhdGUoKS50b0RhdGVTdHJpbmcoKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/skeleton/avoiding-rendering-bouncing.vue)_

vue

```
<template>
  <el-space direction="vertical" alignment="flex-start">
    <div>
      <label style="margin-right: 16px">Switch Loading</label>
      <el-switch v-model="loading" />
    </div>
    <el-skeleton
      style="width: 240px"
      :loading="loading"
      animated
      :throttle="500"
    >
      <template #template>
        <el-skeleton-item variant="image" style="width: 240px; height: 265px" />
        <div style="padding: 14px">
          <el-skeleton-item variant="h3" style="width: 50%" />
          <div
            style="
              display: flex;
              align-items: center;
              justify-items: space-between;
              margin-top: 16px;
              height: 16px;
            "
          >
            <el-skeleton-item variant="text" style="margin-right: 16px" />
            <el-skeleton-item variant="text" style="width: 30%" />
          </div>
        </div>
      </template>
      <template #default>
        <el-card :body-style="{ padding: '0px', marginBottom: '1px' }">
          <img
            src="https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png"
            class="image"
          />
          <div style="padding: 14px">
            <span>Delicious hamburger</span>
            <div class="bottom card-header">
              <div class="time">{{ currentDate }}</div>
              <el-button text class="button">operation button</el-button>
            </div>
          </div>
        </el-card>
      </template>
    </el-skeleton>
  </el-space>
</template>

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

const loading = ref(false)
const currentDate = new Date().toDateString()
</script>
```

隐藏源代码

## 初始渲染加载 2.8.8 [​](#初始渲染加载)

当初始值为 loading: true 时，您可以设置 `throttle: {initVal: true, leading: xxx}` 来控制初始骨架屏的即时显示，而无需进行节流。

Switch Loading

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2UgZGlyZWN0aW9uPVwidmVydGljYWxcIiBhbGlnbm1lbnQ9XCJmbGV4LXN0YXJ0XCI+XG4gICAgPGRpdj5cbiAgICAgIDxsYWJlbCBzdHlsZT1cIm1hcmdpbi1yaWdodDogMTZweFwiPlN3aXRjaCBMb2FkaW5nPC9sYWJlbD5cbiAgICAgIDxlbC1zd2l0Y2ggdi1tb2RlbD1cImxvYWRpbmdcIiAvPlxuICAgIDwvZGl2PlxuICAgIDxlbC1za2VsZXRvblxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgOmxvYWRpbmc9XCJsb2FkaW5nXCJcbiAgICAgIGFuaW1hdGVkXG4gICAgICA6dGhyb3R0bGU9XCJ7IGxlYWRpbmc6IDUwMCwgaW5pdFZhbDogdHJ1ZSB9XCJcbiAgICA+XG4gICAgICA8dGVtcGxhdGUgI3RlbXBsYXRlPlxuICAgICAgICA8ZWwtc2tlbGV0b24taXRlbSB2YXJpYW50PVwiaW1hZ2VcIiBzdHlsZT1cIndpZHRoOiAyNDBweDsgaGVpZ2h0OiAyNjVweFwiIC8+XG4gICAgICAgIDxkaXYgc3R5bGU9XCJwYWRkaW5nOiAxNHB4XCI+XG4gICAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cImgzXCIgc3R5bGU9XCJ3aWR0aDogNTAlXCIgLz5cbiAgICAgICAgICA8ZGl2XG4gICAgICAgICAgICBzdHlsZT1cIlxuICAgICAgICAgICAgICBkaXNwbGF5OiBmbGV4O1xuICAgICAgICAgICAgICBhbGlnbi1pdGVtczogY2VudGVyO1xuICAgICAgICAgICAgICBqdXN0aWZ5LWl0ZW1zOiBzcGFjZS1iZXR3ZWVuO1xuICAgICAgICAgICAgICBtYXJnaW4tdG9wOiAxNnB4O1xuICAgICAgICAgICAgICBoZWlnaHQ6IDE2cHg7XG4gICAgICAgICAgICBcIlxuICAgICAgICAgID5cbiAgICAgICAgICAgIDxlbC1za2VsZXRvbi1pdGVtIHZhcmlhbnQ9XCJ0ZXh0XCIgc3R5bGU9XCJtYXJnaW4tcmlnaHQ6IDE2cHhcIiAvPlxuICAgICAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cInRleHRcIiBzdHlsZT1cIndpZHRoOiAzMCVcIiAvPlxuICAgICAgICAgIDwvZGl2PlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ+XG4gICAgICAgIDxlbC1jYXJkIDpib2R5LXN0eWxlPVwieyBwYWRkaW5nOiAnMHB4JywgbWFyZ2luQm90dG9tOiAnMXB4JyB9XCI+XG4gICAgICAgICAgPGltZ1xuICAgICAgICAgICAgc3JjPVwiaHR0cHM6Ly9zaGFkb3cuZWxlbWVjZG4uY29tL2FwcC9lbGVtZW50L2hhbWJ1cmdlci45Y2Y3YjA5MS01NWU5LTExZTktYTk3Ni03ZjRkMGIwN2VlZjYucG5nXCJcbiAgICAgICAgICAgIGNsYXNzPVwiaW1hZ2VcIlxuICAgICAgICAgIC8+XG4gICAgICAgICAgPGRpdiBzdHlsZT1cInBhZGRpbmc6IDE0cHhcIj5cbiAgICAgICAgICAgIDxzcGFuPkRlbGljaW91cyBoYW1idXJnZXI8L3NwYW4+XG4gICAgICAgICAgICA8ZGl2IGNsYXNzPVwiYm90dG9tIGNhcmQtaGVhZGVyXCI+XG4gICAgICAgICAgICAgIDxkaXYgY2xhc3M9XCJ0aW1lXCI+e3sgY3VycmVudERhdGUgfX08L2Rpdj5cbiAgICAgICAgICAgICAgPGVsLWJ1dHRvbiB0ZXh0IGNsYXNzPVwiYnV0dG9uXCI+b3BlcmF0aW9uIGJ1dHRvbjwvZWwtYnV0dG9uPlxuICAgICAgICAgICAgPC9kaXY+XG4gICAgICAgICAgPC9kaXY+XG4gICAgICAgIDwvZWwtY2FyZD5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1za2VsZXRvbj5cbiAgPC9lbC1zcGFjZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGxvYWRpbmcgPSByZWYodHJ1ZSlcbmNvbnN0IGN1cnJlbnREYXRlID0gbmV3IERhdGUoKS50b0RhdGVTdHJpbmcoKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/skeleton/initial-rendering-loading.vue)_

vue

```
<template>
  <el-space direction="vertical" alignment="flex-start">
    <div>
      <label style="margin-right: 16px">Switch Loading</label>
      <el-switch v-model="loading" />
    </div>
    <el-skeleton
      style="width: 240px"
      :loading="loading"
      animated
      :throttle="{ leading: 500, initVal: true }"
    >
      <template #template>
        <el-skeleton-item variant="image" style="width: 240px; height: 265px" />
        <div style="padding: 14px">
          <el-skeleton-item variant="h3" style="width: 50%" />
          <div
            style="
              display: flex;
              align-items: center;
              justify-items: space-between;
              margin-top: 16px;
              height: 16px;
            "
          >
            <el-skeleton-item variant="text" style="margin-right: 16px" />
            <el-skeleton-item variant="text" style="width: 30%" />
          </div>
        </div>
      </template>
      <template #default>
        <el-card :body-style="{ padding: '0px', marginBottom: '1px' }">
          <img
            src="https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png"
            class="image"
          />
          <div style="padding: 14px">
            <span>Delicious hamburger</span>
            <div class="bottom card-header">
              <div class="time">{{ currentDate }}</div>
              <el-button text class="button">operation button</el-button>
            </div>
          </div>
        </el-card>
      </template>
    </el-skeleton>
  </el-space>
</template>

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

const loading = ref(true)
const currentDate = new Date().toDateString()
</script>
```

隐藏源代码

## 切换显示/隐藏时避免渲染抖动 2.8.8 [​](#切换显示-隐藏时避免渲染抖动)

TIP

您可以设置 `throttle: {initVal: true, leading: xxx, trailing: xxx}`，以控制骨架效果的初始显示，并使切换加载状态时骨架效果的过渡更加平滑。

有时，当加载状态切换显示或隐藏时，您可能希望业务组件的渲染更加平滑。 您可以设置 `throttle: {leading: xxx, trailing: xxx}` 来控制渲染抖动。

Switch Loading

![](https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png)

Delicious hamburger

Wed Jun 24 2026

operation button

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3BhY2UgZGlyZWN0aW9uPVwidmVydGljYWxcIiBhbGlnbm1lbnQ9XCJmbGV4LXN0YXJ0XCI+XG4gICAgPGRpdj5cbiAgICAgIDxsYWJlbCBzdHlsZT1cIm1hcmdpbi1yaWdodDogMTZweFwiPlN3aXRjaCBMb2FkaW5nPC9sYWJlbD5cbiAgICAgIDxlbC1zd2l0Y2ggdi1tb2RlbD1cImxvYWRpbmdcIiAvPlxuICAgIDwvZGl2PlxuICAgIDxlbC1za2VsZXRvblxuICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgOmxvYWRpbmc9XCJsb2FkaW5nXCJcbiAgICAgIGFuaW1hdGVkXG4gICAgICA6dGhyb3R0bGU9XCJ7IGxlYWRpbmc6IDUwMCwgdHJhaWxpbmc6IDUwMCwgaW5pdFZhbDogdHJ1ZSB9XCJcbiAgICA+XG4gICAgICA8dGVtcGxhdGUgI3RlbXBsYXRlPlxuICAgICAgICA8ZWwtc2tlbGV0b24taXRlbSB2YXJpYW50PVwiaW1hZ2VcIiBzdHlsZT1cIndpZHRoOiAyNDBweDsgaGVpZ2h0OiAyNjVweFwiIC8+XG4gICAgICAgIDxkaXYgc3R5bGU9XCJwYWRkaW5nOiAxNHB4XCI+XG4gICAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cImgzXCIgc3R5bGU9XCJ3aWR0aDogNTAlXCIgLz5cbiAgICAgICAgICA8ZGl2XG4gICAgICAgICAgICBzdHlsZT1cIlxuICAgICAgICAgICAgICBkaXNwbGF5OiBmbGV4O1xuICAgICAgICAgICAgICBhbGlnbi1pdGVtczogY2VudGVyO1xuICAgICAgICAgICAgICBqdXN0aWZ5LWl0ZW1zOiBzcGFjZS1iZXR3ZWVuO1xuICAgICAgICAgICAgICBtYXJnaW4tdG9wOiAxNnB4O1xuICAgICAgICAgICAgICBoZWlnaHQ6IDE2cHg7XG4gICAgICAgICAgICBcIlxuICAgICAgICAgID5cbiAgICAgICAgICAgIDxlbC1za2VsZXRvbi1pdGVtIHZhcmlhbnQ9XCJ0ZXh0XCIgc3R5bGU9XCJtYXJnaW4tcmlnaHQ6IDE2cHhcIiAvPlxuICAgICAgICAgICAgPGVsLXNrZWxldG9uLWl0ZW0gdmFyaWFudD1cInRleHRcIiBzdHlsZT1cIndpZHRoOiAzMCVcIiAvPlxuICAgICAgICAgIDwvZGl2PlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ+XG4gICAgICAgIDxlbC1jYXJkIDpib2R5LXN0eWxlPVwieyBwYWRkaW5nOiAnMHB4JywgbWFyZ2luQm90dG9tOiAnMXB4JyB9XCI+XG4gICAgICAgICAgPGltZ1xuICAgICAgICAgICAgc3JjPVwiaHR0cHM6Ly9zaGFkb3cuZWxlbWVjZG4uY29tL2FwcC9lbGVtZW50L2hhbWJ1cmdlci45Y2Y3YjA5MS01NWU5LTExZTktYTk3Ni03ZjRkMGIwN2VlZjYucG5nXCJcbiAgICAgICAgICAgIGNsYXNzPVwiaW1hZ2VcIlxuICAgICAgICAgIC8+XG4gICAgICAgICAgPGRpdiBzdHlsZT1cInBhZGRpbmc6IDE0cHhcIj5cbiAgICAgICAgICAgIDxzcGFuPkRlbGljaW91cyBoYW1idXJnZXI8L3NwYW4+XG4gICAgICAgICAgICA8ZGl2IGNsYXNzPVwiYm90dG9tIGNhcmQtaGVhZGVyXCI+XG4gICAgICAgICAgICAgIDxkaXYgY2xhc3M9XCJ0aW1lXCI+e3sgY3VycmVudERhdGUgfX08L2Rpdj5cbiAgICAgICAgICAgICAgPGVsLWJ1dHRvbiB0ZXh0IGNsYXNzPVwiYnV0dG9uXCI+b3BlcmF0aW9uIGJ1dHRvbjwvZWwtYnV0dG9uPlxuICAgICAgICAgICAgPC9kaXY+XG4gICAgICAgICAgPC9kaXY+XG4gICAgICAgIDwvZWwtY2FyZD5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1za2VsZXRvbj5cbiAgPC9lbC1zcGFjZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGxvYWRpbmcgPSByZWYoZmFsc2UpXG5jb25zdCBjdXJyZW50RGF0ZSA9IG5ldyBEYXRlKCkudG9EYXRlU3RyaW5nKClcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/skeleton/leading-trailing-without-bouncing.vue)_

vue

```
<template>
  <el-space direction="vertical" alignment="flex-start">
    <div>
      <label style="margin-right: 16px">Switch Loading</label>
      <el-switch v-model="loading" />
    </div>
    <el-skeleton
      style="width: 240px"
      :loading="loading"
      animated
      :throttle="{ leading: 500, trailing: 500, initVal: true }"
    >
      <template #template>
        <el-skeleton-item variant="image" style="width: 240px; height: 265px" />
        <div style="padding: 14px">
          <el-skeleton-item variant="h3" style="width: 50%" />
          <div
            style="
              display: flex;
              align-items: center;
              justify-items: space-between;
              margin-top: 16px;
              height: 16px;
            "
          >
            <el-skeleton-item variant="text" style="margin-right: 16px" />
            <el-skeleton-item variant="text" style="width: 30%" />
          </div>
        </div>
      </template>
      <template #default>
        <el-card :body-style="{ padding: '0px', marginBottom: '1px' }">
          <img
            src="https://shadow.elemecdn.com/app/element/hamburger.9cf7b091-55e9-11e9-a976-7f4d0b07eef6.png"
            class="image"
          />
          <div style="padding: 14px">
            <span>Delicious hamburger</span>
            <div class="bottom card-header">
              <div class="time">{{ currentDate }}</div>
              <el-button text class="button">operation button</el-button>
            </div>
          </div>
        </el-card>
      </template>
    </el-skeleton>
  </el-space>
</template>

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

const loading = ref(false)
const currentDate = new Date().toDateString()
</script>
```

隐藏源代码

## [​](#)

## Skeleton API [​](#skeleton-api)

### Skeleton Attributes [​](#skeleton-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| animated | 是否使用动画 | `boolean` | false |
| count | 渲染多少个 template, 建议使用尽可能小的数字 | `number` | 1 |
| loading | 是否显示加载结束后的 DOM 结构 | `boolean` | false |
| rows | 骨架屏段落数量 | `number` | 3 |
| throttle | 渲染延迟（以毫秒为单位） 数字代表延迟显示, 也可以设置为延迟隐藏, 例如 `{ leading: 500, trailing: 500 }` 当需要控制初始加载值时，您可以设置 `{ initVal: true }` | `number` / `object` | 0 |

### Skeleton Slots [​](#skeleton-slots)

| 插槽名 | 说明 | 事件参数 |
| --- | --- | --- |
| default | 真正渲染的DOM | `object` |
| template | 渲染 skeleton 模板的内容 | `object` |

## SkeletonItem API [​](#skeletonitem-api)

### SkeletonItem Attributes [​](#skeletonitem-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| variant | 当前渲染 skeleton 类型 | `enum` | text |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/skeleton) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/skeleton.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/skeleton.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/137589237?v=4&size=64)](https://github.com/zero-years)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/15872986?v=4&size=64)](https://github.com/chenweiyi)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/20543158?v=4&size=64)](https://github.com/porcelainHeart)[![](https://avatars.githubusercontent.com/u/65892539?v=4&size=64)](https://github.com/xionkq)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)

[Result 结果](https://element-plus.org/zh-CN/component/result)

[Table 表格](https://element-plus.org/zh-CN/component/table)




---
## [data/table] Table 表格
> 官方文档: https://element-plus.org/zh-CN/component/table.html

---

# Table 表格 [​](#table-表格)

更新日志待解决

228

用于展示多条结构类似的数据， 可对数据进行排序、筛选、对比或其他自定义操作。

## 基础表格 [​](#基础表格)

基础的表格展示用法。

当 `el-table` 元素中注入 `data` 对象数组后，在 `el-table-column` 中用 `prop` 属性来对应对象中的键名即可填入数据，用 `label` 属性来定义表格的列名。 可以使用 `width` 属性来定义列宽。

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_1_column_1" width="180"><col name="el-table_1_column_2" width="180"><col name="el-table_1_column_3" width="533"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCI+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIHdpZHRoPVwiMTgwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgd2lkdGg9XCIxODBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiAvPlxuICA8L2VsLXRhYmxlPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IHRhYmxlRGF0YSA9IFtcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAzJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAyJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA0JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/basic.vue)_

vue

```
<template>
  <el-table :data="tableData" style="width: 100%">
    <el-table-column prop="date" label="Date" width="180" />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" />
  </el-table>
</template>

<script lang="ts" setup>
const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## 带斑马纹表格 [​](#带斑马纹表格)

使用带斑马纹的表格，可以更容易区分出不同行的数据。

`stripe` 可以创建带斑马纹的表格。 如果 `true`, 表格将会带有斑马纹。

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_2_column_4" width="180"><col name="el-table_2_column_5" width="180"><col name="el-table_2_column_6" width="533"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_2_column_4 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_2_column_5 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_2_column_6 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row el-table__row--striped"><td colspan="1" rowspan="1" class="el-table_2_column_4 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_2_column_5 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_2_column_6 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_2_column_4 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_2_column_5 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_2_column_6 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row el-table__row--striped"><td colspan="1" rowspan="1" class="el-table_2_column_4 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_2_column_5 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_2_column_6 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBzdHJpcGUgc3R5bGU9XCJ3aWR0aDogMTAwJVwiPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImRhdGVcIiBsYWJlbD1cIkRhdGVcIiB3aWR0aD1cIjE4MFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIHdpZHRoPVwiMTgwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhZGRyZXNzXCIgbGFiZWw9XCJBZGRyZXNzXCIgLz5cbiAgPC9lbC10YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5jb25zdCB0YWJsZURhdGEgPSBbXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/striped.vue)_

vue

```
<template>
  <el-table :data="tableData" stripe style="width: 100%">
    <el-table-column prop="date" label="Date" width="180" />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" />
  </el-table>
</template>

<script lang="ts" setup>
const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## 带边框表格 [​](#带边框表格)

默认情况下，Table 组件是不具有竖直方向的边框的， 如果需要，可以使用 `border` 属性，把该属性设置为 `true` 即可启用。

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_3_column_7" width="180"><col name="el-table_3_column_8" width="180"><col name="el-table_3_column_9" width="533"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_3_column_7 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_3_column_8 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_3_column_9 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_3_column_7 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_3_column_8 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_3_column_9 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_3_column_7 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_3_column_8 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_3_column_9 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_3_column_7 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_3_column_8 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_3_column_9 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBib3JkZXIgc3R5bGU9XCJ3aWR0aDogMTAwJVwiPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImRhdGVcIiBsYWJlbD1cIkRhdGVcIiB3aWR0aD1cIjE4MFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIHdpZHRoPVwiMTgwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhZGRyZXNzXCIgbGFiZWw9XCJBZGRyZXNzXCIgLz5cbiAgPC9lbC10YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5jb25zdCB0YWJsZURhdGEgPSBbXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/with-border.vue)_

vue

```
<template>
  <el-table :data="tableData" border style="width: 100%">
    <el-table-column prop="date" label="Date" width="180" />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" />
  </el-table>
</template>

<script lang="ts" setup>
const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## 带状态表格 [​](#带状态表格)

可将表格内容 highlight 显示，方便区分「成功、信息、警告、危险」等内容。

可以通过指定 Table 组件的 `row-class-name` 属性来为 Table 中的某一行添加 class， 这样就可以自定义每一行的样式了。

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_4_column_10" width="180"><col name="el-table_4_column_11" width="180"><col name="el-table_4_column_12" width="533"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_4_column_10 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_4_column_11 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_4_column_12 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row warning-row"><td colspan="1" rowspan="1" class="el-table_4_column_10 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_4_column_11 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_4_column_12 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_4_column_10 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_4_column_11 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_4_column_12 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row success-row"><td colspan="1" rowspan="1" class="el-table_4_column_10 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_4_column_11 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_4_column_12 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGVcbiAgICA6ZGF0YT1cInRhYmxlRGF0YVwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMTAwJVwiXG4gICAgOnJvdy1jbGFzcy1uYW1lPVwidGFibGVSb3dDbGFzc05hbWVcIlxuICA+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIHdpZHRoPVwiMTgwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgd2lkdGg9XCIxODBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiAvPlxuICA8L2VsLXRhYmxlPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmludGVyZmFjZSBVc2VyIHtcbiAgZGF0ZTogc3RyaW5nXG4gIG5hbWU6IHN0cmluZ1xuICBhZGRyZXNzOiBzdHJpbmdcbn1cblxuY29uc3QgdGFibGVSb3dDbGFzc05hbWUgPSAoe1xuICByb3csXG4gIHJvd0luZGV4LFxufToge1xuICByb3c6IFVzZXJcbiAgcm93SW5kZXg6IG51bWJlclxufSkgPT4ge1xuICBpZiAocm93SW5kZXggPT09IDEpIHtcbiAgICByZXR1cm4gJ3dhcm5pbmctcm93J1xuICB9IGVsc2UgaWYgKHJvd0luZGV4ID09PSAzKSB7XG4gICAgcmV0dXJuICdzdWNjZXNzLXJvdydcbiAgfVxuICByZXR1cm4gJydcbn1cblxuY29uc3QgdGFibGVEYXRhOiBVc2VyW10gPSBbXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG5dXG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLmVsLXRhYmxlIC53YXJuaW5nLXJvdyB7XG4gIC0tZWwtdGFibGUtdHItYmctY29sb3I6IHZhcigtLWVsLWNvbG9yLXdhcm5pbmctbGlnaHQtOSk7XG59XG4uZWwtdGFibGUgLnN1Y2Nlc3Mtcm93IHtcbiAgLS1lbC10YWJsZS10ci1iZy1jb2xvcjogdmFyKC0tZWwtY29sb3Itc3VjY2Vzcy1saWdodC05KTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/with-status.vue)_

vue

```
<template>
  <el-table
    :data="tableData"
    style="width: 100%"
    :row-class-name="tableRowClassName"
  >
    <el-table-column prop="date" label="Date" width="180" />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" />
  </el-table>
</template>

<script lang="ts" setup>
interface User {
  date: string
  name: string
  address: string
}

const tableRowClassName = ({
  row,
  rowIndex,
}: {
  row: User
  rowIndex: number
}) => {
  if (rowIndex === 1) {
    return 'warning-row'
  } else if (rowIndex === 3) {
    return 'success-row'
  }
  return ''
}

const tableData: User[] = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>

<style>
.el-table .warning-row {
  --el-table-tr-bg-color: var(--el-color-warning-light-9);
}
.el-table .success-row {
  --el-table-tr-bg-color: var(--el-color-success-light-9);
}
</style>
```

隐藏源代码

## 显示溢出工具提示的表格 [​](#显示溢出工具提示的表格)

当内容太长时，它会分成多行。您可以使用 `show-overflow-tooltip` 将其保留在一行中。

属性 show-overflow-tooltip 接受一个布尔值。 为 `true` 时多余的内容会在 hover 时以 tooltip 的形式显示出来。

|
 |

Date

 |

Name

 |

use show-overflow-tooltip

 |

address

 |
| --- | --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_5_column_13" width="55"><col name="el-table_5_column_14" width="120"><col name="el-table_5_column_15" width="120"><col name="el-table_5_column_16" width="240"><col name="el-table_5_column_17" width="358"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_5_column_13 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-375"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-375"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_5_column_14 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_5_column_15 el-table__cell"><div class="cell">Aleyna Kutzner</div></td><td colspan="1" rowspan="1" class="el-table_5_column_16 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">Lohrbergstr. 86c, Süd Lilli, Saarland</div></td><td colspan="1" rowspan="1" class="el-table_5_column_17 el-table__cell"><div class="cell">Lohrbergstr. 86c, Süd Lilli, Saarland</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_5_column_13 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-376"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-376"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_5_column_14 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_5_column_15 el-table__cell"><div class="cell">Helen Jacobi</div></td><td colspan="1" rowspan="1" class="el-table_5_column_16 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">760 A Street, South Frankfield, Illinois</div></td><td colspan="1" rowspan="1" class="el-table_5_column_17 el-table__cell"><div class="cell">760 A Street, South Frankfield, Illinois</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_5_column_13 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-377"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-377"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_5_column_14 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_5_column_15 el-table__cell"><div class="cell">Brandon Deckert</div></td><td colspan="1" rowspan="1" class="el-table_5_column_16 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">Arnold-Ohletz-Str. 41a, Alt Malinascheid, Thüringen</div></td><td colspan="1" rowspan="1" class="el-table_5_column_17 el-table__cell"><div class="cell">Arnold-Ohletz-Str. 41a, Alt Malinascheid, Thüringen</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_5_column_13 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-378"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-378"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_5_column_14 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_5_column_15 el-table__cell"><div class="cell">Margie Smith</div></td><td colspan="1" rowspan="1" class="el-table_5_column_16 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">23618 Windsor Drive, West Ricardoview, Idaho</div></td><td colspan="1" rowspan="1" class="el-table_5_column_17 el-table__cell"><div class="cell">23618 Windsor Drive, West Ricardoview, Idaho</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCI+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiB0eXBlPVwic2VsZWN0aW9uXCIgd2lkdGg9XCI1NVwiIC8+XG4gICAgPCEtLSBAdnVlLWdlbmVyaWMge1VzZXJ9IC0tPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gbGFiZWw9XCJEYXRlXCIgd2lkdGg9XCIxMjBcIj5cbiAgICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD1cInNjb3BlXCI+e3sgc2NvcGUucm93LmRhdGUgfX08L3RlbXBsYXRlPlxuICAgIDwvZWwtdGFibGUtY29sdW1uPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcGVydHk9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgd2lkdGg9XCIxMjBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW5cbiAgICAgIHByb3BlcnR5PVwiYWRkcmVzc1wiXG4gICAgICBsYWJlbD1cInVzZSBzaG93LW92ZXJmbG93LXRvb2x0aXBcIlxuICAgICAgd2lkdGg9XCIyNDBcIlxuICAgICAgc2hvdy1vdmVyZmxvdy10b29sdGlwXG4gICAgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3BlcnR5PVwiYWRkcmVzc1wiIGxhYmVsPVwiYWRkcmVzc1wiIC8+XG4gIDwvZWwtdGFibGU+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW50ZXJmYWNlIFVzZXIge1xuICBkYXRlOiBzdHJpbmdcbiAgbmFtZTogc3RyaW5nXG4gIGFkZHJlc3M6IHN0cmluZ1xufVxuY29uc3QgdGFibGVEYXRhOiBVc2VyW10gPSBbXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ0FsZXluYSBLdXR6bmVyJyxcbiAgICBhZGRyZXNzOiAnTG9ocmJlcmdzdHIuIDg2YywgU8O8ZCBMaWxsaSwgU2FhcmxhbmQnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDMnLFxuICAgIG5hbWU6ICdIZWxlbiBKYWNvYmknLFxuICAgIGFkZHJlc3M6ICc3NjAgQSBTdHJlZXQsIFNvdXRoIEZyYW5rZmllbGQsIElsbGlub2lzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAyJyxcbiAgICBuYW1lOiAnQnJhbmRvbiBEZWNrZXJ0JyxcbiAgICBhZGRyZXNzOiAnQXJub2xkLU9obGV0ei1TdHIuIDQxYSwgQWx0IE1hbGluYXNjaGVpZCwgVGjDvHJpbmdlbicsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgbmFtZTogJ01hcmdpZSBTbWl0aCcsXG4gICAgYWRkcmVzczogJzIzNjE4IFdpbmRzb3IgRHJpdmUsIFdlc3QgUmljYXJkb3ZpZXcsIElkYWhvJyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/show-overflow-tooltip.vue)_

vue

```
<template>
  <el-table :data="tableData" style="width: 100%">
    <el-table-column type="selection" width="55" />
    <!-- @vue-generic {User} -->
    <el-table-column label="Date" width="120">
      <template #default="scope">{{ scope.row.date }}</template>
    </el-table-column>
    <el-table-column property="name" label="Name" width="120" />
    <el-table-column
      property="address"
      label="use show-overflow-tooltip"
      width="240"
      show-overflow-tooltip
    />
    <el-table-column property="address" label="address" />
  </el-table>
</template>

<script lang="ts" setup>
interface User {
  date: string
  name: string
  address: string
}
const tableData: User[] = [
  {
    date: '2016-05-04',
    name: 'Aleyna Kutzner',
    address: 'Lohrbergstr. 86c, Süd Lilli, Saarland',
  },
  {
    date: '2016-05-03',
    name: 'Helen Jacobi',
    address: '760 A Street, South Frankfield, Illinois',
  },
  {
    date: '2016-05-02',
    name: 'Brandon Deckert',
    address: 'Arnold-Ohletz-Str. 41a, Alt Malinascheid, Thüringen',
  },
  {
    date: '2016-05-01',
    name: 'Margie Smith',
    address: '23618 Windsor Drive, West Ricardoview, Idaho',
  },
]
</script>
```

隐藏源代码

## 固定表头 [​](#固定表头)

纵向内容过多时，可选择固定表头。

只要在 `el-table` 元素中定义了 `height` 属性，即可实现固定表头的表格，而不需要额外的代码。

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_6_column_18" width="180"><col name="el-table_6_column_19" width="180"><col name="el-table_6_column_20" width="533"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_6_column_18 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_6_column_19 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_6_column_20 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_6_column_18 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_6_column_19 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_6_column_20 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_6_column_18 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_6_column_19 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_6_column_20 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_6_column_18 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_6_column_19 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_6_column_20 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_6_column_18 el-table__cell"><div class="cell">2016-05-08</div></td><td colspan="1" rowspan="1" class="el-table_6_column_19 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_6_column_20 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_6_column_18 el-table__cell"><div class="cell">2016-05-06</div></td><td colspan="1" rowspan="1" class="el-table_6_column_19 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_6_column_20 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_6_column_18 el-table__cell"><div class="cell">2016-05-07</div></td><td colspan="1" rowspan="1" class="el-table_6_column_19 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_6_column_20 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBoZWlnaHQ9XCIyNTBcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCI+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIHdpZHRoPVwiMTgwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgd2lkdGg9XCIxODBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiAvPlxuICA8L2VsLXRhYmxlPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IHRhYmxlRGF0YSA9IFtcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAzJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAyJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA0JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA4JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA2JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA3JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/fixed-header.vue)_

vue

```
<template>
  <el-table :data="tableData" height="250" style="width: 100%">
    <el-table-column prop="date" label="Date" width="180" />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" />
  </el-table>
</template>

<script lang="ts" setup>
const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-08',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-06',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-07',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## 固定列 [​](#固定列)

横向内容过多时，可选择固定列。

固定列需要使用 `fixed` 属性，它接受 `Boolean` 值。 如果为 `true`, 列将被左侧固定. 它还接受传入字符串，left 或 right，表示左边固定还是右边固定。

|
Date

 |

Name

 |

State

 |

City

 |

Address

 |

Zip

 |

Operations

 |
| --- | --- | --- | --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 1350px;"><colgroup><col name="el-table_7_column_21" width="150"><col name="el-table_7_column_22" width="120"><col name="el-table_7_column_23" width="120"><col name="el-table_7_column_24" width="120"><col name="el-table_7_column_25" width="600"><col name="el-table_7_column_26" width="120"><col name="el-table_7_column_27" width="120"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_7_column_21 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_7_column_22 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_7_column_23 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_7_column_24 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_7_column_25 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_7_column_26 el-table__cell"><div class="cell">CA 90036</div></td><td colspan="1" rowspan="1" class="el-table_7_column_27 el-table-fixed-column--right is-first-column el-table__cell" style="right: 0px;"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--primary el-button--small is-link"><span class="">Detail </span></button><button aria-disabled="false" type="button" class="el-button el-button--primary el-button--small is-link"><span class="">Edit</span></button></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_7_column_21 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_7_column_22 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_7_column_23 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_7_column_24 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_7_column_25 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_7_column_26 el-table__cell"><div class="cell">CA 90036</div></td><td colspan="1" rowspan="1" class="el-table_7_column_27 el-table-fixed-column--right is-first-column el-table__cell" style="right: 0px;"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--primary el-button--small is-link"><span class="">Detail </span></button><button aria-disabled="false" type="button" class="el-button el-button--primary el-button--small is-link"><span class="">Edit</span></button></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_7_column_21 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_7_column_22 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_7_column_23 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_7_column_24 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_7_column_25 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_7_column_26 el-table__cell"><div class="cell">CA 90036</div></td><td colspan="1" rowspan="1" class="el-table_7_column_27 el-table-fixed-column--right is-first-column el-table__cell" style="right: 0px;"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--primary el-button--small is-link"><span class="">Detail </span></button><button aria-disabled="false" type="button" class="el-button el-button--primary el-button--small is-link"><span class="">Edit</span></button></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_7_column_21 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_7_column_22 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_7_column_23 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_7_column_24 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_7_column_25 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_7_column_26 el-table__cell"><div class="cell">CA 90036</div></td><td colspan="1" rowspan="1" class="el-table_7_column_27 el-table-fixed-column--right is-first-column el-table__cell" style="right: 0px;"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--primary el-button--small is-link"><span class="">Detail </span></button><button aria-disabled="false" type="button" class="el-button el-button--primary el-button--small is-link"><span class="">Edit</span></button></div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCI+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBmaXhlZCBwcm9wPVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIHdpZHRoPVwiMTUwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgd2lkdGg9XCIxMjBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cInN0YXRlXCIgbGFiZWw9XCJTdGF0ZVwiIHdpZHRoPVwiMTIwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJjaXR5XCIgbGFiZWw9XCJDaXR5XCIgd2lkdGg9XCIxMjBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiB3aWR0aD1cIjYwMFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiemlwXCIgbGFiZWw9XCJaaXBcIiB3aWR0aD1cIjEyMFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBmaXhlZD1cInJpZ2h0XCIgbGFiZWw9XCJPcGVyYXRpb25zXCIgbWluLXdpZHRoPVwiMTIwXCI+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ+XG4gICAgICAgIDxlbC1idXR0b24gbGluayB0eXBlPVwicHJpbWFyeVwiIHNpemU9XCJzbWFsbFwiIEBjbGljaz1cImhhbmRsZUNsaWNrXCI+XG4gICAgICAgICAgRGV0YWlsXG4gICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgICA8ZWwtYnV0dG9uIGxpbmsgdHlwZT1cInByaW1hcnlcIiBzaXplPVwic21hbGxcIj5FZGl0PC9lbC1idXR0b24+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtdGFibGUtY29sdW1uPlxuICA8L2VsLXRhYmxlPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IGhhbmRsZUNsaWNrID0gKCkgPT4ge1xuICBjb25zb2xlLmxvZygnY2xpY2snKVxufVxuXG5jb25zdCB0YWJsZURhdGEgPSBbXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgICB0YWc6ICdIb21lJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAyJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdMb3MgQW5nZWxlcycsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgemlwOiAnQ0EgOTAwMzYnLFxuICAgIHRhZzogJ09mZmljZScsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgICB0YWc6ICdIb21lJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdMb3MgQW5nZWxlcycsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgemlwOiAnQ0EgOTAwMzYnLFxuICAgIHRhZzogJ09mZmljZScsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/fixed-column.vue)_

vue

```
<template>
  <el-table :data="tableData" style="width: 100%">
    <el-table-column fixed prop="date" label="Date" width="150" />
    <el-table-column prop="name" label="Name" width="120" />
    <el-table-column prop="state" label="State" width="120" />
    <el-table-column prop="city" label="City" width="120" />
    <el-table-column prop="address" label="Address" width="600" />
    <el-table-column prop="zip" label="Zip" width="120" />
    <el-table-column fixed="right" label="Operations" min-width="120">
      <template #default>
        <el-button link type="primary" size="small" @click="handleClick">
          Detail
        </el-button>
        <el-button link type="primary" size="small">Edit</el-button>
      </template>
    </el-table-column>
  </el-table>
</template>

<script lang="ts" setup>
const handleClick = () => {
  console.log('click')
}

const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    tag: 'Home',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    tag: 'Office',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    tag: 'Home',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    tag: 'Office',
  },
]
</script>
```

隐藏源代码

## 固定列和表头 [​](#固定列和表头)

当您有大量数据块放入表中，您可以同时固定表头和列。

固定列和表头可以同时使用，只需要将上述两个属性分别设置好即可。

|
Date

 |

Name

 |

State

 |

City

 |

Address

 |

Zip

 |
| --- | --- | --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 1390px;"><colgroup><col name="el-table_8_column_28" width="150"><col name="el-table_8_column_29" width="120"><col name="el-table_8_column_30" width="120"><col name="el-table_8_column_31" width="320"><col name="el-table_8_column_32" width="600"><col name="el-table_8_column_33" width="80"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_8_column_28 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_8_column_29 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_8_column_30 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_8_column_31 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_32 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_33 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_8_column_28 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_8_column_29 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_8_column_30 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_8_column_31 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_32 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_33 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_8_column_28 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_8_column_29 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_8_column_30 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_8_column_31 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_32 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_33 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_8_column_28 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_8_column_29 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_8_column_30 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_8_column_31 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_32 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_33 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_8_column_28 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-08</div></td><td colspan="1" rowspan="1" class="el-table_8_column_29 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_8_column_30 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_8_column_31 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_32 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_33 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_8_column_28 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-06</div></td><td colspan="1" rowspan="1" class="el-table_8_column_29 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_8_column_30 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_8_column_31 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_32 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_33 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_8_column_28 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-07</div></td><td colspan="1" rowspan="1" class="el-table_8_column_29 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_8_column_30 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_8_column_31 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_32 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_8_column_33 el-table__cell"><div class="cell">CA 90036</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCIgaGVpZ2h0PVwiMjUwXCI+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBmaXhlZCBwcm9wPVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIHdpZHRoPVwiMTUwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgd2lkdGg9XCIxMjBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cInN0YXRlXCIgbGFiZWw9XCJTdGF0ZVwiIHdpZHRoPVwiMTIwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJjaXR5XCIgbGFiZWw9XCJDaXR5XCIgd2lkdGg9XCIzMjBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiB3aWR0aD1cIjYwMFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiemlwXCIgbGFiZWw9XCJaaXBcIiAvPlxuICA8L2VsLXRhYmxlPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IHRhYmxlRGF0YSA9IFtcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAzJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdMb3MgQW5nZWxlcycsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgemlwOiAnQ0EgOTAwMzYnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDInLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgY2l0eTogJ0xvcyBBbmdlbGVzJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICB6aXA6ICdDQSA5MDAzNicsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdMb3MgQW5nZWxlcycsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgemlwOiAnQ0EgOTAwMzYnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDgnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgY2l0eTogJ0xvcyBBbmdlbGVzJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICB6aXA6ICdDQSA5MDAzNicsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA3JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdMb3MgQW5nZWxlcycsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgemlwOiAnQ0EgOTAwMzYnLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/fixed-column-and-header.vue)_

vue

```
<template>
  <el-table :data="tableData" style="width: 100%" height="250">
    <el-table-column fixed prop="date" label="Date" width="150" />
    <el-table-column prop="name" label="Name" width="120" />
    <el-table-column prop="state" label="State" width="120" />
    <el-table-column prop="city" label="City" width="320" />
    <el-table-column prop="address" label="Address" width="600" />
    <el-table-column prop="zip" label="Zip" />
  </el-table>
</template>

<script lang="ts" setup>
const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-08',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-06',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-07',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
]
</script>
```

隐藏源代码

## 流体高度 [​](#流体高度)

当数据量动态变化时，可以为 Table 设置一个最大高度。

通过设置 `max-height` 属性为 `el-table` 指定最大高度。 此时若表格所需的高度大于最大高度，则会显示一个滚动条。

|
Date

 |

Name

 |

State

 |

City

 |

Address

 |

Zip

 |

Operations

 |
| --- | --- | --- | --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 1350px;"><colgroup><col name="el-table_9_column_34" width="150"><col name="el-table_9_column_35" width="120"><col name="el-table_9_column_36" width="120"><col name="el-table_9_column_37" width="120"><col name="el-table_9_column_38" width="600"><col name="el-table_9_column_39" width="120"><col name="el-table_9_column_40" width="120"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_9_column_34 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_9_column_35 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_9_column_36 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_9_column_37 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_9_column_38 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_9_column_39 el-table__cell"><div class="cell">CA 90036</div></td><td colspan="1" rowspan="1" class="el-table_9_column_40 el-table-fixed-column--right is-first-column el-table__cell" style="right: 0px;"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--primary el-button--small is-link"><span class="">Remove</span></button></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_9_column_34 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_9_column_35 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_9_column_36 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_9_column_37 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_9_column_38 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_9_column_39 el-table__cell"><div class="cell">CA 90036</div></td><td colspan="1" rowspan="1" class="el-table_9_column_40 el-table-fixed-column--right is-first-column el-table__cell" style="right: 0px;"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--primary el-button--small is-link"><span class="">Remove</span></button></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_9_column_34 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_9_column_35 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_9_column_36 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_9_column_37 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_9_column_38 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_9_column_39 el-table__cell"><div class="cell">CA 90036</div></td><td colspan="1" rowspan="1" class="el-table_9_column_40 el-table-fixed-column--right is-first-column el-table__cell" style="right: 0px;"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--primary el-button--small is-link"><span class="">Remove</span></button></div></td></tr></tbody></table>

Add Item

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCIgbWF4LWhlaWdodD1cIjI1MFwiPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gZml4ZWQgcHJvcD1cImRhdGVcIiBsYWJlbD1cIkRhdGVcIiB3aWR0aD1cIjE1MFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIHdpZHRoPVwiMTIwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJzdGF0ZVwiIGxhYmVsPVwiU3RhdGVcIiB3aWR0aD1cIjEyMFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiY2l0eVwiIGxhYmVsPVwiQ2l0eVwiIHdpZHRoPVwiMTIwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhZGRyZXNzXCIgbGFiZWw9XCJBZGRyZXNzXCIgd2lkdGg9XCI2MDBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cInppcFwiIGxhYmVsPVwiWmlwXCIgd2lkdGg9XCIxMjBcIiAvPlxuICAgIDwhLS0gQHZ1ZS1nZW5lcmljIHtVbndyYXBSZWY8dHlwZW9mIHRhYmxlRGF0YT5bbnVtYmVyXX0gLS0+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBmaXhlZD1cInJpZ2h0XCIgbGFiZWw9XCJPcGVyYXRpb25zXCIgbWluLXdpZHRoPVwiMTIwXCI+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJzY29wZVwiPlxuICAgICAgICA8ZWwtYnV0dG9uXG4gICAgICAgICAgbGlua1xuICAgICAgICAgIHR5cGU9XCJwcmltYXJ5XCJcbiAgICAgICAgICBzaXplPVwic21hbGxcIlxuICAgICAgICAgIEBjbGljay5wcmV2ZW50PVwiZGVsZXRlUm93KHNjb3BlLiRpbmRleClcIlxuICAgICAgICA+XG4gICAgICAgICAgUmVtb3ZlXG4gICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLXRhYmxlLWNvbHVtbj5cbiAgPC9lbC10YWJsZT5cbiAgPGVsLWJ1dHRvbiBjbGFzcz1cIm10LTRcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCIgQGNsaWNrPVwib25BZGRJdGVtXCI+XG4gICAgQWRkIEl0ZW1cbiAgPC9lbC1idXR0b24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IGRheWpzIGZyb20gJ2RheWpzJ1xuXG5pbXBvcnQgdHlwZSB7IFVud3JhcFJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3Qgbm93ID0gbmV3IERhdGUoKVxuXG5jb25zdCB0YWJsZURhdGEgPSByZWYoW1xuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgY2l0eTogJ0xvcyBBbmdlbGVzJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICB6aXA6ICdDQSA5MDAzNicsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAzJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdMb3MgQW5nZWxlcycsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgemlwOiAnQ0EgOTAwMzYnLFxuICB9LFxuXSlcblxuY29uc3QgZGVsZXRlUm93ID0gKGluZGV4OiBudW1iZXIpID0+IHtcbiAgdGFibGVEYXRhLnZhbHVlLnNwbGljZShpbmRleCwgMSlcbn1cblxuY29uc3Qgb25BZGRJdGVtID0gKCkgPT4ge1xuICBub3cuc2V0RGF0ZShub3cuZ2V0RGF0ZSgpICsgMSlcbiAgdGFibGVEYXRhLnZhbHVlLnB1c2goe1xuICAgIGRhdGU6IGRheWpzKG5vdykuZm9ybWF0KCdZWVlZLU1NLUREJyksXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/fixed-header-with-fluid-header.vue)_

vue

```
<template>
  <el-table :data="tableData" style="width: 100%" max-height="250">
    <el-table-column fixed prop="date" label="Date" width="150" />
    <el-table-column prop="name" label="Name" width="120" />
    <el-table-column prop="state" label="State" width="120" />
    <el-table-column prop="city" label="City" width="120" />
    <el-table-column prop="address" label="Address" width="600" />
    <el-table-column prop="zip" label="Zip" width="120" />
    <!-- @vue-generic {UnwrapRef<typeof tableData>[number]} -->
    <el-table-column fixed="right" label="Operations" min-width="120">
      <template #default="scope">
        <el-button
          link
          type="primary"
          size="small"
          @click.prevent="deleteRow(scope.$index)"
        >
          Remove
        </el-button>
      </template>
    </el-table-column>
  </el-table>
  <el-button class="mt-4" style="width: 100%" @click="onAddItem">
    Add Item
  </el-button>
</template>

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

import type { UnwrapRef } from 'vue'

const now = new Date()

const tableData = ref([
  {
    date: '2016-05-01',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-03',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
])

const deleteRow = (index: number) => {
  tableData.value.splice(index, 1)
}

const onAddItem = () => {
  now.setDate(now.getDate() + 1)
  tableData.value.push({
    date: dayjs(now).format('YYYY-MM-DD'),
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  })
}
</script>
```

隐藏源代码

## 多级表头 [​](#多级表头)

数据结构比较复杂的时候，可使用多级表头来展现数据的层次关系。

只需要将el-table-column 放置于el-table-column 中，你可以实现组头。

|
Date

 |

Delivery Info

 |
| --- | --- |
|

Name

 |

Address Info

 |
| --- | --- |
|

State

 |

City

 |

Address

 |

Zip

 |
| --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_10_column_41" width="150"><col name="el-table_10_column_42_column_43" width="120"><col name="el-table_10_column_42_column_44_column_45" width="120"><col name="el-table_10_column_42_column_44_column_46" width="120"><col name="el-table_10_column_42_column_44_column_47" width="263"><col name="el-table_10_column_42_column_44_column_48" width="120"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_10_column_41 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_43 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_45 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_46 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_47 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_48 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_10_column_41 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_43 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_45 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_46 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_47 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_48 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_10_column_41 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_43 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_45 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_46 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_47 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_48 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_10_column_41 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_43 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_45 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_46 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_47 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_48 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_10_column_41 el-table__cell"><div class="cell">2016-05-08</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_43 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_45 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_46 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_47 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_48 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_10_column_41 el-table__cell"><div class="cell">2016-05-06</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_43 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_45 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_46 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_47 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_48 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_10_column_41 el-table__cell"><div class="cell">2016-05-07</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_43 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_45 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_46 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_47 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_10_column_42_column_44_column_48 el-table__cell"><div class="cell">CA 90036</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCI+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIHdpZHRoPVwiMTUwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIGxhYmVsPVwiRGVsaXZlcnkgSW5mb1wiPlxuICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIHdpZHRoPVwiMTIwXCIgLz5cbiAgICAgIDxlbC10YWJsZS1jb2x1bW4gbGFiZWw9XCJBZGRyZXNzIEluZm9cIj5cbiAgICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwic3RhdGVcIiBsYWJlbD1cIlN0YXRlXCIgd2lkdGg9XCIxMjBcIiAvPlxuICAgICAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJjaXR5XCIgbGFiZWw9XCJDaXR5XCIgd2lkdGg9XCIxMjBcIiAvPlxuICAgICAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhZGRyZXNzXCIgbGFiZWw9XCJBZGRyZXNzXCIgLz5cbiAgICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiemlwXCIgbGFiZWw9XCJaaXBcIiB3aWR0aD1cIjEyMFwiIC8+XG4gICAgICA8L2VsLXRhYmxlLWNvbHVtbj5cbiAgICA8L2VsLXRhYmxlLWNvbHVtbj5cbiAgPC9lbC10YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5jb25zdCB0YWJsZURhdGEgPSBbXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAyJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdMb3MgQW5nZWxlcycsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgemlwOiAnQ0EgOTAwMzYnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDQnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgY2l0eTogJ0xvcyBBbmdlbGVzJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICB6aXA6ICdDQSA5MDAzNicsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA4JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdMb3MgQW5nZWxlcycsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgemlwOiAnQ0EgOTAwMzYnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDYnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgY2l0eTogJ0xvcyBBbmdlbGVzJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICB6aXA6ICdDQSA5MDAzNicsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNycsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/grouping-header.vue)_

vue

```
<template>
  <el-table :data="tableData" style="width: 100%">
    <el-table-column prop="date" label="Date" width="150" />
    <el-table-column label="Delivery Info">
      <el-table-column prop="name" label="Name" width="120" />
      <el-table-column label="Address Info">
        <el-table-column prop="state" label="State" width="120" />
        <el-table-column prop="city" label="City" width="120" />
        <el-table-column prop="address" label="Address" />
        <el-table-column prop="zip" label="Zip" width="120" />
      </el-table-column>
    </el-table-column>
  </el-table>
</template>

<script lang="ts" setup>
const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-08',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-06',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-07',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
]
</script>
```

隐藏源代码

## 固定表头 [​](#固定表头-1)

支持固定群组头

组头的属性 `fixed` 由最外层 `el-table-column`决定

|
Date

 |

Name

 |

State

 |

City

 |

Address

 |

Zip

 |
| --- | --- | --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 1390px;"><colgroup><col name="el-table_11_column_49" width="150"><col name="el-table_11_column_50" width="120"><col name="el-table_11_column_51" width="120"><col name="el-table_11_column_52" width="320"><col name="el-table_11_column_53" width="600"><col name="el-table_11_column_54" width="80"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_11_column_49 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_11_column_50 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_11_column_51 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_11_column_52 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_53 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_54 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_11_column_49 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_11_column_50 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_11_column_51 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_11_column_52 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_53 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_54 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_11_column_49 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_11_column_50 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_11_column_51 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_11_column_52 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_53 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_54 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_11_column_49 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_11_column_50 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_11_column_51 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_11_column_52 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_53 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_54 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_11_column_49 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-08</div></td><td colspan="1" rowspan="1" class="el-table_11_column_50 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_11_column_51 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_11_column_52 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_53 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_54 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_11_column_49 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-06</div></td><td colspan="1" rowspan="1" class="el-table_11_column_50 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_11_column_51 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_11_column_52 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_53 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_54 el-table__cell"><div class="cell">CA 90036</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_11_column_49 el-table-fixed-column--left is-last-column el-table__cell" style="left: 0px;"><div class="cell">2016-05-07</div></td><td colspan="1" rowspan="1" class="el-table_11_column_50 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_11_column_51 el-table__cell"><div class="cell">California</div></td><td colspan="1" rowspan="1" class="el-table_11_column_52 el-table__cell"><div class="cell">Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_53 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_11_column_54 el-table__cell"><div class="cell">CA 90036</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCIgaGVpZ2h0PVwiMjUwXCI+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBmaXhlZCBwcm9wPVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIHdpZHRoPVwiMTUwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgd2lkdGg9XCIxMjBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cInN0YXRlXCIgbGFiZWw9XCJTdGF0ZVwiIHdpZHRoPVwiMTIwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJjaXR5XCIgbGFiZWw9XCJDaXR5XCIgd2lkdGg9XCIzMjBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiB3aWR0aD1cIjYwMFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiemlwXCIgbGFiZWw9XCJaaXBcIiAvPlxuICA8L2VsLXRhYmxlPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IHRhYmxlRGF0YSA9IFtcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAzJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdMb3MgQW5nZWxlcycsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgemlwOiAnQ0EgOTAwMzYnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDInLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgY2l0eTogJ0xvcyBBbmdlbGVzJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICB6aXA6ICdDQSA5MDAzNicsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdMb3MgQW5nZWxlcycsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgemlwOiAnQ0EgOTAwMzYnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDgnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgY2l0eTogJ0xvcyBBbmdlbGVzJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICB6aXA6ICdDQSA5MDAzNicsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA3JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdMb3MgQW5nZWxlcycsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgemlwOiAnQ0EgOTAwMzYnLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/fixed-column-and-header.vue)_

vue

```
<template>
  <el-table :data="tableData" style="width: 100%" height="250">
    <el-table-column fixed prop="date" label="Date" width="150" />
    <el-table-column prop="name" label="Name" width="120" />
    <el-table-column prop="state" label="State" width="120" />
    <el-table-column prop="city" label="City" width="320" />
    <el-table-column prop="address" label="Address" width="600" />
    <el-table-column prop="zip" label="Zip" />
  </el-table>
</template>

<script lang="ts" setup>
const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-08',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-06',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
  {
    date: '2016-05-07',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
  },
]
</script>
```

隐藏源代码

## 单选 [​](#单选)

选择单行数据时使用色块表示。

Table 组件提供了单选的支持， 只需要配置 `highlight-current-row` 属性即可实现单选。 之后由 `current-change` 事件来管理选中时触发的事件，它会传入 `currentRow`，`oldCurrentRow`。 如果需要显示索引，可以增加一列 `el-table-column`，设置 `type` 属性为 `index` 即可显示从 1 开始的索引号。

|
 |

Date

 |

Name

 |

Address

 |
| --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_12_column_55" width="50"><col name="el-table_12_column_56" width="120"><col name="el-table_12_column_57" width="120"><col name="el-table_12_column_58" width="603"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_12_column_55 el-table__cell"><div class="cell"><div>1</div></div></td><td colspan="1" rowspan="1" class="el-table_12_column_56 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_12_column_57 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_12_column_58 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_12_column_55 el-table__cell"><div class="cell"><div>2</div></div></td><td colspan="1" rowspan="1" class="el-table_12_column_56 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_12_column_57 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_12_column_58 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_12_column_55 el-table__cell"><div class="cell"><div>3</div></div></td><td colspan="1" rowspan="1" class="el-table_12_column_56 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_12_column_57 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_12_column_58 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_12_column_55 el-table__cell"><div class="cell"><div>4</div></div></td><td colspan="1" rowspan="1" class="el-table_12_column_56 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_12_column_57 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_12_column_58 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

Select second rowClear selection

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGVcbiAgICByZWY9XCJzaW5nbGVUYWJsZVJlZlwiXG4gICAgOmRhdGE9XCJ0YWJsZURhdGFcIlxuICAgIGhpZ2hsaWdodC1jdXJyZW50LXJvd1xuICAgIHN0eWxlPVwid2lkdGg6IDEwMCVcIlxuICAgIEBjdXJyZW50LWNoYW5nZT1cImhhbmRsZUN1cnJlbnRDaGFuZ2VcIlxuICA+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiB0eXBlPVwiaW5kZXhcIiB3aWR0aD1cIjUwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3BlcnR5PVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIHdpZHRoPVwiMTIwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3BlcnR5PVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIHdpZHRoPVwiMTIwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3BlcnR5PVwiYWRkcmVzc1wiIGxhYmVsPVwiQWRkcmVzc1wiIC8+XG4gIDwvZWwtdGFibGU+XG4gIDxkaXYgc3R5bGU9XCJtYXJnaW4tdG9wOiAyMHB4XCI+XG4gICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJzZXRDdXJyZW50KHRhYmxlRGF0YVsxXSlcIj5TZWxlY3Qgc2Vjb25kIHJvdzwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gQGNsaWNrPVwic2V0Q3VycmVudCgpXCI+Q2xlYXIgc2VsZWN0aW9uPC9lbC1idXR0b24+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBUYWJsZUluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbnRlcmZhY2UgVXNlciB7XG4gIGRhdGU6IHN0cmluZ1xuICBuYW1lOiBzdHJpbmdcbiAgYWRkcmVzczogc3RyaW5nXG59XG5cbmNvbnN0IGN1cnJlbnRSb3cgPSByZWYoKVxuY29uc3Qgc2luZ2xlVGFibGVSZWYgPSByZWY8VGFibGVJbnN0YW5jZT4oKVxuXG5jb25zdCBzZXRDdXJyZW50ID0gKHJvdz86IFVzZXIpID0+IHtcbiAgc2luZ2xlVGFibGVSZWYudmFsdWUhLnNldEN1cnJlbnRSb3cocm93KVxufVxuY29uc3QgaGFuZGxlQ3VycmVudENoYW5nZSA9ICh2YWw6IFVzZXIgfCBudWxsKSA9PiB7XG4gIGN1cnJlbnRSb3cudmFsdWUgPSB2YWxcbn1cbmNvbnN0IHRhYmxlRGF0YTogVXNlcltdID0gW1xuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDMnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDInLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDQnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/single-select.vue)_

vue

```
<template>
  <el-table
    ref="singleTableRef"
    :data="tableData"
    highlight-current-row
    style="width: 100%"
    @current-change="handleCurrentChange"
  >
    <el-table-column type="index" width="50" />
    <el-table-column property="date" label="Date" width="120" />
    <el-table-column property="name" label="Name" width="120" />
    <el-table-column property="address" label="Address" />
  </el-table>
  <div style="margin-top: 20px">
    <el-button @click="setCurrent(tableData[1])">Select second row</el-button>
    <el-button @click="setCurrent()">Clear selection</el-button>
  </div>
</template>

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

import type { TableInstance } from 'element-plus'

interface User {
  date: string
  name: string
  address: string
}

const currentRow = ref()
const singleTableRef = ref<TableInstance>()

const setCurrent = (row?: User) => {
  singleTableRef.value!.setCurrentRow(row)
}
const handleCurrentChange = (val: User | null) => {
  currentRow.value = val
}
const tableData: User[] = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## 多选 [​](#多选)

你也可以选择多行。

在2.8.3 之后， `toggleRowSelection` 支持第三个参数 `ignoreSelectable` 以确定是否忽略可选属性。

实现多选非常简单: 手动添加一个 `el-table-column`，设 `type` 属性为 `selection` 即可；

|
 |

Date

 |

Name

 |

Address

 |
| --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_13_column_59" width="55"><col name="el-table_13_column_60" width="120"><col name="el-table_13_column_61" width="120"><col name="el-table_13_column_62" width="598"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_13_column_59 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox is-disabled" aria-label="Select this row" for="el-id-1024-380"><span class="el-checkbox__input is-disabled"><input class="el-checkbox__original" type="checkbox" disabled="" id="el-id-1024-380"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_13_column_60 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_13_column_61 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_13_column_62 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_13_column_59 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox is-disabled" aria-label="Select this row" for="el-id-1024-381"><span class="el-checkbox__input is-disabled"><input class="el-checkbox__original" type="checkbox" disabled="" id="el-id-1024-381"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_13_column_60 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_13_column_61 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_13_column_62 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_13_column_59 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-382"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-382"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_13_column_60 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_13_column_61 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_13_column_62 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_13_column_59 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-383"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-383"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_13_column_60 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_13_column_61 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_13_column_62 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_13_column_59 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-384"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-384"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_13_column_60 el-table__cell"><div class="cell">2016-05-08</div></td><td colspan="1" rowspan="1" class="el-table_13_column_61 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_13_column_62 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_13_column_59 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-385"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-385"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_13_column_60 el-table__cell"><div class="cell">2016-05-06</div></td><td colspan="1" rowspan="1" class="el-table_13_column_61 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_13_column_62 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_13_column_59 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-386"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-386"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_13_column_60 el-table__cell"><div class="cell">2016-05-07</div></td><td colspan="1" rowspan="1" class="el-table_13_column_61 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_13_column_62 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

Toggle selection status of second and third rows Toggle selection status based on selectable Clear selection

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGVcbiAgICByZWY9XCJtdWx0aXBsZVRhYmxlUmVmXCJcbiAgICA6ZGF0YT1cInRhYmxlRGF0YVwiXG4gICAgcm93LWtleT1cImlkXCJcbiAgICBzdHlsZT1cIndpZHRoOiAxMDAlXCJcbiAgICBAc2VsZWN0aW9uLWNoYW5nZT1cImhhbmRsZVNlbGVjdGlvbkNoYW5nZVwiXG4gID5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHR5cGU9XCJzZWxlY3Rpb25cIiA6c2VsZWN0YWJsZT1cInNlbGVjdGFibGVcIiB3aWR0aD1cIjU1XCIgLz5cbiAgICA8IS0tIEB2dWUtZ2VuZXJpYyB7VXNlcn0gLS0+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBsYWJlbD1cIkRhdGVcIiB3aWR0aD1cIjEyMFwiPlxuICAgICAgPHRlbXBsYXRlICNkZWZhdWx0PVwic2NvcGVcIj57eyBzY29wZS5yb3cuZGF0ZSB9fTwvdGVtcGxhdGU+XG4gICAgPC9lbC10YWJsZS1jb2x1bW4+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wZXJ0eT1cIm5hbWVcIiBsYWJlbD1cIk5hbWVcIiB3aWR0aD1cIjEyMFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wZXJ0eT1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiAvPlxuICA8L2VsLXRhYmxlPlxuICA8ZGl2IHN0eWxlPVwibWFyZ2luLXRvcDogMjBweFwiPlxuICAgIDxlbC1idXR0b24gQGNsaWNrPVwidG9nZ2xlU2VsZWN0aW9uKFt0YWJsZURhdGFbMV0sIHRhYmxlRGF0YVsyXV0pXCI+XG4gICAgICBUb2dnbGUgc2VsZWN0aW9uIHN0YXR1cyBvZiBzZWNvbmQgYW5kIHRoaXJkIHJvd3NcbiAgICA8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIEBjbGljaz1cInRvZ2dsZVNlbGVjdGlvbihbdGFibGVEYXRhWzFdLCB0YWJsZURhdGFbMl1dLCBmYWxzZSlcIj5cbiAgICAgIFRvZ2dsZSBzZWxlY3Rpb24gc3RhdHVzIGJhc2VkIG9uIHNlbGVjdGFibGVcbiAgICA8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIEBjbGljaz1cInRvZ2dsZVNlbGVjdGlvbigpXCI+Q2xlYXIgc2VsZWN0aW9uPC9lbC1idXR0b24+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBUYWJsZUluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbnRlcmZhY2UgVXNlciB7XG4gIGlkOiBudW1iZXJcbiAgZGF0ZTogc3RyaW5nXG4gIG5hbWU6IHN0cmluZ1xuICBhZGRyZXNzOiBzdHJpbmdcbn1cblxuY29uc3QgbXVsdGlwbGVUYWJsZVJlZiA9IHJlZjxUYWJsZUluc3RhbmNlPigpXG5jb25zdCBtdWx0aXBsZVNlbGVjdGlvbiA9IHJlZjxVc2VyW10+KFtdKVxuXG5jb25zdCBzZWxlY3RhYmxlID0gKHJvdzogVXNlcikgPT4gIVsxLCAyXS5pbmNsdWRlcyhyb3cuaWQpXG5jb25zdCB0b2dnbGVTZWxlY3Rpb24gPSAocm93cz86IFVzZXJbXSwgaWdub3JlU2VsZWN0YWJsZT86IGJvb2xlYW4pID0+IHtcbiAgaWYgKHJvd3MpIHtcbiAgICByb3dzLmZvckVhY2goKHJvdykgPT4ge1xuICAgICAgbXVsdGlwbGVUYWJsZVJlZi52YWx1ZSEudG9nZ2xlUm93U2VsZWN0aW9uKFxuICAgICAgICByb3csXG4gICAgICAgIHVuZGVmaW5lZCxcbiAgICAgICAgaWdub3JlU2VsZWN0YWJsZVxuICAgICAgKVxuICAgIH0pXG4gIH0gZWxzZSB7XG4gICAgbXVsdGlwbGVUYWJsZVJlZi52YWx1ZSEuY2xlYXJTZWxlY3Rpb24oKVxuICB9XG59XG5jb25zdCBoYW5kbGVTZWxlY3Rpb25DaGFuZ2UgPSAodmFsOiBVc2VyW10pID0+IHtcbiAgbXVsdGlwbGVTZWxlY3Rpb24udmFsdWUgPSB2YWxcbn1cblxuY29uc3QgdGFibGVEYXRhOiBVc2VyW10gPSBbXG4gIHtcbiAgICBpZDogMSxcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBpZDogMixcbiAgICBkYXRlOiAnMjAxNi0wNS0wMicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBpZDogMyxcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBpZDogNCxcbiAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBpZDogNSxcbiAgICBkYXRlOiAnMjAxNi0wNS0wOCcsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBpZDogNixcbiAgICBkYXRlOiAnMjAxNi0wNS0wNicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBpZDogNyxcbiAgICBkYXRlOiAnMjAxNi0wNS0wNycsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/multi-select.vue)_

vue

```
<template>
  <el-table
    ref="multipleTableRef"
    :data="tableData"
    row-key="id"
    style="width: 100%"
    @selection-change="handleSelectionChange"
  >
    <el-table-column type="selection" :selectable="selectable" width="55" />
    <!-- @vue-generic {User} -->
    <el-table-column label="Date" width="120">
      <template #default="scope">{{ scope.row.date }}</template>
    </el-table-column>
    <el-table-column property="name" label="Name" width="120" />
    <el-table-column property="address" label="Address" />
  </el-table>
  <div style="margin-top: 20px">
    <el-button @click="toggleSelection([tableData[1], tableData[2]])">
      Toggle selection status of second and third rows
    </el-button>
    <el-button @click="toggleSelection([tableData[1], tableData[2]], false)">
      Toggle selection status based on selectable
    </el-button>
    <el-button @click="toggleSelection()">Clear selection</el-button>
  </div>
</template>

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

import type { TableInstance } from 'element-plus'

interface User {
  id: number
  date: string
  name: string
  address: string
}

const multipleTableRef = ref<TableInstance>()
const multipleSelection = ref<User[]>([])

const selectable = (row: User) => ![1, 2].includes(row.id)
const toggleSelection = (rows?: User[], ignoreSelectable?: boolean) => {
  if (rows) {
    rows.forEach((row) => {
      multipleTableRef.value!.toggleRowSelection(
        row,
        undefined,
        ignoreSelectable
      )
    })
  } else {
    multipleTableRef.value!.clearSelection()
  }
}
const handleSelectionChange = (val: User[]) => {
  multipleSelection.value = val
}

const tableData: User[] = [
  {
    id: 1,
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 2,
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 3,
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 4,
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 5,
    date: '2016-05-08',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 6,
    date: '2016-05-06',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 7,
    date: '2016-05-07',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## 排序 [​](#排序)

对表格进行排序，可快速查找或对比数据。

在列中设置 `sortable` 属性即可实现以该列为基准的排序， 接受一个 `Boolean`，默认为 `false`。 可以通过 Table 的 `default-sort` 属性设置默认的排序列和排序顺序。 可以使用 `sort-method` 或者 `sort-by` 使用自定义的排序规则。 如果需要后端排序，需将 `sortable` 设置为 `custom`，同时在 Table 上监听 `sort-change` 事件， 在事件回调中可以获取当前排序的字段名和排序顺序，从而向接口请求排序后的表格数据。 在本例中，我们还使用了 `formatter` 属性，它用于格式化指定列的值， 接受一个 `Function`，会传入两个参数：`row` 和 `column`， 可以根据自己的需求进行处理。

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_14_column_63" width="180"><col name="el-table_14_column_64" width="180"><col name="el-table_14_column_65" width="533"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_14_column_63 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_14_column_64 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_14_column_65 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_14_column_63 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_14_column_64 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_14_column_65 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_14_column_63 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_14_column_64 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_14_column_65 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_14_column_63 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_14_column_64 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_14_column_65 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGVcbiAgICA6ZGF0YT1cInRhYmxlRGF0YVwiXG4gICAgOmRlZmF1bHQtc29ydD1cInsgcHJvcDogJ2RhdGUnLCBvcmRlcjogJ2Rlc2NlbmRpbmcnIH1cIlxuICAgIHN0eWxlPVwid2lkdGg6IDEwMCVcIlxuICA+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIHNvcnRhYmxlIHdpZHRoPVwiMTgwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgd2lkdGg9XCIxODBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiA6Zm9ybWF0dGVyPVwiZm9ybWF0dGVyXCIgLz5cbiAgPC9lbC10YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgdHlwZSB7IFRhYmxlQ29sdW1uQ3R4IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbnRlcmZhY2UgVXNlciB7XG4gIGRhdGU6IHN0cmluZ1xuICBuYW1lOiBzdHJpbmdcbiAgYWRkcmVzczogc3RyaW5nXG59XG5cbmNvbnN0IGZvcm1hdHRlciA9IChyb3c6IFVzZXIsIGNvbHVtbjogVGFibGVDb2x1bW5DdHg8VXNlcj4pID0+IHtcbiAgcmV0dXJuIHJvdy5hZGRyZXNzXG59XG5cbmNvbnN0IHRhYmxlRGF0YTogVXNlcltdID0gW1xuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDMnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDInLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDQnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/sort.vue)_

vue

```
<template>
  <el-table
    :data="tableData"
    :default-sort="{ prop: 'date', order: 'descending' }"
    style="width: 100%"
  >
    <el-table-column prop="date" label="Date" sortable width="180" />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" :formatter="formatter" />
  </el-table>
</template>

<script lang="ts" setup>
import type { TableColumnCtx } from 'element-plus'

interface User {
  date: string
  name: string
  address: string
}

const formatter = (row: User, column: TableColumnCtx<User>) => {
  return row.address
}

const tableData: User[] = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## 筛选 [​](#筛选)

对表格进行筛选，可快速查找到自己想看的数据。

在列中设置 `filters` 和 `filter-method` 属性即可开启该列的筛选， filters 是一个数组，`filter-method` 是一个方法，它用于决定某些数据是否显示， 会传入三个参数：`value`, `row` 和 `column`。

reset date filterreset all filters

|
Date

 |

Name

 |

Address

 |

Tag

 |
| --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_15_column_66" width="180"><col name="el-table_15_column_67" width="180"><col name="el-table_15_column_68" width="433"><col name="el-table_15_column_69" width="100"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_15_column_66 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_15_column_67 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_15_column_68 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_15_column_69 el-table__cell"><div class="cell"><span class="el-tag el-tag--primary el-tag--light"><span class="el-tag__content">Home</span></span></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_15_column_66 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_15_column_67 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_15_column_68 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_15_column_69 el-table__cell"><div class="cell"><span class="el-tag el-tag--success el-tag--light"><span class="el-tag__content">Office</span></span></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_15_column_66 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_15_column_67 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_15_column_68 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_15_column_69 el-table__cell"><div class="cell"><span class="el-tag el-tag--primary el-tag--light"><span class="el-tag__content">Home</span></span></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_15_column_66 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_15_column_67 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_15_column_68 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td><td colspan="1" rowspan="1" class="el-table_15_column_69 el-table__cell"><div class="cell"><span class="el-tag el-tag--success el-tag--light"><span class="el-tag__content">Office</span></span></div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIEBjbGljaz1cInJlc2V0RGF0ZUZpbHRlclwiPnJlc2V0IGRhdGUgZmlsdGVyPC9lbC1idXR0b24+XG4gIDxlbC1idXR0b24gQGNsaWNrPVwiY2xlYXJGaWx0ZXJcIj5yZXNldCBhbGwgZmlsdGVyczwvZWwtYnV0dG9uPlxuICA8ZWwtdGFibGUgcmVmPVwidGFibGVSZWZcIiByb3cta2V5PVwiZGF0ZVwiIDpkYXRhPVwidGFibGVEYXRhXCIgc3R5bGU9XCJ3aWR0aDogMTAwJVwiPlxuICAgIDxlbC10YWJsZS1jb2x1bW5cbiAgICAgIHByb3A9XCJkYXRlXCJcbiAgICAgIGxhYmVsPVwiRGF0ZVwiXG4gICAgICBzb3J0YWJsZVxuICAgICAgd2lkdGg9XCIxODBcIlxuICAgICAgY29sdW1uLWtleT1cImRhdGVcIlxuICAgICAgOmZpbHRlcnM9XCJbXG4gICAgICAgIHsgdGV4dDogJzIwMTYtMDUtMDEnLCB2YWx1ZTogJzIwMTYtMDUtMDEnIH0sXG4gICAgICAgIHsgdGV4dDogJzIwMTYtMDUtMDInLCB2YWx1ZTogJzIwMTYtMDUtMDInIH0sXG4gICAgICAgIHsgdGV4dDogJzIwMTYtMDUtMDMnLCB2YWx1ZTogJzIwMTYtMDUtMDMnIH0sXG4gICAgICAgIHsgdGV4dDogJzIwMTYtMDUtMDQnLCB2YWx1ZTogJzIwMTYtMDUtMDQnIH0sXG4gICAgICBdXCJcbiAgICAgIDpmaWx0ZXItbWV0aG9kPVwiZmlsdGVySGFuZGxlclwiXG4gICAgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgd2lkdGg9XCIxODBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiA6Zm9ybWF0dGVyPVwiZm9ybWF0dGVyXCIgLz5cblxuICAgIDwhLS0gQHZ1ZS1nZW5lcmljIHtVc2VyfSAtLT5cbiAgICA8ZWwtdGFibGUtY29sdW1uXG4gICAgICBwcm9wPVwidGFnXCJcbiAgICAgIGxhYmVsPVwiVGFnXCJcbiAgICAgIHdpZHRoPVwiMTAwXCJcbiAgICAgIDpmaWx0ZXJzPVwiW1xuICAgICAgICB7IHRleHQ6ICdIb21lJywgdmFsdWU6ICdIb21lJyB9LFxuICAgICAgICB7IHRleHQ6ICdPZmZpY2UnLCB2YWx1ZTogJ09mZmljZScgfSxcbiAgICAgIF1cIlxuICAgICAgOmZpbHRlci1tZXRob2Q9XCJmaWx0ZXJUYWdcIlxuICAgICAgZmlsdGVyLXBsYWNlbWVudD1cImJvdHRvbS1lbmRcIlxuICAgID5cbiAgICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD1cInNjb3BlXCI+XG4gICAgICAgIDxlbC10YWdcbiAgICAgICAgICA6dHlwZT1cInNjb3BlLnJvdy50YWcgPT09ICdIb21lJyA/ICdwcmltYXJ5JyA6ICdzdWNjZXNzJ1wiXG4gICAgICAgICAgZGlzYWJsZS10cmFuc2l0aW9uc1xuICAgICAgICAgID57eyBzY29wZS5yb3cudGFnIH19PC9lbC10YWdcbiAgICAgICAgPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLXRhYmxlLWNvbHVtbj5cbiAgPC9lbC10YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgVGFibGVDb2x1bW5DdHgsIFRhYmxlSW5zdGFuY2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmludGVyZmFjZSBVc2VyIHtcbiAgZGF0ZTogc3RyaW5nXG4gIG5hbWU6IHN0cmluZ1xuICBhZGRyZXNzOiBzdHJpbmdcbiAgdGFnOiBzdHJpbmdcbn1cblxuY29uc3QgdGFibGVSZWYgPSByZWY8VGFibGVJbnN0YW5jZT4oKVxuXG5jb25zdCByZXNldERhdGVGaWx0ZXIgPSAoKSA9PiB7XG4gIHRhYmxlUmVmLnZhbHVlIS5jbGVhckZpbHRlcihbJ2RhdGUnXSlcbn1cbmNvbnN0IGNsZWFyRmlsdGVyID0gKCkgPT4ge1xuICB0YWJsZVJlZi52YWx1ZSEuY2xlYXJGaWx0ZXIoKVxufVxuY29uc3QgZm9ybWF0dGVyID0gKHJvdzogVXNlciwgY29sdW1uOiBUYWJsZUNvbHVtbkN0eDxVc2VyPikgPT4ge1xuICByZXR1cm4gcm93LmFkZHJlc3Ncbn1cbmNvbnN0IGZpbHRlclRhZyA9ICh2YWx1ZTogc3RyaW5nLCByb3c6IFVzZXIpID0+IHtcbiAgcmV0dXJuIHJvdy50YWcgPT09IHZhbHVlXG59XG5jb25zdCBmaWx0ZXJIYW5kbGVyID0gKFxuICB2YWx1ZTogc3RyaW5nLFxuICByb3c6IFVzZXIsXG4gIGNvbHVtbjogVGFibGVDb2x1bW5DdHg8VXNlcj5cbikgPT4ge1xuICBjb25zdCBwcm9wZXJ0eSA9IGNvbHVtblsncHJvcGVydHknXVxuICByZXR1cm4gcm93W3Byb3BlcnR5XSA9PT0gdmFsdWVcbn1cblxuY29uc3QgdGFibGVEYXRhOiBVc2VyW10gPSBbXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgdGFnOiAnSG9tZScsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgdGFnOiAnT2ZmaWNlJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA0JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICB0YWc6ICdIb21lJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICB0YWc6ICdPZmZpY2UnLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/filter.vue)_

vue

```
<template>
  <el-button @click="resetDateFilter">reset date filter</el-button>
  <el-button @click="clearFilter">reset all filters</el-button>
  <el-table ref="tableRef" row-key="date" :data="tableData" style="width: 100%">
    <el-table-column
      prop="date"
      label="Date"
      sortable
      width="180"
      column-key="date"
      :filters="[
        { text: '2016-05-01', value: '2016-05-01' },
        { text: '2016-05-02', value: '2016-05-02' },
        { text: '2016-05-03', value: '2016-05-03' },
        { text: '2016-05-04', value: '2016-05-04' },
      ]"
      :filter-method="filterHandler"
    />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" :formatter="formatter" />

    <!-- @vue-generic {User} -->
    <el-table-column
      prop="tag"
      label="Tag"
      width="100"
      :filters="[
        { text: 'Home', value: 'Home' },
        { text: 'Office', value: 'Office' },
      ]"
      :filter-method="filterTag"
      filter-placement="bottom-end"
    >
      <template #default="scope">
        <el-tag
          :type="scope.row.tag === 'Home' ? 'primary' : 'success'"
          disable-transitions
          >{{ scope.row.tag }}</el-tag
        >
      </template>
    </el-table-column>
  </el-table>
</template>

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

import type { TableColumnCtx, TableInstance } from 'element-plus'

interface User {
  date: string
  name: string
  address: string
  tag: string
}

const tableRef = ref<TableInstance>()

const resetDateFilter = () => {
  tableRef.value!.clearFilter(['date'])
}
const clearFilter = () => {
  tableRef.value!.clearFilter()
}
const formatter = (row: User, column: TableColumnCtx<User>) => {
  return row.address
}
const filterTag = (value: string, row: User) => {
  return row.tag === value
}
const filterHandler = (
  value: string,
  row: User,
  column: TableColumnCtx<User>
) => {
  const property = column['property']
  return row[property] === value
}

const tableData: User[] = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
    tag: 'Home',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
    tag: 'Office',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
    tag: 'Home',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
    tag: 'Office',
  },
]
</script>
```

隐藏源代码

## 自定义列模板 [​](#自定义列模板)

自定义列的显示内容，可组合其他组件使用。

通过 `slot` 可以获取到 row, column, $index 和 store（table 内部的状态管理）的数据，用法参考 demo。

|
Date

 |

Name

 |

Operations

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_16_column_70" width="180"><col name="el-table_16_column_71" width="180"><col name="el-table_16_column_72" width="533"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_16_column_70 el-table__cell"><div class="cell"><div style="display: flex; align-items: center;"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M512 896a320 320 0 1 0 0-640 320 320 0 0 0 0 640m0 64a384 384 0 1 1 0-768 384 384 0 0 1 0 768"></path><path fill="currentColor" d="M512 320a32 32 0 0 1 32 32l-.512 224a32 32 0 1 1-64 0L480 352a32 32 0 0 1 32-32"></path><path fill="currentColor" d="M448 576a64 64 0 1 0 128 0 64 64 0 1 0-128 0m96-448v128h-64V128h-96a32 32 0 0 1 0-64h256a32 32 0 1 1 0 64z"></path></svg></i><span style="margin-left: 10px;">2016-05-03</span></div></div></td><td colspan="1" rowspan="1" class="el-table_16_column_71 el-table__cell"><div class="cell"><span class="el-tag el-tag--primary el-tag--light el-tooltip__trigger"><span class="el-tag__content">Tom</span></span></div></td><td colspan="1" rowspan="1" class="el-table_16_column_72 el-table__cell"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--small"><span class="">Edit </span></button><button aria-disabled="false" type="button" class="el-button el-button--danger el-button--small"><span class="">Delete</span></button></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_16_column_70 el-table__cell"><div class="cell"><div style="display: flex; align-items: center;"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M512 896a320 320 0 1 0 0-640 320 320 0 0 0 0 640m0 64a384 384 0 1 1 0-768 384 384 0 0 1 0 768"></path><path fill="currentColor" d="M512 320a32 32 0 0 1 32 32l-.512 224a32 32 0 1 1-64 0L480 352a32 32 0 0 1 32-32"></path><path fill="currentColor" d="M448 576a64 64 0 1 0 128 0 64 64 0 1 0-128 0m96-448v128h-64V128h-96a32 32 0 0 1 0-64h256a32 32 0 1 1 0 64z"></path></svg></i><span style="margin-left: 10px;">2016-05-02</span></div></div></td><td colspan="1" rowspan="1" class="el-table_16_column_71 el-table__cell"><div class="cell"><span class="el-tag el-tag--primary el-tag--light el-tooltip__trigger"><span class="el-tag__content">Tom</span></span></div></td><td colspan="1" rowspan="1" class="el-table_16_column_72 el-table__cell"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--small"><span class="">Edit </span></button><button aria-disabled="false" type="button" class="el-button el-button--danger el-button--small"><span class="">Delete</span></button></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_16_column_70 el-table__cell"><div class="cell"><div style="display: flex; align-items: center;"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M512 896a320 320 0 1 0 0-640 320 320 0 0 0 0 640m0 64a384 384 0 1 1 0-768 384 384 0 0 1 0 768"></path><path fill="currentColor" d="M512 320a32 32 0 0 1 32 32l-.512 224a32 32 0 1 1-64 0L480 352a32 32 0 0 1 32-32"></path><path fill="currentColor" d="M448 576a64 64 0 1 0 128 0 64 64 0 1 0-128 0m96-448v128h-64V128h-96a32 32 0 0 1 0-64h256a32 32 0 1 1 0 64z"></path></svg></i><span style="margin-left: 10px;">2016-05-04</span></div></div></td><td colspan="1" rowspan="1" class="el-table_16_column_71 el-table__cell"><div class="cell"><span class="el-tag el-tag--primary el-tag--light el-tooltip__trigger"><span class="el-tag__content">Tom</span></span></div></td><td colspan="1" rowspan="1" class="el-table_16_column_72 el-table__cell"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--small"><span class="">Edit </span></button><button aria-disabled="false" type="button" class="el-button el-button--danger el-button--small"><span class="">Delete</span></button></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_16_column_70 el-table__cell"><div class="cell"><div style="display: flex; align-items: center;"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M512 896a320 320 0 1 0 0-640 320 320 0 0 0 0 640m0 64a384 384 0 1 1 0-768 384 384 0 0 1 0 768"></path><path fill="currentColor" d="M512 320a32 32 0 0 1 32 32l-.512 224a32 32 0 1 1-64 0L480 352a32 32 0 0 1 32-32"></path><path fill="currentColor" d="M448 576a64 64 0 1 0 128 0 64 64 0 1 0-128 0m96-448v128h-64V128h-96a32 32 0 0 1 0-64h256a32 32 0 1 1 0 64z"></path></svg></i><span style="margin-left: 10px;">2016-05-01</span></div></div></td><td colspan="1" rowspan="1" class="el-table_16_column_71 el-table__cell"><div class="cell"><span class="el-tag el-tag--primary el-tag--light el-tooltip__trigger"><span class="el-tag__content">Tom</span></span></div></td><td colspan="1" rowspan="1" class="el-table_16_column_72 el-table__cell"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--small"><span class="">Edit </span></button><button aria-disabled="false" type="button" class="el-button el-button--danger el-button--small"><span class="">Delete</span></button></div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCI+XG4gICAgPCEtLSBAdnVlLWdlbmVyaWMge1VzZXJ9IC0tPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gbGFiZWw9XCJEYXRlXCIgd2lkdGg9XCIxODBcIj5cbiAgICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD1cInNjb3BlXCI+XG4gICAgICAgIDxkaXYgc3R5bGU9XCJkaXNwbGF5OiBmbGV4OyBhbGlnbi1pdGVtczogY2VudGVyXCI+XG4gICAgICAgICAgPGVsLWljb24+PHRpbWVyIC8+PC9lbC1pY29uPlxuICAgICAgICAgIDxzcGFuIHN0eWxlPVwibWFyZ2luLWxlZnQ6IDEwcHhcIj57eyBzY29wZS5yb3cuZGF0ZSB9fTwvc3Bhbj5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtdGFibGUtY29sdW1uPlxuICAgIDwhLS0gQHZ1ZS1nZW5lcmljIHtVc2VyfSAtLT5cbiAgICA8ZWwtdGFibGUtY29sdW1uIGxhYmVsPVwiTmFtZVwiIHdpZHRoPVwiMTgwXCI+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJzY29wZVwiPlxuICAgICAgICA8ZWwtcG9wb3ZlciBlZmZlY3Q9XCJsaWdodFwiIHRyaWdnZXI9XCJob3ZlclwiIHBsYWNlbWVudD1cInRvcFwiIHdpZHRoPVwiYXV0b1wiPlxuICAgICAgICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD5cbiAgICAgICAgICAgIDxkaXY+bmFtZToge3sgc2NvcGUucm93Lm5hbWUgfX08L2Rpdj5cbiAgICAgICAgICAgIDxkaXY+YWRkcmVzczoge3sgc2NvcGUucm93LmFkZHJlc3MgfX08L2Rpdj5cbiAgICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICAgIDx0ZW1wbGF0ZSAjcmVmZXJlbmNlPlxuICAgICAgICAgICAgPGVsLXRhZz57eyBzY29wZS5yb3cubmFtZSB9fTwvZWwtdGFnPlxuICAgICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDwvZWwtcG9wb3Zlcj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC10YWJsZS1jb2x1bW4+XG4gICAgPCEtLSBAdnVlLWdlbmVyaWMge1VzZXJ9IC0tPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gbGFiZWw9XCJPcGVyYXRpb25zXCI+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJzY29wZVwiPlxuICAgICAgICA8ZWwtYnV0dG9uIHNpemU9XCJzbWFsbFwiIEBjbGljaz1cImhhbmRsZUVkaXQoc2NvcGUuJGluZGV4LCBzY29wZS5yb3cpXCI+XG4gICAgICAgICAgRWRpdFxuICAgICAgICA8L2VsLWJ1dHRvbj5cbiAgICAgICAgPGVsLWJ1dHRvblxuICAgICAgICAgIHNpemU9XCJzbWFsbFwiXG4gICAgICAgICAgdHlwZT1cImRhbmdlclwiXG4gICAgICAgICAgQGNsaWNrPVwiaGFuZGxlRGVsZXRlKHNjb3BlLiRpbmRleCwgc2NvcGUucm93KVwiXG4gICAgICAgID5cbiAgICAgICAgICBEZWxldGVcbiAgICAgICAgPC9lbC1idXR0b24+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtdGFibGUtY29sdW1uPlxuICA8L2VsLXRhYmxlPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IFRpbWVyIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmludGVyZmFjZSBVc2VyIHtcbiAgZGF0ZTogc3RyaW5nXG4gIG5hbWU6IHN0cmluZ1xuICBhZGRyZXNzOiBzdHJpbmdcbn1cblxuY29uc3QgaGFuZGxlRWRpdCA9IChpbmRleDogbnVtYmVyLCByb3c6IFVzZXIpID0+IHtcbiAgY29uc29sZS5sb2coaW5kZXgsIHJvdylcbn1cbmNvbnN0IGhhbmRsZURlbGV0ZSA9IChpbmRleDogbnVtYmVyLCByb3c6IFVzZXIpID0+IHtcbiAgY29uc29sZS5sb2coaW5kZXgsIHJvdylcbn1cblxuY29uc3QgdGFibGVEYXRhOiBVc2VyW10gPSBbXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/custom-column.vue)_

vue

```
<template>
  <el-table :data="tableData" style="width: 100%">
    <!-- @vue-generic {User} -->
    <el-table-column label="Date" width="180">
      <template #default="scope">
        <div style="display: flex; align-items: center">
          <el-icon><timer /></el-icon>
          <span style="margin-left: 10px">{{ scope.row.date }}</span>
        </div>
      </template>
    </el-table-column>
    <!-- @vue-generic {User} -->
    <el-table-column label="Name" width="180">
      <template #default="scope">
        <el-popover effect="light" trigger="hover" placement="top" width="auto">
          <template #default>
            <div>name: {{ scope.row.name }}</div>
            <div>address: {{ scope.row.address }}</div>
          </template>
          <template #reference>
            <el-tag>{{ scope.row.name }}</el-tag>
          </template>
        </el-popover>
      </template>
    </el-table-column>
    <!-- @vue-generic {User} -->
    <el-table-column label="Operations">
      <template #default="scope">
        <el-button size="small" @click="handleEdit(scope.$index, scope.row)">
          Edit
        </el-button>
        <el-button
          size="small"
          type="danger"
          @click="handleDelete(scope.$index, scope.row)"
        >
          Delete
        </el-button>
      </template>
    </el-table-column>
  </el-table>
</template>

<script lang="ts" setup>
import { Timer } from '@element-plus/icons-vue'

interface User {
  date: string
  name: string
  address: string
}

const handleEdit = (index: number, row: User) => {
  console.log(index, row)
}
const handleDelete = (index: number, row: User) => {
  console.log(index, row)
}

const tableData: User[] = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## 自定义表头 [​](#自定义表头)

表头支持自定义。

通过设置 [slot](https://v3.vuejs.org/guide/component-slots.html) 来自定义表头。

|
Date

 |

Name

 |

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_17_column_73" width="299"><col name="el-table_17_column_74" width="297"><col name="el-table_17_column_75" width="297"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_17_column_73 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_17_column_74 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_17_column_75 is-right el-table__cell"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--small"><span class="">Edit </span></button><button aria-disabled="false" type="button" class="el-button el-button--danger el-button--small"><span class="">Delete</span></button></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_17_column_73 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_17_column_74 el-table__cell"><div class="cell">John</div></td><td colspan="1" rowspan="1" class="el-table_17_column_75 is-right el-table__cell"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--small"><span class="">Edit </span></button><button aria-disabled="false" type="button" class="el-button el-button--danger el-button--small"><span class="">Delete</span></button></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_17_column_73 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_17_column_74 el-table__cell"><div class="cell">Morgan</div></td><td colspan="1" rowspan="1" class="el-table_17_column_75 is-right el-table__cell"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--small"><span class="">Edit </span></button><button aria-disabled="false" type="button" class="el-button el-button--danger el-button--small"><span class="">Delete</span></button></div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_17_column_73 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_17_column_74 el-table__cell"><div class="cell">Jessy</div></td><td colspan="1" rowspan="1" class="el-table_17_column_75 is-right el-table__cell"><div class="cell"><button aria-disabled="false" type="button" class="el-button el-button--small"><span class="">Edit </span></button><button aria-disabled="false" type="button" class="el-button el-button--danger el-button--small"><span class="">Delete</span></button></div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJmaWx0ZXJUYWJsZURhdGFcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCI+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBsYWJlbD1cIkRhdGVcIiBwcm9wPVwiZGF0ZVwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBsYWJlbD1cIk5hbWVcIiBwcm9wPVwibmFtZVwiIC8+XG4gICAgPCEtLSBAdnVlLWdlbmVyaWMge1VzZXJ9IC0tPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gYWxpZ249XCJyaWdodFwiPlxuICAgICAgPHRlbXBsYXRlICNoZWFkZXI+XG4gICAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwic2VhcmNoXCIgc2l6ZT1cInNtYWxsXCIgcGxhY2Vob2xkZXI9XCJUeXBlIHRvIHNlYXJjaFwiIC8+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgPHRlbXBsYXRlICNkZWZhdWx0PVwic2NvcGVcIj5cbiAgICAgICAgPGVsLWJ1dHRvbiBzaXplPVwic21hbGxcIiBAY2xpY2s9XCJoYW5kbGVFZGl0KHNjb3BlLiRpbmRleCwgc2NvcGUucm93KVwiPlxuICAgICAgICAgIEVkaXRcbiAgICAgICAgPC9lbC1idXR0b24+XG4gICAgICAgIDxlbC1idXR0b25cbiAgICAgICAgICBzaXplPVwic21hbGxcIlxuICAgICAgICAgIHR5cGU9XCJkYW5nZXJcIlxuICAgICAgICAgIEBjbGljaz1cImhhbmRsZURlbGV0ZShzY29wZS4kaW5kZXgsIHNjb3BlLnJvdylcIlxuICAgICAgICA+XG4gICAgICAgICAgRGVsZXRlXG4gICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLXRhYmxlLWNvbHVtbj5cbiAgPC9lbC10YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBjb21wdXRlZCwgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbnRlcmZhY2UgVXNlciB7XG4gIGRhdGU6IHN0cmluZ1xuICBuYW1lOiBzdHJpbmdcbiAgYWRkcmVzczogc3RyaW5nXG59XG5cbmNvbnN0IHNlYXJjaCA9IHJlZignJylcbmNvbnN0IGZpbHRlclRhYmxlRGF0YSA9IGNvbXB1dGVkKCgpID0+XG4gIHRhYmxlRGF0YS5maWx0ZXIoXG4gICAgKGRhdGEpID0+XG4gICAgICAhc2VhcmNoLnZhbHVlIHx8XG4gICAgICBkYXRhLm5hbWUudG9Mb3dlckNhc2UoKS5pbmNsdWRlcyhzZWFyY2gudmFsdWUudG9Mb3dlckNhc2UoKSlcbiAgKVxuKVxuY29uc3QgaGFuZGxlRWRpdCA9IChpbmRleDogbnVtYmVyLCByb3c6IFVzZXIpID0+IHtcbiAgY29uc29sZS5sb2coaW5kZXgsIHJvdylcbn1cbmNvbnN0IGhhbmRsZURlbGV0ZSA9IChpbmRleDogbnVtYmVyLCByb3c6IFVzZXIpID0+IHtcbiAgY29uc29sZS5sb2coaW5kZXgsIHJvdylcbn1cblxuY29uc3QgdGFibGVEYXRhOiBVc2VyW10gPSBbXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMicsXG4gICAgbmFtZTogJ0pvaG4nLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDQnLFxuICAgIG5hbWU6ICdNb3JnYW4nLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgIG5hbWU6ICdKZXNzeScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/custom-header.vue)_

vue

```
<template>
  <el-table :data="filterTableData" style="width: 100%">
    <el-table-column label="Date" prop="date" />
    <el-table-column label="Name" prop="name" />
    <!-- @vue-generic {User} -->
    <el-table-column align="right">
      <template #header>
        <el-input v-model="search" size="small" placeholder="Type to search" />
      </template>
      <template #default="scope">
        <el-button size="small" @click="handleEdit(scope.$index, scope.row)">
          Edit
        </el-button>
        <el-button
          size="small"
          type="danger"
          @click="handleDelete(scope.$index, scope.row)"
        >
          Delete
        </el-button>
      </template>
    </el-table-column>
  </el-table>
</template>

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

interface User {
  date: string
  name: string
  address: string
}

const search = ref('')
const filterTableData = computed(() =>
  tableData.filter(
    (data) =>
      !search.value ||
      data.name.toLowerCase().includes(search.value.toLowerCase())
  )
)
const handleEdit = (index: number, row: User) => {
  console.log(index, row)
}
const handleDelete = (index: number, row: User) => {
  console.log(index, row)
}

const tableData: User[] = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-02',
    name: 'John',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-04',
    name: 'Morgan',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-01',
    name: 'Jessy',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## 展开行 [​](#展开行)

当行内容过多并且不想显示横向滚动条时，可以使用 Table 展开行功能。

在 2.9.7 版本后，新增了 `preserve-expanded-content` 属性，用于控制折叠时是否在 DOM 中保留已展开的行内容。

通过设置 type="expand" 和 slot 可以开启展开行功能， el-table-column 的模板会被渲染成为展开行的内容，展开行可访问的属性与使用自定义列模板时的 slot 相同。

switch parent border:

switch child border:

preserve expanded:

|
 |

Date

 |

Name

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_18_column_76" width="48"><col name="el-table_18_column_77" width="423"><col name="el-table_18_column_78" width="422"></colgroup><tbody tabindex="-1"><tr class="el-table__row"><td colspan="1" rowspan="1" class="el-table_18_column_76 el-table__expand-column el-table__cell"><div class="cell"><button type="button" aria-label="Expand this row" aria-expanded="false" class="el-table__expand-icon"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M340.864 149.312a30.59 30.59 0 0 0 0 42.752L652.736 512 340.864 831.872a30.59 30.59 0 0 0 0 42.752 29.12 29.12 0 0 0 41.728 0L714.24 534.336a32 32 0 0 0 0-44.672L382.592 149.376a29.12 29.12 0 0 0-41.728 0z"></path></svg></i></button></div></td><td colspan="1" rowspan="1" class="el-table_18_column_77 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_18_column_78 el-table__cell"><div class="cell">Tom</div></td></tr><tr class="el-table__row"><td colspan="1" rowspan="1" class="el-table_18_column_76 el-table__expand-column el-table__cell"><div class="cell"><button type="button" aria-label="Expand this row" aria-expanded="false" class="el-table__expand-icon"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M340.864 149.312a30.59 30.59 0 0 0 0 42.752L652.736 512 340.864 831.872a30.59 30.59 0 0 0 0 42.752 29.12 29.12 0 0 0 41.728 0L714.24 534.336a32 32 0 0 0 0-44.672L382.592 149.376a29.12 29.12 0 0 0-41.728 0z"></path></svg></i></button></div></td><td colspan="1" rowspan="1" class="el-table_18_column_77 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_18_column_78 el-table__cell"><div class="cell">Tom</div></td></tr><tr class="el-table__row"><td colspan="1" rowspan="1" class="el-table_18_column_76 el-table__expand-column el-table__cell"><div class="cell"><button type="button" aria-label="Expand this row" aria-expanded="false" class="el-table__expand-icon"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M340.864 149.312a30.59 30.59 0 0 0 0 42.752L652.736 512 340.864 831.872a30.59 30.59 0 0 0 0 42.752 29.12 29.12 0 0 0 41.728 0L714.24 534.336a32 32 0 0 0 0-44.672L382.592 149.376a29.12 29.12 0 0 0-41.728 0z"></path></svg></i></button></div></td><td colspan="1" rowspan="1" class="el-table_18_column_77 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_18_column_78 el-table__cell"><div class="cell">Tom</div></td></tr><tr class="el-table__row"><td colspan="1" rowspan="1" class="el-table_18_column_76 el-table__expand-column el-table__cell"><div class="cell"><button type="button" aria-label="Expand this row" aria-expanded="false" class="el-table__expand-icon"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M340.864 149.312a30.59 30.59 0 0 0 0 42.752L652.736 512 340.864 831.872a30.59 30.59 0 0 0 0 42.752 29.12 29.12 0 0 0 41.728 0L714.24 534.336a32 32 0 0 0 0-44.672L382.592 149.376a29.12 29.12 0 0 0-41.728 0z"></path></svg></i></button></div></td><td colspan="1" rowspan="1" class="el-table_18_column_77 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_18_column_78 el-table__cell"><div class="cell">Tom</div></td></tr><tr class="el-table__row"><td colspan="1" rowspan="1" class="el-table_18_column_76 el-table__expand-column el-table__cell"><div class="cell"><button type="button" aria-label="Expand this row" aria-expanded="false" class="el-table__expand-icon"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M340.864 149.312a30.59 30.59 0 0 0 0 42.752L652.736 512 340.864 831.872a30.59 30.59 0 0 0 0 42.752 29.12 29.12 0 0 0 41.728 0L714.24 534.336a32 32 0 0 0 0-44.672L382.592 149.376a29.12 29.12 0 0 0-41.728 0z"></path></svg></i></button></div></td><td colspan="1" rowspan="1" class="el-table_18_column_77 el-table__cell"><div class="cell">2016-05-08</div></td><td colspan="1" rowspan="1" class="el-table_18_column_78 el-table__cell"><div class="cell">Tom</div></td></tr><tr class="el-table__row"><td colspan="1" rowspan="1" class="el-table_18_column_76 el-table__expand-column el-table__cell"><div class="cell"><button type="button" aria-label="Expand this row" aria-expanded="false" class="el-table__expand-icon"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M340.864 149.312a30.59 30.59 0 0 0 0 42.752L652.736 512 340.864 831.872a30.59 30.59 0 0 0 0 42.752 29.12 29.12 0 0 0 41.728 0L714.24 534.336a32 32 0 0 0 0-44.672L382.592 149.376a29.12 29.12 0 0 0-41.728 0z"></path></svg></i></button></div></td><td colspan="1" rowspan="1" class="el-table_18_column_77 el-table__cell"><div class="cell">2016-05-06</div></td><td colspan="1" rowspan="1" class="el-table_18_column_78 el-table__cell"><div class="cell">Tom</div></td></tr><tr class="el-table__row"><td colspan="1" rowspan="1" class="el-table_18_column_76 el-table__expand-column el-table__cell"><div class="cell"><button type="button" aria-label="Expand this row" aria-expanded="false" class="el-table__expand-icon"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M340.864 149.312a30.59 30.59 0 0 0 0 42.752L652.736 512 340.864 831.872a30.59 30.59 0 0 0 0 42.752 29.12 29.12 0 0 0 41.728 0L714.24 534.336a32 32 0 0 0 0-44.672L382.592 149.376a29.12 29.12 0 0 0-41.728 0z"></path></svg></i></button></div></td><td colspan="1" rowspan="1" class="el-table_18_column_77 el-table__cell"><div class="cell">2016-05-07</div></td><td colspan="1" rowspan="1" class="el-table_18_column_78 el-table__cell"><div class="cell">Tom</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICBzd2l0Y2ggcGFyZW50IGJvcmRlcjogPGVsLXN3aXRjaCB2LW1vZGVsPVwicGFyZW50Qm9yZGVyXCIgLz4gc3dpdGNoIGNoaWxkXG4gIGJvcmRlcjogPGVsLXN3aXRjaCB2LW1vZGVsPVwiY2hpbGRCb3JkZXJcIiAvPiBwcmVzZXJ2ZSBleHBhbmRlZDpcbiAgPGVsLXN3aXRjaCB2LW1vZGVsPVwicHJlc2VydmVFeHBhbmRlZFwiIC8+XG4gIDxlbC10YWJsZVxuICAgIDpkYXRhPVwidGFibGVEYXRhXCJcbiAgICA6Ym9yZGVyPVwicGFyZW50Qm9yZGVyXCJcbiAgICA6cHJlc2VydmUtZXhwYW5kZWQtY29udGVudD1cInByZXNlcnZlRXhwYW5kZWRcIlxuICAgIHN0eWxlPVwid2lkdGg6IDEwMCVcIlxuICA+XG4gICAgPCEtLSBAdnVlLWdlbmVyaWMge3R5cGVvZiB0YWJsZURhdGFbbnVtYmVyXX0gLS0+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiB0eXBlPVwiZXhwYW5kXCI+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJwcm9wc1wiPlxuICAgICAgICA8ZGl2IG09XCI0XCI+XG4gICAgICAgICAgPHAgbT1cInQtMCBiLTJcIj5TdGF0ZToge3sgcHJvcHMucm93LnN0YXRlIH19PC9wPlxuICAgICAgICAgIDxwIG09XCJ0LTAgYi0yXCI+Q2l0eToge3sgcHJvcHMucm93LmNpdHkgfX08L3A+XG4gICAgICAgICAgPHAgbT1cInQtMCBiLTJcIj5BZGRyZXNzOiB7eyBwcm9wcy5yb3cuYWRkcmVzcyB9fTwvcD5cbiAgICAgICAgICA8cCBtPVwidC0wIGItMlwiPlppcDoge3sgcHJvcHMucm93LnppcCB9fTwvcD5cbiAgICAgICAgICA8aDM+RmFtaWx5PC9oMz5cbiAgICAgICAgICA8ZWwtdGFibGUgOmRhdGE9XCJwcm9wcy5yb3cuZmFtaWx5XCIgOmJvcmRlcj1cImNoaWxkQm9yZGVyXCI+XG4gICAgICAgICAgICA8ZWwtdGFibGUtY29sdW1uIGxhYmVsPVwiTmFtZVwiIHByb3A9XCJuYW1lXCIgLz5cbiAgICAgICAgICAgIDxlbC10YWJsZS1jb2x1bW4gbGFiZWw9XCJTdGF0ZVwiIHByb3A9XCJzdGF0ZVwiIC8+XG4gICAgICAgICAgICA8ZWwtdGFibGUtY29sdW1uIGxhYmVsPVwiQ2l0eVwiIHByb3A9XCJjaXR5XCIgLz5cbiAgICAgICAgICAgIDxlbC10YWJsZS1jb2x1bW4gbGFiZWw9XCJBZGRyZXNzXCIgcHJvcD1cImFkZHJlc3NcIiAvPlxuICAgICAgICAgICAgPGVsLXRhYmxlLWNvbHVtbiBsYWJlbD1cIlppcFwiIHByb3A9XCJ6aXBcIiAvPlxuICAgICAgICAgIDwvZWwtdGFibGU+XG4gICAgICAgIDwvZGl2PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLXRhYmxlLWNvbHVtbj5cbiAgICA8ZWwtdGFibGUtY29sdW1uIGxhYmVsPVwiRGF0ZVwiIHByb3A9XCJkYXRlXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIGxhYmVsPVwiTmFtZVwiIHByb3A9XCJuYW1lXCIgLz5cbiAgPC9lbC10YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHBhcmVudEJvcmRlciA9IHJlZihmYWxzZSlcbmNvbnN0IGNoaWxkQm9yZGVyID0gcmVmKGZhbHNlKVxuY29uc3QgcHJlc2VydmVFeHBhbmRlZCA9IHJlZihmYWxzZSlcbmNvbnN0IHRhYmxlRGF0YSA9IFtcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAzJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdTYW4gRnJhbmNpc2NvJyxcbiAgICBhZGRyZXNzOiAnMzY1MCAyMXN0IFN0LCBTYW4gRnJhbmNpc2NvJyxcbiAgICB6aXA6ICdDQSA5NDExNCcsXG4gICAgZmFtaWx5OiBbXG4gICAgICB7XG4gICAgICAgIG5hbWU6ICdKZXJyeScsXG4gICAgICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgICAgIGNpdHk6ICdTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgYWRkcmVzczogJzM2NTAgMjFzdCBTdCwgU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIHppcDogJ0NBIDk0MTE0JyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIG5hbWU6ICdTcGlrZScsXG4gICAgICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgICAgIGNpdHk6ICdTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgYWRkcmVzczogJzM2NTAgMjFzdCBTdCwgU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIHppcDogJ0NBIDk0MTE0JyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIG5hbWU6ICdUeWtlJyxcbiAgICAgICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICAgICAgY2l0eTogJ1NhbiBGcmFuY2lzY28nLFxuICAgICAgICBhZGRyZXNzOiAnMzY1MCAyMXN0IFN0LCBTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgemlwOiAnQ0EgOTQxMTQnLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDInLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgY2l0eTogJ1NhbiBGcmFuY2lzY28nLFxuICAgIGFkZHJlc3M6ICczNjUwIDIxc3QgU3QsIFNhbiBGcmFuY2lzY28nLFxuICAgIHppcDogJ0NBIDk0MTE0JyxcbiAgICBmYW1pbHk6IFtcbiAgICAgIHtcbiAgICAgICAgbmFtZTogJ0plcnJ5JyxcbiAgICAgICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICAgICAgY2l0eTogJ1NhbiBGcmFuY2lzY28nLFxuICAgICAgICBhZGRyZXNzOiAnMzY1MCAyMXN0IFN0LCBTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgemlwOiAnQ0EgOTQxMTQnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgbmFtZTogJ1NwaWtlJyxcbiAgICAgICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICAgICAgY2l0eTogJ1NhbiBGcmFuY2lzY28nLFxuICAgICAgICBhZGRyZXNzOiAnMzY1MCAyMXN0IFN0LCBTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgemlwOiAnQ0EgOTQxMTQnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgbmFtZTogJ1R5a2UnLFxuICAgICAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgICAgICBjaXR5OiAnU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIGFkZHJlc3M6ICczNjUwIDIxc3QgU3QsIFNhbiBGcmFuY2lzY28nLFxuICAgICAgICB6aXA6ICdDQSA5NDExNCcsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnU2FuIEZyYW5jaXNjbycsXG4gICAgYWRkcmVzczogJzM2NTAgMjFzdCBTdCwgU2FuIEZyYW5jaXNjbycsXG4gICAgemlwOiAnQ0EgOTQxMTQnLFxuICAgIGZhbWlseTogW1xuICAgICAge1xuICAgICAgICBuYW1lOiAnSmVycnknLFxuICAgICAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgICAgICBjaXR5OiAnU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIGFkZHJlc3M6ICczNjUwIDIxc3QgU3QsIFNhbiBGcmFuY2lzY28nLFxuICAgICAgICB6aXA6ICdDQSA5NDExNCcsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBuYW1lOiAnU3Bpa2UnLFxuICAgICAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgICAgICBjaXR5OiAnU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIGFkZHJlc3M6ICczNjUwIDIxc3QgU3QsIFNhbiBGcmFuY2lzY28nLFxuICAgICAgICB6aXA6ICdDQSA5NDExNCcsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBuYW1lOiAnVHlrZScsXG4gICAgICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgICAgIGNpdHk6ICdTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgYWRkcmVzczogJzM2NTAgMjFzdCBTdCwgU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIHppcDogJ0NBIDk0MTE0JyxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdTYW4gRnJhbmNpc2NvJyxcbiAgICBhZGRyZXNzOiAnMzY1MCAyMXN0IFN0LCBTYW4gRnJhbmNpc2NvJyxcbiAgICB6aXA6ICdDQSA5NDExNCcsXG4gICAgZmFtaWx5OiBbXG4gICAgICB7XG4gICAgICAgIG5hbWU6ICdKZXJyeScsXG4gICAgICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgICAgIGNpdHk6ICdTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgYWRkcmVzczogJzM2NTAgMjFzdCBTdCwgU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIHppcDogJ0NBIDk0MTE0JyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIG5hbWU6ICdTcGlrZScsXG4gICAgICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgICAgIGNpdHk6ICdTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgYWRkcmVzczogJzM2NTAgMjFzdCBTdCwgU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIHppcDogJ0NBIDk0MTE0JyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIG5hbWU6ICdUeWtlJyxcbiAgICAgICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICAgICAgY2l0eTogJ1NhbiBGcmFuY2lzY28nLFxuICAgICAgICBhZGRyZXNzOiAnMzY1MCAyMXN0IFN0LCBTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgemlwOiAnQ0EgOTQxMTQnLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDgnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgY2l0eTogJ1NhbiBGcmFuY2lzY28nLFxuICAgIGFkZHJlc3M6ICczNjUwIDIxc3QgU3QsIFNhbiBGcmFuY2lzY28nLFxuICAgIHppcDogJ0NBIDk0MTE0JyxcbiAgICBmYW1pbHk6IFtcbiAgICAgIHtcbiAgICAgICAgbmFtZTogJ0plcnJ5JyxcbiAgICAgICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICAgICAgY2l0eTogJ1NhbiBGcmFuY2lzY28nLFxuICAgICAgICBhZGRyZXNzOiAnMzY1MCAyMXN0IFN0LCBTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgemlwOiAnQ0EgOTQxMTQnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgbmFtZTogJ1NwaWtlJyxcbiAgICAgICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICAgICAgY2l0eTogJ1NhbiBGcmFuY2lzY28nLFxuICAgICAgICBhZGRyZXNzOiAnMzY1MCAyMXN0IFN0LCBTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgemlwOiAnQ0EgOTQxMTQnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgbmFtZTogJ1R5a2UnLFxuICAgICAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgICAgICBjaXR5OiAnU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIGFkZHJlc3M6ICczNjUwIDIxc3QgU3QsIFNhbiBGcmFuY2lzY28nLFxuICAgICAgICB6aXA6ICdDQSA5NDExNCcsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnU2FuIEZyYW5jaXNjbycsXG4gICAgYWRkcmVzczogJzM2NTAgMjFzdCBTdCwgU2FuIEZyYW5jaXNjbycsXG4gICAgemlwOiAnQ0EgOTQxMTQnLFxuICAgIGZhbWlseTogW1xuICAgICAge1xuICAgICAgICBuYW1lOiAnSmVycnknLFxuICAgICAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgICAgICBjaXR5OiAnU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIGFkZHJlc3M6ICczNjUwIDIxc3QgU3QsIFNhbiBGcmFuY2lzY28nLFxuICAgICAgICB6aXA6ICdDQSA5NDExNCcsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBuYW1lOiAnU3Bpa2UnLFxuICAgICAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgICAgICBjaXR5OiAnU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIGFkZHJlc3M6ICczNjUwIDIxc3QgU3QsIFNhbiBGcmFuY2lzY28nLFxuICAgICAgICB6aXA6ICdDQSA5NDExNCcsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBuYW1lOiAnVHlrZScsXG4gICAgICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgICAgIGNpdHk6ICdTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgYWRkcmVzczogJzM2NTAgMjFzdCBTdCwgU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIHppcDogJ0NBIDk0MTE0JyxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA3JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBzdGF0ZTogJ0NhbGlmb3JuaWEnLFxuICAgIGNpdHk6ICdTYW4gRnJhbmNpc2NvJyxcbiAgICBhZGRyZXNzOiAnMzY1MCAyMXN0IFN0LCBTYW4gRnJhbmNpc2NvJyxcbiAgICB6aXA6ICdDQSA5NDExNCcsXG4gICAgZmFtaWx5OiBbXG4gICAgICB7XG4gICAgICAgIG5hbWU6ICdKZXJyeScsXG4gICAgICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgICAgIGNpdHk6ICdTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgYWRkcmVzczogJzM2NTAgMjFzdCBTdCwgU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIHppcDogJ0NBIDk0MTE0JyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIG5hbWU6ICdTcGlrZScsXG4gICAgICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgICAgIGNpdHk6ICdTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgYWRkcmVzczogJzM2NTAgMjFzdCBTdCwgU2FuIEZyYW5jaXNjbycsXG4gICAgICAgIHppcDogJ0NBIDk0MTE0JyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIG5hbWU6ICdUeWtlJyxcbiAgICAgICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICAgICAgY2l0eTogJ1NhbiBGcmFuY2lzY28nLFxuICAgICAgICBhZGRyZXNzOiAnMzY1MCAyMXN0IFN0LCBTYW4gRnJhbmNpc2NvJyxcbiAgICAgICAgemlwOiAnQ0EgOTQxMTQnLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/expandable-row.vue)_

vue

```
<template>
  switch parent border: <el-switch v-model="parentBorder" /> switch child
  border: <el-switch v-model="childBorder" /> preserve expanded:
  <el-switch v-model="preserveExpanded" />
  <el-table
    :data="tableData"
    :border="parentBorder"
    :preserve-expanded-content="preserveExpanded"
    style="width: 100%"
  >
    <!-- @vue-generic {typeof tableData[number]} -->
    <el-table-column type="expand">
      <template #default="props">
        <div m="4">
          <p m="t-0 b-2">State: {{ props.row.state }}</p>
          <p m="t-0 b-2">City: {{ props.row.city }}</p>
          <p m="t-0 b-2">Address: {{ props.row.address }}</p>
          <p m="t-0 b-2">Zip: {{ props.row.zip }}</p>
          <h3>Family</h3>
          <el-table :data="props.row.family" :border="childBorder">
            <el-table-column label="Name" prop="name" />
            <el-table-column label="State" prop="state" />
            <el-table-column label="City" prop="city" />
            <el-table-column label="Address" prop="address" />
            <el-table-column label="Zip" prop="zip" />
          </el-table>
        </div>
      </template>
    </el-table-column>
    <el-table-column label="Date" prop="date" />
    <el-table-column label="Name" prop="name" />
  </el-table>
</template>

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

const parentBorder = ref(false)
const childBorder = ref(false)
const preserveExpanded = ref(false)
const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-08',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-06',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-07',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 树形数据与懒加载 [​](#树形数据与懒加载)

支持树类型的数据的显示。 当 row 中包含 `children` 字段时，被视为树形数据。 渲染嵌套数据需要 prop 的 `row-key`。 此外，子行数据可以异步加载。 设置 Table 的`lazy`属性为 true 与加载函数 `load` 。 通过指定 row 中的`hasChildren`字段来指定哪些行是包含子节点。 `children` 与`hasChildren`都可以通过 `tree-props` 配置。

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_19_column_79" width="299"><col name="el-table_19_column_80" width="297"><col name="el-table_19_column_81" width="297"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_19_column_79 el-table__cell"><div class="cell"><span class="el-table__placeholder"></span>2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_19_column_80 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_19_column_81 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_19_column_79 el-table__cell"><div class="cell"><span class="el-table__placeholder"></span>2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_19_column_80 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_19_column_81 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row--level-0 el-table__row"><td colspan="1" rowspan="1" class="el-table_19_column_79 el-table__cell"><div class="cell"><button type="button" aria-label="Collapse this row" aria-expanded="true" class="el-table__expand-icon el-table__expand-icon--expanded"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M340.864 149.312a30.59 30.59 0 0 0 0 42.752L652.736 512 340.864 831.872a30.59 30.59 0 0 0 0 42.752 29.12 29.12 0 0 0 41.728 0L714.24 534.336a32 32 0 0 0 0-44.672L382.592 149.376a29.12 29.12 0 0 0-41.728 0z"></path></svg></i></button>2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_19_column_80 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_19_column_81 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row--level-1 el-table__row"><td colspan="1" rowspan="1" class="el-table_19_column_79 el-table__cell"><div class="cell"><span class="el-table__indent" style="padding-left: 16px;"></span><span class="el-table__placeholder"></span>2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_19_column_80 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_19_column_81 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row--level-1 el-table__row"><td colspan="1" rowspan="1" class="el-table_19_column_79 el-table__cell"><div class="cell"><span class="el-table__indent" style="padding-left: 16px;"></span><span class="el-table__placeholder"></span>2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_19_column_80 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_19_column_81 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_19_column_79 el-table__cell"><div class="cell"><span class="el-table__placeholder"></span>2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_19_column_80 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_19_column_81 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_20_column_82" width="299"><col name="el-table_20_column_83" width="297"><col name="el-table_20_column_84" width="297"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_20_column_82 el-table__cell"><div class="cell"><span class="el-table__placeholder"></span>2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_20_column_83 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_20_column_84 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_20_column_82 el-table__cell"><div class="cell"><span class="el-table__placeholder"></span>2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_20_column_83 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_20_column_84 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row--level-0 el-table__row"><td colspan="1" rowspan="1" class="el-table_20_column_82 el-table__cell"><div class="cell"><button type="button" aria-label="Expand this row" aria-expanded="false" class="el-table__expand-icon"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M340.864 149.312a30.59 30.59 0 0 0 0 42.752L652.736 512 340.864 831.872a30.59 30.59 0 0 0 0 42.752 29.12 29.12 0 0 0 41.728 0L714.24 534.336a32 32 0 0 0 0-44.672L382.592 149.376a29.12 29.12 0 0 0-41.728 0z"></path></svg></i></button>2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_20_column_83 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_20_column_84 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_20_column_82 el-table__cell"><div class="cell"><span class="el-table__placeholder"></span>2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_20_column_83 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_20_column_84 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC10YWJsZVxuICAgICAgOmRhdGE9XCJ0YWJsZURhdGFcIlxuICAgICAgc3R5bGU9XCJ3aWR0aDogMTAwJTsgbWFyZ2luLWJvdHRvbTogMjBweFwiXG4gICAgICByb3cta2V5PVwiaWRcIlxuICAgICAgYm9yZGVyXG4gICAgICBkZWZhdWx0LWV4cGFuZC1hbGxcbiAgICA+XG4gICAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJkYXRlXCIgbGFiZWw9XCJEYXRlXCIgc29ydGFibGUgLz5cbiAgICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cIm5hbWVcIiBsYWJlbD1cIk5hbWVcIiBzb3J0YWJsZSAvPlxuICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiYWRkcmVzc1wiIGxhYmVsPVwiQWRkcmVzc1wiIHNvcnRhYmxlIC8+XG4gICAgPC9lbC10YWJsZT5cblxuICAgIDxlbC10YWJsZVxuICAgICAgOmRhdGE9XCJ0YWJsZURhdGExXCJcbiAgICAgIHN0eWxlPVwid2lkdGg6IDEwMCVcIlxuICAgICAgcm93LWtleT1cImlkXCJcbiAgICAgIGJvcmRlclxuICAgICAgbGF6eVxuICAgICAgOmxvYWQ9XCJsb2FkXCJcbiAgICAgIDp0cmVlLXByb3BzPVwieyBjaGlsZHJlbjogJ2NoaWxkcmVuJywgaGFzQ2hpbGRyZW46ICdoYXNDaGlsZHJlbicgfVwiXG4gICAgPlxuICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIC8+XG4gICAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgLz5cbiAgICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiAvPlxuICAgIDwvZWwtdGFibGU+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmludGVyZmFjZSBVc2VyIHtcbiAgaWQ6IG51bWJlclxuICBkYXRlOiBzdHJpbmdcbiAgbmFtZTogc3RyaW5nXG4gIGFkZHJlc3M6IHN0cmluZ1xuICBoYXNDaGlsZHJlbj86IGJvb2xlYW5cbiAgY2hpbGRyZW4/OiBVc2VyW11cbn1cblxuY29uc3QgbG9hZCA9IChcbiAgcm93OiBVc2VyLFxuICB0cmVlTm9kZTogdW5rbm93bixcbiAgcmVzb2x2ZTogKGRhdGE6IFVzZXJbXSkgPT4gdm9pZFxuKSA9PiB7XG4gIHNldFRpbWVvdXQoKCkgPT4ge1xuICAgIHJlc29sdmUoW1xuICAgICAge1xuICAgICAgICBpZDogMzEsXG4gICAgICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICAgICAgbmFtZTogJ3dhbmd4aWFvaHUnLFxuICAgICAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIGlkOiAzMixcbiAgICAgICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgICAgICBuYW1lOiAnd2FuZ3hpYW9odScsXG4gICAgICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgICAgfSxcbiAgICBdKVxuICB9LCAxMDAwKVxufVxuXG5jb25zdCB0YWJsZURhdGE6IFVzZXJbXSA9IFtcbiAge1xuICAgIGlkOiAxLFxuICAgIGRhdGU6ICcyMDE2LTA1LTAyJyxcbiAgICBuYW1lOiAnd2FuZ3hpYW9odScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBpZDogMixcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ3dhbmd4aWFvaHUnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuICB7XG4gICAgaWQ6IDMsXG4gICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgIG5hbWU6ICd3YW5neGlhb2h1JyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICBpZDogMzEsXG4gICAgICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICAgICAgbmFtZTogJ3dhbmd4aWFvaHUnLFxuICAgICAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIGlkOiAzMixcbiAgICAgICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgICAgICBuYW1lOiAnd2FuZ3hpYW9odScsXG4gICAgICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgaWQ6IDQsXG4gICAgZGF0ZTogJzIwMTYtMDUtMDMnLFxuICAgIG5hbWU6ICd3YW5neGlhb2h1JyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbl1cblxuY29uc3QgdGFibGVEYXRhMTogVXNlcltdID0gW1xuICB7XG4gICAgaWQ6IDEsXG4gICAgZGF0ZTogJzIwMTYtMDUtMDInLFxuICAgIG5hbWU6ICd3YW5neGlhb2h1JyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGlkOiAyLFxuICAgIGRhdGU6ICcyMDE2LTA1LTA0JyxcbiAgICBuYW1lOiAnd2FuZ3hpYW9odScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBpZDogMyxcbiAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgbmFtZTogJ3dhbmd4aWFvaHUnLFxuICAgIGhhc0NoaWxkcmVuOiB0cnVlLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuICB7XG4gICAgaWQ6IDQsXG4gICAgZGF0ZTogJzIwMTYtMDUtMDMnLFxuICAgIG5hbWU6ICd3YW5neGlhb2h1JyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/tree-and-lazy.vue)_

vue

```
<template>
  <div>
    <el-table
      :data="tableData"
      style="width: 100%; margin-bottom: 20px"
      row-key="id"
      border
      default-expand-all
    >
      <el-table-column prop="date" label="Date" sortable />
      <el-table-column prop="name" label="Name" sortable />
      <el-table-column prop="address" label="Address" sortable />
    </el-table>

    <el-table
      :data="tableData1"
      style="width: 100%"
      row-key="id"
      border
      lazy
      :load="load"
      :tree-props="{ children: 'children', hasChildren: 'hasChildren' }"
    >
      <el-table-column prop="date" label="Date" />
      <el-table-column prop="name" label="Name" />
      <el-table-column prop="address" label="Address" />
    </el-table>
  </div>
</template>

<script lang="ts" setup>
interface User {
  id: number
  date: string
  name: string
  address: string
  hasChildren?: boolean
  children?: User[]
}

const load = (
  row: User,
  treeNode: unknown,
  resolve: (data: User[]) => void
) => {
  setTimeout(() => {
    resolve([
      {
        id: 31,
        date: '2016-05-01',
        name: 'wangxiaohu',
        address: 'No. 189, Grove St, Los Angeles',
      },
      {
        id: 32,
        date: '2016-05-01',
        name: 'wangxiaohu',
        address: 'No. 189, Grove St, Los Angeles',
      },
    ])
  }, 1000)
}

const tableData: User[] = [
  {
    id: 1,
    date: '2016-05-02',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 2,
    date: '2016-05-04',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 3,
    date: '2016-05-01',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
    children: [
      {
        id: 31,
        date: '2016-05-01',
        name: 'wangxiaohu',
        address: 'No. 189, Grove St, Los Angeles',
      },
      {
        id: 32,
        date: '2016-05-01',
        name: 'wangxiaohu',
        address: 'No. 189, Grove St, Los Angeles',
      },
    ],
  },
  {
    id: 4,
    date: '2016-05-03',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
]

const tableData1: User[] = [
  {
    id: 1,
    date: '2016-05-02',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 2,
    date: '2016-05-04',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 3,
    date: '2016-05-01',
    name: 'wangxiaohu',
    hasChildren: true,
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 4,
    date: '2016-05-03',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## 可选择的树形数据2.8.0 [​](#可选择的树形数据)

当 `treeProps.checkStrictly` 为 true，父节点和子节点的选择状态不再关联， 也就是说，当选择父节点时，它的子节点将不被选择； 当 `treeProps.checkStrictly` 是false，父节点和子节点的选择状态将与子节点的选择状态相关联， 也就是说，当选择父节点时，将选择其所有子节点。

truefalse

|
 |

Date

 |

Name

 |

Address

 |
| --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_21_column_85" width="55"><col name="el-table_21_column_86" width="280"><col name="el-table_21_column_87" width="279"><col name="el-table_21_column_88" width="279"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_21_column_85 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox is-disabled" aria-label="Select this row" for="el-id-1024-391"><span class="el-checkbox__input is-disabled"><input class="el-checkbox__original" type="checkbox" disabled="" id="el-id-1024-391"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_21_column_86 el-table__cell"><div class="cell"><span class="el-table__placeholder"></span>2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_21_column_87 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_21_column_88 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_21_column_85 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-392"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-392"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_21_column_86 el-table__cell"><div class="cell"><span class="el-table__placeholder"></span>2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_21_column_87 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_21_column_88 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row--level-0 el-table__row"><td colspan="1" rowspan="1" class="el-table_21_column_85 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-393"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-393"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_21_column_86 el-table__cell"><div class="cell"><button type="button" aria-label="Collapse this row" aria-expanded="true" class="el-table__expand-icon el-table__expand-icon--expanded"><i class="el-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024"><path fill="currentColor" d="M340.864 149.312a30.59 30.59 0 0 0 0 42.752L652.736 512 340.864 831.872a30.59 30.59 0 0 0 0 42.752 29.12 29.12 0 0 0 41.728 0L714.24 534.336a32 32 0 0 0 0-44.672L382.592 149.376a29.12 29.12 0 0 0-41.728 0z"></path></svg></i></button>2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_21_column_87 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_21_column_88 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row--level-1 el-table__row"><td colspan="1" rowspan="1" class="el-table_21_column_85 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox is-disabled" aria-label="Select this row" for="el-id-1024-394"><span class="el-checkbox__input is-disabled"><input class="el-checkbox__original" type="checkbox" disabled="" id="el-id-1024-394"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_21_column_86 el-table__cell"><div class="cell"><span class="el-table__indent" style="padding-left: 16px;"></span><span class="el-table__placeholder"></span>2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_21_column_87 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_21_column_88 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row--level-1 el-table__row"><td colspan="1" rowspan="1" class="el-table_21_column_85 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-395"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-395"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_21_column_86 el-table__cell"><div class="cell"><span class="el-table__indent" style="padding-left: 16px;"></span><span class="el-table__placeholder"></span>2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_21_column_87 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_21_column_88 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row--level-1 el-table__row"><td colspan="1" rowspan="1" class="el-table_21_column_85 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-396"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-396"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_21_column_86 el-table__cell"><div class="cell"><span class="el-table__indent" style="padding-left: 16px;"></span><span class="el-table__placeholder"></span>2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_21_column_87 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_21_column_88 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_21_column_85 el-table-column--selection el-table__cell"><div class="cell"><label class="el-checkbox" aria-label="Select this row" for="el-id-1024-397"><span class="el-checkbox__input"><input class="el-checkbox__original" type="checkbox" id="el-id-1024-397"><span class="el-checkbox__inner"></span></span></label></div></td><td colspan="1" rowspan="1" class="el-table_21_column_86 el-table__cell"><div class="cell"><span class="el-table__placeholder"></span>2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_21_column_87 el-table__cell"><div class="cell">wangxiaohu</div></td><td colspan="1" rowspan="1" class="el-table_21_column_88 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInRyZWVQcm9wcy5jaGVja1N0cmljdGx5XCIgY2xhc3M9XCJtYi0yXCI+XG4gICAgPGVsLXJhZGlvLWJ1dHRvbiA6dmFsdWU9XCJ0cnVlXCIgbGFiZWw9XCJ0cnVlXCIgLz5cbiAgICA8ZWwtcmFkaW8tYnV0dG9uIDp2YWx1ZT1cImZhbHNlXCIgbGFiZWw9XCJmYWxzZVwiIC8+XG4gIDwvZWwtcmFkaW8tZ3JvdXA+XG4gIDxlbC10YWJsZVxuICAgIDpkYXRhPVwidGFibGVEYXRhXCJcbiAgICA6dHJlZS1wcm9wcz1cInRyZWVQcm9wc1wiXG4gICAgcm93LWtleT1cImlkXCJcbiAgICBkZWZhdWx0LWV4cGFuZC1hbGxcbiAgPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gdHlwZT1cInNlbGVjdGlvblwiIHdpZHRoPVwiNTVcIiA6c2VsZWN0YWJsZT1cInNlbGVjdGFibGVcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImRhdGVcIiBsYWJlbD1cIkRhdGVcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cIm5hbWVcIiBsYWJlbD1cIk5hbWVcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiAvPlxuICA8L2VsLXRhYmxlPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlYWN0aXZlIH0gZnJvbSAndnVlJ1xuXG5pbnRlcmZhY2UgVXNlciB7XG4gIGlkOiBudW1iZXJcbiAgZGF0ZTogc3RyaW5nXG4gIG5hbWU6IHN0cmluZ1xuICBhZGRyZXNzOiBzdHJpbmdcbiAgaGFzQ2hpbGRyZW4/OiBib29sZWFuXG4gIGNoaWxkcmVuPzogVXNlcltdXG59XG5cbmNvbnN0IHRyZWVQcm9wcyA9IHJlYWN0aXZlKHtcbiAgY2hlY2tTdHJpY3RseTogZmFsc2UsXG59KVxuXG5jb25zdCBzZWxlY3RhYmxlID0gKHJvdzogVXNlcikgPT4gIVsxLCAzMV0uaW5jbHVkZXMocm93LmlkKVxuXG5jb25zdCB0YWJsZURhdGE6IFVzZXJbXSA9IFtcbiAge1xuICAgIGlkOiAxLFxuICAgIGRhdGU6ICcyMDE2LTA1LTAyJyxcbiAgICBuYW1lOiAnd2FuZ3hpYW9odScsXG4gICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gIH0sXG4gIHtcbiAgICBpZDogMixcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ3dhbmd4aWFvaHUnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuICB7XG4gICAgaWQ6IDMsXG4gICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgIG5hbWU6ICd3YW5neGlhb2h1JyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICBpZDogMzEsXG4gICAgICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICAgICAgbmFtZTogJ3dhbmd4aWFvaHUnLFxuICAgICAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIGlkOiAzMixcbiAgICAgICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgICAgICBuYW1lOiAnd2FuZ3hpYW9odScsXG4gICAgICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IDMzLFxuICAgICAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgICAgIG5hbWU6ICd3YW5neGlhb2h1JyxcbiAgICAgICAgYWRkcmVzczogJ05vLiAxODksIEdyb3ZlIFN0LCBMb3MgQW5nZWxlcycsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICBpZDogNCxcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ3dhbmd4aWFvaHUnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/check-strictly.vue)_

vue

```
<template>
  <el-radio-group v-model="treeProps.checkStrictly" class="mb-2">
    <el-radio-button :value="true" label="true" />
    <el-radio-button :value="false" label="false" />
  </el-radio-group>
  <el-table
    :data="tableData"
    :tree-props="treeProps"
    row-key="id"
    default-expand-all
  >
    <el-table-column type="selection" width="55" :selectable="selectable" />
    <el-table-column prop="date" label="Date" />
    <el-table-column prop="name" label="Name" />
    <el-table-column prop="address" label="Address" />
  </el-table>
</template>

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

interface User {
  id: number
  date: string
  name: string
  address: string
  hasChildren?: boolean
  children?: User[]
}

const treeProps = reactive({
  checkStrictly: false,
})

const selectable = (row: User) => ![1, 31].includes(row.id)

const tableData: User[] = [
  {
    id: 1,
    date: '2016-05-02',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 2,
    date: '2016-05-04',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 3,
    date: '2016-05-01',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
    children: [
      {
        id: 31,
        date: '2016-05-01',
        name: 'wangxiaohu',
        address: 'No. 189, Grove St, Los Angeles',
      },
      {
        id: 32,
        date: '2016-05-01',
        name: 'wangxiaohu',
        address: 'No. 189, Grove St, Los Angeles',
      },
      {
        id: 33,
        date: '2016-05-01',
        name: 'wangxiaohu',
        address: 'No. 189, Grove St, Los Angeles',
      },
    ],
  },
  {
    id: 4,
    date: '2016-05-03',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## 表尾合计行 [​](#表尾合计行)

若表格展示的是各类数字，可以在表尾显示各列的合计。

将 `show-summary` 设置为`true`就会在表格尾部展示合计行。 默认情况下，对于合计行，第一列不进行数据求合操作，而是显示「合计」二字（可通过`sum-text`配置），其余列会将本列所有数值进行求合操作，并显示出来。 当然，你也可以定义自己的合计逻辑。 使用 `summary-method` 并传入一个方法，返回一个数组，这个数组中的各项就会显示在合计行的各列中，可以是一个 VNode 或 String， 具体可以参考本例中的第二个表格。

|
ID

 |

Name

 |

Amount 1

 |

Amount 2

 |

Amount 3

 |
| --- | --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_22_column_89" width="180"><col name="el-table_22_column_90" width="179"><col name="el-table_22_column_91" width="178"><col name="el-table_22_column_92" width="178"><col name="el-table_22_column_93" width="178"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_22_column_89 el-table__cell"><div class="cell">12987122</div></td><td colspan="1" rowspan="1" class="el-table_22_column_90 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_22_column_91 el-table__cell"><div class="cell">234</div></td><td colspan="1" rowspan="1" class="el-table_22_column_92 el-table__cell"><div class="cell">3.2</div></td><td colspan="1" rowspan="1" class="el-table_22_column_93 el-table__cell"><div class="cell">10</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_22_column_89 el-table__cell"><div class="cell">12987123</div></td><td colspan="1" rowspan="1" class="el-table_22_column_90 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_22_column_91 el-table__cell"><div class="cell">165</div></td><td colspan="1" rowspan="1" class="el-table_22_column_92 el-table__cell"><div class="cell">4.43</div></td><td colspan="1" rowspan="1" class="el-table_22_column_93 el-table__cell"><div class="cell">12</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_22_column_89 el-table__cell"><div class="cell">12987124</div></td><td colspan="1" rowspan="1" class="el-table_22_column_90 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_22_column_91 el-table__cell"><div class="cell">324</div></td><td colspan="1" rowspan="1" class="el-table_22_column_92 el-table__cell"><div class="cell">1.9</div></td><td colspan="1" rowspan="1" class="el-table_22_column_93 el-table__cell"><div class="cell">9</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_22_column_89 el-table__cell"><div class="cell">12987125</div></td><td colspan="1" rowspan="1" class="el-table_22_column_90 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_22_column_91 el-table__cell"><div class="cell">621</div></td><td colspan="1" rowspan="1" class="el-table_22_column_92 el-table__cell"><div class="cell">2.2</div></td><td colspan="1" rowspan="1" class="el-table_22_column_93 el-table__cell"><div class="cell">17</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_22_column_89 el-table__cell"><div class="cell">12987126</div></td><td colspan="1" rowspan="1" class="el-table_22_column_90 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_22_column_91 el-table__cell"><div class="cell">539</div></td><td colspan="1" rowspan="1" class="el-table_22_column_92 el-table__cell"><div class="cell">4.1</div></td><td colspan="1" rowspan="1" class="el-table_22_column_93 el-table__cell"><div class="cell">15</div></td></tr></tbody></table>

<table class="el-table__footer" cellspacing="0" cellpadding="0" border="0" style="width: 893px;"><colgroup><col name="el-table_22_column_89" width="180"><col name="el-table_22_column_90" width="179"><col name="el-table_22_column_91" width="178"><col name="el-table_22_column_92" width="178"><col name="el-table_22_column_93" width="178"></colgroup><tfoot><tr><td colspan="1" rowspan="1" class="el-table__cell el-table_22_column_89 is-leaf"><div class="cell">Sum</div></td><td colspan="1" rowspan="1" class="el-table__cell el-table_22_column_90 is-leaf"><div class="cell"></div></td><td colspan="1" rowspan="1" class="el-table__cell el-table_22_column_91 is-leaf"><div class="cell">1883</div></td><td colspan="1" rowspan="1" class="el-table__cell el-table_22_column_92 is-leaf"><div class="cell">15.83</div></td><td colspan="1" rowspan="1" class="el-table__cell el-table_22_column_93 is-leaf"><div class="cell">63</div></td></tr></tfoot></table>

|
ID

 |

Name

 |

Cost 1 ($)

 |

Cost 2 ($)

 |

Cost 3 ($)

 |
| --- | --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_23_column_94" width="180"><col name="el-table_23_column_95" width="179"><col name="el-table_23_column_96" width="178"><col name="el-table_23_column_97" width="178"><col name="el-table_23_column_98" width="178"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_23_column_94 el-table__cell"><div class="cell">12987122</div></td><td colspan="1" rowspan="1" class="el-table_23_column_95 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_23_column_96 el-table__cell"><div class="cell">234</div></td><td colspan="1" rowspan="1" class="el-table_23_column_97 el-table__cell"><div class="cell">3.2</div></td><td colspan="1" rowspan="1" class="el-table_23_column_98 el-table__cell"><div class="cell">10</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_23_column_94 el-table__cell"><div class="cell">12987123</div></td><td colspan="1" rowspan="1" class="el-table_23_column_95 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_23_column_96 el-table__cell"><div class="cell">165</div></td><td colspan="1" rowspan="1" class="el-table_23_column_97 el-table__cell"><div class="cell">4.43</div></td><td colspan="1" rowspan="1" class="el-table_23_column_98 el-table__cell"><div class="cell">12</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_23_column_94 el-table__cell"><div class="cell">12987124</div></td><td colspan="1" rowspan="1" class="el-table_23_column_95 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_23_column_96 el-table__cell"><div class="cell">324</div></td><td colspan="1" rowspan="1" class="el-table_23_column_97 el-table__cell"><div class="cell">1.9</div></td><td colspan="1" rowspan="1" class="el-table_23_column_98 el-table__cell"><div class="cell">9</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_23_column_94 el-table__cell"><div class="cell">12987125</div></td><td colspan="1" rowspan="1" class="el-table_23_column_95 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_23_column_96 el-table__cell"><div class="cell">621</div></td><td colspan="1" rowspan="1" class="el-table_23_column_97 el-table__cell"><div class="cell">2.2</div></td><td colspan="1" rowspan="1" class="el-table_23_column_98 el-table__cell"><div class="cell">17</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_23_column_94 el-table__cell"><div class="cell">12987126</div></td><td colspan="1" rowspan="1" class="el-table_23_column_95 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_23_column_96 el-table__cell"><div class="cell">539</div></td><td colspan="1" rowspan="1" class="el-table_23_column_97 el-table__cell"><div class="cell">4.1</div></td><td colspan="1" rowspan="1" class="el-table_23_column_98 el-table__cell"><div class="cell">15</div></td></tr></tbody></table>

<table class="el-table__footer" cellspacing="0" cellpadding="0" border="0" style="width: 893px;"><colgroup><col name="el-table_23_column_94" width="180"><col name="el-table_23_column_95" width="179"><col name="el-table_23_column_96" width="178"><col name="el-table_23_column_97" width="178"><col name="el-table_23_column_98" width="178"></colgroup><tfoot><tr><td colspan="1" rowspan="1" class="el-table__cell el-table_23_column_94 is-leaf"><div class="cell"><div style="text-decoration: underline;">Total Cost</div></div></td><td colspan="1" rowspan="1" class="el-table__cell el-table_23_column_95 is-leaf"><div class="cell">N/A</div></td><td colspan="1" rowspan="1" class="el-table__cell el-table_23_column_96 is-leaf"><div class="cell">$ 1883</div></td><td colspan="1" rowspan="1" class="el-table__cell el-table_23_column_97 is-leaf"><div class="cell">$ 15.83</div></td><td colspan="1" rowspan="1" class="el-table__cell el-table_23_column_98 is-leaf"><div class="cell">$ 63</div></td></tr></tfoot></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBib3JkZXIgc2hvdy1zdW1tYXJ5IHN0eWxlPVwid2lkdGg6IDEwMCVcIj5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJpZFwiIGxhYmVsPVwiSURcIiB3aWR0aD1cIjE4MFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiYW1vdW50MVwiIHNvcnRhYmxlIGxhYmVsPVwiQW1vdW50IDFcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFtb3VudDJcIiBzb3J0YWJsZSBsYWJlbD1cIkFtb3VudCAyXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhbW91bnQzXCIgc29ydGFibGUgbGFiZWw9XCJBbW91bnQgM1wiIC8+XG4gIDwvZWwtdGFibGU+XG5cbiAgPGVsLXRhYmxlXG4gICAgOmRhdGE9XCJ0YWJsZURhdGFcIlxuICAgIGJvcmRlclxuICAgIGhlaWdodD1cIjIwMFwiXG4gICAgOnN1bW1hcnktbWV0aG9kPVwiZ2V0U3VtbWFyaWVzXCJcbiAgICBzaG93LXN1bW1hcnlcbiAgICBzdHlsZT1cIndpZHRoOiAxMDAlOyBtYXJnaW4tdG9wOiAyMHB4XCJcbiAgPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImlkXCIgbGFiZWw9XCJJRFwiIHdpZHRoPVwiMTgwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhbW91bnQxXCIgbGFiZWw9XCJDb3N0IDEgKCQpXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhbW91bnQyXCIgbGFiZWw9XCJDb3N0IDIgKCQpXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhbW91bnQzXCIgbGFiZWw9XCJDb3N0IDMgKCQpXCIgLz5cbiAgPC9lbC10YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBoIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IFZOb2RlIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHR5cGUgeyBUYWJsZUNvbHVtbkN0eCB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuaW50ZXJmYWNlIFByb2R1Y3Qge1xuICBpZDogc3RyaW5nXG4gIG5hbWU6IHN0cmluZ1xuICBhbW91bnQxOiBzdHJpbmdcbiAgYW1vdW50Mjogc3RyaW5nXG4gIGFtb3VudDM6IG51bWJlclxufVxuXG5pbnRlcmZhY2UgU3VtbWFyeU1ldGhvZFByb3BzPFQgZXh0ZW5kcyBQcm9kdWN0ID0gUHJvZHVjdD4ge1xuICBjb2x1bW5zOiBUYWJsZUNvbHVtbkN0eDxUPltdXG4gIGRhdGE6IFRbXVxufVxuXG5jb25zdCBnZXRTdW1tYXJpZXMgPSAocGFyYW06IFN1bW1hcnlNZXRob2RQcm9wcykgPT4ge1xuICBjb25zdCB7IGNvbHVtbnMsIGRhdGEgfSA9IHBhcmFtXG4gIGNvbnN0IHN1bXM6IChzdHJpbmcgfCBWTm9kZSlbXSA9IFtdXG4gIGNvbHVtbnMuZm9yRWFjaCgoY29sdW1uLCBpbmRleCkgPT4ge1xuICAgIGlmIChpbmRleCA9PT0gMCkge1xuICAgICAgc3Vtc1tpbmRleF0gPSBoKCdkaXYnLCB7IHN0eWxlOiB7IHRleHREZWNvcmF0aW9uOiAndW5kZXJsaW5lJyB9IH0sIFtcbiAgICAgICAgJ1RvdGFsIENvc3QnLFxuICAgICAgXSlcbiAgICAgIHJldHVyblxuICAgIH1cbiAgICBjb25zdCB2YWx1ZXMgPSBkYXRhLm1hcCgoaXRlbSkgPT4gTnVtYmVyKGl0ZW1bY29sdW1uLnByb3BlcnR5XSkpXG4gICAgaWYgKCF2YWx1ZXMuZXZlcnkoKHZhbHVlKSA9PiBOdW1iZXIuaXNOYU4odmFsdWUpKSkge1xuICAgICAgc3Vtc1tpbmRleF0gPSBgJCAke3ZhbHVlcy5yZWR1Y2UoKHByZXYsIGN1cnIpID0+IHtcbiAgICAgICAgY29uc3QgdmFsdWUgPSBOdW1iZXIoY3VycilcbiAgICAgICAgaWYgKCFOdW1iZXIuaXNOYU4odmFsdWUpKSB7XG4gICAgICAgICAgcmV0dXJuIHByZXYgKyBjdXJyXG4gICAgICAgIH0gZWxzZSB7XG4gICAgICAgICAgcmV0dXJuIHByZXZcbiAgICAgICAgfVxuICAgICAgfSwgMCl9YFxuICAgIH0gZWxzZSB7XG4gICAgICBzdW1zW2luZGV4XSA9ICdOL0EnXG4gICAgfVxuICB9KVxuXG4gIHJldHVybiBzdW1zXG59XG5cbmNvbnN0IHRhYmxlRGF0YTogUHJvZHVjdFtdID0gW1xuICB7XG4gICAgaWQ6ICcxMjk4NzEyMicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYW1vdW50MTogJzIzNCcsXG4gICAgYW1vdW50MjogJzMuMicsXG4gICAgYW1vdW50MzogMTAsXG4gIH0sXG4gIHtcbiAgICBpZDogJzEyOTg3MTIzJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhbW91bnQxOiAnMTY1JyxcbiAgICBhbW91bnQyOiAnNC40MycsXG4gICAgYW1vdW50MzogMTIsXG4gIH0sXG4gIHtcbiAgICBpZDogJzEyOTg3MTI0JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhbW91bnQxOiAnMzI0JyxcbiAgICBhbW91bnQyOiAnMS45JyxcbiAgICBhbW91bnQzOiA5LFxuICB9LFxuICB7XG4gICAgaWQ6ICcxMjk4NzEyNScsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYW1vdW50MTogJzYyMScsXG4gICAgYW1vdW50MjogJzIuMicsXG4gICAgYW1vdW50MzogMTcsXG4gIH0sXG4gIHtcbiAgICBpZDogJzEyOTg3MTI2JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhbW91bnQxOiAnNTM5JyxcbiAgICBhbW91bnQyOiAnNC4xJyxcbiAgICBhbW91bnQzOiAxNSxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/summary.vue)_

vue

```
<template>
  <el-table :data="tableData" border show-summary style="width: 100%">
    <el-table-column prop="id" label="ID" width="180" />
    <el-table-column prop="name" label="Name" />
    <el-table-column prop="amount1" sortable label="Amount 1" />
    <el-table-column prop="amount2" sortable label="Amount 2" />
    <el-table-column prop="amount3" sortable label="Amount 3" />
  </el-table>

  <el-table
    :data="tableData"
    border
    height="200"
    :summary-method="getSummaries"
    show-summary
    style="width: 100%; margin-top: 20px"
  >
    <el-table-column prop="id" label="ID" width="180" />
    <el-table-column prop="name" label="Name" />
    <el-table-column prop="amount1" label="Cost 1 ($)" />
    <el-table-column prop="amount2" label="Cost 2 ($)" />
    <el-table-column prop="amount3" label="Cost 3 ($)" />
  </el-table>
</template>

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

import type { VNode } from 'vue'
import type { TableColumnCtx } from 'element-plus'

interface Product {
  id: string
  name: string
  amount1: string
  amount2: string
  amount3: number
}

interface SummaryMethodProps<T extends Product = Product> {
  columns: TableColumnCtx<T>[]
  data: T[]
}

const getSummaries = (param: SummaryMethodProps) => {
  const { columns, data } = param
  const sums: (string | VNode)[] = []
  columns.forEach((column, index) => {
    if (index === 0) {
      sums[index] = h('div', { style: { textDecoration: 'underline' } }, [
        'Total Cost',
      ])
      return
    }
    const values = data.map((item) => Number(item[column.property]))
    if (!values.every((value) => Number.isNaN(value))) {
      sums[index] = `$ ${values.reduce((prev, curr) => {
        const value = Number(curr)
        if (!Number.isNaN(value)) {
          return prev + curr
        } else {
          return prev
        }
      }, 0)}`
    } else {
      sums[index] = 'N/A'
    }
  })

  return sums
}

const tableData: Product[] = [
  {
    id: '12987122',
    name: 'Tom',
    amount1: '234',
    amount2: '3.2',
    amount3: 10,
  },
  {
    id: '12987123',
    name: 'Tom',
    amount1: '165',
    amount2: '4.43',
    amount3: 12,
  },
  {
    id: '12987124',
    name: 'Tom',
    amount1: '324',
    amount2: '1.9',
    amount3: 9,
  },
  {
    id: '12987125',
    name: 'Tom',
    amount1: '621',
    amount2: '2.2',
    amount3: 17,
  },
  {
    id: '12987126',
    name: 'Tom',
    amount1: '539',
    amount2: '4.1',
    amount3: 15,
  },
]
</script>
```

隐藏源代码

## 合并行或列 [​](#合并行或列)

多行或多列共用一个数据时，可以合并行或列。

通过给 table 传入`span-method`方法可以实现合并行或列， 方法的参数是一个对象，里面包含当前行 `row`、当前列 `column`、当前行号 `rowIndex`、当前列号 `columnIndex` 四个属性。 该函数可以返回一个包含两个元素的数组，第一个元素代表 `rowspan`，第二个元素代表 `colspan`。 也可以返回一个键名为 `rowspan` 和 `colspan` 的对象。

|
ID

 |

Name

 |

Amount 1

 |

Amount 2

 |

Amount 3

 |
| --- | --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_24_column_99" width="180"><col name="el-table_24_column_100" width="179"><col name="el-table_24_column_101" width="178"><col name="el-table_24_column_102" width="178"><col name="el-table_24_column_103" width="178"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="2" rowspan="1" class="el-table_24_column_99 el-table__cell"><div class="cell">12987122</div></td><td colspan="1" rowspan="1" class="el-table_24_column_101 el-table__cell"><div class="cell">234</div></td><td colspan="1" rowspan="1" class="el-table_24_column_102 el-table__cell"><div class="cell">3.2</div></td><td colspan="1" rowspan="1" class="el-table_24_column_103 el-table__cell"><div class="cell">10</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_24_column_99 el-table__cell"><div class="cell">12987123</div></td><td colspan="1" rowspan="1" class="el-table_24_column_100 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_24_column_101 el-table__cell"><div class="cell">165</div></td><td colspan="1" rowspan="1" class="el-table_24_column_102 el-table__cell"><div class="cell">4.43</div></td><td colspan="1" rowspan="1" class="el-table_24_column_103 el-table__cell"><div class="cell">12</div></td></tr><tr style="" class="el-table__row"><td colspan="2" rowspan="1" class="el-table_24_column_99 el-table__cell"><div class="cell">12987124</div></td><td colspan="1" rowspan="1" class="el-table_24_column_101 el-table__cell"><div class="cell">324</div></td><td colspan="1" rowspan="1" class="el-table_24_column_102 el-table__cell"><div class="cell">1.9</div></td><td colspan="1" rowspan="1" class="el-table_24_column_103 el-table__cell"><div class="cell">9</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_24_column_99 el-table__cell"><div class="cell">12987125</div></td><td colspan="1" rowspan="1" class="el-table_24_column_100 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_24_column_101 el-table__cell"><div class="cell">621</div></td><td colspan="1" rowspan="1" class="el-table_24_column_102 el-table__cell"><div class="cell">2.2</div></td><td colspan="1" rowspan="1" class="el-table_24_column_103 el-table__cell"><div class="cell">17</div></td></tr><tr style="" class="el-table__row"><td colspan="2" rowspan="1" class="el-table_24_column_99 el-table__cell"><div class="cell">12987126</div></td><td colspan="1" rowspan="1" class="el-table_24_column_101 el-table__cell"><div class="cell">539</div></td><td colspan="1" rowspan="1" class="el-table_24_column_102 el-table__cell"><div class="cell">4.1</div></td><td colspan="1" rowspan="1" class="el-table_24_column_103 el-table__cell"><div class="cell">15</div></td></tr></tbody></table>

|
ID

 |

Name

 |

Amount 1

 |

Amount 2

 |

Amount 3

 |
| --- | --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_25_column_104" width="180"><col name="el-table_25_column_105" width="179"><col name="el-table_25_column_106" width="178"><col name="el-table_25_column_107" width="178"><col name="el-table_25_column_108" width="178"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="2" class="el-table_25_column_104 el-table__cell"><div class="cell">12987122</div></td><td colspan="1" rowspan="1" class="el-table_25_column_105 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_25_column_106 el-table__cell"><div class="cell">234</div></td><td colspan="1" rowspan="1" class="el-table_25_column_107 el-table__cell"><div class="cell">3.2</div></td><td colspan="1" rowspan="1" class="el-table_25_column_108 el-table__cell"><div class="cell">10</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_25_column_105 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_25_column_106 el-table__cell"><div class="cell">165</div></td><td colspan="1" rowspan="1" class="el-table_25_column_107 el-table__cell"><div class="cell">4.43</div></td><td colspan="1" rowspan="1" class="el-table_25_column_108 el-table__cell"><div class="cell">12</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="2" class="el-table_25_column_104 el-table__cell"><div class="cell">12987124</div></td><td colspan="1" rowspan="1" class="el-table_25_column_105 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_25_column_106 el-table__cell"><div class="cell">324</div></td><td colspan="1" rowspan="1" class="el-table_25_column_107 el-table__cell"><div class="cell">1.9</div></td><td colspan="1" rowspan="1" class="el-table_25_column_108 el-table__cell"><div class="cell">9</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_25_column_105 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_25_column_106 el-table__cell"><div class="cell">621</div></td><td colspan="1" rowspan="1" class="el-table_25_column_107 el-table__cell"><div class="cell">2.2</div></td><td colspan="1" rowspan="1" class="el-table_25_column_108 el-table__cell"><div class="cell">17</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="2" class="el-table_25_column_104 el-table__cell"><div class="cell">12987126</div></td><td colspan="1" rowspan="1" class="el-table_25_column_105 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_25_column_106 el-table__cell"><div class="cell">539</div></td><td colspan="1" rowspan="1" class="el-table_25_column_107 el-table__cell"><div class="cell">4.1</div></td><td colspan="1" rowspan="1" class="el-table_25_column_108 el-table__cell"><div class="cell">15</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC10YWJsZVxuICAgICAgOmRhdGE9XCJ0YWJsZURhdGFcIlxuICAgICAgOnNwYW4tbWV0aG9kPVwiYXJyYXlTcGFuTWV0aG9kXCJcbiAgICAgIGJvcmRlclxuICAgICAgc3R5bGU9XCJ3aWR0aDogMTAwJVwiXG4gICAgPlxuICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiaWRcIiBsYWJlbD1cIklEXCIgd2lkdGg9XCIxODBcIiAvPlxuICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIC8+XG4gICAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhbW91bnQxXCIgc29ydGFibGUgbGFiZWw9XCJBbW91bnQgMVwiIC8+XG4gICAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhbW91bnQyXCIgc29ydGFibGUgbGFiZWw9XCJBbW91bnQgMlwiIC8+XG4gICAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhbW91bnQzXCIgc29ydGFibGUgbGFiZWw9XCJBbW91bnQgM1wiIC8+XG4gICAgPC9lbC10YWJsZT5cblxuICAgIDxlbC10YWJsZVxuICAgICAgOmRhdGE9XCJ0YWJsZURhdGFcIlxuICAgICAgOnNwYW4tbWV0aG9kPVwib2JqZWN0U3Bhbk1ldGhvZFwiXG4gICAgICBib3JkZXJcbiAgICAgIHN0eWxlPVwid2lkdGg6IDEwMCU7IG1hcmdpbi10b3A6IDIwcHhcIlxuICAgID5cbiAgICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImlkXCIgbGFiZWw9XCJJRFwiIHdpZHRoPVwiMTgwXCIgLz5cbiAgICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cIm5hbWVcIiBsYWJlbD1cIk5hbWVcIiAvPlxuICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiYW1vdW50MVwiIGxhYmVsPVwiQW1vdW50IDFcIiAvPlxuICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiYW1vdW50MlwiIGxhYmVsPVwiQW1vdW50IDJcIiAvPlxuICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiYW1vdW50M1wiIGxhYmVsPVwiQW1vdW50IDNcIiAvPlxuICAgIDwvZWwtdGFibGU+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB0eXBlIHsgVGFibGVDb2x1bW5DdHggfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmludGVyZmFjZSBVc2VyIHtcbiAgaWQ6IHN0cmluZ1xuICBuYW1lOiBzdHJpbmdcbiAgYW1vdW50MTogc3RyaW5nXG4gIGFtb3VudDI6IHN0cmluZ1xuICBhbW91bnQzOiBudW1iZXJcbn1cblxuaW50ZXJmYWNlIFNwYW5NZXRob2RQcm9wcyB7XG4gIHJvdzogVXNlclxuICBjb2x1bW46IFRhYmxlQ29sdW1uQ3R4PFVzZXI+XG4gIHJvd0luZGV4OiBudW1iZXJcbiAgY29sdW1uSW5kZXg6IG51bWJlclxufVxuXG5jb25zdCBhcnJheVNwYW5NZXRob2QgPSAoe1xuICByb3csXG4gIGNvbHVtbixcbiAgcm93SW5kZXgsXG4gIGNvbHVtbkluZGV4LFxufTogU3Bhbk1ldGhvZFByb3BzKSA9PiB7XG4gIGlmIChyb3dJbmRleCAlIDIgPT09IDApIHtcbiAgICBpZiAoY29sdW1uSW5kZXggPT09IDApIHtcbiAgICAgIHJldHVybiBbMSwgMl1cbiAgICB9IGVsc2UgaWYgKGNvbHVtbkluZGV4ID09PSAxKSB7XG4gICAgICByZXR1cm4gWzAsIDBdXG4gICAgfVxuICB9XG59XG5cbmNvbnN0IG9iamVjdFNwYW5NZXRob2QgPSAoe1xuICByb3csXG4gIGNvbHVtbixcbiAgcm93SW5kZXgsXG4gIGNvbHVtbkluZGV4LFxufTogU3Bhbk1ldGhvZFByb3BzKSA9PiB7XG4gIGlmIChjb2x1bW5JbmRleCA9PT0gMCkge1xuICAgIGlmIChyb3dJbmRleCAlIDIgPT09IDApIHtcbiAgICAgIHJldHVybiB7XG4gICAgICAgIHJvd3NwYW46IDIsXG4gICAgICAgIGNvbHNwYW46IDEsXG4gICAgICB9XG4gICAgfSBlbHNlIHtcbiAgICAgIHJldHVybiB7XG4gICAgICAgIHJvd3NwYW46IDAsXG4gICAgICAgIGNvbHNwYW46IDAsXG4gICAgICB9XG4gICAgfVxuICB9XG59XG5cbmNvbnN0IHRhYmxlRGF0YTogVXNlcltdID0gW1xuICB7XG4gICAgaWQ6ICcxMjk4NzEyMicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYW1vdW50MTogJzIzNCcsXG4gICAgYW1vdW50MjogJzMuMicsXG4gICAgYW1vdW50MzogMTAsXG4gIH0sXG4gIHtcbiAgICBpZDogJzEyOTg3MTIzJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhbW91bnQxOiAnMTY1JyxcbiAgICBhbW91bnQyOiAnNC40MycsXG4gICAgYW1vdW50MzogMTIsXG4gIH0sXG4gIHtcbiAgICBpZDogJzEyOTg3MTI0JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhbW91bnQxOiAnMzI0JyxcbiAgICBhbW91bnQyOiAnMS45JyxcbiAgICBhbW91bnQzOiA5LFxuICB9LFxuICB7XG4gICAgaWQ6ICcxMjk4NzEyNScsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgYW1vdW50MTogJzYyMScsXG4gICAgYW1vdW50MjogJzIuMicsXG4gICAgYW1vdW50MzogMTcsXG4gIH0sXG4gIHtcbiAgICBpZDogJzEyOTg3MTI2JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhbW91bnQxOiAnNTM5JyxcbiAgICBhbW91bnQyOiAnNC4xJyxcbiAgICBhbW91bnQzOiAxNSxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/rowspan-and-colspan.vue)_

vue

```
<template>
  <div>
    <el-table
      :data="tableData"
      :span-method="arraySpanMethod"
      border
      style="width: 100%"
    >
      <el-table-column prop="id" label="ID" width="180" />
      <el-table-column prop="name" label="Name" />
      <el-table-column prop="amount1" sortable label="Amount 1" />
      <el-table-column prop="amount2" sortable label="Amount 2" />
      <el-table-column prop="amount3" sortable label="Amount 3" />
    </el-table>

    <el-table
      :data="tableData"
      :span-method="objectSpanMethod"
      border
      style="width: 100%; margin-top: 20px"
    >
      <el-table-column prop="id" label="ID" width="180" />
      <el-table-column prop="name" label="Name" />
      <el-table-column prop="amount1" label="Amount 1" />
      <el-table-column prop="amount2" label="Amount 2" />
      <el-table-column prop="amount3" label="Amount 3" />
    </el-table>
  </div>
</template>

<script lang="ts" setup>
import type { TableColumnCtx } from 'element-plus'

interface User {
  id: string
  name: string
  amount1: string
  amount2: string
  amount3: number
}

interface SpanMethodProps {
  row: User
  column: TableColumnCtx<User>
  rowIndex: number
  columnIndex: number
}

const arraySpanMethod = ({
  row,
  column,
  rowIndex,
  columnIndex,
}: SpanMethodProps) => {
  if (rowIndex % 2 === 0) {
    if (columnIndex === 0) {
      return [1, 2]
    } else if (columnIndex === 1) {
      return [0, 0]
    }
  }
}

const objectSpanMethod = ({
  row,
  column,
  rowIndex,
  columnIndex,
}: SpanMethodProps) => {
  if (columnIndex === 0) {
    if (rowIndex % 2 === 0) {
      return {
        rowspan: 2,
        colspan: 1,
      }
    } else {
      return {
        rowspan: 0,
        colspan: 0,
      }
    }
  }
}

const tableData: User[] = [
  {
    id: '12987122',
    name: 'Tom',
    amount1: '234',
    amount2: '3.2',
    amount3: 10,
  },
  {
    id: '12987123',
    name: 'Tom',
    amount1: '165',
    amount2: '4.43',
    amount3: 12,
  },
  {
    id: '12987124',
    name: 'Tom',
    amount1: '324',
    amount2: '1.9',
    amount3: 9,
  },
  {
    id: '12987125',
    name: 'Tom',
    amount1: '621',
    amount2: '2.2',
    amount3: 17,
  },
  {
    id: '12987126',
    name: 'Tom',
    amount1: '539',
    amount2: '4.1',
    amount3: 15,
  },
]
</script>
```

隐藏源代码

## 自定义索引 [​](#自定义索引)

自定义 `type=index` 列的行号。

通过给 `type=index` 的列传入 index 属性，可以自定义索引。 该属性传入数字时，将作为索引的起始值。 也可以传入一个方法，它提供当前行的行号（从 `0` 开始）作为参数，返回值将作为索引展示。

|
 |

Date

 |

Name

 |

Address

 |
| --- | --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_26_column_109" width="48"><col name="el-table_26_column_110" width="180"><col name="el-table_26_column_111" width="180"><col name="el-table_26_column_112" width="485"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_26_column_109 el-table__cell"><div class="cell"><div>0</div></div></td><td colspan="1" rowspan="1" class="el-table_26_column_110 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_26_column_111 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_26_column_112 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_26_column_109 el-table__cell"><div class="cell"><div>2</div></div></td><td colspan="1" rowspan="1" class="el-table_26_column_110 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_26_column_111 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_26_column_112 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_26_column_109 el-table__cell"><div class="cell"><div>4</div></div></td><td colspan="1" rowspan="1" class="el-table_26_column_110 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_26_column_111 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_26_column_112 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_26_column_109 el-table__cell"><div class="cell"><div>6</div></div></td><td colspan="1" rowspan="1" class="el-table_26_column_110 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_26_column_111 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_26_column_112 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgOmRhdGE9XCJ0YWJsZURhdGFcIiBzdHlsZT1cIndpZHRoOiAxMDAlXCI+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiB0eXBlPVwiaW5kZXhcIiA6aW5kZXg9XCJpbmRleE1ldGhvZFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIHdpZHRoPVwiMTgwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgd2lkdGg9XCIxODBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiAvPlxuICA8L2VsLXRhYmxlPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IGluZGV4TWV0aG9kID0gKGluZGV4OiBudW1iZXIpID0+IHtcbiAgcmV0dXJuIGluZGV4ICogMlxufVxuY29uc3QgdGFibGVEYXRhID0gW1xuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDMnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgY2l0eTogJ0xvcyBBbmdlbGVzJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICB6aXA6ICdDQSA5MDAzNicsXG4gICAgdGFnOiAnSG9tZScsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMicsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgICB0YWc6ICdPZmZpY2UnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDQnLFxuICAgIG5hbWU6ICdUb20nLFxuICAgIHN0YXRlOiAnQ2FsaWZvcm5pYScsXG4gICAgY2l0eTogJ0xvcyBBbmdlbGVzJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgICB6aXA6ICdDQSA5MDAzNicsXG4gICAgdGFnOiAnSG9tZScsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgbmFtZTogJ1RvbScsXG4gICAgc3RhdGU6ICdDYWxpZm9ybmlhJyxcbiAgICBjaXR5OiAnTG9zIEFuZ2VsZXMnLFxuICAgIGFkZHJlc3M6ICdOby4gMTg5LCBHcm92ZSBTdCwgTG9zIEFuZ2VsZXMnLFxuICAgIHppcDogJ0NBIDkwMDM2JyxcbiAgICB0YWc6ICdPZmZpY2UnLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/custom-index.vue)_

vue

```
<template>
  <el-table :data="tableData" style="width: 100%">
    <el-table-column type="index" :index="indexMethod" />
    <el-table-column prop="date" label="Date" width="180" />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" />
  </el-table>
</template>

<script lang="ts" setup>
const indexMethod = (index: number) => {
  return index * 2
}
const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    tag: 'Home',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    tag: 'Office',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    tag: 'Home',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    tag: 'Office',
  },
]
</script>
```

隐藏源代码

## 表格布局 [​](#表格布局)

通过属性 [table-layout](https://developer.mozilla.org/en-US/docs/Web/CSS/table-layout) 可以指定表格中单元格、行和列的布局方式

fixedauto

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_27_column_113" width="299"><col name="el-table_27_column_114" width="297"><col name="el-table_27_column_115" width="297"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_27_column_113 el-table__cell"><div class="cell">2016-05-03</div></td><td colspan="1" rowspan="1" class="el-table_27_column_114 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_27_column_115 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_27_column_113 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_27_column_114 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_27_column_115 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_27_column_113 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_27_column_114 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_27_column_115 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_27_column_113 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_27_column_114 el-table__cell"><div class="cell">Tom</div></td><td colspan="1" rowspan="1" class="el-table_27_column_115 el-table__cell"><div class="cell">No. 189, Grove St, Los Angeles</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInRhYmxlTGF5b3V0XCIgY2xhc3M9XCJtYi0yXCI+XG4gICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cImZpeGVkXCI+Zml4ZWQ8L2VsLXJhZGlvLWJ1dHRvbj5cbiAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwiYXV0b1wiPmF1dG88L2VsLXJhZGlvLWJ1dHRvbj5cbiAgPC9lbC1yYWRpby1ncm91cD5cbiAgPGVsLXRhYmxlIDpkYXRhPVwidGFibGVEYXRhXCIgOnRhYmxlLWxheW91dD1cInRhYmxlTGF5b3V0XCI+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiYWRkcmVzc1wiIGxhYmVsPVwiQWRkcmVzc1wiIC8+XG4gIDwvZWwtdGFibGU+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IFRhYmxlSW5zdGFuY2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHRhYmxlTGF5b3V0ID0gcmVmPFRhYmxlSW5zdGFuY2VbJ3RhYmxlTGF5b3V0J10+KCdmaXhlZCcpXG5cbmNvbnN0IHRhYmxlRGF0YSA9IFtcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAzJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAyJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA0JyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAxJyxcbiAgICBuYW1lOiAnVG9tJyxcbiAgICBhZGRyZXNzOiAnTm8uIDE4OSwgR3JvdmUgU3QsIExvcyBBbmdlbGVzJyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/table-layout.vue)_

vue

```
<template>
  <el-radio-group v-model="tableLayout" class="mb-2">
    <el-radio-button value="fixed">fixed</el-radio-button>
    <el-radio-button value="auto">auto</el-radio-button>
  </el-radio-group>
  <el-table :data="tableData" :table-layout="tableLayout">
    <el-table-column prop="date" label="Date" />
    <el-table-column prop="name" label="Name" />
    <el-table-column prop="address" label="Address" />
  </el-table>
</template>

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

import type { TableInstance } from 'element-plus'

const tableLayout = ref<TableInstance['tableLayout']>('fixed')

const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

隐藏源代码

## Tooltip 自定义 2.9.4 [​](#tooltip-自定义)

您可以使用 `tooltip-formatter` 自定义 Tooltip 提示内容。

|
extends table formatter

 |

formatter object

 |

with vnode

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 720px;"><colgroup><col name="el-table_28_column_116" width="240"><col name="el-table_28_column_117" width="240"><col name="el-table_28_column_118" width="240"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_28_column_116 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">Lohrbergstr. 86c, Süd Lilli, Saarland</div></td><td colspan="1" rowspan="1" class="el-table_28_column_117 el-table__cell"><div class="cell el-tooltip" style="width: 238px;"><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">Office</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">Home</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">Park</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">Garden</span></span></div></td><td colspan="1" rowspan="1" class="el-table_28_column_118 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">https://github.com/element-plus/element-plus/issues</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_28_column_116 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">760 A Street, South Frankfield, Illinois</div></td><td colspan="1" rowspan="1" class="el-table_28_column_117 el-table__cell"><div class="cell el-tooltip" style="width: 238px;"><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">error</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">warning</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">success</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">info</span></span></div></td><td colspan="1" rowspan="1" class="el-table_28_column_118 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">https://github.com/element-plus/element-plus/pulls</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_28_column_116 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">Arnold-Ohletz-Str. 41a, Alt Malinascheid, Thüringen</div></td><td colspan="1" rowspan="1" class="el-table_28_column_117 el-table__cell"><div class="cell el-tooltip" style="width: 238px;"><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">one</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">two</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">three</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">four</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">five</span></span></div></td><td colspan="1" rowspan="1" class="el-table_28_column_118 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">https://github.com/element-plus/element-plus/discussions</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_28_column_116 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">23618 Windsor Drive, West Ricardoview, Idaho</div></td><td colspan="1" rowspan="1" class="el-table_28_column_117 el-table__cell"><div class="cell el-tooltip" style="width: 238px;"><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">blue</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">white</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">dark</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">gray</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">red</span></span><span data-v-90c15426="" class="el-tag el-tag--primary el-tag--light tag-item"><span class="el-tag__content">bright</span></span></div></td><td colspan="1" rowspan="1" class="el-table_28_column_118 el-table__cell"><div class="cell el-tooltip" style="width: 238px;">https://github.com/element-plus/element-plus/actions</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGVcbiAgICA6ZGF0YT1cInRhYmxlRGF0YVwiXG4gICAgc2hvdy1vdmVyZmxvdy10b29sdGlwXG4gICAgOnRvb2x0aXAtZm9ybWF0dGVyPVwidGFibGVSb3dGb3JtYXR0ZXJcIlxuICAgIHN0eWxlPVwid2lkdGg6IDEwMCVcIlxuICA+XG4gICAgPGVsLXRhYmxlLWNvbHVtblxuICAgICAgcHJvcD1cImFkZHJlc3NcIlxuICAgICAgbGFiZWw9XCJleHRlbmRzIHRhYmxlIGZvcm1hdHRlclwiXG4gICAgICB3aWR0aD1cIjI0MFwiXG4gICAgLz5cbiAgICA8IS0tIEB2dWUtZ2VuZXJpYyB7VGFibGVEYXRhfSAtLT5cbiAgICA8ZWwtdGFibGUtY29sdW1uXG4gICAgICBwcm9wPVwidGFnc1wiXG4gICAgICBsYWJlbD1cImZvcm1hdHRlciBvYmplY3RcIlxuICAgICAgd2lkdGg9XCIyNDBcIlxuICAgICAgOnRvb2x0aXAtZm9ybWF0dGVyPVwiKHsgcm93IH0pID0+IHJvdy50YWdzLmpvaW4oJywgJylcIlxuICAgID5cbiAgICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD1cInsgcm93IH1cIj5cbiAgICAgICAgPGVsLXRhZ1xuICAgICAgICAgIHYtZm9yPVwidGFnIGluIHJvdy50YWdzXCJcbiAgICAgICAgICA6a2V5PVwidGFnXCJcbiAgICAgICAgICBjbGFzcz1cInRhZy1pdGVtXCJcbiAgICAgICAgICB0eXBlPVwicHJpbWFyeVwiXG4gICAgICAgID5cbiAgICAgICAgICB7eyB0YWcgfX1cbiAgICAgICAgPC9lbC10YWc+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtdGFibGUtY29sdW1uPlxuICAgIDxlbC10YWJsZS1jb2x1bW5cbiAgICAgIHByb3A9XCJ1cmxcIlxuICAgICAgbGFiZWw9XCJ3aXRoIHZub2RlXCJcbiAgICAgIHdpZHRoPVwiMjQwXCJcbiAgICAgIDp0b29sdGlwLWZvcm1hdHRlcj1cIndpdGhWTm9kZVwiXG4gICAgLz5cbiAgPC9lbC10YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBoIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgRWxMaW5rLCB0eXBlIFRhYmxlVG9vbHRpcERhdGEgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbnR5cGUgVGFibGVEYXRhID0ge1xuICBhZGRyZXNzOiBzdHJpbmdcbiAgdGFnczogc3RyaW5nW11cbiAgdXJsOiBzdHJpbmdcbn1cblxuY29uc3QgdGFibGVEYXRhOiBUYWJsZURhdGFbXSA9IFtcbiAge1xuICAgIGFkZHJlc3M6ICdMb2hyYmVyZ3N0ci4gODZjLCBTw7xkIExpbGxpLCBTYWFybGFuZCcsXG4gICAgdGFnczogWydPZmZpY2UnLCAnSG9tZScsICdQYXJrJywgJ0dhcmRlbiddLFxuICAgIHVybDogJ2h0dHBzOi8vZ2l0aHViLmNvbS9lbGVtZW50LXBsdXMvZWxlbWVudC1wbHVzL2lzc3VlcycsXG4gIH0sXG4gIHtcbiAgICBhZGRyZXNzOiAnNzYwIEEgU3RyZWV0LCBTb3V0aCBGcmFua2ZpZWxkLCBJbGxpbm9pcycsXG4gICAgdGFnczogWydlcnJvcicsICd3YXJuaW5nJywgJ3N1Y2Nlc3MnLCAnaW5mbyddLFxuICAgIHVybDogJ2h0dHBzOi8vZ2l0aHViLmNvbS9lbGVtZW50LXBsdXMvZWxlbWVudC1wbHVzL3B1bGxzJyxcbiAgfSxcbiAge1xuICAgIGFkZHJlc3M6ICdBcm5vbGQtT2hsZXR6LVN0ci4gNDFhLCBBbHQgTWFsaW5hc2NoZWlkLCBUaMO8cmluZ2VuJyxcbiAgICB0YWdzOiBbJ29uZScsICd0d28nLCAndGhyZWUnLCAnZm91cicsICdmaXZlJ10sXG4gICAgdXJsOiAnaHR0cHM6Ly9naXRodWIuY29tL2VsZW1lbnQtcGx1cy9lbGVtZW50LXBsdXMvZGlzY3Vzc2lvbnMnLFxuICB9LFxuICB7XG4gICAgYWRkcmVzczogJzIzNjE4IFdpbmRzb3IgRHJpdmUsIFdlc3QgUmljYXJkb3ZpZXcsIElkYWhvJyxcbiAgICB0YWdzOiBbJ2JsdWUnLCAnd2hpdGUnLCAnZGFyaycsICdncmF5JywgJ3JlZCcsICdicmlnaHQnXSxcbiAgICB1cmw6ICdodHRwczovL2dpdGh1Yi5jb20vZWxlbWVudC1wbHVzL2VsZW1lbnQtcGx1cy9hY3Rpb25zJyxcbiAgfSxcbl1cblxuY29uc3QgdGFibGVSb3dGb3JtYXR0ZXIgPSAoZGF0YTogVGFibGVUb29sdGlwRGF0YTxUYWJsZURhdGE+KSA9PiB7XG4gIHJldHVybiBgJHtkYXRhLmNlbGxWYWx1ZX06IHRhYmxlIGZvcm1hdHRlcmBcbn1cblxuY29uc3Qgd2l0aFZOb2RlID0gKGRhdGE6IFRhYmxlVG9vbHRpcERhdGE8VGFibGVEYXRhPikgPT4ge1xuICByZXR1cm4gaChFbExpbmssIHsgdHlwZTogJ3ByaW1hcnknLCBocmVmOiBkYXRhLmNlbGxWYWx1ZSB9LCAoKSA9PlxuICAgIGgoJ3NwYW4nLCBudWxsLCBkYXRhLmNlbGxWYWx1ZSlcbiAgKVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG5wIHtcbiAgbWFyZ2luOiAxMHB4O1xuICBwYWRkaW5nOiAwO1xufVxuLnRhZy1pdGVtICsgLnRhZy1pdGVtIHtcbiAgbWFyZ2luLWxlZnQ6IDVweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table/tooltip-formatter.vue)_

vue

```
<template>
  <el-table
    :data="tableData"
    show-overflow-tooltip
    :tooltip-formatter="tableRowFormatter"
    style="width: 100%"
  >
    <el-table-column
      prop="address"
      label="extends table formatter"
      width="240"
    />
    <!-- @vue-generic {TableData} -->
    <el-table-column
      prop="tags"
      label="formatter object"
      width="240"
      :tooltip-formatter="({ row }) => row.tags.join(', ')"
    >
      <template #default="{ row }">
        <el-tag
          v-for="tag in row.tags"
          :key="tag"
          class="tag-item"
          type="primary"
        >
          {{ tag }}
        </el-tag>
      </template>
    </el-table-column>
    <el-table-column
      prop="url"
      label="with vnode"
      width="240"
      :tooltip-formatter="withVNode"
    />
  </el-table>
</template>

<script lang="ts" setup>
import { h } from 'vue'
import { ElLink, type TableTooltipData } from 'element-plus'

type TableData = {
  address: string
  tags: string[]
  url: string
}

const tableData: TableData[] = [
  {
    address: 'Lohrbergstr. 86c, Süd Lilli, Saarland',
    tags: ['Office', 'Home', 'Park', 'Garden'],
    url: 'https://github.com/element-plus/element-plus/issues',
  },
  {
    address: '760 A Street, South Frankfield, Illinois',
    tags: ['error', 'warning', 'success', 'info'],
    url: 'https://github.com/element-plus/element-plus/pulls',
  },
  {
    address: 'Arnold-Ohletz-Str. 41a, Alt Malinascheid, Thüringen',
    tags: ['one', 'two', 'three', 'four', 'five'],
    url: 'https://github.com/element-plus/element-plus/discussions',
  },
  {
    address: '23618 Windsor Drive, West Ricardoview, Idaho',
    tags: ['blue', 'white', 'dark', 'gray', 'red', 'bright'],
    url: 'https://github.com/element-plus/element-plus/actions',
  },
]

const tableRowFormatter = (data: TableTooltipData<TableData>) => {
  return `${data.cellValue}: table formatter`
}

const withVNode = (data: TableTooltipData<TableData>) => {
  return h(ElLink, { type: 'primary', href: data.cellValue }, () =>
    h('span', null, data.cellValue)
  )
}
</script>

<style scoped>
p {
  margin: 10px;
  padding: 0;
}
.tag-item + .tag-item {
  margin-left: 5px;
}
</style>
```

隐藏源代码

## Table API [​](#table-api)

### Table 属性 [​](#table-属性)

| 属性名 | 说明 | 类型 | Default |
| --- | --- | --- | --- |
| data | 表数据 | `array` | \[\] |
| height | table 的高度。 默认为自动高度。 如果 height 为 number 类型，单位 px；如果 height 为 string 类型，则这个高度会设置为 Table 的 style.height 的值，Table 的高度会受控于外部样式。 | `string` / `number` | — |
| max-height | table 的最大高度。 合法的值为数字或者单位为 px 的高度。 | `string` / `number` | — |
| stripe | 是否为斑马纹 table | `boolean` | false |
| border | 是否带有纵向边框 | `boolean` | false |
| size | Table 的尺寸 | `enum` | — |
| fit | 列的宽度是否自撑开 | `boolean` | true |
| show-header | 是否显示表头 | `boolean` | true |
| highlight-current-row | 是否要高亮当前行 | `boolean` | false |
| current-row-key | 当前行的 key，只写属性 | `string` / `number` | — |
| row-class-name | 行的 className 的回调方法，也可以使用字符串为所有行设置一个固定的 className。 | `Function` / `string` | — |
| row-style | 行的 style 的回调方法，也可以使用一个固定的 Object 为所有行设置一样的 Style。 | `Function` / `object` | — |
| cell-class-name | 单元格的 className 的回调方法，也可以使用字符串为所有单元格设置一个固定的 className。 | `Function` / `string` | — |
| cell-style | 单元格的 style 的回调方法，也可以使用一个固定的 Object 为所有单元格设置一样的 Style。 | `Function` / `object` | — |
| header-row-class-name | 表头行的 className 的回调方法，也可以使用字符串为所有表头行设置一个固定的 className。 | `Function` / `string` | — |
| header-row-style | 表头行的 style 的回调方法，也可以使用一个固定的 Object 为所有表头行设置一样的 Style。 | `Function` / `object` | — |
| header-cell-class-name | 表头单元格的 className 的回调方法，也可以使用字符串为所有表头单元格设置一个固定的 className。 | `Function` / `string` | — |
| header-cell-style | 表头单元格的 style 的回调方法，也可以使用一个固定的 Object 为所有表头单元格设置一样的 Style。 | `Function` / `object` | — |
| row-key | 行数据的 Key，用来优化 Table 的渲染； 在使用`reserve-selection`功能与显示树形数据时，该属性是必填的。 类型为 String 时，支持多层访问：`user.info.id`，但不支持 `user.info[0].id`，此种情况请使用 `Function`。 | `Function` / `string` | — |
| empty-text | 空数据时显示的文本内容， 也可以通过 `#empty` 设置 | `string` | No Data |
| default-expand-all | 是否默认展开所有行，当 Table 包含展开行存在或者为树形表格时有效 | `boolean` | false |
| expand-row-keys | 可以通过该属性设置 Table 目前的展开行，需要设置 row-key 属性才能使用，该属性为展开行的 keys 数组。 | `array` | — |
| default-sort | 默认的排序列的 prop 和顺序。 它的 `prop` 属性指定默认的排序的列，`order` 指定默认排序的顺序 | `object` | 如果设置了`prop`，但没有设置 `order`，那么 `order`将被默认设置为ascending |
| tooltip-effect | 溢出的 tooltip 的 `effect` | `enum` | dark |
| tooltip-options 2.2.28 | 溢出 tooltip 的选项，[参见下述 tooltip 组件](https://element-plus.org/zh-CN/component/tooltip.html#attributes) | `object` | `object` |
| append-filter-panel-to 2.8.4 | 挂载到哪个 DOM 元素 | `string` | — |
| show-summary | 是否在表尾显示合计行 | `boolean` | false |
| sum-text | 显示摘要行第一列的文本 | `string` | Sum |
| summary-method | 自定义的合计计算方法 | `Function` | — |
| span-method | 合并行或列的计算方法 | `Function` | — |
| select-on-indeterminate | 在多选表格中，当仅有部分行被选中时，点击表头的多选框时的行为。 若为 true，则选中所有行；若为 false，则取消选择所有行 | `boolean` | true |
| indent | 展示树形数据时，树节点的缩进 | `number` | 16 |
| lazy | 是否懒加载子节点数据 | `boolean` | false |
| load | 加载子节点数据的函数，`lazy` 为 true 时生效 | `Function` | — |
| tree-props | 渲染嵌套数据的配置选项 | `object` | `object` |
| table-layout | 设置表格单元、行和列的布局方式 | `enum` | fixed |
| scrollbar-always-on | 总是显示滚动条 | `boolean` | false |
| show-overflow-tooltip | 是否隐藏额外内容并在单元格悬停时使用 Tooltip 显示它们。这将影响全部列的展示，详请参考[tooltip-options](#table-attributes) | `boolean` / [`object`](#table-attributes) 2.3.7 | — |
| flexible 2.2.1 | 确保主轴的最小尺寸，以便不超过内容 | `boolean` | false |
| scrollbar-tabindex 2.8.3 | body 的滚动条的包裹容器 tabindex | `string` / `number` | — |
| allow-drag-last-column 2.9.2 | 是否允许拖动最后一列 | `boolean` | true |
| tooltip-formatter 2.9.4 | 自定义 `show-overflow-tooltip` 时的 tooltip 内容 | `Function` | — |
| preserve-expanded-content 2.9.7 | 在折叠后是否在DOM中保留展开行内容 | `boolean` | false |
| native-scrollbar 2.10.5 | 是否使用原生滚动条样式 | `boolean` | false |
| row-expandable 2.13.2 | 启用可展开行，当表格具有 type="expand" 列时有效 | `Function` | — |

### Table 事件 [​](#table-事件)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| select | 当用户手动勾选数据行的 Checkbox 时触发的事件 | `Function` |
| select-all | 当用户手动勾选全选 Checkbox 时触发的事件 | `Function` |
| selection-change | 当选择项发生变化时会触发该事件 | `Function` |
| cell-mouse-enter | 当单元格 hover 进入时会触发该事件 | `Function` |
| cell-mouse-leave | 当单元格 hover 退出时会触发该事件 | `Function` |
| cell-click | 当某个单元格被点击时会触发该事件 | `Function` |
| cell-dblclick | 当某个单元格被双击击时会触发该事件 | `Function` |
| cell-contextmenu | 当某个单元格被鼠标右键点击时会触发该事件 | `Function` |
| row-click | 当某一行被点击时会触发该事件 | `Function` |
| row-contextmenu | 当某一行被鼠标右键点击时会触发该事件 | `Function` |
| row-dblclick | 当某一行被双击时会触发该事件 | `Function` |
| header-click | 当某一列的表头被点击时会触发该事件 | `Function` |
| header-contextmenu | 当某一列的表头被鼠标右键点击时触发该事件 | `Function` |
| sort-change | 当表格的排序条件发生变化的时候会触发该事件 | `Function` |
| filter-change | 当表格的过滤条件发生变化的时候会触发该事件 | `Function` |
| current-change | 当表格的当前行发生变化的时候会触发该事件，如果要高亮当前行，请打开表格的 highlight-current-row 属性 | `Function` |
| header-dragend | 当拖动表头改变了列的宽度的时候会触发该事件 | `Function` |
| expand-change | 当用户对某一行展开或者关闭的时候会触发该事件（展开行时，回调的第二个参数为 expandedRows；树形表格时第二参数为 expanded） | `Function` |
| scroll 2.9.0 | 表格被用户滚动后触发 | `Function` |

### Table 插槽 [​](#table-插槽)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | Table-column |
| append | 插入至表格最后一行之后的内容， 如果需要对表格的内容进行无限滚动操作，可能需要用到这个 slot。 若表格有合计行，该 slot 会位于合计行之上。 | — |
| empty | 当数据为空时自定义的内容 | — |

### Table Exposes [​](#table-exposes)

| 方法名 | 说明 | Type |
| --- | --- | --- |
| clearSelection | 用于多选表格，清空用户的选择 | `Function` |
| getSelectionRows | 返回当前选中的行 | `Function` |
| getHalfSelectionRows 2.14.2 | 返回当前半选中的行 | `Function` |
| toggleRowSelection | 用于多选表格，切换某一行的选中状态， 如果使用了第二个参数，则可直接设置这一行选中与否 | `Function` |
| toggleAllSelection | 用于多选表格，切换全选和全不选 | `Function` |
| toggleRowExpansion | 用于可扩展的表格或树表格，如果某行被扩展，则切换。 使用第二个参数，您可以直接设置该行应该被扩展或折叠。 | `Function` |
| setCurrentRow | 用于单选表格，设定某一行为选中行， 如果调用时不加参数，则会取消目前高亮行的选中状态。 | `Function` |
| clearSort | 用于清空排序条件，数据会恢复成未排序的状态 | `Function` |
| clearFilter | 传入由`columnKey` 组成的数组以清除指定列的过滤条件。 如果没有参数，清除所有过滤器 | `Function` |
| doLayout | 对 Table 进行重新布局。 当表格可见性变化时，您可能需要调用此方法以获得正确的布局 | `Function` |
| sort | 手动排序表格。 参数 `prop` 属性指定排序列，`order` 指定排序顺序。 | `Function` |
| scrollTo | 滚动到一组特定坐标 | `Function` |
| setScrollTop | 设置垂直滚动位置 | `Function` |
| setScrollLeft | 设置水平滚动位置 | `Function` |
| columns 2.7.6 | 获取表列的 context | `array` |
| updateKeyChildren 2.8.4 | 适用于 lazy Table, 需要设置 `rowKey`, 更新 key children | `Function` |

## Table-column API [​](#table-column-api)

### Table-column 属性 [​](#table-column-属性)

| 属性名 | 说明 | Type | 默认值 |
| --- | --- | --- | --- |
| type | 对应列的类型。 如果设置了`selection`则显示多选框； 如果设置了 `index` 则显示该行的索引（从 1 开始计算）； 如果设置了 `expand` 则显示为一个可展开的按钮 | `enum` | default |
| index | 如果设置了 `type=index`，可以通过传递 `index` 属性来自定义索引 | `number` / `Function` | — |
| label | 显示的标题 | `string` | — |
| column-key | column 的 key， column 的 key， 如果需要使用 filter-change 事件，则需要此属性标识是哪个 column 的筛选条件 | `string` | — |
| prop | 字段名称 对应列内容的字段名， 也可以使用 `property`属性 | `string` | — |
| width | 对应列的宽度 | `string` / `number` | '' |
| min-width | 对应列的最小宽度， 对应列的最小宽度， 与 `width` 的区别是 `width` 是固定的，`min-width` 会把剩余宽度按比例分配给设置了 `min-width` 的列 | `string` / `number` | '' |
| fixed | 列是否固定在左侧或者右侧。 `true` 表示固定在左侧 | `enum` / `boolean` | false |
| render-header | 列标题 Label 区域渲染使用的 Function | `Function` | — |
| sortable | 对应列是否可以排序， 如果设置为 'custom'，则代表用户希望远程排序，需要监听 Table 的 sort-change 事件 | `boolean` / `string` | false |
| sort-method | 指定数据按照哪个属性进行排序，仅当`sortable`设置为`true`的时候有效。 应该如同 Array.sort 那样返回一个 Number | `Function` | — |
| sort-by | 指定数据按照哪个属性进行排序，仅当 sortable 设置为 true 且没有设置 sort-method 的时候有效。 如果 sort-by 为数组，则先按照第 1 个属性排序，如果第 1 个相等，再按照第 2 个排序，以此类推 | `Function` / `string` / `array` | — |
| sort-orders | 数据在排序时所使用排序策略的轮转顺序，仅当 sortable 为 true 时有效。 需传入一个数组，随着用户点击表头，该列依次按照数组中元素的顺序进行排序 | `object` | \['ascending', 'descending', null\] |
| resizable | 对应列是否可以通过拖动改变宽度（需要在 el-table 上设置 border 属性为真） | `boolean` | true |
| formatter | 用来格式化内容 | `Function` | — |
| show-overflow-tooltip | 当内容过长被隐藏时显示 tooltip | `boolean` / [`object`](#table-attributes) 2.2.28 | undefined |
| align | 对齐方式 | `enum` | left |
| header-align | 表头对齐方式， 若不设置该项，则使用表格的对齐方式 | `enum` | left |
| class-name | 列的 className | `string` | — |
| label-class-name | 当前列标题的自定义类名 | `string` | — |
| selectable | 仅对 type=selection 的列有效，类型为 Function，Function 的返回值用来决定这一行的 CheckBox 是否可以勾选 | `Function` | — |
| reserve-selection | 数据刷新后是否保留选项，仅对 `type=selection` 的列有效， 请注意， 需指定 `row-key` 来让这个功能生效。 | `boolean` | false |
| filters | 数据过滤的选项， 数组格式，数组中的元素需要有 text 和 value 属性。 数组中的每个元素都需要有 text 和 value 属性。 | `array` | ::: |
| filter-placement | 过滤弹出框的定位 | `enum` | — |
| filter-class-name 2.5.0 | 过滤弹出框的 className | `string` | — |
| filter-multiple | 数据过滤的选项是否多选 | `boolean` | true |
| filter-method | 数据过滤使用的方法， 如果是多选的筛选项，对每一条数据会执行多次，任意一次返回 true 就会显示。 | `Function` | ::: |
| filtered-value | 选中的数据过滤项，如果需要自定义表头过滤的渲染方式，可能会需要此属性。 | `array` | — |
| tooltip-formatter 2.9.4 | 使用 `show-overflow-tooltip` 时自定义 tooltip 内容 | `Function` | — |

### Table-column 插槽 [​](#table-column-插槽)

| 插槽名 | 说明 | 类型 |
| --- | --- | --- |
| default | 自定义列的内容 | `object` |
| header | 自定义表头的内容， | `object` |
| filter-icon 2.7.8 | 自定义 filter 图标 | `object` |
| expand 2.10.0 | 展开列的自定义内容 从 v2.13.2 开始支持 `expandable` 属性。 | `object` |

## Type Declarations [​](#type-declarations)

显示类型声明

ts

```
interface Sort {
  prop: string
  order: 'ascending' | 'descending'
  init?: any
  silent?: any
}

interface TreeNode {
  expanded?: boolean
  loading?: boolean
  noLazyChildren?: boolean
  indent?: number
  level?: number
  display?: boolean
}

type DefaultRow = Record<PropertyKey, any>

type TableColumnCtx<T extends DefaultRow = DefaultRow> = {
  id: string
  realWidth: number | null
  type: string
  label: string
  className: string
  labelClassName: string
  property: string
  prop: string
  width?: string | number
  minWidth: string | number
  renderHeader: (data: CI<T>) => VNode
  sortable: boolean | string
  sortMethod: (a: T, b: T) => number
  sortBy: string | ((row: T, index: number, array?: T[]) => string) | string[]
  resizable: boolean
  columnKey: string
  rawColumnKey: string
  align: string
  headerAlign: string
  showOverflowTooltip?: boolean | TableOverflowTooltipOptions
  tooltipFormatter?: TableOverflowTooltipFormatter<T>
  fixed: boolean | string
  formatter: (
    row: T,
    column: TableColumnCtx<T>,
    cellValue: any,
    index: number
  ) => VNode | string
  selectable: (row: T, index: number) => boolean
  reserveSelection: boolean
  filterMethod: FilterMethods<T>
  filteredValue: string[]
  filters: Filters
  filterPlacement: string
  filterMultiple: boolean
  filterClassName: string
  index: number | ((index: number) => number)
  sortOrders: (TableSortOrder | null)[]
  renderCell: (data: any) => VNode | VNode[]
  colSpan: number
  rowSpan: number
  children?: TableColumnCtx<T>[]
  level: number
  filterable: boolean | FilterMethods<T> | Filters
  order: TableSortOrder | null
  isColumnGroup: boolean
  isSubColumn: boolean
  columns: TableColumnCtx<T>[]
  getColumnIndex: () => number
  no: number
  filterOpened?: boolean
  renderFilterIcon?: (scope: any) => VNode
  renderExpand?: (scope: any) => VNode
}
```

## 常见问题解答（FAQ） [​](#常见问题解答-faq)

#### 如何为 `el-table-column` 推断正确的插槽类型？ [​](#如何为-el-table-column-推断正确的插槽类型)

`el-table-column` 是一个泛型组件。 如果 TypeScript 无法从上下文中推断其插槽的行类型，请在 `el-table-column` 前紧挨着添加 Vue 的 `@vue-generic` 指令注释，并显式传入行类型。 更多细节请参考 Vue 文档 [Generics](https://vuejs.org/api/sfc-script-setup.html#generics).

vue

```
<template>
  <el-table :data="tableData">
    <!-- @vue-generic {User} -->
    <el-table-column label="Name">
      <template #default="{ row }">
        {{ row.name }}
      </template>
    </el-table-column>
  </el-table>
</template>

<script lang="ts" setup>
interface User {
  name: string
  address: string
}

const tableData: User[] = [
  {
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>
```

#### 如何在表格中使用图像预览？ [​](#如何在表格中使用图像预览)

vue

```
<template>
  <el-table-column width="180">
    <template #default="scope">
      <el-image preview-teleported :preview-src-list="srcList" />
    </template>
  </el-table-column>
</template>
```

#### 当使用 DOM 模板时，为什么列没有渲染？ [​](#当使用-dom-模板时-为什么列没有渲染)

典型问题： [#5046](https://github.com/element-plus/element-plus/issues/5046) [#5862](https://github.com/element-plus/element-plus/issues/5862) [#6919](https://github.com/element-plus/element-plus/issues/6919)

这是因为 HTML 定义只允许一些特定元素省略关闭标签，最常见的是 `<input>` 和 `<img>`。 对于任意其他元素，如果你省略了关闭标签，原生的 HTML 解析器会认为你从未关闭打开的标签。

详情请参阅 [Vue 文档](https://vuejs.org/guide/essentials/component-basics.html#self-closing-tags)。

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/table) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/table.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/table.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/24290011?v=4&size=64)](https://github.com/xingyixiang)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/30046649?v=4&size=64)](https://github.com/MrWeilian)[![](https://avatars.githubusercontent.com/u/43257608?v=4&size=64)](https://github.com/Liao-js)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/45098544?v=4&size=64)](https://github.com/tuzixiangs)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/38874640?v=4&size=64)](https://github.com/wNing50)[![](https://avatars.githubusercontent.com/u/108655466?v=4&size=64)](https://github.com/Karolis-Stoncius)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/59350883?v=4&size=64)](https://github.com/init-qy)[![](https://avatars.githubusercontent.com/u/25472916?v=4&size=64)](https://github.com/wiidede)[![](https://avatars.githubusercontent.com/u/45122329?v=4&size=64)](https://github.com/cokemine)[![](https://avatars.githubusercontent.com/u/46664126?v=4&size=64)](https://github.com/btnkr)[![](https://avatars.githubusercontent.com/u/126545033?v=4&size=64)](https://github.com/dhj-l)[![](https://avatars.githubusercontent.com/u/54931083?v=4&size=64)](https://github.com/wjp980108)[![](https://avatars.githubusercontent.com/u/30883395?v=4&size=64)](https://github.com/webvs2)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/17523626?v=4&size=64)](https://github.com/dowinweb)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/30335393?v=4&size=64)](https://github.com/justwiner)[![](https://avatars.githubusercontent.com/u/67093787?v=4&size=64)](https://github.com/tinyfind)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/31885971?v=4&size=64)](https://github.com/wonderl17)[![](https://avatars.githubusercontent.com/u/26755049?v=4&size=64)](https://github.com/qq282126990)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/9188028?v=4&size=64)](https://github.com/406087475)[![](https://avatars.githubusercontent.com/u/71749650?v=4&size=64)](https://github.com/qeTM)[![](https://avatars.githubusercontent.com/u/45625953?v=4&size=64)](https://github.com/an501920078)[![](https://avatars.githubusercontent.com/u/158829893?v=4&size=64)](https://github.com/JoiePink)[![](https://avatars.githubusercontent.com/u/67700142?v=4&size=64)](https://github.com/vueWorker-x)[![](https://avatars.githubusercontent.com/u/31912749?v=4&size=64)](https://github.com/KeroZhai)[![](https://avatars.githubusercontent.com/u/33254923?v=4&size=64)](https://github.com/yicheny)[![](https://avatars.githubusercontent.com/u/127294190?v=4&size=64)](https://github.com/xuhuaiyu24)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/96716634?v=4&size=64)](https://github.com/ylcjwq)[![](https://avatars.githubusercontent.com/u/45786118?v=4&size=64)](https://github.com/realainov)[![](https://avatars.githubusercontent.com/u/27413795?v=4&size=64)](https://github.com/SpanManX)[![](https://avatars.githubusercontent.com/u/33643257?v=4&size=64)](https://github.com/OFreshman)[![](https://avatars.githubusercontent.com/u/59353463?v=4&size=64)](https://github.com/xiaohe0601)[![](https://avatars.githubusercontent.com/u/59367231?v=4&size=64)](https://github.com/qp666)[![](https://avatars.githubusercontent.com/u/45218946?v=4&size=64)](https://github.com/comp-squirrel)[![](https://avatars.githubusercontent.com/u/82485978?v=4&size=64)](https://github.com/EralChen)[![](https://avatars.githubusercontent.com/u/16640248?v=4&size=64)](https://github.com/chengang4505)[![](https://avatars.githubusercontent.com/u/132551120?v=4&size=64)](https://github.com/YiMo1)[![](https://avatars.githubusercontent.com/u/26403700?v=4&size=64)](https://github.com/blesstosam)[![](https://avatars.githubusercontent.com/u/8591261?v=4&size=64)](https://github.com/zeyongTsai)[![](https://avatars.githubusercontent.com/u/70090558?v=4&size=64)](https://github.com/starryeve)[![](https://avatars.githubusercontent.com/u/48341368?v=4&size=64)](https://github.com/HaceraI)[![](https://avatars.githubusercontent.com/u/204166003?v=4&size=64)](https://github.com/Putia3)[![](https://avatars.githubusercontent.com/u/22910740?v=4&size=64)](https://github.com/StephenKe)[![](https://avatars.githubusercontent.com/u/839559?v=4&size=64)](https://github.com/FrankFang)[![](https://avatars.githubusercontent.com/u/23010875?v=4&size=64)](https://github.com/bartoszrudzinski)[![](https://avatars.githubusercontent.com/u/18254135?v=4&size=64)](https://github.com/zhengbangbo)[![](https://avatars.githubusercontent.com/u/23442840?v=4&size=64)](https://github.com/liunnn1994)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/20264397?v=4&size=64)](https://github.com/Simplifer)[![](https://avatars.githubusercontent.com/u/29966471?v=4&size=64)](https://github.com/tiandaoyi)[![](https://avatars.githubusercontent.com/u/6063358?v=4&size=64)](https://github.com/xxholly32)[![](https://avatars.githubusercontent.com/u/101238421?v=4&size=64)](https://github.com/acyza)[![](https://avatars.githubusercontent.com/u/2098770?v=4&size=64)](https://github.com/liuyutao)[![](https://avatars.githubusercontent.com/u/33687038?v=4&size=64)](https://github.com/guozi9999)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/38490578?v=4&size=64)](https://github.com/yuyinws)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/42139754?v=4&size=64)](https://github.com/zyyv)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/144224541?v=4&size=64)](https://github.com/xixiIBN5100)[![](https://avatars.githubusercontent.com/u/59329360?v=4&size=64)](https://github.com/electroluxcode)[![](https://avatars.githubusercontent.com/u/16920092?v=4&size=64)](https://github.com/LiZheGuang)[![](https://avatars.githubusercontent.com/u/29250746?v=4&size=64)](https://github.com/lxy030988)[![](https://avatars.githubusercontent.com/u/6340506?v=4&size=64)](https://github.com/mdoi2)[![](https://avatars.githubusercontent.com/u/42017165?v=4&size=64)](https://github.com/Mario34)[![](https://avatars.githubusercontent.com/u/13410410?v=4&size=64)](https://github.com/jaa134)[![](https://avatars.githubusercontent.com/u/42532333?v=4&size=64)](https://github.com/ivan0525)[![](https://avatars.githubusercontent.com/u/20083373?v=4&size=64)](https://github.com/Cenavy1019)[![](https://avatars.githubusercontent.com/u/87003751?v=4&size=64)](https://github.com/faga295)[![](https://avatars.githubusercontent.com/u/57086651?v=4&size=64)](https://github.com/Simon-He95)[![](https://avatars.githubusercontent.com/u/46318880?v=4&size=64)](https://github.com/yangliguo7)[![](https://avatars.githubusercontent.com/u/49601167?v=4&size=64)](https://github.com/jianjunyuu)[![](https://avatars.githubusercontent.com/u/169252980?v=4&size=64)](https://github.com/xiaochenchen-igg-com)[![](https://avatars.githubusercontent.com/u/44334858?v=4&size=64)](https://github.com/k713927)[![](https://avatars.githubusercontent.com/u/26833520?v=4&size=64)](https://github.com/josonho)[![](https://avatars.githubusercontent.com/u/1744129?v=4&size=64)](https://github.com/hminghe)[![](https://avatars.githubusercontent.com/u/45614103?v=4&size=64)](https://github.com/kakigakki)[![](https://avatars.githubusercontent.com/u/17698194?v=4&size=64)](https://github.com/nieyuyao)[![](https://avatars.githubusercontent.com/u/15374687?v=4&size=64)](https://github.com/zhangshichun)[![](https://avatars.githubusercontent.com/u/22695767?v=4&size=64)](https://github.com/deepthan)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)[![](https://avatars.githubusercontent.com/u/29143658?v=4&size=64)](https://github.com/HaitaoWang555)

[Skeleton 骨架屏](https://element-plus.org/zh-CN/component/skeleton)

[Virtualized Table 虚拟化表格](https://element-plus.org/zh-CN/component/table-v2)




---
## [data/table-v2] Virtualized Table 虚拟化表格
> 官方文档: https://element-plus.org/zh-CN/component/table-v2.html

---

# Virtualized Table 虚拟化表格 beta [​](#virtualized-table-虚拟化表格)

更新日志待解决

48

在前端开发领域，表格一直都是一个高频出现的组件，尤其是在中后台和数据分析场景。 但是，对于 [Table V1](https://element-plus.org/zh-CN/component/table)来说，当一屏里超过 1000 条数据记录时，就会出现卡顿等性能问题，体验不是很好。

通过虚拟化表格组件，超大数据渲染将不再是一个头疼的问题。

TIP

该组件**仍在测试中**，生产环境使用可能有风险。 若您发现了 bug 或问题，请于 [GitHub](https://github.com/element-plus/element-plus/issues) 报告给我们以便修复。 同时，有一些 API 并未在此文档中提及，因为部分还没有开发完全，因此我们不在此提及。

**即使**虚拟化的表格是高效的，但是当数据负载过大时，**网络**和**内存容量**也会成为您应用程序的瓶颈。 因此请牢记，虚拟化表格永远不是最完美的解决方案，请考虑数据分页、过滤器等优化方案。

## 基础用法 [​](#基础用法)

让我们演示虚拟化表的性能，用10列和1 000行渲染一个基本示例。

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgOndpZHRoPVwiNzAwXCJcbiAgICA6aGVpZ2h0PVwiNDAwXCJcbiAgICBmaXhlZFxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IGdlbmVyYXRlQ29sdW1ucyA9IChsZW5ndGggPSAxMCwgcHJlZml4ID0gJ2NvbHVtbi0nLCBwcm9wcz86IGFueSkgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIGNvbHVtbkluZGV4KSA9PiAoe1xuICAgIC4uLnByb3BzLFxuICAgIGtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICBkYXRhS2V5OiBgJHtwcmVmaXh9JHtjb2x1bW5JbmRleH1gLFxuICAgIHRpdGxlOiBgQ29sdW1uICR7Y29sdW1uSW5kZXh9YCxcbiAgICB3aWR0aDogMTUwLFxuICB9KSlcblxuY29uc3QgZ2VuZXJhdGVEYXRhID0gKFxuICBjb2x1bW5zOiBSZXR1cm5UeXBlPHR5cGVvZiBnZW5lcmF0ZUNvbHVtbnM+LFxuICBsZW5ndGggPSAyMDAsXG4gIHByZWZpeCA9ICdyb3ctJ1xuKSA9PlxuICBBcnJheS5mcm9tKHsgbGVuZ3RoIH0pLm1hcCgoXywgcm93SW5kZXgpID0+IHtcbiAgICByZXR1cm4gY29sdW1ucy5yZWR1Y2UoXG4gICAgICAocm93RGF0YSwgY29sdW1uLCBjb2x1bW5JbmRleCkgPT4ge1xuICAgICAgICByb3dEYXRhW2NvbHVtbi5kYXRhS2V5XSA9IGBSb3cgJHtyb3dJbmRleH0gLSBDb2wgJHtjb2x1bW5JbmRleH1gXG4gICAgICAgIHJldHVybiByb3dEYXRhXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogYCR7cHJlZml4fSR7cm93SW5kZXh9YCxcbiAgICAgICAgcGFyZW50SWQ6IG51bGwsXG4gICAgICB9XG4gICAgKVxuICB9KVxuXG5jb25zdCBjb2x1bW5zID0gZ2VuZXJhdGVDb2x1bW5zKDEwKVxuY29uc3QgZGF0YSA9IGdlbmVyYXRlRGF0YShjb2x1bW5zLCAxMDAwKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/basic.vue)_

vue

```
<template>
  <el-table-v2
    :columns="columns"
    :data="data"
    :width="700"
    :height="400"
    fixed
  />
</template>

<script lang="ts" setup>
const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
const data = generateData(columns, 1000)
</script>
```

隐藏源代码

## 自动调整大小 [​](#自动调整大小)

如果不想手动向表格传递 `width` 和 `height` 属性，可以使用 AutoResizer 对表格组件进行封装。 这会自动为你更新宽度和高度。

尝试调整您的浏览器大小来看看它是如何工作的。

TIP

由于 `AutoResizer` 组件的默认高度是 100%，所以请确保该组件的父元素**拥有固定的高度值**。 或者，您可以通过将 `style` 属性传递到 `AutoResizer` 来定义它。

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwiaGVpZ2h0OiA0MDBweFwiPlxuICAgIDxlbC1hdXRvLXJlc2l6ZXI+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJ7IGhlaWdodCwgd2lkdGggfVwiPlxuICAgICAgICA8ZWwtdGFibGUtdjJcbiAgICAgICAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgICAgICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgICAgICAgOndpZHRoPVwid2lkdGhcIlxuICAgICAgICAgIDpoZWlnaHQ9XCJoZWlnaHRcIlxuICAgICAgICAgIGZpeGVkXG4gICAgICAgIC8+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtYXV0by1yZXNpemVyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5jb25zdCBnZW5lcmF0ZUNvbHVtbnMgPSAobGVuZ3RoID0gMTAsIHByZWZpeCA9ICdjb2x1bW4tJywgcHJvcHM/OiBhbnkpID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCBjb2x1bW5JbmRleCkgPT4gKHtcbiAgICAuLi5wcm9wcyxcbiAgICBrZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgZGF0YUtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICB0aXRsZTogYENvbHVtbiAke2NvbHVtbkluZGV4fWAsXG4gICAgd2lkdGg6IDE1MCxcbiAgfSkpXG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9IChcbiAgY29sdW1uczogUmV0dXJuVHlwZTx0eXBlb2YgZ2VuZXJhdGVDb2x1bW5zPixcbiAgbGVuZ3RoID0gMjAwLFxuICBwcmVmaXggPSAncm93LSdcbikgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIHJvd0luZGV4KSA9PiB7XG4gICAgcmV0dXJuIGNvbHVtbnMucmVkdWNlKFxuICAgICAgKHJvd0RhdGEsIGNvbHVtbiwgY29sdW1uSW5kZXgpID0+IHtcbiAgICAgICAgcm93RGF0YVtjb2x1bW4uZGF0YUtleV0gPSBgUm93ICR7cm93SW5kZXh9IC0gQ29sICR7Y29sdW1uSW5kZXh9YFxuICAgICAgICByZXR1cm4gcm93RGF0YVxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IGAke3ByZWZpeH0ke3Jvd0luZGV4fWAsXG4gICAgICAgIHBhcmVudElkOiBudWxsLFxuICAgICAgfVxuICAgIClcbiAgfSlcblxuY29uc3QgY29sdW1ucyA9IGdlbmVyYXRlQ29sdW1ucygxMClcbmNvbnN0IGRhdGEgPSBnZW5lcmF0ZURhdGEoY29sdW1ucywgMjAwKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/auto-resizer.vue)_

vue

```
<template>
  <div style="height: 400px">
    <el-auto-resizer>
      <template #default="{ height, width }">
        <el-table-v2
          :columns="columns"
          :data="data"
          :width="width"
          :height="height"
          fixed
        />
      </template>
    </el-auto-resizer>
  </div>
</template>

<script lang="ts" setup>
const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
const data = generateData(columns, 200)
</script>
```

隐藏源代码

## 自定义单元格渲染器 [​](#customize-cell-renderer)

当然，您可以根据您的需要呈现表格单元格。 这是如何自定义您的单元格的简单例子。

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Name

Operations

2020/10/01

2020/10/01

2020/10/01

2020/10/01

2020/10/01

2020/10/01

2020/10/01

2020/10/01

2020/10/01

Date

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgOndpZHRoPVwiNzAwXCJcbiAgICA6aGVpZ2h0PVwiNDAwXCJcbiAgICBmaXhlZFxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHN4XCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgZGF5anMgZnJvbSAnZGF5anMnXG5pbXBvcnQge1xuICBFbEJ1dHRvbixcbiAgRWxJY29uLFxuICBFbFRhZyxcbiAgRWxUb29sdGlwLFxuICBUYWJsZVYyRml4ZWREaXIsXG59IGZyb20gJ2VsZW1lbnQtcGx1cydcbmltcG9ydCB7IFRpbWVyIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmltcG9ydCB0eXBlIHsgQ29sdW1uIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5sZXQgaWQgPSAwXG5cbmNvbnN0IGRhdGFHZW5lcmF0b3IgPSAoKSA9PiAoe1xuICBpZDogYHJhbmRvbS1pZC0keysraWR9YCxcbiAgbmFtZTogJ1RvbScsXG4gIGRhdGU6ICcyMDIwLTEwLTEnLFxufSlcblxuY29uc3QgY29sdW1uczogQ29sdW1uPGFueT5bXSA9IFtcbiAge1xuICAgIGtleTogJ2RhdGUnLFxuICAgIHRpdGxlOiAnRGF0ZScsXG4gICAgZGF0YUtleTogJ2RhdGUnLFxuICAgIHdpZHRoOiAxNTAsXG4gICAgZml4ZWQ6IFRhYmxlVjJGaXhlZERpci5MRUZULFxuICAgIGNlbGxSZW5kZXJlcjogKHsgY2VsbERhdGE6IGRhdGUgfSkgPT4gKFxuICAgICAgPEVsVG9vbHRpcCBjb250ZW50PXtkYXlqcyhkYXRlKS5mb3JtYXQoJ1lZWVkvTU0vREQnKX0+XG4gICAgICAgIHtcbiAgICAgICAgICA8c3BhbiBjbGFzcz1cImZsZXggaXRlbXMtY2VudGVyXCI+XG4gICAgICAgICAgICA8RWxJY29uIGNsYXNzPVwibXItM1wiPlxuICAgICAgICAgICAgICA8VGltZXIgLz5cbiAgICAgICAgICAgIDwvRWxJY29uPlxuICAgICAgICAgICAge2RheWpzKGRhdGUpLmZvcm1hdCgnWVlZWS9NTS9ERCcpfVxuICAgICAgICAgIDwvc3Bhbj5cbiAgICAgICAgfVxuICAgICAgPC9FbFRvb2x0aXA+XG4gICAgKSxcbiAgfSxcbiAge1xuICAgIGtleTogJ25hbWUnLFxuICAgIHRpdGxlOiAnTmFtZScsXG4gICAgZGF0YUtleTogJ25hbWUnLFxuICAgIHdpZHRoOiAxNTAsXG4gICAgYWxpZ246ICdjZW50ZXInLFxuICAgIGNlbGxSZW5kZXJlcjogKHsgY2VsbERhdGE6IG5hbWUgfSkgPT4gPEVsVGFnPntuYW1lfTwvRWxUYWc+LFxuICB9LFxuICB7XG4gICAga2V5OiAnb3BlcmF0aW9ucycsXG4gICAgdGl0bGU6ICdPcGVyYXRpb25zJyxcbiAgICBjZWxsUmVuZGVyZXI6ICgpID0+IChcbiAgICAgIDw+XG4gICAgICAgIDxFbEJ1dHRvbiBzaXplPVwic21hbGxcIj5FZGl0PC9FbEJ1dHRvbj5cbiAgICAgICAgPEVsQnV0dG9uIHNpemU9XCJzbWFsbFwiIHR5cGU9XCJkYW5nZXJcIj5cbiAgICAgICAgICBEZWxldGVcbiAgICAgICAgPC9FbEJ1dHRvbj5cbiAgICAgIDwvPlxuICAgICksXG4gICAgd2lkdGg6IDE1MCxcbiAgICBhbGlnbjogJ2NlbnRlcicsXG4gIH0sXG5dXG5cbmNvbnN0IGRhdGEgPSByZWYoQXJyYXkuZnJvbSh7IGxlbmd0aDogMjAwIH0pLm1hcChkYXRhR2VuZXJhdG9yKSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/cell-templating.vue)_

vue

```
<template>
  <el-table-v2
    :columns="columns"
    :data="data"
    :width="700"
    :height="400"
    fixed
  />
</template>

<script lang="tsx" setup>
import { ref } from 'vue'
import dayjs from 'dayjs'
import {
  ElButton,
  ElIcon,
  ElTag,
  ElTooltip,
  TableV2FixedDir,
} from 'element-plus'
import { Timer } from '@element-plus/icons-vue'

import type { Column } from 'element-plus'

let id = 0

const dataGenerator = () => ({
  id: `random-id-${++id}`,
  name: 'Tom',
  date: '2020-10-1',
})

const columns: Column<any>[] = [
  {
    key: 'date',
    title: 'Date',
    dataKey: 'date',
    width: 150,
    fixed: TableV2FixedDir.LEFT,
    cellRenderer: ({ cellData: date }) => (
      <ElTooltip content={dayjs(date).format('YYYY/MM/DD')}>
        {
          <span class="flex items-center">
            <ElIcon class="mr-3">
              <Timer />
            </ElIcon>
            {dayjs(date).format('YYYY/MM/DD')}
          </span>
        }
      </ElTooltip>
    ),
  },
  {
    key: 'name',
    title: 'Name',
    dataKey: 'name',
    width: 150,
    align: 'center',
    cellRenderer: ({ cellData: name }) => <ElTag>{name}</ElTag>,
  },
  {
    key: 'operations',
    title: 'Operations',
    cellRenderer: () => (
      <>
        <ElButton size="small">Edit</ElButton>
        <ElButton size="small" type="danger">
          Delete
        </ElButton>
      </>
    ),
    width: 150,
    align: 'center',
  },
]

const data = ref(Array.from({ length: 200 }).map(dataGenerator))
</script>
```

隐藏源代码

## 带有选择的表格 [​](#带有选择的表格)

使用自定义的单元格渲染来给表格组件添加选择的能力。

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 0 - Col 10

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 1 - Col 10

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 2 - Col 10

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 3 - Col 10

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 4 - Col 10

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 5 - Col 10

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 6 - Col 10

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 7 - Col 10

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Row 8 - Col 10

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwiaGVpZ2h0OiA0MDBweFwiPlxuICAgIDxlbC1hdXRvLXJlc2l6ZXI+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJ7IGhlaWdodCwgd2lkdGggfVwiPlxuICAgICAgICA8ZWwtdGFibGUtdjJcbiAgICAgICAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgICAgICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgICAgICAgOndpZHRoPVwid2lkdGhcIlxuICAgICAgICAgIDpoZWlnaHQ9XCJoZWlnaHRcIlxuICAgICAgICAgIGZpeGVkXG4gICAgICAgIC8+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtYXV0by1yZXNpemVyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzeFwiIHNldHVwPlxuaW1wb3J0IHsgcmVmLCB1bnJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVsQ2hlY2tib3gsIHVzZUxvY2FsZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuaW1wb3J0IHR5cGUgeyBGdW5jdGlvbmFsQ29tcG9uZW50IH0gZnJvbSAndnVlJ1xuaW1wb3J0IHR5cGUgeyBDaGVja2JveFZhbHVlVHlwZSwgQ29sdW1uIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG50eXBlIFNlbGVjdGlvbkNlbGxQcm9wcyA9IHtcbiAgdmFsdWU6IGJvb2xlYW5cbiAgaW50ZXJtZWRpYXRlPzogYm9vbGVhblxuICBhcmlhTGFiZWw/OiBzdHJpbmdcbiAgb25DaGFuZ2U6ICh2YWx1ZTogQ2hlY2tib3hWYWx1ZVR5cGUpID0+IHZvaWRcbn1cblxuY29uc3QgeyB0IH0gPSB1c2VMb2NhbGUoKVxuXG5jb25zdCBTZWxlY3Rpb25DZWxsOiBGdW5jdGlvbmFsQ29tcG9uZW50PFNlbGVjdGlvbkNlbGxQcm9wcz4gPSAoe1xuICB2YWx1ZSxcbiAgaW50ZXJtZWRpYXRlID0gZmFsc2UsXG4gIGFyaWFMYWJlbCxcbiAgb25DaGFuZ2UsXG59KSA9PiB7XG4gIHJldHVybiAoXG4gICAgPEVsQ2hlY2tib3hcbiAgICAgIG9uQ2hhbmdlPXtvbkNoYW5nZX1cbiAgICAgIG1vZGVsVmFsdWU9e3ZhbHVlfVxuICAgICAgYXJpYUxhYmVsPXthcmlhTGFiZWx9XG4gICAgICBpbmRldGVybWluYXRlPXtpbnRlcm1lZGlhdGV9XG4gICAgLz5cbiAgKVxufVxuXG5jb25zdCBnZW5lcmF0ZUNvbHVtbnMgPSAobGVuZ3RoID0gMTAsIHByZWZpeCA9ICdjb2x1bW4tJywgcHJvcHM/OiBhbnkpID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCBjb2x1bW5JbmRleCkgPT4gKHtcbiAgICAuLi5wcm9wcyxcbiAgICBrZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgZGF0YUtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICB0aXRsZTogYENvbHVtbiAke2NvbHVtbkluZGV4fWAsXG4gICAgd2lkdGg6IDE1MCxcbiAgfSkpXG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9IChcbiAgY29sdW1uczogUmV0dXJuVHlwZTx0eXBlb2YgZ2VuZXJhdGVDb2x1bW5zPixcbiAgbGVuZ3RoID0gMjAwLFxuICBwcmVmaXggPSAncm93LSdcbikgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIHJvd0luZGV4KSA9PiB7XG4gICAgcmV0dXJuIGNvbHVtbnMucmVkdWNlKFxuICAgICAgKHJvd0RhdGEsIGNvbHVtbiwgY29sdW1uSW5kZXgpID0+IHtcbiAgICAgICAgcm93RGF0YVtjb2x1bW4uZGF0YUtleV0gPSBgUm93ICR7cm93SW5kZXh9IC0gQ29sICR7Y29sdW1uSW5kZXh9YFxuICAgICAgICByZXR1cm4gcm93RGF0YVxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IGAke3ByZWZpeH0ke3Jvd0luZGV4fWAsXG4gICAgICAgIGNoZWNrZWQ6IGZhbHNlLFxuICAgICAgICBwYXJlbnRJZDogbnVsbCxcbiAgICAgIH1cbiAgICApXG4gIH0pXG5cbmNvbnN0IGNvbHVtbnM6IENvbHVtbjxhbnk+W10gPSBnZW5lcmF0ZUNvbHVtbnMoMTApXG5jb2x1bW5zLnVuc2hpZnQoe1xuICBrZXk6ICdzZWxlY3Rpb24nLFxuICB3aWR0aDogNTAsXG4gIGNlbGxSZW5kZXJlcjogKHsgcm93RGF0YSB9KSA9PiB7XG4gICAgY29uc3Qgb25DaGFuZ2UgPSAodmFsdWU6IENoZWNrYm94VmFsdWVUeXBlKSA9PiAocm93RGF0YS5jaGVja2VkID0gdmFsdWUpXG4gICAgcmV0dXJuIChcbiAgICAgIDxTZWxlY3Rpb25DZWxsXG4gICAgICAgIHZhbHVlPXtyb3dEYXRhLmNoZWNrZWR9XG4gICAgICAgIGFyaWFMYWJlbD17dCgnZWwudGFibGUuc2VsZWN0Um93TGFiZWwnKX1cbiAgICAgICAgb25DaGFuZ2U9e29uQ2hhbmdlfVxuICAgICAgLz5cbiAgICApXG4gIH0sXG5cbiAgaGVhZGVyQ2VsbFJlbmRlcmVyOiAoKSA9PiB7XG4gICAgY29uc3QgX2RhdGEgPSB1bnJlZihkYXRhKVxuICAgIGNvbnN0IG9uQ2hhbmdlID0gKHZhbHVlOiBDaGVja2JveFZhbHVlVHlwZSkgPT5cbiAgICAgIChkYXRhLnZhbHVlID0gX2RhdGEubWFwKChyb3cpID0+IHtcbiAgICAgICAgcm93LmNoZWNrZWQgPSB2YWx1ZVxuICAgICAgICByZXR1cm4gcm93XG4gICAgICB9KSlcbiAgICBjb25zdCBhbGxTZWxlY3RlZCA9IF9kYXRhLmV2ZXJ5KChyb3cpID0+IHJvdy5jaGVja2VkKVxuICAgIGNvbnN0IGNvbnRhaW5zQ2hlY2tlZCA9IF9kYXRhLnNvbWUoKHJvdykgPT4gcm93LmNoZWNrZWQpXG5cbiAgICByZXR1cm4gKFxuICAgICAgPFNlbGVjdGlvbkNlbGxcbiAgICAgICAgdmFsdWU9e2FsbFNlbGVjdGVkfVxuICAgICAgICBpbnRlcm1lZGlhdGU9e2NvbnRhaW5zQ2hlY2tlZCAmJiAhYWxsU2VsZWN0ZWR9XG4gICAgICAgIGFyaWFMYWJlbD17dCgnZWwudGFibGUuc2VsZWN0QWxsTGFiZWwnKX1cbiAgICAgICAgb25DaGFuZ2U9e29uQ2hhbmdlfVxuICAgICAgLz5cbiAgICApXG4gIH0sXG59KVxuXG5jb25zdCBkYXRhID0gcmVmKGdlbmVyYXRlRGF0YShjb2x1bW5zLCAyMDApKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/selection.vue)_

vue

```
<template>
  <div style="height: 400px">
    <el-auto-resizer>
      <template #default="{ height, width }">
        <el-table-v2
          :columns="columns"
          :data="data"
          :width="width"
          :height="height"
          fixed
        />
      </template>
    </el-auto-resizer>
  </div>
</template>

<script lang="tsx" setup>
import { ref, unref } from 'vue'
import { ElCheckbox, useLocale } from 'element-plus'

import type { FunctionalComponent } from 'vue'
import type { CheckboxValueType, Column } from 'element-plus'

type SelectionCellProps = {
  value: boolean
  intermediate?: boolean
  ariaLabel?: string
  onChange: (value: CheckboxValueType) => void
}

const { t } = useLocale()

const SelectionCell: FunctionalComponent<SelectionCellProps> = ({
  value,
  intermediate = false,
  ariaLabel,
  onChange,
}) => {
  return (
    <ElCheckbox
      onChange={onChange}
      modelValue={value}
      ariaLabel={ariaLabel}
      indeterminate={intermediate}
    />
  )
}

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        checked: false,
        parentId: null,
      }
    )
  })

const columns: Column<any>[] = generateColumns(10)
columns.unshift({
  key: 'selection',
  width: 50,
  cellRenderer: ({ rowData }) => {
    const onChange = (value: CheckboxValueType) => (rowData.checked = value)
    return (
      <SelectionCell
        value={rowData.checked}
        ariaLabel={t('el.table.selectRowLabel')}
        onChange={onChange}
      />
    )
  },

  headerCellRenderer: () => {
    const _data = unref(data)
    const onChange = (value: CheckboxValueType) =>
      (data.value = _data.map((row) => {
        row.checked = value
        return row
      }))
    const allSelected = _data.every((row) => row.checked)
    const containsChecked = _data.some((row) => row.checked)

    return (
      <SelectionCell
        value={allSelected}
        intermediate={containsChecked && !allSelected}
        ariaLabel={t('el.table.selectAllLabel')}
        onChange={onChange}
      />
    )
  },
})

const data = ref(generateData(columns, 200))
</script>
```

隐藏源代码

## 可编辑单元格 [​](#可编辑单元格)

类似上面添加筛选框的方法，我们可以用同样的方法实现可编辑单元格。

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Editable Column

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwiaGVpZ2h0OiA0MDBweFwiPlxuICAgIDxlbC1hdXRvLXJlc2l6ZXI+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJ7IGhlaWdodCwgd2lkdGggfVwiPlxuICAgICAgICA8ZWwtdGFibGUtdjJcbiAgICAgICAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgICAgICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgICAgICAgOndpZHRoPVwid2lkdGhcIlxuICAgICAgICAgIDpoZWlnaHQ9XCJoZWlnaHRcIlxuICAgICAgICAgIGZpeGVkXG4gICAgICAgIC8+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtYXV0by1yZXNpemVyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzeFwiIHNldHVwPlxuaW1wb3J0IHsgcmVmLCB3aXRoS2V5cyB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVsSW5wdXQgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmltcG9ydCB0eXBlIHsgRnVuY3Rpb25hbENvbXBvbmVudCB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB0eXBlIHsgQ29sdW1uLCBJbnB1dEluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG50eXBlIFNlbGVjdGlvbkNlbGxQcm9wcyA9IHtcbiAgdmFsdWU6IHN0cmluZ1xuICBpbnRlcm1lZGlhdGU/OiBib29sZWFuXG4gIG9uQ2hhbmdlOiAodmFsdWU6IHN0cmluZykgPT4gdm9pZFxuICBvbkJsdXI6ICgpID0+IHZvaWRcbiAgb25LZXlkb3duRW50ZXI6ICgpID0+IHZvaWRcbiAgZm9yd2FyZFJlZjogKGVsOiBJbnB1dEluc3RhbmNlKSA9PiB2b2lkXG59XG5cbmNvbnN0IElucHV0Q2VsbDogRnVuY3Rpb25hbENvbXBvbmVudDxTZWxlY3Rpb25DZWxsUHJvcHM+ID0gKHtcbiAgdmFsdWUsXG4gIG9uQ2hhbmdlLFxuICBvbkJsdXIsXG4gIG9uS2V5ZG93bkVudGVyLFxuICBmb3J3YXJkUmVmLFxufSkgPT4ge1xuICByZXR1cm4gKFxuICAgIDxFbElucHV0XG4gICAgICByZWY9e2ZvcndhcmRSZWYgYXMgYW55fVxuICAgICAgb25JbnB1dD17b25DaGFuZ2V9XG4gICAgICBvbkJsdXI9e29uQmx1cn1cbiAgICAgIG9uS2V5ZG93bj17d2l0aEtleXMob25LZXlkb3duRW50ZXIsIFsnZW50ZXInXSl9XG4gICAgICBtb2RlbFZhbHVlPXt2YWx1ZX1cbiAgICAvPlxuICApXG59XG5cbmNvbnN0IGdlbmVyYXRlQ29sdW1ucyA9IChsZW5ndGggPSAxMCwgcHJlZml4ID0gJ2NvbHVtbi0nLCBwcm9wcz86IGFueSkgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIGNvbHVtbkluZGV4KSA9PiAoe1xuICAgIC4uLnByb3BzLFxuICAgIGtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICBkYXRhS2V5OiBgJHtwcmVmaXh9JHtjb2x1bW5JbmRleH1gLFxuICAgIHRpdGxlOiBgQ29sdW1uICR7Y29sdW1uSW5kZXh9YCxcbiAgICB3aWR0aDogMTUwLFxuICB9KSlcblxuY29uc3QgZ2VuZXJhdGVEYXRhID0gKFxuICBjb2x1bW5zOiBSZXR1cm5UeXBlPHR5cGVvZiBnZW5lcmF0ZUNvbHVtbnM+LFxuICBsZW5ndGggPSAyMDAsXG4gIHByZWZpeCA9ICdyb3ctJ1xuKSA9PlxuICBBcnJheS5mcm9tKHsgbGVuZ3RoIH0pLm1hcCgoXywgcm93SW5kZXgpID0+IHtcbiAgICByZXR1cm4gY29sdW1ucy5yZWR1Y2UoXG4gICAgICAocm93RGF0YSwgY29sdW1uLCBjb2x1bW5JbmRleCkgPT4ge1xuICAgICAgICByb3dEYXRhW2NvbHVtbi5kYXRhS2V5XSA9IGBSb3cgJHtyb3dJbmRleH0gLSBDb2wgJHtjb2x1bW5JbmRleH1gXG4gICAgICAgIHJldHVybiByb3dEYXRhXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogYCR7cHJlZml4fSR7cm93SW5kZXh9YCxcbiAgICAgICAgZWRpdGluZzogZmFsc2UsXG4gICAgICAgIHBhcmVudElkOiBudWxsLFxuICAgICAgfVxuICAgIClcbiAgfSlcblxuY29uc3QgY29sdW1uczogQ29sdW1uPGFueT5bXSA9IGdlbmVyYXRlQ29sdW1ucygxMClcbmNvbHVtbnNbMF0gPSB7XG4gIC4uLmNvbHVtbnNbMF0sXG4gIHRpdGxlOiAnRWRpdGFibGUgQ29sdW1uJyxcbiAgY2VsbFJlbmRlcmVyOiAoeyByb3dEYXRhLCBjb2x1bW4gfSkgPT4ge1xuICAgIGNvbnN0IG9uQ2hhbmdlID0gKHZhbHVlOiBzdHJpbmcpID0+IHtcbiAgICAgIHJvd0RhdGFbY29sdW1uLmRhdGFLZXkhXSA9IHZhbHVlXG4gICAgfVxuICAgIGNvbnN0IG9uRW50ZXJFZGl0TW9kZSA9ICgpID0+IHtcbiAgICAgIHJvd0RhdGEuZWRpdGluZyA9IHRydWVcbiAgICB9XG5cbiAgICBjb25zdCBvbkV4aXRFZGl0TW9kZSA9ICgpID0+IChyb3dEYXRhLmVkaXRpbmcgPSBmYWxzZSlcbiAgICBjb25zdCBpbnB1dCA9IHJlZigpXG4gICAgY29uc3Qgc2V0UmVmID0gKGVsKSA9PiB7XG4gICAgICBpbnB1dC52YWx1ZSA9IGVsXG4gICAgICBpZiAoZWwpIHtcbiAgICAgICAgZWwuZm9jdXM/LigpXG4gICAgICB9XG4gICAgfVxuXG4gICAgcmV0dXJuIHJvd0RhdGEuZWRpdGluZyA/IChcbiAgICAgIDxJbnB1dENlbGxcbiAgICAgICAgZm9yd2FyZFJlZj17c2V0UmVmfVxuICAgICAgICB2YWx1ZT17cm93RGF0YVtjb2x1bW4uZGF0YUtleSFdfVxuICAgICAgICBvbkNoYW5nZT17b25DaGFuZ2V9XG4gICAgICAgIG9uQmx1cj17b25FeGl0RWRpdE1vZGV9XG4gICAgICAgIG9uS2V5ZG93bkVudGVyPXtvbkV4aXRFZGl0TW9kZX1cbiAgICAgIC8+XG4gICAgKSA6IChcbiAgICAgIDxkaXYgY2xhc3M9XCJ0YWJsZS12Mi1pbmxpbmUtZWRpdGluZy10cmlnZ2VyXCIgb25DbGljaz17b25FbnRlckVkaXRNb2RlfT5cbiAgICAgICAge3Jvd0RhdGFbY29sdW1uLmRhdGFLZXkhXX1cbiAgICAgIDwvZGl2PlxuICAgIClcbiAgfSxcbn1cblxuY29uc3QgZGF0YSA9IHJlZihnZW5lcmF0ZURhdGEoY29sdW1ucywgMjAwKSlcbjwvc2NyaXB0PlxuXG48c3R5bGU+XG4udGFibGUtdjItaW5saW5lLWVkaXRpbmctdHJpZ2dlciB7XG4gIGJvcmRlcjogMXB4IHRyYW5zcGFyZW50IGRvdHRlZDtcbiAgcGFkZGluZzogNHB4O1xufVxuXG4udGFibGUtdjItaW5saW5lLWVkaXRpbmctdHJpZ2dlcjpob3ZlciB7XG4gIGJvcmRlci1jb2xvcjogdmFyKC0tZWwtY29sb3ItcHJpbWFyeSk7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/inline-editing.vue)_

vue

```
<template>
  <div style="height: 400px">
    <el-auto-resizer>
      <template #default="{ height, width }">
        <el-table-v2
          :columns="columns"
          :data="data"
          :width="width"
          :height="height"
          fixed
        />
      </template>
    </el-auto-resizer>
  </div>
</template>

<script lang="tsx" setup>
import { ref, withKeys } from 'vue'
import { ElInput } from 'element-plus'

import type { FunctionalComponent } from 'vue'
import type { Column, InputInstance } from 'element-plus'

type SelectionCellProps = {
  value: string
  intermediate?: boolean
  onChange: (value: string) => void
  onBlur: () => void
  onKeydownEnter: () => void
  forwardRef: (el: InputInstance) => void
}

const InputCell: FunctionalComponent<SelectionCellProps> = ({
  value,
  onChange,
  onBlur,
  onKeydownEnter,
  forwardRef,
}) => {
  return (
    <ElInput
      ref={forwardRef as any}
      onInput={onChange}
      onBlur={onBlur}
      onKeydown={withKeys(onKeydownEnter, ['enter'])}
      modelValue={value}
    />
  )
}

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        editing: false,
        parentId: null,
      }
    )
  })

const columns: Column<any>[] = generateColumns(10)
columns[0] = {
  ...columns[0],
  title: 'Editable Column',
  cellRenderer: ({ rowData, column }) => {
    const onChange = (value: string) => {
      rowData[column.dataKey!] = value
    }
    const onEnterEditMode = () => {
      rowData.editing = true
    }

    const onExitEditMode = () => (rowData.editing = false)
    const input = ref()
    const setRef = (el) => {
      input.value = el
      if (el) {
        el.focus?.()
      }
    }

    return rowData.editing ? (
      <InputCell
        forwardRef={setRef}
        value={rowData[column.dataKey!]}
        onChange={onChange}
        onBlur={onExitEditMode}
        onKeydownEnter={onExitEditMode}
      />
    ) : (
      <div class="table-v2-inline-editing-trigger" onClick={onEnterEditMode}>
        {rowData[column.dataKey!]}
      </div>
    )
  },
}

const data = ref(generateData(columns, 200))
</script>

<style>
.table-v2-inline-editing-trigger {
  border: 1px transparent dotted;
  padding: 4px;
}

.table-v2-inline-editing-trigger:hover {
  border-color: var(--el-color-primary);
}
</style>
```

隐藏源代码

## 带状态的表格 [​](#带状态的表格)

可将表格内容 highlight 显示，方便区分「成功、信息、警告、危险」等内容。

要自定义行的外观，请使用 `row-class-name` 属性。 举个例子，每10行会自动添加 `bg-blue-200` 类名，每5行会添加 `bg-red-100` 类名。

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Tom

EditDelete

Name

Operations

2020/10/01

2020/10/01

2020/10/01

2020/10/01

2020/10/01

2020/10/01

2020/10/01

2020/10/01

2020/10/01

Date

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgOnJvdy1jbGFzcz1cInJvd0NsYXNzXCJcbiAgICA6d2lkdGg9XCI3MDBcIlxuICAgIDpoZWlnaHQ9XCI0MDBcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHN4XCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgZGF5anMgZnJvbSAnZGF5anMnXG5pbXBvcnQge1xuICBFbEJ1dHRvbixcbiAgRWxJY29uLFxuICBFbFRhZyxcbiAgRWxUb29sdGlwLFxuICBUYWJsZVYyRml4ZWREaXIsXG59IGZyb20gJ2VsZW1lbnQtcGx1cydcbmltcG9ydCB7IFRpbWVyIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmltcG9ydCB0eXBlIHsgQ29sdW1uLCBSb3dDbGFzc05hbWVHZXR0ZXIgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmxldCBpZCA9IDBcblxuY29uc3QgZGF0YUdlbmVyYXRvciA9ICgpID0+ICh7XG4gIGlkOiBgcmFuZG9tLWlkLSR7KytpZH1gLFxuICBuYW1lOiAnVG9tJyxcbiAgZGF0ZTogJzIwMjAtMTAtMScsXG59KVxuXG5jb25zdCBjb2x1bW5zOiBDb2x1bW48YW55PltdID0gW1xuICB7XG4gICAga2V5OiAnZGF0ZScsXG4gICAgdGl0bGU6ICdEYXRlJyxcbiAgICBkYXRhS2V5OiAnZGF0ZScsXG4gICAgd2lkdGg6IDE1MCxcbiAgICBmaXhlZDogVGFibGVWMkZpeGVkRGlyLkxFRlQsXG4gICAgY2VsbFJlbmRlcmVyOiAoeyBjZWxsRGF0YTogZGF0ZSB9KSA9PiAoXG4gICAgICA8RWxUb29sdGlwIGNvbnRlbnQ9e2RheWpzKGRhdGUpLmZvcm1hdCgnWVlZWS9NTS9ERCcpfT5cbiAgICAgICAge1xuICAgICAgICAgIDxzcGFuIGNsYXNzPVwiZmxleCBpdGVtcy1jZW50ZXJcIj5cbiAgICAgICAgICAgIDxFbEljb24gY2xhc3M9XCJtci0zXCI+XG4gICAgICAgICAgICAgIDxUaW1lciAvPlxuICAgICAgICAgICAgPC9FbEljb24+XG4gICAgICAgICAgICB7ZGF5anMoZGF0ZSkuZm9ybWF0KCdZWVlZL01NL0REJyl9XG4gICAgICAgICAgPC9zcGFuPlxuICAgICAgICB9XG4gICAgICA8L0VsVG9vbHRpcD5cbiAgICApLFxuICB9LFxuICB7XG4gICAga2V5OiAnbmFtZScsXG4gICAgdGl0bGU6ICdOYW1lJyxcbiAgICBkYXRhS2V5OiAnbmFtZScsXG4gICAgd2lkdGg6IDE1MCxcbiAgICBhbGlnbjogJ2NlbnRlcicsXG4gICAgY2VsbFJlbmRlcmVyOiAoeyBjZWxsRGF0YTogbmFtZSB9KSA9PiA8RWxUYWc+e25hbWV9PC9FbFRhZz4sXG4gIH0sXG4gIHtcbiAgICBrZXk6ICdvcGVyYXRpb25zJyxcbiAgICB0aXRsZTogJ09wZXJhdGlvbnMnLFxuICAgIGNlbGxSZW5kZXJlcjogKCkgPT4gKFxuICAgICAgPD5cbiAgICAgICAgPEVsQnV0dG9uIHNpemU9XCJzbWFsbFwiPkVkaXQ8L0VsQnV0dG9uPlxuICAgICAgICA8RWxCdXR0b24gc2l6ZT1cInNtYWxsXCIgdHlwZT1cImRhbmdlclwiPlxuICAgICAgICAgIERlbGV0ZVxuICAgICAgICA8L0VsQnV0dG9uPlxuICAgICAgPC8+XG4gICAgKSxcbiAgICB3aWR0aDogMTUwLFxuICAgIGFsaWduOiAnY2VudGVyJyxcbiAgICBmbGV4R3JvdzogMSxcbiAgfSxcbl1cblxuY29uc3QgZGF0YSA9IHJlZihBcnJheS5mcm9tKHsgbGVuZ3RoOiAyMDAgfSkubWFwKGRhdGFHZW5lcmF0b3IpKVxuXG5jb25zdCByb3dDbGFzcyA9ICh7IHJvd0luZGV4IH06IFBhcmFtZXRlcnM8Um93Q2xhc3NOYW1lR2V0dGVyPGFueT4+WzBdKSA9PiB7XG4gIGlmIChyb3dJbmRleCAlIDEwID09PSA1KSB7XG4gICAgcmV0dXJuICdiZy1yZWQtMTAwJ1xuICB9IGVsc2UgaWYgKHJvd0luZGV4ICUgMTAgPT09IDApIHtcbiAgICByZXR1cm4gJ2JnLWJsdWUtMjAwJ1xuICB9XG4gIHJldHVybiAnJ1xufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/row-class.vue)_

vue

```
<template>
  <el-table-v2
    :columns="columns"
    :data="data"
    :row-class="rowClass"
    :width="700"
    :height="400"
  />
</template>

<script lang="tsx" setup>
import { ref } from 'vue'
import dayjs from 'dayjs'
import {
  ElButton,
  ElIcon,
  ElTag,
  ElTooltip,
  TableV2FixedDir,
} from 'element-plus'
import { Timer } from '@element-plus/icons-vue'

import type { Column, RowClassNameGetter } from 'element-plus'

let id = 0

const dataGenerator = () => ({
  id: `random-id-${++id}`,
  name: 'Tom',
  date: '2020-10-1',
})

const columns: Column<any>[] = [
  {
    key: 'date',
    title: 'Date',
    dataKey: 'date',
    width: 150,
    fixed: TableV2FixedDir.LEFT,
    cellRenderer: ({ cellData: date }) => (
      <ElTooltip content={dayjs(date).format('YYYY/MM/DD')}>
        {
          <span class="flex items-center">
            <ElIcon class="mr-3">
              <Timer />
            </ElIcon>
            {dayjs(date).format('YYYY/MM/DD')}
          </span>
        }
      </ElTooltip>
    ),
  },
  {
    key: 'name',
    title: 'Name',
    dataKey: 'name',
    width: 150,
    align: 'center',
    cellRenderer: ({ cellData: name }) => <ElTag>{name}</ElTag>,
  },
  {
    key: 'operations',
    title: 'Operations',
    cellRenderer: () => (
      <>
        <ElButton size="small">Edit</ElButton>
        <ElButton size="small" type="danger">
          Delete
        </ElButton>
      </>
    ),
    width: 150,
    align: 'center',
    flexGrow: 1,
  },
]

const data = ref(Array.from({ length: 200 }).map(dataGenerator))

const rowClass = ({ rowIndex }: Parameters<RowClassNameGetter<any>>[0]) => {
  if (rowIndex % 10 === 5) {
    return 'bg-red-100'
  } else if (rowIndex % 10 === 0) {
    return 'bg-blue-200'
  }
  return ''
}
</script>
```

隐藏源代码

## 表格行的粘性布局 [​](#表格行的粘性布局)

您可以简单地使用 `fixed-data` 属性来实现将某些行固定到表格的头部。

您可以根据滚动事件动态设置粘性行，如这个示例所示。

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwidGFibGVEYXRhXCJcbiAgICA6Zml4ZWQtZGF0YT1cImZpeGVkRGF0YVwiXG4gICAgOndpZHRoPVwiNzAwXCJcbiAgICA6aGVpZ2h0PVwiNDAwXCJcbiAgICA6cm93LWNsYXNzPVwicm93Q2xhc3NcIlxuICAgIGZpeGVkXG4gICAgQHNjcm9sbD1cIm9uU2Nyb2xsXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBjb21wdXRlZCwgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBnZW5lcmF0ZUNvbHVtbnMgPSAobGVuZ3RoID0gMTAsIHByZWZpeCA9ICdjb2x1bW4tJywgcHJvcHM/OiBhbnkpID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCBjb2x1bW5JbmRleCkgPT4gKHtcbiAgICAuLi5wcm9wcyxcbiAgICBrZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgZGF0YUtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICB0aXRsZTogYENvbHVtbiAke2NvbHVtbkluZGV4fWAsXG4gICAgd2lkdGg6IDE1MCxcbiAgfSkpXG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9IChcbiAgY29sdW1uczogUmV0dXJuVHlwZTx0eXBlb2YgZ2VuZXJhdGVDb2x1bW5zPixcbiAgbGVuZ3RoID0gMjAwLFxuICBwcmVmaXggPSAncm93LSdcbikgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIHJvd0luZGV4KSA9PiB7XG4gICAgcmV0dXJuIGNvbHVtbnMucmVkdWNlKFxuICAgICAgKHJvd0RhdGEsIGNvbHVtbiwgY29sdW1uSW5kZXgpID0+IHtcbiAgICAgICAgcm93RGF0YVtjb2x1bW4uZGF0YUtleV0gPSBgUm93ICR7cm93SW5kZXh9IC0gQ29sICR7Y29sdW1uSW5kZXh9YFxuICAgICAgICByZXR1cm4gcm93RGF0YVxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IGAke3ByZWZpeH0ke3Jvd0luZGV4fWAsXG4gICAgICAgIHBhcmVudElkOiBudWxsLFxuICAgICAgfVxuICAgIClcbiAgfSlcblxuY29uc3QgY29sdW1ucyA9IGdlbmVyYXRlQ29sdW1ucygxMClcbmNvbnN0IGRhdGEgPSBnZW5lcmF0ZURhdGEoY29sdW1ucywgMjAwKVxuXG5jb25zdCByb3dDbGFzcyA9ICh7IHJvd0luZGV4IH0pID0+IHtcbiAgaWYgKHJvd0luZGV4IDwgMCB8fCAocm93SW5kZXggKyAxKSAlIDUgPT09IDApIHJldHVybiAnc3RpY2t5LXJvdydcbn1cblxuY29uc3Qgc3RpY2t5SW5kZXggPSByZWYoMClcblxuY29uc3QgZml4ZWREYXRhID0gY29tcHV0ZWQoKCkgPT5cbiAgZGF0YS5zbGljZShzdGlja3lJbmRleC52YWx1ZSwgc3RpY2t5SW5kZXgudmFsdWUgKyAxKVxuKVxuXG5jb25zdCB0YWJsZURhdGEgPSBjb21wdXRlZCgoKSA9PiB7XG4gIHJldHVybiBkYXRhLnNsaWNlKDEpXG59KVxuXG5jb25zdCBvblNjcm9sbCA9ICh7IHNjcm9sbFRvcCB9KSA9PiB7XG4gIHN0aWNreUluZGV4LnZhbHVlID0gTWF0aC5mbG9vcihzY3JvbGxUb3AgLyAyNTApICogNVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5lbC1lbC10YWJsZS12Ml9fZml4ZWQtaGVhZGVyLXJvdyB7XG4gIGJhY2tncm91bmQtY29sb3I6IHZhcigtLWVsLWNvbG9yLXByaW1hcnktbGlnaHQtNSk7XG4gIGZvbnQtd2VpZ2h0OiBib2xkO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/sticky-rows.vue)_

vue

```
<template>
  <el-table-v2
    :columns="columns"
    :data="tableData"
    :fixed-data="fixedData"
    :width="700"
    :height="400"
    :row-class="rowClass"
    fixed
    @scroll="onScroll"
  />
</template>

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

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
const data = generateData(columns, 200)

const rowClass = ({ rowIndex }) => {
  if (rowIndex < 0 || (rowIndex + 1) % 5 === 0) return 'sticky-row'
}

const stickyIndex = ref(0)

const fixedData = computed(() =>
  data.slice(stickyIndex.value, stickyIndex.value + 1)
)

const tableData = computed(() => {
  return data.slice(1)
})

const onScroll = ({ scrollTop }) => {
  stickyIndex.value = Math.floor(scrollTop / 250) * 5
}
</script>

<style>
.el-el-table-v2__fixed-header-row {
  background-color: var(--el-color-primary-light-5);
  font-weight: bold;
}
</style>
```

隐藏源代码

## 固定列表格 [​](#固定列表格)

如果您想要有列粘贴左侧或右侧的某种原因。 您可以通过向表中添加特殊属性来实现这一点。

您可以设置该行的 `fixed` 属性为 `true` （代表`FixedDir.LEFT`）、`FixedDir.LEFT` 或 `FixedDir.RIGHT`

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Row 0 - Col 0

Row 0 - Col 1

Row 1 - Col 0

Row 1 - Col 1

Row 2 - Col 0

Row 2 - Col 1

Row 3 - Col 0

Row 3 - Col 1

Row 4 - Col 0

Row 4 - Col 1

Row 5 - Col 0

Row 5 - Col 1

Row 6 - Col 0

Row 6 - Col 1

Row 7 - Col 0

Row 7 - Col 1

Row 8 - Col 0

Row 8 - Col 1

Column 0

Column 1

Row 0 - Col 9

Row 1 - Col 9

Row 2 - Col 9

Row 3 - Col 9

Row 4 - Col 9

Row 5 - Col 9

Row 6 - Col 9

Row 7 - Col 9

Row 8 - Col 9

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgOnNvcnQtYnk9XCJzb3J0QnlcIlxuICAgIDp3aWR0aD1cIjcwMFwiXG4gICAgOmhlaWdodD1cIjQwMFwiXG4gICAgZml4ZWRcbiAgICBAY29sdW1uLXNvcnQ9XCJvblNvcnRcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IFRhYmxlVjJGaXhlZERpciwgVGFibGVWMlNvcnRPcmRlciB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuaW1wb3J0IHR5cGUgeyBTb3J0QnkgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGdlbmVyYXRlQ29sdW1ucyA9IChsZW5ndGggPSAxMCwgcHJlZml4ID0gJ2NvbHVtbi0nLCBwcm9wcz86IGFueSkgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIGNvbHVtbkluZGV4KSA9PiAoe1xuICAgIC4uLnByb3BzLFxuICAgIGtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICBkYXRhS2V5OiBgJHtwcmVmaXh9JHtjb2x1bW5JbmRleH1gLFxuICAgIHRpdGxlOiBgQ29sdW1uICR7Y29sdW1uSW5kZXh9YCxcbiAgICB3aWR0aDogMTUwLFxuICB9KSlcblxuY29uc3QgZ2VuZXJhdGVEYXRhID0gKFxuICBjb2x1bW5zOiBSZXR1cm5UeXBlPHR5cGVvZiBnZW5lcmF0ZUNvbHVtbnM+LFxuICBsZW5ndGggPSAyMDAsXG4gIHByZWZpeCA9ICdyb3ctJ1xuKSA9PlxuICBBcnJheS5mcm9tKHsgbGVuZ3RoIH0pLm1hcCgoXywgcm93SW5kZXgpID0+IHtcbiAgICByZXR1cm4gY29sdW1ucy5yZWR1Y2UoXG4gICAgICAocm93RGF0YSwgY29sdW1uLCBjb2x1bW5JbmRleCkgPT4ge1xuICAgICAgICByb3dEYXRhW2NvbHVtbi5kYXRhS2V5XSA9IGBSb3cgJHtyb3dJbmRleH0gLSBDb2wgJHtjb2x1bW5JbmRleH1gXG4gICAgICAgIHJldHVybiByb3dEYXRhXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogYCR7cHJlZml4fSR7cm93SW5kZXh9YCxcbiAgICAgICAgcGFyZW50SWQ6IG51bGwsXG4gICAgICB9XG4gICAgKVxuICB9KVxuXG5jb25zdCBjb2x1bW5zID0gZ2VuZXJhdGVDb2x1bW5zKDEwKVxubGV0IGRhdGEgPSBnZW5lcmF0ZURhdGEoY29sdW1ucywgMjAwKVxuXG5jb2x1bW5zWzBdLmZpeGVkID0gdHJ1ZVxuY29sdW1uc1sxXS5maXhlZCA9IFRhYmxlVjJGaXhlZERpci5MRUZUXG5jb2x1bW5zWzldLmZpeGVkID0gVGFibGVWMkZpeGVkRGlyLlJJR0hUXG5cbmZvciAobGV0IGkgPSAwOyBpIDwgMzsgaSsrKSBjb2x1bW5zW2ldLnNvcnRhYmxlID0gdHJ1ZVxuXG5jb25zdCBzb3J0QnkgPSByZWY8U29ydEJ5Pih7XG4gIGtleTogJ2NvbHVtbi0wJyxcbiAgb3JkZXI6IFRhYmxlVjJTb3J0T3JkZXIuQVNDLFxufSlcblxuY29uc3Qgb25Tb3J0ID0gKF9zb3J0Qnk6IFNvcnRCeSkgPT4ge1xuICBkYXRhID0gZGF0YS5yZXZlcnNlKClcbiAgc29ydEJ5LnZhbHVlID0gX3NvcnRCeVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/fixed-columns.vue)_

vue

```
<template>
  <el-table-v2
    :columns="columns"
    :data="data"
    :sort-by="sortBy"
    :width="700"
    :height="400"
    fixed
    @column-sort="onSort"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { TableV2FixedDir, TableV2SortOrder } from 'element-plus'

import type { SortBy } from 'element-plus'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
let data = generateData(columns, 200)

columns[0].fixed = true
columns[1].fixed = TableV2FixedDir.LEFT
columns[9].fixed = TableV2FixedDir.RIGHT

for (let i = 0; i < 3; i++) columns[i].sortable = true

const sortBy = ref<SortBy>({
  key: 'column-0',
  order: TableV2SortOrder.ASC,
})

const onSort = (_sortBy: SortBy) => {
  data = data.reverse()
  sortBy.value = _sortBy
}
</script>
```

隐藏源代码

## 表头分组 [​](#表头分组)

正如这个示例，通过自定义表头渲染以将表头分组。

TIP

在这种情况下，我们使用了 `JSX` 功能，这个功能在playground上不被支持。 您可以在本地环境或在线集成开发环境（如 `codesandbox` ）中试用它们。

建议您使用 JSX 使用您的表格组件，因为它包含 VNode 操作。

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 0 - Col 10

Row 0 - Col 11

Row 0 - Col 12

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 1 - Col 10

Row 1 - Col 11

Row 1 - Col 12

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 2 - Col 10

Row 2 - Col 11

Row 2 - Col 12

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 3 - Col 10

Row 3 - Col 11

Row 3 - Col 12

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 4 - Col 10

Row 4 - Col 11

Row 4 - Col 12

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 5 - Col 10

Row 5 - Col 11

Row 5 - Col 12

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 6 - Col 10

Row 6 - Col 11

Row 6 - Col 12

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 7 - Col 10

Row 7 - Col 11

Row 7 - Col 12

Group width 400

Group width 400

Group width 200

Group width 200

Group width 200

Group width 200

Group width 200

Group width 200

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

Column 10

Column 11

Column 12

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Group width 300

Group width 200

Group width 100

Column 0

Column 1

Column 2

Row 0 - Col 13

Row 0 - Col 14

Row 1 - Col 13

Row 1 - Col 14

Row 2 - Col 13

Row 2 - Col 14

Row 3 - Col 13

Row 3 - Col 14

Row 4 - Col 13

Row 4 - Col 14

Row 5 - Col 13

Row 5 - Col 14

Row 6 - Col 13

Row 6 - Col 14

Row 7 - Col 13

Row 7 - Col 14

Group width 200

Group width 200

Column 13

Column 14

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICBmaXhlZFxuICAgIDpjb2x1bW5zPVwiZml4ZWRDb2x1bW5zXCJcbiAgICA6ZGF0YT1cImRhdGFcIlxuICAgIDpoZWFkZXItaGVpZ2h0PVwiWzUwLCA0MCwgNTBdXCJcbiAgICA6aGVhZGVyLWNsYXNzPVwiaGVhZGVyQ2xhc3NcIlxuICAgIDp3aWR0aD1cIjcwMFwiXG4gICAgOmhlaWdodD1cIjQwMFwiXG4gID5cbiAgICA8dGVtcGxhdGUgI2hlYWRlcj1cInByb3BzXCI+XG4gICAgICA8Y3VzdG9taXplZC1oZWFkZXIgdi1iaW5kPVwicHJvcHNcIiAvPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtdGFibGUtdjI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c3hcIiBzZXR1cD5cbmltcG9ydCB7IFRhYmxlVjJGaXhlZERpciwgVGFibGVWMlBsYWNlaG9sZGVyIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbXBvcnQgdHlwZSB7IEZ1bmN0aW9uYWxDb21wb25lbnQgfSBmcm9tICd2dWUnXG5pbXBvcnQgdHlwZSB7XG4gIEhlYWRlckNsYXNzTmFtZUdldHRlcixcbiAgVGFibGVWMkN1c3RvbWl6ZWRIZWFkZXJTbG90UGFyYW0sXG59IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgZ2VuZXJhdGVDb2x1bW5zID0gKGxlbmd0aCA9IDEwLCBwcmVmaXggPSAnY29sdW1uLScsIHByb3BzPzogYW55KSA9PlxuICBBcnJheS5mcm9tKHsgbGVuZ3RoIH0pLm1hcCgoXywgY29sdW1uSW5kZXgpID0+ICh7XG4gICAgLi4ucHJvcHMsXG4gICAga2V5OiBgJHtwcmVmaXh9JHtjb2x1bW5JbmRleH1gLFxuICAgIGRhdGFLZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgdGl0bGU6IGBDb2x1bW4gJHtjb2x1bW5JbmRleH1gLFxuICAgIHdpZHRoOiAxNTAsXG4gIH0pKVxuXG5jb25zdCBnZW5lcmF0ZURhdGEgPSAoXG4gIGNvbHVtbnM6IFJldHVyblR5cGU8dHlwZW9mIGdlbmVyYXRlQ29sdW1ucz4sXG4gIGxlbmd0aCA9IDIwMCxcbiAgcHJlZml4ID0gJ3Jvdy0nXG4pID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCByb3dJbmRleCkgPT4ge1xuICAgIHJldHVybiBjb2x1bW5zLnJlZHVjZShcbiAgICAgIChyb3dEYXRhLCBjb2x1bW4sIGNvbHVtbkluZGV4KSA9PiB7XG4gICAgICAgIHJvd0RhdGFbY29sdW1uLmRhdGFLZXldID0gYFJvdyAke3Jvd0luZGV4fSAtIENvbCAke2NvbHVtbkluZGV4fWBcbiAgICAgICAgcmV0dXJuIHJvd0RhdGFcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIGlkOiBgJHtwcmVmaXh9JHtyb3dJbmRleH1gLFxuICAgICAgICBwYXJlbnRJZDogbnVsbCxcbiAgICAgIH1cbiAgICApXG4gIH0pXG5jb25zdCBjb2x1bW5zID0gZ2VuZXJhdGVDb2x1bW5zKDE1KVxuY29uc3QgZGF0YSA9IGdlbmVyYXRlRGF0YShjb2x1bW5zLCAyMDApXG5cbmNvbnN0IGZpeGVkQ29sdW1ucyA9IGNvbHVtbnMubWFwKChjb2x1bW4sIGNvbHVtbkluZGV4KSA9PiB7XG4gIGxldCBmaXhlZDogVGFibGVWMkZpeGVkRGlyIHwgdW5kZWZpbmVkID0gdW5kZWZpbmVkXG4gIGlmIChjb2x1bW5JbmRleCA8IDMpIGZpeGVkID0gVGFibGVWMkZpeGVkRGlyLkxFRlRcbiAgaWYgKGNvbHVtbkluZGV4ID4gMTIpIGZpeGVkID0gVGFibGVWMkZpeGVkRGlyLlJJR0hUXG4gIHJldHVybiB7IC4uLmNvbHVtbiwgZml4ZWQsIHdpZHRoOiAxMDAgfVxufSlcblxuY29uc3QgQ3VzdG9taXplZEhlYWRlcjogRnVuY3Rpb25hbENvbXBvbmVudDxcbiAgVGFibGVWMkN1c3RvbWl6ZWRIZWFkZXJTbG90UGFyYW1cbj4gPSAoeyBjZWxscywgY29sdW1ucywgaGVhZGVySW5kZXggfSkgPT4ge1xuICBpZiAoaGVhZGVySW5kZXggPT09IDIpIHJldHVybiBjZWxsc1xuXG4gIGNvbnN0IGdyb3VwQ2VsbHMgPSBbXSBhcyB0eXBlb2YgY2VsbHNcbiAgbGV0IHdpZHRoID0gMFxuICBsZXQgaWR4ID0gMFxuXG4gIGNvbHVtbnMuZm9yRWFjaCgoY29sdW1uLCBjb2x1bW5JbmRleCkgPT4ge1xuICAgIGlmIChjb2x1bW4ucGxhY2Vob2xkZXJTaWduID09PSBUYWJsZVYyUGxhY2Vob2xkZXIpXG4gICAgICBncm91cENlbGxzLnB1c2goY2VsbHNbY29sdW1uSW5kZXhdKVxuICAgIGVsc2Uge1xuICAgICAgd2lkdGggKz0gY2VsbHNbY29sdW1uSW5kZXhdLnByb3BzIS5jb2x1bW4ud2lkdGhcbiAgICAgIGlkeCsrXG5cbiAgICAgIGNvbnN0IG5leHRDb2x1bW4gPSBjb2x1bW5zW2NvbHVtbkluZGV4ICsgMV1cbiAgICAgIGlmIChcbiAgICAgICAgY29sdW1uSW5kZXggPT09IGNvbHVtbnMubGVuZ3RoIC0gMSB8fFxuICAgICAgICBuZXh0Q29sdW1uLnBsYWNlaG9sZGVyU2lnbiA9PT0gVGFibGVWMlBsYWNlaG9sZGVyIHx8XG4gICAgICAgIGlkeCA9PT0gKGhlYWRlckluZGV4ID09PSAwID8gNCA6IDIpXG4gICAgICApIHtcbiAgICAgICAgZ3JvdXBDZWxscy5wdXNoKFxuICAgICAgICAgIDxkaXZcbiAgICAgICAgICAgIGNsYXNzPVwiZmxleCBpdGVtcy1jZW50ZXIganVzdGlmeS1jZW50ZXIgY3VzdG9tLWhlYWRlci1jZWxsXCJcbiAgICAgICAgICAgIHJvbGU9XCJjb2x1bW5oZWFkZXJcIlxuICAgICAgICAgICAgc3R5bGU9e3tcbiAgICAgICAgICAgICAgLi4uY2VsbHNbY29sdW1uSW5kZXhdLnByb3BzIS5zdHlsZSxcbiAgICAgICAgICAgICAgd2lkdGg6IGAke3dpZHRofXB4YCxcbiAgICAgICAgICAgIH19XG4gICAgICAgICAgPlxuICAgICAgICAgICAgR3JvdXAgd2lkdGgge3dpZHRofVxuICAgICAgICAgIDwvZGl2PlxuICAgICAgICApXG4gICAgICAgIHdpZHRoID0gMFxuICAgICAgICBpZHggPSAwXG4gICAgICB9XG4gICAgfVxuICB9KVxuICByZXR1cm4gZ3JvdXBDZWxsc1xufVxuXG5jb25zdCBoZWFkZXJDbGFzcyA9ICh7XG4gIGhlYWRlckluZGV4LFxufTogUGFyYW1ldGVyczxIZWFkZXJDbGFzc05hbWVHZXR0ZXI8YW55Pj5bMF0pID0+IHtcbiAgaWYgKGhlYWRlckluZGV4ID09PSAxKSByZXR1cm4gJ2VsLXByaW1hcnktY29sb3InXG4gIHJldHVybiAnJ1xufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5lbC1lbC10YWJsZS12Ml9faGVhZGVyLXJvdyAuY3VzdG9tLWhlYWRlci1jZWxsIHtcbiAgYm9yZGVyLXJpZ2h0OiAxcHggc29saWQgdmFyKC0tZWwtYm9yZGVyLWNvbG9yKTtcbn1cblxuLmVsLWVsLXRhYmxlLXYyX19oZWFkZXItcm93IC5jdXN0b20taGVhZGVyLWNlbGw6bGFzdC1jaGlsZCB7XG4gIGJvcmRlci1yaWdodDogbm9uZTtcbn1cblxuLmVsLXByaW1hcnktY29sb3Ige1xuICBiYWNrZ3JvdW5kLWNvbG9yOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbiAgY29sb3I6IHZhcigtLWVsLWNvbG9yLXdoaXRlKTtcbiAgZm9udC1zaXplOiAxNHB4O1xuICBmb250LXdlaWdodDogYm9sZDtcbn1cblxuLmVsLXByaW1hcnktY29sb3IgLmN1c3RvbS1oZWFkZXItY2VsbCB7XG4gIHBhZGRpbmc6IDAgNHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/grouping-header.vue)_

vue

```
<template>
  <el-table-v2
    fixed
    :columns="fixedColumns"
    :data="data"
    :header-height="[50, 40, 50]"
    :header-class="headerClass"
    :width="700"
    :height="400"
  >
    <template #header="props">
      <customized-header v-bind="props" />
    </template>
  </el-table-v2>
</template>

<script lang="tsx" setup>
import { TableV2FixedDir, TableV2Placeholder } from 'element-plus'

import type { FunctionalComponent } from 'vue'
import type {
  HeaderClassNameGetter,
  TableV2CustomizedHeaderSlotParam,
} from 'element-plus'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })
const columns = generateColumns(15)
const data = generateData(columns, 200)

const fixedColumns = columns.map((column, columnIndex) => {
  let fixed: TableV2FixedDir | undefined = undefined
  if (columnIndex < 3) fixed = TableV2FixedDir.LEFT
  if (columnIndex > 12) fixed = TableV2FixedDir.RIGHT
  return { ...column, fixed, width: 100 }
})

const CustomizedHeader: FunctionalComponent<
  TableV2CustomizedHeaderSlotParam
> = ({ cells, columns, headerIndex }) => {
  if (headerIndex === 2) return cells

  const groupCells = [] as typeof cells
  let width = 0
  let idx = 0

  columns.forEach((column, columnIndex) => {
    if (column.placeholderSign === TableV2Placeholder)
      groupCells.push(cells[columnIndex])
    else {
      width += cells[columnIndex].props!.column.width
      idx++

      const nextColumn = columns[columnIndex + 1]
      if (
        columnIndex === columns.length - 1 ||
        nextColumn.placeholderSign === TableV2Placeholder ||
        idx === (headerIndex === 0 ? 4 : 2)
      ) {
        groupCells.push(
          <div
            class="flex items-center justify-center custom-header-cell"
            role="columnheader"
            style={{
              ...cells[columnIndex].props!.style,
              width: `${width}px`,
            }}
          >
            Group width {width}
          </div>
        )
        width = 0
        idx = 0
      }
    }
  })
  return groupCells
}

const headerClass = ({
  headerIndex,
}: Parameters<HeaderClassNameGetter<any>>[0]) => {
  if (headerIndex === 1) return 'el-primary-color'
  return ''
}
</script>

<style>
.el-el-table-v2__header-row .custom-header-cell {
  border-right: 1px solid var(--el-border-color);
}

.el-el-table-v2__header-row .custom-header-cell:last-child {
  border-right: none;
}

.el-primary-color {
  background-color: var(--el-color-primary);
  color: var(--el-color-white);
  font-size: 14px;
  font-weight: bold;
}

.el-primary-color .custom-header-cell {
  padding: 0 4px;
}
</style>
```

隐藏源代码

## 过滤器 [​](#过滤器)

虚拟表格提供自定义页眉渲染器以创建自定义标题。 然后我们可以利用这些来渲染过滤器。

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

Row 0 - Col 0

Row 0 - Col 1

Row 1 - Col 0

Row 1 - Col 1

Row 2 - Col 0

Row 2 - Col 1

Row 3 - Col 0

Row 3 - Col 1

Row 4 - Col 0

Row 4 - Col 1

Row 5 - Col 0

Row 5 - Col 1

Row 6 - Col 0

Row 6 - Col 1

Row 7 - Col 0

Row 7 - Col 1

Row 8 - Col 0

Row 8 - Col 1

Column 0

Column 1

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICBmaXhlZFxuICAgIDpjb2x1bW5zPVwiZml4ZWRDb2x1bW5zXCJcbiAgICA6ZGF0YT1cImRhdGFcIlxuICAgIDp3aWR0aD1cIjcwMFwiXG4gICAgOmhlaWdodD1cIjQwMFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c3hcIiBzZXR1cD5cbmltcG9ydCB7IGNvbXB1dGVkLCByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQge1xuICBFbEJ1dHRvbixcbiAgRWxDaGVja2JveCxcbiAgRWxJY29uLFxuICBFbFBvcG92ZXIsXG4gIFRhYmxlVjJGaXhlZERpcixcbiAgdXNlTG9jYWxlLFxufSBmcm9tICdlbGVtZW50LXBsdXMnXG5pbXBvcnQgeyBGaWx0ZXIgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuaW1wb3J0IHR5cGUgeyBIZWFkZXJDZWxsU2xvdFByb3BzIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBnZW5lcmF0ZUNvbHVtbnMgPSAobGVuZ3RoID0gMTAsIHByZWZpeCA9ICdjb2x1bW4tJywgcHJvcHM/OiBhbnkpID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCBjb2x1bW5JbmRleCkgPT4gKHtcbiAgICAuLi5wcm9wcyxcbiAgICBrZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgZGF0YUtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICB0aXRsZTogYENvbHVtbiAke2NvbHVtbkluZGV4fWAsXG4gICAgd2lkdGg6IDE1MCxcbiAgfSkpXG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9IChcbiAgY29sdW1uczogUmV0dXJuVHlwZTx0eXBlb2YgZ2VuZXJhdGVDb2x1bW5zPixcbiAgbGVuZ3RoID0gMjAwLFxuICBwcmVmaXggPSAncm93LSdcbikgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIHJvd0luZGV4KSA9PiB7XG4gICAgcmV0dXJuIGNvbHVtbnMucmVkdWNlKFxuICAgICAgKHJvd0RhdGEsIGNvbHVtbiwgY29sdW1uSW5kZXgpID0+IHtcbiAgICAgICAgcm93RGF0YVtjb2x1bW4uZGF0YUtleV0gPSBgUm93ICR7cm93SW5kZXh9IC0gQ29sICR7Y29sdW1uSW5kZXh9YFxuICAgICAgICByZXR1cm4gcm93RGF0YVxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IGAke3ByZWZpeH0ke3Jvd0luZGV4fWAsXG4gICAgICAgIHBhcmVudElkOiBudWxsLFxuICAgICAgfVxuICAgIClcbiAgfSlcbmNvbnN0IGNvbHVtbnMgPSBnZW5lcmF0ZUNvbHVtbnMoMTApXG5jb25zdCBkYXRhID0gcmVmKGdlbmVyYXRlRGF0YShjb2x1bW5zLCAyMDApKVxuXG5jb25zdCB7IHQgfSA9IHVzZUxvY2FsZSgpXG5jb25zdCBzaG91bGRGaWx0ZXIgPSByZWYoZmFsc2UpXG5jb25zdCBwb3BvdmVyUmVmID0gcmVmKClcblxuY29uc3QgYXJpYUxhYmVsID0gY29tcHV0ZWQoKCkgPT4ge1xuICByZXR1cm4gdCgnZWwudGFibGUuZmlsdGVyTGFiZWwnLCB7IGNvbHVtbjogY29sdW1uc1swXS50aXRsZSB9KVxufSlcblxuY29uc3Qgb25GaWx0ZXIgPSAoKSA9PiB7XG4gIHBvcG92ZXJSZWYudmFsdWUuaGlkZSgpXG4gIGlmIChzaG91bGRGaWx0ZXIudmFsdWUpIHtcbiAgICBkYXRhLnZhbHVlID0gZ2VuZXJhdGVEYXRhKGNvbHVtbnMsIDEwMCwgJ2ZpbHRlcmVkLScpXG4gIH0gZWxzZSB7XG4gICAgZGF0YS52YWx1ZSA9IGdlbmVyYXRlRGF0YShjb2x1bW5zLCAyMDApXG4gIH1cbn1cblxuY29uc3Qgb25SZXNldCA9ICgpID0+IHtcbiAgc2hvdWxkRmlsdGVyLnZhbHVlID0gZmFsc2VcbiAgb25GaWx0ZXIoKVxufVxuXG5jb25zdCBoYW5kbGVTaG93UG9wb3ZlciA9ICgpID0+IHtcbiAgY29uc3QgYnV0dG9uID0gZG9jdW1lbnQucXVlcnlTZWxlY3RvcignLmVsLXRhYmxlLXYyX19kZW1vLWZpbHRlciBidXR0b24nKVxuICA7KGJ1dHRvbiBhcyBIVE1MRWxlbWVudCk/LmZvY3VzKClcbn1cblxuY29sdW1uc1swXS5oZWFkZXJDZWxsUmVuZGVyZXIgPSAocHJvcHM6IEhlYWRlckNlbGxTbG90UHJvcHMpID0+IHtcbiAgcmV0dXJuIChcbiAgICA8ZGl2IGNsYXNzPVwiZmxleCBpdGVtcy1jZW50ZXIganVzdGlmeS1jZW50ZXJcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwibXItMiB0ZXh0LXhzXCI+e3Byb3BzLmNvbHVtbi50aXRsZX08L3NwYW4+XG4gICAgICA8RWxQb3BvdmVyXG4gICAgICAgIHJlZj17cG9wb3ZlclJlZn1cbiAgICAgICAgdHJpZ2dlcj1cImNsaWNrXCJcbiAgICAgICAgd2lkdGg9ezIwMH1cbiAgICAgICAgb25BZnRlci1lbnRlcj17aGFuZGxlU2hvd1BvcG92ZXJ9XG4gICAgICA+XG4gICAgICAgIHt7XG4gICAgICAgICAgZGVmYXVsdDogKCkgPT4gKFxuICAgICAgICAgICAgPGRpdiBjbGFzcz1cImZpbHRlci13cmFwcGVyXCI+XG4gICAgICAgICAgICAgIDxkaXYgY2xhc3M9XCJmaWx0ZXItZ3JvdXBcIj5cbiAgICAgICAgICAgICAgICA8RWxDaGVja2JveCB2LW1vZGVsPXtzaG91bGRGaWx0ZXIudmFsdWV9PlxuICAgICAgICAgICAgICAgICAgRmlsdGVyIFRleHRcbiAgICAgICAgICAgICAgICA8L0VsQ2hlY2tib3g+XG4gICAgICAgICAgICAgIDwvZGl2PlxuICAgICAgICAgICAgICA8ZGl2IGNsYXNzPVwiZWwtdGFibGUtdjJfX2RlbW8tZmlsdGVyXCI+XG4gICAgICAgICAgICAgICAgPEVsQnV0dG9uIHRleHQgb25DbGljaz17b25GaWx0ZXJ9PlxuICAgICAgICAgICAgICAgICAgQ29uZmlybVxuICAgICAgICAgICAgICAgIDwvRWxCdXR0b24+XG4gICAgICAgICAgICAgICAgPEVsQnV0dG9uIHRleHQgb25DbGljaz17b25SZXNldH0+XG4gICAgICAgICAgICAgICAgICBSZXNldFxuICAgICAgICAgICAgICAgIDwvRWxCdXR0b24+XG4gICAgICAgICAgICAgIDwvZGl2PlxuICAgICAgICAgICAgPC9kaXY+XG4gICAgICAgICAgKSxcbiAgICAgICAgICByZWZlcmVuY2U6ICgpID0+IChcbiAgICAgICAgICAgIDxidXR0b25cbiAgICAgICAgICAgICAgdHlwZT1cImJ1dHRvblwiXG4gICAgICAgICAgICAgIGFyaWEtbGFiZWw9e2FyaWFMYWJlbC52YWx1ZX1cbiAgICAgICAgICAgICAgY2xhc3M9XCJlbC10YWJsZS12Ml9fZGVtby1maWx0ZXItYnRuXCJcbiAgICAgICAgICAgID5cbiAgICAgICAgICAgICAgPEVsSWNvbiBzaXplPXsxNH0+XG4gICAgICAgICAgICAgICAgPEZpbHRlciAvPlxuICAgICAgICAgICAgICA8L0VsSWNvbj5cbiAgICAgICAgICAgIDwvYnV0dG9uPlxuICAgICAgICAgICksXG4gICAgICAgIH19XG4gICAgICA8L0VsUG9wb3Zlcj5cbiAgICA8L2Rpdj5cbiAgKVxufVxuXG5jb25zdCBmaXhlZENvbHVtbnMgPSBjb2x1bW5zLm1hcCgoY29sdW1uLCBjb2x1bW5JbmRleCkgPT4ge1xuICBsZXQgZml4ZWQ6IFRhYmxlVjJGaXhlZERpciB8IHVuZGVmaW5lZCA9IHVuZGVmaW5lZFxuICBpZiAoY29sdW1uSW5kZXggPCAyKSBmaXhlZCA9IFRhYmxlVjJGaXhlZERpci5MRUZUXG4gIGlmIChjb2x1bW5JbmRleCA+IDkpIGZpeGVkID0gVGFibGVWMkZpeGVkRGlyLlJJR0hUXG4gIHJldHVybiB7IC4uLmNvbHVtbiwgZml4ZWQsIHdpZHRoOiAxMDAgfVxufSlcbjwvc2NyaXB0PlxuXG48c3R5bGU+XG4uZWwtdGFibGUtdjJfX2RlbW8tZmlsdGVyIHtcbiAgYm9yZGVyLXRvcDogdmFyKC0tZWwtYm9yZGVyKTtcbiAgbWFyZ2luOiAxMnB4IC0xMnB4IC0xMnB4O1xuICBwYWRkaW5nOiAwIDEycHg7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGp1c3RpZnktY29udGVudDogc3BhY2UtYmV0d2Vlbjtcbn1cbi5lbC10YWJsZS12Ml9fZGVtby1maWx0ZXItYnRuIHtcbiAgZGlzcGxheTogZmxleDtcbiAgY3Vyc29yOiBwb2ludGVyO1xuICBwYWRkaW5nOiAwO1xuICBtYXJnaW46IDA7XG4gIGJhY2tncm91bmQtY29sb3I6IHRyYW5zcGFyZW50O1xuICBhcHBlYXJhbmNlOiBub25lO1xuICBib3JkZXI6IG5vbmU7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/filter.vue)_

vue

```
<template>
  <el-table-v2
    fixed
    :columns="fixedColumns"
    :data="data"
    :width="700"
    :height="400"
  />
</template>

<script lang="tsx" setup>
import { computed, ref } from 'vue'
import {
  ElButton,
  ElCheckbox,
  ElIcon,
  ElPopover,
  TableV2FixedDir,
  useLocale,
} from 'element-plus'
import { Filter } from '@element-plus/icons-vue'

import type { HeaderCellSlotProps } from 'element-plus'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })
const columns = generateColumns(10)
const data = ref(generateData(columns, 200))

const { t } = useLocale()
const shouldFilter = ref(false)
const popoverRef = ref()

const ariaLabel = computed(() => {
  return t('el.table.filterLabel', { column: columns[0].title })
})

const onFilter = () => {
  popoverRef.value.hide()
  if (shouldFilter.value) {
    data.value = generateData(columns, 100, 'filtered-')
  } else {
    data.value = generateData(columns, 200)
  }
}

const onReset = () => {
  shouldFilter.value = false
  onFilter()
}

const handleShowPopover = () => {
  const button = document.querySelector('.el-table-v2__demo-filter button')
  ;(button as HTMLElement)?.focus()
}

columns[0].headerCellRenderer = (props: HeaderCellSlotProps) => {
  return (
    <div class="flex items-center justify-center">
      <span class="mr-2 text-xs">{props.column.title}</span>
      <ElPopover
        ref={popoverRef}
        trigger="click"
        width={200}
        onAfter-enter={handleShowPopover}
      >
        {{
          default: () => (
            <div class="filter-wrapper">
              <div class="filter-group">
                <ElCheckbox v-model={shouldFilter.value}>
                  Filter Text
                </ElCheckbox>
              </div>
              <div class="el-table-v2__demo-filter">
                <ElButton text onClick={onFilter}>
                  Confirm
                </ElButton>
                <ElButton text onClick={onReset}>
                  Reset
                </ElButton>
              </div>
            </div>
          ),
          reference: () => (
            <button
              type="button"
              aria-label={ariaLabel.value}
              class="el-table-v2__demo-filter-btn"
            >
              <ElIcon size={14}>
                <Filter />
              </ElIcon>
            </button>
          ),
        }}
      </ElPopover>
    </div>
  )
}

const fixedColumns = columns.map((column, columnIndex) => {
  let fixed: TableV2FixedDir | undefined = undefined
  if (columnIndex < 2) fixed = TableV2FixedDir.LEFT
  if (columnIndex > 9) fixed = TableV2FixedDir.RIGHT
  return { ...column, fixed, width: 100 }
})
</script>

<style>
.el-table-v2__demo-filter {
  border-top: var(--el-border);
  margin: 12px -12px -12px;
  padding: 0 12px;
  display: flex;
  justify-content: space-between;
}
.el-table-v2__demo-filter-btn {
  display: flex;
  cursor: pointer;
  padding: 0;
  margin: 0;
  background-color: transparent;
  appearance: none;
  border: none;
}
</style>
```

隐藏源代码

## 可排序表格 [​](#可排序表格)

您可以使用排序状态来对表格进行排序。

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgOnNvcnQtYnk9XCJzb3J0U3RhdGVcIlxuICAgIDp3aWR0aD1cIjcwMFwiXG4gICAgOmhlaWdodD1cIjQwMFwiXG4gICAgZml4ZWRcbiAgICBAY29sdW1uLXNvcnQ9XCJvblNvcnRcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IFRhYmxlVjJTb3J0T3JkZXIgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmltcG9ydCB0eXBlIHsgU29ydEJ5IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBnZW5lcmF0ZUNvbHVtbnMgPSAobGVuZ3RoID0gMTAsIHByZWZpeCA9ICdjb2x1bW4tJywgcHJvcHM/OiBhbnkpID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCBjb2x1bW5JbmRleCkgPT4gKHtcbiAgICAuLi5wcm9wcyxcbiAgICBrZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgZGF0YUtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICB0aXRsZTogYENvbHVtbiAke2NvbHVtbkluZGV4fWAsXG4gICAgd2lkdGg6IDE1MCxcbiAgfSkpXG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9IChcbiAgY29sdW1uczogUmV0dXJuVHlwZTx0eXBlb2YgZ2VuZXJhdGVDb2x1bW5zPixcbiAgbGVuZ3RoID0gMjAwLFxuICBwcmVmaXggPSAncm93LSdcbikgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIHJvd0luZGV4KSA9PiB7XG4gICAgcmV0dXJuIGNvbHVtbnMucmVkdWNlKFxuICAgICAgKHJvd0RhdGEsIGNvbHVtbiwgY29sdW1uSW5kZXgpID0+IHtcbiAgICAgICAgcm93RGF0YVtjb2x1bW4uZGF0YUtleV0gPSBgUm93ICR7cm93SW5kZXh9IC0gQ29sICR7Y29sdW1uSW5kZXh9YFxuICAgICAgICByZXR1cm4gcm93RGF0YVxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IGAke3ByZWZpeH0ke3Jvd0luZGV4fWAsXG4gICAgICAgIHBhcmVudElkOiBudWxsLFxuICAgICAgfVxuICAgIClcbiAgfSlcblxuY29uc3QgY29sdW1ucyA9IGdlbmVyYXRlQ29sdW1ucygxMClcbmxldCBkYXRhID0gZ2VuZXJhdGVEYXRhKGNvbHVtbnMsIDIwMClcblxuY29sdW1uc1swXS5zb3J0YWJsZSA9IHRydWVcblxuY29uc3Qgc29ydFN0YXRlID0gcmVmPFNvcnRCeT4oe1xuICBrZXk6ICdjb2x1bW4tMCcsXG4gIG9yZGVyOiBUYWJsZVYyU29ydE9yZGVyLkFTQyxcbn0pXG5cbmNvbnN0IG9uU29ydCA9IChzb3J0Qnk6IFNvcnRCeSkgPT4ge1xuICBjb25zb2xlLmxvZyhzb3J0QnkpXG4gIGRhdGEgPSBkYXRhLnJldmVyc2UoKVxuICBzb3J0U3RhdGUudmFsdWUgPSBzb3J0Qnlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/sort.vue)_

vue

```
<template>
  <el-table-v2
    :columns="columns"
    :data="data"
    :sort-by="sortState"
    :width="700"
    :height="400"
    fixed
    @column-sort="onSort"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { TableV2SortOrder } from 'element-plus'

import type { SortBy } from 'element-plus'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
let data = generateData(columns, 200)

columns[0].sortable = true

const sortState = ref<SortBy>({
  key: 'column-0',
  order: TableV2SortOrder.ASC,
})

const onSort = (sortBy: SortBy) => {
  console.log(sortBy)
  data = data.reverse()
  sortState.value = sortBy
}
</script>
```

隐藏源代码

## 受控的排序 [​](#受控的排序)

您可以在需要时定义多个可排序的列。 请记住，当您在定义了多个可排序的列时， UI 可能会显得有些奇怪，因为用户不知道哪一列被排序。

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICB2LW1vZGVsOnNvcnQtc3RhdGU9XCJzb3J0U3RhdGVcIlxuICAgIDpjb2x1bW5zPVwiY29sdW1uc1wiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6d2lkdGg9XCI3MDBcIlxuICAgIDpoZWlnaHQ9XCI0MDBcIlxuICAgIGZpeGVkXG4gICAgQGNvbHVtbi1zb3J0PVwib25Tb3J0XCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBUYWJsZVYyU29ydE9yZGVyIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbXBvcnQgdHlwZSB7IFNvcnRCeSwgU29ydFN0YXRlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBnZW5lcmF0ZUNvbHVtbnMgPSAobGVuZ3RoID0gMTAsIHByZWZpeCA9ICdjb2x1bW4tJywgcHJvcHM/OiBhbnkpID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCBjb2x1bW5JbmRleCkgPT4gKHtcbiAgICAuLi5wcm9wcyxcbiAgICBrZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgZGF0YUtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICB0aXRsZTogYENvbHVtbiAke2NvbHVtbkluZGV4fWAsXG4gICAgd2lkdGg6IDE1MCxcbiAgfSkpXG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9IChcbiAgY29sdW1uczogUmV0dXJuVHlwZTx0eXBlb2YgZ2VuZXJhdGVDb2x1bW5zPixcbiAgbGVuZ3RoID0gMjAwLFxuICBwcmVmaXggPSAncm93LSdcbikgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIHJvd0luZGV4KSA9PiB7XG4gICAgcmV0dXJuIGNvbHVtbnMucmVkdWNlKFxuICAgICAgKHJvd0RhdGEsIGNvbHVtbiwgY29sdW1uSW5kZXgpID0+IHtcbiAgICAgICAgcm93RGF0YVtjb2x1bW4uZGF0YUtleV0gPSBgUm93ICR7cm93SW5kZXh9IC0gQ29sICR7Y29sdW1uSW5kZXh9YFxuICAgICAgICByZXR1cm4gcm93RGF0YVxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IGAke3ByZWZpeH0ke3Jvd0luZGV4fWAsXG4gICAgICAgIHBhcmVudElkOiBudWxsLFxuICAgICAgfVxuICAgIClcbiAgfSlcblxuY29uc3QgY29sdW1ucyA9IGdlbmVyYXRlQ29sdW1ucygxMClcbmNvbnN0IGRhdGEgPSByZWYoZ2VuZXJhdGVEYXRhKGNvbHVtbnMsIDIwMCkpXG5cbmNvbHVtbnNbMF0uc29ydGFibGUgPSB0cnVlXG5jb2x1bW5zWzFdLnNvcnRhYmxlID0gdHJ1ZVxuXG5jb25zdCBzb3J0U3RhdGUgPSByZWY8U29ydFN0YXRlPih7XG4gICdjb2x1bW4tMCc6IFRhYmxlVjJTb3J0T3JkZXIuREVTQyxcbiAgJ2NvbHVtbi0xJzogVGFibGVWMlNvcnRPcmRlci5BU0MsXG59KVxuXG5jb25zdCBvblNvcnQgPSAoeyBrZXksIG9yZGVyIH06IFNvcnRCeSkgPT4ge1xuICBzb3J0U3RhdGUudmFsdWVba2V5XSA9IG9yZGVyXG4gIGRhdGEudmFsdWUgPSBkYXRhLnZhbHVlLnJldmVyc2UoKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/controlled-sort.vue)_

vue

```
<template>
  <el-table-v2
    v-model:sort-state="sortState"
    :columns="columns"
    :data="data"
    :width="700"
    :height="400"
    fixed
    @column-sort="onSort"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { TableV2SortOrder } from 'element-plus'

import type { SortBy, SortState } from 'element-plus'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
const data = ref(generateData(columns, 200))

columns[0].sortable = true
columns[1].sortable = true

const sortState = ref<SortState>({
  'column-0': TableV2SortOrder.DESC,
  'column-1': TableV2SortOrder.ASC,
})

const onSort = ({ key, order }: SortBy) => {
  sortState.value[key] = order
  data.value = data.value.reverse()
}
</script>
```

隐藏源代码

## 高亮显示鼠标悬停单元格 [​](#高亮显示鼠标悬停单元格)

当处理一个大的列表时，很容易丢失当前行的轨迹和您正在访问的一列。 在这种情况下，使用这个功能可能很有帮助。

1

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 0 - Col 10

2

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 1 - Col 10

3

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 2 - Col 10

4

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 3 - Col 10

5

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 4 - Col 10

6

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 5 - Col 10

7

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 6 - Col 10

8

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 7 - Col 10

9

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Row 8 - Col 10

Row No.

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwiaGVpZ2h0OiA0MDBweFwiPlxuICAgIDxlbC1hdXRvLXJlc2l6ZXI+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJ7IGhlaWdodCwgd2lkdGggfVwiPlxuICAgICAgICA8ZWwtdGFibGUtdjJcbiAgICAgICAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgICAgICAgIDpjZWxsLXByb3BzPVwiY2VsbFByb3BzXCJcbiAgICAgICAgICA6Y2xhc3M9XCJrbHNcIlxuICAgICAgICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgICAgICAgOndpZHRoPVwid2lkdGhcIlxuICAgICAgICAgIDpoZWlnaHQ9XCJoZWlnaHRcIlxuICAgICAgICAvPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWF1dG8tcmVzaXplcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBnZW5lcmF0ZUNvbHVtbnMgPSAobGVuZ3RoID0gMTAsIHByZWZpeCA9ICdjb2x1bW4tJywgcHJvcHM/OiBhbnkpID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCBjb2x1bW5JbmRleCkgPT4gKHtcbiAgICAuLi5wcm9wcyxcbiAgICBrZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgZGF0YUtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICB0aXRsZTogYENvbHVtbiAke2NvbHVtbkluZGV4fWAsXG4gICAgd2lkdGg6IDE1MCxcbiAgfSkpXG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9IChcbiAgY29sdW1uczogUmV0dXJuVHlwZTx0eXBlb2YgZ2VuZXJhdGVDb2x1bW5zPixcbiAgbGVuZ3RoID0gMjAwLFxuICBwcmVmaXggPSAncm93LSdcbikgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIHJvd0luZGV4KSA9PiB7XG4gICAgcmV0dXJuIGNvbHVtbnMucmVkdWNlKFxuICAgICAgKHJvd0RhdGEsIGNvbHVtbiwgY29sdW1uSW5kZXgpID0+IHtcbiAgICAgICAgcm93RGF0YVtjb2x1bW4uZGF0YUtleV0gPSBgUm93ICR7cm93SW5kZXh9IC0gQ29sICR7Y29sdW1uSW5kZXh9YFxuICAgICAgICByZXR1cm4gcm93RGF0YVxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IGAke3ByZWZpeH0ke3Jvd0luZGV4fWAsXG4gICAgICAgIHBhcmVudElkOiBudWxsLFxuICAgICAgfVxuICAgIClcbiAgfSlcblxuY29uc3QgY29sdW1ucyA9IGdlbmVyYXRlQ29sdW1ucygxMClcbmNvbHVtbnMudW5zaGlmdCh7XG4gIGtleTogJ2NvbHVtbi1uLTEnLFxuICB3aWR0aDogNTAsXG4gIHRpdGxlOiAnUm93IE5vLicsXG4gIGNlbGxSZW5kZXJlcjogKHsgcm93SW5kZXggfSkgPT4gYCR7cm93SW5kZXggKyAxfWAsXG4gIGFsaWduOiAnY2VudGVyJyxcbn0pXG5jb25zdCBkYXRhID0gZ2VuZXJhdGVEYXRhKGNvbHVtbnMsIDIwMClcblxuY29uc3QgY2VsbFByb3BzID0gKHsgY29sdW1uSW5kZXggfSkgPT4ge1xuICBjb25zdCBrZXkgPSBgaG92ZXJpbmctY29sLSR7Y29sdW1uSW5kZXh9YFxuICByZXR1cm4ge1xuICAgIFsnZGF0YS1rZXknXToga2V5LFxuICAgIG9uTW91c2VlbnRlcjogKCkgPT4ge1xuICAgICAga2xzLnZhbHVlID0ga2V5XG4gICAgfSxcbiAgICBvbk1vdXNlbGVhdmU6ICgpID0+IHtcbiAgICAgIGtscy52YWx1ZSA9ICcnXG4gICAgfSxcbiAgfVxufVxuXG5jb25zdCBrbHMgPSByZWY8c3RyaW5nPignJylcbjwvc2NyaXB0PlxuXG48c3R5bGU+XG4uaG92ZXJpbmctY29sLTAgW2RhdGEta2V5PSdob3ZlcmluZy1jb2wtMCddLFxuLmhvdmVyaW5nLWNvbC0xIFtkYXRhLWtleT0naG92ZXJpbmctY29sLTEnXSxcbi5ob3ZlcmluZy1jb2wtMiBbZGF0YS1rZXk9J2hvdmVyaW5nLWNvbC0yJ10sXG4uaG92ZXJpbmctY29sLTMgW2RhdGEta2V5PSdob3ZlcmluZy1jb2wtMyddLFxuLmhvdmVyaW5nLWNvbC00IFtkYXRhLWtleT0naG92ZXJpbmctY29sLTQnXSxcbi5ob3ZlcmluZy1jb2wtNSBbZGF0YS1rZXk9J2hvdmVyaW5nLWNvbC01J10sXG4uaG92ZXJpbmctY29sLTYgW2RhdGEta2V5PSdob3ZlcmluZy1jb2wtNiddLFxuLmhvdmVyaW5nLWNvbC03IFtkYXRhLWtleT0naG92ZXJpbmctY29sLTcnXSxcbi5ob3ZlcmluZy1jb2wtOCBbZGF0YS1rZXk9J2hvdmVyaW5nLWNvbC04J10sXG4uaG92ZXJpbmctY29sLTkgW2RhdGEta2V5PSdob3ZlcmluZy1jb2wtOSddLFxuLmhvdmVyaW5nLWNvbC0xMCBbZGF0YS1rZXk9J2hvdmVyaW5nLWNvbC0xMCddIHtcbiAgYmFja2dyb3VuZDogdmFyKC0tZWwtdGFibGUtcm93LWhvdmVyLWJnLWNvbG9yKTtcbn1cblxuW2RhdGEta2V5PSdob3ZlcmluZy1jb2wtMCddIHtcbiAgZm9udC13ZWlnaHQ6IGJvbGQ7XG4gIHVzZXItc2VsZWN0OiBub25lO1xuICBwb2ludGVyLWV2ZW50czogbm9uZTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/cross-hovering.vue)_

vue

```
<template>
  <div style="height: 400px">
    <el-auto-resizer>
      <template #default="{ height, width }">
        <el-table-v2
          :columns="columns"
          :cell-props="cellProps"
          :class="kls"
          :data="data"
          :width="width"
          :height="height"
        />
      </template>
    </el-auto-resizer>
  </div>
</template>

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

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
columns.unshift({
  key: 'column-n-1',
  width: 50,
  title: 'Row No.',
  cellRenderer: ({ rowIndex }) => `${rowIndex + 1}`,
  align: 'center',
})
const data = generateData(columns, 200)

const cellProps = ({ columnIndex }) => {
  const key = `hovering-col-${columnIndex}`
  return {
    ['data-key']: key,
    onMouseenter: () => {
      kls.value = key
    },
    onMouseleave: () => {
      kls.value = ''
    },
  }
}

const kls = ref<string>('')
</script>

<style>
.hovering-col-0 [data-key='hovering-col-0'],
.hovering-col-1 [data-key='hovering-col-1'],
.hovering-col-2 [data-key='hovering-col-2'],
.hovering-col-3 [data-key='hovering-col-3'],
.hovering-col-4 [data-key='hovering-col-4'],
.hovering-col-5 [data-key='hovering-col-5'],
.hovering-col-6 [data-key='hovering-col-6'],
.hovering-col-7 [data-key='hovering-col-7'],
.hovering-col-8 [data-key='hovering-col-8'],
.hovering-col-9 [data-key='hovering-col-9'],
.hovering-col-10 [data-key='hovering-col-10'] {
  background: var(--el-table-row-hover-bg-color);
}

[data-key='hovering-col-0'] {
  font-weight: bold;
  user-select: none;
  pointer-events: none;
}
</style>
```

隐藏源代码

## 横跨列 [​](#横跨列)

虚拟化表格没有使用内置的 `table` 元素，故 `colspan` 和 `rowspan` 与 [TableV1](https://element-plus.org/zh-CN/component/table) 比较略有不同。 然而，通过定制的行渲染器，这些功能仍然可以实现。 在本节中，我们将演示如何实现这一点。

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjIgZml4ZWQgOmNvbHVtbnM9XCJjb2x1bW5zXCIgOmRhdGE9XCJkYXRhXCIgOndpZHRoPVwiNzAwXCIgOmhlaWdodD1cIjQwMFwiPlxuICAgIDx0ZW1wbGF0ZSAjcm93PVwicHJvcHNcIj5cbiAgICAgIDxSb3cgdi1iaW5kPVwicHJvcHNcIiAvPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtdGFibGUtdjI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgY2xvbmVWTm9kZSB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgZ2VuZXJhdGVDb2x1bW5zID0gKGxlbmd0aCA9IDEwLCBwcmVmaXggPSAnY29sdW1uLScsIHByb3BzPzogYW55KSA9PlxuICBBcnJheS5mcm9tKHsgbGVuZ3RoIH0pLm1hcCgoXywgY29sdW1uSW5kZXgpID0+ICh7XG4gICAgLi4ucHJvcHMsXG4gICAga2V5OiBgJHtwcmVmaXh9JHtjb2x1bW5JbmRleH1gLFxuICAgIGRhdGFLZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgdGl0bGU6IGBDb2x1bW4gJHtjb2x1bW5JbmRleH1gLFxuICAgIHdpZHRoOiAxNTAsXG4gIH0pKVxuXG5jb25zdCBnZW5lcmF0ZURhdGEgPSAoXG4gIGNvbHVtbnM6IFJldHVyblR5cGU8dHlwZW9mIGdlbmVyYXRlQ29sdW1ucz4sXG4gIGxlbmd0aCA9IDIwMCxcbiAgcHJlZml4ID0gJ3Jvdy0nXG4pID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCByb3dJbmRleCkgPT4ge1xuICAgIHJldHVybiBjb2x1bW5zLnJlZHVjZShcbiAgICAgIChyb3dEYXRhLCBjb2x1bW4sIGNvbHVtbkluZGV4KSA9PiB7XG4gICAgICAgIHJvd0RhdGFbY29sdW1uLmRhdGFLZXldID0gYFJvdyAke3Jvd0luZGV4fSAtIENvbCAke2NvbHVtbkluZGV4fWBcbiAgICAgICAgcmV0dXJuIHJvd0RhdGFcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIGlkOiBgJHtwcmVmaXh9JHtyb3dJbmRleH1gLFxuICAgICAgICBwYXJlbnRJZDogbnVsbCxcbiAgICAgIH1cbiAgICApXG4gIH0pXG5cbmNvbnN0IGNvbHVtbnMgPSBnZW5lcmF0ZUNvbHVtbnMoMTApXG5jb25zdCBkYXRhID0gZ2VuZXJhdGVEYXRhKGNvbHVtbnMsIDIwMClcblxuY29uc3QgY29sU3BhbkluZGV4ID0gMVxuY29sdW1uc1tjb2xTcGFuSW5kZXhdLmNvbFNwYW4gPSAoeyByb3dJbmRleCB9KSA9PiAocm93SW5kZXggJSA0KSArIDFcbmNvbHVtbnNbY29sU3BhbkluZGV4XS5hbGlnbiA9ICdjZW50ZXInXG5cbmNvbnN0IFJvdyA9ICh7IHJvd0RhdGEsIHJvd0luZGV4LCBjZWxscywgY29sdW1ucyB9KSA9PiB7XG4gIGNvbnN0IGNvbFNwYW4gPSBjb2x1bW5zW2NvbFNwYW5JbmRleF0uY29sU3Bhbih7IHJvd0RhdGEsIHJvd0luZGV4IH0pXG4gIGlmIChjb2xTcGFuID4gMSkge1xuICAgIGxldCB3aWR0aCA9IE51bWJlci5wYXJzZUludChjZWxsc1tjb2xTcGFuSW5kZXhdLnByb3BzLnN0eWxlLndpZHRoKVxuICAgIGZvciAobGV0IGkgPSAxOyBpIDwgY29sU3BhbjsgaSsrKSB7XG4gICAgICB3aWR0aCArPSBOdW1iZXIucGFyc2VJbnQoY2VsbHNbY29sU3BhbkluZGV4ICsgaV0ucHJvcHMuc3R5bGUud2lkdGgpXG4gICAgICBjZWxsc1tjb2xTcGFuSW5kZXggKyBpXSA9IG51bGxcbiAgICB9XG4gICAgY29uc3Qgc3R5bGUgPSB7XG4gICAgICAuLi5jZWxsc1tjb2xTcGFuSW5kZXhdLnByb3BzLnN0eWxlLFxuICAgICAgd2lkdGg6IGAke3dpZHRofXB4YCxcbiAgICAgIGJhY2tncm91bmRDb2xvcjogJ3ZhcigtLWVsLWNvbG9yLXByaW1hcnktbGlnaHQtMyknLFxuICAgIH1cbiAgICBjZWxsc1tjb2xTcGFuSW5kZXhdID0gY2xvbmVWTm9kZShjZWxsc1tjb2xTcGFuSW5kZXhdLCB7IHN0eWxlIH0pXG4gIH1cblxuICByZXR1cm4gY2VsbHNcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/colspan.vue)_

vue

```
<template>
  <el-table-v2 fixed :columns="columns" :data="data" :width="700" :height="400">
    <template #row="props">
      <Row v-bind="props" />
    </template>
  </el-table-v2>
</template>

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

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
const data = generateData(columns, 200)

const colSpanIndex = 1
columns[colSpanIndex].colSpan = ({ rowIndex }) => (rowIndex % 4) + 1
columns[colSpanIndex].align = 'center'

const Row = ({ rowData, rowIndex, cells, columns }) => {
  const colSpan = columns[colSpanIndex].colSpan({ rowData, rowIndex })
  if (colSpan > 1) {
    let width = Number.parseInt(cells[colSpanIndex].props.style.width)
    for (let i = 1; i < colSpan; i++) {
      width += Number.parseInt(cells[colSpanIndex + i].props.style.width)
      cells[colSpanIndex + i] = null
    }
    const style = {
      ...cells[colSpanIndex].props.style,
      width: `${width}px`,
      backgroundColor: 'var(--el-color-primary-light-3)',
    }
    cells[colSpanIndex] = cloneVNode(cells[colSpanIndex], { style })
  }

  return cells
}
</script>
```

隐藏源代码

## 纵跨行 [​](#纵跨行)

既然我们已经提到了 [Colspan](#colspan)，那跨行（row span）也是没有问题的。 它与colspan略有不同，但是基本原理是一样的。

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjIgZml4ZWQgOmNvbHVtbnM9XCJjb2x1bW5zXCIgOmRhdGE9XCJkYXRhXCIgOndpZHRoPVwiNzAwXCIgOmhlaWdodD1cIjQwMFwiPlxuICAgIDx0ZW1wbGF0ZSAjcm93PVwicHJvcHNcIj5cbiAgICAgIDxSb3cgdi1iaW5kPVwicHJvcHNcIiAvPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtdGFibGUtdjI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgY2xvbmVWTm9kZSB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgZ2VuZXJhdGVDb2x1bW5zID0gKGxlbmd0aCA9IDEwLCBwcmVmaXggPSAnY29sdW1uLScsIHByb3BzPzogYW55KSA9PlxuICBBcnJheS5mcm9tKHsgbGVuZ3RoIH0pLm1hcCgoXywgY29sdW1uSW5kZXgpID0+ICh7XG4gICAgLi4ucHJvcHMsXG4gICAga2V5OiBgJHtwcmVmaXh9JHtjb2x1bW5JbmRleH1gLFxuICAgIGRhdGFLZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgdGl0bGU6IGBDb2x1bW4gJHtjb2x1bW5JbmRleH1gLFxuICAgIHdpZHRoOiAxNTAsXG4gIH0pKVxuXG5jb25zdCBnZW5lcmF0ZURhdGEgPSAoXG4gIGNvbHVtbnM6IFJldHVyblR5cGU8dHlwZW9mIGdlbmVyYXRlQ29sdW1ucz4sXG4gIGxlbmd0aCA9IDIwMCxcbiAgcHJlZml4ID0gJ3Jvdy0nXG4pID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCByb3dJbmRleCkgPT4ge1xuICAgIHJldHVybiBjb2x1bW5zLnJlZHVjZShcbiAgICAgIChyb3dEYXRhLCBjb2x1bW4sIGNvbHVtbkluZGV4KSA9PiB7XG4gICAgICAgIHJvd0RhdGFbY29sdW1uLmRhdGFLZXldID0gYFJvdyAke3Jvd0luZGV4fSAtIENvbCAke2NvbHVtbkluZGV4fWBcbiAgICAgICAgcmV0dXJuIHJvd0RhdGFcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIGlkOiBgJHtwcmVmaXh9JHtyb3dJbmRleH1gLFxuICAgICAgICBwYXJlbnRJZDogbnVsbCxcbiAgICAgIH1cbiAgICApXG4gIH0pXG5cbmNvbnN0IGNvbHVtbnMgPSBnZW5lcmF0ZUNvbHVtbnMoMTApXG5jb25zdCBkYXRhID0gZ2VuZXJhdGVEYXRhKGNvbHVtbnMsIDIwMClcblxuY29uc3Qgcm93U3BhbkluZGV4ID0gMFxuY29sdW1uc1tyb3dTcGFuSW5kZXhdLnJvd1NwYW4gPSAoeyByb3dJbmRleCB9KSA9PlxuICByb3dJbmRleCAlIDIgPT09IDAgJiYgcm93SW5kZXggPD0gZGF0YS5sZW5ndGggLSAyID8gMiA6IDFcblxuY29uc3QgUm93ID0gKHsgcm93RGF0YSwgcm93SW5kZXgsIGNlbGxzLCBjb2x1bW5zIH0pID0+IHtcbiAgY29uc3Qgcm93U3BhbiA9IGNvbHVtbnNbcm93U3BhbkluZGV4XS5yb3dTcGFuKHsgcm93RGF0YSwgcm93SW5kZXggfSlcbiAgaWYgKHJvd1NwYW4gPiAxKSB7XG4gICAgY29uc3QgY2VsbCA9IGNlbGxzW3Jvd1NwYW5JbmRleF1cbiAgICBjb25zdCBzdHlsZSA9IHtcbiAgICAgIC4uLmNlbGwucHJvcHMuc3R5bGUsXG4gICAgICBiYWNrZ3JvdW5kQ29sb3I6ICd2YXIoLS1lbC1jb2xvci1wcmltYXJ5LWxpZ2h0LTMpJyxcbiAgICAgIGhlaWdodDogYCR7cm93U3BhbiAqIDUwIC0gMX1weGAsXG4gICAgICBhbGlnblNlbGY6ICdmbGV4LXN0YXJ0JyxcbiAgICAgIHpJbmRleDogMSxcbiAgICB9XG4gICAgY2VsbHNbcm93U3BhbkluZGV4XSA9IGNsb25lVk5vZGUoY2VsbCwgeyBzdHlsZSB9KVxuICB9XG4gIHJldHVybiBjZWxsc1xufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/rowspan.vue)_

vue

```
<template>
  <el-table-v2 fixed :columns="columns" :data="data" :width="700" :height="400">
    <template #row="props">
      <Row v-bind="props" />
    </template>
  </el-table-v2>
</template>

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

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
const data = generateData(columns, 200)

const rowSpanIndex = 0
columns[rowSpanIndex].rowSpan = ({ rowIndex }) =>
  rowIndex % 2 === 0 && rowIndex <= data.length - 2 ? 2 : 1

const Row = ({ rowData, rowIndex, cells, columns }) => {
  const rowSpan = columns[rowSpanIndex].rowSpan({ rowData, rowIndex })
  if (rowSpan > 1) {
    const cell = cells[rowSpanIndex]
    const style = {
      ...cell.props.style,
      backgroundColor: 'var(--el-color-primary-light-3)',
      height: `${rowSpan * 50 - 1}px`,
      alignSelf: 'flex-start',
      zIndex: 1,
    }
    cells[rowSpanIndex] = cloneVNode(cell, { style })
  }
  return cells
}
</script>
```

隐藏源代码

## 同时跨行和跨列 [​](#同时跨行和跨列)

我们当然可以同时使用横跨列与纵跨行来满足您的业务需求！

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 1

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 1

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 1

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 1

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjIgZml4ZWQgOmNvbHVtbnM9XCJjb2x1bW5zXCIgOmRhdGE9XCJkYXRhXCIgOndpZHRoPVwiNzAwXCIgOmhlaWdodD1cIjQwMFwiPlxuICAgIDx0ZW1wbGF0ZSAjcm93PVwicHJvcHNcIj5cbiAgICAgIDxSb3cgdi1iaW5kPVwicHJvcHNcIiAvPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtdGFibGUtdjI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c3hcIiBzZXR1cD5cbmltcG9ydCB7IGNsb25lVk5vZGUgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGdlbmVyYXRlQ29sdW1ucyA9IChsZW5ndGggPSAxMCwgcHJlZml4ID0gJ2NvbHVtbi0nLCBwcm9wcz86IGFueSkgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIGNvbHVtbkluZGV4KSA9PiAoe1xuICAgIC4uLnByb3BzLFxuICAgIGtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICBkYXRhS2V5OiBgJHtwcmVmaXh9JHtjb2x1bW5JbmRleH1gLFxuICAgIHRpdGxlOiBgQ29sdW1uICR7Y29sdW1uSW5kZXh9YCxcbiAgICB3aWR0aDogMTUwLFxuICB9KSlcblxuY29uc3QgZ2VuZXJhdGVEYXRhID0gKFxuICBjb2x1bW5zOiBSZXR1cm5UeXBlPHR5cGVvZiBnZW5lcmF0ZUNvbHVtbnM+LFxuICBsZW5ndGggPSAyMDAsXG4gIHByZWZpeCA9ICdyb3ctJ1xuKSA9PlxuICBBcnJheS5mcm9tKHsgbGVuZ3RoIH0pLm1hcCgoXywgcm93SW5kZXgpID0+IHtcbiAgICByZXR1cm4gY29sdW1ucy5yZWR1Y2UoXG4gICAgICAocm93RGF0YSwgY29sdW1uLCBjb2x1bW5JbmRleCkgPT4ge1xuICAgICAgICByb3dEYXRhW2NvbHVtbi5kYXRhS2V5XSA9IGBSb3cgJHtyb3dJbmRleH0gLSBDb2wgJHtjb2x1bW5JbmRleH1gXG4gICAgICAgIHJldHVybiByb3dEYXRhXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogYCR7cHJlZml4fSR7cm93SW5kZXh9YCxcbiAgICAgICAgcGFyZW50SWQ6IG51bGwsXG4gICAgICB9XG4gICAgKVxuICB9KVxuXG5jb25zdCBjb2x1bW5zID0gZ2VuZXJhdGVDb2x1bW5zKDEwKVxuY29uc3QgZGF0YSA9IGdlbmVyYXRlRGF0YShjb2x1bW5zLCAyMDApXG5cbmNvbnN0IGNvbFNwYW5JbmRleCA9IDFcbmNvbHVtbnNbY29sU3BhbkluZGV4XS5jb2xTcGFuID0gKHsgcm93SW5kZXggfSkgPT4gKHJvd0luZGV4ICUgNCkgKyAxXG5jb2x1bW5zW2NvbFNwYW5JbmRleF0uYWxpZ24gPSAnY2VudGVyJ1xuXG5jb25zdCByb3dTcGFuSW5kZXggPSAwXG5jb2x1bW5zW3Jvd1NwYW5JbmRleF0ucm93U3BhbiA9ICh7IHJvd0luZGV4IH0pID0+XG4gIHJvd0luZGV4ICUgMiA9PT0gMCAmJiByb3dJbmRleCA8PSBkYXRhLmxlbmd0aCAtIDIgPyAyIDogMVxuXG5jb25zdCBSb3cgPSAoeyByb3dEYXRhLCByb3dJbmRleCwgY2VsbHMsIGNvbHVtbnMgfSkgPT4ge1xuICBjb25zdCBjb2xTcGFuID0gY29sdW1uc1tjb2xTcGFuSW5kZXhdLmNvbFNwYW4oeyByb3dEYXRhLCByb3dJbmRleCB9KVxuICBpZiAoY29sU3BhbiA+IDEpIHtcbiAgICBsZXQgd2lkdGggPSBOdW1iZXIucGFyc2VJbnQoY2VsbHNbY29sU3BhbkluZGV4XS5wcm9wcy5zdHlsZS53aWR0aClcbiAgICBmb3IgKGxldCBpID0gMTsgaSA8IGNvbFNwYW47IGkrKykge1xuICAgICAgd2lkdGggKz0gTnVtYmVyLnBhcnNlSW50KGNlbGxzW2NvbFNwYW5JbmRleCArIGldLnByb3BzLnN0eWxlLndpZHRoKVxuICAgICAgY2VsbHNbY29sU3BhbkluZGV4ICsgaV0gPSBudWxsXG4gICAgfVxuICAgIGNvbnN0IHN0eWxlID0ge1xuICAgICAgLi4uY2VsbHNbY29sU3BhbkluZGV4XS5wcm9wcy5zdHlsZSxcbiAgICAgIHdpZHRoOiBgJHt3aWR0aH1weGAsXG4gICAgICBiYWNrZ3JvdW5kQ29sb3I6ICd2YXIoLS1lbC1jb2xvci1wcmltYXJ5LWxpZ2h0LTMpJyxcbiAgICB9XG4gICAgY2VsbHNbY29sU3BhbkluZGV4XSA9IGNsb25lVk5vZGUoY2VsbHNbY29sU3BhbkluZGV4XSwgeyBzdHlsZSB9KVxuICB9XG5cbiAgY29uc3Qgcm93U3BhbiA9IGNvbHVtbnNbcm93U3BhbkluZGV4XS5yb3dTcGFuKHsgcm93RGF0YSwgcm93SW5kZXggfSlcbiAgaWYgKHJvd1NwYW4gPiAxKSB7XG4gICAgY29uc3QgY2VsbCA9IGNlbGxzW3Jvd1NwYW5JbmRleF1cbiAgICBjb25zdCBzdHlsZSA9IHtcbiAgICAgIC4uLmNlbGwucHJvcHMuc3R5bGUsXG4gICAgICBiYWNrZ3JvdW5kQ29sb3I6ICd2YXIoLS1lbC1jb2xvci1kYW5nZXItbGlnaHQtMyknLFxuICAgICAgaGVpZ2h0OiBgJHtyb3dTcGFuICogNTB9cHhgLFxuICAgICAgYWxpZ25TZWxmOiAnZmxleC1zdGFydCcsXG4gICAgICB6SW5kZXg6IDEsXG4gICAgfVxuICAgIGNlbGxzW3Jvd1NwYW5JbmRleF0gPSBjbG9uZVZOb2RlKGNlbGwsIHsgc3R5bGUgfSlcbiAgfSBlbHNlIHtcbiAgICBjb25zdCBzdHlsZSA9IGNlbGxzW3Jvd1NwYW5JbmRleF0ucHJvcHMuc3R5bGVcbiAgICAvLyBvdmVycmlkZSB0aGUgY2VsbCBoZXJlIGZvciBjcmVhdGluZyBhIHB1cmUgbm9kZSB3aXRob3V0IHBvbGx1dGUgdGhlIHN0eWxlXG4gICAgY2VsbHNbcm93U3BhbkluZGV4XSA9IChcbiAgICAgIDxkaXYgc3R5bGU9e3sgLi4uc3R5bGUsIHdpZHRoOiBgJHtzdHlsZS53aWR0aH1weGAgfX0gLz5cbiAgICApXG4gIH1cbiAgcmV0dXJuIGNlbGxzXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/spans.vue)_

vue

```
<template>
  <el-table-v2 fixed :columns="columns" :data="data" :width="700" :height="400">
    <template #row="props">
      <Row v-bind="props" />
    </template>
  </el-table-v2>
</template>

<script lang="tsx" setup>
import { cloneVNode } from 'vue'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
const data = generateData(columns, 200)

const colSpanIndex = 1
columns[colSpanIndex].colSpan = ({ rowIndex }) => (rowIndex % 4) + 1
columns[colSpanIndex].align = 'center'

const rowSpanIndex = 0
columns[rowSpanIndex].rowSpan = ({ rowIndex }) =>
  rowIndex % 2 === 0 && rowIndex <= data.length - 2 ? 2 : 1

const Row = ({ rowData, rowIndex, cells, columns }) => {
  const colSpan = columns[colSpanIndex].colSpan({ rowData, rowIndex })
  if (colSpan > 1) {
    let width = Number.parseInt(cells[colSpanIndex].props.style.width)
    for (let i = 1; i < colSpan; i++) {
      width += Number.parseInt(cells[colSpanIndex + i].props.style.width)
      cells[colSpanIndex + i] = null
    }
    const style = {
      ...cells[colSpanIndex].props.style,
      width: `${width}px`,
      backgroundColor: 'var(--el-color-primary-light-3)',
    }
    cells[colSpanIndex] = cloneVNode(cells[colSpanIndex], { style })
  }

  const rowSpan = columns[rowSpanIndex].rowSpan({ rowData, rowIndex })
  if (rowSpan > 1) {
    const cell = cells[rowSpanIndex]
    const style = {
      ...cell.props.style,
      backgroundColor: 'var(--el-color-danger-light-3)',
      height: `${rowSpan * 50}px`,
      alignSelf: 'flex-start',
      zIndex: 1,
    }
    cells[rowSpanIndex] = cloneVNode(cell, { style })
  } else {
    const style = cells[rowSpanIndex].props.style
    // override the cell here for creating a pure node without pollute the style
    cells[rowSpanIndex] = (
      <div style={{ ...style, width: `${style.width}px` }} />
    )
  }
  return cells
}
</script>
```

隐藏源代码

## 树形数据 [​](#树形数据)

虚拟表也可以在树状结构中呈现数据。 点击箭头图标，你可以展开或折叠树节点。

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Row 0 - Col 0

Row 0 - Col 1

Row 1 - Col 0

Row 1 - Col 1

Row 2 - Col 0

Row 2 - Col 1

Row 3 - Col 0

Row 3 - Col 1

Row 4 - Col 0

Row 4 - Col 1

Row 5 - Col 0

Row 5 - Col 1

Row 6 - Col 0

Row 6 - Col 1

Row 7 - Col 0

Row 7 - Col 1

Row 8 - Col 0

Row 8 - Col 1

Column 0

Column 1

Row 0 - Col 9

Row 1 - Col 9

Row 2 - Col 9

Row 3 - Col 9

Row 4 - Col 9

Row 5 - Col 9

Row 6 - Col 9

Row 7 - Col 9

Row 8 - Col 9

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICB2LW1vZGVsOmV4cGFuZGVkLXJvdy1rZXlzPVwiZXhwYW5kZWRSb3dLZXlzXCJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwidHJlZURhdGFcIlxuICAgIDp3aWR0aD1cIjcwMFwiXG4gICAgOmV4cGFuZC1jb2x1bW4ta2V5PVwiZXhwYW5kQ29sdW1uS2V5XCJcbiAgICA6aGVpZ2h0PVwiNDAwXCJcbiAgICBmaXhlZFxuICAgIEByb3ctZXhwYW5kPVwib25Sb3dFeHBhbmRlZFwiXG4gICAgQGV4cGFuZGVkLXJvd3MtY2hhbmdlPVwib25FeHBhbmRlZFJvd3NDaGFuZ2VcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IGNvbXB1dGVkLCByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBUYWJsZVYyRml4ZWREaXIgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmltcG9ydCB0eXBlIHsgRXhwYW5kZWRSb3dzQ2hhbmdlSGFuZGxlciwgUm93RXhwYW5kSGFuZGxlciB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgZ2VuZXJhdGVDb2x1bW5zID0gKGxlbmd0aCA9IDEwLCBwcmVmaXggPSAnY29sdW1uLScsIHByb3BzPzogYW55KSA9PlxuICBBcnJheS5mcm9tKHsgbGVuZ3RoIH0pLm1hcCgoXywgY29sdW1uSW5kZXgpID0+ICh7XG4gICAgLi4ucHJvcHMsXG4gICAga2V5OiBgJHtwcmVmaXh9JHtjb2x1bW5JbmRleH1gLFxuICAgIGRhdGFLZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgdGl0bGU6IGBDb2x1bW4gJHtjb2x1bW5JbmRleH1gLFxuICAgIHdpZHRoOiAxNTAsXG4gIH0pKVxuXG5jb25zdCBnZW5lcmF0ZURhdGEgPSAoXG4gIGNvbHVtbnM6IFJldHVyblR5cGU8dHlwZW9mIGdlbmVyYXRlQ29sdW1ucz4sXG4gIGxlbmd0aCA9IDIwMCxcbiAgcHJlZml4ID0gJ3Jvdy0nXG4pID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCByb3dJbmRleCkgPT4ge1xuICAgIHJldHVybiBjb2x1bW5zLnJlZHVjZShcbiAgICAgIChyb3dEYXRhLCBjb2x1bW4sIGNvbHVtbkluZGV4KSA9PiB7XG4gICAgICAgIHJvd0RhdGFbY29sdW1uLmRhdGFLZXldID0gYFJvdyAke3Jvd0luZGV4fSAtIENvbCAke2NvbHVtbkluZGV4fWBcbiAgICAgICAgcmV0dXJuIHJvd0RhdGFcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIGlkOiBgJHtwcmVmaXh9JHtyb3dJbmRleH1gLFxuICAgICAgICBwYXJlbnRJZDogbnVsbCxcbiAgICAgIH1cbiAgICApXG4gIH0pXG5cbmNvbnN0IGNvbHVtbnMgPSBnZW5lcmF0ZUNvbHVtbnMoMTApLm1hcCgoY29sdW1uLCBjb2x1bW5JbmRleCkgPT4ge1xuICBsZXQgZml4ZWQhOiBUYWJsZVYyRml4ZWREaXJcbiAgaWYgKGNvbHVtbkluZGV4IDwgMikgZml4ZWQgPSBUYWJsZVYyRml4ZWREaXIuTEVGVFxuICBpZiAoY29sdW1uSW5kZXggPiA4KSBmaXhlZCA9IFRhYmxlVjJGaXhlZERpci5SSUdIVFxuICByZXR1cm4geyAuLi5jb2x1bW4sIGZpeGVkIH1cbn0pXG5cbmNvbnN0IGRhdGEgPSBnZW5lcmF0ZURhdGEoY29sdW1ucywgMjAwKVxuXG5jb25zdCBleHBhbmRDb2x1bW5LZXkgPSAnY29sdW1uLTAnXG5cbi8vIGFkZCBzb21lIHN1YiBpdGVtc1xuZm9yIChsZXQgaSA9IDA7IGkgPCA1MDsgaSsrKSB7XG4gIGRhdGEucHVzaChcbiAgICB7XG4gICAgICAuLi5kYXRhWzBdLFxuICAgICAgaWQ6IGAke2RhdGFbMF0uaWR9LXN1Yi0ke2l9YCxcbiAgICAgIHBhcmVudElkOiBkYXRhWzBdLmlkLFxuICAgICAgW2V4cGFuZENvbHVtbktleV06IGBTdWIgJHtpfWAsXG4gICAgfSxcbiAgICB7XG4gICAgICAuLi5kYXRhWzJdLFxuICAgICAgaWQ6IGAke2RhdGFbMl0uaWR9LXN1Yi0ke2l9YCxcbiAgICAgIHBhcmVudElkOiBkYXRhWzJdLmlkLFxuICAgICAgW2V4cGFuZENvbHVtbktleV06IGBTdWIgJHtpfWAsXG4gICAgfSxcbiAgICB7XG4gICAgICAuLi5kYXRhWzJdLFxuICAgICAgaWQ6IGAke2RhdGFbMl0uaWR9LXN1Yi1zdWItJHtpfWAsXG4gICAgICBwYXJlbnRJZDogYCR7ZGF0YVsyXS5pZH0tc3ViLSR7aX1gLFxuICAgICAgW2V4cGFuZENvbHVtbktleV06IGBTdWItU3ViICR7aX1gLFxuICAgIH1cbiAgKVxufVxuXG5mdW5jdGlvbiB1bmZsYXR0ZW4oXG4gIGRhdGE6IFJldHVyblR5cGU8dHlwZW9mIGdlbmVyYXRlRGF0YT4sXG4gIHJvb3RJZCA9IG51bGwsXG4gIGRhdGFLZXkgPSAnaWQnLFxuICBwYXJlbnRLZXkgPSAncGFyZW50SWQnXG4pIHtcbiAgY29uc3QgdHJlZTogYW55W10gPSBbXVxuICBjb25zdCBjaGlsZHJlbk1hcCA9IHt9XG5cbiAgZm9yIChjb25zdCBkYXR1bSBvZiBkYXRhKSB7XG4gICAgY29uc3QgaXRlbSA9IHsgLi4uZGF0dW0gfVxuICAgIGNvbnN0IGlkID0gaXRlbVtkYXRhS2V5XVxuICAgIGNvbnN0IHBhcmVudElkID0gaXRlbVtwYXJlbnRLZXldXG5cbiAgICBpZiAoQXJyYXkuaXNBcnJheShpdGVtLmNoaWxkcmVuKSkge1xuICAgICAgY2hpbGRyZW5NYXBbaWRdID0gaXRlbS5jaGlsZHJlbi5jb25jYXQoY2hpbGRyZW5NYXBbaWRdIHx8IFtdKVxuICAgIH0gZWxzZSBpZiAoIWNoaWxkcmVuTWFwW2lkXSkge1xuICAgICAgY2hpbGRyZW5NYXBbaWRdID0gW11cbiAgICB9XG4gICAgaXRlbS5jaGlsZHJlbiA9IGNoaWxkcmVuTWFwW2lkXVxuXG4gICAgaWYgKHBhcmVudElkICE9PSB1bmRlZmluZWQgJiYgcGFyZW50SWQgIT09IHJvb3RJZCkge1xuICAgICAgaWYgKCFjaGlsZHJlbk1hcFtwYXJlbnRJZF0pIGNoaWxkcmVuTWFwW3BhcmVudElkXSA9IFtdXG4gICAgICBjaGlsZHJlbk1hcFtwYXJlbnRJZF0ucHVzaChpdGVtKVxuICAgIH0gZWxzZSB7XG4gICAgICB0cmVlLnB1c2goaXRlbSlcbiAgICB9XG4gIH1cblxuICByZXR1cm4gdHJlZVxufVxuXG5jb25zdCB0cmVlRGF0YSA9IGNvbXB1dGVkKCgpID0+IHVuZmxhdHRlbihkYXRhKSlcblxuY29uc3QgZXhwYW5kZWRSb3dLZXlzID0gcmVmPHN0cmluZ1tdPihbXSlcblxuY29uc3Qgb25Sb3dFeHBhbmRlZCA9ICh7IGV4cGFuZGVkIH06IFBhcmFtZXRlcnM8Um93RXhwYW5kSGFuZGxlcj5bMF0pID0+IHtcbiAgY29uc29sZS5sb2coJ0V4cGFuZGVkOicsIGV4cGFuZGVkKVxufVxuXG5jb25zdCBvbkV4cGFuZGVkUm93c0NoYW5nZSA9IChcbiAgZXhwYW5kZWRLZXlzOiBQYXJhbWV0ZXJzPEV4cGFuZGVkUm93c0NoYW5nZUhhbmRsZXI+WzBdXG4pID0+IHtcbiAgY29uc29sZS5sb2coZXhwYW5kZWRLZXlzKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/tree-data.vue)_

vue

```
<template>
  <el-table-v2
    v-model:expanded-row-keys="expandedRowKeys"
    :columns="columns"
    :data="treeData"
    :width="700"
    :expand-column-key="expandColumnKey"
    :height="400"
    fixed
    @row-expand="onRowExpanded"
    @expanded-rows-change="onExpandedRowsChange"
  />
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'
import { TableV2FixedDir } from 'element-plus'

import type { ExpandedRowsChangeHandler, RowExpandHandler } from 'element-plus'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10).map((column, columnIndex) => {
  let fixed!: TableV2FixedDir
  if (columnIndex < 2) fixed = TableV2FixedDir.LEFT
  if (columnIndex > 8) fixed = TableV2FixedDir.RIGHT
  return { ...column, fixed }
})

const data = generateData(columns, 200)

const expandColumnKey = 'column-0'

// add some sub items
for (let i = 0; i < 50; i++) {
  data.push(
    {
      ...data[0],
      id: `${data[0].id}-sub-${i}`,
      parentId: data[0].id,
      [expandColumnKey]: `Sub ${i}`,
    },
    {
      ...data[2],
      id: `${data[2].id}-sub-${i}`,
      parentId: data[2].id,
      [expandColumnKey]: `Sub ${i}`,
    },
    {
      ...data[2],
      id: `${data[2].id}-sub-sub-${i}`,
      parentId: `${data[2].id}-sub-${i}`,
      [expandColumnKey]: `Sub-Sub ${i}`,
    }
  )
}

function unflatten(
  data: ReturnType<typeof generateData>,
  rootId = null,
  dataKey = 'id',
  parentKey = 'parentId'
) {
  const tree: any[] = []
  const childrenMap = {}

  for (const datum of data) {
    const item = { ...datum }
    const id = item[dataKey]
    const parentId = item[parentKey]

    if (Array.isArray(item.children)) {
      childrenMap[id] = item.children.concat(childrenMap[id] || [])
    } else if (!childrenMap[id]) {
      childrenMap[id] = []
    }
    item.children = childrenMap[id]

    if (parentId !== undefined && parentId !== rootId) {
      if (!childrenMap[parentId]) childrenMap[parentId] = []
      childrenMap[parentId].push(item)
    } else {
      tree.push(item)
    }
  }

  return tree
}

const treeData = computed(() => unflatten(data))

const expandedRowKeys = ref<string[]>([])

const onRowExpanded = ({ expanded }: Parameters<RowExpandHandler>[0]) => {
  console.log('Expanded:', expanded)
}

const onExpandedRowsChange = (
  expandedKeys: Parameters<ExpandedRowsChangeHandler>[0]
) => {
  console.log(expandedKeys)
}
</script>
```

隐藏源代码

## 动态高度行 [​](#动态高度行)

虚拟表能够呈现具有动态高度的行数。 如果您正在处理数据并不确定内容大小， 此功能对于调整到内容高度的渲染行是理想的。 要启用此功能，请传递 `estimated-row-height` 属性。 估计高度越接近实际内容，渲染体验就越顺。

TIP

每行高度在渲染过程中动态测量。 因此，如果您试图显示大量数据， UI **可能会** 抖动。

Tom

Eius optio fugiat.

EditDelete

Tom

Corrupti doloremque a quos vero delectus consequatur.

EditDelete

Tom

Eius optio fugiat.

EditDelete

Name

Description

Operations

random-200

random-199

random-198

random-197

random-196

random-195

random-194

random-193

random-192

random-191

random-190

Id

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgOnNvcnQtYnk9XCJzb3J0XCJcbiAgICA6ZXN0aW1hdGVkLXJvdy1oZWlnaHQ9XCI0MFwiXG4gICAgOndpZHRoPVwiNzAwXCJcbiAgICA6aGVpZ2h0PVwiNDAwXCJcbiAgICBmaXhlZFxuICAgIEBjb2x1bW4tc29ydD1cIm9uQ29sdW1uU29ydFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c3hcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7XG4gIEVsQnV0dG9uLFxuICBFbFRhZyxcbiAgVGFibGVWMkZpeGVkRGlyLFxuICBUYWJsZVYyU29ydE9yZGVyLFxufSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmltcG9ydCB0eXBlIHsgQ29sdW1uLCBTb3J0QnkgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGxvbmdUZXh0ID1cbiAgJ1F1YWVyYXQgaXBzYW0gbmVjZXNzaXRhdGlidXMgZXVtIHF1aWJ1c2RhbSBlc3QgaWQgdm9sdXB0YXRlbSBjdW1xdWUgbW9sbGl0aWEuJ1xuY29uc3QgbWlkVGV4dCA9ICdDb3JydXB0aSBkb2xvcmVtcXVlIGEgcXVvcyB2ZXJvIGRlbGVjdHVzIGNvbnNlcXVhdHVyLidcbmNvbnN0IHNob3J0VGV4dCA9ICdFaXVzIG9wdGlvIGZ1Z2lhdC4nXG5cbmNvbnN0IHRleHRMaXN0ID0gW3Nob3J0VGV4dCwgbWlkVGV4dCwgbG9uZ1RleHRdXG5cbi8vIGdlbmVyYXRlIHJhbmRvbSBudW1iZXIgaW4gcmFuZ2UgMCB0byAyXG5cbmxldCBpZCA9IDBcblxuY29uc3QgZGF0YUdlbmVyYXRvciA9ICgpID0+ICh7XG4gIGlkOiBgcmFuZG9tLSR7KytpZH1gLFxuICBuYW1lOiAnVG9tJyxcbiAgZGF0ZTogJzIwMTYtMDUtMDMnLFxuICBkZXNjcmlwdGlvbjogdGV4dExpc3RbTWF0aC5mbG9vcihNYXRoLnJhbmRvbSgpICogMyldLFxufSlcblxuY29uc3QgY29sdW1uczogQ29sdW1uPGFueT5bXSA9IFtcbiAge1xuICAgIGtleTogJ2lkJyxcbiAgICB0aXRsZTogJ0lkJyxcbiAgICBkYXRhS2V5OiAnaWQnLFxuICAgIHdpZHRoOiAxNTAsXG4gICAgc29ydGFibGU6IHRydWUsXG4gICAgZml4ZWQ6IFRhYmxlVjJGaXhlZERpci5MRUZULFxuICB9LFxuICB7XG4gICAga2V5OiAnbmFtZScsXG4gICAgdGl0bGU6ICdOYW1lJyxcbiAgICBkYXRhS2V5OiAnbmFtZScsXG4gICAgd2lkdGg6IDE1MCxcbiAgICBhbGlnbjogJ2NlbnRlcicsXG4gICAgY2VsbFJlbmRlcmVyOiAoeyBjZWxsRGF0YTogbmFtZSB9KSA9PiA8RWxUYWc+e25hbWV9PC9FbFRhZz4sXG4gIH0sXG4gIHtcbiAgICBrZXk6ICdkZXNjcmlwdGlvbicsXG4gICAgdGl0bGU6ICdEZXNjcmlwdGlvbicsXG4gICAgZGF0YUtleTogJ2Rlc2NyaXB0aW9uJyxcbiAgICB3aWR0aDogMTUwLFxuICAgIGNlbGxSZW5kZXJlcjogKHsgY2VsbERhdGE6IGRlc2NyaXB0aW9uIH0pID0+IChcbiAgICAgIDxkaXYgc3R5bGU9XCJwYWRkaW5nOiAxMHB4IDA7XCI+e2Rlc2NyaXB0aW9ufTwvZGl2PlxuICAgICksXG4gIH0sXG4gIHtcbiAgICBrZXk6ICdvcGVyYXRpb25zJyxcbiAgICB0aXRsZTogJ09wZXJhdGlvbnMnLFxuICAgIGNlbGxSZW5kZXJlcjogKCkgPT4gKFxuICAgICAgPD5cbiAgICAgICAgPEVsQnV0dG9uIHNpemU9XCJzbWFsbFwiPkVkaXQ8L0VsQnV0dG9uPlxuICAgICAgICA8RWxCdXR0b24gc2l6ZT1cInNtYWxsXCIgdHlwZT1cImRhbmdlclwiPlxuICAgICAgICAgIERlbGV0ZVxuICAgICAgICA8L0VsQnV0dG9uPlxuICAgICAgPC8+XG4gICAgKSxcbiAgICB3aWR0aDogMTUwLFxuICAgIGFsaWduOiAnY2VudGVyJyxcbiAgfSxcbl1cbmNvbnN0IGRhdGEgPSByZWYoXG4gIEFycmF5LmZyb20oeyBsZW5ndGg6IDIwMCB9KVxuICAgIC5tYXAoZGF0YUdlbmVyYXRvcilcbiAgICAuc29ydCgoYSwgYikgPT4gKGEubmFtZSA+IGIubmFtZSA/IDEgOiAtMSkpXG4pXG5cbmNvbnN0IHNvcnQgPSByZWY8U29ydEJ5Pih7IGtleTogJ25hbWUnLCBvcmRlcjogVGFibGVWMlNvcnRPcmRlci5BU0MgfSlcblxuY29uc3Qgb25Db2x1bW5Tb3J0ID0gKHNvcnRCeTogU29ydEJ5KSA9PiB7XG4gIGNvbnN0IG9yZGVyID0gc29ydEJ5Lm9yZGVyID09PSAnYXNjJyA/IDEgOiAtMVxuICBjb25zdCBkYXRhQ2xvbmUgPSBbLi4uZGF0YS52YWx1ZV1cbiAgZGF0YUNsb25lLnNvcnQoKGEsIGIpID0+IChhW3NvcnRCeS5rZXldID4gYltzb3J0Qnkua2V5XSA/IG9yZGVyIDogLW9yZGVyKSlcbiAgc29ydC52YWx1ZSA9IHNvcnRCeVxuICBkYXRhLnZhbHVlID0gZGF0YUNsb25lXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/dynamic-height.vue)_

vue

```
<template>
  <el-table-v2
    :columns="columns"
    :data="data"
    :sort-by="sort"
    :estimated-row-height="40"
    :width="700"
    :height="400"
    fixed
    @column-sort="onColumnSort"
  />
</template>

<script lang="tsx" setup>
import { ref } from 'vue'
import {
  ElButton,
  ElTag,
  TableV2FixedDir,
  TableV2SortOrder,
} from 'element-plus'

import type { Column, SortBy } from 'element-plus'

const longText =
  'Quaerat ipsam necessitatibus eum quibusdam est id voluptatem cumque mollitia.'
const midText = 'Corrupti doloremque a quos vero delectus consequatur.'
const shortText = 'Eius optio fugiat.'

const textList = [shortText, midText, longText]

// generate random number in range 0 to 2

let id = 0

const dataGenerator = () => ({
  id: `random-${++id}`,
  name: 'Tom',
  date: '2016-05-03',
  description: textList[Math.floor(Math.random() * 3)],
})

const columns: Column<any>[] = [
  {
    key: 'id',
    title: 'Id',
    dataKey: 'id',
    width: 150,
    sortable: true,
    fixed: TableV2FixedDir.LEFT,
  },
  {
    key: 'name',
    title: 'Name',
    dataKey: 'name',
    width: 150,
    align: 'center',
    cellRenderer: ({ cellData: name }) => <ElTag>{name}</ElTag>,
  },
  {
    key: 'description',
    title: 'Description',
    dataKey: 'description',
    width: 150,
    cellRenderer: ({ cellData: description }) => (
      <div style="padding: 10px 0;">{description}</div>
    ),
  },
  {
    key: 'operations',
    title: 'Operations',
    cellRenderer: () => (
      <>
        <ElButton size="small">Edit</ElButton>
        <ElButton size="small" type="danger">
          Delete
        </ElButton>
      </>
    ),
    width: 150,
    align: 'center',
  },
]
const data = ref(
  Array.from({ length: 200 })
    .map(dataGenerator)
    .sort((a, b) => (a.name > b.name ? 1 : -1))
)

const sort = ref<SortBy>({ key: 'name', order: TableV2SortOrder.ASC })

const onColumnSort = (sortBy: SortBy) => {
  const order = sortBy.order === 'asc' ? 1 : -1
  const dataClone = [...data.value]
  dataClone.sort((a, b) => (a[sortBy.key] > b[sortBy.key] ? order : -order))
  sort.value = sortBy
  data.value = dataClone
}
</script>
```

隐藏源代码

## 可展开的附加信息 [​](#可展开的附加信息)

使用动态高度渲染，您也可以在表格中显示详细的视图。

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgOmVzdGltYXRlZC1yb3ctaGVpZ2h0PVwiNTBcIlxuICAgIDpleHBhbmQtY29sdW1uLWtleT1cImNvbHVtbnNbMF0ua2V5XCJcbiAgICA6d2lkdGg9XCI3MDBcIlxuICAgIDpoZWlnaHQ9XCI0MDBcIlxuICA+XG4gICAgPHRlbXBsYXRlICNyb3c9XCJwcm9wc1wiPlxuICAgICAgPFJvdyB2LWJpbmQ9XCJwcm9wc1wiIC8+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC10YWJsZS12Mj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzeFwiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBkZXRhaWxlZFRleHQgPSBgVmVsaXQgc2VkIGFzcGVybmF0dXIgdGVtcG9yYS4gTmF0dXMgY29uc2VxdWF0dXIgb2ZmaWNpaXMgZGljdGEgdmVsIGFzc3VtZW5kYS5cbkl0YXF1ZSBlc3QgdGVtcG9yaWJ1cyBtaW51cyBxdWlzLiBJcHN1bSBjb21tb2RpYWIgcG9ycm8gdmVsIHZvbHVwdGFzIGlsbHVtLlxuUXVpIHF1YW0gbnVsbGEgZXQgZG9sb3JlIGF1dGVtIGl0YXF1ZSBlc3QuXG5JZCBjb25zZXF1YXR1ciBpcHN1bSBlYSBmdWdhIGV0IG9kaXQgZWxpZ2VuZGkgaW1wZWRpdC5cbk1haW9yZXMgb2ZmaWNpaXMgb2NjYWVjYXRpIGV0IG1hZ25hbSBldCBzYXBpZW50ZSBlc3QgdmVsaXQgc3VudC5cbk5vbiBldCB0ZW1wb3JlIHRlbXBvcmlidXMuIEV4Y2VwdHVyaSBldCBxdW9zLiBNaW51cyBkaXN0aW5jdGlvIGF1dC5cblZvbHVwdGF0ZW0gZWEgZXhjZXB0dXJpIG9tbmlzIHZlbC4gTm9uIGFwZXJpYW0gc2l0IHNlZCBsYWJvcmlvc2FtIGVhcXVlIG9tbmlzIGRlbGVuaXRpLlxuRXN0IG1vbGVzdGlhZSBvbW5pcyBub24gZXQgbnVsbGEgcmVwdWRpYW5kYWUgZnVnYSBzaXQuYFxuXG5jb25zdCBnZW5lcmF0ZUNvbHVtbnMgPSAobGVuZ3RoID0gMTAsIHByZWZpeCA9ICdjb2x1bW4tJywgcHJvcHM/OiBhbnkpID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCBjb2x1bW5JbmRleCkgPT4gKHtcbiAgICAuLi5wcm9wcyxcbiAgICBrZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgZGF0YUtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICB0aXRsZTogYENvbHVtbiAke2NvbHVtbkluZGV4fWAsXG4gICAgd2lkdGg6IDE1MCxcbiAgfSkpXG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9IChcbiAgY29sdW1uczogUmV0dXJuVHlwZTx0eXBlb2YgZ2VuZXJhdGVDb2x1bW5zPixcbiAgbGVuZ3RoID0gMjAwLFxuICBwcmVmaXggPSAncm93LSdcbikgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIHJvd0luZGV4KSA9PiB7XG4gICAgcmV0dXJuIGNvbHVtbnMucmVkdWNlKFxuICAgICAgKHJvd0RhdGEsIGNvbHVtbiwgY29sdW1uSW5kZXgpID0+IHtcbiAgICAgICAgcm93RGF0YVtjb2x1bW4uZGF0YUtleV0gPSBgUm93ICR7cm93SW5kZXh9IC0gQ29sICR7Y29sdW1uSW5kZXh9YFxuICAgICAgICByZXR1cm4gcm93RGF0YVxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IGAke3ByZWZpeH0ke3Jvd0luZGV4fWAsXG4gICAgICAgIHBhcmVudElkOiBudWxsLFxuICAgICAgfVxuICAgIClcbiAgfSlcblxuY29uc3QgY29sdW1ucyA9IGdlbmVyYXRlQ29sdW1ucygxMClcbmNvbnN0IGRhdGEgPSByZWYoXG4gIGdlbmVyYXRlRGF0YShjb2x1bW5zLCAyMDApLm1hcCgoZGF0YSkgPT4ge1xuICAgIGRhdGEuY2hpbGRyZW4gPSBbXG4gICAgICB7XG4gICAgICAgIGlkOiBgJHtkYXRhLmlkfS1kZXRhaWwtY29udGVudGAsXG4gICAgICAgIGRldGFpbDogZGV0YWlsZWRUZXh0LFxuICAgICAgfSxcbiAgICBdXG4gICAgcmV0dXJuIGRhdGFcbiAgfSlcbilcblxuY29uc3QgUm93ID0gKHsgY2VsbHMsIHJvd0RhdGEgfSkgPT4ge1xuICBpZiAocm93RGF0YS5kZXRhaWwpIHJldHVybiA8ZGl2IGNsYXNzPVwicC02XCI+e3Jvd0RhdGEuZGV0YWlsfTwvZGl2PlxuICByZXR1cm4gY2VsbHNcbn1cblxuUm93LmluaGVyaXRBdHRycyA9IGZhbHNlXG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLmVsLXRhYmxlLXYyX19yb3ctZGVwdGgtMCB7XG4gIGhlaWdodDogNTBweDtcbn1cblxuLmVsLXRhYmxlLXYyX19jZWxsLXRleHQge1xuICBvdmVyZmxvdzogaGlkZGVuO1xuICB0ZXh0LW92ZXJmbG93OiBlbGxpcHNpcztcbiAgd2hpdGUtc3BhY2U6IG5vd3JhcDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/detailed-view.vue)_

vue

```
<template>
  <el-table-v2
    :columns="columns"
    :data="data"
    :estimated-row-height="50"
    :expand-column-key="columns[0].key"
    :width="700"
    :height="400"
  >
    <template #row="props">
      <Row v-bind="props" />
    </template>
  </el-table-v2>
</template>

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

const detailedText = `Velit sed aspernatur tempora. Natus consequatur officiis dicta vel assumenda.
Itaque est temporibus minus quis. Ipsum commodiab porro vel voluptas illum.
Qui quam nulla et dolore autem itaque est.
Id consequatur ipsum ea fuga et odit eligendi impedit.
Maiores officiis occaecati et magnam et sapiente est velit sunt.
Non et tempore temporibus. Excepturi et quos. Minus distinctio aut.
Voluptatem ea excepturi omnis vel. Non aperiam sit sed laboriosam eaque omnis deleniti.
Est molestiae omnis non et nulla repudiandae fuga sit.`

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
const data = ref(
  generateData(columns, 200).map((data) => {
    data.children = [
      {
        id: `${data.id}-detail-content`,
        detail: detailedText,
      },
    ]
    return data
  })
)

const Row = ({ cells, rowData }) => {
  if (rowData.detail) return <div class="p-6">{rowData.detail}</div>
  return cells
}

Row.inheritAttrs = false
</script>

<style>
.el-table-v2__row-depth-0 {
  height: 50px;
}

.el-table-v2__cell-text {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}
</style>
```

隐藏源代码

## 自定义页脚 [​](#自定义页脚)

自定义表格 footer， 通常用来展示一些汇总数据和信息。

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Row 9 - Col 0

Row 9 - Col 1

Row 9 - Col 2

Row 9 - Col 3

Row 9 - Col 4

Row 9 - Col 5

Row 9 - Col 6

Row 9 - Col 7

Row 9 - Col 8

Row 9 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

Display a message in the footer

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgOnJvdy1oZWlnaHQ9XCI0MFwiXG4gICAgOndpZHRoPVwiNzAwXCJcbiAgICA6aGVpZ2h0PVwiNDAwXCJcbiAgICA6Zm9vdGVyLWhlaWdodD1cIjUwXCJcbiAgICBmaXhlZFxuICA+XG4gICAgPHRlbXBsYXRlICNmb290ZXJcbiAgICAgID48ZGl2XG4gICAgICAgIGNsYXNzPVwiZmxleCBpdGVtcy1jZW50ZXJcIlxuICAgICAgICBzdHlsZT1cIlxuICAgICAgICAgIGp1c3RpZnktY29udGVudDogY2VudGVyO1xuICAgICAgICAgIGhlaWdodDogMTAwJTtcbiAgICAgICAgICBiYWNrZ3JvdW5kLWNvbG9yOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5LWxpZ2h0LTcpO1xuICAgICAgICBcIlxuICAgICAgPlxuICAgICAgICBEaXNwbGF5IGEgbWVzc2FnZSBpbiB0aGUgZm9vdGVyXG4gICAgICA8L2Rpdj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLXRhYmxlLXYyPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IGdlbmVyYXRlQ29sdW1ucyA9IChsZW5ndGggPSAxMCwgcHJlZml4ID0gJ2NvbHVtbi0nLCBwcm9wcz86IGFueSkgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIGNvbHVtbkluZGV4KSA9PiAoe1xuICAgIC4uLnByb3BzLFxuICAgIGtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICBkYXRhS2V5OiBgJHtwcmVmaXh9JHtjb2x1bW5JbmRleH1gLFxuICAgIHRpdGxlOiBgQ29sdW1uICR7Y29sdW1uSW5kZXh9YCxcbiAgICB3aWR0aDogMTUwLFxuICB9KSlcblxuY29uc3QgZ2VuZXJhdGVEYXRhID0gKFxuICBjb2x1bW5zOiBSZXR1cm5UeXBlPHR5cGVvZiBnZW5lcmF0ZUNvbHVtbnM+LFxuICBsZW5ndGggPSAyMDAsXG4gIHByZWZpeCA9ICdyb3ctJ1xuKSA9PlxuICBBcnJheS5mcm9tKHsgbGVuZ3RoIH0pLm1hcCgoXywgcm93SW5kZXgpID0+IHtcbiAgICByZXR1cm4gY29sdW1ucy5yZWR1Y2UoXG4gICAgICAocm93RGF0YSwgY29sdW1uLCBjb2x1bW5JbmRleCkgPT4ge1xuICAgICAgICByb3dEYXRhW2NvbHVtbi5kYXRhS2V5XSA9IGBSb3cgJHtyb3dJbmRleH0gLSBDb2wgJHtjb2x1bW5JbmRleH1gXG4gICAgICAgIHJldHVybiByb3dEYXRhXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogYCR7cHJlZml4fSR7cm93SW5kZXh9YCxcbiAgICAgICAgcGFyZW50SWQ6IG51bGwsXG4gICAgICB9XG4gICAgKVxuICB9KVxuXG5jb25zdCBjb2x1bW5zID0gZ2VuZXJhdGVDb2x1bW5zKDEwKVxuY29uc3QgZGF0YSA9IGdlbmVyYXRlRGF0YShjb2x1bW5zLCAyMDApXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/footer.vue)_

vue

```
<template>
  <el-table-v2
    :columns="columns"
    :data="data"
    :row-height="40"
    :width="700"
    :height="400"
    :footer-height="50"
    fixed
  >
    <template #footer
      ><div
        class="flex items-center"
        style="
          justify-content: center;
          height: 100%;
          background-color: var(--el-color-primary-light-7);
        "
      >
        Display a message in the footer
      </div>
    </template>
  </el-table-v2>
</template>

<script lang="ts" setup>
const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
const data = generateData(columns, 200)
</script>
```

隐藏源代码

## 自定义空元素渲染器 [​](#自定义空元素渲染器)

渲染自定义的空元素。

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

No Data

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwiW11cIlxuICAgIDpyb3ctaGVpZ2h0PVwiNDBcIlxuICAgIDp3aWR0aD1cIjcwMFwiXG4gICAgOmhlaWdodD1cIjQwMFwiXG4gICAgOmZvb3Rlci1oZWlnaHQ9XCI1MFwiXG4gID5cbiAgICA8dGVtcGxhdGUgI2VtcHR5PlxuICAgICAgPGRpdiBjbGFzcz1cImZsZXggaXRlbXMtY2VudGVyIGp1c3RpZnktY2VudGVyIGgtMTAwJVwiPlxuICAgICAgICA8ZWwtZW1wdHkgLz5cbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtdGFibGUtdjI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c3hcIiBzZXR1cD5cbmNvbnN0IGdlbmVyYXRlQ29sdW1ucyA9IChsZW5ndGggPSAxMCwgcHJlZml4ID0gJ2NvbHVtbi0nLCBwcm9wcz86IGFueSkgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIGNvbHVtbkluZGV4KSA9PiAoe1xuICAgIC4uLnByb3BzLFxuICAgIGtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICBkYXRhS2V5OiBgJHtwcmVmaXh9JHtjb2x1bW5JbmRleH1gLFxuICAgIHRpdGxlOiBgQ29sdW1uICR7Y29sdW1uSW5kZXh9YCxcbiAgICB3aWR0aDogMTUwLFxuICB9KSlcblxuY29uc3QgY29sdW1ucyA9IGdlbmVyYXRlQ29sdW1ucygxMClcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/empty.vue)_

vue

```
<template>
  <el-table-v2
    :columns="columns"
    :data="[]"
    :row-height="40"
    :width="700"
    :height="400"
    :footer-height="50"
  >
    <template #empty>
      <div class="flex items-center justify-center h-100%">
        <el-empty />
      </div>
    </template>
  </el-table-v2>
</template>

<script lang="tsx" setup>
const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const columns = generateColumns(10)
</script>
```

隐藏源代码

## 浮动遮罩层 [​](#浮动遮罩层)

当您想要显示加载指示器之类的浮动元素，可以通过渲染一个浮动在表格之上的遮罩层来实现。

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Row 9 - Col 0

Row 9 - Col 1

Row 9 - Col 2

Row 9 - Col 3

Row 9 - Col 4

Row 9 - Col 5

Row 9 - Col 6

Row 9 - Col 7

Row 9 - Col 8

Row 9 - Col 9

Row 10 - Col 0

Row 10 - Col 1

Row 10 - Col 2

Row 10 - Col 3

Row 10 - Col 4

Row 10 - Col 5

Row 10 - Col 6

Row 10 - Col 7

Row 10 - Col 8

Row 10 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUtdjJcbiAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgOnJvdy1oZWlnaHQ9XCI0MFwiXG4gICAgOndpZHRoPVwiNzAwXCJcbiAgICA6aGVpZ2h0PVwiNDAwXCJcbiAgPlxuICAgIDx0ZW1wbGF0ZSAjb3ZlcmxheT5cbiAgICAgIDxkaXZcbiAgICAgICAgY2xhc3M9XCJlbC1sb2FkaW5nLW1hc2tcIlxuICAgICAgICBzdHlsZT1cImRpc3BsYXk6IGZsZXg7IGFsaWduLWl0ZW1zOiBjZW50ZXI7IGp1c3RpZnktY29udGVudDogY2VudGVyXCJcbiAgICAgID5cbiAgICAgICAgPGVsLWljb24gY2xhc3M9XCJpcy1sb2FkaW5nXCIgY29sb3I9XCJ2YXIoLS1lbC1jb2xvci1wcmltYXJ5KVwiIDpzaXplPVwiMjZcIj5cbiAgICAgICAgICA8bG9hZGluZy1pY29uIC8+XG4gICAgICAgIDwvZWwtaWNvbj5cbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtdGFibGUtdjI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgTG9hZGluZyBhcyBMb2FkaW5nSWNvbiB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5jb25zdCBnZW5lcmF0ZUNvbHVtbnMgPSAobGVuZ3RoID0gMTAsIHByZWZpeCA9ICdjb2x1bW4tJywgcHJvcHM/OiBhbnkpID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCBjb2x1bW5JbmRleCkgPT4gKHtcbiAgICAuLi5wcm9wcyxcbiAgICBrZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgZGF0YUtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICB0aXRsZTogYENvbHVtbiAke2NvbHVtbkluZGV4fWAsXG4gICAgd2lkdGg6IDE1MCxcbiAgfSkpXG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9IChcbiAgY29sdW1uczogUmV0dXJuVHlwZTx0eXBlb2YgZ2VuZXJhdGVDb2x1bW5zPixcbiAgbGVuZ3RoID0gMjAwLFxuICBwcmVmaXggPSAncm93LSdcbikgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIHJvd0luZGV4KSA9PiB7XG4gICAgcmV0dXJuIGNvbHVtbnMucmVkdWNlKFxuICAgICAgKHJvd0RhdGEsIGNvbHVtbiwgY29sdW1uSW5kZXgpID0+IHtcbiAgICAgICAgcm93RGF0YVtjb2x1bW4uZGF0YUtleV0gPSBgUm93ICR7cm93SW5kZXh9IC0gQ29sICR7Y29sdW1uSW5kZXh9YFxuICAgICAgICByZXR1cm4gcm93RGF0YVxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IGAke3ByZWZpeH0ke3Jvd0luZGV4fWAsXG4gICAgICAgIHBhcmVudElkOiBudWxsLFxuICAgICAgfVxuICAgIClcbiAgfSlcblxuY29uc3QgY29sdW1ucyA9IGdlbmVyYXRlQ29sdW1ucygxMClcbmNvbnN0IGRhdGEgPSBnZW5lcmF0ZURhdGEoY29sdW1ucywgMjAwKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5leGFtcGxlLXNob3djYXNlIC5lbC10YWJsZS12Ml9fb3ZlcmxheSB7XG4gIHotaW5kZXg6IDk7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/overlay.vue)_

vue

```
<template>
  <el-table-v2
    :columns="columns"
    :data="data"
    :row-height="40"
    :width="700"
    :height="400"
  >
    <template #overlay>
      <div
        class="el-loading-mask"
        style="display: flex; align-items: center; justify-content: center"
      >
        <el-icon class="is-loading" color="var(--el-color-primary)" :size="26">
          <loading-icon />
        </el-icon>
      </div>
    </template>
  </el-table-v2>
</template>

<script lang="ts" setup>
import { Loading as LoadingIcon } from '@element-plus/icons-vue'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
const data = generateData(columns, 200)
</script>

<style>
.example-showcase .el-table-v2__overlay {
  z-index: 9;
}
</style>
```

隐藏源代码

## 手动滚动 [​](#手动滚动)

使用 Table V2 暴露的方法可以进行手动或编程式的滚动到指定的偏移量或者行。

TIP

`scrollToRow` 的第二个参数代表滚动策略，计算了要滚动的位置，其默认值是 `auto`。 如果你想要滚动到某个特定位置，你可以自己定义战略。 可用的选项是 `"auto" | "center" | "end" | "start" | "smart"`

`smart` 和`auto` 之间的区别是， `auto` 是 `smart` 滚动策略的子集。

Scroll pixels

Scroll rows

Scroll by pixels Scroll by rows

Row 0 - Col 0

Row 0 - Col 1

Row 0 - Col 2

Row 0 - Col 3

Row 0 - Col 4

Row 0 - Col 5

Row 0 - Col 6

Row 0 - Col 7

Row 0 - Col 8

Row 0 - Col 9

Row 1 - Col 0

Row 1 - Col 1

Row 1 - Col 2

Row 1 - Col 3

Row 1 - Col 4

Row 1 - Col 5

Row 1 - Col 6

Row 1 - Col 7

Row 1 - Col 8

Row 1 - Col 9

Row 2 - Col 0

Row 2 - Col 1

Row 2 - Col 2

Row 2 - Col 3

Row 2 - Col 4

Row 2 - Col 5

Row 2 - Col 6

Row 2 - Col 7

Row 2 - Col 8

Row 2 - Col 9

Row 3 - Col 0

Row 3 - Col 1

Row 3 - Col 2

Row 3 - Col 3

Row 3 - Col 4

Row 3 - Col 5

Row 3 - Col 6

Row 3 - Col 7

Row 3 - Col 8

Row 3 - Col 9

Row 4 - Col 0

Row 4 - Col 1

Row 4 - Col 2

Row 4 - Col 3

Row 4 - Col 4

Row 4 - Col 5

Row 4 - Col 6

Row 4 - Col 7

Row 4 - Col 8

Row 4 - Col 9

Row 5 - Col 0

Row 5 - Col 1

Row 5 - Col 2

Row 5 - Col 3

Row 5 - Col 4

Row 5 - Col 5

Row 5 - Col 6

Row 5 - Col 7

Row 5 - Col 8

Row 5 - Col 9

Row 6 - Col 0

Row 6 - Col 1

Row 6 - Col 2

Row 6 - Col 3

Row 6 - Col 4

Row 6 - Col 5

Row 6 - Col 6

Row 6 - Col 7

Row 6 - Col 8

Row 6 - Col 9

Row 7 - Col 0

Row 7 - Col 1

Row 7 - Col 2

Row 7 - Col 3

Row 7 - Col 4

Row 7 - Col 5

Row 7 - Col 6

Row 7 - Col 7

Row 7 - Col 8

Row 7 - Col 9

Row 8 - Col 0

Row 8 - Col 1

Row 8 - Col 2

Row 8 - Col 3

Row 8 - Col 4

Row 8 - Col 5

Row 8 - Col 6

Row 8 - Col 7

Row 8 - Col 8

Row 8 - Col 9

Column 0

Column 1

Column 2

Column 3

Column 4

Column 5

Column 6

Column 7

Column 8

Column 9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwibWItNCBmbGV4IGl0ZW1zLWNlbnRlclwiPlxuICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJTY3JvbGwgcGl4ZWxzXCIgY2xhc3M9XCJtci00XCI+XG4gICAgICA8ZWwtaW5wdXQgdi1tb2RlbD1cInNjcm9sbERlbHRhXCIgLz5cbiAgICA8L2VsLWZvcm0taXRlbT5cbiAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiU2Nyb2xsIHJvd3NcIj5cbiAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwic2Nyb2xsUm93c1wiIC8+XG4gICAgPC9lbC1mb3JtLWl0ZW0+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwibWItNCBmbGV4IGl0ZW1zLWNlbnRlclwiPlxuICAgIDxlbC1idXR0b24gQGNsaWNrPVwic2Nyb2xsQnlQaXhlbHNcIj4gU2Nyb2xsIGJ5IHBpeGVscyA8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIEBjbGljaz1cInNjcm9sbEJ5Um93c1wiPiBTY3JvbGwgYnkgcm93cyA8L2VsLWJ1dHRvbj5cbiAgPC9kaXY+XG4gIDxkaXYgc3R5bGU9XCJoZWlnaHQ6IDQwMHB4XCI+XG4gICAgPGVsLWF1dG8tcmVzaXplcj5cbiAgICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD1cInsgaGVpZ2h0LCB3aWR0aCB9XCI+XG4gICAgICAgIDxlbC10YWJsZS12MlxuICAgICAgICAgIHJlZj1cInRhYmxlUmVmXCJcbiAgICAgICAgICA6Y29sdW1ucz1cImNvbHVtbnNcIlxuICAgICAgICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgICAgICAgOndpZHRoPVwid2lkdGhcIlxuICAgICAgICAgIDpoZWlnaHQ9XCJoZWlnaHRcIlxuICAgICAgICAgIGZpeGVkXG4gICAgICAgIC8+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtYXV0by1yZXNpemVyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgVGFibGVWMkluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBnZW5lcmF0ZUNvbHVtbnMgPSAobGVuZ3RoID0gMTAsIHByZWZpeCA9ICdjb2x1bW4tJywgcHJvcHM/OiBhbnkpID0+XG4gIEFycmF5LmZyb20oeyBsZW5ndGggfSkubWFwKChfLCBjb2x1bW5JbmRleCkgPT4gKHtcbiAgICAuLi5wcm9wcyxcbiAgICBrZXk6IGAke3ByZWZpeH0ke2NvbHVtbkluZGV4fWAsXG4gICAgZGF0YUtleTogYCR7cHJlZml4fSR7Y29sdW1uSW5kZXh9YCxcbiAgICB0aXRsZTogYENvbHVtbiAke2NvbHVtbkluZGV4fWAsXG4gICAgd2lkdGg6IDE1MCxcbiAgfSkpXG5cbmNvbnN0IGdlbmVyYXRlRGF0YSA9IChcbiAgY29sdW1uczogUmV0dXJuVHlwZTx0eXBlb2YgZ2VuZXJhdGVDb2x1bW5zPixcbiAgbGVuZ3RoID0gMjAwLFxuICBwcmVmaXggPSAncm93LSdcbikgPT5cbiAgQXJyYXkuZnJvbSh7IGxlbmd0aCB9KS5tYXAoKF8sIHJvd0luZGV4KSA9PiB7XG4gICAgcmV0dXJuIGNvbHVtbnMucmVkdWNlKFxuICAgICAgKHJvd0RhdGEsIGNvbHVtbiwgY29sdW1uSW5kZXgpID0+IHtcbiAgICAgICAgcm93RGF0YVtjb2x1bW4uZGF0YUtleV0gPSBgUm93ICR7cm93SW5kZXh9IC0gQ29sICR7Y29sdW1uSW5kZXh9YFxuICAgICAgICByZXR1cm4gcm93RGF0YVxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IGAke3ByZWZpeH0ke3Jvd0luZGV4fWAsXG4gICAgICAgIHBhcmVudElkOiBudWxsLFxuICAgICAgfVxuICAgIClcbiAgfSlcblxuY29uc3QgY29sdW1ucyA9IGdlbmVyYXRlQ29sdW1ucygxMClcbmNvbnN0IGRhdGEgPSBnZW5lcmF0ZURhdGEoY29sdW1ucywgMjAwKVxuY29uc3QgdGFibGVSZWYgPSByZWY8VGFibGVWMkluc3RhbmNlPigpXG5jb25zdCBzY3JvbGxEZWx0YSA9IHJlZigyMDApXG5jb25zdCBzY3JvbGxSb3dzID0gcmVmKDEwKVxuXG5mdW5jdGlvbiBzY3JvbGxCeVBpeGVscygpIHtcbiAgdGFibGVSZWYudmFsdWU/LnNjcm9sbFRvVG9wKHNjcm9sbERlbHRhLnZhbHVlKVxufVxuXG5mdW5jdGlvbiBzY3JvbGxCeVJvd3MoKSB7XG4gIHRhYmxlUmVmLnZhbHVlPy5zY3JvbGxUb1JvdyhzY3JvbGxSb3dzLnZhbHVlKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/table-v2/manual-scroll.vue)_

vue

```
<template>
  <div class="mb-4 flex items-center">
    <el-form-item label="Scroll pixels" class="mr-4">
      <el-input v-model="scrollDelta" />
    </el-form-item>
    <el-form-item label="Scroll rows">
      <el-input v-model="scrollRows" />
    </el-form-item>
  </div>
  <div class="mb-4 flex items-center">
    <el-button @click="scrollByPixels"> Scroll by pixels </el-button>
    <el-button @click="scrollByRows"> Scroll by rows </el-button>
  </div>
  <div style="height: 400px">
    <el-auto-resizer>
      <template #default="{ height, width }">
        <el-table-v2
          ref="tableRef"
          :columns="columns"
          :data="data"
          :width="width"
          :height="height"
          fixed
        />
      </template>
    </el-auto-resizer>
  </div>
</template>

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

import type { TableV2Instance } from 'element-plus'

const generateColumns = (length = 10, prefix = 'column-', props?: any) =>
  Array.from({ length }).map((_, columnIndex) => ({
    ...props,
    key: `${prefix}${columnIndex}`,
    dataKey: `${prefix}${columnIndex}`,
    title: `Column ${columnIndex}`,
    width: 150,
  }))

const generateData = (
  columns: ReturnType<typeof generateColumns>,
  length = 200,
  prefix = 'row-'
) =>
  Array.from({ length }).map((_, rowIndex) => {
    return columns.reduce(
      (rowData, column, columnIndex) => {
        rowData[column.dataKey] = `Row ${rowIndex} - Col ${columnIndex}`
        return rowData
      },
      {
        id: `${prefix}${rowIndex}`,
        parentId: null,
      }
    )
  })

const columns = generateColumns(10)
const data = generateData(columns, 200)
const tableRef = ref<TableV2Instance>()
const scrollDelta = ref(200)
const scrollRows = ref(10)

function scrollByPixels() {
  tableRef.value?.scrollToTop(scrollDelta.value)
}

function scrollByRows() {
  tableRef.value?.scrollToRow(scrollRows.value)
}
</script>
```

隐藏源代码

## TableV2 API [​](#tablev2-api)

### TableV2 Attributes [​](#tablev2-attributes)

| 属性名 | 描述说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| cache | 为了更好的渲染效果预先多加载的行数 | `number` | 2 |
| estimated-row-height | 渲染动态的单元格的预估高度 | `number` | — |
| header-class | header 部分的自定义 class 名 | `string` / Function<[HeaderClassGetter](#typings)\> | — |
| header-props | header 部分的自定义 props 名 | `object` / Function<[HeaderPropsGetter](#typings)\> | — |
| header-cell-props | header cell 部分的自定义 props 名 | `object` / Function<[HeaderCellPropsGetter](#typings)\> | — |
| header-height | Header 的高度由`height`设置。 如果传入数组，它会使 header row 等于数组长度 | `number`/ `number[]` | 50 |
| footer-height | Footer 部分的高度，当传入值时，这部分将被计算入 table 的高度里 | `number` | 0 |
| row-class | row wrapper 部分的自定义 class 名 | `string` / Function<[RowClassGetter](#typings)\> | — |
| row-key | 每行的 key 值，如果不提供，将使用索引 index 代替 | `string` / `Symbol` / `number` | id |
| row-props | row component 部分的自定义 class 名 | `object` / Function<[RowPropsGetter](#typings)\> | — |
| row-height | 每行的高度, 用于计算表的总高度 | `number` | 50 |
| row-event-handlers | 当每行添加了一系列事件处理器时触发 | `object`<[RowEventHandlers](#typings)\> | — |
| cell-props | 每个单元格 cell 的自定义 props (除了 header cell 以外) | `object` / Function<[CellPropsGetter](#typings)\> | — |
| columns | 列 column 的配置数组 | [Column\[\]](#column-attribute) | — |
| data | 要在表中渲染的数据数组 | [Data\[\]](#typings) | \[\] |
| data-getter | 一个自定义方法从数据源获取数据 | Function<[DataGetter<T>](#typings)\> | — |
| fixed-data | 渲染行在表格主内容上方和 header 下方区域的数据 | `object`<[Data](#typings)\> | — |
| expand-column-key | 列的 key 来标记哪个行可以被展开 | `string` | — |
| expanded-row-keys | 存放行展开状态的 key 的数组，可以和 `v-model` 搭配使用 | [KeyType\[\]](#typings) | — |
| default-expanded-row-keys | 默认展开的行的 key 的数组, **这个数据不是响应式的** | [KeyType\[\]](#typings) | — |
| class | 表格的类名称，将应用于表格的全部的三个部分 (左、右、主) | `string` / `array` / `object` | — |
| fixed | 单元格宽度是自适应还是固定 | `boolean` | false |
| width required | 表格的宽度 | `number` | — |
| height required | 表格的高度 | `number` | — |
| max-height | 表格的最大高度 | `number` | — |
| indent-size | 树形表的水平缩进 | `number` | 12 |
| h-scrollbar-size | 配置表格的水平滚动条大小，防止水平和垂直滚动条重叠。 | `number` | 6 |
| v-scrollbar-size | 配置表格的垂直滚动条大小，防止水平和垂直滚动条重叠。 | `number` | 6 |
| scrollbar-always-on | 如果开启，滚动条将一直显示，反之只会在鼠标经过时显示。 | `boolean` | false |
| sort-by | 排序方式 | `object`<[SortBy](#typings)\> | {} |
| sort-state | 多个排序 | `object`<[SortState](#typings)\> | undefined |

### TableV2 Slots [​](#tablev2-slots)

| 插槽名 | 事件参数 |
| --- | --- |
| cell | `object`<[CellSlotProps](#typings)\> |
| header | `object`<[HeaderSlotProps](#typings)\> |
| header-cell | `object`<[HeaderCellSlotProps](#typings)\> |
| row | `object`<[RowSlotProps](#typings)\> |
| footer | — |
| empty | — |
| overlay | — |

### TableV2 Events [​](#tablev2-events)

| 事件名 | 描述 | 参数 |
| --- | --- | --- |
| column-sort | 列排序时调用 | `object`<[ColumnSortParam](#typings)\> |
| expanded-rows-change | 行展开状态改变时触发 | [KeyType\[\]](#typings) |
| end-reached | 到达表格末尾时触发。 回调包含剩余距离，它通常是滚动条高度。 | `Function` |
| scroll | 表格被用户滚动后触发 | `object`<[ScrollParams](#typings)\> |
| rows-rendered | 当行被渲染后触发 | `object`<[RowsRenderedParams](#typings)\> |
| row-expand | 点击箭头图标展开/折叠树节点时触发 | `object`<[RowExpandParams](#typings)\> |

### TableV2 Exposes [​](#tablev2-exposes)

| Method | 描述 | 参数 |
| --- | --- | --- |
| scrollTo | 滚动到给定位置 | `Function` |
| scrollToLeft | 滚动到给定的水平位置 | `Function` |
| scrollToTop | 滚动到给定的垂直位置 | `Function` |
| scrollToRow | 使用给定的滚动策略滚动至指定行 | `Function` |

TIP

请注意：这些是 `JavaScript` 对象，所以您 **不能使用** 短横线命名法（kebab-case）来处理这些属性

### Column Attribute [​](#column-attribute)

| 属性名 | 描述 | 类型 | 默认值 |
| --- | --- | --- | --- |
| align | 表格单元格内容对齐方式 | [Alignment](https://github.com/element-plus/element-plus/blob/b92b22932758f0ddea98810ae248f6ca62f77e25/packages/components/table-v2/src/constants.ts#L6) | left |
| class | 列的类名 | `string` | — |
| key | 唯一标志 | [KeyType](#typings) | — |
| dataKey | data 的唯一标志符 | [KeyType](#typings) | — |
| fixed | 固定列位置 | `boolean` / [FixedDir](https://github.com/element-plus/element-plus/blob/b92b22932758f0ddea98810ae248f6ca62f77e25/packages/components/table-v2/src/constants.ts#L11) | false |
| flexGrow | CSS 属性 flex grow, 仅当不是固定表时才生效 | `number` | 0 |
| flexShrink | CSS 属性 flex shrink, 仅当不是固定表时才生效 | `number` | 1 |
| headerClass | 自定义 header 头部类名 | `string` | — |
| hidden | 此列是否不可见 | `boolean` | — |
| style | 自定义列单元格的类名，将会与 gird 单元格合并 | `object` | — |
| sortable | 设置列是否可排序 | `boolean` | — |
| title | Header 头部单元格中的默认文本 | `string` | — |
| maxWidth | 列的最大宽度 | `number` | — |
| minWidth | 列的最小宽度 | `number` | — |
| width required | 列宽度 | `number` | — |
| cellRenderer | 自定义单元格渲染器 | `VueComponent` / (props: [CellRenderProps](#typings)) => VNode | — |
| headerCellRenderer | 自定义头部渲染器 | `VueComponent` / (props: [HeaderRenderProps](#typings)) => VNode | — |

## Typings [​](#typings)

显示类型声明

ts

```
type HeaderClassGetter = (param: {
  columns: Column<any>[]
  headerIndex: number
}) => string

type HeaderPropsGetter = (param: {
  columns: Column<any>[]
  headerIndex: number
}) => Record<string, any>

type HeaderCellPropsGetter = (param: {
  columns: Column<any>[]
  column: Column<any>
  columnIndex: number
  headerIndex: number
  style: CSSProperties
}) => Record<string, any>

type RowClassGetter = (param: {
  columns: Column<any>[]
  rowData: any
  rowIndex: number
}) => string

type RowPropsGetter = (param: {
  columns: Column<any>[]
  rowData: any
  rowIndex: number
}) => Record<string, any>

type CellPropsGetter = (param: {
  column: Column<any>
  columns: Column<any>[]
  columnIndex: number
  cellData: any
  rowData: any
  rowIndex: number
}) => void

type DataGetterParams<T> = {
  columns: Column<T>[]
  column: Column<T>
  columnIndex: number
} & RowCommonParams

type DataGetter<T> = (params: DataGetterParams<T>) => T

type CellRenderProps<T> = {
  cellData: T
  column: Column<T>
  columns: Column<T>[]
  columnIndex: number
  rowData: any
  rowIndex: number
}

type HeaderRenderProps<T> = {
  column: Column<T>
  columns: Column<T>[]
  columnIndex: number
  headerIndex: number
}

type ScrollParams = {
  xAxisScrollDir: 'forward' | 'backward'
  scrollLeft: number
  yAxisScrollDir: 'forward' | 'backward'
  scrollTop: number
}

type CellSlotProps<T> = {
  column: Column<T>
  columns: Column<T>[]
  columnIndex: number
  depth: number
  style: CSSProperties
  rowData: any
  rowIndex: number
  isScrolling: boolean
  expandIconProps?:
    | {
        rowData: any
        rowIndex: number
        onExpand: (expand: boolean) => void
      }
    | undefined
}

type HeaderSlotProps = {
  cells: VNode[]
  columns: Column<any>[]
  headerIndex: number
}

type HeaderCellSlotProps = {
  class: string
  columns: Column<any>[]
  column: Column<any>
  columnIndex: number
  headerIndex: number
  style: CSSProperties
  headerCellProps?: any
  sortBy: SortBy
  sortState?: SortState | undefined
  onColumnSorted: (e: MouseEvent) => void
}

type RowCommonParams = {
  rowData: any
  rowIndex: number
}

type RowEventHandlerParams = {
  rowKey: KeyType
  event: Event
} & RowCommonParams

type RowEventHandler = (params: RowEventHandlerParams) => void
type RowEventHandlers = {
  onClick?: RowEventHandler
  onContextmenu?: RowEventHandler
  onDblclick?: RowEventHandler
  onMouseenter?: RowEventHandler
  onMouseleave?: RowEventHandler
}

type RowsRenderedParams = {
  rowCacheStart: number
  rowCacheEnd: number
  rowVisibleStart: number
  rowVisibleEnd: number
}

type RowSlotProps = {
  columns: Column<any>[]
  rowData: any
  columnIndex: number
  rowIndex: number
  data: any
  key: number | string
  isScrolling?: boolean
  style: CSSProperties
}

type RowExpandParams = {
  expanded: boolean
  rowKey: KeyType
} & RowCommonParams

type Data = {
  [key: KeyType]: any
  children?: Array<any>
}

type FixedData = Data

type KeyType = string | number | symbol

type ColumnSortParam<T> = { column: Column<T>; key: KeyType; order: SortOrder }

enum SortOrder {
  ASC = 'asc',
  DESC = 'desc',
}

enum Alignment {
  LEFT = 'left',
  CENTER = 'center',
  RIGHT = 'right',
}

type SortBy = { key: KeyType; Order: SortOrder }
type SortState = Record<KeyType, SortOrder>
```

## 常见问题 [​](#常见问题)

#### 如何在第一列中渲染带复选框的列表？ [​](#如何在第一列中渲染带复选框的列表)

由于可以自己定义单元格渲染器，您可以根据示例 [自定义单元格渲染器](#customize-cell-renderer) 代码来渲染 `checkbox`，并自行管理其状态。

#### 为什么虚拟化表提供的功能较 [TableV1](https://element-plus.org/zh-CN/component/table) 少？ [​](#为什么虚拟化表提供的功能较-tablev1-少)

对于虚拟化表格，我们打算减少一些功能，让用户根据需求自行实现。 整合过多的功能会让组件的代码变得难以维护，且对于大多数用户来说，基础功能就已足够。 一些主要的功能尚未开发。 我们很希望听从您的意见。 进入 [Discord](https://discord.com/invite/gXK9XNzW3X) 持续关注.

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/table-v2) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/table-v2.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/table-v2.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/33254923?v=4&size=64)](https://github.com/yicheny)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/132551120?v=4&size=64)](https://github.com/YiMo1)[![](https://avatars.githubusercontent.com/u/80318503?v=4&size=64)](https://github.com/YancyZhang30)[![](https://avatars.githubusercontent.com/u/35426360?v=4&size=64)](https://github.com/Jungzl)[![](https://avatars.githubusercontent.com/u/60510247?v=4&size=64)](https://github.com/Whbbit1999)[![](https://avatars.githubusercontent.com/u/30046649?v=4&size=64)](https://github.com/MrWeilian)[![](https://avatars.githubusercontent.com/u/169252980?v=4&size=64)](https://github.com/xiaochenchen-igg-com)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/22515951?v=4&size=64)](https://github.com/webfansplz)[![](https://avatars.githubusercontent.com/u/17539193?v=4&size=64)](https://github.com/gaoyia)[![](https://avatars.githubusercontent.com/u/32761502?v=4&size=64)](https://github.com/kimverchan)[![](https://avatars.githubusercontent.com/u/134276765?v=4&size=64)](https://github.com/zwgwf)[![](https://avatars.githubusercontent.com/u/93197952?v=4&size=64)](https://github.com/Mutter45)[![](https://avatars.githubusercontent.com/u/32960305?v=4&size=64)](https://github.com/KimYangOfCat)[![](https://avatars.githubusercontent.com/u/48878568?v=4&size=64)](https://github.com/SignDawn)[![](https://avatars.githubusercontent.com/u/24557533?v=4&size=64)](https://github.com/gb853940223)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/78799103?v=4&size=64)](https://github.com/kankan-web)[![](https://avatars.githubusercontent.com/u/75007029?v=4&size=64)](https://github.com/yj-liuzepeng)[![](https://avatars.githubusercontent.com/u/83541965?v=4&size=64)](https://github.com/MilesTails01)[![](https://avatars.githubusercontent.com/u/62194324?v=4&size=64)](https://github.com/onishi-kohei)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)

[Table 表格](https://element-plus.org/zh-CN/component/table)

[Tag 标签](https://element-plus.org/zh-CN/component/tag)




---
## [data/tag] Tag 标签
> 官方文档: https://element-plus.org/zh-CN/component/tag.html

---

# Tag 标签 [​](#tag-标签)

更新日志待解决

7

用于标记和选择。

## 基础用法 [​](#基础用法)

由 `type` 属性来选择 tag 的类型。 也可以通过 `color` 属性来自定义背景色。

Tag 1Tag 2Tag 3Tag 4Tag 5

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtMlwiPlxuICAgIDxlbC10YWcgdHlwZT1cInByaW1hcnlcIj5UYWcgMTwvZWwtdGFnPlxuICAgIDxlbC10YWcgdHlwZT1cInN1Y2Nlc3NcIj5UYWcgMjwvZWwtdGFnPlxuICAgIDxlbC10YWcgdHlwZT1cImluZm9cIj5UYWcgMzwvZWwtdGFnPlxuICAgIDxlbC10YWcgdHlwZT1cIndhcm5pbmdcIj5UYWcgNDwvZWwtdGFnPlxuICAgIDxlbC10YWcgdHlwZT1cImRhbmdlclwiPlRhZyA1PC9lbC10YWc+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tag/basic.vue)_

vue

```
<template>
  <div class="flex gap-2">
    <el-tag type="primary">Tag 1</el-tag>
    <el-tag type="success">Tag 2</el-tag>
    <el-tag type="info">Tag 3</el-tag>
    <el-tag type="warning">Tag 4</el-tag>
    <el-tag type="danger">Tag 5</el-tag>
  </div>
</template>
```

隐藏源代码

## 可移除标签 [​](#可移除标签)

设置 `closable` 属性可以定义一个标签是否可移除。 它接受一个 `Boolean`。 默认的标签移除时会附带渐变动画。 如果不想使用，可以设置 `disable-transitions` 属性，它接受一个 `Boolean`，`true` 为关闭。 当 Tag 被移除时会触发 `close` 事件。

Tag 1Tag 2Tag 3Tag 4Tag 5

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtMlwiPlxuICAgIDxlbC10YWcgdi1mb3I9XCJ0YWcgaW4gdGFnc1wiIDprZXk9XCJ0YWcubmFtZVwiIGNsb3NhYmxlIDp0eXBlPVwidGFnLnR5cGVcIj5cbiAgICAgIHt7IHRhZy5uYW1lIH19XG4gICAgPC9lbC10YWc+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBUYWdQcm9wcyB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuaW50ZXJmYWNlIFRhZ3NJdGVtIHtcbiAgbmFtZTogc3RyaW5nXG4gIHR5cGU6IFRhZ1Byb3BzWyd0eXBlJ11cbn1cblxuY29uc3QgdGFncyA9IHJlZjxUYWdzSXRlbVtdPihbXG4gIHsgbmFtZTogJ1RhZyAxJywgdHlwZTogJ3ByaW1hcnknIH0sXG4gIHsgbmFtZTogJ1RhZyAyJywgdHlwZTogJ3N1Y2Nlc3MnIH0sXG4gIHsgbmFtZTogJ1RhZyAzJywgdHlwZTogJ2luZm8nIH0sXG4gIHsgbmFtZTogJ1RhZyA0JywgdHlwZTogJ3dhcm5pbmcnIH0sXG4gIHsgbmFtZTogJ1RhZyA1JywgdHlwZTogJ2RhbmdlcicgfSxcbl0pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tag/removable.vue)_

vue

```
<template>
  <div class="flex gap-2">
    <el-tag v-for="tag in tags" :key="tag.name" closable :type="tag.type">
      {{ tag.name }}
    </el-tag>
  </div>
</template>

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

import type { TagProps } from 'element-plus'

interface TagsItem {
  name: string
  type: TagProps['type']
}

const tags = ref<TagsItem[]>([
  { name: 'Tag 1', type: 'primary' },
  { name: 'Tag 2', type: 'success' },
  { name: 'Tag 3', type: 'info' },
  { name: 'Tag 4', type: 'warning' },
  { name: 'Tag 5', type: 'danger' },
])
</script>
```

隐藏源代码

## 动态编辑标签 [​](#动态编辑标签)

动态编辑标签可以通过点击标签关闭按钮后触发的 `close` 事件来实现。

Tag 1Tag 2Tag 3 + New Tag

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtMlwiPlxuICAgIDxlbC10YWdcbiAgICAgIHYtZm9yPVwidGFnIGluIGR5bmFtaWNUYWdzXCJcbiAgICAgIDprZXk9XCJ0YWdcIlxuICAgICAgY2xvc2FibGVcbiAgICAgIDpkaXNhYmxlLXRyYW5zaXRpb25zPVwiZmFsc2VcIlxuICAgICAgQGNsb3NlPVwiaGFuZGxlQ2xvc2UodGFnKVwiXG4gICAgPlxuICAgICAge3sgdGFnIH19XG4gICAgPC9lbC10YWc+XG4gICAgPGVsLWlucHV0XG4gICAgICB2LWlmPVwiaW5wdXRWaXNpYmxlXCJcbiAgICAgIHJlZj1cIklucHV0UmVmXCJcbiAgICAgIHYtbW9kZWw9XCJpbnB1dFZhbHVlXCJcbiAgICAgIGNsYXNzPVwidy0yMFwiXG4gICAgICBzaXplPVwic21hbGxcIlxuICAgICAgQGtleXVwLmVudGVyPVwiaGFuZGxlSW5wdXRDb25maXJtXCJcbiAgICAgIEBibHVyPVwiaGFuZGxlSW5wdXRDb25maXJtXCJcbiAgICAvPlxuICAgIDxlbC1idXR0b24gdi1lbHNlIGNsYXNzPVwiYnV0dG9uLW5ldy10YWdcIiBzaXplPVwic21hbGxcIiBAY2xpY2s9XCJzaG93SW5wdXRcIj5cbiAgICAgICsgTmV3IFRhZ1xuICAgIDwvZWwtYnV0dG9uPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBuZXh0VGljaywgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IElucHV0SW5zdGFuY2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGlucHV0VmFsdWUgPSByZWYoJycpXG5jb25zdCBkeW5hbWljVGFncyA9IHJlZihbJ1RhZyAxJywgJ1RhZyAyJywgJ1RhZyAzJ10pXG5jb25zdCBpbnB1dFZpc2libGUgPSByZWYoZmFsc2UpXG5jb25zdCBJbnB1dFJlZiA9IHJlZjxJbnB1dEluc3RhbmNlPigpXG5cbmNvbnN0IGhhbmRsZUNsb3NlID0gKHRhZzogc3RyaW5nKSA9PiB7XG4gIGR5bmFtaWNUYWdzLnZhbHVlLnNwbGljZShkeW5hbWljVGFncy52YWx1ZS5pbmRleE9mKHRhZyksIDEpXG59XG5cbmNvbnN0IHNob3dJbnB1dCA9ICgpID0+IHtcbiAgaW5wdXRWaXNpYmxlLnZhbHVlID0gdHJ1ZVxuICBuZXh0VGljaygoKSA9PiB7XG4gICAgSW5wdXRSZWYudmFsdWUhLmlucHV0IS5mb2N1cygpXG4gIH0pXG59XG5cbmNvbnN0IGhhbmRsZUlucHV0Q29uZmlybSA9ICgpID0+IHtcbiAgaWYgKGlucHV0VmFsdWUudmFsdWUpIHtcbiAgICBkeW5hbWljVGFncy52YWx1ZS5wdXNoKGlucHV0VmFsdWUudmFsdWUpXG4gIH1cbiAgaW5wdXRWaXNpYmxlLnZhbHVlID0gZmFsc2VcbiAgaW5wdXRWYWx1ZS52YWx1ZSA9ICcnXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tag/editable.vue)_

vue

```
<template>
  <div class="flex gap-2">
    <el-tag
      v-for="tag in dynamicTags"
      :key="tag"
      closable
      :disable-transitions="false"
      @close="handleClose(tag)"
    >
      {{ tag }}
    </el-tag>
    <el-input
      v-if="inputVisible"
      ref="InputRef"
      v-model="inputValue"
      class="w-20"
      size="small"
      @keyup.enter="handleInputConfirm"
      @blur="handleInputConfirm"
    />
    <el-button v-else class="button-new-tag" size="small" @click="showInput">
      + New Tag
    </el-button>
  </div>
</template>

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

import type { InputInstance } from 'element-plus'

const inputValue = ref('')
const dynamicTags = ref(['Tag 1', 'Tag 2', 'Tag 3'])
const inputVisible = ref(false)
const InputRef = ref<InputInstance>()

const handleClose = (tag: string) => {
  dynamicTags.value.splice(dynamicTags.value.indexOf(tag), 1)
}

const showInput = () => {
  inputVisible.value = true
  nextTick(() => {
    InputRef.value!.input!.focus()
  })
}

const handleInputConfirm = () => {
  if (inputValue.value) {
    dynamicTags.value.push(inputValue.value)
  }
  inputVisible.value = false
  inputValue.value = ''
}
</script>
```

隐藏源代码

## 不同尺寸 [​](#不同尺寸)

Tag 组件提供除了默认值以外的三种尺寸，可以在不同场景下选择合适的按钮尺寸。

使用 `size` 属性来设置额外尺寸, 可选值包括 `large`, `default` 或 `small`.

LargeDefaultSmall

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtMlwiPlxuICAgIDxlbC10YWcgc2l6ZT1cImxhcmdlXCI+TGFyZ2U8L2VsLXRhZz5cbiAgICA8ZWwtdGFnPkRlZmF1bHQ8L2VsLXRhZz5cbiAgICA8ZWwtdGFnIHNpemU9XCJzbWFsbFwiPlNtYWxsPC9lbC10YWc+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tag/sizes.vue)_

vue

```
<template>
  <div class="flex gap-2">
    <el-tag size="large">Large</el-tag>
    <el-tag>Default</el-tag>
    <el-tag size="small">Small</el-tag>
  </div>
</template>
```

隐藏源代码

## 主题 [​](#主题)

Tag 组件提供了三个不同的主题：`dark`、`light` 和 `plain`。

通过设置 `effect` 属性来改变主题，默认为 `light`。

DarkTag 1Tag 2Tag 3Tag 4Tag 5

LightTag 1Tag 2Tag 3Tag 4Tag 5

PlainTag 1Tag 2Tag 3Tag 4Tag 5

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtMlwiPlxuICAgIDxzcGFuPkRhcms8L3NwYW4+XG4gICAgPGVsLXRhZ1xuICAgICAgdi1mb3I9XCJpdGVtIGluIGl0ZW1zXCJcbiAgICAgIDprZXk9XCJpdGVtLmxhYmVsXCJcbiAgICAgIDp0eXBlPVwiaXRlbS50eXBlXCJcbiAgICAgIGVmZmVjdD1cImRhcmtcIlxuICAgID5cbiAgICAgIHt7IGl0ZW0ubGFiZWwgfX1cbiAgICA8L2VsLXRhZz5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJmbGV4IGdhcC0yIG10LTRcIj5cbiAgICA8c3Bhbj5MaWdodDwvc3Bhbj5cbiAgICA8ZWwtdGFnXG4gICAgICB2LWZvcj1cIml0ZW0gaW4gaXRlbXNcIlxuICAgICAgOmtleT1cIml0ZW0ubGFiZWxcIlxuICAgICAgOnR5cGU9XCJpdGVtLnR5cGVcIlxuICAgICAgZWZmZWN0PVwibGlnaHRcIlxuICAgID5cbiAgICAgIHt7IGl0ZW0ubGFiZWwgfX1cbiAgICA8L2VsLXRhZz5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJmbGV4IGdhcC0yIG10LTRcIj5cbiAgICA8c3Bhbj5QbGFpbjwvc3Bhbj5cbiAgICA8ZWwtdGFnXG4gICAgICB2LWZvcj1cIml0ZW0gaW4gaXRlbXNcIlxuICAgICAgOmtleT1cIml0ZW0ubGFiZWxcIlxuICAgICAgOnR5cGU9XCJpdGVtLnR5cGVcIlxuICAgICAgZWZmZWN0PVwicGxhaW5cIlxuICAgID5cbiAgICAgIHt7IGl0ZW0ubGFiZWwgfX1cbiAgICA8L2VsLXRhZz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IFRhZ1Byb3BzIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG50eXBlIEl0ZW0gPSB7IHR5cGU6IFRhZ1Byb3BzWyd0eXBlJ107IGxhYmVsOiBzdHJpbmcgfVxuXG5jb25zdCBpdGVtcyA9IHJlZjxBcnJheTxJdGVtPj4oW1xuICB7IHR5cGU6ICdwcmltYXJ5JywgbGFiZWw6ICdUYWcgMScgfSxcbiAgeyB0eXBlOiAnc3VjY2VzcycsIGxhYmVsOiAnVGFnIDInIH0sXG4gIHsgdHlwZTogJ2luZm8nLCBsYWJlbDogJ1RhZyAzJyB9LFxuICB7IHR5cGU6ICd3YXJuaW5nJywgbGFiZWw6ICdUYWcgNCcgfSxcbiAgeyB0eXBlOiAnZGFuZ2VyJywgbGFiZWw6ICdUYWcgNScgfSxcbl0pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tag/theme.vue)_

vue

```
<template>
  <div class="flex gap-2">
    <span>Dark</span>
    <el-tag
      v-for="item in items"
      :key="item.label"
      :type="item.type"
      effect="dark"
    >
      {{ item.label }}
    </el-tag>
  </div>
  <div class="flex gap-2 mt-4">
    <span>Light</span>
    <el-tag
      v-for="item in items"
      :key="item.label"
      :type="item.type"
      effect="light"
    >
      {{ item.label }}
    </el-tag>
  </div>
  <div class="flex gap-2 mt-4">
    <span>Plain</span>
    <el-tag
      v-for="item in items"
      :key="item.label"
      :type="item.type"
      effect="plain"
    >
      {{ item.label }}
    </el-tag>
  </div>
</template>

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

import type { TagProps } from 'element-plus'

type Item = { type: TagProps['type']; label: string }

const items = ref<Array<Item>>([
  { type: 'primary', label: 'Tag 1' },
  { type: 'success', label: 'Tag 2' },
  { type: 'info', label: 'Tag 3' },
  { type: 'warning', label: 'Tag 4' },
  { type: 'danger', label: 'Tag 5' },
])
</script>
```

隐藏源代码

## 圆形标签 [​](#圆形标签)

Tag 可以向按钮组件一样变为完全圆形。

Tag 1Tag 2Tag 3Tag 4Tag 5

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtMlwiPlxuICAgIDxlbC10YWdcbiAgICAgIHYtZm9yPVwiaXRlbSBpbiBpdGVtc1wiXG4gICAgICA6a2V5PVwiaXRlbS5sYWJlbFwiXG4gICAgICA6dHlwZT1cIml0ZW0udHlwZVwiXG4gICAgICBlZmZlY3Q9XCJkYXJrXCJcbiAgICAgIHJvdW5kXG4gICAgPlxuICAgICAge3sgaXRlbS5sYWJlbCB9fVxuICAgIDwvZWwtdGFnPlxuICA8L2Rpdj5cbiAgPGRpdiBjbGFzcz1cImZsZXggZ2FwLTIgbXQtNFwiPlxuICAgIDxlbC10YWdcbiAgICAgIHYtZm9yPVwiaXRlbSBpbiBpdGVtc1wiXG4gICAgICA6a2V5PVwiaXRlbS5sYWJlbFwiXG4gICAgICA6dHlwZT1cIml0ZW0udHlwZVwiXG4gICAgICBlZmZlY3Q9XCJsaWdodFwiXG4gICAgICByb3VuZFxuICAgID5cbiAgICAgIHt7IGl0ZW0ubGFiZWwgfX1cbiAgICA8L2VsLXRhZz5cbiAgPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJmbGV4IGdhcC0yIG10LTRcIj5cbiAgICA8ZWwtdGFnXG4gICAgICB2LWZvcj1cIml0ZW0gaW4gaXRlbXNcIlxuICAgICAgOmtleT1cIml0ZW0ubGFiZWxcIlxuICAgICAgOnR5cGU9XCJpdGVtLnR5cGVcIlxuICAgICAgZWZmZWN0PVwicGxhaW5cIlxuICAgICAgcm91bmRcbiAgICA+XG4gICAgICB7eyBpdGVtLmxhYmVsIH19XG4gICAgPC9lbC10YWc+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBUYWdQcm9wcyB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxudHlwZSBJdGVtID0geyB0eXBlOiBUYWdQcm9wc1sndHlwZSddOyBsYWJlbDogc3RyaW5nIH1cblxuY29uc3QgaXRlbXMgPSByZWY8QXJyYXk8SXRlbT4+KFtcbiAgeyB0eXBlOiAncHJpbWFyeScsIGxhYmVsOiAnVGFnIDEnIH0sXG4gIHsgdHlwZTogJ3N1Y2Nlc3MnLCBsYWJlbDogJ1RhZyAyJyB9LFxuICB7IHR5cGU6ICdpbmZvJywgbGFiZWw6ICdUYWcgMycgfSxcbiAgeyB0eXBlOiAnd2FybmluZycsIGxhYmVsOiAnVGFnIDQnIH0sXG4gIHsgdHlwZTogJ2RhbmdlcicsIGxhYmVsOiAnVGFnIDUnIH0sXG5dKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tag/rounded.vue)_

vue

```
<template>
  <div class="flex gap-2">
    <el-tag
      v-for="item in items"
      :key="item.label"
      :type="item.type"
      effect="dark"
      round
    >
      {{ item.label }}
    </el-tag>
  </div>
  <div class="flex gap-2 mt-4">
    <el-tag
      v-for="item in items"
      :key="item.label"
      :type="item.type"
      effect="light"
      round
    >
      {{ item.label }}
    </el-tag>
  </div>
  <div class="flex gap-2 mt-4">
    <el-tag
      v-for="item in items"
      :key="item.label"
      :type="item.type"
      effect="plain"
      round
    >
      {{ item.label }}
    </el-tag>
  </div>
</template>

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

import type { TagProps } from 'element-plus'

type Item = { type: TagProps['type']; label: string }

const items = ref<Array<Item>>([
  { type: 'primary', label: 'Tag 1' },
  { type: 'success', label: 'Tag 2' },
  { type: 'info', label: 'Tag 3' },
  { type: 'warning', label: 'Tag 4' },
  { type: 'danger', label: 'Tag 5' },
])
</script>
```

隐藏源代码

## 可选中的标签 [​](#可选中的标签)

有时候因为业务需求，我们可能会需要用到类似复选框的标签，但是**按钮式的复选框**的样式又不满足需求，此时我们就可以用到 `check-tag`组件。 您可以在2.5.4中使用 `type` 属性。

check-tag 的基础使用方法，check-tag 提供的 API 非常简单。

CheckedToggle meDisabled

Tag 1 Tag 2 Tag 3 Tag 4 Tag 5 Tag 6

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtMlwiPlxuICAgIDxlbC1jaGVjay10YWcgY2hlY2tlZD5DaGVja2VkPC9lbC1jaGVjay10YWc+XG4gICAgPGVsLWNoZWNrLXRhZyA6Y2hlY2tlZD1cImNoZWNrZWRcIiBAY2hhbmdlPVwib25DaGFuZ2VcIj5Ub2dnbGUgbWU8L2VsLWNoZWNrLXRhZz5cbiAgICA8ZWwtY2hlY2stdGFnIGRpc2FibGVkPkRpc2FibGVkPC9lbC1jaGVjay10YWc+XG4gIDwvZGl2PlxuICA8ZGl2IGNsYXNzPVwiZmxleCBnYXAtMiBtdC00XCI+XG4gICAgPGVsLWNoZWNrLXRhZyA6Y2hlY2tlZD1cImNoZWNrZWQxXCIgdHlwZT1cInByaW1hcnlcIiBAY2hhbmdlPVwib25DaGFuZ2UxXCI+XG4gICAgICBUYWcgMVxuICAgIDwvZWwtY2hlY2stdGFnPlxuICAgIDxlbC1jaGVjay10YWcgOmNoZWNrZWQ9XCJjaGVja2VkMlwiIHR5cGU9XCJzdWNjZXNzXCIgQGNoYW5nZT1cIm9uQ2hhbmdlMlwiPlxuICAgICAgVGFnIDJcbiAgICA8L2VsLWNoZWNrLXRhZz5cbiAgICA8ZWwtY2hlY2stdGFnIDpjaGVja2VkPVwiY2hlY2tlZDNcIiB0eXBlPVwiaW5mb1wiIEBjaGFuZ2U9XCJvbkNoYW5nZTNcIj5cbiAgICAgIFRhZyAzXG4gICAgPC9lbC1jaGVjay10YWc+XG4gICAgPGVsLWNoZWNrLXRhZyA6Y2hlY2tlZD1cImNoZWNrZWQ0XCIgdHlwZT1cIndhcm5pbmdcIiBAY2hhbmdlPVwib25DaGFuZ2U0XCI+XG4gICAgICBUYWcgNFxuICAgIDwvZWwtY2hlY2stdGFnPlxuICAgIDxlbC1jaGVjay10YWcgOmNoZWNrZWQ9XCJjaGVja2VkNVwiIHR5cGU9XCJkYW5nZXJcIiBAY2hhbmdlPVwib25DaGFuZ2U1XCI+XG4gICAgICBUYWcgNVxuICAgIDwvZWwtY2hlY2stdGFnPlxuICAgIDxlbC1jaGVjay10YWdcbiAgICAgIDpjaGVja2VkPVwiY2hlY2tlZDZcIlxuICAgICAgZGlzYWJsZWRcbiAgICAgIHR5cGU9XCJzdWNjZXNzXCJcbiAgICAgIEBjaGFuZ2U9XCJvbkNoYW5nZTZcIlxuICAgID5cbiAgICAgIFRhZyA2XG4gICAgPC9lbC1jaGVjay10YWc+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgY2hlY2tlZCA9IHJlZihmYWxzZSlcbmNvbnN0IGNoZWNrZWQxID0gcmVmKHRydWUpXG5jb25zdCBjaGVja2VkMiA9IHJlZih0cnVlKVxuY29uc3QgY2hlY2tlZDMgPSByZWYodHJ1ZSlcbmNvbnN0IGNoZWNrZWQ0ID0gcmVmKHRydWUpXG5jb25zdCBjaGVja2VkNSA9IHJlZih0cnVlKVxuY29uc3QgY2hlY2tlZDYgPSByZWYodHJ1ZSlcblxuY29uc3Qgb25DaGFuZ2UgPSAoc3RhdHVzOiBib29sZWFuKSA9PiB7XG4gIGNoZWNrZWQudmFsdWUgPSBzdGF0dXNcbn1cblxuY29uc3Qgb25DaGFuZ2UxID0gKHN0YXR1czogYm9vbGVhbikgPT4ge1xuICBjaGVja2VkMS52YWx1ZSA9IHN0YXR1c1xufVxuXG5jb25zdCBvbkNoYW5nZTIgPSAoc3RhdHVzOiBib29sZWFuKSA9PiB7XG4gIGNoZWNrZWQyLnZhbHVlID0gc3RhdHVzXG59XG5cbmNvbnN0IG9uQ2hhbmdlMyA9IChzdGF0dXM6IGJvb2xlYW4pID0+IHtcbiAgY2hlY2tlZDMudmFsdWUgPSBzdGF0dXNcbn1cblxuY29uc3Qgb25DaGFuZ2U0ID0gKHN0YXR1czogYm9vbGVhbikgPT4ge1xuICBjaGVja2VkNC52YWx1ZSA9IHN0YXR1c1xufVxuXG5jb25zdCBvbkNoYW5nZTUgPSAoc3RhdHVzOiBib29sZWFuKSA9PiB7XG4gIGNoZWNrZWQ1LnZhbHVlID0gc3RhdHVzXG59XG5cbmNvbnN0IG9uQ2hhbmdlNiA9IChzdGF0dXM6IGJvb2xlYW4pID0+IHtcbiAgY2hlY2tlZDYudmFsdWUgPSBzdGF0dXNcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tag/checkable.vue)_

vue

```
<template>
  <div class="flex gap-2">
    <el-check-tag checked>Checked</el-check-tag>
    <el-check-tag :checked="checked" @change="onChange">Toggle me</el-check-tag>
    <el-check-tag disabled>Disabled</el-check-tag>
  </div>
  <div class="flex gap-2 mt-4">
    <el-check-tag :checked="checked1" type="primary" @change="onChange1">
      Tag 1
    </el-check-tag>
    <el-check-tag :checked="checked2" type="success" @change="onChange2">
      Tag 2
    </el-check-tag>
    <el-check-tag :checked="checked3" type="info" @change="onChange3">
      Tag 3
    </el-check-tag>
    <el-check-tag :checked="checked4" type="warning" @change="onChange4">
      Tag 4
    </el-check-tag>
    <el-check-tag :checked="checked5" type="danger" @change="onChange5">
      Tag 5
    </el-check-tag>
    <el-check-tag
      :checked="checked6"
      disabled
      type="success"
      @change="onChange6"
    >
      Tag 6
    </el-check-tag>
  </div>
</template>

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

const checked = ref(false)
const checked1 = ref(true)
const checked2 = ref(true)
const checked3 = ref(true)
const checked4 = ref(true)
const checked5 = ref(true)
const checked6 = ref(true)

const onChange = (status: boolean) => {
  checked.value = status
}

const onChange1 = (status: boolean) => {
  checked1.value = status
}

const onChange2 = (status: boolean) => {
  checked2.value = status
}

const onChange3 = (status: boolean) => {
  checked3.value = status
}

const onChange4 = (status: boolean) => {
  checked4.value = status
}

const onChange5 = (status: boolean) => {
  checked5.value = status
}

const onChange6 = (status: boolean) => {
  checked6.value = status
}
</script>
```

隐藏源代码

## Tag API [​](#tag-api)

### Tag Attributes [​](#tag-attributes)

| 属性名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| type | Tag 的类型 | `enum` | primary |
| closable | 是否可关闭 | `boolean` | false |
| disable-transitions | 是否禁用渐变动画 | `boolean` | false |
| hit | 是否有边框描边 | `boolean` | false |
| color | 背景色 | `string` | — |
| size | Tag 的尺寸 | `enum` | — |
| effect | Tag 的主题 | `enum` | light |
| round | Tag 是否为圆形 | `boolean` | false |

### Tag Events [​](#tag-events)

| 事件名 | 说明 | Type |
| --- | --- | --- |
| click | 点击 Tag 时触发的事件 | `Function` |
| close | 关闭 Tag 时触发的事件 | `Function` |

### Tag Slots [​](#tag-slots)

| 名称 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## CheckTag API [​](#checktag-api)

### CheckTag Attributes [​](#checktag-attributes)

| 属性名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| checked / v-model:checked | 是否选中 | `boolean` | false |
| disabled 2.8.2 | 是否禁用 | `boolean` | false |
| type 2.5.4 | CheckTag 类型 | `enum` | primary |

### CheckTag Events [​](#checktag-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | 点击 Check Tag 时触发的事件 | `Function` |

### CheckTag Slots [​](#checktag-slots)

| 名称 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/tag) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/tag.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/tag.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/20987775?v=4&size=64)](https://github.com/cbbfcd)[![](https://avatars.githubusercontent.com/u/20396642?v=4&size=64)](https://github.com/zmyjs)[![](https://avatars.githubusercontent.com/u/75007029?v=4&size=64)](https://github.com/yj-liuzepeng)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/48341368?v=4&size=64)](https://github.com/HaceraI)[![](https://avatars.githubusercontent.com/u/26403700?v=4&size=64)](https://github.com/blesstosam)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/49635988?v=4&size=64)](https://github.com/BgaSol)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)

[Virtualized Table 虚拟化表格](https://element-plus.org/zh-CN/component/table-v2)

[Timeline 时间线](https://element-plus.org/zh-CN/component/timeline)




---
## [data/timeline] Timeline 时间线
> 官方文档: https://element-plus.org/zh-CN/component/timeline.html

---

# Timeline 时间线 [​](#timeline-时间线)

更新日志待解决

2

可视化地呈现时间流信息。

## 基础用法 [​](#基础用法)

Timeline 可拆分成多个按照时间戳排列的活动， 时间戳是其区分于其他控件的重要特征， 使用时注意与 Steps 步骤条等区分。

-   Event start

    2018-04-15

-   Approved

    2018-04-13

-   Success

    2018-04-11

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGltZWxpbmU+XG4gICAgPGVsLXRpbWVsaW5lLWl0ZW1cbiAgICAgIHYtZm9yPVwiKGFjdGl2aXR5LCBpbmRleCkgaW4gYWN0aXZpdGllc1wiXG4gICAgICA6a2V5PVwiaW5kZXhcIlxuICAgICAgOnRpbWVzdGFtcD1cImFjdGl2aXR5LnRpbWVzdGFtcFwiXG4gICAgPlxuICAgICAge3sgYWN0aXZpdHkuY29udGVudCB9fVxuICAgIDwvZWwtdGltZWxpbmUtaXRlbT5cbiAgPC9lbC10aW1lbGluZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5jb25zdCBhY3Rpdml0aWVzID0gW1xuICB7XG4gICAgY29udGVudDogJ0V2ZW50IHN0YXJ0JyxcbiAgICB0aW1lc3RhbXA6ICcyMDE4LTA0LTE1JyxcbiAgfSxcbiAge1xuICAgIGNvbnRlbnQ6ICdBcHByb3ZlZCcsXG4gICAgdGltZXN0YW1wOiAnMjAxOC0wNC0xMycsXG4gIH0sXG4gIHtcbiAgICBjb250ZW50OiAnU3VjY2VzcycsXG4gICAgdGltZXN0YW1wOiAnMjAxOC0wNC0xMScsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/timeline/basic.vue)_

vue

```
<template>
  <el-timeline>
    <el-timeline-item
      v-for="(activity, index) in activities"
      :key="index"
      :timestamp="activity.timestamp"
    >
      {{ activity.content }}
    </el-timeline-item>
  </el-timeline>
</template>

<script lang="ts" setup>
const activities = [
  {
    content: 'Event start',
    timestamp: '2018-04-15',
  },
  {
    content: 'Approved',
    timestamp: '2018-04-13',
  },
  {
    content: 'Success',
    timestamp: '2018-04-11',
  },
]
</script>
```

隐藏源代码

## Mode 2.13.1 [​](#mode)

使用 `mode` 来控制时间线与内容的相对位置。

TIP

在 2.13.1 之后，`el-timeline` 显式设置了内边距样式。 如果您在项目中覆盖了 `ul` 标签的填充样式，请检查以确保布局正确。

startalternatealternate-reverseend

-   Event start

    2018-04-15

-   Approved

    2018-04-13

-   Success

    2018-04-11

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cIm1vZGVcIj5cbiAgICA8ZWwtcmFkaW8tYnV0dG9uIGxhYmVsPVwic3RhcnRcIiB2YWx1ZT1cInN0YXJ0XCIgLz5cbiAgICA8ZWwtcmFkaW8tYnV0dG9uIGxhYmVsPVwiYWx0ZXJuYXRlXCIgdmFsdWU9XCJhbHRlcm5hdGVcIiAvPlxuICAgIDxlbC1yYWRpby1idXR0b24gbGFiZWw9XCJhbHRlcm5hdGUtcmV2ZXJzZVwiIHZhbHVlPVwiYWx0ZXJuYXRlLXJldmVyc2VcIiAvPlxuICAgIDxlbC1yYWRpby1idXR0b24gbGFiZWw9XCJlbmRcIiB2YWx1ZT1cImVuZFwiIC8+XG4gIDwvZWwtcmFkaW8tZ3JvdXA+XG5cbiAgPGVsLXRpbWVsaW5lIGNsYXNzPVwibXQtNFwiIDptb2RlPVwibW9kZVwiPlxuICAgIDxlbC10aW1lbGluZS1pdGVtXG4gICAgICB2LWZvcj1cIihhY3Rpdml0eSwgaW5kZXgpIGluIGFjdGl2aXRpZXNcIlxuICAgICAgOmtleT1cImluZGV4XCJcbiAgICAgIDp0aW1lc3RhbXA9XCJhY3Rpdml0eS50aW1lc3RhbXBcIlxuICAgID5cbiAgICAgIHt7IGFjdGl2aXR5LmNvbnRlbnQgfX1cbiAgICA8L2VsLXRpbWVsaW5lLWl0ZW0+XG4gIDwvZWwtdGltZWxpbmU+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IFRpbWVsaW5lUHJvcHMgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGFjdGl2aXRpZXMgPSBbXG4gIHtcbiAgICBjb250ZW50OiAnRXZlbnQgc3RhcnQnLFxuICAgIHRpbWVzdGFtcDogJzIwMTgtMDQtMTUnLFxuICB9LFxuICB7XG4gICAgY29udGVudDogJ0FwcHJvdmVkJyxcbiAgICB0aW1lc3RhbXA6ICcyMDE4LTA0LTEzJyxcbiAgfSxcbiAge1xuICAgIGNvbnRlbnQ6ICdTdWNjZXNzJyxcbiAgICB0aW1lc3RhbXA6ICcyMDE4LTA0LTExJyxcbiAgfSxcbl1cblxuY29uc3QgbW9kZSA9IHJlZjxUaW1lbGluZVByb3BzWydtb2RlJ10+KCdzdGFydCcpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/timeline/mode.vue)_

vue

```
<template>
  <el-radio-group v-model="mode">
    <el-radio-button label="start" value="start" />
    <el-radio-button label="alternate" value="alternate" />
    <el-radio-button label="alternate-reverse" value="alternate-reverse" />
    <el-radio-button label="end" value="end" />
  </el-radio-group>

  <el-timeline class="mt-4" :mode="mode">
    <el-timeline-item
      v-for="(activity, index) in activities"
      :key="index"
      :timestamp="activity.timestamp"
    >
      {{ activity.content }}
    </el-timeline-item>
  </el-timeline>
</template>

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

import type { TimelineProps } from 'element-plus'

const activities = [
  {
    content: 'Event start',
    timestamp: '2018-04-15',
  },
  {
    content: 'Approved',
    timestamp: '2018-04-13',
  },
  {
    content: 'Success',
    timestamp: '2018-04-11',
  },
]

const mode = ref<TimelineProps['mode']>('start')
</script>
```

隐藏源代码

## ⾃定义节点样式 [​](#自定义节点样式)

可根据实际场景⾃定义节点尺⼨、颜⾊，或直接使⽤图标。

-   Custom icon

    2018-04-12 20:46

-   Custom color

    2018-04-03 20:46

-   Custom size

    2018-04-03 20:46

-   Custom hollow

    2018-04-03 20:46

-   Default node

    2018-04-03 20:46

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGltZWxpbmU+XG4gICAgPGVsLXRpbWVsaW5lLWl0ZW1cbiAgICAgIHYtZm9yPVwiKGFjdGl2aXR5LCBpbmRleCkgaW4gYWN0aXZpdGllc1wiXG4gICAgICA6a2V5PVwiaW5kZXhcIlxuICAgICAgOmljb249XCJhY3Rpdml0eS5pY29uXCJcbiAgICAgIDp0eXBlPVwiYWN0aXZpdHkudHlwZVwiXG4gICAgICA6Y29sb3I9XCJhY3Rpdml0eS5jb2xvclwiXG4gICAgICA6c2l6ZT1cImFjdGl2aXR5LnNpemVcIlxuICAgICAgOmhvbGxvdz1cImFjdGl2aXR5LmhvbGxvd1wiXG4gICAgICA6dGltZXN0YW1wPVwiYWN0aXZpdHkudGltZXN0YW1wXCJcbiAgICA+XG4gICAgICB7eyBhY3Rpdml0eS5jb250ZW50IH19XG4gICAgPC9lbC10aW1lbGluZS1pdGVtPlxuICA8L2VsLXRpbWVsaW5lPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IE1vcmVGaWxsZWQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuaW1wb3J0IHR5cGUgeyBUaW1lbGluZUl0ZW1Qcm9wcyB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuaW50ZXJmYWNlIEFjdGl2aXR5VHlwZSBleHRlbmRzIFBhcnRpYWw8VGltZWxpbmVJdGVtUHJvcHM+IHtcbiAgY29udGVudDogc3RyaW5nXG59XG5cbmNvbnN0IGFjdGl2aXRpZXM6IEFjdGl2aXR5VHlwZVtdID0gW1xuICB7XG4gICAgY29udGVudDogJ0N1c3RvbSBpY29uJyxcbiAgICB0aW1lc3RhbXA6ICcyMDE4LTA0LTEyIDIwOjQ2JyxcbiAgICBzaXplOiAnbGFyZ2UnLFxuICAgIHR5cGU6ICdwcmltYXJ5JyxcbiAgICBpY29uOiBNb3JlRmlsbGVkLFxuICB9LFxuICB7XG4gICAgY29udGVudDogJ0N1c3RvbSBjb2xvcicsXG4gICAgdGltZXN0YW1wOiAnMjAxOC0wNC0wMyAyMDo0NicsXG4gICAgY29sb3I6ICcjMGJiZDg3JyxcbiAgfSxcbiAge1xuICAgIGNvbnRlbnQ6ICdDdXN0b20gc2l6ZScsXG4gICAgdGltZXN0YW1wOiAnMjAxOC0wNC0wMyAyMDo0NicsXG4gICAgc2l6ZTogJ2xhcmdlJyxcbiAgfSxcbiAge1xuICAgIGNvbnRlbnQ6ICdDdXN0b20gaG9sbG93JyxcbiAgICB0aW1lc3RhbXA6ICcyMDE4LTA0LTAzIDIwOjQ2JyxcbiAgICB0eXBlOiAncHJpbWFyeScsXG4gICAgaG9sbG93OiB0cnVlLFxuICB9LFxuICB7XG4gICAgY29udGVudDogJ0RlZmF1bHQgbm9kZScsXG4gICAgdGltZXN0YW1wOiAnMjAxOC0wNC0wMyAyMDo0NicsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/timeline/custom-node.vue)_

vue

```
<template>
  <el-timeline>
    <el-timeline-item
      v-for="(activity, index) in activities"
      :key="index"
      :icon="activity.icon"
      :type="activity.type"
      :color="activity.color"
      :size="activity.size"
      :hollow="activity.hollow"
      :timestamp="activity.timestamp"
    >
      {{ activity.content }}
    </el-timeline-item>
  </el-timeline>
</template>

<script lang="ts" setup>
import { MoreFilled } from '@element-plus/icons-vue'

import type { TimelineItemProps } from 'element-plus'

interface ActivityType extends Partial<TimelineItemProps> {
  content: string
}

const activities: ActivityType[] = [
  {
    content: 'Custom icon',
    timestamp: '2018-04-12 20:46',
    size: 'large',
    type: 'primary',
    icon: MoreFilled,
  },
  {
    content: 'Custom color',
    timestamp: '2018-04-03 20:46',
    color: '#0bbd87',
  },
  {
    content: 'Custom size',
    timestamp: '2018-04-03 20:46',
    size: 'large',
  },
  {
    content: 'Custom hollow',
    timestamp: '2018-04-03 20:46',
    type: 'primary',
    hollow: true,
  },
  {
    content: 'Default node',
    timestamp: '2018-04-03 20:46',
  },
]
</script>
```

隐藏源代码

## ⾃定义时间戳 [​](#自定义时间戳)

当内容在垂直⽅向上过⾼时，可将时间戳置于内容之上。

-   2018/4/12

    #### Update Github template

    Tom committed 2018/4/12 20:46

-   2018/4/3

    #### Update Github template

    Tom committed 2018/4/3 20:46

-   2018/4/2

    #### Update Github template

    Tom committed 2018/4/2 20:46

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGltZWxpbmU+XG4gICAgPGVsLXRpbWVsaW5lLWl0ZW0gdGltZXN0YW1wPVwiMjAxOC80LzEyXCIgcGxhY2VtZW50PVwidG9wXCI+XG4gICAgICA8ZWwtY2FyZD5cbiAgICAgICAgPGg0PlVwZGF0ZSBHaXRodWIgdGVtcGxhdGU8L2g0PlxuICAgICAgICA8cD5Ub20gY29tbWl0dGVkIDIwMTgvNC8xMiAyMDo0NjwvcD5cbiAgICAgIDwvZWwtY2FyZD5cbiAgICA8L2VsLXRpbWVsaW5lLWl0ZW0+XG4gICAgPGVsLXRpbWVsaW5lLWl0ZW0gdGltZXN0YW1wPVwiMjAxOC80LzNcIiBwbGFjZW1lbnQ9XCJ0b3BcIj5cbiAgICAgIDxlbC1jYXJkPlxuICAgICAgICA8aDQ+VXBkYXRlIEdpdGh1YiB0ZW1wbGF0ZTwvaDQ+XG4gICAgICAgIDxwPlRvbSBjb21taXR0ZWQgMjAxOC80LzMgMjA6NDY8L3A+XG4gICAgICA8L2VsLWNhcmQ+XG4gICAgPC9lbC10aW1lbGluZS1pdGVtPlxuICAgIDxlbC10aW1lbGluZS1pdGVtIHRpbWVzdGFtcD1cIjIwMTgvNC8yXCIgcGxhY2VtZW50PVwidG9wXCI+XG4gICAgICA8ZWwtY2FyZD5cbiAgICAgICAgPGg0PlVwZGF0ZSBHaXRodWIgdGVtcGxhdGU8L2g0PlxuICAgICAgICA8cD5Ub20gY29tbWl0dGVkIDIwMTgvNC8yIDIwOjQ2PC9wPlxuICAgICAgPC9lbC1jYXJkPlxuICAgIDwvZWwtdGltZWxpbmUtaXRlbT5cbiAgPC9lbC10aW1lbGluZT5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/timeline/custom-timestamp.vue)_

vue

```
<template>
  <el-timeline>
    <el-timeline-item timestamp="2018/4/12" placement="top">
      <el-card>
        <h4>Update Github template</h4>
        <p>Tom committed 2018/4/12 20:46</p>
      </el-card>
    </el-timeline-item>
    <el-timeline-item timestamp="2018/4/3" placement="top">
      <el-card>
        <h4>Update Github template</h4>
        <p>Tom committed 2018/4/3 20:46</p>
      </el-card>
    </el-timeline-item>
    <el-timeline-item timestamp="2018/4/2" placement="top">
      <el-card>
        <h4>Update Github template</h4>
        <p>Tom committed 2018/4/2 20:46</p>
      </el-card>
    </el-timeline-item>
  </el-timeline>
</template>
```

隐藏源代码

## 垂直居中 [​](#垂直居中)

垂直居中样式的 Timeline-Item

-   2018/4/12

    #### Update Github template

    Tom committed 2018/4/12 20:46

-   2018/4/3

    #### Update Github template

    Tom committed 2018/4/3 20:46

-   2018/4/2

    Event start

-   2018/4/2

    Event end

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGltZWxpbmU+XG4gICAgPGVsLXRpbWVsaW5lLWl0ZW0gY2VudGVyIHRpbWVzdGFtcD1cIjIwMTgvNC8xMlwiIHBsYWNlbWVudD1cInRvcFwiPlxuICAgICAgPGVsLWNhcmQ+XG4gICAgICAgIDxoND5VcGRhdGUgR2l0aHViIHRlbXBsYXRlPC9oND5cbiAgICAgICAgPHA+VG9tIGNvbW1pdHRlZCAyMDE4LzQvMTIgMjA6NDY8L3A+XG4gICAgICA8L2VsLWNhcmQ+XG4gICAgPC9lbC10aW1lbGluZS1pdGVtPlxuICAgIDxlbC10aW1lbGluZS1pdGVtIHRpbWVzdGFtcD1cIjIwMTgvNC8zXCIgcGxhY2VtZW50PVwidG9wXCI+XG4gICAgICA8ZWwtY2FyZD5cbiAgICAgICAgPGg0PlVwZGF0ZSBHaXRodWIgdGVtcGxhdGU8L2g0PlxuICAgICAgICA8cD5Ub20gY29tbWl0dGVkIDIwMTgvNC8zIDIwOjQ2PC9wPlxuICAgICAgPC9lbC1jYXJkPlxuICAgIDwvZWwtdGltZWxpbmUtaXRlbT5cbiAgICA8ZWwtdGltZWxpbmUtaXRlbSBjZW50ZXIgdGltZXN0YW1wPVwiMjAxOC80LzJcIiBwbGFjZW1lbnQ9XCJ0b3BcIj5cbiAgICAgIEV2ZW50IHN0YXJ0XG4gICAgPC9lbC10aW1lbGluZS1pdGVtPlxuICAgIDxlbC10aW1lbGluZS1pdGVtIHRpbWVzdGFtcD1cIjIwMTgvNC8yXCIgcGxhY2VtZW50PVwidG9wXCI+XG4gICAgICBFdmVudCBlbmRcbiAgICA8L2VsLXRpbWVsaW5lLWl0ZW0+XG4gIDwvZWwtdGltZWxpbmU+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/timeline/center.vue)_

vue

```
<template>
  <el-timeline>
    <el-timeline-item center timestamp="2018/4/12" placement="top">
      <el-card>
        <h4>Update Github template</h4>
        <p>Tom committed 2018/4/12 20:46</p>
      </el-card>
    </el-timeline-item>
    <el-timeline-item timestamp="2018/4/3" placement="top">
      <el-card>
        <h4>Update Github template</h4>
        <p>Tom committed 2018/4/3 20:46</p>
      </el-card>
    </el-timeline-item>
    <el-timeline-item center timestamp="2018/4/2" placement="top">
      Event start
    </el-timeline-item>
    <el-timeline-item timestamp="2018/4/2" placement="top">
      Event end
    </el-timeline-item>
  </el-timeline>
</template>
```

隐藏源代码

## 反向 2.11.9 [​](#反向)

使用 reverse 属性来控制节点的顺序。

reverse

-   Success

    2018-04-11

-   Approved

    2018-04-13

-   Event start

    2018-04-15

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3dpdGNoIHYtbW9kZWw9XCJyZXZlcnNlXCIgYWN0aXZlLXRleHQ9XCJyZXZlcnNlXCIgLz5cblxuICA8ZWwtdGltZWxpbmUgY2xhc3M9XCJtdC0yXCIgOnJldmVyc2U9XCJyZXZlcnNlXCI+XG4gICAgPGVsLXRpbWVsaW5lLWl0ZW1cbiAgICAgIHYtZm9yPVwiKGFjdGl2aXR5LCBpbmRleCkgaW4gYWN0aXZpdGllc1wiXG4gICAgICA6a2V5PVwiaW5kZXhcIlxuICAgICAgOnRpbWVzdGFtcD1cImFjdGl2aXR5LnRpbWVzdGFtcFwiXG4gICAgPlxuICAgICAge3sgYWN0aXZpdHkuY29udGVudCB9fVxuICAgIDwvZWwtdGltZWxpbmUtaXRlbT5cbiAgPC9lbC10aW1lbGluZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHJldmVyc2UgPSByZWYodHJ1ZSlcbmNvbnN0IGFjdGl2aXRpZXMgPSBbXG4gIHtcbiAgICBjb250ZW50OiAnRXZlbnQgc3RhcnQnLFxuICAgIHRpbWVzdGFtcDogJzIwMTgtMDQtMTUnLFxuICB9LFxuICB7XG4gICAgY29udGVudDogJ0FwcHJvdmVkJyxcbiAgICB0aW1lc3RhbXA6ICcyMDE4LTA0LTEzJyxcbiAgfSxcbiAge1xuICAgIGNvbnRlbnQ6ICdTdWNjZXNzJyxcbiAgICB0aW1lc3RhbXA6ICcyMDE4LTA0LTExJyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/timeline/reverse.vue)_

vue

```
<template>
  <el-switch v-model="reverse" active-text="reverse" />

  <el-timeline class="mt-2" :reverse="reverse">
    <el-timeline-item
      v-for="(activity, index) in activities"
      :key="index"
      :timestamp="activity.timestamp"
    >
      {{ activity.content }}
    </el-timeline-item>
  </el-timeline>
</template>

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

const reverse = ref(true)
const activities = [
  {
    content: 'Event start',
    timestamp: '2018-04-15',
  },
  {
    content: 'Approved',
    timestamp: '2018-04-13',
  },
  {
    content: 'Success',
    timestamp: '2018-04-11',
  },
]
</script>
```

隐藏源代码

## Timeline API [​](#timeline-api)

### Timeline Attributes [​](#timeline-attributes)

| 插槽名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| reverse 2.11.9 | 是否逆序排序 | `boolean` | false |
| mode 2.13.1 | 时间线与内容的相对位置 | `enum` | start |

### Timeline Slots [​](#timeline-slots)

| 属性名 | 说明 | 子标签 |
| --- | --- | --- |
| default | timeline 组件的自定义默认内容 | Timeline-Item |

## Timeline-Item API [​](#timeline-item-api)

### Timeline-Item Attributes [​](#timeline-item-attributes)

| 插槽名 | 说明 | Type | Default |
| --- | --- | --- | --- |
| timestamp | 时间戳 | `string` | '' |
| hide-timestamp | 是否隐藏时间戳 | `boolean` | false |
| center | 是否垂直居中 | `boolean` | false |
| placement | 时间戳位置 | `enum` | bottom |
| type | 节点类型 | `enum` | '' |
| color | 节点颜色 | `string` | '' |
| size | 节点尺寸 | `enum` | normal |
| icon | 自定义图标 | `string` / `Component` | — |
| hollow | 是否空心点 | `boolean` | false |

### Timeline-Item Slots [​](#timeline-item-slots)

| 方法名 | 详情 |
| --- | --- |
| default | 自定义 timeline 项的默认内容 |
| dot | 为时间线项目自定义已定义的节点 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/timeline) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/timeline.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/timeline.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/5559812?v=4&size=64)](https://github.com/metanas)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)

[Tag 标签](https://element-plus.org/zh-CN/component/tag)

[Tour 漫游式引导](https://element-plus.org/zh-CN/component/tour)




---
## [data/tour] Tour 漫游式引导
> 官方文档: https://element-plus.org/zh-CN/component/tour.html

---

# Tour 漫游式引导 [​](#tour-漫游式引导)

更新日志待解决

0

用于分步引导用户了解产品功能的气泡组件。 用来引导用户并介绍产品

## 基础用法 [​](#基础用法)

最简单的用法。

Begin Tour

Upload

Save

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwib3BlbiA9IHRydWVcIj5CZWdpbiBUb3VyPC9lbC1idXR0b24+XG5cbiAgPGVsLWRpdmlkZXIgLz5cblxuICA8ZWwtc3BhY2U+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYxXCI+VXBsb2FkPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYyXCIgdHlwZT1cInByaW1hcnlcIj5TYXZlPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYzXCIgOmljb249XCJNb3JlRmlsbGVkXCIgLz5cbiAgPC9lbC1zcGFjZT5cblxuICA8ZWwtdG91ciB2LW1vZGVsPVwib3BlblwiPlxuICAgIDxlbC10b3VyLXN0ZXAgOnRhcmdldD1cInJlZjE/LiRlbFwiIHRpdGxlPVwiVXBsb2FkIEZpbGVcIj5cbiAgICAgIDxpbWdcbiAgICAgICAgc3R5bGU9XCJ3aWR0aDogMjQwcHhcIlxuICAgICAgICBzcmM9XCJodHRwczovL2VsZW1lbnQtcGx1cy5vcmcvaW1hZ2VzL2VsZW1lbnQtcGx1cy1sb2dvLnN2Z1wiXG4gICAgICAgIGFsdD1cInRvdXIucG5nXCJcbiAgICAgIC8+XG4gICAgICA8ZGl2PlB1dCB5b3UgZmlsZXMgaGVyZS48L2Rpdj5cbiAgICA8L2VsLXRvdXItc3RlcD5cbiAgICA8ZWwtdG91ci1zdGVwXG4gICAgICA6dGFyZ2V0PVwicmVmMj8uJGVsXCJcbiAgICAgIHRpdGxlPVwiU2F2ZVwiXG4gICAgICBkZXNjcmlwdGlvbj1cIlNhdmUgeW91ciBjaGFuZ2VzXCJcbiAgICAvPlxuICAgIDxlbC10b3VyLXN0ZXBcbiAgICAgIDp0YXJnZXQ9XCJyZWYzPy4kZWxcIlxuICAgICAgdGl0bGU9XCJPdGhlciBBY3Rpb25zXCJcbiAgICAgIGRlc2NyaXB0aW9uPVwiQ2xpY2sgdG8gc2VlIG90aGVyXCJcbiAgICAvPlxuICA8L2VsLXRvdXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgTW9yZUZpbGxlZCB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5pbXBvcnQgdHlwZSB7IEJ1dHRvbkluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCByZWYxID0gcmVmPEJ1dHRvbkluc3RhbmNlPigpXG5jb25zdCByZWYyID0gcmVmPEJ1dHRvbkluc3RhbmNlPigpXG5jb25zdCByZWYzID0gcmVmPEJ1dHRvbkluc3RhbmNlPigpXG5cbmNvbnN0IG9wZW4gPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tour/basic.vue)_

vue

```
<template>
  <el-button type="primary" @click="open = true">Begin Tour</el-button>

  <el-divider />

  <el-space>
    <el-button ref="ref1">Upload</el-button>
    <el-button ref="ref2" type="primary">Save</el-button>
    <el-button ref="ref3" :icon="MoreFilled" />
  </el-space>

  <el-tour v-model="open">
    <el-tour-step :target="ref1?.$el" title="Upload File">
      <img
        style="width: 240px"
        src="https://element-plus.org/images/element-plus-logo.svg"
        alt="tour.png"
      />
      <div>Put you files here.</div>
    </el-tour-step>
    <el-tour-step
      :target="ref2?.$el"
      title="Save"
      description="Save your changes"
    />
    <el-tour-step
      :target="ref3?.$el"
      title="Other Actions"
      description="Click to see other"
    />
  </el-tour>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { MoreFilled } from '@element-plus/icons-vue'

import type { ButtonInstance } from 'element-plus'

const ref1 = ref<ButtonInstance>()
const ref2 = ref<ButtonInstance>()
const ref3 = ref<ButtonInstance>()

const open = ref(false)
</script>
```

隐藏源代码

## 非模态 [​](#非模态)

使用`:mask="false"`可以将引导变为非模态， 同时为了强调引导本身，建议与 type="primary" 组合使用。

Begin Tour

Upload

Save

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwib3BlbiA9IHRydWVcIj5CZWdpbiBUb3VyPC9lbC1idXR0b24+XG5cbiAgPGVsLWRpdmlkZXIgLz5cblxuICA8ZWwtc3BhY2U+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYxXCI+VXBsb2FkPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYyXCIgdHlwZT1cInByaW1hcnlcIj5TYXZlPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYzXCIgOmljb249XCJNb3JlRmlsbGVkXCIgLz5cbiAgPC9lbC1zcGFjZT5cblxuICA8ZWwtdG91ciB2LW1vZGVsPVwib3BlblwiIHR5cGU9XCJwcmltYXJ5XCIgOm1hc2s9XCJmYWxzZVwiPlxuICAgIDxlbC10b3VyLXN0ZXBcbiAgICAgIDp0YXJnZXQ9XCJyZWYxPy4kZWxcIlxuICAgICAgdGl0bGU9XCJVcGxvYWQgRmlsZVwiXG4gICAgICBkZXNjcmlwdGlvbj1cIlB1dCB5b3UgZmlsZXMgaGVyZS5cIlxuICAgIC8+XG4gICAgPGVsLXRvdXItc3RlcFxuICAgICAgOnRhcmdldD1cInJlZjI/LiRlbFwiXG4gICAgICB0aXRsZT1cIlNhdmVcIlxuICAgICAgZGVzY3JpcHRpb249XCJTYXZlIHlvdXIgY2hhbmdlc1wiXG4gICAgLz5cbiAgICA8ZWwtdG91ci1zdGVwXG4gICAgICA6dGFyZ2V0PVwicmVmMz8uJGVsXCJcbiAgICAgIHRpdGxlPVwiT3RoZXIgQWN0aW9uc1wiXG4gICAgICBkZXNjcmlwdGlvbj1cIkNsaWNrIHRvIHNlZSBvdGhlclwiXG4gICAgLz5cbiAgPC9lbC10b3VyPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IE1vcmVGaWxsZWQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuaW1wb3J0IHR5cGUgeyBCdXR0b25JbnN0YW5jZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgcmVmMSA9IHJlZjxCdXR0b25JbnN0YW5jZT4oKVxuY29uc3QgcmVmMiA9IHJlZjxCdXR0b25JbnN0YW5jZT4oKVxuY29uc3QgcmVmMyA9IHJlZjxCdXR0b25JbnN0YW5jZT4oKVxuXG5jb25zdCBvcGVuID0gcmVmKGZhbHNlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tour/non-modal.vue)_

vue

```
<template>
  <el-button type="primary" @click="open = true">Begin Tour</el-button>

  <el-divider />

  <el-space>
    <el-button ref="ref1">Upload</el-button>
    <el-button ref="ref2" type="primary">Save</el-button>
    <el-button ref="ref3" :icon="MoreFilled" />
  </el-space>

  <el-tour v-model="open" type="primary" :mask="false">
    <el-tour-step
      :target="ref1?.$el"
      title="Upload File"
      description="Put you files here."
    />
    <el-tour-step
      :target="ref2?.$el"
      title="Save"
      description="Save your changes"
    />
    <el-tour-step
      :target="ref3?.$el"
      title="Other Actions"
      description="Click to see other"
    />
  </el-tour>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { MoreFilled } from '@element-plus/icons-vue'

import type { ButtonInstance } from 'element-plus'

const ref1 = ref<ButtonInstance>()
const ref2 = ref<ButtonInstance>()
const ref3 = ref<ButtonInstance>()

const open = ref(false)
</script>
```

隐藏源代码

## 位置 [​](#位置)

改变引导相对于目标的位置，共有 12 种位置可供选择。 当 `target` 为空时引导将会展示在正中央。

Begin Tour

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHJlZj1cImJ0blJlZlwiIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwib3BlbiA9IHRydWVcIj5cbiAgICBCZWdpbiBUb3VyXG4gIDwvZWwtYnV0dG9uPlxuXG4gIDxlbC10b3VyIHYtbW9kZWw9XCJvcGVuXCI+XG4gICAgPGVsLXRvdXItc3RlcFxuICAgICAgdGl0bGU9XCJDZW50ZXJcIlxuICAgICAgZGVzY3JpcHRpb249XCJEaXNwbGF5ZWQgaW4gdGhlIGNlbnRlciBvZiBzY3JlZW4uXCJcbiAgICAvPlxuICAgIDxlbC10b3VyLXN0ZXBcbiAgICAgIHRpdGxlPVwiUmlnaHRcIlxuICAgICAgZGVzY3JpcHRpb249XCJPbiB0aGUgcmlnaHQgb2YgdGFyZ2V0LlwiXG4gICAgICBwbGFjZW1lbnQ9XCJyaWdodFwiXG4gICAgICA6dGFyZ2V0PVwiYnRuUmVmPy4kZWxcIlxuICAgIC8+XG4gICAgPGVsLXRvdXItc3RlcFxuICAgICAgdGl0bGU9XCJUb3BcIlxuICAgICAgZGVzY3JpcHRpb249XCJPbiB0aGUgdG9wIG9mIHRhcmdldC5cIlxuICAgICAgcGxhY2VtZW50PVwidG9wXCJcbiAgICAgIDp0YXJnZXQ9XCJidG5SZWY/LiRlbFwiXG4gICAgLz5cbiAgPC9lbC10b3VyPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBCdXR0b25JbnN0YW5jZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgYnRuUmVmID0gcmVmPEJ1dHRvbkluc3RhbmNlPigpXG5cbmNvbnN0IG9wZW4gPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tour/placement.vue)_

vue

```
<template>
  <el-button ref="btnRef" type="primary" @click="open = true">
    Begin Tour
  </el-button>

  <el-tour v-model="open">
    <el-tour-step
      title="Center"
      description="Displayed in the center of screen."
    />
    <el-tour-step
      title="Right"
      description="On the right of target."
      placement="right"
      :target="btnRef?.$el"
    />
    <el-tour-step
      title="Top"
      description="On the top of target."
      placement="top"
      :target="btnRef?.$el"
    />
  </el-tour>
</template>

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

import type { ButtonInstance } from 'element-plus'

const btnRef = ref<ButtonInstance>()

const open = ref(false)
</script>
```

隐藏源代码

## 自定义遮罩样式 [​](#自定义遮罩样式)

自定义遮罩样式。

Begin Tour

Upload

Save

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwib3BlbiA9IHRydWVcIj5CZWdpbiBUb3VyPC9lbC1idXR0b24+XG5cbiAgPGVsLWRpdmlkZXIgLz5cblxuICA8ZWwtc3BhY2U+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYxXCI+VXBsb2FkPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYyXCIgdHlwZT1cInByaW1hcnlcIj5TYXZlPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYzXCIgOmljb249XCJNb3JlRmlsbGVkXCIgLz5cbiAgPC9lbC1zcGFjZT5cblxuICA8ZWwtdG91clxuICAgIHYtbW9kZWw9XCJvcGVuXCJcbiAgICA6bWFzaz1cIntcbiAgICAgIHN0eWxlOiB7XG4gICAgICAgIGJveFNoYWRvdzogJ2luc2V0IDAgMCAxNXB4ICMzMzMnLFxuICAgICAgfSxcbiAgICAgIGNvbG9yOiAncmdiYSg4MCwgMjU1LCAyNTUsIC40KScsXG4gICAgfVwiXG4gID5cbiAgICA8ZWwtdG91ci1zdGVwIDp0YXJnZXQ9XCJyZWYxPy4kZWxcIiB0aXRsZT1cIlVwbG9hZCBGaWxlXCI+XG4gICAgICA8aW1nXG4gICAgICAgIHNyYz1cImh0dHBzOi8vZWxlbWVudC1wbHVzLm9yZy9pbWFnZXMvZWxlbWVudC1wbHVzLWxvZ28uc3ZnXCJcbiAgICAgICAgYWx0PVwidG91ci5wbmdcIlxuICAgICAgLz5cbiAgICAgIDxkaXY+UHV0IHlvdSBmaWxlcyBoZXJlLjwvZGl2PlxuICAgIDwvZWwtdG91ci1zdGVwPlxuICAgIDxlbC10b3VyLXN0ZXBcbiAgICAgIDp0YXJnZXQ9XCJyZWYyPy4kZWxcIlxuICAgICAgdGl0bGU9XCJTYXZlXCJcbiAgICAgIGRlc2NyaXB0aW9uPVwiU2F2ZSB5b3VyIGNoYW5nZXNcIlxuICAgICAgOm1hc2s9XCJ7XG4gICAgICAgIHN0eWxlOiB7XG4gICAgICAgICAgYm94U2hhZG93OiAnaW5zZXQgMCAwIDE1cHggI2ZmZicsXG4gICAgICAgIH0sXG4gICAgICAgIGNvbG9yOiAncmdiYSg0MCwgMCwgMjU1LCAuNCknLFxuICAgICAgfVwiXG4gICAgLz5cbiAgICA8ZWwtdG91ci1zdGVwXG4gICAgICA6dGFyZ2V0PVwicmVmMz8uJGVsXCJcbiAgICAgIHRpdGxlPVwiT3RoZXIgQWN0aW9uc1wiXG4gICAgICBkZXNjcmlwdGlvbj1cIkNsaWNrIHRvIHNlZSBvdGhlclwiXG4gICAgICA6bWFzaz1cImZhbHNlXCJcbiAgICAvPlxuICA8L2VsLXRvdXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgTW9yZUZpbGxlZCB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5pbXBvcnQgdHlwZSB7IEJ1dHRvbkluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCByZWYxID0gcmVmPEJ1dHRvbkluc3RhbmNlPigpXG5jb25zdCByZWYyID0gcmVmPEJ1dHRvbkluc3RhbmNlPigpXG5jb25zdCByZWYzID0gcmVmPEJ1dHRvbkluc3RhbmNlPigpXG5cbmNvbnN0IG9wZW4gPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tour/mask.vue)_

vue

```
<template>
  <el-button type="primary" @click="open = true">Begin Tour</el-button>

  <el-divider />

  <el-space>
    <el-button ref="ref1">Upload</el-button>
    <el-button ref="ref2" type="primary">Save</el-button>
    <el-button ref="ref3" :icon="MoreFilled" />
  </el-space>

  <el-tour
    v-model="open"
    :mask="{
      style: {
        boxShadow: 'inset 0 0 15px #333',
      },
      color: 'rgba(80, 255, 255, .4)',
    }"
  >
    <el-tour-step :target="ref1?.$el" title="Upload File">
      <img
        src="https://element-plus.org/images/element-plus-logo.svg"
        alt="tour.png"
      />
      <div>Put you files here.</div>
    </el-tour-step>
    <el-tour-step
      :target="ref2?.$el"
      title="Save"
      description="Save your changes"
      :mask="{
        style: {
          boxShadow: 'inset 0 0 15px #fff',
        },
        color: 'rgba(40, 0, 255, .4)',
      }"
    />
    <el-tour-step
      :target="ref3?.$el"
      title="Other Actions"
      description="Click to see other"
      :mask="false"
    />
  </el-tour>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { MoreFilled } from '@element-plus/icons-vue'

import type { ButtonInstance } from 'element-plus'

const ref1 = ref<ButtonInstance>()
const ref2 = ref<ButtonInstance>()
const ref3 = ref<ButtonInstance>()

const open = ref(false)
</script>
```

隐藏源代码

## 自定义指示器 [​](#自定义指示器)

自定义指示器。

Begin Tour

Upload

Save

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwib3BlbiA9IHRydWVcIj5CZWdpbiBUb3VyPC9lbC1idXR0b24+XG5cbiAgPGVsLWRpdmlkZXIgLz5cblxuICA8ZWwtc3BhY2U+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYxXCI+VXBsb2FkPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYyXCIgdHlwZT1cInByaW1hcnlcIj5TYXZlPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiByZWY9XCJyZWYzXCIgOmljb249XCJNb3JlRmlsbGVkXCIgLz5cbiAgPC9lbC1zcGFjZT5cblxuICA8ZWwtdG91ciB2LW1vZGVsPVwib3BlblwiPlxuICAgIDxlbC10b3VyLXN0ZXBcbiAgICAgIDp0YXJnZXQ9XCJyZWYxPy4kZWxcIlxuICAgICAgdGl0bGU9XCJVcGxvYWQgRmlsZVwiXG4gICAgICBkZXNjcmlwdGlvbj1cIlB1dCB5b3UgZmlsZXMgaGVyZS5cIlxuICAgIC8+XG4gICAgPGVsLXRvdXItc3RlcFxuICAgICAgOnRhcmdldD1cInJlZjI/LiRlbFwiXG4gICAgICB0aXRsZT1cIlNhdmVcIlxuICAgICAgZGVzY3JpcHRpb249XCJTYXZlIHlvdXIgY2hhbmdlc1wiXG4gICAgLz5cbiAgICA8ZWwtdG91ci1zdGVwXG4gICAgICA6dGFyZ2V0PVwicmVmMz8uJGVsXCJcbiAgICAgIHRpdGxlPVwiT3RoZXIgQWN0aW9uc1wiXG4gICAgICBkZXNjcmlwdGlvbj1cIkNsaWNrIHRvIHNlZSBvdGhlclwiXG4gICAgLz5cbiAgICA8dGVtcGxhdGUgI2luZGljYXRvcnM9XCJ7IGN1cnJlbnQsIHRvdGFsIH1cIj5cbiAgICAgIDxzcGFuPnt7IGN1cnJlbnQgKyAxIH19IC8ge3sgdG90YWwgfX08L3NwYW4+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC10b3VyPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IE1vcmVGaWxsZWQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuaW1wb3J0IHR5cGUgeyBCdXR0b25JbnN0YW5jZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgcmVmMSA9IHJlZjxCdXR0b25JbnN0YW5jZT4oKVxuY29uc3QgcmVmMiA9IHJlZjxCdXR0b25JbnN0YW5jZT4oKVxuY29uc3QgcmVmMyA9IHJlZjxCdXR0b25JbnN0YW5jZT4oKVxuXG5jb25zdCBvcGVuID0gcmVmKGZhbHNlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tour/indicator.vue)_

vue

```
<template>
  <el-button type="primary" @click="open = true">Begin Tour</el-button>

  <el-divider />

  <el-space>
    <el-button ref="ref1">Upload</el-button>
    <el-button ref="ref2" type="primary">Save</el-button>
    <el-button ref="ref3" :icon="MoreFilled" />
  </el-space>

  <el-tour v-model="open">
    <el-tour-step
      :target="ref1?.$el"
      title="Upload File"
      description="Put you files here."
    />
    <el-tour-step
      :target="ref2?.$el"
      title="Save"
      description="Save your changes"
    />
    <el-tour-step
      :target="ref3?.$el"
      title="Other Actions"
      description="Click to see other"
    />
    <template #indicators="{ current, total }">
      <span>{{ current + 1 }} / {{ total }}</span>
    </template>
  </el-tour>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { MoreFilled } from '@element-plus/icons-vue'

import type { ButtonInstance } from 'element-plus'

const ref1 = ref<ButtonInstance>()
const ref2 = ref<ButtonInstance>()
const ref3 = ref<ButtonInstance>()

const open = ref(false)
</script>
```

隐藏源代码

## 目标 [​](#目标)

可以传入目标的各种类型的参数。 自2.5.2以来支持字符串和函数类型。

Begin Tour

Upload

Save

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwib3BlbiA9IHRydWVcIj5CZWdpbiBUb3VyPC9lbC1idXR0b24+XG5cbiAgPGVsLWRpdmlkZXIgLz5cblxuICA8ZWwtc3BhY2U+XG4gICAgPGVsLWJ1dHRvbiBpZD1cImJ0bjFcIj5VcGxvYWQ8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGlkPVwiYnRuMlwiIHR5cGU9XCJwcmltYXJ5XCI+U2F2ZTwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gcmVmPVwiYnRuUmVmXCIgOmljb249XCJNb3JlRmlsbGVkXCIgLz5cbiAgPC9lbC1zcGFjZT5cblxuICA8ZWwtdG91ciB2LW1vZGVsPVwib3BlblwiPlxuICAgIDxlbC10b3VyLXN0ZXBcbiAgICAgIHRhcmdldD1cIiNidG4xXCJcbiAgICAgIHRpdGxlPVwiVXBsb2FkIEZpbGVcIlxuICAgICAgZGVzY3JpcHRpb249XCJQdXQgeW91IGZpbGVzIGhlcmUuXCJcbiAgICAvPlxuICAgIDxlbC10b3VyLXN0ZXAgOnRhcmdldD1cImVsXCIgdGl0bGU9XCJTYXZlXCIgZGVzY3JpcHRpb249XCJTYXZlIHlvdXIgY2hhbmdlc1wiIC8+XG4gICAgPGVsLXRvdXItc3RlcFxuICAgICAgOnRhcmdldD1cImJ0blJlZj8uJGVsXCJcbiAgICAgIHRpdGxlPVwiT3RoZXIgQWN0aW9uc1wiXG4gICAgICBkZXNjcmlwdGlvbj1cIkNsaWNrIHRvIHNlZSBvdGhlclwiXG4gICAgLz5cbiAgPC9lbC10b3VyPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IE1vcmVGaWxsZWQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuaW1wb3J0IHR5cGUgeyBCdXR0b25JbnN0YW5jZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgZWwgPSAoKSA9PiBkb2N1bWVudC5xdWVyeVNlbGVjdG9yPEhUTUxFbGVtZW50PignI2J0bjInKVxuY29uc3QgYnRuUmVmID0gcmVmPEJ1dHRvbkluc3RhbmNlPigpXG5cbmNvbnN0IG9wZW4gPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tour/target.vue)_

vue

```
<template>
  <el-button type="primary" @click="open = true">Begin Tour</el-button>

  <el-divider />

  <el-space>
    <el-button id="btn1">Upload</el-button>
    <el-button id="btn2" type="primary">Save</el-button>
    <el-button ref="btnRef" :icon="MoreFilled" />
  </el-space>

  <el-tour v-model="open">
    <el-tour-step
      target="#btn1"
      title="Upload File"
      description="Put you files here."
    />
    <el-tour-step :target="el" title="Save" description="Save your changes" />
    <el-tour-step
      :target="btnRef?.$el"
      title="Other Actions"
      description="Click to see other"
    />
  </el-tour>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { MoreFilled } from '@element-plus/icons-vue'

import type { ButtonInstance } from 'element-plus'

const el = () => document.querySelector<HTMLElement>('#btn2')
const btnRef = ref<ButtonInstance>()

const open = ref(false)
</script>
```

隐藏源代码

## Tour API [​](#tour-api)

TIP

tour-step 组件上相同名称配置的优先级更高。

### Tour Attributes [​](#tour-attributes)

| 属性 | 描述 | 类型 | 默认值 |
| --- | --- | --- | --- |
| append-to | 挂载到哪个 DOM 元素 | `CSSSelector` / `HTMLElement` | `body` |
| show-arrow | 是否显示箭头 | `boolean` | true |
| placement | 引导卡片相对于目标元素的位置 | `enum` | `bottom` |
| content-style | 为content自定义样式 | `CSSProperties` | — |
| mask | 是否启用遮罩，通过自定义属性改变遮罩样式以及填充的颜色 | `boolean` | `Object` | `true` |
| gap | 遮罩和目标之间的透明的间距 | `TourGap` | `Object` |
| type | 类型，影响底色与文字颜色 | `default` | `primary` | `default` |
| model-value / v-model | 打开引导 | `boolean` | `false` |
| current / v-model:current | 当前值 | `number` | `0` |
| scroll-into-view-options | 是否支持当前元素滚动到视窗内，也可传入配置指定滚动视窗的相关参数 | `boolean` | `ScrollIntoViewOptions` | `Object` |
| z-index | Tour 的层级 | `number` | `2001` |
| show-close | 是否显示关闭按钮 | `boolean` | `true` |
| close-icon | 自定义关闭图标，默认Close | `string` | `Component` | — |
| close-on-press-escape | 是否可以通过按下 ESC 关闭引导 | `boolean` | `true` |
| target-area-clickable | 启用蒙层时，target 元素区域是否可以点击。 | `boolean` | `true` |

### Tour slots [​](#tour-slots)

| 插槽名 | 说明 | 类型 |
| --- | --- | --- |
| default | tourStep 组件列表 | — |
| indicators | 自定义指示器 | `object` |

### Tour events [​](#tour-events)

| 事件名 | 描述 | 类型 |
| --- | --- | --- |
| close | 关闭引导时的回调函数 | `Function` |
| finish | 引导完成时的回调 | `Function` |
| change | 步骤改变时的回调 | `Function` |

## TourStep API [​](#tourstep-api)

### TourStep Attributes [​](#tourstep-attributes)

| 属性 | 描述 | 事件参数 | 默认值 |
| --- | --- | --- | --- |
| target | 获取引导卡片指向的元素， 为空时居中于屏幕。 自2.5.2以来支持字符串和函数类型。 字符串类型是文档.querySelector的选择器。 | `HTMLElement` | `string` | `Function` | — |
| show-arrow | 是否显示箭头 | `boolean` | — |
| title | title | `string` | — |
| description | description | `string` | — |
| placement | 引导卡片相对于目标元素的位置 | `enum` | `bottom` |
| content-style | 为content自定义样式 | `CSSProperties` | — |
| mask | 是否启用蒙层，也可传入配置改变蒙层样式和填充色 | `boolean` | `Object` | — |
| type | 类型，影响底色与文字颜色 | `default` | `primary` | `default` |
| next-button-props | “下一步”按钮的属性 | `Object` | — |
| prev-button-props | “上一步”按钮的属性 | `Object` | — |
| scroll-into-view-options | 是否支持当前元素滚动到视窗内，也可传入配置指定滚动视窗的相关参数，默认跟随 Tour 的 `scrollIntoViewOptions` 属性 | `boolean` | `ScrollIntoViewOptions` | — |
| show-close | 是否显示关闭按钮 | `boolean` | — |
| close-icon | 自定义关闭图标，默认Close | `string` | `Component` | — |

### TourStep slots [​](#tourstep-slots)

| 插槽名 | 描述 |
| --- | --- |
| default | 自定义描述 |
| header | 自定义 header 内容 |

### TourStep events [​](#tourstep-events)

| 事件名 | 描述 | 参数 |
| --- | --- | --- |
| close | 关闭引导时的回调函数 | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/tour) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/tour.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/tour.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/27912232?v=4&size=64)](https://github.com/Fuphoenixes)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/35091020?v=4&size=64)](https://github.com/zzh948498)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)

[Timeline 时间线](https://element-plus.org/zh-CN/component/timeline)

[Tree 树形控件](https://element-plus.org/zh-CN/component/tree)




---
## [data/tree] Tree 树形控件
> 官方文档: https://element-plus.org/zh-CN/component/tree.html

---

# Tree 树形控件 [​](#tree-树形控件)

更新日志待解决

77

用清晰的层级结构展示信息，可展开或折叠。

## 基础用法 [​](#基础用法)

基础的树形结构展示

Level one 1

Level one 2

Level one 3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZVxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6cHJvcHM9XCJkZWZhdWx0UHJvcHNcIlxuICAgIEBub2RlLWNsaWNrPVwiaGFuZGxlTm9kZUNsaWNrXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbnRlcmZhY2UgVHJlZSB7XG4gIGxhYmVsOiBzdHJpbmdcbiAgY2hpbGRyZW4/OiBUcmVlW11cbn1cblxuY29uc3QgaGFuZGxlTm9kZUNsaWNrID0gKGRhdGE6IFRyZWUpID0+IHtcbiAgY29uc29sZS5sb2coZGF0YSlcbn1cblxuY29uc3QgZGF0YTogVHJlZVtdID0gW1xuICB7XG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMS0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDEtMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMicsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDItMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0yJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDItMi0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMycsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0yJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMi0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuXG5jb25zdCBkZWZhdWx0UHJvcHMgPSB7XG4gIGNoaWxkcmVuOiAnY2hpbGRyZW4nLFxuICBsYWJlbDogJ2xhYmVsJyxcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/basic.vue)_

vue

```
<template>
  <el-tree
    style="max-width: 600px"
    :data="data"
    :props="defaultProps"
    @node-click="handleNodeClick"
  />
</template>

<script lang="ts" setup>
interface Tree {
  label: string
  children?: Tree[]
}

const handleNodeClick = (data: Tree) => {
  console.log(data)
}

const data: Tree[] = [
  {
    label: 'Level one 1',
    children: [
      {
        label: 'Level two 1-1',
        children: [
          {
            label: 'Level three 1-1-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Level one 2',
    children: [
      {
        label: 'Level two 2-1',
        children: [
          {
            label: 'Level three 2-1-1',
          },
        ],
      },
      {
        label: 'Level two 2-2',
        children: [
          {
            label: 'Level three 2-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Level one 3',
    children: [
      {
        label: 'Level two 3-1',
        children: [
          {
            label: 'Level three 3-1-1',
          },
        ],
      },
      {
        label: 'Level two 3-2',
        children: [
          {
            label: 'Level three 3-2-1',
          },
        ],
      },
    ],
  },
]

const defaultProps = {
  children: 'children',
  label: 'label',
}
</script>
```

隐藏源代码

## 可选择 [​](#可选择)

适用于需要选择层级时使用。

本例还展示了动态加载节点数据的方法。

Root1

Root2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZVxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOnByb3BzPVwicHJvcHNcIlxuICAgIDpsb2FkPVwibG9hZE5vZGVcIlxuICAgIGxhenlcbiAgICBzaG93LWNoZWNrYm94XG4gICAgQGNoZWNrLWNoYW5nZT1cImhhbmRsZUNoZWNrQ2hhbmdlXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgdHlwZSB7IExvYWRGdW5jdGlvbiB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuaW50ZXJmYWNlIFRyZWUge1xuICBuYW1lOiBzdHJpbmdcbn1cblxubGV0IGNvdW50ID0gMVxuY29uc3QgcHJvcHMgPSB7XG4gIGxhYmVsOiAnbmFtZScsXG4gIGNoaWxkcmVuOiAnem9uZXMnLFxufVxuXG5jb25zdCBoYW5kbGVDaGVja0NoYW5nZSA9IChcbiAgZGF0YTogVHJlZSxcbiAgY2hlY2tlZDogYm9vbGVhbixcbiAgaW5kZXRlcm1pbmF0ZTogYm9vbGVhblxuKSA9PiB7XG4gIGNvbnNvbGUubG9nKGRhdGEsIGNoZWNrZWQsIGluZGV0ZXJtaW5hdGUpXG59XG5cbmNvbnN0IGxvYWROb2RlOiBMb2FkRnVuY3Rpb24gPSAobm9kZSwgcmVzb2x2ZSkgPT4ge1xuICBpZiAobm9kZS5sZXZlbCA9PT0gMCkge1xuICAgIHJldHVybiByZXNvbHZlKFt7IG5hbWU6ICdSb290MScgfSwgeyBuYW1lOiAnUm9vdDInIH1dKVxuICB9XG4gIGlmIChub2RlLmxldmVsID4gMykgcmV0dXJuIHJlc29sdmUoW10pXG5cbiAgbGV0IGhhc0NoaWxkID0gZmFsc2VcbiAgaWYgKG5vZGUuZGF0YS5uYW1lID09PSAncmVnaW9uMScpIHtcbiAgICBoYXNDaGlsZCA9IHRydWVcbiAgfSBlbHNlIGlmIChub2RlLmRhdGEubmFtZSA9PT0gJ3JlZ2lvbjInKSB7XG4gICAgaGFzQ2hpbGQgPSBmYWxzZVxuICB9IGVsc2Uge1xuICAgIGhhc0NoaWxkID0gTWF0aC5yYW5kb20oKSA+IDAuNVxuICB9XG5cbiAgc2V0VGltZW91dCgoKSA9PiB7XG4gICAgbGV0IGRhdGE6IFRyZWVbXSA9IFtdXG4gICAgaWYgKGhhc0NoaWxkKSB7XG4gICAgICBkYXRhID0gW1xuICAgICAgICB7XG4gICAgICAgICAgbmFtZTogYHpvbmUke2NvdW50Kyt9YCxcbiAgICAgICAgfSxcbiAgICAgICAge1xuICAgICAgICAgIG5hbWU6IGB6b25lJHtjb3VudCsrfWAsXG4gICAgICAgIH0sXG4gICAgICBdXG4gICAgfSBlbHNlIHtcbiAgICAgIGRhdGEgPSBbXVxuICAgIH1cblxuICAgIHJlc29sdmUoZGF0YSlcbiAgfSwgNTAwKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/selectable.vue)_

vue

```
<template>
  <el-tree
    style="max-width: 600px"
    :props="props"
    :load="loadNode"
    lazy
    show-checkbox
    @check-change="handleCheckChange"
  />
</template>

<script lang="ts" setup>
import type { LoadFunction } from 'element-plus'

interface Tree {
  name: string
}

let count = 1
const props = {
  label: 'name',
  children: 'zones',
}

const handleCheckChange = (
  data: Tree,
  checked: boolean,
  indeterminate: boolean
) => {
  console.log(data, checked, indeterminate)
}

const loadNode: LoadFunction = (node, resolve) => {
  if (node.level === 0) {
    return resolve([{ name: 'Root1' }, { name: 'Root2' }])
  }
  if (node.level > 3) return resolve([])

  let hasChild = false
  if (node.data.name === 'region1') {
    hasChild = true
  } else if (node.data.name === 'region2') {
    hasChild = false
  } else {
    hasChild = Math.random() > 0.5
  }

  setTimeout(() => {
    let data: Tree[] = []
    if (hasChild) {
      data = [
        {
          name: `zone${count++}`,
        },
        {
          name: `zone${count++}`,
        },
      ]
    } else {
      data = []
    }

    resolve(data)
  }, 500)
}
</script>
```

隐藏源代码

WARNING

在使用 show-checkbox 时，因为 `check-on-click-leaf` 默认值为 true， 最后一个树节点可以通过点击节点进行勾选。

## 懒加载自定义叶子节点 [​](#懒加载自定义叶子节点)

由于在点击节点时才进行该层数据的获取，默认情况下 Tree 无法预知某个节点是否为叶子节点， 所以会为每个节点添加一个下拉按钮，如果节点没有下层数据，则点击后下拉按钮会消失。 同时，你也可以提前告知 Tree 某个节点是否为叶子节点，从而避免在叶子节点前渲染下拉按钮。

region

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZVxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOnByb3BzPVwicHJvcHNcIlxuICAgIDpsb2FkPVwibG9hZE5vZGVcIlxuICAgIGxhenlcbiAgICBzaG93LWNoZWNrYm94XG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHR5cGUgeyBMb2FkRnVuY3Rpb24gfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmludGVyZmFjZSBUcmVlIHtcbiAgbmFtZTogc3RyaW5nXG4gIGxlYWY/OiBib29sZWFuXG59XG5cbmNvbnN0IHByb3BzID0ge1xuICBsYWJlbDogJ25hbWUnLFxuICBjaGlsZHJlbjogJ3pvbmVzJyxcbiAgaXNMZWFmOiAnbGVhZicsXG59XG5cbmNvbnN0IGxvYWROb2RlOiBMb2FkRnVuY3Rpb24gPSAobm9kZSwgcmVzb2x2ZSkgPT4ge1xuICBpZiAobm9kZS5sZXZlbCA9PT0gMCkge1xuICAgIHJldHVybiByZXNvbHZlKFt7IG5hbWU6ICdyZWdpb24nIH1dKVxuICB9XG4gIGlmIChub2RlLmxldmVsID4gMSkgcmV0dXJuIHJlc29sdmUoW10pXG5cbiAgc2V0VGltZW91dCgoKSA9PiB7XG4gICAgY29uc3QgZGF0YTogVHJlZVtdID0gW1xuICAgICAge1xuICAgICAgICBuYW1lOiAnbGVhZicsXG4gICAgICAgIGxlYWY6IHRydWUsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBuYW1lOiAnem9uZScsXG4gICAgICB9LFxuICAgIF1cblxuICAgIHJlc29sdmUoZGF0YSlcbiAgfSwgNTAwKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/custom-leaf.vue)_

vue

```
<template>
  <el-tree
    style="max-width: 600px"
    :props="props"
    :load="loadNode"
    lazy
    show-checkbox
  />
</template>

<script lang="ts" setup>
import type { LoadFunction } from 'element-plus'

interface Tree {
  name: string
  leaf?: boolean
}

const props = {
  label: 'name',
  children: 'zones',
  isLeaf: 'leaf',
}

const loadNode: LoadFunction = (node, resolve) => {
  if (node.level === 0) {
    return resolve([{ name: 'region' }])
  }
  if (node.level > 1) return resolve([])

  setTimeout(() => {
    const data: Tree[] = [
      {
        name: 'leaf',
        leaf: true,
      },
      {
        name: 'zone',
      },
    ]

    resolve(data)
  }, 500)
}
</script>
```

隐藏源代码

## 多次懒加载 2.6.3 [​](#多次懒加载)

加载远程节点数据时，懒加载有时可能失败。 在这种情况下，您可以调用 reject 以保持节点状态，并允许远程加载继续。

region

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZSBzdHlsZT1cIm1heC13aWR0aDogNjAwcHhcIiA6cHJvcHM9XCJwcm9wc1wiIDpsb2FkPVwibG9hZE5vZGVcIiBsYXp5IC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHR5cGUgeyBMb2FkRnVuY3Rpb24gfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHByb3BzID0ge1xuICBsYWJlbDogJ25hbWUnLFxuICBjaGlsZHJlbjogJ3pvbmVzJyxcbiAgaXNMZWFmOiAnbGVhZicsXG59XG5cbmxldCB0aW1lID0gMFxuY29uc3QgbG9hZE5vZGU6IExvYWRGdW5jdGlvbiA9IChub2RlLCByZXNvbHZlLCByZWplY3QpID0+IHtcbiAgaWYgKG5vZGUubGV2ZWwgPT09IDApIHtcbiAgICByZXR1cm4gcmVzb2x2ZShbeyBuYW1lOiAncmVnaW9uJyB9XSlcbiAgfVxuICB0aW1lKytcbiAgaWYgKG5vZGUubGV2ZWwgPj0gMSkge1xuICAgIHNldFRpbWVvdXQoKCkgPT4ge1xuICAgICAgaWYgKHRpbWUgPiAzKSB7XG4gICAgICAgIHJldHVybiByZXNvbHZlKFtcbiAgICAgICAgICB7IG5hbWU6ICd6b25lMScsIGxlYWY6IHRydWUgfSxcbiAgICAgICAgICB7IG5hbWU6ICd6b25lMicsIGxlYWY6IHRydWUgfSxcbiAgICAgICAgICB7IG5hbWU6ICd6b25lMycsIGxlYWY6IHRydWUgfSxcbiAgICAgICAgXSlcbiAgICAgIH0gZWxzZSB7XG4gICAgICAgIHJldHVybiByZWplY3QoKVxuICAgICAgfVxuICAgIH0sIDMwMDApXG4gIH1cbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/multiple-times-load.vue)_

vue

```
<template>
  <el-tree style="max-width: 600px" :props="props" :load="loadNode" lazy />
</template>

<script lang="ts" setup>
import type { LoadFunction } from 'element-plus'

const props = {
  label: 'name',
  children: 'zones',
  isLeaf: 'leaf',
}

let time = 0
const loadNode: LoadFunction = (node, resolve, reject) => {
  if (node.level === 0) {
    return resolve([{ name: 'region' }])
  }
  time++
  if (node.level >= 1) {
    setTimeout(() => {
      if (time > 3) {
        return resolve([
          { name: 'zone1', leaf: true },
          { name: 'zone2', leaf: true },
          { name: 'zone3', leaf: true },
        ])
      } else {
        return reject()
      }
    }, 3000)
  }
}
</script>
```

隐藏源代码

## 禁用复选框 [​](#禁用复选框)

节点的复选框可以设置为禁用。

在示例中，通过 disabled 设置禁用状态。 相应的复选框已禁用，不能点击。

Level one 1

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZVxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6cHJvcHM9XCJkZWZhdWx0UHJvcHNcIlxuICAgIHNob3ctY2hlY2tib3hcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5jb25zdCBkZWZhdWx0UHJvcHMgPSB7XG4gIGNoaWxkcmVuOiAnY2hpbGRyZW4nLFxuICBsYWJlbDogJ2xhYmVsJyxcbiAgZGlzYWJsZWQ6ICdkaXNhYmxlZCcsXG59XG5cbmNvbnN0IGRhdGEgPSBbXG4gIHtcbiAgICBpZDogMSxcbiAgICBsYWJlbDogJ0xldmVsIG9uZSAxJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICBpZDogMyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBpZDogNCxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMy0xLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgaWQ6IDUsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMS0yJyxcbiAgICAgICAgICAgIGRpc2FibGVkOiB0cnVlLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogMixcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0yJyxcbiAgICAgICAgZGlzYWJsZWQ6IHRydWUsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgaWQ6IDYsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMi0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIGlkOiA3LFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAzLTItMicsXG4gICAgICAgICAgICBkaXNhYmxlZDogdHJ1ZSxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/disabled.vue)_

vue

```
<template>
  <el-tree
    style="max-width: 600px"
    :data="data"
    :props="defaultProps"
    show-checkbox
  />
</template>

<script lang="ts" setup>
const defaultProps = {
  children: 'children',
  label: 'label',
  disabled: 'disabled',
}

const data = [
  {
    id: 1,
    label: 'Level one 1',
    children: [
      {
        id: 3,
        label: 'Level two 2-1',
        children: [
          {
            id: 4,
            label: 'Level three 3-1-1',
          },
          {
            id: 5,
            label: 'Level three 3-1-2',
            disabled: true,
          },
        ],
      },
      {
        id: 2,
        label: 'Level two 2-2',
        disabled: true,
        children: [
          {
            id: 6,
            label: 'Level three 3-2-1',
          },
          {
            id: 7,
            label: 'Level three 3-2-2',
            disabled: true,
          },
        ],
      },
    ],
  },
]
</script>
```

隐藏源代码

## 默认展开以及默认选中 [​](#默认展开以及默认选中)

树节点可以在初始化阶段被设置为展开和选中。

分别通过 `default-expanded-keys` 和 `default-checked-keys` 设置默认展开和默认选中的节点。 需要注意的是，此时必须设置 `node-key`， 其值为节点数据中的一个字段名，该字段在整棵树中是唯一的。

Level one 1

Level one 2

Level two 2-1

Level two 2-2

Level one 3

Level two 3-1

Level two 3-2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZVxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICBzaG93LWNoZWNrYm94XG4gICAgbm9kZS1rZXk9XCJpZFwiXG4gICAgOmRlZmF1bHQtZXhwYW5kZWQta2V5cz1cIlsyLCAzXVwiXG4gICAgOmRlZmF1bHQtY2hlY2tlZC1rZXlzPVwiWzVdXCJcbiAgICA6cHJvcHM9XCJkZWZhdWx0UHJvcHNcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmNvbnN0IGRlZmF1bHRQcm9wcyA9IHtcbiAgY2hpbGRyZW46ICdjaGlsZHJlbicsXG4gIGxhYmVsOiAnbGFiZWwnLFxufVxuY29uc3QgZGF0YSA9IFtcbiAge1xuICAgIGlkOiAxLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDEnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIGlkOiA0LFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAxLTEnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIGlkOiA5LFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAxLTEtMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICBpZDogMTAsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDEtMS0yJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgaWQ6IDIsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMicsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgaWQ6IDUsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDItMScsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogNixcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0yJyxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIGlkOiAzLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDMnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIGlkOiA3LFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAzLTEnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IDgsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDMtMicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/default-state.vue)_

vue

```
<template>
  <el-tree
    style="max-width: 600px"
    :data="data"
    show-checkbox
    node-key="id"
    :default-expanded-keys="[2, 3]"
    :default-checked-keys="[5]"
    :props="defaultProps"
  />
</template>

<script lang="ts" setup>
const defaultProps = {
  children: 'children',
  label: 'label',
}
const data = [
  {
    id: 1,
    label: 'Level one 1',
    children: [
      {
        id: 4,
        label: 'Level two 1-1',
        children: [
          {
            id: 9,
            label: 'Level three 1-1-1',
          },
          {
            id: 10,
            label: 'Level three 1-1-2',
          },
        ],
      },
    ],
  },
  {
    id: 2,
    label: 'Level one 2',
    children: [
      {
        id: 5,
        label: 'Level two 2-1',
      },
      {
        id: 6,
        label: 'Level two 2-2',
      },
    ],
  },
  {
    id: 3,
    label: 'Level one 3',
    children: [
      {
        id: 7,
        label: 'Level two 3-1',
      },
      {
        id: 8,
        label: 'Level two 3-2',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 树节点的选择 [​](#树节点的选择)

本例展示如何获取和设置选中节点。 获取和设置各有两种方式：通过 node 或通过 key。 如果需要通过 key 来获取或设置，则必须设置 `node-key`。

Level one 1

Level two 1-1

Level three 1-1-1

Level three 1-1-2

Level one 2

Level two 2-1

Level two 2-2

Level one 3

Level two 3-1

Level two 3-2

get by nodeget by keyset by nodeset by keyreset

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZVxuICAgIHJlZj1cInRyZWVSZWZcIlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICBzaG93LWNoZWNrYm94XG4gICAgZGVmYXVsdC1leHBhbmQtYWxsXG4gICAgbm9kZS1rZXk9XCJpZFwiXG4gICAgaGlnaGxpZ2h0LWN1cnJlbnRcbiAgICA6cHJvcHM9XCJkZWZhdWx0UHJvcHNcIlxuICAvPlxuXG4gIDxkaXYgY2xhc3M9XCJmbGV4IGZsZXgtd3JhcCBnYXAtMSBtdC0yXCI+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgQGNsaWNrPVwiZ2V0Q2hlY2tlZE5vZGVzXCI+Z2V0IGJ5IG5vZGU8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBAY2xpY2s9XCJnZXRDaGVja2VkS2V5c1wiPmdldCBieSBrZXk8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBAY2xpY2s9XCJzZXRDaGVja2VkTm9kZXNcIj5zZXQgYnkgbm9kZTwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gY2xhc3M9XCIhbWwtMFwiIEBjbGljaz1cInNldENoZWNrZWRLZXlzXCI+c2V0IGJ5IGtleTwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gY2xhc3M9XCIhbWwtMFwiIEBjbGljaz1cInJlc2V0Q2hlY2tlZFwiPnJlc2V0PC9lbC1idXR0b24+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBSZW5kZXJDb250ZW50Q29udGV4dCwgVHJlZUluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbnRlcmZhY2UgVHJlZSB7XG4gIGlkOiBudW1iZXJcbiAgbGFiZWw6IHN0cmluZ1xuICBjaGlsZHJlbj86IFRyZWVbXVxufVxudHlwZSBOb2RlID0gUmVuZGVyQ29udGVudENvbnRleHRbJ25vZGUnXVxuXG5jb25zdCB0cmVlUmVmID0gcmVmPFRyZWVJbnN0YW5jZT4oKVxuXG5jb25zdCBnZXRDaGVja2VkTm9kZXMgPSAoKSA9PiB7XG4gIGNvbnNvbGUubG9nKHRyZWVSZWYudmFsdWUhLmdldENoZWNrZWROb2RlcyhmYWxzZSwgZmFsc2UpKVxufVxuY29uc3QgZ2V0Q2hlY2tlZEtleXMgPSAoKSA9PiB7XG4gIGNvbnNvbGUubG9nKHRyZWVSZWYudmFsdWUhLmdldENoZWNrZWRLZXlzKGZhbHNlKSlcbn1cbmNvbnN0IHNldENoZWNrZWROb2RlcyA9ICgpID0+IHtcbiAgdHJlZVJlZi52YWx1ZSEuc2V0Q2hlY2tlZE5vZGVzKFxuICAgIFtcbiAgICAgIHtcbiAgICAgICAgaWQ6IDUsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDItMScsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogOSxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAxLTEtMScsXG4gICAgICB9LFxuICAgIF0gYXMgTm9kZVtdLFxuICAgIGZhbHNlXG4gIClcbn1cbmNvbnN0IHNldENoZWNrZWRLZXlzID0gKCkgPT4ge1xuICB0cmVlUmVmLnZhbHVlIS5zZXRDaGVja2VkS2V5cyhbM10sIGZhbHNlKVxufVxuY29uc3QgcmVzZXRDaGVja2VkID0gKCkgPT4ge1xuICB0cmVlUmVmLnZhbHVlIS5zZXRDaGVja2VkS2V5cyhbXSwgZmFsc2UpXG59XG5cbmNvbnN0IGRlZmF1bHRQcm9wcyA9IHtcbiAgY2hpbGRyZW46ICdjaGlsZHJlbicsXG4gIGxhYmVsOiAnbGFiZWwnLFxufVxuXG5jb25zdCBkYXRhOiBUcmVlW10gPSBbXG4gIHtcbiAgICBpZDogMSxcbiAgICBsYWJlbDogJ0xldmVsIG9uZSAxJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICBpZDogNCxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMS0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBpZDogOSxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMS0xLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgaWQ6IDEwLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAxLTEtMicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIGlkOiAyLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDInLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIGlkOiA1LFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAyLTEnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IDYsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDItMicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICBpZDogMyxcbiAgICBsYWJlbDogJ0xldmVsIG9uZSAzJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICBpZDogNyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0xJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIGlkOiA4LFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAzLTInLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/checking-tree.vue)_

vue

```
<template>
  <el-tree
    ref="treeRef"
    style="max-width: 600px"
    :data="data"
    show-checkbox
    default-expand-all
    node-key="id"
    highlight-current
    :props="defaultProps"
  />

  <div class="flex flex-wrap gap-1 mt-2">
    <el-button class="!ml-0" @click="getCheckedNodes">get by node</el-button>
    <el-button class="!ml-0" @click="getCheckedKeys">get by key</el-button>
    <el-button class="!ml-0" @click="setCheckedNodes">set by node</el-button>
    <el-button class="!ml-0" @click="setCheckedKeys">set by key</el-button>
    <el-button class="!ml-0" @click="resetChecked">reset</el-button>
  </div>
</template>

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

import type { RenderContentContext, TreeInstance } from 'element-plus'

interface Tree {
  id: number
  label: string
  children?: Tree[]
}
type Node = RenderContentContext['node']

const treeRef = ref<TreeInstance>()

const getCheckedNodes = () => {
  console.log(treeRef.value!.getCheckedNodes(false, false))
}
const getCheckedKeys = () => {
  console.log(treeRef.value!.getCheckedKeys(false))
}
const setCheckedNodes = () => {
  treeRef.value!.setCheckedNodes(
    [
      {
        id: 5,
        label: 'Level two 2-1',
      },
      {
        id: 9,
        label: 'Level three 1-1-1',
      },
    ] as Node[],
    false
  )
}
const setCheckedKeys = () => {
  treeRef.value!.setCheckedKeys([3], false)
}
const resetChecked = () => {
  treeRef.value!.setCheckedKeys([], false)
}

const defaultProps = {
  children: 'children',
  label: 'label',
}

const data: Tree[] = [
  {
    id: 1,
    label: 'Level one 1',
    children: [
      {
        id: 4,
        label: 'Level two 1-1',
        children: [
          {
            id: 9,
            label: 'Level three 1-1-1',
          },
          {
            id: 10,
            label: 'Level three 1-1-2',
          },
        ],
      },
    ],
  },
  {
    id: 2,
    label: 'Level one 2',
    children: [
      {
        id: 5,
        label: 'Level two 2-1',
      },
      {
        id: 6,
        label: 'Level two 2-2',
      },
    ],
  },
  {
    id: 3,
    label: 'Level one 3',
    children: [
      {
        id: 7,
        label: 'Level two 3-1',
      },
      {
        id: 8,
        label: 'Level two 3-2',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 自定义节点内容 [​](#自定义节点内容)

节点的内容支持自定义，可以在节点区添加按钮或图标等内容

可以通过两种方法进行树节点内容的自定义：`render-content` 和 scoped slot。 使用 `render-content` 指定渲染函数，该函数返回需要的节点区内容即可。 渲染函数的用法请参考 Vue 文档。 使用 scoped slot 会传入两个参数 `node` 和 `data`，分别表示当前节点的 Node 对象和当前节点的数据。 注意：由于 JSFiddle 不支持 JSX 语法，所以 `render-content` 示例无法在那里运行。 但是在实际的项目中，只要正确地配置了相关依赖，就可以正常运行。

Using render-content

Level one 1

AppendDelete

Level two 1-1

AppendDelete

Level three 1-1-1

AppendDelete

Level three 1-1-2

AppendDelete

Level one 2

AppendDelete

Level two 2-1

AppendDelete

Level two 2-2

AppendDelete

Level one 3

AppendDelete

Level two 3-1

AppendDelete

Level two 3-2

AppendDelete

Using scoped slot

Level one 1

Append Delete

Level two 1-1

Append Delete

Level three 1-1-1

Append Delete

Level three 1-1-2

Append Delete

Level one 2

Append Delete

Level two 2-1

Append Delete

Level two 2-2

Append Delete

Level one 3

Append Delete

Level two 3-1

Append Delete

Level two 3-2

Append Delete

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiY3VzdG9tLXRyZWUtY29udGFpbmVyXCI+XG4gICAgPHA+VXNpbmcgcmVuZGVyLWNvbnRlbnQ8L3A+XG4gICAgPGVsLXRyZWVcbiAgICAgIHJlZj1cInRyZWVSZWYxXCJcbiAgICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgICA6ZGF0YT1cImRhdGFTb3VyY2VcIlxuICAgICAgc2hvdy1jaGVja2JveFxuICAgICAgbm9kZS1rZXk9XCJpZFwiXG4gICAgICBkZWZhdWx0LWV4cGFuZC1hbGxcbiAgICAgIDpleHBhbmQtb24tY2xpY2stbm9kZT1cImZhbHNlXCJcbiAgICAgIDpyZW5kZXItY29udGVudD1cInJlbmRlckNvbnRlbnRcIlxuICAgIC8+XG4gICAgPHA+VXNpbmcgc2NvcGVkIHNsb3Q8L3A+XG4gICAgPGVsLXRyZWVcbiAgICAgIHJlZj1cInRyZWVSZWYyXCJcbiAgICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgICA6ZGF0YT1cImRhdGFTb3VyY2VcIlxuICAgICAgc2hvdy1jaGVja2JveFxuICAgICAgbm9kZS1rZXk9XCJpZFwiXG4gICAgICBkZWZhdWx0LWV4cGFuZC1hbGxcbiAgICAgIDpleHBhbmQtb24tY2xpY2stbm9kZT1cImZhbHNlXCJcbiAgICA+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJ7IG5vZGUsIGRhdGEgfVwiPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiY3VzdG9tLXRyZWUtbm9kZVwiPlxuICAgICAgICAgIDxzcGFuPnt7IG5vZGUubGFiZWwgfX08L3NwYW4+XG4gICAgICAgICAgPGRpdj5cbiAgICAgICAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBsaW5rIEBjbGljaz1cImFwcGVuZChkYXRhKVwiPlxuICAgICAgICAgICAgICBBcHBlbmRcbiAgICAgICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgICAgICAgPGVsLWJ1dHRvblxuICAgICAgICAgICAgICBzdHlsZT1cIm1hcmdpbi1sZWZ0OiA0cHhcIlxuICAgICAgICAgICAgICB0eXBlPVwiZGFuZ2VyXCJcbiAgICAgICAgICAgICAgbGlua1xuICAgICAgICAgICAgICBAY2xpY2s9XCJyZW1vdmUobm9kZSwgZGF0YSlcIlxuICAgICAgICAgICAgPlxuICAgICAgICAgICAgICBEZWxldGVcbiAgICAgICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgICAgIDwvZGl2PlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC10cmVlPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBFbEJ1dHRvbiB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuaW1wb3J0IHR5cGUge1xuICBSZW5kZXJDb250ZW50Q29udGV4dCxcbiAgUmVuZGVyQ29udGVudEZ1bmN0aW9uLFxuICBUcmVlSW5zdGFuY2UsXG59IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuaW50ZXJmYWNlIFRyZWUge1xuICBpZDogbnVtYmVyXG4gIGxhYmVsOiBzdHJpbmdcbiAgY2hpbGRyZW4/OiBUcmVlW11cbn1cbnR5cGUgTm9kZSA9IFJlbmRlckNvbnRlbnRDb250ZXh0Wydub2RlJ11cbnR5cGUgRGF0YSA9IFJlbmRlckNvbnRlbnRDb250ZXh0WydkYXRhJ11cblxubGV0IGlkID0gMTAwMFxuY29uc3QgdHJlZVJlZjEgPSByZWY8VHJlZUluc3RhbmNlPigpXG5jb25zdCB0cmVlUmVmMiA9IHJlZjxUcmVlSW5zdGFuY2U+KClcblxuY29uc3QgYXBwZW5kID0gKGRhdGE6IERhdGEpID0+IHtcbiAgY29uc3QgbmV3Q2hpbGQgPSB7IGlkOiBpZCsrLCBsYWJlbDogJ3Rlc3R0ZXN0JywgY2hpbGRyZW46IFtdIH1cbiAgdHJlZVJlZjEudmFsdWU/LmFwcGVuZChuZXdDaGlsZCwgZGF0YSlcbiAgdHJlZVJlZjIudmFsdWU/LmFwcGVuZChuZXdDaGlsZCwgZGF0YSlcbn1cblxuY29uc3QgcmVtb3ZlID0gKG5vZGU6IE5vZGUsIGRhdGE6IERhdGEpID0+IHtcbiAgdHJlZVJlZjEudmFsdWU/LnJlbW92ZShkYXRhKVxuICB0cmVlUmVmMi52YWx1ZT8ucmVtb3ZlKGRhdGEpXG59XG5cbmNvbnN0IHJlbmRlckNvbnRlbnQ6IFJlbmRlckNvbnRlbnRGdW5jdGlvbiA9IChoLCB7IG5vZGUsIGRhdGEgfSkgPT4ge1xuICByZXR1cm4gaChcbiAgICAnZGl2JyxcbiAgICB7XG4gICAgICBjbGFzczogJ2N1c3RvbS10cmVlLW5vZGUnLFxuICAgIH0sXG4gICAgW1xuICAgICAgaCgnc3BhbicsIG51bGwsIG5vZGUubGFiZWwpLFxuICAgICAgaCgnZGl2JywgbnVsbCwgW1xuICAgICAgICBoKFxuICAgICAgICAgIEVsQnV0dG9uLFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHR5cGU6ICdwcmltYXJ5JyxcbiAgICAgICAgICAgIGxpbms6IHRydWUsXG4gICAgICAgICAgICBvbkNsaWNrOiAoKSA9PiBhcHBlbmQoZGF0YSksXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICBkZWZhdWx0OiAoKSA9PiAnQXBwZW5kJyxcbiAgICAgICAgICB9XG4gICAgICAgICksXG4gICAgICAgIGgoXG4gICAgICAgICAgRWxCdXR0b24sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdHlwZTogJ2RhbmdlcicsXG4gICAgICAgICAgICBsaW5rOiB0cnVlLFxuICAgICAgICAgICAgc3R5bGU6ICdtYXJnaW4tbGVmdDogNHB4JyxcbiAgICAgICAgICAgIG9uQ2xpY2s6ICgpID0+IHJlbW92ZShub2RlLCBkYXRhKSxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIGRlZmF1bHQ6ICgpID0+ICdEZWxldGUnLFxuICAgICAgICAgIH1cbiAgICAgICAgKSxcbiAgICAgIF0pLFxuICAgIF1cbiAgKVxufVxuXG5jb25zdCBkYXRhU291cmNlID0gcmVmPFRyZWVbXT4oW1xuICB7XG4gICAgaWQ6IDEsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgaWQ6IDQsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDEtMScsXG4gICAgICAgIGNoaWxkcmVuOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgaWQ6IDksXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDEtMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIGlkOiAxMCxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMS0xLTInLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICBpZDogMixcbiAgICBsYWJlbDogJ0xldmVsIG9uZSAyJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICBpZDogNSxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0xJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIGlkOiA2LFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAyLTInLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgaWQ6IDMsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMycsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgaWQ6IDcsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDMtMScsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogOCxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0yJyxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbl0pXG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLmN1c3RvbS10cmVlLW5vZGUge1xuICBmbGV4OiAxO1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBqdXN0aWZ5LWNvbnRlbnQ6IHNwYWNlLWJldHdlZW47XG4gIGZvbnQtc2l6ZTogMTRweDtcbiAgcGFkZGluZy1yaWdodDogOHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/customized-node.vue)_

vue

```
<template>
  <div class="custom-tree-container">
    <p>Using render-content</p>
    <el-tree
      ref="treeRef1"
      style="max-width: 600px"
      :data="dataSource"
      show-checkbox
      node-key="id"
      default-expand-all
      :expand-on-click-node="false"
      :render-content="renderContent"
    />
    <p>Using scoped slot</p>
    <el-tree
      ref="treeRef2"
      style="max-width: 600px"
      :data="dataSource"
      show-checkbox
      node-key="id"
      default-expand-all
      :expand-on-click-node="false"
    >
      <template #default="{ node, data }">
        <div class="custom-tree-node">
          <span>{{ node.label }}</span>
          <div>
            <el-button type="primary" link @click="append(data)">
              Append
            </el-button>
            <el-button
              style="margin-left: 4px"
              type="danger"
              link
              @click="remove(node, data)"
            >
              Delete
            </el-button>
          </div>
        </div>
      </template>
    </el-tree>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElButton } from 'element-plus'

import type {
  RenderContentContext,
  RenderContentFunction,
  TreeInstance,
} from 'element-plus'

interface Tree {
  id: number
  label: string
  children?: Tree[]
}
type Node = RenderContentContext['node']
type Data = RenderContentContext['data']

let id = 1000
const treeRef1 = ref<TreeInstance>()
const treeRef2 = ref<TreeInstance>()

const append = (data: Data) => {
  const newChild = { id: id++, label: 'testtest', children: [] }
  treeRef1.value?.append(newChild, data)
  treeRef2.value?.append(newChild, data)
}

const remove = (node: Node, data: Data) => {
  treeRef1.value?.remove(data)
  treeRef2.value?.remove(data)
}

const renderContent: RenderContentFunction = (h, { node, data }) => {
  return h(
    'div',
    {
      class: 'custom-tree-node',
    },
    [
      h('span', null, node.label),
      h('div', null, [
        h(
          ElButton,
          {
            type: 'primary',
            link: true,
            onClick: () => append(data),
          },
          {
            default: () => 'Append',
          }
        ),
        h(
          ElButton,
          {
            type: 'danger',
            link: true,
            style: 'margin-left: 4px',
            onClick: () => remove(node, data),
          },
          {
            default: () => 'Delete',
          }
        ),
      ]),
    ]
  )
}

const dataSource = ref<Tree[]>([
  {
    id: 1,
    label: 'Level one 1',
    children: [
      {
        id: 4,
        label: 'Level two 1-1',
        children: [
          {
            id: 9,
            label: 'Level three 1-1-1',
          },
          {
            id: 10,
            label: 'Level three 1-1-2',
          },
        ],
      },
    ],
  },
  {
    id: 2,
    label: 'Level one 2',
    children: [
      {
        id: 5,
        label: 'Level two 2-1',
      },
      {
        id: 6,
        label: 'Level two 2-2',
      },
    ],
  },
  {
    id: 3,
    label: 'Level one 3',
    children: [
      {
        id: 7,
        label: 'Level two 3-1',
      },
      {
        id: 8,
        label: 'Level two 3-2',
      },
    ],
  },
])
</script>

<style>
.custom-tree-node {
  flex: 1;
  display: flex;
  align-items: center;
  justify-content: space-between;
  font-size: 14px;
  padding-right: 8px;
}
</style>
```

隐藏源代码

## 自定义节点类名 [​](#自定义节点类名)

节点的类名支持自定义。

使用 `props.class` 来建立节点的类名。

Level one 1

Level two 1-1

Level three 1-1-1

Level three 1-1-2

Level one 2

Level two 2-1

Level two 2-2

Level one 3

Level two 3-1

Level two 3-2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiY3VzdG9tLXRyZWUtbm9kZS1jb250YWluZXJcIj5cbiAgICA8ZWwtdHJlZVxuICAgICAgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCJcbiAgICAgIDpkYXRhPVwiZGF0YVwiXG4gICAgICBzaG93LWNoZWNrYm94XG4gICAgICBub2RlLWtleT1cImlkXCJcbiAgICAgIGRlZmF1bHQtZXhwYW5kLWFsbFxuICAgICAgOmV4cGFuZC1vbi1jbGljay1ub2RlPVwiZmFsc2VcIlxuICAgICAgOnByb3BzPVwieyBjbGFzczogY3VzdG9tTm9kZUNsYXNzIH1cIlxuICAgIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB0eXBlIHsgVHJlZU5vZGVEYXRhIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbnRlcmZhY2UgVHJlZSB7XG4gIGlkOiBudW1iZXJcbiAgbGFiZWw6IHN0cmluZ1xuICBpc1BlbnVsdGltYXRlPzogYm9vbGVhblxuICBjaGlsZHJlbj86IFRyZWVbXVxufVxuXG5jb25zdCBjdXN0b21Ob2RlQ2xhc3MgPSAoeyBpc1BlbnVsdGltYXRlIH06IFRyZWVOb2RlRGF0YSkgPT5cbiAgaXNQZW51bHRpbWF0ZSA/ICdpcy1wZW51bHRpbWF0ZScgOiAnJ1xuXG5jb25zdCBkYXRhOiBUcmVlW10gPSBbXG4gIHtcbiAgICBpZDogMSxcbiAgICBsYWJlbDogJ0xldmVsIG9uZSAxJyxcbiAgICBjaGlsZHJlbjogW1xuICAgICAge1xuICAgICAgICBpZDogNCxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMS0xJyxcbiAgICAgICAgaXNQZW51bHRpbWF0ZTogdHJ1ZSxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBpZDogOSxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMS0xLTEnLFxuICAgICAgICAgIH0sXG4gICAgICAgICAge1xuICAgICAgICAgICAgaWQ6IDEwLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAxLTEtMicsXG4gICAgICAgICAgfSxcbiAgICAgICAgXSxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIGlkOiAyLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDInLFxuICAgIGlzUGVudWx0aW1hdGU6IHRydWUsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgaWQ6IDUsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDItMScsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogNixcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0yJyxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIGlkOiAzLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDMnLFxuICAgIGlzUGVudWx0aW1hdGU6IHRydWUsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgaWQ6IDcsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDMtMScsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogOCxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0yJyxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuXG48c3R5bGU+XG4uaXMtcGVudWx0aW1hdGUgPiAuZWwtdHJlZS1ub2RlX19jb250ZW50IC5lbC10cmVlLW5vZGVfX2xhYmVsIHtcbiAgY29sb3I6ICM2MjZhZWY7XG59XG4uaXMtcGVudWx0aW1hdGUgPiAuZWwtdHJlZS1ub2RlX19jaGlsZHJlbiA+IGRpdiB7XG4gIGRpc3BsYXk6IGlubGluZS1ibG9jaztcbiAgbWFyZ2luLXJpZ2h0OiA0cHg7XG5cbiAgJjpub3QoOmZpcnN0LWNoaWxkKSAuZWwtdHJlZS1ub2RlX19jb250ZW50IHtcbiAgICBwYWRkaW5nLWxlZnQ6IDBweCAhaW1wb3J0YW50O1xuICB9XG4gIC5lbC10cmVlLW5vZGVfX2NvbnRlbnQge1xuICAgIHBhZGRpbmctcmlnaHQ6IDE2cHg7XG4gIH1cbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/custom-node-class.vue)_

vue

```
<template>
  <div class="custom-tree-node-container">
    <el-tree
      style="max-width: 600px"
      :data="data"
      show-checkbox
      node-key="id"
      default-expand-all
      :expand-on-click-node="false"
      :props="{ class: customNodeClass }"
    />
  </div>
</template>

<script lang="ts" setup>
import type { TreeNodeData } from 'element-plus'

interface Tree {
  id: number
  label: string
  isPenultimate?: boolean
  children?: Tree[]
}

const customNodeClass = ({ isPenultimate }: TreeNodeData) =>
  isPenultimate ? 'is-penultimate' : ''

const data: Tree[] = [
  {
    id: 1,
    label: 'Level one 1',
    children: [
      {
        id: 4,
        label: 'Level two 1-1',
        isPenultimate: true,
        children: [
          {
            id: 9,
            label: 'Level three 1-1-1',
          },
          {
            id: 10,
            label: 'Level three 1-1-2',
          },
        ],
      },
    ],
  },
  {
    id: 2,
    label: 'Level one 2',
    isPenultimate: true,
    children: [
      {
        id: 5,
        label: 'Level two 2-1',
      },
      {
        id: 6,
        label: 'Level two 2-2',
      },
    ],
  },
  {
    id: 3,
    label: 'Level one 3',
    isPenultimate: true,
    children: [
      {
        id: 7,
        label: 'Level two 3-1',
      },
      {
        id: 8,
        label: 'Level two 3-2',
      },
    ],
  },
]
</script>

<style>
.is-penultimate > .el-tree-node__content .el-tree-node__label {
  color: #626aef;
}
.is-penultimate > .el-tree-node__children > div {
  display: inline-block;
  margin-right: 4px;

  &:not(:first-child) .el-tree-node__content {
    padding-left: 0px !important;
  }
  .el-tree-node__content {
    padding-right: 16px;
  }
}
</style>
```

隐藏源代码

## 树节点过滤 [​](#树节点过滤)

树节点是可以被过滤的

调用 Tree 实例对象的 `filter` 方法来过滤树节点。 方法的参数就是过滤关键字。 需要注意的是，此时需要设置 `filter-node-method` 属性，其值为过滤函数。

Level one 1

Level two 1-1

Level three 1-1-1

Level three 1-1-2

Level one 2

Level two 2-1

Level two 2-2

Level one 3

Level two 3-1

Level two 3-2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXRcbiAgICB2LW1vZGVsPVwiZmlsdGVyVGV4dFwiXG4gICAgY2xhc3M9XCJ3LTYwIG1iLTJcIlxuICAgIHBsYWNlaG9sZGVyPVwiRmlsdGVyIGtleXdvcmRcIlxuICAvPlxuXG4gIDxlbC10cmVlXG4gICAgcmVmPVwidHJlZVJlZlwiXG4gICAgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCJcbiAgICBjbGFzcz1cImZpbHRlci10cmVlXCJcbiAgICA6ZGF0YT1cImRhdGFcIlxuICAgIDpwcm9wcz1cImRlZmF1bHRQcm9wc1wiXG4gICAgZGVmYXVsdC1leHBhbmQtYWxsXG4gICAgOmZpbHRlci1ub2RlLW1ldGhvZD1cImZpbHRlck5vZGVcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiwgd2F0Y2ggfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgRmlsdGVyTm9kZU1ldGhvZEZ1bmN0aW9uLCBUcmVlSW5zdGFuY2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmludGVyZmFjZSBUcmVlIHtcbiAgW2tleTogc3RyaW5nXTogYW55XG59XG5cbmNvbnN0IGZpbHRlclRleHQgPSByZWYoJycpXG5jb25zdCB0cmVlUmVmID0gcmVmPFRyZWVJbnN0YW5jZT4oKVxuXG5jb25zdCBkZWZhdWx0UHJvcHMgPSB7XG4gIGNoaWxkcmVuOiAnY2hpbGRyZW4nLFxuICBsYWJlbDogJ2xhYmVsJyxcbn1cblxud2F0Y2goZmlsdGVyVGV4dCwgKHZhbCkgPT4ge1xuICB0cmVlUmVmLnZhbHVlIS5maWx0ZXIodmFsKVxufSlcblxuY29uc3QgZmlsdGVyTm9kZTogRmlsdGVyTm9kZU1ldGhvZEZ1bmN0aW9uID0gKHZhbHVlOiBzdHJpbmcsIGRhdGE6IFRyZWUpID0+IHtcbiAgaWYgKCF2YWx1ZSkgcmV0dXJuIHRydWVcbiAgcmV0dXJuIGRhdGEubGFiZWwuaW5jbHVkZXModmFsdWUpXG59XG5cbmNvbnN0IGRhdGE6IFRyZWVbXSA9IFtcbiAge1xuICAgIGlkOiAxLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDEnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIGlkOiA0LFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAxLTEnLFxuICAgICAgICBjaGlsZHJlbjogW1xuICAgICAgICAgIHtcbiAgICAgICAgICAgIGlkOiA5LFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAxLTEtMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICBpZDogMTAsXG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDEtMS0yJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgaWQ6IDIsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMicsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgaWQ6IDUsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDItMScsXG4gICAgICB9LFxuICAgICAge1xuICAgICAgICBpZDogNixcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0yJyxcbiAgICAgIH0sXG4gICAgXSxcbiAgfSxcbiAge1xuICAgIGlkOiAzLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDMnLFxuICAgIGNoaWxkcmVuOiBbXG4gICAgICB7XG4gICAgICAgIGlkOiA3LFxuICAgICAgICBsYWJlbDogJ0xldmVsIHR3byAzLTEnLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgaWQ6IDgsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDMtMicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/filtering.vue)_

vue

```
<template>
  <el-input
    v-model="filterText"
    class="w-60 mb-2"
    placeholder="Filter keyword"
  />

  <el-tree
    ref="treeRef"
    style="max-width: 600px"
    class="filter-tree"
    :data="data"
    :props="defaultProps"
    default-expand-all
    :filter-node-method="filterNode"
  />
</template>

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

import type { FilterNodeMethodFunction, TreeInstance } from 'element-plus'

interface Tree {
  [key: string]: any
}

const filterText = ref('')
const treeRef = ref<TreeInstance>()

const defaultProps = {
  children: 'children',
  label: 'label',
}

watch(filterText, (val) => {
  treeRef.value!.filter(val)
})

const filterNode: FilterNodeMethodFunction = (value: string, data: Tree) => {
  if (!value) return true
  return data.label.includes(value)
}

const data: Tree[] = [
  {
    id: 1,
    label: 'Level one 1',
    children: [
      {
        id: 4,
        label: 'Level two 1-1',
        children: [
          {
            id: 9,
            label: 'Level three 1-1-1',
          },
          {
            id: 10,
            label: 'Level three 1-1-2',
          },
        ],
      },
    ],
  },
  {
    id: 2,
    label: 'Level one 2',
    children: [
      {
        id: 5,
        label: 'Level two 2-1',
      },
      {
        id: 6,
        label: 'Level two 2-2',
      },
    ],
  },
  {
    id: 3,
    label: 'Level one 3',
    children: [
      {
        id: 7,
        label: 'Level two 3-1',
      },
      {
        id: 8,
        label: 'Level two 3-2',
      },
    ],
  },
]
</script>
```

隐藏源代码

## 手风琴模式 [​](#手风琴模式)

对于同一级的节点，每次只能展开一个

Level one 1

Level one 2

Level one 3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZVxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6cHJvcHM9XCJkZWZhdWx0UHJvcHNcIlxuICAgIGFjY29yZGlvblxuICAgIEBub2RlLWNsaWNrPVwiaGFuZGxlTm9kZUNsaWNrXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbnRlcmZhY2UgVHJlZSB7XG4gIGxhYmVsOiBzdHJpbmdcbiAgY2hpbGRyZW4/OiBUcmVlW11cbn1cblxuY29uc3QgaGFuZGxlTm9kZUNsaWNrID0gKGRhdGE6IFRyZWUpID0+IHtcbiAgY29uc29sZS5sb2coZGF0YSlcbn1cblxuY29uc3QgZGF0YTogVHJlZVtdID0gW1xuICB7XG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMS0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDEtMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMicsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDItMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0yJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDItMi0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMycsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0yJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMi0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuY29uc3QgZGVmYXVsdFByb3BzID0ge1xuICBjaGlsZHJlbjogJ2NoaWxkcmVuJyxcbiAgbGFiZWw6ICdsYWJlbCcsXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/accordion.vue)_

vue

```
<template>
  <el-tree
    style="max-width: 600px"
    :data="data"
    :props="defaultProps"
    accordion
    @node-click="handleNodeClick"
  />
</template>

<script lang="ts" setup>
interface Tree {
  label: string
  children?: Tree[]
}

const handleNodeClick = (data: Tree) => {
  console.log(data)
}

const data: Tree[] = [
  {
    label: 'Level one 1',
    children: [
      {
        label: 'Level two 1-1',
        children: [
          {
            label: 'Level three 1-1-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Level one 2',
    children: [
      {
        label: 'Level two 2-1',
        children: [
          {
            label: 'Level three 2-1-1',
          },
        ],
      },
      {
        label: 'Level two 2-2',
        children: [
          {
            label: 'Level three 2-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Level one 3',
    children: [
      {
        label: 'Level two 3-1',
        children: [
          {
            label: 'Level three 3-1-1',
          },
        ],
      },
      {
        label: 'Level two 3-2',
        children: [
          {
            label: 'Level three 3-2-1',
          },
        ],
      },
    ],
  },
]
const defaultProps = {
  children: 'children',
  label: 'label',
}
</script>
```

隐藏源代码

## 可拖拽节点 [​](#可拖拽节点)

通过 `draggable` 属性可让节点变为可拖拽

Level one 1

Level two 1-1

Level three 1-1-1

Level one 2

Level two 2-1

Level three 2-1-1

Level two 2-2

Level three 2-2-1

Level one 3

Level two 3-1

Level three 3-1-1

Level two 3-2

Level three 3-2-1

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZVxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmFsbG93LWRyb3A9XCJhbGxvd0Ryb3BcIlxuICAgIDphbGxvdy1kcmFnPVwiYWxsb3dEcmFnXCJcbiAgICA6ZGF0YT1cImRhdGFcIlxuICAgIGRyYWdnYWJsZVxuICAgIGRlZmF1bHQtZXhwYW5kLWFsbFxuICAgIG5vZGUta2V5PVwiaWRcIlxuICAgIEBub2RlLWRyYWctc3RhcnQ9XCJoYW5kbGVEcmFnU3RhcnRcIlxuICAgIEBub2RlLWRyYWctZW50ZXI9XCJoYW5kbGVEcmFnRW50ZXJcIlxuICAgIEBub2RlLWRyYWctbGVhdmU9XCJoYW5kbGVEcmFnTGVhdmVcIlxuICAgIEBub2RlLWRyYWctb3Zlcj1cImhhbmRsZURyYWdPdmVyXCJcbiAgICBAbm9kZS1kcmFnLWVuZD1cImhhbmRsZURyYWdFbmRcIlxuICAgIEBub2RlLWRyb3A9XCJoYW5kbGVEcm9wXCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgdHlwZSB7XG4gIEFsbG93RHJvcFR5cGUsXG4gIE5vZGVEcm9wVHlwZSxcbiAgUmVuZGVyQ29udGVudENvbnRleHQsXG59IGZyb20gJ2VsZW1lbnQtcGx1cydcblxudHlwZSBOb2RlID0gUmVuZGVyQ29udGVudENvbnRleHRbJ25vZGUnXVxuXG5jb25zdCBoYW5kbGVEcmFnU3RhcnQgPSAobm9kZTogTm9kZSwgZXY6IERyYWdFdmVudCkgPT4ge1xuICBjb25zb2xlLmxvZygnZHJhZyBzdGFydCcsIG5vZGUpXG59XG5jb25zdCBoYW5kbGVEcmFnRW50ZXIgPSAoZHJhZ2dpbmdOb2RlOiBOb2RlLCBkcm9wTm9kZTogTm9kZSwgZXY6IERyYWdFdmVudCkgPT4ge1xuICBjb25zb2xlLmxvZygndHJlZSBkcmFnIGVudGVyOicsIGRyb3BOb2RlLmxhYmVsKVxufVxuY29uc3QgaGFuZGxlRHJhZ0xlYXZlID0gKGRyYWdnaW5nTm9kZTogTm9kZSwgZHJvcE5vZGU6IE5vZGUsIGV2OiBEcmFnRXZlbnQpID0+IHtcbiAgY29uc29sZS5sb2coJ3RyZWUgZHJhZyBsZWF2ZTonLCBkcm9wTm9kZS5sYWJlbClcbn1cbmNvbnN0IGhhbmRsZURyYWdPdmVyID0gKGRyYWdnaW5nTm9kZTogTm9kZSwgZHJvcE5vZGU6IE5vZGUsIGV2OiBEcmFnRXZlbnQpID0+IHtcbiAgY29uc29sZS5sb2coJ3RyZWUgZHJhZyBvdmVyOicsIGRyb3BOb2RlLmxhYmVsKVxufVxuY29uc3QgaGFuZGxlRHJhZ0VuZCA9IChcbiAgZHJhZ2dpbmdOb2RlOiBOb2RlLFxuICBkcm9wTm9kZTogTm9kZSB8IG51bGwsXG4gIGRyb3BUeXBlOiBOb2RlRHJvcFR5cGUsXG4gIGV2OiBEcmFnRXZlbnRcbikgPT4ge1xuICBjb25zb2xlLmxvZygndHJlZSBkcmFnIGVuZDonLCBkcm9wTm9kZSAmJiBkcm9wTm9kZS5sYWJlbCwgZHJvcFR5cGUpXG59XG5jb25zdCBoYW5kbGVEcm9wID0gKFxuICBkcmFnZ2luZ05vZGU6IE5vZGUsXG4gIGRyb3BOb2RlOiBOb2RlLFxuICBkcm9wVHlwZTogRXhjbHVkZTxOb2RlRHJvcFR5cGUsICdub25lJz4sXG4gIGV2OiBEcmFnRXZlbnRcbikgPT4ge1xuICBjb25zb2xlLmxvZygndHJlZSBkcm9wOicsIGRyb3BOb2RlLmxhYmVsLCBkcm9wVHlwZSlcbn1cbmNvbnN0IGFsbG93RHJvcCA9IChkcmFnZ2luZ05vZGU6IE5vZGUsIGRyb3BOb2RlOiBOb2RlLCB0eXBlOiBBbGxvd0Ryb3BUeXBlKSA9PiB7XG4gIGlmIChkcm9wTm9kZS5kYXRhLmxhYmVsID09PSAnTGV2ZWwgdHdvIDMtMScpIHtcbiAgICByZXR1cm4gdHlwZSAhPT0gJ2lubmVyJ1xuICB9IGVsc2Uge1xuICAgIHJldHVybiB0cnVlXG4gIH1cbn1cbmNvbnN0IGFsbG93RHJhZyA9IChkcmFnZ2luZ05vZGU6IE5vZGUpID0+IHtcbiAgcmV0dXJuICFkcmFnZ2luZ05vZGUuZGF0YS5sYWJlbC5pbmNsdWRlcygnTGV2ZWwgdGhyZWUgMy0xLTEnKVxufVxuXG5jb25zdCBkYXRhID0gW1xuICB7XG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMS0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDEtMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMicsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDItMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0yJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDItMi0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMycsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0xJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMS0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICAgIHtcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0yJyxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBsYWJlbDogJ0xldmVsIHRocmVlIDMtMi0xJyxcbiAgICAgICAgICB9LFxuICAgICAgICBdLFxuICAgICAgfSxcbiAgICBdLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree/draggable.vue)_

vue

```
<template>
  <el-tree
    style="max-width: 600px"
    :allow-drop="allowDrop"
    :allow-drag="allowDrag"
    :data="data"
    draggable
    default-expand-all
    node-key="id"
    @node-drag-start="handleDragStart"
    @node-drag-enter="handleDragEnter"
    @node-drag-leave="handleDragLeave"
    @node-drag-over="handleDragOver"
    @node-drag-end="handleDragEnd"
    @node-drop="handleDrop"
  />
</template>

<script lang="ts" setup>
import type {
  AllowDropType,
  NodeDropType,
  RenderContentContext,
} from 'element-plus'

type Node = RenderContentContext['node']

const handleDragStart = (node: Node, ev: DragEvent) => {
  console.log('drag start', node)
}
const handleDragEnter = (draggingNode: Node, dropNode: Node, ev: DragEvent) => {
  console.log('tree drag enter:', dropNode.label)
}
const handleDragLeave = (draggingNode: Node, dropNode: Node, ev: DragEvent) => {
  console.log('tree drag leave:', dropNode.label)
}
const handleDragOver = (draggingNode: Node, dropNode: Node, ev: DragEvent) => {
  console.log('tree drag over:', dropNode.label)
}
const handleDragEnd = (
  draggingNode: Node,
  dropNode: Node | null,
  dropType: NodeDropType,
  ev: DragEvent
) => {
  console.log('tree drag end:', dropNode && dropNode.label, dropType)
}
const handleDrop = (
  draggingNode: Node,
  dropNode: Node,
  dropType: Exclude<NodeDropType, 'none'>,
  ev: DragEvent
) => {
  console.log('tree drop:', dropNode.label, dropType)
}
const allowDrop = (draggingNode: Node, dropNode: Node, type: AllowDropType) => {
  if (dropNode.data.label === 'Level two 3-1') {
    return type !== 'inner'
  } else {
    return true
  }
}
const allowDrag = (draggingNode: Node) => {
  return !draggingNode.data.label.includes('Level three 3-1-1')
}

const data = [
  {
    label: 'Level one 1',
    children: [
      {
        label: 'Level two 1-1',
        children: [
          {
            label: 'Level three 1-1-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Level one 2',
    children: [
      {
        label: 'Level two 2-1',
        children: [
          {
            label: 'Level three 2-1-1',
          },
        ],
      },
      {
        label: 'Level two 2-2',
        children: [
          {
            label: 'Level three 2-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Level one 3',
    children: [
      {
        label: 'Level two 3-1',
        children: [
          {
            label: 'Level three 3-1-1',
          },
        ],
      },
      {
        label: 'Level two 3-2',
        children: [
          {
            label: 'Level three 3-2-1',
          },
        ],
      },
    ],
  },
]
</script>
```

隐藏源代码

## Tree API [​](#tree-api)

### 属性 [​](#属性)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| data | 展示数据 | `array` | — |
| empty-text | 内容为空的时候展示的文本 | `string` | — |
| node-key | 每个树节点用来作为唯一标识的属性，整棵树应该是唯一的 | `string` | — |
| [props](#props) | 配置选项，具体看下表 | `object` | — |
| render-after-expand | 是否在第一次展开某个树节点后才渲染其子节点 | `boolean` | true |
| load | 加载子树数据的方法，仅当 lazy 属性为true 时生效 | `Function` | — |
| render-content | 树节点的内容区的渲染 Function | `Function` | — |
| highlight-current | 是否高亮当前选中节点，默认值是 false。 | `boolean` | false |
| default-expand-all | 是否默认展开所有节点 | `boolean` | false |
| expand-on-click-node | 是否在点击节点的时候展开或者收缩节点， 默认值为 true，如果为 false，则只有点箭头图标的时候才会展开或者收缩节点。 | `boolean` | true |
| check-on-click-node | 是否在点击节点的时候选中节点，默认值为 false，即只有在点击复选框时才会选中节点。 | `boolean` | false |
| check-on-click-leaf 2.9.6 | 点击叶节点(最后一个子节点)时是否选中或取消选中节点。 | `boolean` | true |
| auto-expand-parent | 展开子节点的时候是否自动展开父节点 | `boolean` | true |
| default-expanded-keys | 默认展开的节点的 key 的数组 | `array` | — |
| show-checkbox | 节点是否可被选择 | `boolean` | false |
| check-strictly | 在显示复选框的情况下，是否严格的遵循父子不互相关联的做法，默认为 false | `boolean` | false |
| default-checked-keys | 默认勾选的节点的 key 的数组 | `array` | — |
| current-node-key | 当前选中的节点 | `string` / `number` | — |
| filter-node-method | 对树节点进行筛选时执行的方法， 返回 `false` 则表示这个节点会被隐藏 | `Function` | — |
| accordion | 是否每次只打开一个同级树节点展开 | `boolean` | false |
| indent | 相邻级节点间的水平缩进，单位为像素 | `number` | 18 |
| icon | 自定义树节点图标组件 | `string` / `Component` | — |
| lazy | 是否懒加载子节点，需与 load 方法结合使用 | `boolean` | false |
| draggable | 是否开启拖拽节点功能 | `boolean` | false |
| allow-drag | 判断节点能否被拖拽 如果返回 `false` ，节点不能被拖动 | `Function` | — |
| allow-drop | 拖拽时判定目标节点能否成为拖动目标位置。 如果返回 `false` ，拖动节点不能被拖放到目标节点。 `type` 参数有三种情况：'prev'、'inner' 和 'next'，分别表示放置在目标节点前、插入至目标节点和放置在目标节点后 | `Function` | — |

### Props [​](#props)

| Props | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| label | 指定节点标签为节点对象的某个属性值 | `string` / `Function` | — |
| children | 指定子树为节点对象的某个属性值 | `string` | — |
| disabled | 指定节点选择框是否禁用为节点对象的某个属性值 | `string` / `Function` | — |
| isLeaf | 指定节点是否为叶子节点，仅在指定了 lazy 属性的情况下生效 | `string` / `Function` | — |
| class | 自定义节点类名 | `string` / `Function` | — |

### 对外暴露的方法 [​](#对外暴露的方法)

`Tree` 组件有以下方法，均返回当前选中的节点数组

| 方法 | 说明 | 回调参数 |
| --- | --- | --- |
| filter | 过滤所有树节点，过滤后的节点将被隐藏 | 接收一个参数并指定为 filter-node-method 属性的第一个参数 |
| updateKeyChildren | 为节点设置新数据，只有当设置 `node-key` 属性的时候才可用 | (key, data) 接收两个参数: 1. 节点的 key 2. 新数据 |
| getCheckedNodes | 如果节点可以被选中，(`show-checkbox` 为 `true`), 本方法将返回当前选中节点的数组 | (leafOnly, includeHalfChecked) 接收两个布尔类型参数: 1. 默认值为 `false`. 若参数为 `true`, 它将返回当前选中节点的子节点 2. 默认值为 `false`. 如果参数为 `true`, 返回值包含半选中节点数据 |
| setCheckedNodes | 设置目前选中的节点，使用此方法必须设置 `node-key` 属性 | (nodes, leafOnly) 接收两个参数: 1. 要选中的节点对象构成的数组 2. 布尔类型的值 如果设置为 `true`，将只设置选中的叶子节点状态。 默认值是 `false`. |
| getCheckedKeys | 若节点可用被选中 (`show-checkbox` 为 `true`), 它将返回当前选中节点 key 的数组 | (leafOnly) 接收一个布尔类型参数，默认为 `false`. 若参数为 `true`, 它将返回当前选中节点的子节点 |
| setCheckedKeys | 设置目前选中的节点，使用此方法必须设置 `node-key` 属性 | (keys, leafOnly) 接收两个参数: 1. 一个需要被选中的多节点 key 的数组 2. 布尔类型的值 如果设置为 `true`，将只设置选中的叶子节点状态。 默认值是 `false`. |
| setChecked | 设置节点是否被选中, 使用此方法必须设置 `node-key` 属性 | (key/data, checked, deep) 接收三个参数: 1. 要选中的节点的 key 或者数据 2. 一个布尔类型参数表明是否选中. 3. 一个布尔类型参数，用于指示是否递归选中/取消选中子节点（自 2.14.0 起，无论 `check-strictly` 设置如何，该行为均有效）。 |
| getHalfCheckedNodes | 如果节点可用被选中 (`show-checkbox` 为 `true`), 它将返回当前半选中的节点组成的数组 | — |
| getHalfCheckedKeys | 若节点可被选中(`show-checkbox` 为 `true`)，则返回目前半选中的节点的 key 所组成的数组 | — |
| getCurrentKey | 返回当前被选中节点的数据 (如果没有则返回 null) | — |
| getCurrentNode | 返回当前被选中节点的数据 (如果没有则返回 null) | — |
| setCurrentKey | 通过 key 设置某个节点的当前选中状态，使用此方法必须设置 `node-key` 属性 | (key, shouldAutoExpandParent=true) 1. 待被选节点的 key， 如果为 `null`, 取消当前选中的节点 2. 是否展开父节点 |
| setCurrentNode | 设置节点为选中状态，使用此方法必须设置 `node-key` 属性 | (node, shouldAutoExpandParent=true) 1. 待被选中的节点 2. 是否展开父节点 |
| getNode | 根据 data 或者 key 拿到 Tree 组件中的 node | (data) 节点的 data 或 key |
| remove | 删除 Tree 中的一个节点，使用此方法必须设置 node-key 属性 | (data) 要删除的节点的 data 或者 node 对象 |
| append | 为 Tree 中的一个节点追加一个子节点 | (data, parentNode) 1. 要追加的子节点的 data 2. 父节点的 data, key 或 node |
| insertBefore | 在 Tree 中给定节点前插入一个节点 | (data, refNode) 1. 要增加的节点的 data 2. 参考节点的 data, key 或 node |
| insertAfter | 在 Tree 中给定节点后插入一个节点 | (data, refNode) 1. 要增加的节点的 data 2. 参考节点的 data, key 或 node |

### 事件 [​](#事件)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| node-click | 当节点被点击的时候触发 | 四个参数：对应于节点点击的节点对象，TreeNode 的 `node` 属性, TreeNode和事件对象 |
| node-contextmenu | 当某一节点被鼠标右键点击时会触发该事件 | 共四个参数，依次为：event、传递给 `data` 属性的数组中该节点所对应的对象、节点对应的 Node、节点组件本身。 |
| check-change | 当复选框被点击的时候触发 | 共三个参数，依次为：传递给 data 属性的数组中该节点所对应的对象、节点本身是否被选中、节点的子树中是否有被选中的节点 |
| check | 点击节点复选框之后触发 | 共两个参数，依次为：传递给 data 属性的数组中该节点所对应的对象、树目前的选中状态对象，包含 checkedNodes、checkedKeys、halfCheckedNodes、halfCheckedKeys 四个属性 |
| current-change | 当前选中节点变化时触发的事件 | 共两个参数，依次为：当前节点的数据，当前节点的 Node 对象 |
| node-expand | 节点被展开时触发的事件 | 共三个参数，依次为：传递给 `data` 属性的数组中该节点所对应的对象、节点对应的 Node、节点组件本身 |
| node-collapse | 节点被关闭时触发的事件 | 共三个参数，依次为：传递给 `data` 属性的数组中该节点所对应的对象、节点对应的 Node、节点组件本身 |
| node-drag-start | 节点开始拖拽时触发的事件 | 共两个参数，依次为：被拖拽节点对应的 Node、event |
| node-drag-enter | 拖拽进入其他节点时触发的事件 | 共三个参数，依次为：被拖拽节点对应的 Node、所进入节点对应的 Node、event |
| node-drag-leave | 拖拽离开某个节点时触发的事件 | 共三个参数，依次为：被拖拽节点对应的 Node、所离开节点对应的 Node、event |
| node-drag-over | 在拖拽节点时触发的事件（类似浏览器的 mouseover 事件） | 共三个参数，依次为：被拖拽节点对应的 Node、当前进入节点对应的 Node、event |
| node-drag-end | 拖拽结束时（可能未成功）触发的事件 | 共四个参数，依次为：被拖拽节点对应的 Node、结束拖拽时最后进入的节点（可能为空）、被拖拽节点的放置位置（before、after、inner）、event |
| node-drop | 拖拽成功完成时触发的事件 | 共四个参数，依次为：被拖拽节点对应的 Node、结束拖拽时最后进入的节点、被拖拽节点的放置位置（before、after、inner）、event |

### 插槽 [​](#插槽)

| 插槽名 | 描述 | Type |
| --- | --- | --- |
| default | 自定义树节点的内容。 | `object` |
| empty 2.3.4 | 当数据为空时自定义的内容 | — |

## 类型声明 [​](#类型声明)

Show declarations

ts

```
interface RootTreeType {
  root: Ref<Node>
  // ...
}

// UnwrapRef<RootTreeType['root']> => Node
type Node = {
  canFocus: boolean
  checked: boolean
  childNodes: Node[]
  data: TreeNodeData
  expanded: boolean
  id: number
  indeterminate: boolean
  isCurrent: boolean
  isEffectivelyChecked: boolean
  isLeaf?: boolean
  isLeafByUser?: boolean
  level: number
  loaded: boolean
  loading: boolean
  parent: Node | null
  store: TreeStore
  text: string | null
  visible: boolean
}

// TreeNodeData => Tree / TreeOptionProps
// Tree type is your prop type.
// TreeOptionProps is default prop type
interface TreeOptionProps {
  children?: string
  label?: string | ((data: TreeNodeData, node: Node) => string)
  disabled?: string | ((data: TreeNodeData, node: Node) => boolean)
  isLeaf?: string | ((data: TreeNodeData, node: Node) => boolean)
  class?: (
    data: TreeNodeData,
    node: Node
  ) => string | { [key: string]: boolean }
}
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/tree) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/tree.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/tree.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/27413795?v=4&size=64)](https://github.com/SpanManX)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/59350883?v=4&size=64)](https://github.com/init-qy)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/36940267?v=4&size=64)](https://github.com/gaoxuan-haxibiao)[![](https://avatars.githubusercontent.com/u/75007029?v=4&size=64)](https://github.com/yj-liuzepeng)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/32807958?v=4&size=64)](https://github.com/zhiyuanzmj)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/283908624?v=4&size=64)](https://github.com/ruguoba)[![](https://avatars.githubusercontent.com/u/53589602?v=4&size=64)](https://github.com/l246804)[![](https://avatars.githubusercontent.com/u/15535177?v=4&size=64)](https://github.com/liuzi6612)[![](https://avatars.githubusercontent.com/u/24290011?v=4&size=64)](https://github.com/xingyixiang)[![](https://avatars.githubusercontent.com/u/14892120?v=4&size=64)](https://github.com/scvzerng)[![](https://avatars.githubusercontent.com/u/16952163?v=4&size=64)](https://github.com/ben-lau)[![](https://avatars.githubusercontent.com/u/110156942?v=4&size=64)](https://github.com/a92126)[![](https://avatars.githubusercontent.com/u/78132554?v=4&size=64)](https://github.com/momei-LJM)[![](https://avatars.githubusercontent.com/u/57086651?v=4&size=64)](https://github.com/Simon-He95)[![](https://avatars.githubusercontent.com/u/34467508?v=4&size=64)](https://github.com/kaedeair)[![](https://avatars.githubusercontent.com/u/22884361?v=4&size=64)](https://github.com/Alixhan)[![](https://avatars.githubusercontent.com/u/65433954?v=4&size=64)](https://github.com/inside5545)[![](https://avatars.githubusercontent.com/u/41944818?v=4&size=64)](https://github.com/CherishTheYouth)[![](https://avatars.githubusercontent.com/u/54665054?v=4&size=64)](https://github.com/lyric-zemin)[![](https://avatars.githubusercontent.com/u/105651386?v=4&size=64)](https://github.com/heappynd)[![](https://avatars.githubusercontent.com/u/26755049?v=4&size=64)](https://github.com/qq282126990)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/54560462?v=4&size=64)](https://github.com/matto49)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/49394793?v=4&size=64)](https://github.com/bxh1071)[![](https://avatars.githubusercontent.com/u/15629755?v=4&size=64)](https://github.com/Nullaha)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/23442840?v=4&size=64)](https://github.com/liunnn1994)[![](https://avatars.githubusercontent.com/u/1687298?v=4&size=64)](https://github.com/greper)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/52314078?v=4&size=64)](https://github.com/vaebe)[![](https://avatars.githubusercontent.com/u/38553985?v=4&size=64)](https://github.com/lequangdongg)[![](https://avatars.githubusercontent.com/u/38248854?v=4&size=64)](https://github.com/Yueyanc)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/48074435?v=4&size=64)](https://github.com/ElsaOOo)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)[![](https://avatars.githubusercontent.com/u/22695767?v=4&size=64)](https://github.com/deepthan)

[Tour 漫游式引导](https://element-plus.org/zh-CN/component/tour)

[Virtualized Tree 虚拟化树形控件](https://element-plus.org/zh-CN/component/tree-v2)




---
## [data/tree-v2] Virtualized Tree 虚拟化树形控件
> 官方文档: https://element-plus.org/zh-CN/component/tree-v2.html

---

#

Tree V2 虚拟化树形控件beta

[​](#tree-v2-虚拟化树形控件)

更新日志待解决

17

不论你的数据量多大，虚拟树都能毫无压力地处理。

## 基础用法 [​](#基础用法)

基础的树形结构展示

node-1

node-2

node-3

node-4

node-5

node-6

node-7

node-8

node-9

node-10

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS12MlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgOmhlaWdodD1cIjIwMFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW50ZXJmYWNlIFRyZWUge1xuICBpZDogc3RyaW5nXG4gIGxhYmVsOiBzdHJpbmdcbiAgY2hpbGRyZW4/OiBUcmVlW11cbn1cblxuY29uc3QgZ2V0S2V5ID0gKHByZWZpeDogc3RyaW5nLCBpZDogbnVtYmVyKSA9PiB7XG4gIHJldHVybiBgJHtwcmVmaXh9LSR7aWR9YFxufVxuXG5jb25zdCBjcmVhdGVEYXRhID0gKFxuICBtYXhEZWVwOiBudW1iZXIsXG4gIG1heENoaWxkcmVuOiBudW1iZXIsXG4gIG1pbk5vZGVzTnVtYmVyOiBudW1iZXIsXG4gIGRlZXAgPSAxLFxuICBrZXkgPSAnbm9kZSdcbik6IFRyZWVbXSA9PiB7XG4gIGxldCBpZCA9IDBcbiAgcmV0dXJuIEFycmF5LmZyb20oeyBsZW5ndGg6IG1pbk5vZGVzTnVtYmVyIH0pXG4gICAgLmZpbGwoZGVlcClcbiAgICAubWFwKCgpID0+IHtcbiAgICAgIGNvbnN0IGNoaWxkcmVuTnVtYmVyID1cbiAgICAgICAgZGVlcCA9PT0gbWF4RGVlcCA/IDAgOiBNYXRoLnJvdW5kKE1hdGgucmFuZG9tKCkgKiBtYXhDaGlsZHJlbilcbiAgICAgIGNvbnN0IG5vZGVLZXkgPSBnZXRLZXkoa2V5LCArK2lkKVxuICAgICAgcmV0dXJuIHtcbiAgICAgICAgaWQ6IG5vZGVLZXksXG4gICAgICAgIGxhYmVsOiBub2RlS2V5LFxuICAgICAgICBjaGlsZHJlbjogY2hpbGRyZW5OdW1iZXJcbiAgICAgICAgICA/IGNyZWF0ZURhdGEobWF4RGVlcCwgbWF4Q2hpbGRyZW4sIGNoaWxkcmVuTnVtYmVyLCBkZWVwICsgMSwgbm9kZUtleSlcbiAgICAgICAgICA6IHVuZGVmaW5lZCxcbiAgICAgIH1cbiAgICB9KVxufVxuXG5jb25zdCBwcm9wcyA9IHtcbiAgdmFsdWU6ICdpZCcsXG4gIGxhYmVsOiAnbGFiZWwnLFxuICBjaGlsZHJlbjogJ2NoaWxkcmVuJyxcbn1cbmNvbnN0IGRhdGEgPSBjcmVhdGVEYXRhKDQsIDMwLCA0MClcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-v2/basic.vue)_

vue

```
<template>
  <el-tree-v2
    style="max-width: 600px"
    :data="data"
    :props="props"
    :height="200"
  />
</template>

<script lang="ts" setup>
interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = 'node'
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const props = {
  value: 'id',
  label: 'label',
  children: 'children',
}
const data = createData(4, 30, 40)
</script>
```

隐藏源代码

## 可选择的虚拟树 [​](#可选择的虚拟树)

适用于需要选择层级时使用。

node-1

node-2

node-3

node-4

node-5

node-6

node-7

node-8

node-9

node-10

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS12MlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgc2hvdy1jaGVja2JveFxuICAgIDpoZWlnaHQ9XCIyMDBcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmludGVyZmFjZSBUcmVlIHtcbiAgaWQ6IHN0cmluZ1xuICBsYWJlbDogc3RyaW5nXG4gIGNoaWxkcmVuPzogVHJlZVtdXG59XG5cbmNvbnN0IGdldEtleSA9IChwcmVmaXg6IHN0cmluZywgaWQ6IG51bWJlcikgPT4ge1xuICByZXR1cm4gYCR7cHJlZml4fS0ke2lkfWBcbn1cblxuY29uc3QgY3JlYXRlRGF0YSA9IChcbiAgbWF4RGVlcDogbnVtYmVyLFxuICBtYXhDaGlsZHJlbjogbnVtYmVyLFxuICBtaW5Ob2Rlc051bWJlcjogbnVtYmVyLFxuICBkZWVwID0gMSxcbiAga2V5ID0gJ25vZGUnXG4pOiBUcmVlW10gPT4ge1xuICBsZXQgaWQgPSAwXG4gIHJldHVybiBBcnJheS5mcm9tKHsgbGVuZ3RoOiBtaW5Ob2Rlc051bWJlciB9KVxuICAgIC5maWxsKGRlZXApXG4gICAgLm1hcCgoKSA9PiB7XG4gICAgICBjb25zdCBjaGlsZHJlbk51bWJlciA9XG4gICAgICAgIGRlZXAgPT09IG1heERlZXAgPyAwIDogTWF0aC5yb3VuZChNYXRoLnJhbmRvbSgpICogbWF4Q2hpbGRyZW4pXG4gICAgICBjb25zdCBub2RlS2V5ID0gZ2V0S2V5KGtleSwgKytpZClcbiAgICAgIHJldHVybiB7XG4gICAgICAgIGlkOiBub2RlS2V5LFxuICAgICAgICBsYWJlbDogbm9kZUtleSxcbiAgICAgICAgY2hpbGRyZW46IGNoaWxkcmVuTnVtYmVyXG4gICAgICAgICAgPyBjcmVhdGVEYXRhKG1heERlZXAsIG1heENoaWxkcmVuLCBjaGlsZHJlbk51bWJlciwgZGVlcCArIDEsIG5vZGVLZXkpXG4gICAgICAgICAgOiB1bmRlZmluZWQsXG4gICAgICB9XG4gICAgfSlcbn1cblxuY29uc3QgcHJvcHMgPSB7XG4gIHZhbHVlOiAnaWQnLFxuICBsYWJlbDogJ2xhYmVsJyxcbiAgY2hpbGRyZW46ICdjaGlsZHJlbicsXG59XG5jb25zdCBkYXRhID0gY3JlYXRlRGF0YSg0LCAzMCwgNDApXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-v2/selectable.vue)_

vue

```
<template>
  <el-tree-v2
    style="max-width: 600px"
    :data="data"
    :props="props"
    show-checkbox
    :height="200"
  />
</template>

<script lang="ts" setup>
interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = 'node'
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const props = {
  value: 'id',
  label: 'label',
  children: 'children',
}
const data = createData(4, 30, 40)
</script>
```

隐藏源代码

WARNING

在使用 show-checkbox 时，因为 `check-on-click-leaf` 默认值为 true， 最后一个树节点可以通过点击节点进行勾选。

## 禁用复选框 [​](#禁用复选框)

节点的复选框可以设置为禁用。

在示例中，属性在 defaultProps 中声明了 `disabled`，一些节点被设置为 `disabled：true`。 相应的复选框已禁用，不能点击。

node-1

node-2

node-3

node-4

node-5

node-6

node-7

node-8

node-9

node-10

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS12MlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgc2hvdy1jaGVja2JveFxuICAgIDpoZWlnaHQ9XCIyMDBcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmludGVyZmFjZSBUcmVlIHtcbiAgaWQ6IHN0cmluZ1xuICBsYWJlbDogc3RyaW5nXG4gIGNoaWxkcmVuPzogVHJlZVtdXG4gIGRpc2FibGVkOiBib29sZWFuXG59XG5cbmNvbnN0IGdldEtleSA9IChwcmVmaXg6IHN0cmluZywgaWQ6IG51bWJlcikgPT4ge1xuICByZXR1cm4gYCR7cHJlZml4fS0ke2lkfWBcbn1cblxuY29uc3QgY3JlYXRlRGF0YSA9IChcbiAgbWF4RGVlcDogbnVtYmVyLFxuICBtYXhDaGlsZHJlbjogbnVtYmVyLFxuICBtaW5Ob2Rlc051bWJlcjogbnVtYmVyLFxuICBkZWVwID0gMSxcbiAga2V5ID0gJ25vZGUnXG4pOiBUcmVlW10gPT4ge1xuICBsZXQgaWQgPSAwXG4gIHJldHVybiBBcnJheS5mcm9tKHsgbGVuZ3RoOiBtaW5Ob2Rlc051bWJlciB9KVxuICAgIC5maWxsKGRlZXApXG4gICAgLm1hcCgoKSA9PiB7XG4gICAgICBjb25zdCBjaGlsZHJlbk51bWJlciA9XG4gICAgICAgIGRlZXAgPT09IG1heERlZXAgPyAwIDogTWF0aC5yb3VuZChNYXRoLnJhbmRvbSgpICogbWF4Q2hpbGRyZW4pXG4gICAgICBjb25zdCBub2RlS2V5ID0gZ2V0S2V5KGtleSwgKytpZClcbiAgICAgIHJldHVybiB7XG4gICAgICAgIGlkOiBub2RlS2V5LFxuICAgICAgICBsYWJlbDogbm9kZUtleSxcbiAgICAgICAgY2hpbGRyZW46IGNoaWxkcmVuTnVtYmVyXG4gICAgICAgICAgPyBjcmVhdGVEYXRhKG1heERlZXAsIG1heENoaWxkcmVuLCBjaGlsZHJlbk51bWJlciwgZGVlcCArIDEsIG5vZGVLZXkpXG4gICAgICAgICAgOiB1bmRlZmluZWQsXG4gICAgICAgIGRpc2FibGVkOiBub2RlS2V5LmluY2x1ZGVzKCcyJyksXG4gICAgICB9XG4gICAgfSlcbn1cblxuY29uc3QgcHJvcHMgPSB7XG4gIHZhbHVlOiAnaWQnLFxuICBsYWJlbDogJ2xhYmVsJyxcbiAgY2hpbGRyZW46ICdjaGlsZHJlbicsXG4gIGRpc2FibGVkOiAnZGlzYWJsZWQnLFxufVxuY29uc3QgZGF0YSA9IGNyZWF0ZURhdGEoNCwgMzAsIDQwKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-v2/disabled.vue)_

vue

```
<template>
  <el-tree-v2
    style="max-width: 600px"
    :data="data"
    :props="props"
    show-checkbox
    :height="200"
  />
</template>

<script lang="ts" setup>
interface Tree {
  id: string
  label: string
  children?: Tree[]
  disabled: boolean
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = 'node'
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
        disabled: nodeKey.includes('2'),
      }
    })
}

const props = {
  value: 'id',
  label: 'label',
  children: 'children',
  disabled: 'disabled',
}
const data = createData(4, 30, 40)
</script>
```

隐藏源代码

## 默认扩展和默认检查 [​](#默认扩展和默认检查)

树节点可以在初始化阶段被设置为展开或选中。

分别通过 `default-expanded-keys` 和 `default-checked-keys` 设置默认展开和默认选中的节点。

node-1

node-1-1

node-1-2

node-1-3

node-1-4

node-1-5

node-1-6

node-1-7

node-1-8

node-1-9

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS12MlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6aGVpZ2h0PVwiMjAwXCJcbiAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgc2hvdy1jaGVja2JveFxuICAgIDpkZWZhdWx0LWNoZWNrZWQta2V5cz1cImRlZmF1bHRDaGVja2VkS2V5c1wiXG4gICAgOmRlZmF1bHQtZXhwYW5kZWQta2V5cz1cImRlZmF1bHRFeHBhbmRlZEtleXNcIlxuICAvPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW50ZXJmYWNlIFRyZWUge1xuICBpZDogc3RyaW5nXG4gIGxhYmVsOiBzdHJpbmdcbiAgY2hpbGRyZW4/OiBUcmVlW11cbn1cblxuY29uc3QgZ2V0S2V5ID0gKHByZWZpeDogc3RyaW5nLCBpZDogbnVtYmVyKSA9PiB7XG4gIHJldHVybiBgJHtwcmVmaXh9LSR7aWR9YFxufVxuXG5jb25zdCBjcmVhdGVEYXRhID0gKFxuICBtYXhEZWVwOiBudW1iZXIsXG4gIG1heENoaWxkcmVuOiBudW1iZXIsXG4gIG1pbk5vZGVzTnVtYmVyOiBudW1iZXIsXG4gIGRlZXAgPSAxLFxuICBrZXkgPSAnbm9kZSdcbik6IFRyZWVbXSA9PiB7XG4gIGxldCBpZCA9IDBcbiAgcmV0dXJuIEFycmF5LmZyb20oeyBsZW5ndGg6IG1pbk5vZGVzTnVtYmVyIH0pXG4gICAgLmZpbGwoZGVlcClcbiAgICAubWFwKCgpID0+IHtcbiAgICAgIGNvbnN0IGNoaWxkcmVuTnVtYmVyID1cbiAgICAgICAgZGVlcCA9PT0gbWF4RGVlcCA/IDAgOiBNYXRoLnJvdW5kKE1hdGgucmFuZG9tKCkgKiBtYXhDaGlsZHJlbilcbiAgICAgIGNvbnN0IG5vZGVLZXkgPSBnZXRLZXkoa2V5LCArK2lkKVxuICAgICAgcmV0dXJuIHtcbiAgICAgICAgaWQ6IG5vZGVLZXksXG4gICAgICAgIGxhYmVsOiBub2RlS2V5LFxuICAgICAgICBjaGlsZHJlbjogY2hpbGRyZW5OdW1iZXJcbiAgICAgICAgICA/IGNyZWF0ZURhdGEobWF4RGVlcCwgbWF4Q2hpbGRyZW4sIGNoaWxkcmVuTnVtYmVyLCBkZWVwICsgMSwgbm9kZUtleSlcbiAgICAgICAgICA6IHVuZGVmaW5lZCxcbiAgICAgIH1cbiAgICB9KVxufVxuXG5jb25zdCBwcm9wcyA9IHtcbiAgdmFsdWU6ICdpZCcsXG4gIGxhYmVsOiAnbGFiZWwnLFxuICBjaGlsZHJlbjogJ2NoaWxkcmVuJyxcbn1cbmNvbnN0IGRhdGEgPSBjcmVhdGVEYXRhKDQsIDMwLCA0MClcbmNvbnN0IGNoZWNrZWRLZXlzOiBzdHJpbmdbXSA9IFtdXG5jb25zdCBleHBhbmVkS2V5czogc3RyaW5nW10gPSBbXVxuZm9yIChjb25zdCBkYXR1bSBvZiBkYXRhKSB7XG4gIGNvbnN0IGNoaWxkcmVuID0gZGF0dW0uY2hpbGRyZW5cbiAgaWYgKGNoaWxkcmVuKSB7XG4gICAgZXhwYW5lZEtleXMucHVzaChkYXR1bS5pZClcbiAgICBjaGVja2VkS2V5cy5wdXNoKGNoaWxkcmVuWzBdLmlkKVxuICAgIGJyZWFrXG4gIH1cbn1cblxuY29uc3QgZGVmYXVsdENoZWNrZWRLZXlzID0gcmVmKGNoZWNrZWRLZXlzKVxuY29uc3QgZGVmYXVsdEV4cGFuZGVkS2V5cyA9IHJlZihleHBhbmVkS2V5cylcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-v2/default-state.vue)_

vue

```
<template>
  <el-tree-v2
    style="max-width: 600px"
    :data="data"
    :height="200"
    :props="props"
    show-checkbox
    :default-checked-keys="defaultCheckedKeys"
    :default-expanded-keys="defaultExpandedKeys"
  />
</template>

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

interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = 'node'
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const props = {
  value: 'id',
  label: 'label',
  children: 'children',
}
const data = createData(4, 30, 40)
const checkedKeys: string[] = []
const expanedKeys: string[] = []
for (const datum of data) {
  const children = datum.children
  if (children) {
    expanedKeys.push(datum.id)
    checkedKeys.push(children[0].id)
    break
  }
}

const defaultCheckedKeys = ref(checkedKeys)
const defaultExpandedKeys = ref(expanedKeys)
</script>
```

隐藏源代码

## 自定义节点内容 [​](#自定义节点内容)

节点的内容支持自定义，可以在节点区添加按钮或图标等内容

\[ElementPlus\]node-1

\[ElementPlus\]node-2

\[ElementPlus\]node-3

\[ElementPlus\]node-4

\[ElementPlus\]node-5

\[ElementPlus\]node-6

\[ElementPlus\]node-7

\[ElementPlus\]node-8

\[ElementPlus\]node-9

\[ElementPlus\]node-10

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS12MlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgOmhlaWdodD1cIjIwMFwiXG4gID5cbiAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJ7IG5vZGUgfVwiPlxuICAgICAgPGVsLWljb24gY2xhc3M9XCJlbC1pY29uLS1sZWZ0XCI+XG4gICAgICAgIDxEb2N1bWVudCB2LWlmPVwibm9kZS5pc0xlYWZcIiAvPlxuICAgICAgICA8Rm9sZGVyIHYtZWxzZS1pZj1cIiFub2RlLmV4cGFuZGVkXCIgLz5cbiAgICAgICAgPEZvbGRlck9wZW5lZCB2LWVsc2UgLz5cbiAgICAgIDwvZWwtaWNvbj5cbiAgICAgIDxzcGFuIGNsYXNzPVwicHJlZml4XCIgOmNsYXNzPVwieyAnaXMtbGVhZic6IG5vZGUuaXNMZWFmIH1cIlxuICAgICAgICA+W0VsZW1lbnRQbHVzXTwvc3BhblxuICAgICAgPlxuICAgICAgPHNwYW4+e3sgbm9kZS5sYWJlbCB9fTwvc3Bhbj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLXRyZWUtdjI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRG9jdW1lbnQsIEZvbGRlciwgRm9sZGVyT3BlbmVkIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmludGVyZmFjZSBUcmVlIHtcbiAgaWQ6IHN0cmluZ1xuICBsYWJlbDogc3RyaW5nXG4gIGNoaWxkcmVuPzogVHJlZVtdXG59XG5cbmNvbnN0IGdldEtleSA9IChwcmVmaXg6IHN0cmluZywgaWQ6IG51bWJlcikgPT4ge1xuICByZXR1cm4gYCR7cHJlZml4fS0ke2lkfWBcbn1cblxuY29uc3QgY3JlYXRlRGF0YSA9IChcbiAgbWF4RGVlcDogbnVtYmVyLFxuICBtYXhDaGlsZHJlbjogbnVtYmVyLFxuICBtaW5Ob2Rlc051bWJlcjogbnVtYmVyLFxuICBkZWVwID0gMSxcbiAga2V5ID0gJ25vZGUnXG4pOiBUcmVlW10gPT4ge1xuICBsZXQgaWQgPSAwXG4gIHJldHVybiBBcnJheS5mcm9tKHsgbGVuZ3RoOiBtaW5Ob2Rlc051bWJlciB9KVxuICAgIC5maWxsKGRlZXApXG4gICAgLm1hcCgoKSA9PiB7XG4gICAgICBjb25zdCBjaGlsZHJlbk51bWJlciA9XG4gICAgICAgIGRlZXAgPT09IG1heERlZXAgPyAwIDogTWF0aC5yb3VuZChNYXRoLnJhbmRvbSgpICogbWF4Q2hpbGRyZW4pXG4gICAgICBjb25zdCBub2RlS2V5ID0gZ2V0S2V5KGtleSwgKytpZClcbiAgICAgIHJldHVybiB7XG4gICAgICAgIGlkOiBub2RlS2V5LFxuICAgICAgICBsYWJlbDogbm9kZUtleSxcbiAgICAgICAgY2hpbGRyZW46IGNoaWxkcmVuTnVtYmVyXG4gICAgICAgICAgPyBjcmVhdGVEYXRhKG1heERlZXAsIG1heENoaWxkcmVuLCBjaGlsZHJlbk51bWJlciwgZGVlcCArIDEsIG5vZGVLZXkpXG4gICAgICAgICAgOiB1bmRlZmluZWQsXG4gICAgICB9XG4gICAgfSlcbn1cblxuY29uc3QgcHJvcHMgPSB7XG4gIHZhbHVlOiAnaWQnLFxuICBsYWJlbDogJ2xhYmVsJyxcbiAgY2hpbGRyZW46ICdjaGlsZHJlbicsXG59XG5jb25zdCBkYXRhID0gY3JlYXRlRGF0YSg0LCAzMCwgNDApXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5wcmVmaXgge1xuICBjb2xvcjogdmFyKC0tZWwtY29sb3ItcHJpbWFyeSk7XG4gIG1hcmdpbi1yaWdodDogMTBweDtcbn1cbi5wcmVmaXguaXMtbGVhZiB7XG4gIGNvbG9yOiB2YXIoLS1lbC1jb2xvci1zdWNjZXNzKTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-v2/custom-node.vue)_

vue

```
<template>
  <el-tree-v2
    style="max-width: 600px"
    :data="data"
    :props="props"
    :height="200"
  >
    <template #default="{ node }">
      <el-icon class="el-icon--left">
        <Document v-if="node.isLeaf" />
        <Folder v-else-if="!node.expanded" />
        <FolderOpened v-else />
      </el-icon>
      <span class="prefix" :class="{ 'is-leaf': node.isLeaf }"
        >[ElementPlus]</span
      >
      <span>{{ node.label }}</span>
    </template>
  </el-tree-v2>
</template>

<script lang="ts" setup>
import { Document, Folder, FolderOpened } from '@element-plus/icons-vue'

interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = 'node'
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const props = {
  value: 'id',
  label: 'label',
  children: 'children',
}
const data = createData(4, 30, 40)
</script>

<style scoped>
.prefix {
  color: var(--el-color-primary);
  margin-right: 10px;
}
.prefix.is-leaf {
  color: var(--el-color-success);
}
</style>
```

隐藏源代码

## 自定义节点类 2.9.0 [​](#自定义节点类)

节点的类名支持自定义。

Level one 1

Level one 2

Level one 3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS12MlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICBzaG93LWNoZWNrYm94XG4gICAgOmV4cGFuZC1vbi1jbGljay1ub2RlPVwiZmFsc2VcIlxuICAgIDpwcm9wcz1cInsgY2xhc3M6IGN1c3RvbU5vZGVDbGFzcyB9XCJcbiAgLz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgdHlwZSB7IFRyZWVOb2RlLCBUcmVlTm9kZURhdGEgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmludGVyZmFjZSBUcmVlIHtcbiAgaWQ/OiBzdHJpbmdcbiAgdmFsdWU/OiBzdHJpbmdcbiAgbGFiZWw/OiBzdHJpbmdcbiAgaXNQZW51bHRpbWF0ZT86IGJvb2xlYW5cbiAgY2hpbGRyZW4/OiBUcmVlW11cbn1cblxuY29uc3QgY3VzdG9tTm9kZUNsYXNzID0gKHsgaXNQZW51bHRpbWF0ZSB9OiBUcmVlTm9kZURhdGEsIG5vZGU6IFRyZWVOb2RlKSA9PlxuICBpc1BlbnVsdGltYXRlID8gJ2lzLXBlbnVsdGltYXRlJyA6ICcnXG5cbmNvbnN0IGRhdGE6IFRyZWVbXSA9IFtcbiAge1xuICAgIGlkOiAnMScsXG4gICAgbGFiZWw6ICdMZXZlbCBvbmUgMScsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgaWQ6ICc0JyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMS0xJyxcbiAgICAgICAgaXNQZW51bHRpbWF0ZTogdHJ1ZSxcbiAgICAgICAgY2hpbGRyZW46IFtcbiAgICAgICAgICB7XG4gICAgICAgICAgICBpZDogJzknLFxuICAgICAgICAgICAgbGFiZWw6ICdMZXZlbCB0aHJlZSAxLTEtMScsXG4gICAgICAgICAgfSxcbiAgICAgICAgICB7XG4gICAgICAgICAgICBpZDogJzEwJyxcbiAgICAgICAgICAgIGxhYmVsOiAnTGV2ZWwgdGhyZWUgMS0xLTInLFxuICAgICAgICAgIH0sXG4gICAgICAgIF0sXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICBpZDogJzInLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDInLFxuICAgIGlzUGVudWx0aW1hdGU6IHRydWUsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgaWQ6ICc1JyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMi0xJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIGlkOiAnNicsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDItMicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG4gIHtcbiAgICBpZDogJzMnLFxuICAgIGxhYmVsOiAnTGV2ZWwgb25lIDMnLFxuICAgIGlzUGVudWx0aW1hdGU6IHRydWUsXG4gICAgY2hpbGRyZW46IFtcbiAgICAgIHtcbiAgICAgICAgaWQ6ICc3JyxcbiAgICAgICAgbGFiZWw6ICdMZXZlbCB0d28gMy0xJyxcbiAgICAgIH0sXG4gICAgICB7XG4gICAgICAgIGlkOiAnOCcsXG4gICAgICAgIGxhYmVsOiAnTGV2ZWwgdHdvIDMtMicsXG4gICAgICB9LFxuICAgIF0sXG4gIH0sXG5dXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbjpkZWVwKC5pcy1wZW51bHRpbWF0ZSAuZWwtdHJlZS1ub2RlX19sYWJlbCkge1xuICBjb2xvcjogIzYyNmFlZjtcbiAgZm9udC13ZWlnaHQ6IDYwMDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-v2/custom-node-class.vue)_

vue

```
<template>
  <el-tree-v2
    style="max-width: 600px"
    :data="data"
    show-checkbox
    :expand-on-click-node="false"
    :props="{ class: customNodeClass }"
  />
</template>

<script lang="ts" setup>
import type { TreeNode, TreeNodeData } from 'element-plus'

interface Tree {
  id?: string
  value?: string
  label?: string
  isPenultimate?: boolean
  children?: Tree[]
}

const customNodeClass = ({ isPenultimate }: TreeNodeData, node: TreeNode) =>
  isPenultimate ? 'is-penultimate' : ''

const data: Tree[] = [
  {
    id: '1',
    label: 'Level one 1',
    children: [
      {
        id: '4',
        label: 'Level two 1-1',
        isPenultimate: true,
        children: [
          {
            id: '9',
            label: 'Level three 1-1-1',
          },
          {
            id: '10',
            label: 'Level three 1-1-2',
          },
        ],
      },
    ],
  },
  {
    id: '2',
    label: 'Level one 2',
    isPenultimate: true,
    children: [
      {
        id: '5',
        label: 'Level two 2-1',
      },
      {
        id: '6',
        label: 'Level two 2-2',
      },
    ],
  },
  {
    id: '3',
    label: 'Level one 3',
    isPenultimate: true,
    children: [
      {
        id: '7',
        label: 'Level two 3-1',
      },
      {
        id: '8',
        label: 'Level two 3-2',
      },
    ],
  },
]
</script>

<style scoped>
:deep(.is-penultimate .el-tree-node__label) {
  color: #626aef;
  font-weight: 600;
}
</style>
```

隐藏源代码

## 自定义图标 2.10.3 [​](#自定义图标)

您可以自定义不同节点状态的图标。 树节点暴露了 `expanded` 属性和 `isLeaf` 属性，允许你根据节点的状态动态渲染不同的图标：叶子节点、展开的节点或折叠的节点。

node-1

node-2

node-3

node-4

node-5

node-6

node-7

node-8

node-9

node-10

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdHJlZS12MlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOmRhdGE9XCJkYXRhXCJcbiAgICA6cHJvcHM9XCJwcm9wc1wiXG4gICAgOmhlaWdodD1cIjIwMFwiXG4gID5cbiAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJ7IG5vZGUgfVwiPlxuICAgICAgPGVsLWljb24gY2xhc3M9XCJub2RlLWljb25cIiA6Y2xhc3M9XCJ7ICdpcy1sZWFmJzogbm9kZS5pc0xlYWYgfVwiPlxuICAgICAgICA8RG9jdW1lbnQgdi1pZj1cIm5vZGUuaXNMZWFmXCIgLz5cbiAgICAgICAgPEZvbGRlciB2LWVsc2UtaWY9XCIhbm9kZS5leHBhbmRlZFwiIC8+XG4gICAgICAgIDxGb2xkZXJPcGVuZWQgdi1lbHNlIC8+XG4gICAgICA8L2VsLWljb24+XG4gICAgICA8c3Bhbj57eyBub2RlLmxhYmVsIH19PC9zcGFuPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtdHJlZS12Mj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBEb2N1bWVudCwgRm9sZGVyLCBGb2xkZXJPcGVuZWQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuaW50ZXJmYWNlIFRyZWUge1xuICBpZDogc3RyaW5nXG4gIGxhYmVsOiBzdHJpbmdcbiAgY2hpbGRyZW4/OiBUcmVlW11cbn1cblxuY29uc3QgZ2V0S2V5ID0gKHByZWZpeDogc3RyaW5nLCBpZDogbnVtYmVyKSA9PiB7XG4gIHJldHVybiBgJHtwcmVmaXh9LSR7aWR9YFxufVxuXG5jb25zdCBjcmVhdGVEYXRhID0gKFxuICBtYXhEZWVwOiBudW1iZXIsXG4gIG1heENoaWxkcmVuOiBudW1iZXIsXG4gIG1pbk5vZGVzTnVtYmVyOiBudW1iZXIsXG4gIGRlZXAgPSAxLFxuICBrZXkgPSAnbm9kZSdcbik6IFRyZWVbXSA9PiB7XG4gIGxldCBpZCA9IDBcbiAgcmV0dXJuIEFycmF5LmZyb20oeyBsZW5ndGg6IG1pbk5vZGVzTnVtYmVyIH0pXG4gICAgLmZpbGwoZGVlcClcbiAgICAubWFwKCgpID0+IHtcbiAgICAgIGNvbnN0IGNoaWxkcmVuTnVtYmVyID1cbiAgICAgICAgZGVlcCA9PT0gbWF4RGVlcCA/IDAgOiBNYXRoLnJvdW5kKE1hdGgucmFuZG9tKCkgKiBtYXhDaGlsZHJlbilcbiAgICAgIGNvbnN0IG5vZGVLZXkgPSBnZXRLZXkoa2V5LCArK2lkKVxuICAgICAgcmV0dXJuIHtcbiAgICAgICAgaWQ6IG5vZGVLZXksXG4gICAgICAgIGxhYmVsOiBub2RlS2V5LFxuICAgICAgICBjaGlsZHJlbjogY2hpbGRyZW5OdW1iZXJcbiAgICAgICAgICA/IGNyZWF0ZURhdGEobWF4RGVlcCwgbWF4Q2hpbGRyZW4sIGNoaWxkcmVuTnVtYmVyLCBkZWVwICsgMSwgbm9kZUtleSlcbiAgICAgICAgICA6IHVuZGVmaW5lZCxcbiAgICAgIH1cbiAgICB9KVxufVxuXG5jb25zdCBwcm9wcyA9IHtcbiAgdmFsdWU6ICdpZCcsXG4gIGxhYmVsOiAnbGFiZWwnLFxuICBjaGlsZHJlbjogJ2NoaWxkcmVuJyxcbn1cbmNvbnN0IGRhdGEgPSBjcmVhdGVEYXRhKDQsIDMwLCA0MClcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLm5vZGUtaWNvbiB7XG4gIG1hcmdpbi1yaWdodDogNXB4O1xuICBjb2xvcjogdmFyKC0tZWwtY29sb3Itd2FybmluZyk7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-v2/custom-icon.vue)_

vue

```
<template>
  <el-tree-v2
    style="max-width: 600px"
    :data="data"
    :props="props"
    :height="200"
  >
    <template #default="{ node }">
      <el-icon class="node-icon" :class="{ 'is-leaf': node.isLeaf }">
        <Document v-if="node.isLeaf" />
        <Folder v-else-if="!node.expanded" />
        <FolderOpened v-else />
      </el-icon>
      <span>{{ node.label }}</span>
    </template>
  </el-tree-v2>
</template>

<script lang="ts" setup>
import { Document, Folder, FolderOpened } from '@element-plus/icons-vue'

interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = 'node'
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const props = {
  value: 'id',
  label: 'label',
  children: 'children',
}
const data = createData(4, 30, 40)
</script>

<style scoped>
.node-icon {
  margin-right: 5px;
  color: var(--el-color-warning);
}
</style>
```

隐藏源代码

## 树节点过滤 2.9.1 [​](#树节点过滤)

`filter-method` 方法只有在版本 `2.9.1` 之后才能接受第三个参数。 树节点是可以被过滤的

在需要对节点进行过滤时，调用 Tree 实例的 `filter` 方法， 参数为关键字。 需要注意的是，此时需要设置 `filter-method`，值为过滤函数。

node-1

node-2

node-3

node-4

node-5

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtaW5wdXRcbiAgICB2LW1vZGVsPVwicXVlcnlcIlxuICAgIHN0eWxlPVwid2lkdGg6IDI0MHB4XCJcbiAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBlbnRlciBrZXl3b3JkXCJcbiAgICBAaW5wdXQ9XCJvblF1ZXJ5Q2hhbmdlZFwiXG4gIC8+XG4gIDxlbC10cmVlLXYyXG4gICAgcmVmPVwidHJlZVJlZlwiXG4gICAgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCJcbiAgICA6ZGF0YT1cImRhdGFcIlxuICAgIDpwcm9wcz1cInByb3BzXCJcbiAgICA6ZmlsdGVyLW1ldGhvZD1cImZpbHRlck1ldGhvZFwiXG4gICAgOmhlaWdodD1cIjIwMFwiXG4gIC8+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IFRyZWVOb2RlRGF0YSwgVHJlZVYySW5zdGFuY2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmludGVyZmFjZSBUcmVlIHtcbiAgaWQ6IHN0cmluZ1xuICBsYWJlbDogc3RyaW5nXG4gIGNoaWxkcmVuPzogVHJlZVtdXG59XG5cbmNvbnN0IGdldEtleSA9IChwcmVmaXg6IHN0cmluZywgaWQ6IG51bWJlcikgPT4gYCR7cHJlZml4fS0ke2lkfWBcblxuY29uc3QgY3JlYXRlRGF0YSA9IChcbiAgbWF4RGVlcDogbnVtYmVyLFxuICBtYXhDaGlsZHJlbjogbnVtYmVyLFxuICBtaW5Ob2Rlc051bWJlcjogbnVtYmVyLFxuICBkZWVwID0gMSxcbiAga2V5ID0gJ25vZGUnXG4pOiBUcmVlW10gPT4ge1xuICBsZXQgaWQgPSAwXG4gIHJldHVybiBBcnJheS5mcm9tKHsgbGVuZ3RoOiBtaW5Ob2Rlc051bWJlciB9KVxuICAgIC5maWxsKGRlZXApXG4gICAgLm1hcCgoKSA9PiB7XG4gICAgICBjb25zdCBjaGlsZHJlbk51bWJlciA9XG4gICAgICAgIGRlZXAgPT09IG1heERlZXAgPyAwIDogTWF0aC5yb3VuZChNYXRoLnJhbmRvbSgpICogbWF4Q2hpbGRyZW4pXG4gICAgICBjb25zdCBub2RlS2V5ID0gZ2V0S2V5KGtleSwgKytpZClcbiAgICAgIHJldHVybiB7XG4gICAgICAgIGlkOiBub2RlS2V5LFxuICAgICAgICBsYWJlbDogbm9kZUtleSxcbiAgICAgICAgY2hpbGRyZW46IGNoaWxkcmVuTnVtYmVyXG4gICAgICAgICAgPyBjcmVhdGVEYXRhKG1heERlZXAsIG1heENoaWxkcmVuLCBjaGlsZHJlbk51bWJlciwgZGVlcCArIDEsIG5vZGVLZXkpXG4gICAgICAgICAgOiB1bmRlZmluZWQsXG4gICAgICB9XG4gICAgfSlcbn1cblxuY29uc3QgcXVlcnkgPSByZWYoJycpXG5jb25zdCB0cmVlUmVmID0gcmVmPFRyZWVWMkluc3RhbmNlPigpXG5jb25zdCBkYXRhID0gY3JlYXRlRGF0YSg0LCAzMCwgNSlcbmNvbnN0IHByb3BzID0ge1xuICB2YWx1ZTogJ2lkJyxcbiAgbGFiZWw6ICdsYWJlbCcsXG4gIGNoaWxkcmVuOiAnY2hpbGRyZW4nLFxufVxuXG5jb25zdCBvblF1ZXJ5Q2hhbmdlZCA9IChxdWVyeTogc3RyaW5nKSA9PiB7XG4gIHRyZWVSZWYudmFsdWUhLmZpbHRlcihxdWVyeSlcbn1cbmNvbnN0IGZpbHRlck1ldGhvZCA9IChxdWVyeTogc3RyaW5nLCBub2RlOiBUcmVlTm9kZURhdGEpID0+XG4gIG5vZGUubGFiZWwhLmluY2x1ZGVzKHF1ZXJ5KVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tree-v2/filter.vue)_

vue

```
<template>
  <el-input
    v-model="query"
    style="width: 240px"
    placeholder="Please enter keyword"
    @input="onQueryChanged"
  />
  <el-tree-v2
    ref="treeRef"
    style="max-width: 600px"
    :data="data"
    :props="props"
    :filter-method="filterMethod"
    :height="200"
  />
</template>

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

import type { TreeNodeData, TreeV2Instance } from 'element-plus'

interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => `${prefix}-${id}`

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = 'node'
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const query = ref('')
const treeRef = ref<TreeV2Instance>()
const data = createData(4, 30, 5)
const props = {
  value: 'id',
  label: 'label',
  children: 'children',
}

const onQueryChanged = (query: string) => {
  treeRef.value!.filter(query)
}
const filterMethod = (query: string, node: TreeNodeData) =>
  node.label!.includes(query)
</script>
```

隐藏源代码

## TreeV2 API [​](#treev2-api)

### TreeV2 Attributes [​](#treev2-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| data | 展示数据 | `array` | — |
| empty-text | 内容为空的时候展示的文本 | `string` | — |
| [props](#props) | 配置选项，具体看下表 | `object` | — |
| highlight-current | 是否高亮当前选中节点 | `boolean` | false |
| expand-on-click-node | 是否在点击节点的时候展开或者收缩节点， 默认值为 true，如果为 false，则只有点箭头图标的时候才会展开或者收缩节点 | `boolean` | true |
| check-on-click-node | 是否在点击节点的时候选中节点，默认值为 false，即只有在点击复选框时才会选中节点 | `boolean` | false |
| check-on-click-leaf 2.9.6 | 点击叶节点(最后一个子节点)时是否检查或取消节点 | `boolean` | true |
| default-expanded-keys | 默认展开的节点的 key 的数组 | `array` | — |
| show-checkbox | 节点是否可被选择 | `boolean` | false |
| check-strictly | 在显示复选框的情况下，是否严格的遵循父子不互相关联的做法，默认为 false | `boolean` | false |
| default-checked-keys | 默认勾选的节点的 key 的数组 | `array` | — |
| current-node-key | 当前选中的节点 | `string` / `number` | — |
| filter-method | 对树节点进行筛选时执行的方法，返回 true 表示这个节点可以显示， 返回 `false` 则表示这个节点会被隐藏 | `Function` | — |
| indent | 相邻级节点间的水平缩进，单位为像素 | `number` | 16 |
| icon | 自定义树节点图标组件 | `string` / `Component` | — |
| item-size 2.2.33 | 自定义树节点的高度 | `number` | 26 |
| scrollbar-always-on 2.10.4 | 总是显示滚动条 | `boolean` | false |
| height | tree 的高度 | `number` | 200 |

### props [​](#props)

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value | 每个树节点用来作为唯一标识的属性，在整棵树中应该是唯一的 | `string` | id |
| label | 指定节点标签为节点对象的某个属性值 | `string` | label |
| children | 指定子树为节点对象的某个属性值 | `string` | children |
| disabled | 指定节点选择框是否禁用为节点对象的某个属性值 | `string` | disabled |
| class 2.9.0 | 自定义节点类名 | `string` / `Function` | — |

### TreeV2 Exposes [​](#treev2-exposes)

`Tree` 组件有以下方法，均返回当前选中的节点数组

| 方法 | 说明 | 参数 |
| --- | --- | --- |
| filter | 过滤所有树节点，过滤后的节点将被隐藏 | `(query: string)` |
| getCheckedNodes | 如果节点可以被选中，(`show-checkbox` 为 `true`), 本方法将返回当前选中节点的数组 | `(leafOnly: boolean)` |
| getCheckedKeys | 若节点可用被选中 (`show-checkbox` 为 `true`), 它将返回当前选中节点 key 的数组 | `(leafOnly: boolean)` |
| setCheckedKeys | 通过 keys 设置目前勾选的节点 | `(keys: TreeKey[])` |
| setChecked | 设置节点是否被选中，`deep`（2.14.0 新增）表示是否递归选中/取消选中子节点。 | `(key: TreeKey, checked: boolean, deep?: boolean)` |
| setExpandedKeys | 设置当前展开的节点 | `(keys: TreeKey[])` |
| getHalfCheckedNodes | 如果节点可用被选中 (`show-checkbox` 为 `true`), 它将返回当前半选中的节点组成的数组 | — |
| getHalfCheckedKeys | 若节点可被选中(`show-checkbox` 为 `true`)，则返回目前半选中的节点的 key 所组成的数组 | — |
| getCurrentKey | 获取当前被选中节点的 key，若没有节点被选中则返回 `undefined` | — |
| getCurrentNode | 获取当前被选中节点的 data，若没有节点被选中则返回 `undefined` | — |
| setCurrentKey | 通过 key 设置某个节点的当前选中状态 | `(key: TreeKey)` |
| getNode | 通过 key 或 data 获取节点 | `(data: TreeKey | TreeNodeData)` |
| expandNode | 展开指定节点 | `(node: TreeNode)` |
| collapseNode | 折叠指定节点 | `(node: TreeNode)` |
| setData | 当数据量非常庞大的时候，总是使用响应式数据将导致性能表现不佳，所以我们提供一种显式设置的方式来避免此种情况 | `(data: TreeData)` |
| scrollTo 2.8.0 | 滚动到给定位置 | `(offset: number)` |
| scrollToNode 2.8.0 | 使用给定的滚动策略滚动至指定位置 | `(key: TreeKey, strategy?: auto | smart | center | start | end)` |

### TreeV2 Events [​](#treev2-events)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| node-click | 当节点被点击的时候触发 | `(data: TreeNodeData, node: TreeNode, e: MouseEvent)` |
| node-drop 2.8.3 | 拖放到节点时触发器 | `(data: TreeNodeData, node: TreeNode, e: DragEvent)` |
| node-contextmenu | 当某一节点被鼠标右键点击时会触发该事件 | `(e: Event, data: TreeNodeData, node: TreeNode)` |
| check-change | 当复选框被点击的时候触发 | `(data: TreeNodeData, checked: boolean)` |
| check | 点击节点复选框之后触发 | `(data: TreeNodeData, info: { checkedKeys: TreeKey[],checkedNodes: TreeData, halfCheckedKeys: TreeKey[], halfCheckedNodes: TreeData,})` |
| current-change | 当前选中节点变化时触发的事件 | `(data: TreeNodeData, node: TreeNode)` |
| node-expand | 节点被展开时触发的事件 | `(data: TreeNodeData, node: TreeNode)` |
| node-collapse | 节点被关闭时触发的事件 | `(data: TreeNodeData, node: TreeNode)` |

### TreeV2 Slots [​](#treev2-slots)

| 插槽名 | 描述 | Type |
| --- | --- | --- |
| default | 自定义树节点的内容。 | `object` |
| empty 2.9.0 | 当数据为空时自定义的内容 | — |

## 类型声明 [​](#类型声明)

Show declarations

ts

```
type TreeNodeData = Record<string, any>
type TreeKey = string | number
type TreeData = TreeNodeData[]

interface TreeNode {
  key: TreeKey
  level: number
  parent?: TreeNode
  children?: TreeNode[]
  data: TreeNodeData
  disabled?: boolean
  label?: string
  isLeaf?: boolean
  expanded?: boolean
  isEffectivelyChecked?: boolean
}
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/tree-v2) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/tree-v2.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/24290011?v=4&size=64)](https://github.com/xingyixiang)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/75007029?v=4&size=64)](https://github.com/yj-liuzepeng)[![](https://avatars.githubusercontent.com/u/59350883?v=4&size=64)](https://github.com/init-qy)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/33687038?v=4&size=64)](https://github.com/guozi9999)[![](https://avatars.githubusercontent.com/u/53589602?v=4&size=64)](https://github.com/l246804)[![](https://avatars.githubusercontent.com/u/16463481?v=4&size=64)](https://github.com/hellomrbigshot)[![](https://avatars.githubusercontent.com/u/54931083?v=4&size=64)](https://github.com/wjp980108)[![](https://avatars.githubusercontent.com/u/69580637?v=4&size=64)](https://github.com/jevin98)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/14892120?v=4&size=64)](https://github.com/scvzerng)[![](https://avatars.githubusercontent.com/u/33497338?v=4&size=64)](https://github.com/MoConWu)[![](https://avatars.githubusercontent.com/u/35138018?v=4&size=64)](https://github.com/tuskermanshu)[![](https://avatars.githubusercontent.com/u/47178158?v=4&size=64)](https://github.com/Aaron-zon)[![](https://avatars.githubusercontent.com/u/159113473?v=4&size=64)](https://github.com/huangjw1997)[![](https://avatars.githubusercontent.com/u/26035718?v=4&size=64)](https://github.com/SnowingFox)[![](https://avatars.githubusercontent.com/u/5389932?v=4&size=64)](https://github.com/muuyao)[![](https://avatars.githubusercontent.com/u/77471461?v=4&size=64)](https://github.com/qinhuangdaoooo)[![](https://avatars.githubusercontent.com/u/22515951?v=4&size=64)](https://github.com/webfansplz)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/9244703?v=4&size=64)](https://github.com/JobinJia)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/49394793?v=4&size=64)](https://github.com/bxh1071)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/145281501?v=4&size=64)](https://github.com/typed-sigterm)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/49453941?v=4&size=64)](https://github.com/maxime-bc)[![](https://avatars.githubusercontent.com/u/38248854?v=4&size=64)](https://github.com/Yueyanc)

[Tree 树形控件](https://element-plus.org/zh-CN/component/tree)

[Statistic 统计组件](https://element-plus.org/zh-CN/component/statistic)




---
## [data/statistic] Statistic 统计组件
> 官方文档: https://element-plus.org/zh-CN/component/statistic.html

---

# Statistic 统计组件 [​](#statistic-统计组件)

更新日志待解决

0

显示统计数据。

## 基础用法 [​](#基础用法)

用于突出某个或某组数字时，如统计数值、金额、排名等，数值和标题前后都可以加icon、单位等元素。 可以使用 [vueuse](https://vueuse.org/core/useTransition/) 实现数值的变化动效

Daily active users

268,500

Ratio of men to women

138

/100

Total Transactions

172,000

Feedback number

562

TS

JS

_[](https://element-plus.run/?extra_packages=%40vueuse%2Fcore#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IDpndXR0ZXI9XCIxNlwiPlxuICAgIDxlbC1jb2wgOnhzPVwiMjRcIiA6c209XCIxMlwiIDptZD1cIjZcIiBjbGFzcz1cInRleHQtY2VudGVyIG1iLTRcIj5cbiAgICAgIDxlbC1zdGF0aXN0aWMgdGl0bGU9XCJEYWlseSBhY3RpdmUgdXNlcnNcIiA6dmFsdWU9XCIyNjg1MDBcIiAvPlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnhzPVwiMjRcIiA6c209XCIxMlwiIDptZD1cIjZcIiBjbGFzcz1cInRleHQtY2VudGVyIG1iLTRcIj5cbiAgICAgIDxlbC1zdGF0aXN0aWMgOnZhbHVlPVwiMTM4XCI+XG4gICAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+XG4gICAgICAgICAgPGRpdiBzdHlsZT1cImRpc3BsYXk6IGlubGluZS1mbGV4OyBhbGlnbi1pdGVtczogY2VudGVyXCI+XG4gICAgICAgICAgICBSYXRpbyBvZiBtZW4gdG8gd29tZW5cbiAgICAgICAgICAgIDxlbC1pY29uIHN0eWxlPVwibWFyZ2luLWxlZnQ6IDRweFwiIDpzaXplPVwiMTJcIj5cbiAgICAgICAgICAgICAgPE1hbGUgLz5cbiAgICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgICA8L2Rpdj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPHRlbXBsYXRlICNzdWZmaXg+LzEwMDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXN0YXRpc3RpYz5cbiAgICA8L2VsLWNvbD5cbiAgICA8ZWwtY29sIDp4cz1cIjI0XCIgOnNtPVwiMTJcIiA6bWQ9XCI2XCIgY2xhc3M9XCJ0ZXh0LWNlbnRlciBtYi00XCI+XG4gICAgICA8ZWwtc3RhdGlzdGljIHRpdGxlPVwiVG90YWwgVHJhbnNhY3Rpb25zXCIgOnZhbHVlPVwib3V0cHV0VmFsdWVcIiAvPlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnhzPVwiMjRcIiA6c209XCIxMlwiIDptZD1cIjZcIiBjbGFzcz1cInRleHQtY2VudGVyIG1iLTRcIj5cbiAgICAgIDxlbC1zdGF0aXN0aWMgdGl0bGU9XCJGZWVkYmFjayBudW1iZXJcIiA6dmFsdWU9XCI1NjJcIj5cbiAgICAgICAgPHRlbXBsYXRlICNzdWZmaXg+XG4gICAgICAgICAgPGVsLWljb24gc3R5bGU9XCJ2ZXJ0aWNhbC1hbGlnbjogLTAuMTI1ZW1cIj5cbiAgICAgICAgICAgIDxDaGF0TGluZVJvdW5kIC8+XG4gICAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1zdGF0aXN0aWM+XG4gICAgPC9lbC1jb2w+XG4gIDwvZWwtcm93PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IHVzZVRyYW5zaXRpb24gfSBmcm9tICdAdnVldXNlL2NvcmUnXG5pbXBvcnQgeyBDaGF0TGluZVJvdW5kLCBNYWxlIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmNvbnN0IHNvdXJjZSA9IHJlZigwKVxuY29uc3Qgb3V0cHV0VmFsdWUgPSB1c2VUcmFuc2l0aW9uKHNvdXJjZSwge1xuICBkdXJhdGlvbjogMTUwMCxcbn0pXG5zb3VyY2UudmFsdWUgPSAxNzIwMDBcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/statistic/basic.vue)_

vue

```
<template>
  <el-row :gutter="16">
    <el-col :xs="24" :sm="12" :md="6" class="text-center mb-4">
      <el-statistic title="Daily active users" :value="268500" />
    </el-col>
    <el-col :xs="24" :sm="12" :md="6" class="text-center mb-4">
      <el-statistic :value="138">
        <template #title>
          <div style="display: inline-flex; align-items: center">
            Ratio of men to women
            <el-icon style="margin-left: 4px" :size="12">
              <Male />
            </el-icon>
          </div>
        </template>
        <template #suffix>/100</template>
      </el-statistic>
    </el-col>
    <el-col :xs="24" :sm="12" :md="6" class="text-center mb-4">
      <el-statistic title="Total Transactions" :value="outputValue" />
    </el-col>
    <el-col :xs="24" :sm="12" :md="6" class="text-center mb-4">
      <el-statistic title="Feedback number" :value="562">
        <template #suffix>
          <el-icon style="vertical-align: -0.125em">
            <ChatLineRound />
          </el-icon>
        </template>
      </el-statistic>
    </el-col>
  </el-row>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { useTransition } from '@vueuse/core'
import { ChatLineRound, Male } from '@element-plus/icons-vue'

const source = ref(0)
const outputValue = useTransition(source, {
  duration: 1500,
})
source.value = 172000
</script>
```

隐藏源代码

## 倒计时 [​](#倒计时)

倒计时组件，支持添加其他组件来控制。

Start to grab

06:59:56

Remaining VIP time

47:59:56

Reset

Still to go until next month

06 days 09:27:39

2026-07-01

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IDpndXR0ZXI9XCIxNlwiPlxuICAgIDxlbC1jb2wgOnhzPVwiMjRcIiA6c209XCIxMlwiIDptZD1cIjhcIiBjbGFzcz1cInRleHQtY2VudGVyIG1iLTRcIj5cbiAgICAgIDxlbC1jb3VudGRvd24gdGl0bGU9XCJTdGFydCB0byBncmFiXCIgOnZhbHVlPVwidmFsdWVcIiAvPlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnhzPVwiMjRcIiA6c209XCIxMlwiIDptZD1cIjhcIiBjbGFzcz1cInRleHQtY2VudGVyIG1iLTRcIj5cbiAgICAgIDxlbC1jb3VudGRvd25cbiAgICAgICAgdGl0bGU9XCJSZW1haW5pbmcgVklQIHRpbWVcIlxuICAgICAgICBmb3JtYXQ9XCJISDptbTpzc1wiXG4gICAgICAgIDp2YWx1ZT1cInZhbHVlMVwiXG4gICAgICAvPlxuICAgICAgPGVsLWJ1dHRvbiBjbGFzcz1cImNvdW50ZG93bi1mb290ZXJcIiB0eXBlPVwicHJpbWFyeVwiIEBjbGljaz1cInJlc2V0XCI+XG4gICAgICAgIFJlc2V0XG4gICAgICA8L2VsLWJ1dHRvbj5cbiAgICA8L2VsLWNvbD5cbiAgICA8ZWwtY29sIDp4cz1cIjI0XCIgOnNtPVwiMTJcIiA6bWQ9XCI4XCIgY2xhc3M9XCJ0ZXh0LWNlbnRlciBtYi00XCI+XG4gICAgICA8ZWwtY291bnRkb3duIGZvcm1hdD1cIkREIFtkYXlzXSBISDptbTpzc1wiIDp2YWx1ZT1cInZhbHVlMlwiPlxuICAgICAgICA8dGVtcGxhdGUgI3RpdGxlPlxuICAgICAgICAgIDxkaXYgc3R5bGU9XCJkaXNwbGF5OiBpbmxpbmUtZmxleDsgYWxpZ24taXRlbXM6IGNlbnRlclwiPlxuICAgICAgICAgICAgPGVsLWljb24gc3R5bGU9XCJtYXJnaW4tcmlnaHQ6IDRweFwiIDpzaXplPVwiMTJcIj5cbiAgICAgICAgICAgICAgPENhbGVuZGFyIC8+XG4gICAgICAgICAgICA8L2VsLWljb24+XG4gICAgICAgICAgICBTdGlsbCB0byBnbyB1bnRpbCBuZXh0IG1vbnRoXG4gICAgICAgICAgPC9kaXY+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLWNvdW50ZG93bj5cbiAgICAgIDxkaXYgY2xhc3M9XCJjb3VudGRvd24tZm9vdGVyXCI+e3sgdmFsdWUyLmZvcm1hdCgnWVlZWS1NTS1ERCcpIH19PC9kaXY+XG4gICAgPC9lbC1jb2w+XG4gIDwvZWwtcm93PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCBkYXlqcyBmcm9tICdkYXlqcydcbmltcG9ydCB7IENhbGVuZGFyIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKERhdGUubm93KCkgKyAxMDAwICogNjAgKiA2MCAqIDcpXG5jb25zdCB2YWx1ZTEgPSByZWYoRGF0ZS5ub3coKSArIDEwMDAgKiA2MCAqIDYwICogMjQgKiAyKVxuY29uc3QgdmFsdWUyID0gcmVmKGRheWpzKCkuYWRkKDEsICdtb250aCcpLnN0YXJ0T2YoJ21vbnRoJykpXG5cbmZ1bmN0aW9uIHJlc2V0KCkge1xuICB2YWx1ZTEudmFsdWUgPSBEYXRlLm5vdygpICsgMTAwMCAqIDYwICogNjAgKiAyNCAqIDJcbn1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmNvdW50ZG93bi1mb290ZXIge1xuICBtYXJnaW4tdG9wOiA4cHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/statistic/countdown.vue)_

vue

```
<template>
  <el-row :gutter="16">
    <el-col :xs="24" :sm="12" :md="8" class="text-center mb-4">
      <el-countdown title="Start to grab" :value="value" />
    </el-col>
    <el-col :xs="24" :sm="12" :md="8" class="text-center mb-4">
      <el-countdown
        title="Remaining VIP time"
        format="HH:mm:ss"
        :value="value1"
      />
      <el-button class="countdown-footer" type="primary" @click="reset">
        Reset
      </el-button>
    </el-col>
    <el-col :xs="24" :sm="12" :md="8" class="text-center mb-4">
      <el-countdown format="DD [days] HH:mm:ss" :value="value2">
        <template #title>
          <div style="display: inline-flex; align-items: center">
            <el-icon style="margin-right: 4px" :size="12">
              <Calendar />
            </el-icon>
            Still to go until next month
          </div>
        </template>
      </el-countdown>
      <div class="countdown-footer">{{ value2.format('YYYY-MM-DD') }}</div>
    </el-col>
  </el-row>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import dayjs from 'dayjs'
import { Calendar } from '@element-plus/icons-vue'

const value = ref(Date.now() + 1000 * 60 * 60 * 7)
const value1 = ref(Date.now() + 1000 * 60 * 60 * 24 * 2)
const value2 = ref(dayjs().add(1, 'month').startOf('month'))

function reset() {
  value1.value = Date.now() + 1000 * 60 * 60 * 24 * 2
}
</script>

<style scoped>
.countdown-footer {
  margin-top: 8px;
}
</style>
```

隐藏源代码

TIP

在格式化过程中，建议在天数范围内

## 统计卡片 [​](#统计卡片)

卡片式用法展示，可以自由组合

Daily active users

98,500

than yesterday 24%

Monthly Active Users

693,700

month on month 12%

New transactions today

72,000

than yesterday 16%

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IDpndXR0ZXI9XCIxNlwiPlxuICAgIDxlbC1jb2wgOnhzPVwiMjRcIiA6c209XCIxMlwiIDptZD1cIjhcIiBjbGFzcz1cIm1iLTRcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJzdGF0aXN0aWMtY2FyZFwiPlxuICAgICAgICA8ZWwtc3RhdGlzdGljIDp2YWx1ZT1cIjk4NTAwXCI+XG4gICAgICAgICAgPHRlbXBsYXRlICN0aXRsZT5cbiAgICAgICAgICAgIDxkaXYgc3R5bGU9XCJkaXNwbGF5OiBpbmxpbmUtZmxleDsgYWxpZ24taXRlbXM6IGNlbnRlclwiPlxuICAgICAgICAgICAgICBEYWlseSBhY3RpdmUgdXNlcnNcbiAgICAgICAgICAgICAgPGVsLXRvb2x0aXBcbiAgICAgICAgICAgICAgICBlZmZlY3Q9XCJkYXJrXCJcbiAgICAgICAgICAgICAgICBjb250ZW50PVwiTnVtYmVyIG9mIHVzZXJzIHdobyBsb2dnZWQgaW50byB0aGUgcHJvZHVjdCBpbiBvbmUgZGF5XCJcbiAgICAgICAgICAgICAgICBwbGFjZW1lbnQ9XCJ0b3BcIlxuICAgICAgICAgICAgICA+XG4gICAgICAgICAgICAgICAgPGVsLWljb24gc3R5bGU9XCJtYXJnaW4tbGVmdDogNHB4XCIgOnNpemU9XCIxMlwiPlxuICAgICAgICAgICAgICAgICAgPFdhcm5pbmcgLz5cbiAgICAgICAgICAgICAgICA8L2VsLWljb24+XG4gICAgICAgICAgICAgIDwvZWwtdG9vbHRpcD5cbiAgICAgICAgICAgIDwvZGl2PlxuICAgICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDwvZWwtc3RhdGlzdGljPlxuICAgICAgICA8ZGl2IGNsYXNzPVwic3RhdGlzdGljLWZvb3RlclwiPlxuICAgICAgICAgIDxkaXYgY2xhc3M9XCJmb290ZXItaXRlbVwiPlxuICAgICAgICAgICAgPHNwYW4+dGhhbiB5ZXN0ZXJkYXk8L3NwYW4+XG4gICAgICAgICAgICA8c3BhbiBjbGFzcz1cImdyZWVuXCI+XG4gICAgICAgICAgICAgIDI0JVxuICAgICAgICAgICAgICA8ZWwtaWNvbj5cbiAgICAgICAgICAgICAgICA8Q2FyZXRUb3AgLz5cbiAgICAgICAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICAgICAgPC9zcGFuPlxuICAgICAgICAgIDwvZGl2PlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZGl2PlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnhzPVwiMjRcIiA6c209XCIxMlwiIDptZD1cIjhcIiBjbGFzcz1cIm1iLTRcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJzdGF0aXN0aWMtY2FyZFwiPlxuICAgICAgICA8ZWwtc3RhdGlzdGljIDp2YWx1ZT1cIjY5MzcwMFwiPlxuICAgICAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+XG4gICAgICAgICAgICA8ZGl2IHN0eWxlPVwiZGlzcGxheTogaW5saW5lLWZsZXg7IGFsaWduLWl0ZW1zOiBjZW50ZXJcIj5cbiAgICAgICAgICAgICAgTW9udGhseSBBY3RpdmUgVXNlcnNcbiAgICAgICAgICAgICAgPGVsLXRvb2x0aXBcbiAgICAgICAgICAgICAgICBlZmZlY3Q9XCJkYXJrXCJcbiAgICAgICAgICAgICAgICBjb250ZW50PVwiTnVtYmVyIG9mIHVzZXJzIHdobyBsb2dnZWQgaW50byB0aGUgcHJvZHVjdCBpbiBvbmUgbW9udGhcIlxuICAgICAgICAgICAgICAgIHBsYWNlbWVudD1cInRvcFwiXG4gICAgICAgICAgICAgID5cbiAgICAgICAgICAgICAgICA8ZWwtaWNvbiBzdHlsZT1cIm1hcmdpbi1sZWZ0OiA0cHhcIiA6c2l6ZT1cIjEyXCI+XG4gICAgICAgICAgICAgICAgICA8V2FybmluZyAvPlxuICAgICAgICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgICAgICAgPC9lbC10b29sdGlwPlxuICAgICAgICAgICAgPC9kaXY+XG4gICAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPC9lbC1zdGF0aXN0aWM+XG4gICAgICAgIDxkaXYgY2xhc3M9XCJzdGF0aXN0aWMtZm9vdGVyXCI+XG4gICAgICAgICAgPGRpdiBjbGFzcz1cImZvb3Rlci1pdGVtXCI+XG4gICAgICAgICAgICA8c3Bhbj5tb250aCBvbiBtb250aDwvc3Bhbj5cbiAgICAgICAgICAgIDxzcGFuIGNsYXNzPVwicmVkXCI+XG4gICAgICAgICAgICAgIDEyJVxuICAgICAgICAgICAgICA8ZWwtaWNvbj5cbiAgICAgICAgICAgICAgICA8Q2FyZXRCb3R0b20gLz5cbiAgICAgICAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICAgICAgPC9zcGFuPlxuICAgICAgICAgIDwvZGl2PlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZGl2PlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnhzPVwiMjRcIiA6c209XCIxMlwiIDptZD1cIjhcIiBjbGFzcz1cIm1iLTRcIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJzdGF0aXN0aWMtY2FyZFwiPlxuICAgICAgICA8ZWwtc3RhdGlzdGljIDp2YWx1ZT1cIjcyMDAwXCIgdGl0bGU9XCJOZXcgdHJhbnNhY3Rpb25zIHRvZGF5XCI+XG4gICAgICAgICAgPHRlbXBsYXRlICN0aXRsZT5cbiAgICAgICAgICAgIDxkaXYgc3R5bGU9XCJkaXNwbGF5OiBpbmxpbmUtZmxleDsgYWxpZ24taXRlbXM6IGNlbnRlclwiPlxuICAgICAgICAgICAgICBOZXcgdHJhbnNhY3Rpb25zIHRvZGF5XG4gICAgICAgICAgICA8L2Rpdj5cbiAgICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICA8L2VsLXN0YXRpc3RpYz5cbiAgICAgICAgPGRpdiBjbGFzcz1cInN0YXRpc3RpYy1mb290ZXJcIj5cbiAgICAgICAgICA8ZGl2IGNsYXNzPVwiZm9vdGVyLWl0ZW1cIj5cbiAgICAgICAgICAgIDxzcGFuPnRoYW4geWVzdGVyZGF5PC9zcGFuPlxuICAgICAgICAgICAgPHNwYW4gY2xhc3M9XCJncmVlblwiPlxuICAgICAgICAgICAgICAxNiVcbiAgICAgICAgICAgICAgPGVsLWljb24+XG4gICAgICAgICAgICAgICAgPENhcmV0VG9wIC8+XG4gICAgICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgICAgIDwvc3Bhbj5cbiAgICAgICAgICA8L2Rpdj5cbiAgICAgICAgICA8ZGl2IGNsYXNzPVwiZm9vdGVyLWl0ZW1cIj5cbiAgICAgICAgICAgIDxlbC1pY29uIDpzaXplPVwiMTRcIj5cbiAgICAgICAgICAgICAgPEFycm93UmlnaHQgLz5cbiAgICAgICAgICAgIDwvZWwtaWNvbj5cbiAgICAgICAgICA8L2Rpdj5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L2Rpdj5cbiAgICA8L2VsLWNvbD5cbiAgPC9lbC1yb3c+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHtcbiAgQXJyb3dSaWdodCxcbiAgQ2FyZXRCb3R0b20sXG4gIENhcmV0VG9wLFxuICBXYXJuaW5nLFxufSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuOmdsb2JhbChoMiNjYXJkLXVzYWdlIH4gLmV4YW1wbGUgLmV4YW1wbGUtc2hvd2Nhc2UpIHtcbiAgYmFja2dyb3VuZC1jb2xvcjogdmFyKC0tZWwtZmlsbC1jb2xvcikgIWltcG9ydGFudDtcbn1cblxuLmVsLXN0YXRpc3RpYyB7XG4gIC0tZWwtc3RhdGlzdGljLWNvbnRlbnQtZm9udC1zaXplOiAyOHB4O1xufVxuXG4uc3RhdGlzdGljLWNhcmQge1xuICBoZWlnaHQ6IDEwMCU7XG4gIHBhZGRpbmc6IDIwcHg7XG4gIGJvcmRlci1yYWRpdXM6IDRweDtcbiAgYmFja2dyb3VuZC1jb2xvcjogdmFyKC0tZWwtYmctY29sb3Itb3ZlcmxheSk7XG59XG5cbi5zdGF0aXN0aWMtZm9vdGVyIHtcbiAgZGlzcGxheTogZmxleDtcbiAganVzdGlmeS1jb250ZW50OiBzcGFjZS1iZXR3ZWVuO1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBmbGV4LXdyYXA6IHdyYXA7XG4gIGZvbnQtc2l6ZTogMTJweDtcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3ItcmVndWxhcik7XG4gIG1hcmdpbi10b3A6IDE2cHg7XG59XG5cbi5zdGF0aXN0aWMtZm9vdGVyIC5mb290ZXItaXRlbSB7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGp1c3RpZnktY29udGVudDogc3BhY2UtYmV0d2VlbjtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbn1cblxuLnN0YXRpc3RpYy1mb290ZXIgLmZvb3Rlci1pdGVtIHNwYW46bGFzdC1jaGlsZCB7XG4gIGRpc3BsYXk6IGlubGluZS1mbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBtYXJnaW4tbGVmdDogNHB4O1xufVxuXG4uZ3JlZW4ge1xuICBjb2xvcjogdmFyKC0tZWwtY29sb3Itc3VjY2Vzcyk7XG59XG4ucmVkIHtcbiAgY29sb3I6IHZhcigtLWVsLWNvbG9yLWVycm9yKTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/statistic/card.vue)_

vue

```
<template>
  <el-row :gutter="16">
    <el-col :xs="24" :sm="12" :md="8" class="mb-4">
      <div class="statistic-card">
        <el-statistic :value="98500">
          <template #title>
            <div style="display: inline-flex; align-items: center">
              Daily active users
              <el-tooltip
                effect="dark"
                content="Number of users who logged into the product in one day"
                placement="top"
              >
                <el-icon style="margin-left: 4px" :size="12">
                  <Warning />
                </el-icon>
              </el-tooltip>
            </div>
          </template>
        </el-statistic>
        <div class="statistic-footer">
          <div class="footer-item">
            <span>than yesterday</span>
            <span class="green">
              24%
              <el-icon>
                <CaretTop />
              </el-icon>
            </span>
          </div>
        </div>
      </div>
    </el-col>
    <el-col :xs="24" :sm="12" :md="8" class="mb-4">
      <div class="statistic-card">
        <el-statistic :value="693700">
          <template #title>
            <div style="display: inline-flex; align-items: center">
              Monthly Active Users
              <el-tooltip
                effect="dark"
                content="Number of users who logged into the product in one month"
                placement="top"
              >
                <el-icon style="margin-left: 4px" :size="12">
                  <Warning />
                </el-icon>
              </el-tooltip>
            </div>
          </template>
        </el-statistic>
        <div class="statistic-footer">
          <div class="footer-item">
            <span>month on month</span>
            <span class="red">
              12%
              <el-icon>
                <CaretBottom />
              </el-icon>
            </span>
          </div>
        </div>
      </div>
    </el-col>
    <el-col :xs="24" :sm="12" :md="8" class="mb-4">
      <div class="statistic-card">
        <el-statistic :value="72000" title="New transactions today">
          <template #title>
            <div style="display: inline-flex; align-items: center">
              New transactions today
            </div>
          </template>
        </el-statistic>
        <div class="statistic-footer">
          <div class="footer-item">
            <span>than yesterday</span>
            <span class="green">
              16%
              <el-icon>
                <CaretTop />
              </el-icon>
            </span>
          </div>
          <div class="footer-item">
            <el-icon :size="14">
              <ArrowRight />
            </el-icon>
          </div>
        </div>
      </div>
    </el-col>
  </el-row>
</template>

<script lang="ts" setup>
import {
  ArrowRight,
  CaretBottom,
  CaretTop,
  Warning,
} from '@element-plus/icons-vue'
</script>

<style scoped>
:global(h2#card-usage ~ .example .example-showcase) {
  background-color: var(--el-fill-color) !important;
}

.el-statistic {
  --el-statistic-content-font-size: 28px;
}

.statistic-card {
  height: 100%;
  padding: 20px;
  border-radius: 4px;
  background-color: var(--el-bg-color-overlay);
}

.statistic-footer {
  display: flex;
  justify-content: space-between;
  align-items: center;
  flex-wrap: wrap;
  font-size: 12px;
  color: var(--el-text-color-regular);
  margin-top: 16px;
}

.statistic-footer .footer-item {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.statistic-footer .footer-item span:last-child {
  display: inline-flex;
  align-items: center;
  margin-left: 4px;
}

.green {
  color: var(--el-color-success);
}
.red {
  color: var(--el-color-error);
}
</style>
```

隐藏源代码

## Statistic API [​](#statistic-api)

### Statistic Attributes [​](#statistic-attributes)

| Attribute | 描述 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value | 数字内容 | `number` | 0 |
| decimal-separator | 设置小数点符号 | `string` | . |
| formatter | 自定义数字格式化 | `Function` | — |
| group-separator | 设置千分位标识符 | `string` | , |
| precision | 数字精度 | `number` | 0 |
| prefix | 设置数字的前缀 | `string` | — |
| suffix | 设置数字的后缀 | `string` | — |
| title | 数字标题 | `string` | — |
| value-style | 数字样式 | `string` / `object` | — |

### Statistic Slots [​](#statistic-slots)

| 插槽名 | 详情 |
| --- | --- |
| prefix | 数字区之前 |
| suffix | 数字区之后 |
| title | 数字标题 |

### Statistic Exposes [​](#statistic-exposes)

| 名称 | 描述 | 类型 |
| --- | --- | --- |
| displayValue | 当前显示值 | `object` |

## Countdown API [​](#countdown-api)

### Countdown Attributes [​](#countdown-attributes)

| 属性 | 详情 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value | 目标时间 | `number` / `Dayjs` | — |
| format | 格式化倒计时 | `string` | HH:mm:ss |
| prefix | 设置倒计时前缀 | `string` | — |
| suffix | 设置倒计时的后缀 | `string` | — |
| title | 倒计时标题 | `string` | — |
| value-style | 倒计时值的样式 | `string` / `object` | — |

### Countdown Events [​](#countdown-events)

| 方法名 | 描述 | 类型 |
| --- | --- | --- |
| change | 时间差改变事件 | `Function` |
| finish | 倒计时结束事件 | `Function` |

### Countdown Slots [​](#countdown-slots)

| 插槽名 | 描述 |
| --- | --- |
| prefix | 倒计时值前缀 |
| suffix | 倒计时后缀 |
| title | 倒计时标题 |

### Countdown Exposes [​](#countdown-exposes)

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| displayValue | 当前显示值 | `object` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/statistic) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/statistic.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/statistic.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/35138018?v=4&size=64)](https://github.com/tuskermanshu)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/30883395?v=4&size=64)](https://github.com/webvs2)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)

[Virtualized Tree 虚拟化树形控件](https://element-plus.org/zh-CN/component/tree-v2)

[Segmented 分段控制器](https://element-plus.org/zh-CN/component/segmented)




---
## [data/segmented] Segmented 分段控制器
> 官方文档: https://element-plus.org/zh-CN/component/segmented.html

---

# Segmented 分段控制器 [​](#segmented-分段控制器)

更新日志待解决

1

用于展示多个选项并允许用户选择其中单个选项。

## 基础用法 [​](#基础用法)

设置`v-model`为选项值。

Mon

Tue

Wed

Thu

Fri

Sat

Sun

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LWNvbCBpdGVtcy1zdGFydCBnYXAtNFwiPlxuICAgIDxlbC1zZWdtZW50ZWQgdi1tb2RlbD1cInZhbHVlXCIgOm9wdGlvbnM9XCJvcHRpb25zXCIgc2l6ZT1cImxhcmdlXCIgLz5cbiAgICA8ZWwtc2VnbWVudGVkIHYtbW9kZWw9XCJ2YWx1ZVwiIDpvcHRpb25zPVwib3B0aW9uc1wiIHNpemU9XCJkZWZhdWx0XCIgLz5cbiAgICA8ZWwtc2VnbWVudGVkIHYtbW9kZWw9XCJ2YWx1ZVwiIDpvcHRpb25zPVwib3B0aW9uc1wiIHNpemU9XCJzbWFsbFwiIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoJ01vbicpXG5cbmNvbnN0IG9wdGlvbnMgPSBbJ01vbicsICdUdWUnLCAnV2VkJywgJ1RodScsICdGcmknLCAnU2F0JywgJ1N1biddXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/segmented/basic.vue)_

vue

```
<template>
  <div class="flex flex-col items-start gap-4">
    <el-segmented v-model="value" :options="options" size="large" />
    <el-segmented v-model="value" :options="options" size="default" />
    <el-segmented v-model="value" :options="options" size="small" />
  </div>
</template>

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

const value = ref('Mon')

const options = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
</script>
```

隐藏源代码

## 配置方向2.8.7 [​](#配置方向)

设置 `vertical` 来改变方向。

large

default

small

Horizontal

Vertical

Apple

Cherry

Grape

Orange

Pear

Watermelon

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1zZWdtZW50ZWRcbiAgICAgIHYtbW9kZWw9XCJzaXplXCJcbiAgICAgIDpvcHRpb25zPVwic2l6ZU9wdGlvbnNcIlxuICAgICAgc3R5bGU9XCJtYXJnaW4tYm90dG9tOiAxcmVtXCJcbiAgICAvPlxuICAgIDxiciAvPlxuICAgIDxlbC1zZWdtZW50ZWRcbiAgICAgIHYtbW9kZWw9XCJkaXJlY3Rpb25cIlxuICAgICAgOm9wdGlvbnM9XCJkaXJlY3Rpb25PcHRpb25zXCJcbiAgICAgIHN0eWxlPVwibWFyZ2luLWJvdHRvbTogMXJlbVwiXG4gICAgLz5cbiAgICA8YnIgLz5cbiAgICA8ZWwtc2VnbWVudGVkXG4gICAgICB2LW1vZGVsPVwidmFsdWVcIlxuICAgICAgOm9wdGlvbnM9XCJvcHRpb25zXCJcbiAgICAgIDpkaXJlY3Rpb249XCJkaXJlY3Rpb25cIlxuICAgICAgOnNpemU9XCJzaXplXCJcbiAgICA+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJzY29wZVwiPlxuICAgICAgICA8ZGl2XG4gICAgICAgICAgOmNsYXNzPVwiW1xuICAgICAgICAgICAgJ2ZsZXgnLFxuICAgICAgICAgICAgJ2l0ZW1zLWNlbnRlcicsXG4gICAgICAgICAgICAnZ2FwLTInLFxuICAgICAgICAgICAgJ2ZsZXgtY29sJyxcbiAgICAgICAgICAgIGRpcmVjdGlvbiA9PT0gJ2hvcml6b250YWwnICYmICdwLTInLFxuICAgICAgICAgIF1cIlxuICAgICAgICA+XG4gICAgICAgICAgPGVsLWljb24gc2l6ZT1cIjIwXCI+XG4gICAgICAgICAgICA8Y29tcG9uZW50IDppcz1cInNjb3BlLml0ZW0uaWNvblwiIC8+XG4gICAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICAgIDxkaXY+e3sgc2NvcGUuaXRlbS5sYWJlbCB9fTwvZGl2PlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1zZWdtZW50ZWQ+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7XG4gIEFwcGxlLFxuICBDaGVycnksXG4gIEdyYXBlLFxuICBPcmFuZ2UsXG4gIFBlYXIsXG4gIFdhdGVybWVsb24sXG59IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5pbXBvcnQgdHlwZSB7IFNlZ21lbnRlZFByb3BzIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZignQXBwbGUnKVxuY29uc3QgZGlyZWN0aW9uID0gcmVmPFNlZ21lbnRlZFByb3BzWydkaXJlY3Rpb24nXT4oJ2hvcml6b250YWwnKVxuY29uc3Qgc2l6ZSA9IHJlZjxTZWdtZW50ZWRQcm9wc1snc2l6ZSddPignZGVmYXVsdCcpXG5cbmNvbnN0IGRpcmVjdGlvbk9wdGlvbnMgPSBbXG4gIHsgbGFiZWw6ICdIb3Jpem9udGFsJywgdmFsdWU6ICdob3Jpem9udGFsJyB9LFxuICB7IGxhYmVsOiAnVmVydGljYWwnLCB2YWx1ZTogJ3ZlcnRpY2FsJyB9LFxuXVxuXG5jb25zdCBzaXplT3B0aW9ucyA9IFsnbGFyZ2UnLCAnZGVmYXVsdCcsICdzbWFsbCddXG5cbmNvbnN0IG9wdGlvbnMgPSBbXG4gIHtcbiAgICBsYWJlbDogJ0FwcGxlJyxcbiAgICB2YWx1ZTogJ0FwcGxlJyxcbiAgICBpY29uOiBBcHBsZSxcbiAgfSxcbiAge1xuICAgIGxhYmVsOiAnQ2hlcnJ5JyxcbiAgICB2YWx1ZTogJ0NoZXJyeScsXG4gICAgaWNvbjogQ2hlcnJ5LFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdHcmFwZScsXG4gICAgdmFsdWU6ICdHcmFwZScsXG4gICAgaWNvbjogR3JhcGUsXG4gIH0sXG4gIHtcbiAgICBsYWJlbDogJ09yYW5nZScsXG4gICAgdmFsdWU6ICdPcmFuZ2UnLFxuICAgIGljb246IE9yYW5nZSxcbiAgfSxcbiAge1xuICAgIGxhYmVsOiAnUGVhcicsXG4gICAgdmFsdWU6ICdQZWFyJyxcbiAgICBpY29uOiBQZWFyLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdXYXRlcm1lbG9uJyxcbiAgICB2YWx1ZTogJ1dhdGVybWVsb24nLFxuICAgIGljb246IFdhdGVybWVsb24sXG4gICAgZGlzYWJsZWQ6IHRydWUsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/segmented/custom-direction.vue)_

vue

```
<template>
  <div>
    <el-segmented
      v-model="size"
      :options="sizeOptions"
      style="margin-bottom: 1rem"
    />
    <br />
    <el-segmented
      v-model="direction"
      :options="directionOptions"
      style="margin-bottom: 1rem"
    />
    <br />
    <el-segmented
      v-model="value"
      :options="options"
      :direction="direction"
      :size="size"
    >
      <template #default="scope">
        <div
          :class="[
            'flex',
            'items-center',
            'gap-2',
            'flex-col',
            direction === 'horizontal' && 'p-2',
          ]"
        >
          <el-icon size="20">
            <component :is="scope.item.icon" />
          </el-icon>
          <div>{{ scope.item.label }}</div>
        </div>
      </template>
    </el-segmented>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import {
  Apple,
  Cherry,
  Grape,
  Orange,
  Pear,
  Watermelon,
} from '@element-plus/icons-vue'

import type { SegmentedProps } from 'element-plus'

const value = ref('Apple')
const direction = ref<SegmentedProps['direction']>('horizontal')
const size = ref<SegmentedProps['size']>('default')

const directionOptions = [
  { label: 'Horizontal', value: 'horizontal' },
  { label: 'Vertical', value: 'vertical' },
]

const sizeOptions = ['large', 'default', 'small']

const options = [
  {
    label: 'Apple',
    value: 'Apple',
    icon: Apple,
  },
  {
    label: 'Cherry',
    value: 'Cherry',
    icon: Cherry,
  },
  {
    label: 'Grape',
    value: 'Grape',
    icon: Grape,
  },
  {
    label: 'Orange',
    value: 'Orange',
    icon: Orange,
  },
  {
    label: 'Pear',
    value: 'Pear',
    icon: Pear,
  },
  {
    label: 'Watermelon',
    value: 'Watermelon',
    icon: Watermelon,
    disabled: true,
  },
]
</script>
```

隐藏源代码

## 禁用状态 [​](#禁用状态)

设置 `disabled` 属性来禁用一些选项。

Mon

Tue

Wed

Thu

Fri

Sat

Sun

Mon

Tue

Wed

Thu

Fri

Sat

Sun

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LWNvbCBpdGVtcy1zdGFydCBnYXAtNFwiPlxuICAgIDxlbC1zZWdtZW50ZWQgdi1tb2RlbD1cInZhbHVlXCIgOm9wdGlvbnM9XCJvcHRpb25zXCIgZGlzYWJsZWQgLz5cbiAgICA8ZWwtc2VnbWVudGVkIHYtbW9kZWw9XCJ2YWx1ZVwiIDpvcHRpb25zPVwib3B0aW9uc1wiIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmFsdWUgPSByZWYoJ01vbicpXG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgbGFiZWw6ICdNb24nLFxuICAgIHZhbHVlOiAnTW9uJyxcbiAgICBkaXNhYmxlZDogdHJ1ZSxcbiAgfSxcbiAge1xuICAgIGxhYmVsOiAnVHVlJyxcbiAgICB2YWx1ZTogJ1R1ZScsXG4gIH0sXG4gIHtcbiAgICBsYWJlbDogJ1dlZCcsXG4gICAgdmFsdWU6ICdXZWQnLFxuICAgIGRpc2FibGVkOiB0cnVlLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdUaHUnLFxuICAgIHZhbHVlOiAnVGh1JyxcbiAgfSxcbiAge1xuICAgIGxhYmVsOiAnRnJpJyxcbiAgICB2YWx1ZTogJ0ZyaScsXG4gICAgZGlzYWJsZWQ6IHRydWUsXG4gIH0sXG4gIHtcbiAgICBsYWJlbDogJ1NhdCcsXG4gICAgdmFsdWU6ICdTYXQnLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdTdW4nLFxuICAgIHZhbHVlOiAnU3VuJyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/segmented/disabled.vue)_

vue

```
<template>
  <div class="flex flex-col items-start gap-4">
    <el-segmented v-model="value" :options="options" disabled />
    <el-segmented v-model="value" :options="options" />
  </div>
</template>

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

const value = ref('Mon')
const options = [
  {
    label: 'Mon',
    value: 'Mon',
    disabled: true,
  },
  {
    label: 'Tue',
    value: 'Tue',
  },
  {
    label: 'Wed',
    value: 'Wed',
    disabled: true,
  },
  {
    label: 'Thu',
    value: 'Thu',
  },
  {
    label: 'Fri',
    value: 'Fri',
    disabled: true,
  },
  {
    label: 'Sat',
    value: 'Sat',
  },
  {
    label: 'Sun',
    value: 'Sun',
  },
]
</script>
```

隐藏源代码

## 自定义选项 2.9.8 [​](#自定义选项)

当您的 `options` 格式不同于默认格式时，可通过 `props` 属性自定义 `options`

Mon

Tue

Wed

Thu

Fri

Sat

Sun

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1zZWdtZW50ZWQgdi1tb2RlbD1cInZhbHVlXCIgOm9wdGlvbnM9XCJvcHRpb25zXCIgOnByb3BzPVwicHJvcHNcIiAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKCdNb24nKVxuY29uc3QgcHJvcHMgPSB7XG4gIGxhYmVsOiAnbXlMYWJlbCcsXG4gIHZhbHVlOiAnbXlWYWx1ZScsXG4gIGRpc2FibGVkOiAnbXlEaXNhYmxlZCcsXG59XG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgbXlMYWJlbDogJ01vbicsXG4gICAgbXlWYWx1ZTogJ01vbicsXG4gICAgbXlEaXNhYmxlZDogdHJ1ZSxcbiAgfSxcbiAge1xuICAgIG15TGFiZWw6ICdUdWUnLFxuICAgIG15VmFsdWU6ICdUdWUnLFxuICB9LFxuICB7XG4gICAgbXlMYWJlbDogJ1dlZCcsXG4gICAgbXlWYWx1ZTogJ1dlZCcsXG4gICAgbXlEaXNhYmxlZDogdHJ1ZSxcbiAgfSxcbiAge1xuICAgIG15TGFiZWw6ICdUaHUnLFxuICAgIG15VmFsdWU6ICdUaHUnLFxuICB9LFxuICB7XG4gICAgbXlMYWJlbDogJ0ZyaScsXG4gICAgbXlWYWx1ZTogJ0ZyaScsXG4gICAgbXlEaXNhYmxlZDogdHJ1ZSxcbiAgfSxcbiAge1xuICAgIG15TGFiZWw6ICdTYXQnLFxuICAgIG15VmFsdWU6ICdTYXQnLFxuICB9LFxuICB7XG4gICAgbXlMYWJlbDogJ1N1bicsXG4gICAgbXlWYWx1ZTogJ1N1bicsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/segmented/props.vue)_

vue

```
<template>
  <div>
    <el-segmented v-model="value" :options="options" :props="props" />
  </div>
</template>

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

const value = ref('Mon')
const props = {
  label: 'myLabel',
  value: 'myValue',
  disabled: 'myDisabled',
}
const options = [
  {
    myLabel: 'Mon',
    myValue: 'Mon',
    myDisabled: true,
  },
  {
    myLabel: 'Tue',
    myValue: 'Tue',
  },
  {
    myLabel: 'Wed',
    myValue: 'Wed',
    myDisabled: true,
  },
  {
    myLabel: 'Thu',
    myValue: 'Thu',
  },
  {
    myLabel: 'Fri',
    myValue: 'Fri',
    myDisabled: true,
  },
  {
    myLabel: 'Sat',
    myValue: 'Sat',
  },
  {
    myLabel: 'Sun',
    myValue: 'Sun',
  },
]
</script>
```

隐藏源代码

## Block 分段选择器 [​](#block-分段选择器)

设置`block`为`true`以适应父元素的宽度。

Mon

Tue

Wed

Thu

Fri

Sat

Sunday long long long long long long long

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1zZWdtZW50ZWQgdi1tb2RlbD1cInZhbHVlXCIgOm9wdGlvbnM9XCJvcHRpb25zXCIgYmxvY2sgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZignTW9uJylcblxuY29uc3Qgb3B0aW9ucyA9IFtcbiAgJ01vbicsXG4gICdUdWUnLFxuICAnV2VkJyxcbiAgJ1RodScsXG4gICdGcmknLFxuICAnU2F0JyxcbiAgJ1N1bmRheSBsb25nIGxvbmcgbG9uZyBsb25nIGxvbmcgbG9uZyBsb25nJyxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/segmented/block.vue)_

vue

```
<template>
  <div>
    <el-segmented v-model="value" :options="options" block />
  </div>
</template>

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

const value = ref('Mon')

const options = [
  'Mon',
  'Tue',
  'Wed',
  'Thu',
  'Fri',
  'Sat',
  'Sunday long long long long long long long',
]
</script>
```

隐藏源代码

## 自定义内容 [​](#自定义内容)

设置 default slot 位来渲染自定义内容。

Apple

Cherry

Grape

Orange

Pear

Watermelon

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1zZWdtZW50ZWQgdi1tb2RlbD1cInZhbHVlXCIgOm9wdGlvbnM9XCJvcHRpb25zXCI+XG4gICAgICA8dGVtcGxhdGUgI2RlZmF1bHQ9XCJzY29wZVwiPlxuICAgICAgICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LWNvbCBpdGVtcy1jZW50ZXIgZ2FwLTIgcC0yXCI+XG4gICAgICAgICAgPGVsLWljb24gc2l6ZT1cIjIwXCI+XG4gICAgICAgICAgICA8Y29tcG9uZW50IDppcz1cInNjb3BlLml0ZW0uaWNvblwiIC8+XG4gICAgICAgICAgPC9lbC1pY29uPlxuICAgICAgICAgIDxkaXY+e3sgc2NvcGUuaXRlbS5sYWJlbCB9fTwvZGl2PlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1zZWdtZW50ZWQ+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7XG4gIEFwcGxlLFxuICBDaGVycnksXG4gIEdyYXBlLFxuICBPcmFuZ2UsXG4gIFBlYXIsXG4gIFdhdGVybWVsb24sXG59IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5jb25zdCB2YWx1ZSA9IHJlZignQXBwbGUnKVxuXG5jb25zdCBvcHRpb25zID0gW1xuICB7XG4gICAgbGFiZWw6ICdBcHBsZScsXG4gICAgdmFsdWU6ICdBcHBsZScsXG4gICAgaWNvbjogQXBwbGUsXG4gIH0sXG4gIHtcbiAgICBsYWJlbDogJ0NoZXJyeScsXG4gICAgdmFsdWU6ICdDaGVycnknLFxuICAgIGljb246IENoZXJyeSxcbiAgfSxcbiAge1xuICAgIGxhYmVsOiAnR3JhcGUnLFxuICAgIHZhbHVlOiAnR3JhcGUnLFxuICAgIGljb246IEdyYXBlLFxuICB9LFxuICB7XG4gICAgbGFiZWw6ICdPcmFuZ2UnLFxuICAgIHZhbHVlOiAnT3JhbmdlJyxcbiAgICBpY29uOiBPcmFuZ2UsXG4gIH0sXG4gIHtcbiAgICBsYWJlbDogJ1BlYXInLFxuICAgIHZhbHVlOiAnUGVhcicsXG4gICAgaWNvbjogUGVhcixcbiAgfSxcbiAge1xuICAgIGxhYmVsOiAnV2F0ZXJtZWxvbicsXG4gICAgdmFsdWU6ICdXYXRlcm1lbG9uJyxcbiAgICBpY29uOiBXYXRlcm1lbG9uLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/segmented/custom-content.vue)_

vue

```
<template>
  <div>
    <el-segmented v-model="value" :options="options">
      <template #default="scope">
        <div class="flex flex-col items-center gap-2 p-2">
          <el-icon size="20">
            <component :is="scope.item.icon" />
          </el-icon>
          <div>{{ scope.item.label }}</div>
        </div>
      </template>
    </el-segmented>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import {
  Apple,
  Cherry,
  Grape,
  Orange,
  Pear,
  Watermelon,
} from '@element-plus/icons-vue'

const value = ref('Apple')

const options = [
  {
    label: 'Apple',
    value: 'Apple',
    icon: Apple,
  },
  {
    label: 'Cherry',
    value: 'Cherry',
    icon: Cherry,
  },
  {
    label: 'Grape',
    value: 'Grape',
    icon: Grape,
  },
  {
    label: 'Orange',
    value: 'Orange',
    icon: Orange,
  },
  {
    label: 'Pear',
    value: 'Pear',
    icon: Pear,
  },
  {
    label: 'Watermelon',
    value: 'Watermelon',
    icon: Watermelon,
  },
]
</script>
```

隐藏源代码

## 自定义样式 [​](#自定义样式)

使用 CSS 变量设置自定义样式。

Delicacy

Desserts&Drinks

Fresh foods

Supermarket

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiY3VzdG9tLXN0eWxlXCI+XG4gICAgPGVsLXNlZ21lbnRlZCB2LW1vZGVsPVwidmFsdWVcIiA6b3B0aW9ucz1cIm9wdGlvbnNcIiAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZhbHVlID0gcmVmKCdEZWxpY2FjeScpXG5cbmNvbnN0IG9wdGlvbnMgPSBbJ0RlbGljYWN5JywgJ0Rlc3NlcnRzJkRyaW5rcycsICdGcmVzaCBmb29kcycsICdTdXBlcm1hcmtldCddXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5jdXN0b20tc3R5bGUgLmVsLXNlZ21lbnRlZCB7XG4gIC0tZWwtc2VnbWVudGVkLWl0ZW0tc2VsZWN0ZWQtY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3ItcHJpbWFyeSk7XG4gIC0tZWwtc2VnbWVudGVkLWl0ZW0tc2VsZWN0ZWQtYmctY29sb3I6ICNmZmQxMDA7XG4gIC0tZWwtYm9yZGVyLXJhZGl1cy1iYXNlOiAxNnB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/segmented/custom-style.vue)_

vue

```
<template>
  <div class="custom-style">
    <el-segmented v-model="value" :options="options" />
  </div>
</template>

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

const value = ref('Delicacy')

const options = ['Delicacy', 'Desserts&Drinks', 'Fresh foods', 'Supermarket']
</script>

<style scoped>
.custom-style .el-segmented {
  --el-segmented-item-selected-color: var(--el-text-color-primary);
  --el-segmented-item-selected-bg-color: #ffd100;
  --el-border-radius-base: 16px;
}
</style>
```

隐藏源代码

## API [​](#api)

### 属性 [​](#属性)

| 名称 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 绑定值 | `string` / `number` / `boolean` | — |
| options | 选项的数据 | `array` | \[\] |
| [props](#props) 2.9.8 | 配置选项，详见下表 | `object` | — |
| size | 组件大小 | `enum` | '' |
| block | 撑满父元素宽度 | `boolean` | false |
| disabled | 是否禁用 | `boolean` | false |
| validate-event | 是否触发表单验证 | `boolean` | true |
| name | 原生 name 属性 | `string` | — |
| id | 原生 `id` 属性 | `string` | — |
| aria-label a11y | 原生 `aria-label` 属性 | `string` | — |
| direction 2.8.7 | 展示的方向 | `enum` | horizontal |

### props [​](#props)

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| value | 指定键为节点对象的某个属性值 | `string` | value |
| label | 指定标签为节点对象的某个属性值 | `string` | label |
| disabled | 指定禁用状态为节点对象的某个属性值 | `string` | disabled |

### 事件 [​](#事件)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| change | 当所选值更改时触发，参数是当前选中的值 | `Function` |

### Slots [​](#slots)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| default | 自定义 Option 模板 | `object` |

## 类型声明 [​](#类型声明)

显示类型声明

ts

```
type Option = Record<string, any> | string | number | boolean
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/segmented) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/segmented.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/segmented.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/124225078?v=4&size=64)](https://github.com/ykcory)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/52314078?v=4&size=64)](https://github.com/vaebe)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/35400818?v=4&size=64)](https://github.com/ToyCat93)[![](https://avatars.githubusercontent.com/u/47178158?v=4&size=64)](https://github.com/Aaron-zon)[![](https://avatars.githubusercontent.com/u/100760523?v=4&size=64)](https://github.com/jhinzhou)[![](https://avatars.githubusercontent.com/u/31943807?v=4&size=64)](https://github.com/ayay459547)[![](https://avatars.githubusercontent.com/u/50254496?v=4&size=64)](https://github.com/LoTwT)[![](https://avatars.githubusercontent.com/u/145281501?v=4&size=64)](https://github.com/typed-sigterm)

[Statistic 统计组件](https://element-plus.org/zh-CN/component/statistic)

[Affix 固钉](https://element-plus.org/zh-CN/component/affix)




---

<!-- ============================================ -->
<!-- 类别: 导航组件 -->
<!-- ============================================ -->

## [navigation/affix] Affix 固钉
> 官方文档: https://element-plus.org/zh-CN/component/affix.html

---

# Affix 固钉 [​](#affix-固钉)

更新日志待解决

4

将页面元素固定在特定可视区域。

## 基础用法 [​](#基础用法)

固钉默认固定在页面顶部。

通过设置 `offset` 属性来改变吸顶距离，默认值为 0。

Offset top 120px

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYWZmaXggOm9mZnNldD1cIjEyMFwiPlxuICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIj5PZmZzZXQgdG9wIDEyMHB4PC9lbC1idXR0b24+XG4gIDwvZWwtYWZmaXg+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/affix/basic.vue)_

vue

```
<template>
  <el-affix :offset="120">
    <el-button type="primary">Offset top 120px</el-button>
  </el-affix>
</template>
```

隐藏源代码

## 指定容器 [​](#指定容器)

通过设置 `target` 属性，让固钉始终保持在容器内， 超过范围则隐藏。

请注意容器避免出现滚动条。

Target container

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiYWZmaXgtY29udGFpbmVyXCI+XG4gICAgPGVsLWFmZml4IHRhcmdldD1cIi5hZmZpeC1jb250YWluZXJcIiA6b2Zmc2V0PVwiODBcIj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIj5UYXJnZXQgY29udGFpbmVyPC9lbC1idXR0b24+XG4gICAgPC9lbC1hZmZpeD5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c3R5bGUgc2NvcGVkPlxuLmFmZml4LWNvbnRhaW5lciB7XG4gIHRleHQtYWxpZ246IGNlbnRlcjtcbiAgaGVpZ2h0OiA0MDBweDtcbiAgYm9yZGVyLXJhZGl1czogNHB4O1xuICBiYWNrZ3JvdW5kOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5LWxpZ2h0LTkpO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/affix/target.vue)_

vue

```
<template>
  <div class="affix-container">
    <el-affix target=".affix-container" :offset="80">
      <el-button type="primary">Target container</el-button>
    </el-affix>
  </div>
</template>

<style scoped>
.affix-container {
  text-align: center;
  height: 400px;
  border-radius: 4px;
  background: var(--el-color-primary-light-9);
}
</style>
```

隐藏源代码

## 固定位置 [​](#固定位置)

Affix 组件提供 2 个固定的位置参数 `top` 和 `bottom`。

通过设置 `position` 属性来改变固定位置，默认值为 `top` 。

Offset bottom 20px

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYWZmaXggcG9zaXRpb249XCJib3R0b21cIiA6b2Zmc2V0PVwiMjBcIj5cbiAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCI+T2Zmc2V0IGJvdHRvbSAyMHB4PC9lbC1idXR0b24+XG4gIDwvZWwtYWZmaXg+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/affix/fixed.vue)_

vue

```
<template>
  <el-affix position="bottom" :offset="20">
    <el-button type="primary">Offset bottom 20px</el-button>
  </el-affix>
</template>
```

隐藏源代码

## API [​](#api)

### 属性 [​](#属性)

| 名称 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| offset | 偏移距离 | `number` | 0 |
| position | 固钉位置 | `enum` | top |
| target | 指定容器（CSS 选择器） | `string` | — |
| z-index | `z-index` | `number` | 100 |
| teleported 2.13.0 | Affix 元素是否使用 teleport 特性，设置为 `true` 将会使得该元素“传送”至 `append-to` 设置的位置 | `boolean` | false |
| append-to 2.13.0 | Affix 元素将被挂载至哪个元素 | `CSSSelector` / `HTMLElement` | body |

### 事件 [​](#事件)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| change | 固钉状态改变时触发的事件 | `Function` |
| scroll | 滚动时触发的事件 | `Function` |

### 插槽 [​](#插槽)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

### 暴露 [​](#暴露)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| update | 手动更新固钉状态 | `Function` |
| updateRoot | 手动更新根元素的盒模型信息 | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/affix) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/affix.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/affix.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/46664126?v=4&size=64)](https://github.com/btnkr)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/50874301?v=4&size=64)](https://github.com/markbiu)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/72804789?v=4&size=64)](https://github.com/akashbagchi)[![](https://avatars.githubusercontent.com/u/17726809?v=4&size=64)](https://github.com/LiZhequ)[![](https://avatars.githubusercontent.com/u/26272596?v=4&size=64)](https://github.com/CodeListener)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/47516844?v=4&size=64)](https://github.com/midcu)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/22695767?v=4&size=64)](https://github.com/deepthan)[![](https://avatars.githubusercontent.com/u/20411966?v=4&size=64)](https://github.com/SorrowX)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)

[Segmented 分段控制器](https://element-plus.org/zh-CN/component/segmented)

[Anchor 锚点](https://element-plus.org/zh-CN/component/anchor)




---
## [navigation/anchor] Anchor 锚点
> 官方文档: https://element-plus.org/zh-CN/component/anchor.html

---

# Anchor 锚点 [​](#anchor-锚点)

更新日志待解决

1

通过锚点，您可以很快找到当前页面上信息内容的位置。

## 基础用法 [​](#基础用法)

最简单的用法。

[基础用法](#基础用法)

[水平模式](#水平模式)

[滚动容器](#滚动的容器)

[Anchor API](#anchor-api)

[Anchor Attributes](#anchor-attributes)

[Anchor Events](#anchor-events)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYW5jaG9yIDpvZmZzZXQ9XCI3MFwiPlxuICAgIDxlbC1hbmNob3ItbGluayA6aHJlZj1cImAjJHtsb2NhbGVbJ2Jhc2ljLXVzYWdlJ119YFwiPlxuICAgICAge3sgbG9jYWxlWydCYXNpYyBVc2FnZSddIH19XG4gICAgPC9lbC1hbmNob3ItbGluaz5cbiAgICA8ZWwtYW5jaG9yLWxpbmsgOmhyZWY9XCJgIyR7bG9jYWxlWydob3Jpem9udGFsLW1vZGUnXX1gXCI+XG4gICAgICB7eyBsb2NhbGVbJ0hvcml6b250YWwgTW9kZSddIH19XG4gICAgPC9lbC1hbmNob3ItbGluaz5cbiAgICA8ZWwtYW5jaG9yLWxpbmsgOmhyZWY9XCJgIyR7bG9jYWxlWydzY3JvbGwtY29udGFpbmVyJ119YFwiPlxuICAgICAge3sgbG9jYWxlWydTY3JvbGwgQ29udGFpbmVyJ10gfX1cbiAgICA8L2VsLWFuY2hvci1saW5rPlxuICAgIDxlbC1hbmNob3ItbGluayA6aHJlZj1cImAjJHtsb2NhbGVbJ2FuY2hvci1hcGknXX1gXCI+XG4gICAgICB7eyBsb2NhbGVbJ0FuY2hvciBBUEknXSB9fVxuICAgICAgPHRlbXBsYXRlICNzdWItbGluaz5cbiAgICAgICAgPGVsLWFuY2hvci1saW5rIDpocmVmPVwiYCMke2xvY2FsZVsnYW5jaG9yLWF0dHJpYnV0ZXMnXX1gXCI+XG4gICAgICAgICAge3sgbG9jYWxlWydBbmNob3IgQXR0cmlidXRlcyddIH19XG4gICAgICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gICAgICAgIDxlbC1hbmNob3ItbGluayA6aHJlZj1cImAjJHtsb2NhbGVbJ2FuY2hvci1ldmVudHMnXX1gXCI+XG4gICAgICAgICAge3sgbG9jYWxlWydBbmNob3IgRXZlbnRzJ10gfX1cbiAgICAgICAgPC9lbC1hbmNob3ItbGluaz5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1hbmNob3ItbGluaz5cbiAgPC9lbC1hbmNob3I+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgY29tcHV0ZWQgfSBmcm9tICd2dWUnXG5pbXBvcnQgYW5jaG9yTG9jYWxlIGZyb20gJy4uLy4uLy52aXRlcHJlc3MvaTE4bi9jb21wb25lbnQvYW5jaG9yLmpzb24nXG5pbXBvcnQgeyB1c2VMYW5nIH0gZnJvbSAnfi9jb21wb3NhYmxlcy9sYW5nJ1xuXG5jb25zdCBsYW5nID0gdXNlTGFuZygpXG5jb25zdCBsb2NhbGUgPSBjb21wdXRlZCgoKSA9PiBhbmNob3JMb2NhbGVbbGFuZy52YWx1ZV0pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/anchor/basic.vue)_

vue

```
<template>
  <el-anchor :offset="70">
    <el-anchor-link :href="`#${locale['basic-usage']}`">
      {{ locale['Basic Usage'] }}
    </el-anchor-link>
    <el-anchor-link :href="`#${locale['horizontal-mode']}`">
      {{ locale['Horizontal Mode'] }}
    </el-anchor-link>
    <el-anchor-link :href="`#${locale['scroll-container']}`">
      {{ locale['Scroll Container'] }}
    </el-anchor-link>
    <el-anchor-link :href="`#${locale['anchor-api']}`">
      {{ locale['Anchor API'] }}
      <template #sub-link>
        <el-anchor-link :href="`#${locale['anchor-attributes']}`">
          {{ locale['Anchor Attributes'] }}
        </el-anchor-link>
        <el-anchor-link :href="`#${locale['anchor-events']}`">
          {{ locale['Anchor Events'] }}
        </el-anchor-link>
      </template>
    </el-anchor-link>
  </el-anchor>
</template>

<script lang="ts" setup>
import { computed } from 'vue'
import anchorLocale from '../../.vitepress/i18n/component/anchor.json'
import { useLang } from '~/composables/lang'

const lang = useLang()
const locale = computed(() => anchorLocale[lang.value])
</script>
```

隐藏源代码

## 水平模式 [​](#水平模式)

水平排列的锚点

TIP

水平模式不支持`sub-link`槽位

[基础用法](#基础用法)

[水平模式](#水平模式)

[滚动容器](#滚动的容器)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYW5jaG9yIDpvZmZzZXQ9XCI3MFwiIGRpcmVjdGlvbj1cImhvcml6b250YWxcIj5cbiAgICA8ZWwtYW5jaG9yLWxpbmsgOmhyZWY9XCJgIyR7bG9jYWxlWydiYXNpYy11c2FnZSddfWBcIj5cbiAgICAgIHt7IGxvY2FsZVsnQmFzaWMgVXNhZ2UnXSB9fVxuICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gICAgPGVsLWFuY2hvci1saW5rIDpocmVmPVwiYCMke2xvY2FsZVsnaG9yaXpvbnRhbC1tb2RlJ119YFwiPlxuICAgICAge3sgbG9jYWxlWydIb3Jpem9udGFsIE1vZGUnXSB9fVxuICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gICAgPGVsLWFuY2hvci1saW5rIDpocmVmPVwiYCMke2xvY2FsZVsnc2Nyb2xsLWNvbnRhaW5lciddfWBcIj5cbiAgICAgIHt7IGxvY2FsZVsnU2Nyb2xsIENvbnRhaW5lciddIH19XG4gICAgPC9lbC1hbmNob3ItbGluaz5cbiAgPC9lbC1hbmNob3I+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgY29tcHV0ZWQgfSBmcm9tICd2dWUnXG5pbXBvcnQgYW5jaG9yTG9jYWxlIGZyb20gJy4uLy4uLy52aXRlcHJlc3MvaTE4bi9jb21wb25lbnQvYW5jaG9yLmpzb24nXG5pbXBvcnQgeyB1c2VMYW5nIH0gZnJvbSAnfi9jb21wb3NhYmxlcy9sYW5nJ1xuXG5jb25zdCBsYW5nID0gdXNlTGFuZygpXG5jb25zdCBsb2NhbGUgPSBjb21wdXRlZCgoKSA9PiBhbmNob3JMb2NhbGVbbGFuZy52YWx1ZV0pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/anchor/horizontal.vue)_

vue

```
<template>
  <el-anchor :offset="70" direction="horizontal">
    <el-anchor-link :href="`#${locale['basic-usage']}`">
      {{ locale['Basic Usage'] }}
    </el-anchor-link>
    <el-anchor-link :href="`#${locale['horizontal-mode']}`">
      {{ locale['Horizontal Mode'] }}
    </el-anchor-link>
    <el-anchor-link :href="`#${locale['scroll-container']}`">
      {{ locale['Scroll Container'] }}
    </el-anchor-link>
  </el-anchor>
</template>

<script lang="ts" setup>
import { computed } from 'vue'
import anchorLocale from '../../.vitepress/i18n/component/anchor.json'
import { useLang } from '~/composables/lang'

const lang = useLang()
const locale = computed(() => anchorLocale[lang.value])
</script>
```

隐藏源代码

## 滚动容器 [​](#滚动容器)

自定义滚动区域，使用 `offset` props 可以设置锚点滚动偏移。 监听`link-click`事件并阻止浏览器的默认行为，从而不会更改历史记录。

Fixed Top Block

part1

part2

part3

[part1](#part1)

[part2](#part2)

[part3](#part3)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1yb3c+XG4gICAgICA8ZWwtY29sIDpzcGFuPVwiMThcIj5cbiAgICAgICAgPGRpdlxuICAgICAgICAgIHN0eWxlPVwiXG4gICAgICAgICAgICBoZWlnaHQ6IDMwcHg7XG4gICAgICAgICAgICB3aWR0aDogNzAlO1xuICAgICAgICAgICAgYmFja2dyb3VuZDogIzAwMDtcbiAgICAgICAgICAgIHBvc2l0aW9uOiBhYnNvbHV0ZTtcbiAgICAgICAgICAgIHRvcDogMDtcbiAgICAgICAgICAgIGxlZnQ6IDA7XG4gICAgICAgICAgICBjb2xvcjogI2ZmZjtcbiAgICAgICAgICBcIlxuICAgICAgICA+XG4gICAgICAgICAgRml4ZWQgVG9wIEJsb2NrXG4gICAgICAgIDwvZGl2PlxuICAgICAgICA8ZGl2IHJlZj1cImNvbnRhaW5lclJlZlwiIHN0eWxlPVwiaGVpZ2h0OiAzMDBweDsgb3ZlcmZsb3cteTogYXV0b1wiPlxuICAgICAgICAgIDxkaXZcbiAgICAgICAgICAgIGlkPVwicGFydDFcIlxuICAgICAgICAgICAgc3R5bGU9XCJcbiAgICAgICAgICAgICAgaGVpZ2h0OiAzMDBweDtcbiAgICAgICAgICAgICAgYmFja2dyb3VuZDogcmdiYSgyNTUsIDAsIDAsIDAuMDIpO1xuICAgICAgICAgICAgICBtYXJnaW4tdG9wOiAzMHB4O1xuICAgICAgICAgICAgXCJcbiAgICAgICAgICA+XG4gICAgICAgICAgICBwYXJ0MVxuICAgICAgICAgIDwvZGl2PlxuICAgICAgICAgIDxkaXZcbiAgICAgICAgICAgIGlkPVwicGFydDJcIlxuICAgICAgICAgICAgc3R5bGU9XCJcbiAgICAgICAgICAgICAgaGVpZ2h0OiAzMDBweDtcbiAgICAgICAgICAgICAgYmFja2dyb3VuZDogcmdiYSgwLCAyNTUsIDAsIDAuMDIpO1xuICAgICAgICAgICAgICBtYXJnaW4tdG9wOiAzMHB4O1xuICAgICAgICAgICAgXCJcbiAgICAgICAgICA+XG4gICAgICAgICAgICBwYXJ0MlxuICAgICAgICAgIDwvZGl2PlxuICAgICAgICAgIDxkaXZcbiAgICAgICAgICAgIGlkPVwicGFydDNcIlxuICAgICAgICAgICAgc3R5bGU9XCJcbiAgICAgICAgICAgICAgaGVpZ2h0OiAzMDBweDtcbiAgICAgICAgICAgICAgYmFja2dyb3VuZDogcmdiYSgwLCAwLCAyNTUsIDAuMDIpO1xuICAgICAgICAgICAgICBtYXJnaW4tdG9wOiAzMHB4O1xuICAgICAgICAgICAgXCJcbiAgICAgICAgICA+XG4gICAgICAgICAgICBwYXJ0M1xuICAgICAgICAgIDwvZGl2PlxuICAgICAgICA8L2Rpdj5cbiAgICAgIDwvZWwtY29sPlxuICAgICAgPGVsLWNvbCA6c3Bhbj1cIjZcIj5cbiAgICAgICAgPGRpdiBjbGFzcz1cInZwLXJhd1wiPlxuICAgICAgICAgIDxlbC1hbmNob3JcbiAgICAgICAgICAgIDpjb250YWluZXI9XCJjb250YWluZXJSZWZcIlxuICAgICAgICAgICAgZGlyZWN0aW9uPVwidmVydGljYWxcIlxuICAgICAgICAgICAgdHlwZT1cImRlZmF1bHRcIlxuICAgICAgICAgICAgOm9mZnNldD1cIjMwXCJcbiAgICAgICAgICAgIEBjbGljaz1cImhhbmRsZUNsaWNrXCJcbiAgICAgICAgICA+XG4gICAgICAgICAgICA8ZWwtYW5jaG9yLWxpbmsgaHJlZj1cIiNwYXJ0MVwiIHRpdGxlPVwicGFydDFcIiAvPlxuICAgICAgICAgICAgPGVsLWFuY2hvci1saW5rIGhyZWY9XCIjcGFydDJcIiB0aXRsZT1cInBhcnQyXCIgLz5cbiAgICAgICAgICAgIDxlbC1hbmNob3ItbGluayBocmVmPVwiI3BhcnQzXCIgdGl0bGU9XCJwYXJ0M1wiIC8+XG4gICAgICAgICAgPC9lbC1hbmNob3I+XG4gICAgICAgIDwvZGl2PlxuICAgICAgPC9lbC1jb2w+XG4gICAgPC9lbC1yb3c+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgY29udGFpbmVyUmVmID0gcmVmPEhUTUxFbGVtZW50IHwgbnVsbD4obnVsbClcblxuY29uc3QgaGFuZGxlQ2xpY2sgPSAoZTogTW91c2VFdmVudCkgPT4ge1xuICBlLnByZXZlbnREZWZhdWx0KClcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/anchor/scroll.vue)_

vue

```
<template>
  <div>
    <el-row>
      <el-col :span="18">
        <div
          style="
            height: 30px;
            width: 70%;
            background: #000;
            position: absolute;
            top: 0;
            left: 0;
            color: #fff;
          "
        >
          Fixed Top Block
        </div>
        <div ref="containerRef" style="height: 300px; overflow-y: auto">
          <div
            id="part1"
            style="
              height: 300px;
              background: rgba(255, 0, 0, 0.02);
              margin-top: 30px;
            "
          >
            part1
          </div>
          <div
            id="part2"
            style="
              height: 300px;
              background: rgba(0, 255, 0, 0.02);
              margin-top: 30px;
            "
          >
            part2
          </div>
          <div
            id="part3"
            style="
              height: 300px;
              background: rgba(0, 0, 255, 0.02);
              margin-top: 30px;
            "
          >
            part3
          </div>
        </div>
      </el-col>
      <el-col :span="6">
        <div class="vp-raw">
          <el-anchor
            :container="containerRef"
            direction="vertical"
            type="default"
            :offset="30"
            @click="handleClick"
          >
            <el-anchor-link href="#part1" title="part1" />
            <el-anchor-link href="#part2" title="part2" />
            <el-anchor-link href="#part3" title="part3" />
          </el-anchor>
        </div>
      </el-col>
    </el-row>
  </div>
</template>

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

const containerRef = ref<HTMLElement | null>(null)

const handleClick = (e: MouseEvent) => {
  e.preventDefault()
}
</script>
```

隐藏源代码

## 锚点链接变化 [​](#锚点链接变化)

监听锚点链接变化

[基础用法](#基础用法)

[水平模式](#水平模式)

[滚动容器](#滚动的容器)

[Anchor API](#anchor-api)

[Anchor Attributes](#anchor-attributes)

[Anchor Events](#anchor-events)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYW5jaG9yIDpvZmZzZXQ9XCI3MFwiIEBjaGFuZ2U9XCJoYW5kbGVDaGFuZ2VcIj5cbiAgICA8ZWwtYW5jaG9yLWxpbmsgOmhyZWY9XCJgIyR7bG9jYWxlWydiYXNpYy11c2FnZSddfWBcIj5cbiAgICAgIHt7IGxvY2FsZVsnQmFzaWMgVXNhZ2UnXSB9fVxuICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gICAgPGVsLWFuY2hvci1saW5rIDpocmVmPVwiYCMke2xvY2FsZVsnaG9yaXpvbnRhbC1tb2RlJ119YFwiPlxuICAgICAge3sgbG9jYWxlWydIb3Jpem9udGFsIE1vZGUnXSB9fVxuICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gICAgPGVsLWFuY2hvci1saW5rIDpocmVmPVwiYCMke2xvY2FsZVsnc2Nyb2xsLWNvbnRhaW5lciddfWBcIj5cbiAgICAgIHt7IGxvY2FsZVsnU2Nyb2xsIENvbnRhaW5lciddIH19XG4gICAgPC9lbC1hbmNob3ItbGluaz5cbiAgICA8ZWwtYW5jaG9yLWxpbmsgOmhyZWY9XCJgIyR7bG9jYWxlWydhbmNob3ItYXBpJ119YFwiPlxuICAgICAge3sgbG9jYWxlWydBbmNob3IgQVBJJ10gfX1cbiAgICAgIDx0ZW1wbGF0ZSAjc3ViLWxpbms+XG4gICAgICAgIDxlbC1hbmNob3ItbGluayA6aHJlZj1cImAjJHtsb2NhbGVbJ2FuY2hvci1hdHRyaWJ1dGVzJ119YFwiPlxuICAgICAgICAgIHt7IGxvY2FsZVsnQW5jaG9yIEF0dHJpYnV0ZXMnXSB9fVxuICAgICAgICA8L2VsLWFuY2hvci1saW5rPlxuICAgICAgICA8ZWwtYW5jaG9yLWxpbmsgOmhyZWY9XCJgIyR7bG9jYWxlWydhbmNob3ItZXZlbnRzJ119YFwiPlxuICAgICAgICAgIHt7IGxvY2FsZVsnQW5jaG9yIEV2ZW50cyddIH19XG4gICAgICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gIDwvZWwtYW5jaG9yPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IGNvbXB1dGVkIH0gZnJvbSAndnVlJ1xuaW1wb3J0IGFuY2hvckxvY2FsZSBmcm9tICcuLi8uLi8udml0ZXByZXNzL2kxOG4vY29tcG9uZW50L2FuY2hvci5qc29uJ1xuaW1wb3J0IHsgdXNlTGFuZyB9IGZyb20gJ34vY29tcG9zYWJsZXMvbGFuZydcblxuY29uc3QgbGFuZyA9IHVzZUxhbmcoKVxuY29uc3QgbG9jYWxlID0gY29tcHV0ZWQoKCkgPT4gYW5jaG9yTG9jYWxlW2xhbmcudmFsdWVdKVxuXG5jb25zdCBoYW5kbGVDaGFuZ2UgPSAoaHJlZjogc3RyaW5nKSA9PiB7XG4gIGNvbnNvbGUubG9nKGBhbmNob3IgY2hhbmdlOiAke2hyZWZ9YClcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/anchor/change.vue)_

vue

```
<template>
  <el-anchor :offset="70" @change="handleChange">
    <el-anchor-link :href="`#${locale['basic-usage']}`">
      {{ locale['Basic Usage'] }}
    </el-anchor-link>
    <el-anchor-link :href="`#${locale['horizontal-mode']}`">
      {{ locale['Horizontal Mode'] }}
    </el-anchor-link>
    <el-anchor-link :href="`#${locale['scroll-container']}`">
      {{ locale['Scroll Container'] }}
    </el-anchor-link>
    <el-anchor-link :href="`#${locale['anchor-api']}`">
      {{ locale['Anchor API'] }}
      <template #sub-link>
        <el-anchor-link :href="`#${locale['anchor-attributes']}`">
          {{ locale['Anchor Attributes'] }}
        </el-anchor-link>
        <el-anchor-link :href="`#${locale['anchor-events']}`">
          {{ locale['Anchor Events'] }}
        </el-anchor-link>
      </template>
    </el-anchor-link>
  </el-anchor>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import anchorLocale from '../../.vitepress/i18n/component/anchor.json'
import { useLang } from '~/composables/lang'

const lang = useLang()
const locale = computed(() => anchorLocale[lang.value])

const handleChange = (href: string) => {
  console.log(`anchor change: ${href}`)
}
</script>
```

隐藏源代码

## 下划线类型 [​](#下划线类型)

设置`type="underline"`以更改为下划线类型

[基础用法](#基础用法)

[水平模式](#水平模式)

[滚动容器](#滚动的容器)

[Anchor API](#anchor-api)

[Anchor Attributes](#anchor-attributes)

[Anchor Events](#anchor-events)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYW5jaG9yIHR5cGU9XCJ1bmRlcmxpbmVcIiA6b2Zmc2V0PVwiNzBcIj5cbiAgICA8ZWwtYW5jaG9yLWxpbmsgOmhyZWY9XCJgIyR7bG9jYWxlWydiYXNpYy11c2FnZSddfWBcIj5cbiAgICAgIHt7IGxvY2FsZVsnQmFzaWMgVXNhZ2UnXSB9fVxuICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gICAgPGVsLWFuY2hvci1saW5rIDpocmVmPVwiYCMke2xvY2FsZVsnaG9yaXpvbnRhbC1tb2RlJ119YFwiPlxuICAgICAge3sgbG9jYWxlWydIb3Jpem9udGFsIE1vZGUnXSB9fVxuICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gICAgPGVsLWFuY2hvci1saW5rIDpocmVmPVwiYCMke2xvY2FsZVsnc2Nyb2xsLWNvbnRhaW5lciddfWBcIj5cbiAgICAgIHt7IGxvY2FsZVsnU2Nyb2xsIENvbnRhaW5lciddIH19XG4gICAgPC9lbC1hbmNob3ItbGluaz5cbiAgICA8ZWwtYW5jaG9yLWxpbmsgOmhyZWY9XCJgIyR7bG9jYWxlWydhbmNob3ItYXBpJ119YFwiPlxuICAgICAge3sgbG9jYWxlWydBbmNob3IgQVBJJ10gfX1cbiAgICAgIDx0ZW1wbGF0ZSAjc3ViLWxpbms+XG4gICAgICAgIDxlbC1hbmNob3ItbGluayA6aHJlZj1cImAjJHtsb2NhbGVbJ2FuY2hvci1hdHRyaWJ1dGVzJ119YFwiPlxuICAgICAgICAgIHt7IGxvY2FsZVsnQW5jaG9yIEF0dHJpYnV0ZXMnXSB9fVxuICAgICAgICA8L2VsLWFuY2hvci1saW5rPlxuICAgICAgICA8ZWwtYW5jaG9yLWxpbmsgOmhyZWY9XCJgIyR7bG9jYWxlWydhbmNob3ItZXZlbnRzJ119YFwiPlxuICAgICAgICAgIHt7IGxvY2FsZVsnQW5jaG9yIEV2ZW50cyddIH19XG4gICAgICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gIDwvZWwtYW5jaG9yPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IGNvbXB1dGVkIH0gZnJvbSAndnVlJ1xuaW1wb3J0IGFuY2hvckxvY2FsZSBmcm9tICcuLi8uLi8udml0ZXByZXNzL2kxOG4vY29tcG9uZW50L2FuY2hvci5qc29uJ1xuaW1wb3J0IHsgdXNlTGFuZyB9IGZyb20gJ34vY29tcG9zYWJsZXMvbGFuZydcblxuY29uc3QgbGFuZyA9IHVzZUxhbmcoKVxuY29uc3QgbG9jYWxlID0gY29tcHV0ZWQoKCkgPT4gYW5jaG9yTG9jYWxlW2xhbmcudmFsdWVdKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/anchor/underline.vue)_

vue

```
<template>
  <el-anchor type="underline" :offset="70">
    <el-anchor-link :href="`#${locale['basic-usage']}`">
      {{ locale['Basic Usage'] }}
    </el-anchor-link>
    <el-anchor-link :href="`#${locale['horizontal-mode']}`">
      {{ locale['Horizontal Mode'] }}
    </el-anchor-link>
    <el-anchor-link :href="`#${locale['scroll-container']}`">
      {{ locale['Scroll Container'] }}
    </el-anchor-link>
    <el-anchor-link :href="`#${locale['anchor-api']}`">
      {{ locale['Anchor API'] }}
      <template #sub-link>
        <el-anchor-link :href="`#${locale['anchor-attributes']}`">
          {{ locale['Anchor Attributes'] }}
        </el-anchor-link>
        <el-anchor-link :href="`#${locale['anchor-events']}`">
          {{ locale['Anchor Events'] }}
        </el-anchor-link>
      </template>
    </el-anchor-link>
  </el-anchor>
</template>

<script lang="ts" setup>
import { computed } from 'vue'
import anchorLocale from '../../.vitepress/i18n/component/anchor.json'
import { useLang } from '~/composables/lang'

const lang = useLang()
const locale = computed(() => anchorLocale[lang.value])
</script>
```

隐藏源代码

## 固定模式 [​](#固定模式)

使用 affix 组件来固定住页面中的锚点。

[基础用法](#基础用法)

[水平模式](#水平模式)

[滚动容器](#滚动的容器)

[Anchor API](#anchor-api)

[Anchor Attributes](#anchor-attributes)

[Anchor Events](#anchor-events)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYWZmaXggOm9mZnNldD1cIjYwXCI+XG4gICAgPGVsLWFuY2hvciA6b2Zmc2V0PVwiNzBcIiBzdHlsZT1cIndpZHRoOiAzMDBweFwiPlxuICAgICAgPGVsLWFuY2hvci1saW5rIDpocmVmPVwiYCMke2xvY2FsZVsnYmFzaWMtdXNhZ2UnXX1gXCI+XG4gICAgICAgIHt7IGxvY2FsZVsnQmFzaWMgVXNhZ2UnXSB9fVxuICAgICAgPC9lbC1hbmNob3ItbGluaz5cbiAgICAgIDxlbC1hbmNob3ItbGluayA6aHJlZj1cImAjJHtsb2NhbGVbJ2hvcml6b250YWwtbW9kZSddfWBcIj5cbiAgICAgICAge3sgbG9jYWxlWydIb3Jpem9udGFsIE1vZGUnXSB9fVxuICAgICAgPC9lbC1hbmNob3ItbGluaz5cbiAgICAgIDxlbC1hbmNob3ItbGluayA6aHJlZj1cImAjJHtsb2NhbGVbJ3Njcm9sbC1jb250YWluZXInXX1gXCI+XG4gICAgICAgIHt7IGxvY2FsZVsnU2Nyb2xsIENvbnRhaW5lciddIH19XG4gICAgICA8L2VsLWFuY2hvci1saW5rPlxuICAgICAgPGVsLWFuY2hvci1saW5rIDpocmVmPVwiYCMke2xvY2FsZVsnYW5jaG9yLWFwaSddfWBcIj5cbiAgICAgICAge3sgbG9jYWxlWydBbmNob3IgQVBJJ10gfX1cbiAgICAgICAgPHRlbXBsYXRlICNzdWItbGluaz5cbiAgICAgICAgICA8ZWwtYW5jaG9yLWxpbmsgOmhyZWY9XCJgIyR7bG9jYWxlWydhbmNob3ItYXR0cmlidXRlcyddfWBcIj5cbiAgICAgICAgICAgIHt7IGxvY2FsZVsnQW5jaG9yIEF0dHJpYnV0ZXMnXSB9fVxuICAgICAgICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gICAgICAgICAgPGVsLWFuY2hvci1saW5rIDpocmVmPVwiYCMke2xvY2FsZVsnYW5jaG9yLWV2ZW50cyddfWBcIj5cbiAgICAgICAgICAgIHt7IGxvY2FsZVsnQW5jaG9yIEV2ZW50cyddIH19XG4gICAgICAgICAgPC9lbC1hbmNob3ItbGluaz5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtYW5jaG9yLWxpbms+XG4gICAgPC9lbC1hbmNob3I+XG4gIDwvZWwtYWZmaXg+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgY29tcHV0ZWQgfSBmcm9tICd2dWUnXG5pbXBvcnQgYW5jaG9yTG9jYWxlIGZyb20gJy4uLy4uLy52aXRlcHJlc3MvaTE4bi9jb21wb25lbnQvYW5jaG9yLmpzb24nXG5pbXBvcnQgeyB1c2VMYW5nIH0gZnJvbSAnfi9jb21wb3NhYmxlcy9sYW5nJ1xuXG5jb25zdCBsYW5nID0gdXNlTGFuZygpXG5jb25zdCBsb2NhbGUgPSBjb21wdXRlZCgoKSA9PiBhbmNob3JMb2NhbGVbbGFuZy52YWx1ZV0pXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/anchor/affix.vue)_

vue

```
<template>
  <el-affix :offset="60">
    <el-anchor :offset="70" style="width: 300px">
      <el-anchor-link :href="`#${locale['basic-usage']}`">
        {{ locale['Basic Usage'] }}
      </el-anchor-link>
      <el-anchor-link :href="`#${locale['horizontal-mode']}`">
        {{ locale['Horizontal Mode'] }}
      </el-anchor-link>
      <el-anchor-link :href="`#${locale['scroll-container']}`">
        {{ locale['Scroll Container'] }}
      </el-anchor-link>
      <el-anchor-link :href="`#${locale['anchor-api']}`">
        {{ locale['Anchor API'] }}
        <template #sub-link>
          <el-anchor-link :href="`#${locale['anchor-attributes']}`">
            {{ locale['Anchor Attributes'] }}
          </el-anchor-link>
          <el-anchor-link :href="`#${locale['anchor-events']}`">
            {{ locale['Anchor Events'] }}
          </el-anchor-link>
        </template>
      </el-anchor-link>
    </el-anchor>
  </el-affix>
</template>

<script lang="ts" setup>
import { computed } from 'vue'
import anchorLocale from '../../.vitepress/i18n/component/anchor.json'
import { useLang } from '~/composables/lang'

const lang = useLang()
const locale = computed(() => anchorLocale[lang.value])
</script>
```

隐藏源代码

## Anchor API [​](#anchor-api)

### 属性 [​](#属性)

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| container | 滚动的容器 | `string` | `HTMLElement` | `Window` | — |
| offset | 设置锚点滚动的偏移量 | `number` | 0 |
| bound | 触发锚点的元素的位置偏移量 | `number` | 15 |
| duration | 设置容器滚动持续时间，单位为毫秒 | `number` | 300 |
| marker | 是否显示标记 | `boolean` | true |
| type | 设置锚点类型 | `enum` | `default` |
| direction | 设置锚点方向 | `enum` | `vertical` |
| select-scroll-top 2.9.2 | 滚动时，链接是否选中位于顶部 | `boolean` | false |

### Anchor Events [​](#anchor-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| change | step 改变时的回调 | `Function` |
| click | 当用户点击链接时触发 | `Function` |

### Anchor Exposes [​](#anchor-exposes)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| scrollTo | 手动滚动到特定位置。 | `Function` |

### Anchor Slots [​](#anchor-slots)

| 名称 | 说明 |
| --- | --- |
| default | AnchorLink 组件列表 |

### AnchorLink Attributes [​](#anchorlink-attributes)

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| title | 链接的文本内容 | `string` | — |
| href | 链接的地址。 | `string` | — |

### AnchorLink Slots [​](#anchorlink-slots)

| 名称 | 说明 |
| --- | --- |
| default | 链接的内容 |
| sub-link | 子链接的槽位 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/anchor) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/anchor.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/anchor.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/27912232?v=4&size=64)](https://github.com/Fuphoenixes)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/45098544?v=4&size=64)](https://github.com/tuzixiangs)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/48147837?v=4&size=64)](https://github.com/kcmeven)[![](https://avatars.githubusercontent.com/u/45616067?v=4&size=64)](https://github.com/elioist)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/8591261?v=4&size=64)](https://github.com/zeyongTsai)[![](https://avatars.githubusercontent.com/u/22683538?v=4&size=64)](https://github.com/hanyueqiang)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)

[Affix 固钉](https://element-plus.org/zh-CN/component/affix)

[Backtop 回到顶部](https://element-plus.org/zh-CN/component/backtop)




---
## [navigation/backtop] Backtop 回到顶部
> 官方文档: https://element-plus.org/zh-CN/component/backtop.html

---

# Backtop 回到顶部 [​](#backtop-回到顶部)

更新日志待解决

1

返回页面顶部的操作按钮。

## 基础用法 [​](#基础用法)

通过滑动来查看容器右下角的按钮。

Scroll down to see the bottom-right button.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICBTY3JvbGwgZG93biB0byBzZWUgdGhlIGJvdHRvbS1yaWdodCBidXR0b24uXG4gIDxlbC1iYWNrdG9wIDpyaWdodD1cIjEwMFwiIDpib3R0b209XCIxMDBcIiAvPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/backtop/basic.vue)_

vue

```
<template>
  Scroll down to see the bottom-right button.
  <el-backtop :right="100" :bottom="100" />
</template>
```

隐藏源代码

## 自定义内容 [​](#自定义内容)

显示区域被固定为 40px \* 40px 的区域，其中的内容可支持自定义。

Scroll down to see the bottom-right button.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICBTY3JvbGwgZG93biB0byBzZWUgdGhlIGJvdHRvbS1yaWdodCBidXR0b24uXG4gIDxlbC1iYWNrdG9wIDpib3R0b209XCIxMDBcIj5cbiAgICA8ZGl2XG4gICAgICBzdHlsZT1cIlxuICAgICAgICBoZWlnaHQ6IDEwMCU7XG4gICAgICAgIHdpZHRoOiAxMDAlO1xuICAgICAgICBiYWNrZ3JvdW5kLWNvbG9yOiB2YXIoLS1lbC1iZy1jb2xvci1vdmVybGF5KTtcbiAgICAgICAgYm94LXNoYWRvdzogdmFyKC0tZWwtYm94LXNoYWRvdy1saWdodGVyKTtcbiAgICAgICAgdGV4dC1hbGlnbjogY2VudGVyO1xuICAgICAgICBsaW5lLWhlaWdodDogNDBweDtcbiAgICAgICAgY29sb3I6ICMxOTg5ZmE7XG4gICAgICBcIlxuICAgID5cbiAgICAgIFVQXG4gICAgPC9kaXY+XG4gIDwvZWwtYmFja3RvcD5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/backtop/custom.vue)_

vue

```
<template>
  Scroll down to see the bottom-right button.
  <el-backtop :bottom="100">
    <div
      style="
        height: 100%;
        width: 100%;
        background-color: var(--el-bg-color-overlay);
        box-shadow: var(--el-box-shadow-lighter);
        text-align: center;
        line-height: 40px;
        color: #1989fa;
      "
    >
      UP
    </div>
  </el-backtop>
</template>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 名称 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| target | 触发滚动的对象 | `string` | — |
| visibility-height | 滚动高度达到此参数值才出现 | `number` | 200 |
| right | 控制其显示位置，距离页面右边距 | `number` | 40 |
| bottom | 控制其显示位置，距离页面底部距离 | `number` | 40 |

### Events [​](#events)

| 名称 | 说明 | 回调参数 |
| --- | --- | --- |
| click | 点击按钮触发的事件 | `Function` |

### Slots [​](#slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/backtop) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/backtop.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/backtop.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/59350883?v=4&size=64)](https://github.com/init-qy)[![](https://avatars.githubusercontent.com/u/5701072?v=4&size=64)](https://github.com/Naeemo)[![](https://avatars.githubusercontent.com/u/110765073?v=4&size=64)](https://github.com/fwr220807)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)

[Anchor 锚点](https://element-plus.org/zh-CN/component/anchor)

[Breadcrumb 面包屑](https://element-plus.org/zh-CN/component/breadcrumb)




---
## [navigation/breadcrumb] Breadcrumb 面包屑
> 官方文档: https://element-plus.org/zh-CN/component/breadcrumb.html

---

# Breadcrumb 面包屑 [​](#breadcrumb-面包屑)

更新日志待解决

0

显示当前页面的路径，快速返回之前的任意页面。

## 基础用法 [​](#基础用法)

在 `el-breadcrumb` 中使用 `el-breadcrumb-item` 标签表示从首页开始的每一级。 该组件接受一个 `String` 类型的参数 `separator`来作为分隔符。 默认值为 '/'。

homepage/[promotion management](https://element-plus.org/)/promotion list/promotion detail/

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnJlYWRjcnVtYiBzZXBhcmF0b3I9XCIvXCI+XG4gICAgPGVsLWJyZWFkY3J1bWItaXRlbSA6dG89XCJ7IHBhdGg6ICcvJyB9XCI+aG9tZXBhZ2U8L2VsLWJyZWFkY3J1bWItaXRlbT5cbiAgICA8ZWwtYnJlYWRjcnVtYi1pdGVtPlxuICAgICAgPGEgaHJlZj1cIi9cIj5wcm9tb3Rpb24gbWFuYWdlbWVudDwvYT5cbiAgICA8L2VsLWJyZWFkY3J1bWItaXRlbT5cbiAgICA8ZWwtYnJlYWRjcnVtYi1pdGVtPnByb21vdGlvbiBsaXN0PC9lbC1icmVhZGNydW1iLWl0ZW0+XG4gICAgPGVsLWJyZWFkY3J1bWItaXRlbT5wcm9tb3Rpb24gZGV0YWlsPC9lbC1icmVhZGNydW1iLWl0ZW0+XG4gIDwvZWwtYnJlYWRjcnVtYj5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/breadcrumb/basic.vue)_

vue

```
<template>
  <el-breadcrumb separator="/">
    <el-breadcrumb-item :to="{ path: '/' }">homepage</el-breadcrumb-item>
    <el-breadcrumb-item>
      <a href="/">promotion management</a>
    </el-breadcrumb-item>
    <el-breadcrumb-item>promotion list</el-breadcrumb-item>
    <el-breadcrumb-item>promotion detail</el-breadcrumb-item>
  </el-breadcrumb>
</template>
```

隐藏源代码

## 图标分隔符 [​](#图标分隔符)

通过设置 `separator-class` 可使用相应的 `iconfont` 作为分隔符，注意这将使 `separator` 失效。

homepagepromotion managementpromotion listpromotion detail

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnJlYWRjcnVtYiA6c2VwYXJhdG9yLWljb249XCJBcnJvd1JpZ2h0XCI+XG4gICAgPGVsLWJyZWFkY3J1bWItaXRlbSA6dG89XCJ7IHBhdGg6ICcvJyB9XCI+aG9tZXBhZ2U8L2VsLWJyZWFkY3J1bWItaXRlbT5cbiAgICA8ZWwtYnJlYWRjcnVtYi1pdGVtPnByb21vdGlvbiBtYW5hZ2VtZW50PC9lbC1icmVhZGNydW1iLWl0ZW0+XG4gICAgPGVsLWJyZWFkY3J1bWItaXRlbT5wcm9tb3Rpb24gbGlzdDwvZWwtYnJlYWRjcnVtYi1pdGVtPlxuICAgIDxlbC1icmVhZGNydW1iLWl0ZW0+cHJvbW90aW9uIGRldGFpbDwvZWwtYnJlYWRjcnVtYi1pdGVtPlxuICA8L2VsLWJyZWFkY3J1bWI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgQXJyb3dSaWdodCB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/breadcrumb/icon.vue)_

vue

```
<template>
  <el-breadcrumb :separator-icon="ArrowRight">
    <el-breadcrumb-item :to="{ path: '/' }">homepage</el-breadcrumb-item>
    <el-breadcrumb-item>promotion management</el-breadcrumb-item>
    <el-breadcrumb-item>promotion list</el-breadcrumb-item>
    <el-breadcrumb-item>promotion detail</el-breadcrumb-item>
  </el-breadcrumb>
</template>

<script lang="ts" setup>
import { ArrowRight } from '@element-plus/icons-vue'
</script>
```

隐藏源代码

## Breadcrumb API [​](#breadcrumb-api)

### Breadcrumb Attributes [​](#breadcrumb-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| separator | 分隔符 | `string` | / |
| separator-icon | 图标分隔符的组件或组件名 | `string` / `Component` | — |

### Breadcrumb Slots [​](#breadcrumb-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | Breadcrumb Item |

## BreadcrumbItem API [​](#breadcrumbitem-api)

### BreadcrumbItem Attributes [​](#breadcrumbitem-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| to | 路由跳转目标，同 `vue-router` 的 `to` 属性 | `string` / `object` | '' |
| replace | 如果设置该属性为 `true`, 导航将不会留下历史记录 | `boolean` | false |

### BreadcrumbItem Slots [​](#breadcrumbitem-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/breadcrumb) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/breadcrumb.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/breadcrumb.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/42489652?v=4&size=64)](https://github.com/GGupzHH)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)

[Backtop 回到顶部](https://element-plus.org/zh-CN/component/backtop)

[Dropdown 下拉菜单](https://element-plus.org/zh-CN/component/dropdown)




---
## [navigation/dropdown] Dropdown 下拉菜单
> 官方文档: https://element-plus.org/zh-CN/component/dropdown.html

---

# Dropdown 下拉菜单 [​](#dropdown-下拉菜单)

更新日志待解决

24

将动作或菜单折叠到下拉菜单中。

## 基础用法 [​](#基础用法)

悬停在下拉菜单上以展开更多操作。

通过组件 `slot` 来设置下拉触发的元素以及需要通过具名 `slot` 为 `dropdown` 来设置下拉菜单。 默认情况下，只需要悬停在触发菜单的元素上即可，无需点击也会显示下拉菜单。

Dropdown List

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZHJvcGRvd24+XG4gICAgPHNwYW4gY2xhc3M9XCJlbC1kcm9wZG93bi1saW5rXCI+XG4gICAgICBEcm9wZG93biBMaXN0XG4gICAgICA8ZWwtaWNvbiBjbGFzcz1cImVsLWljb24tLXJpZ2h0XCI+XG4gICAgICAgIDxhcnJvdy1kb3duIC8+XG4gICAgICA8L2VsLWljb24+XG4gICAgPC9zcGFuPlxuICAgIDx0ZW1wbGF0ZSAjZHJvcGRvd24+XG4gICAgICA8ZWwtZHJvcGRvd24tbWVudT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0+QWN0aW9uIDE8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPkFjdGlvbiAyPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gMzwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gZGlzYWJsZWQ+QWN0aW9uIDQ8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIGRpdmlkZWQ+QWN0aW9uIDU8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICA8L2VsLWRyb3Bkb3duLW1lbnU+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1kcm9wZG93bj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBBcnJvd0Rvd24gfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmV4YW1wbGUtc2hvd2Nhc2UgLmVsLWRyb3Bkb3duLWxpbmsge1xuICBjdXJzb3I6IHBvaW50ZXI7XG4gIGNvbG9yOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dropdown/basic-usage.vue)_

vue

```
<template>
  <el-dropdown>
    <span class="el-dropdown-link">
      Dropdown List
      <el-icon class="el-icon--right">
        <arrow-down />
      </el-icon>
    </span>
    <template #dropdown>
      <el-dropdown-menu>
        <el-dropdown-item>Action 1</el-dropdown-item>
        <el-dropdown-item>Action 2</el-dropdown-item>
        <el-dropdown-item>Action 3</el-dropdown-item>
        <el-dropdown-item disabled>Action 4</el-dropdown-item>
        <el-dropdown-item divided>Action 5</el-dropdown-item>
      </el-dropdown-menu>
    </template>
  </el-dropdown>
</template>

<script lang="ts" setup>
import { ArrowDown } from '@element-plus/icons-vue'
</script>

<style scoped>
.example-showcase .el-dropdown-link {
  cursor: pointer;
  color: var(--el-color-primary);
  display: flex;
  align-items: center;
}
</style>
```

隐藏源代码

## 位置 [​](#位置)

支持 6 个位置。

设置 `placement` 属性，使下拉菜单出现在不同位置。

topStart

top

topEnd

bottomStart

bottom

bottomEnd

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgaXRlbXMtY2VudGVyIGdhcC00XCI+XG4gICAgPGVsLWRyb3Bkb3duIHBsYWNlbWVudD1cInRvcC1zdGFydFwiPlxuICAgICAgPGVsLWJ1dHRvbj4gdG9wU3RhcnQgPC9lbC1idXR0b24+XG4gICAgICA8dGVtcGxhdGUgI2Ryb3Bkb3duPlxuICAgICAgICA8ZWwtZHJvcGRvd24tbWVudT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5UaGUgQWN0aW9uIDFzdDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5UaGUgQWN0aW9uIDJuZDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5UaGUgQWN0aW9uIDNyZDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPC9lbC1kcm9wZG93bi1tZW51PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWRyb3Bkb3duPlxuICAgIDxlbC1kcm9wZG93biBwbGFjZW1lbnQ9XCJ0b3BcIj5cbiAgICAgIDxlbC1idXR0b24+IHRvcCA8L2VsLWJ1dHRvbj5cbiAgICAgIDx0ZW1wbGF0ZSAjZHJvcGRvd24+XG4gICAgICAgIDxlbC1kcm9wZG93bi1tZW51PlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gMXN0PC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gMm5kPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gM3JkPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8L2VsLWRyb3Bkb3duLW1lbnU+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtZHJvcGRvd24+XG4gICAgPGVsLWRyb3Bkb3duIHBsYWNlbWVudD1cInRvcC1lbmRcIj5cbiAgICAgIDxlbC1idXR0b24+IHRvcEVuZCA8L2VsLWJ1dHRvbj5cbiAgICAgIDx0ZW1wbGF0ZSAjZHJvcGRvd24+XG4gICAgICAgIDxlbC1kcm9wZG93bi1tZW51PlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gMXN0PC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gMm5kPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gM3JkPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8L2VsLWRyb3Bkb3duLW1lbnU+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtZHJvcGRvd24+XG4gICAgPGVsLWRyb3Bkb3duIHBsYWNlbWVudD1cImJvdHRvbS1zdGFydFwiPlxuICAgICAgPGVsLWJ1dHRvbj4gYm90dG9tU3RhcnQgPC9lbC1idXR0b24+XG4gICAgICA8dGVtcGxhdGUgI2Ryb3Bkb3duPlxuICAgICAgICA8ZWwtZHJvcGRvd24tbWVudT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5UaGUgQWN0aW9uIDFzdDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5UaGUgQWN0aW9uIDJuZDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5UaGUgQWN0aW9uIDNyZDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPC9lbC1kcm9wZG93bi1tZW51PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWRyb3Bkb3duPlxuICAgIDxlbC1kcm9wZG93biBwbGFjZW1lbnQ9XCJib3R0b21cIj5cbiAgICAgIDxlbC1idXR0b24+IGJvdHRvbSA8L2VsLWJ1dHRvbj5cbiAgICAgIDx0ZW1wbGF0ZSAjZHJvcGRvd24+XG4gICAgICAgIDxlbC1kcm9wZG93bi1tZW51PlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gMXN0PC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gMm5kPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gM3JkPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8L2VsLWRyb3Bkb3duLW1lbnU+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtZHJvcGRvd24+XG4gICAgPGVsLWRyb3Bkb3duIHBsYWNlbWVudD1cImJvdHRvbS1lbmRcIj5cbiAgICAgIDxlbC1idXR0b24+IGJvdHRvbUVuZCA8L2VsLWJ1dHRvbj5cbiAgICAgIDx0ZW1wbGF0ZSAjZHJvcGRvd24+XG4gICAgICAgIDxlbC1kcm9wZG93bi1tZW51PlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gMXN0PC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gMm5kPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPlRoZSBBY3Rpb24gM3JkPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8L2VsLWRyb3Bkb3duLW1lbnU+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtZHJvcGRvd24+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dropdown/placements.vue)_

vue

```
<template>
  <div class="flex flex-wrap items-center gap-4">
    <el-dropdown placement="top-start">
      <el-button> topStart </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="top">
      <el-button> top </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="top-end">
      <el-button> topEnd </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="bottom-start">
      <el-button> bottomStart </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="bottom">
      <el-button> bottom </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="bottom-end">
      <el-button> bottomEnd </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
  </div>
</template>
```

隐藏源代码

## 触发对象 [​](#触发对象)

可使用按钮触发下拉菜单。

设置 `split-button` 属性来让触发下拉元素呈现为按钮组，左边是功能按钮，右边是触发下拉菜单的按钮，设置为 `true` 即可。 如果你想要在第三和第四个选项之间添加一个分隔符，你只需要为第四个选项添加一个 `divided` 的属性。

Dropdown List

Dropdown List

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgaXRlbXMtY2VudGVyXCI+XG4gICAgPGVsLWRyb3Bkb3duPlxuICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiPlxuICAgICAgICBEcm9wZG93biBMaXN0PGVsLWljb24gY2xhc3M9XCJlbC1pY29uLS1yaWdodFwiPjxhcnJvdy1kb3duIC8+PC9lbC1pY29uPlxuICAgICAgPC9lbC1idXR0b24+XG4gICAgICA8dGVtcGxhdGUgI2Ryb3Bkb3duPlxuICAgICAgICA8ZWwtZHJvcGRvd24tbWVudT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gMTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gMjwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gMzwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gNDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gNTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPC9lbC1kcm9wZG93bi1tZW51PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWRyb3Bkb3duPlxuICAgIDxlbC1kcm9wZG93biBzcGxpdC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBAY2xpY2s9XCJoYW5kbGVDbGlja1wiPlxuICAgICAgRHJvcGRvd24gTGlzdFxuICAgICAgPHRlbXBsYXRlICNkcm9wZG93bj5cbiAgICAgICAgPGVsLWRyb3Bkb3duLW1lbnU+XG4gICAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0+QWN0aW9uIDE8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0+QWN0aW9uIDI8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0+QWN0aW9uIDM8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gZGl2aWRlZD5BY3Rpb24gNDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gNTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPC9lbC1kcm9wZG93bi1tZW51PlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICA8L2VsLWRyb3Bkb3duPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBBcnJvd0Rvd24gfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgaGFuZGxlQ2xpY2sgPSAoKSA9PiB7XG4gIC8vIGVzbGludC1kaXNhYmxlLW5leHQtbGluZSBuby1hbGVydFxuICBhbGVydCgnYnV0dG9uIGNsaWNrJylcbn1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmV4YW1wbGUtc2hvd2Nhc2UgLmVsLWRyb3Bkb3duICsgLmVsLWRyb3Bkb3duIHtcbiAgbWFyZ2luLWxlZnQ6IDE1cHg7XG59XG4uZXhhbXBsZS1zaG93Y2FzZSAuZWwtZHJvcGRvd24tbGluayB7XG4gIGN1cnNvcjogcG9pbnRlcjtcbiAgY29sb3I6IHZhcigtLWVsLWNvbG9yLXByaW1hcnkpO1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dropdown/triggering-element.vue)_

vue

```
<template>
  <div class="flex flex-wrap items-center">
    <el-dropdown>
      <el-button type="primary">
        Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
      </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>Action 1</el-dropdown-item>
          <el-dropdown-item>Action 2</el-dropdown-item>
          <el-dropdown-item>Action 3</el-dropdown-item>
          <el-dropdown-item>Action 4</el-dropdown-item>
          <el-dropdown-item>Action 5</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown split-button type="primary" @click="handleClick">
      Dropdown List
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>Action 1</el-dropdown-item>
          <el-dropdown-item>Action 2</el-dropdown-item>
          <el-dropdown-item>Action 3</el-dropdown-item>
          <el-dropdown-item divided>Action 4</el-dropdown-item>
          <el-dropdown-item>Action 5</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
  </div>
</template>

<script lang="ts" setup>
import { ArrowDown } from '@element-plus/icons-vue'

const handleClick = () => {
  // eslint-disable-next-line no-alert
  alert('button click')
}
</script>

<style scoped>
.example-showcase .el-dropdown + .el-dropdown {
  margin-left: 15px;
}
.example-showcase .el-dropdown-link {
  cursor: pointer;
  color: var(--el-color-primary);
  display: flex;
  align-items: center;
}
</style>
```

隐藏源代码

## 触发方式 [​](#触发方式)

可以配置点击激活或者悬停激活。

将 `trigger` 属性设置为 click 即可， 默认为 `hover`。

hover to trigger

Dropdown List

right click to trigger

Dropdown List

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IGNsYXNzPVwiYmxvY2stY29sLTJcIj5cbiAgICA8ZWwtY29sIDpzcGFuPVwiOFwiPlxuICAgICAgPHNwYW4gY2xhc3M9XCJkZW1vbnN0cmF0aW9uXCI+aG92ZXIgdG8gdHJpZ2dlcjwvc3Bhbj5cbiAgICAgIDxlbC1kcm9wZG93bj5cbiAgICAgICAgPHNwYW4gY2xhc3M9XCJlbC1kcm9wZG93bi1saW5rXCI+XG4gICAgICAgICAgRHJvcGRvd24gTGlzdDxlbC1pY29uIGNsYXNzPVwiZWwtaWNvbi0tcmlnaHRcIj48YXJyb3ctZG93biAvPjwvZWwtaWNvbj5cbiAgICAgICAgPC9zcGFuPlxuICAgICAgICA8dGVtcGxhdGUgI2Ryb3Bkb3duPlxuICAgICAgICAgIDxlbC1kcm9wZG93bi1tZW51PlxuICAgICAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gOmljb249XCJQbHVzXCI+QWN0aW9uIDE8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSA6aWNvbj1cIkNpcmNsZVBsdXNGaWxsZWRcIj5cbiAgICAgICAgICAgICAgQWN0aW9uIDJcbiAgICAgICAgICAgIDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIDppY29uPVwiQ2lyY2xlUGx1c1wiPkFjdGlvbiAzPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gOmljb249XCJDaGVja1wiPkFjdGlvbiA0PC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gOmljb249XCJDaXJjbGVDaGVja1wiPkFjdGlvbiA1PC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgIDwvZWwtZHJvcGRvd24tbWVudT5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtZHJvcGRvd24+XG4gICAgPC9lbC1jb2w+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjhcIj5cbiAgICAgIDxzcGFuIGNsYXNzPVwiZGVtb25zdHJhdGlvblwiPmNsaWNrIHRvIHRyaWdnZXI8L3NwYW4+XG4gICAgICA8ZWwtZHJvcGRvd24gdHJpZ2dlcj1cImNsaWNrXCI+XG4gICAgICAgIDxzcGFuIGNsYXNzPVwiZWwtZHJvcGRvd24tbGlua1wiPlxuICAgICAgICAgIERyb3Bkb3duIExpc3Q8ZWwtaWNvbiBjbGFzcz1cImVsLWljb24tLXJpZ2h0XCI+PGFycm93LWRvd24gLz48L2VsLWljb24+XG4gICAgICAgIDwvc3Bhbj5cbiAgICAgICAgPHRlbXBsYXRlICNkcm9wZG93bj5cbiAgICAgICAgICA8ZWwtZHJvcGRvd24tbWVudT5cbiAgICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIDppY29uPVwiUGx1c1wiPkFjdGlvbiAxPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gOmljb249XCJDaXJjbGVQbHVzRmlsbGVkXCI+XG4gICAgICAgICAgICAgIEFjdGlvbiAyXG4gICAgICAgICAgICA8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSA6aWNvbj1cIkNpcmNsZVBsdXNcIj5BY3Rpb24gMzwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIDppY29uPVwiQ2hlY2tcIj5BY3Rpb24gNDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIDppY29uPVwiQ2lyY2xlQ2hlY2tcIj5BY3Rpb24gNTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICA8L2VsLWRyb3Bkb3duLW1lbnU+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLWRyb3Bkb3duPlxuICAgIDwvZWwtY29sPlxuICAgIDxlbC1jb2wgOnNwYW49XCI4XCI+XG4gICAgICA8c3BhbiBjbGFzcz1cImRlbW9uc3RyYXRpb25cIj5yaWdodCBjbGljayB0byB0cmlnZ2VyPC9zcGFuPlxuICAgICAgPGVsLWRyb3Bkb3duIHRyaWdnZXI9XCJjb250ZXh0bWVudVwiPlxuICAgICAgICA8c3BhbiBjbGFzcz1cImVsLWRyb3Bkb3duLWxpbmtcIj5cbiAgICAgICAgICBEcm9wZG93biBMaXN0PGVsLWljb24gY2xhc3M9XCJlbC1pY29uLS1yaWdodFwiPjxhcnJvdy1kb3duIC8+PC9lbC1pY29uPlxuICAgICAgICA8L3NwYW4+XG4gICAgICAgIDx0ZW1wbGF0ZSAjZHJvcGRvd24+XG4gICAgICAgICAgPGVsLWRyb3Bkb3duLW1lbnU+XG4gICAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSA6aWNvbj1cIlBsdXNcIj5BY3Rpb24gMTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIDppY29uPVwiQ2lyY2xlUGx1c0ZpbGxlZFwiPlxuICAgICAgICAgICAgICBBY3Rpb24gMlxuICAgICAgICAgICAgPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gOmljb249XCJDaXJjbGVQbHVzXCI+QWN0aW9uIDM8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSA6aWNvbj1cIkNoZWNrXCI+QWN0aW9uIDQ8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSA6aWNvbj1cIkNpcmNsZUNoZWNrXCI+QWN0aW9uIDU8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgICAgPC9lbC1kcm9wZG93bi1tZW51PlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1kcm9wZG93bj5cbiAgICA8L2VsLWNvbD5cbiAgPC9lbC1yb3c+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHtcbiAgQXJyb3dEb3duLFxuICBDaGVjayxcbiAgQ2lyY2xlQ2hlY2ssXG4gIENpcmNsZVBsdXMsXG4gIENpcmNsZVBsdXNGaWxsZWQsXG4gIFBsdXMsXG59IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uYmxvY2stY29sLTIgLmRlbW9uc3RyYXRpb24ge1xuICBkaXNwbGF5OiBibG9jaztcbiAgY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3Itc2Vjb25kYXJ5KTtcbiAgZm9udC1zaXplOiAxNHB4O1xuICBtYXJnaW4tYm90dG9tOiAyMHB4O1xufVxuXG4uYmxvY2stY29sLTIgLmVsLWRyb3Bkb3duLWxpbmsge1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dropdown/how-to-trigger.vue)_

vue

```
<template>
  <el-row class="block-col-2">
    <el-col :span="8">
      <span class="demonstration">hover to trigger</span>
      <el-dropdown>
        <span class="el-dropdown-link">
          Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
        </span>
        <template #dropdown>
          <el-dropdown-menu>
            <el-dropdown-item :icon="Plus">Action 1</el-dropdown-item>
            <el-dropdown-item :icon="CirclePlusFilled">
              Action 2
            </el-dropdown-item>
            <el-dropdown-item :icon="CirclePlus">Action 3</el-dropdown-item>
            <el-dropdown-item :icon="Check">Action 4</el-dropdown-item>
            <el-dropdown-item :icon="CircleCheck">Action 5</el-dropdown-item>
          </el-dropdown-menu>
        </template>
      </el-dropdown>
    </el-col>
    <el-col :span="8">
      <span class="demonstration">click to trigger</span>
      <el-dropdown trigger="click">
        <span class="el-dropdown-link">
          Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
        </span>
        <template #dropdown>
          <el-dropdown-menu>
            <el-dropdown-item :icon="Plus">Action 1</el-dropdown-item>
            <el-dropdown-item :icon="CirclePlusFilled">
              Action 2
            </el-dropdown-item>
            <el-dropdown-item :icon="CirclePlus">Action 3</el-dropdown-item>
            <el-dropdown-item :icon="Check">Action 4</el-dropdown-item>
            <el-dropdown-item :icon="CircleCheck">Action 5</el-dropdown-item>
          </el-dropdown-menu>
        </template>
      </el-dropdown>
    </el-col>
    <el-col :span="8">
      <span class="demonstration">right click to trigger</span>
      <el-dropdown trigger="contextmenu">
        <span class="el-dropdown-link">
          Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
        </span>
        <template #dropdown>
          <el-dropdown-menu>
            <el-dropdown-item :icon="Plus">Action 1</el-dropdown-item>
            <el-dropdown-item :icon="CirclePlusFilled">
              Action 2
            </el-dropdown-item>
            <el-dropdown-item :icon="CirclePlus">Action 3</el-dropdown-item>
            <el-dropdown-item :icon="Check">Action 4</el-dropdown-item>
            <el-dropdown-item :icon="CircleCheck">Action 5</el-dropdown-item>
          </el-dropdown-menu>
        </template>
      </el-dropdown>
    </el-col>
  </el-row>
</template>

<script lang="ts" setup>
import {
  ArrowDown,
  Check,
  CircleCheck,
  CirclePlus,
  CirclePlusFilled,
  Plus,
} from '@element-plus/icons-vue'
</script>

<style scoped>
.block-col-2 .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}

.block-col-2 .el-dropdown-link {
  display: flex;
  align-items: center;
}
</style>
```

隐藏源代码

## 菜单隐藏方式 [​](#菜单隐藏方式)

可以通过 `hide-on-click` 属性来配置。

下拉菜单默认在点击菜单项后会被隐藏，将 hide-on-click 属性设置为 false 可以关闭此功能。

Dropdown List

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZHJvcGRvd24gOmhpZGUtb24tY2xpY2s9XCJmYWxzZVwiPlxuICAgIDxzcGFuIGNsYXNzPVwiZWwtZHJvcGRvd24tbGlua1wiPlxuICAgICAgRHJvcGRvd24gTGlzdDxlbC1pY29uIGNsYXNzPVwiZWwtaWNvbi0tcmlnaHRcIj48YXJyb3ctZG93biAvPjwvZWwtaWNvbj5cbiAgICA8L3NwYW4+XG4gICAgPHRlbXBsYXRlICNkcm9wZG93bj5cbiAgICAgIDxlbC1kcm9wZG93bi1tZW51PlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gMTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0+QWN0aW9uIDI8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPkFjdGlvbiAzPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSBkaXNhYmxlZD5BY3Rpb24gNDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gZGl2aWRlZD5BY3Rpb24gNTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gZGl2aWRlZD5BY3Rpb24gNjwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgIDwvZWwtZHJvcGRvd24tbWVudT5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLWRyb3Bkb3duPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IEFycm93RG93biB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZXhhbXBsZS1zaG93Y2FzZSAuZWwtZHJvcGRvd24gKyAuZWwtZHJvcGRvd24ge1xuICBtYXJnaW4tbGVmdDogMTVweDtcbn1cbi5leGFtcGxlLXNob3djYXNlIC5lbC1kcm9wZG93bi1saW5rIHtcbiAgY3Vyc29yOiBwb2ludGVyO1xuICBjb2xvcjogdmFyKC0tZWwtY29sb3ItcHJpbWFyeSk7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dropdown/menu-hiding-behavior.vue)_

vue

```
<template>
  <el-dropdown :hide-on-click="false">
    <span class="el-dropdown-link">
      Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
    </span>
    <template #dropdown>
      <el-dropdown-menu>
        <el-dropdown-item>Action 1</el-dropdown-item>
        <el-dropdown-item>Action 2</el-dropdown-item>
        <el-dropdown-item>Action 3</el-dropdown-item>
        <el-dropdown-item disabled>Action 4</el-dropdown-item>
        <el-dropdown-item divided>Action 5</el-dropdown-item>
        <el-dropdown-item divided>Action 6</el-dropdown-item>
      </el-dropdown-menu>
    </template>
  </el-dropdown>
</template>

<script lang="ts" setup>
import { ArrowDown } from '@element-plus/icons-vue'
</script>

<style scoped>
.example-showcase .el-dropdown + .el-dropdown {
  margin-left: 15px;
}
.example-showcase .el-dropdown-link {
  cursor: pointer;
  color: var(--el-color-primary);
  display: flex;
  align-items: center;
}
</style>
```

隐藏源代码

## 指令事件 [​](#指令事件)

点击菜单项后会触发事件，用户可以通过相应的菜单项 key 进行不同的操作。

Dropdown List

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZHJvcGRvd24gQGNvbW1hbmQ9XCJoYW5kbGVDb21tYW5kXCI+XG4gICAgPHNwYW4gY2xhc3M9XCJlbC1kcm9wZG93bi1saW5rXCI+XG4gICAgICBEcm9wZG93biBMaXN0PGVsLWljb24gY2xhc3M9XCJlbC1pY29uLS1yaWdodFwiPjxhcnJvdy1kb3duIC8+PC9lbC1pY29uPlxuICAgIDwvc3Bhbj5cbiAgICA8dGVtcGxhdGUgI2Ryb3Bkb3duPlxuICAgICAgPGVsLWRyb3Bkb3duLW1lbnU+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIGNvbW1hbmQ9XCJhXCI+QWN0aW9uIDE8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIGNvbW1hbmQ9XCJiXCI+QWN0aW9uIDI8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIGNvbW1hbmQ9XCJjXCI+QWN0aW9uIDM8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIGNvbW1hbmQ9XCJkXCIgZGlzYWJsZWQ+QWN0aW9uIDQ8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIGNvbW1hbmQ9XCJlXCIgZGl2aWRlZD5BY3Rpb24gNTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgIDwvZWwtZHJvcGRvd24tbWVudT5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLWRyb3Bkb3duPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IEVsTWVzc2FnZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcbmltcG9ydCB7IEFycm93RG93biB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5jb25zdCBoYW5kbGVDb21tYW5kID0gKGNvbW1hbmQ6IHN0cmluZyB8IG51bWJlciB8IG9iamVjdCkgPT4ge1xuICBFbE1lc3NhZ2UoYGNsaWNrIG9uIGl0ZW0gJHtjb21tYW5kfWApXG59XG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5leGFtcGxlLXNob3djYXNlIC5lbC1kcm9wZG93bi1saW5rIHtcbiAgY3Vyc29yOiBwb2ludGVyO1xuICBjb2xvcjogdmFyKC0tZWwtY29sb3ItcHJpbWFyeSk7XG4gIGRpc3BsYXk6IGZsZXg7XG4gIGFsaWduLWl0ZW1zOiBjZW50ZXI7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dropdown/command-event.vue)_

vue

```
<template>
  <el-dropdown @command="handleCommand">
    <span class="el-dropdown-link">
      Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
    </span>
    <template #dropdown>
      <el-dropdown-menu>
        <el-dropdown-item command="a">Action 1</el-dropdown-item>
        <el-dropdown-item command="b">Action 2</el-dropdown-item>
        <el-dropdown-item command="c">Action 3</el-dropdown-item>
        <el-dropdown-item command="d" disabled>Action 4</el-dropdown-item>
        <el-dropdown-item command="e" divided>Action 5</el-dropdown-item>
      </el-dropdown-menu>
    </template>
  </el-dropdown>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus'
import { ArrowDown } from '@element-plus/icons-vue'

const handleCommand = (command: string | number | object) => {
  ElMessage(`click on item ${command}`)
}
</script>

<style scoped>
.example-showcase .el-dropdown-link {
  cursor: pointer;
  color: var(--el-color-primary);
  display: flex;
  align-items: center;
}
</style>
```

隐藏源代码

## 下拉方法 [​](#下拉方法)

您可以手动使用 `手动打开` 或 `手动关闭下拉菜单以打开或关闭`

open(close) the Dropdown list2 will close(open) the Dropdown List1.

show

Dropdown List1

Dropdown List2

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwiZm9udC1zaXplOiAxNHB4XCI+XG4gICAgPHA+b3BlbihjbG9zZSkgdGhlIERyb3Bkb3duIGxpc3QyIHdpbGwgY2xvc2Uob3BlbikgdGhlIERyb3Bkb3duIExpc3QxLjwvcD5cbiAgPC9kaXY+XG4gIDxkaXYgc3R5bGU9XCJtYXJnaW46IDE1cHhcIj5cbiAgICA8ZWwtYnV0dG9uIEBjbGljaz1cInNob3dDbGlja1wiPnNob3c8L2VsLWJ1dHRvbj5cbiAgPC9kaXY+XG4gIDxlbC1kcm9wZG93biByZWY9XCJkcm9wZG93bjFcIiB0cmlnZ2VyPVwiY29udGV4dG1lbnVcIiBzdHlsZT1cIm1hcmdpbi1yaWdodDogMzBweFwiPlxuICAgIDxzcGFuIGNsYXNzPVwiZWwtZHJvcGRvd24tbGlua1wiPiBEcm9wZG93biBMaXN0MSA8L3NwYW4+XG4gICAgPHRlbXBsYXRlICNkcm9wZG93bj5cbiAgICAgIDxlbC1kcm9wZG93bi1tZW51PlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gMTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0+QWN0aW9uIDI8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPkFjdGlvbiAzPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSBkaXNhYmxlZD5BY3Rpb24gNDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gZGl2aWRlZD5BY3Rpb24gNTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgIDwvZWwtZHJvcGRvd24tbWVudT5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLWRyb3Bkb3duPlxuXG4gIDxlbC1kcm9wZG93biB0cmlnZ2VyPVwiY29udGV4dG1lbnVcIiBAdmlzaWJsZS1jaGFuZ2U9XCJoYW5kbGVWaXNpYmxlMlwiPlxuICAgIDxzcGFuIGNsYXNzPVwiZWwtZHJvcGRvd24tbGlua1wiPiBEcm9wZG93biBMaXN0MiA8L3NwYW4+XG4gICAgPHRlbXBsYXRlICNkcm9wZG93bj5cbiAgICAgIDxlbC1kcm9wZG93bi1tZW51PlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gMTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0+QWN0aW9uIDI8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPkFjdGlvbiAzPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSBkaXNhYmxlZD5BY3Rpb24gNDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gZGl2aWRlZD5BY3Rpb24gNTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgIDwvZWwtZHJvcGRvd24tbWVudT5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLWRyb3Bkb3duPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBEcm9wZG93bkluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBkcm9wZG93bjEgPSByZWY8RHJvcGRvd25JbnN0YW5jZT4oKVxuZnVuY3Rpb24gaGFuZGxlVmlzaWJsZTIodmlzaWJsZTogYW55KSB7XG4gIGlmICghZHJvcGRvd24xLnZhbHVlKSByZXR1cm5cbiAgaWYgKHZpc2libGUpIHtcbiAgICBkcm9wZG93bjEudmFsdWUuaGFuZGxlQ2xvc2UoKVxuICB9IGVsc2Uge1xuICAgIGRyb3Bkb3duMS52YWx1ZS5oYW5kbGVPcGVuKClcbiAgfVxufVxuZnVuY3Rpb24gc2hvd0NsaWNrKCkge1xuICBpZiAoIWRyb3Bkb3duMS52YWx1ZSkgcmV0dXJuXG4gIGRyb3Bkb3duMS52YWx1ZS5oYW5kbGVPcGVuKClcbn1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmV4YW1wbGUtc2hvd2Nhc2UgLmVsLWRyb3Bkb3duLWxpbmsge1xuICBjdXJzb3I6IHBvaW50ZXI7XG4gIGNvbG9yOiB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dropdown/dropdown-methods.vue)_

vue

```
<template>
  <div style="font-size: 14px">
    <p>open(close) the Dropdown list2 will close(open) the Dropdown List1.</p>
  </div>
  <div style="margin: 15px">
    <el-button @click="showClick">show</el-button>
  </div>
  <el-dropdown ref="dropdown1" trigger="contextmenu" style="margin-right: 30px">
    <span class="el-dropdown-link"> Dropdown List1 </span>
    <template #dropdown>
      <el-dropdown-menu>
        <el-dropdown-item>Action 1</el-dropdown-item>
        <el-dropdown-item>Action 2</el-dropdown-item>
        <el-dropdown-item>Action 3</el-dropdown-item>
        <el-dropdown-item disabled>Action 4</el-dropdown-item>
        <el-dropdown-item divided>Action 5</el-dropdown-item>
      </el-dropdown-menu>
    </template>
  </el-dropdown>

  <el-dropdown trigger="contextmenu" @visible-change="handleVisible2">
    <span class="el-dropdown-link"> Dropdown List2 </span>
    <template #dropdown>
      <el-dropdown-menu>
        <el-dropdown-item>Action 1</el-dropdown-item>
        <el-dropdown-item>Action 2</el-dropdown-item>
        <el-dropdown-item>Action 3</el-dropdown-item>
        <el-dropdown-item disabled>Action 4</el-dropdown-item>
        <el-dropdown-item divided>Action 5</el-dropdown-item>
      </el-dropdown-menu>
    </template>
  </el-dropdown>
</template>

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

import type { DropdownInstance } from 'element-plus'

const dropdown1 = ref<DropdownInstance>()
function handleVisible2(visible: any) {
  if (!dropdown1.value) return
  if (visible) {
    dropdown1.value.handleClose()
  } else {
    dropdown1.value.handleOpen()
  }
}
function showClick() {
  if (!dropdown1.value) return
  dropdown1.value.handleOpen()
}
</script>

<style scoped>
.example-showcase .el-dropdown-link {
  cursor: pointer;
  color: var(--el-color-primary);
  display: flex;
  align-items: center;
}
</style>
```

隐藏源代码

## 尺寸 [​](#尺寸)

Dropdown 组件提供除了默认值以外的三种尺寸，可以在不同场景下选择合适的尺寸。

使用 `size` 属性配置尺寸，可选的尺寸大小有: `large`, `default` 或 `small`

Large

Default

Small

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtZHJvcGRvd24gc2l6ZT1cImxhcmdlXCIgc3BsaXQtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCI+XG4gICAgTGFyZ2VcbiAgICA8dGVtcGxhdGUgI2Ryb3Bkb3duPlxuICAgICAgPGVsLWRyb3Bkb3duLW1lbnU+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPkFjdGlvbiAxPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gMjwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0+QWN0aW9uIDM8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPkFjdGlvbiA0PC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgPC9lbC1kcm9wZG93bi1tZW51PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtZHJvcGRvd24+XG5cbiAgPGVsLWRyb3Bkb3duIHNwbGl0LWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiPlxuICAgIERlZmF1bHRcbiAgICA8dGVtcGxhdGUgI2Ryb3Bkb3duPlxuICAgICAgPGVsLWRyb3Bkb3duLW1lbnU+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPkFjdGlvbiAxPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gMjwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0+QWN0aW9uIDM8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPkFjdGlvbiA0PC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgPC9lbC1kcm9wZG93bi1tZW51PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtZHJvcGRvd24+XG5cbiAgPGVsLWRyb3Bkb3duIHNpemU9XCJzbWFsbFwiIHNwbGl0LWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiPlxuICAgIFNtYWxsXG4gICAgPHRlbXBsYXRlICNkcm9wZG93bj5cbiAgICAgIDxlbC1kcm9wZG93bi1tZW51PlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gMTwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0+QWN0aW9uIDI8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtPkFjdGlvbiAzPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbT5BY3Rpb24gNDwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgIDwvZWwtZHJvcGRvd24tbWVudT5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLWRyb3Bkb3duPlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlIHNjb3BlZD5cbi5leGFtcGxlLXNob3djYXNlIC5lbC1kcm9wZG93biArIC5lbC1kcm9wZG93biB7XG4gIG1hcmdpbi1sZWZ0OiAxNXB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dropdown/sizes.vue)_

vue

```
<template>
  <el-dropdown size="large" split-button type="primary">
    Large
    <template #dropdown>
      <el-dropdown-menu>
        <el-dropdown-item>Action 1</el-dropdown-item>
        <el-dropdown-item>Action 2</el-dropdown-item>
        <el-dropdown-item>Action 3</el-dropdown-item>
        <el-dropdown-item>Action 4</el-dropdown-item>
      </el-dropdown-menu>
    </template>
  </el-dropdown>

  <el-dropdown split-button type="primary">
    Default
    <template #dropdown>
      <el-dropdown-menu>
        <el-dropdown-item>Action 1</el-dropdown-item>
        <el-dropdown-item>Action 2</el-dropdown-item>
        <el-dropdown-item>Action 3</el-dropdown-item>
        <el-dropdown-item>Action 4</el-dropdown-item>
      </el-dropdown-menu>
    </template>
  </el-dropdown>

  <el-dropdown size="small" split-button type="primary">
    Small
    <template #dropdown>
      <el-dropdown-menu>
        <el-dropdown-item>Action 1</el-dropdown-item>
        <el-dropdown-item>Action 2</el-dropdown-item>
        <el-dropdown-item>Action 3</el-dropdown-item>
        <el-dropdown-item>Action 4</el-dropdown-item>
      </el-dropdown-menu>
    </template>
  </el-dropdown>
</template>

<style scoped>
.example-showcase .el-dropdown + .el-dropdown {
  margin-left: 15px;
}
</style>
```

隐藏源代码

## 虚拟触发2.11.3 [​](#虚拟触发)

有时候我们想把 dropdown 的触发元素放在别的地方，而不需要写在一起，这时候就可以使用虚拟触发。

Right click

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtY2FyZFxuICAgIGNsYXNzPVwiY29udGVudFwiXG4gICAgYm9keS1jbGFzcz1cImNhcmQtYm9keVwiXG4gICAgQGNsaWNrPVwiaGFuZGxlQ2xpY2tcIlxuICAgIEBjb250ZXh0bWVudT1cImhhbmRsZUNvbnRleHRtZW51XCJcbiAgPlxuICAgIFJpZ2h0IGNsaWNrXG4gIDwvZWwtY2FyZD5cbiAgPGVsLWRyb3Bkb3duXG4gICAgcmVmPVwiZHJvcGRvd25SZWZcIlxuICAgIDp2aXJ0dWFsLXJlZj1cInRyaWdnZXJSZWZcIlxuICAgIDpzaG93LWFycm93PVwiZmFsc2VcIlxuICAgIDpwb3BwZXItb3B0aW9ucz1cIntcbiAgICAgIG1vZGlmaWVyczogW3sgbmFtZTogJ29mZnNldCcsIG9wdGlvbnM6IHsgb2Zmc2V0OiBbMCwgMF0gfSB9XSxcbiAgICB9XCJcbiAgICB2aXJ0dWFsLXRyaWdnZXJpbmdcbiAgICB0cmlnZ2VyPVwiY29udGV4dG1lbnVcIlxuICAgIHBsYWNlbWVudD1cImJvdHRvbS1zdGFydFwiXG4gID5cbiAgICA8dGVtcGxhdGUgI2Ryb3Bkb3duPlxuICAgICAgPGVsLWRyb3Bkb3duLW1lbnU+XG4gICAgICAgIDxlbC1kcm9wZG93bi1pdGVtIDppY29uPVwiUGx1c1wiPkFjdGlvbiAxPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSA6aWNvbj1cIkNpcmNsZVBsdXNGaWxsZWRcIj4gQWN0aW9uIDIgPC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSA6aWNvbj1cIkNpcmNsZVBsdXNcIj5BY3Rpb24gMzwvZWwtZHJvcGRvd24taXRlbT5cbiAgICAgICAgPGVsLWRyb3Bkb3duLWl0ZW0gOmljb249XCJDaGVja1wiPkFjdGlvbiA0PC9lbC1kcm9wZG93bi1pdGVtPlxuICAgICAgICA8ZWwtZHJvcGRvd24taXRlbSA6aWNvbj1cIkNpcmNsZUNoZWNrXCI+QWN0aW9uIDU8L2VsLWRyb3Bkb3duLWl0ZW0+XG4gICAgICA8L2VsLWRyb3Bkb3duLW1lbnU+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1kcm9wZG93bj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQge1xuICBDaGVjayxcbiAgQ2lyY2xlQ2hlY2ssXG4gIENpcmNsZVBsdXMsXG4gIENpcmNsZVBsdXNGaWxsZWQsXG4gIFBsdXMsXG59IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5pbXBvcnQgdHlwZSB7IERyb3Bkb3duSW5zdGFuY2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGRyb3Bkb3duUmVmID0gcmVmPERyb3Bkb3duSW5zdGFuY2U+KClcbmNvbnN0IHBvc2l0aW9uID0gcmVmKHtcbiAgdG9wOiAwLFxuICBsZWZ0OiAwLFxuICBib3R0b206IDAsXG4gIHJpZ2h0OiAwLFxufSBhcyBET01SZWN0KVxuXG5jb25zdCB0cmlnZ2VyUmVmID0gcmVmKHtcbiAgZ2V0Qm91bmRpbmdDbGllbnRSZWN0OiAoKSA9PiBwb3NpdGlvbi52YWx1ZSxcbn0pXG5cbmNvbnN0IGhhbmRsZUNsaWNrID0gKCkgPT4ge1xuICBkcm9wZG93blJlZi52YWx1ZT8uaGFuZGxlQ2xvc2UoKVxufVxuXG5jb25zdCBoYW5kbGVDb250ZXh0bWVudSA9IChldmVudDogTW91c2VFdmVudCkgPT4ge1xuICBjb25zdCB7IGNsaWVudFgsIGNsaWVudFkgfSA9IGV2ZW50XG4gIHBvc2l0aW9uLnZhbHVlID0gRE9NUmVjdC5mcm9tUmVjdCh7XG4gICAgeDogY2xpZW50WCxcbiAgICB5OiBjbGllbnRZLFxuICB9KVxuICBldmVudC5wcmV2ZW50RGVmYXVsdCgpXG4gIGRyb3Bkb3duUmVmLnZhbHVlPy5oYW5kbGVPcGVuKClcbn1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmNvbnRlbnQge1xuICBkaXNwbGF5OiBmbGV4O1xuICBqdXN0aWZ5LWNvbnRlbnQ6IGNlbnRlcjtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbiAgaGVpZ2h0OiAyMDBweDtcbn1cblxuLmNvbnRlbnQgOmRlZXAoLmNhcmQtYm9keSkge1xuICBmbGV4LWdyb3c6IDA7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dropdown/virtual-trigger.vue)_

vue

```
<template>
  <el-card
    class="content"
    body-class="card-body"
    @click="handleClick"
    @contextmenu="handleContextmenu"
  >
    Right click
  </el-card>
  <el-dropdown
    ref="dropdownRef"
    :virtual-ref="triggerRef"
    :show-arrow="false"
    :popper-options="{
      modifiers: [{ name: 'offset', options: { offset: [0, 0] } }],
    }"
    virtual-triggering
    trigger="contextmenu"
    placement="bottom-start"
  >
    <template #dropdown>
      <el-dropdown-menu>
        <el-dropdown-item :icon="Plus">Action 1</el-dropdown-item>
        <el-dropdown-item :icon="CirclePlusFilled"> Action 2 </el-dropdown-item>
        <el-dropdown-item :icon="CirclePlus">Action 3</el-dropdown-item>
        <el-dropdown-item :icon="Check">Action 4</el-dropdown-item>
        <el-dropdown-item :icon="CircleCheck">Action 5</el-dropdown-item>
      </el-dropdown-menu>
    </template>
  </el-dropdown>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import {
  Check,
  CircleCheck,
  CirclePlus,
  CirclePlusFilled,
  Plus,
} from '@element-plus/icons-vue'

import type { DropdownInstance } from 'element-plus'

const dropdownRef = ref<DropdownInstance>()
const position = ref({
  top: 0,
  left: 0,
  bottom: 0,
  right: 0,
} as DOMRect)

const triggerRef = ref({
  getBoundingClientRect: () => position.value,
})

const handleClick = () => {
  dropdownRef.value?.handleClose()
}

const handleContextmenu = (event: MouseEvent) => {
  const { clientX, clientY } = event
  position.value = DOMRect.fromRect({
    x: clientX,
    y: clientY,
  })
  event.preventDefault()
  dropdownRef.value?.handleOpen()
}
</script>

<style scoped>
.content {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 200px;
}

.content :deep(.card-body) {
  flex-grow: 0;
}
</style>
```

隐藏源代码

## Dropdown API [​](#dropdown-api)

### Dropdown Attributes [​](#dropdown-attributes)

| 属性名 | 说明 | 类型 | Default |
| --- | --- | --- | --- |
| type | 菜单按钮类型，同 `Button` 组件一样，仅在 `split-button` 为 true 的情况下有效。 | `enum` | '' |
| size | 菜单尺寸，在 split-button 为 true 的情况下也对触发按钮生效。 | `enum` | '' |
| button-props | 按钮组件的 props，参考 [按钮属性](https://element-plus.org/zh-CN/component/button.html#button-attributes) | `object` | — |
| max-height | 菜单最大高度 | `string` / `number` | '' |
| split-button | 下拉触发元素呈现为按钮组 | `boolean` | false |
| disabled | 是否禁用 | `boolean` | false |
| placement | 菜单弹出位置 | `enum` | bottom |
| effect | Tooltip 主题，内置了 `dark` / `light` 两种主题 | `enum` / `string` | light |
| trigger | 触发下拉的行为 | `enum` / `array` | hover |
| trigger-keys 2.9.1 | 指定键盘上哪些按键可以触发操作 | `array` | `['Enter', 'Space', 'ArrowDown', 'NumpadEnter']` |
| virtual-triggering 2.11.3 | 是否启用虚拟触发器 | `boolean` | — |
| virtual-ref 2.11.3 | 指示下拉框所依附的参考元素 | `HTMLElement` | — |
| hide-on-click | 是否在点击菜单项后隐藏菜单 | `boolean` | true |
| show-arrow 2.11.3 | tooltip 的内容是否有箭头 | `boolean` | true |
| show-timeout | 展开下拉菜单的延时，仅在 trigger 为 hover 时有效 | `number` | 150 |
| hide-timeout | 收起下拉菜单的延时（仅在 trigger 为 hover 时有效） | `number` | 150 |
| role | 下拉菜单的 ARIA 属性。 根据具体场景，您可能想要将此更改为“navigation” | `enum` | menu |
| tabindex | Dropdown 组件的 [tabindex](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) | `number` / `string` | 0 |
| popper-class | 自定义浮层类名 | `string` / `object` | '' |
| popper-style 2.11.5 | 自定义浮层类名 | `string` / `object` | — |
| popper-options | [popper.js](https://popper.js.org/docs/v2/) 参数 | `object` | `{modifiers: [{name: 'computeStyles',options: {gpuAcceleration: false}}]}` |
| teleported 2.2.20 | 是否将下拉列表插入至 body 元素 | `boolean` | true |
| append-to 2.13.0 | dropdown 的内容将挂载到哪一个元素上 | `CSSSelector` / `HTMLElement` | — |
| persistent 2.9.5 | 当下拉菜单处于非活动状态且 `persistent` 为 `false` 时，下拉菜单将被销毁 | `boolean` | true |

### Dropdown Slots [​](#dropdown-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 下拉菜单的内容。 注意：必须是有效的 html DOM 元素（例如 `<span>、<button>` 等）或 `el-component`，以附加监听触发器 | ::: |
| dropdown | 下拉列表，通常是 `<el-dropdown-menu>` 组件 | Dropdown-Menu |

### Dropdown Events [​](#dropdown-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| click | `split-button` 为 true 时，点击左侧按钮的回调 | `Function` |
| command | 当下拉项被点击时触发，参数是从下拉菜单中发送的命令 | `Function` |
| visible-change | 当下拉菜单出现/消失时触发器, 当它出现时, 参数将是 `true`, 否则将是 `false` | `Function` |

### Dropdown Exposes [​](#dropdown-exposes)

| 方法名 | 说明 | Type |
| --- | --- | --- |
| handleOpen | 打开下拉菜单 | `Function` |
| handleClose | 关闭下拉菜单 | `Function` |

## Dropdown-Menu API [​](#dropdown-menu-api)

### Dropdown-Menu Slots [​](#dropdown-menu-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 下拉菜单的内容 | Dropdown-Item |

## Dropdown-Item API [​](#dropdown-item-api)

### Dropdown-Item Attributes [​](#dropdown-item-attributes)

| 属性名 | 说明 | Type | 默认值 |
| --- | --- | --- | --- |
| command | 派发到`command`回调函数的指令参数 | `string` / `number` / `object` | — |
| disabled | 是否禁用 | `boolean` | false |
| divided | 是否显示分隔符 | `boolean` | false |
| icon | 自定义图标 | `string` / `Component` | — |

### Dropdown-Item Slots [​](#dropdown-item-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义Dropdown-Item内容 |
| icon 2.13.1 | 自定义图标，它将覆盖图标prop |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/dropdown) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/dropdown.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/dropdown.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/57086651?v=4&size=64)](https://github.com/Simon-He95)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/23609695?v=4&size=64)](https://github.com/shooterRao)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/21095710?v=4&size=64)](https://github.com/zouhangwithsweet)[![](https://avatars.githubusercontent.com/u/62818957?v=4&size=64)](https://github.com/ZacharyBear)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/134212703?v=4&size=64)](https://github.com/ydkdev)[![](https://avatars.githubusercontent.com/u/31850793?v=4&size=64)](https://github.com/ModyQyW)[![](https://avatars.githubusercontent.com/u/4075314?v=4&size=64)](https://github.com/Giwayume)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/66702442?v=4&size=64)](https://github.com/danny-hebert)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/44260795?v=4&size=64)](https://github.com/iwusong)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/49612241?v=4&size=64)](https://github.com/mawi1512)[![](https://avatars.githubusercontent.com/u/43257608?v=4&size=64)](https://github.com/Liao-js)[![](https://avatars.githubusercontent.com/u/18509404?v=4&size=64)](https://github.com/inottn)[![](https://avatars.githubusercontent.com/u/32129111?v=4&size=64)](https://github.com/Vgbire)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/36978416?v=4&size=64)](https://github.com/SimonaliaChen)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/216826433?v=4&size=64)](https://github.com/vsqaq)[![](https://avatars.githubusercontent.com/u/171831965?v=4&size=64)](https://github.com/allenxu09)[![](https://avatars.githubusercontent.com/u/188531008?v=4&size=64)](https://github.com/dengguangmiaoyyds)[![](https://avatars.githubusercontent.com/u/234136872?v=4&size=64)](https://github.com/z-kunf)[![](https://avatars.githubusercontent.com/u/15611493?v=4&size=64)](https://github.com/smallbonelu)[![](https://avatars.githubusercontent.com/u/145281501?v=4&size=64)](https://github.com/typed-sigterm)[![](https://avatars.githubusercontent.com/u/65441198?v=4&size=64)](https://github.com/tyj-321)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/60056876?v=4&size=64)](https://github.com/LinZhanMing)

[Breadcrumb 面包屑](https://element-plus.org/zh-CN/component/breadcrumb)

[Menu 菜单](https://element-plus.org/zh-CN/component/menu)




---
## [navigation/menu] Menu 菜单
> 官方文档: https://element-plus.org/zh-CN/component/menu.html

---

# Menu 菜单 [​](#menu-菜单)

更新日志待解决

60

为网站提供导航功能的菜单。

TIP

如果您想要覆盖el-menu的默认高度, 您可以使用下列CSS

css

```
.el-menu--horizontal {
  --el-menu-horizontal-height: 100px;
}
```

## 顶栏 [​](#顶栏)

顶部栏菜单可以在各种场景中使用。

导航菜单默认为垂直模式，通过将 mode 属性设置为 horizontal 来使导航菜单变更为水平模式。 另外，在菜单中通过 sub-menu 组件可以生成二级菜单。 Menu 还提供了`background-color`、`text-color`和`active-text-color`，分别用于设置菜单的背景色、菜单的文字颜色和当前激活菜单的文字颜色。

-   Processing Center
-   Workspace

-   Info
-   Orders

-   Processing Center
-   Workspace

-   Info
-   Orders

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtbWVudVxuICAgIDpkZWZhdWx0LWFjdGl2ZT1cImFjdGl2ZUluZGV4XCJcbiAgICBjbGFzcz1cImVsLW1lbnUtZGVtb1wiXG4gICAgbW9kZT1cImhvcml6b250YWxcIlxuICAgIEBzZWxlY3Q9XCJoYW5kbGVTZWxlY3RcIlxuICA+XG4gICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjFcIj5Qcm9jZXNzaW5nIENlbnRlcjwvZWwtbWVudS1pdGVtPlxuICAgIDxlbC1zdWItbWVudSBpbmRleD1cIjJcIj5cbiAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+V29ya3NwYWNlPC90ZW1wbGF0ZT5cbiAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIyLTFcIj5pdGVtIG9uZTwvZWwtbWVudS1pdGVtPlxuICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjItMlwiPml0ZW0gdHdvPC9lbC1tZW51LWl0ZW0+XG4gICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMi0zXCI+aXRlbSB0aHJlZTwvZWwtbWVudS1pdGVtPlxuICAgICAgPGVsLXN1Yi1tZW51IGluZGV4PVwiMi00XCI+XG4gICAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+aXRlbSBmb3VyPC90ZW1wbGF0ZT5cbiAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjItNC0xXCI+aXRlbSBvbmU8L2VsLW1lbnUtaXRlbT5cbiAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjItNC0yXCI+aXRlbSB0d288L2VsLW1lbnUtaXRlbT5cbiAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjItNC0zXCI+aXRlbSB0aHJlZTwvZWwtbWVudS1pdGVtPlxuICAgICAgPC9lbC1zdWItbWVudT5cbiAgICA8L2VsLXN1Yi1tZW51PlxuICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIzXCIgZGlzYWJsZWQ+SW5mbzwvZWwtbWVudS1pdGVtPlxuICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCI0XCI+T3JkZXJzPC9lbC1tZW51LWl0ZW0+XG4gIDwvZWwtbWVudT5cbiAgPGRpdiBjbGFzcz1cImgtNlwiIC8+XG4gIDxlbC1tZW51XG4gICAgOmRlZmF1bHQtYWN0aXZlPVwiYWN0aXZlSW5kZXgyXCJcbiAgICBjbGFzcz1cImVsLW1lbnUtZGVtb1wiXG4gICAgbW9kZT1cImhvcml6b250YWxcIlxuICAgIGJhY2tncm91bmQtY29sb3I9XCIjNTQ1YzY0XCJcbiAgICB0ZXh0LWNvbG9yPVwiI2ZmZlwiXG4gICAgYWN0aXZlLXRleHQtY29sb3I9XCIjZmZkMDRiXCJcbiAgICBAc2VsZWN0PVwiaGFuZGxlU2VsZWN0XCJcbiAgPlxuICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIxXCI+UHJvY2Vzc2luZyBDZW50ZXI8L2VsLW1lbnUtaXRlbT5cbiAgICA8ZWwtc3ViLW1lbnUgaW5kZXg9XCIyXCI+XG4gICAgICA8dGVtcGxhdGUgI3RpdGxlPldvcmtzcGFjZTwvdGVtcGxhdGU+XG4gICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMi0xXCI+aXRlbSBvbmU8L2VsLW1lbnUtaXRlbT5cbiAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIyLTJcIj5pdGVtIHR3bzwvZWwtbWVudS1pdGVtPlxuICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjItM1wiPml0ZW0gdGhyZWU8L2VsLW1lbnUtaXRlbT5cbiAgICAgIDxlbC1zdWItbWVudSBpbmRleD1cIjItNFwiPlxuICAgICAgICA8dGVtcGxhdGUgI3RpdGxlPml0ZW0gZm91cjwvdGVtcGxhdGU+XG4gICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIyLTQtMVwiPml0ZW0gb25lPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIyLTQtMlwiPml0ZW0gdHdvPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIyLTQtM1wiPml0ZW0gdGhyZWU8L2VsLW1lbnUtaXRlbT5cbiAgICAgIDwvZWwtc3ViLW1lbnU+XG4gICAgPC9lbC1zdWItbWVudT5cbiAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiM1wiIGRpc2FibGVkPkluZm88L2VsLW1lbnUtaXRlbT5cbiAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiNFwiPk9yZGVyczwvZWwtbWVudS1pdGVtPlxuICA8L2VsLW1lbnU+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBhY3RpdmVJbmRleCA9IHJlZignMScpXG5jb25zdCBhY3RpdmVJbmRleDIgPSByZWYoJzEnKVxuY29uc3QgaGFuZGxlU2VsZWN0ID0gKGtleTogc3RyaW5nLCBrZXlQYXRoOiBzdHJpbmdbXSkgPT4ge1xuICBjb25zb2xlLmxvZyhrZXksIGtleVBhdGgpXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/menu/basic.vue)_

vue

```
<template>
  <el-menu
    :default-active="activeIndex"
    class="el-menu-demo"
    mode="horizontal"
    @select="handleSelect"
  >
    <el-menu-item index="1">Processing Center</el-menu-item>
    <el-sub-menu index="2">
      <template #title>Workspace</template>
      <el-menu-item index="2-1">item one</el-menu-item>
      <el-menu-item index="2-2">item two</el-menu-item>
      <el-menu-item index="2-3">item three</el-menu-item>
      <el-sub-menu index="2-4">
        <template #title>item four</template>
        <el-menu-item index="2-4-1">item one</el-menu-item>
        <el-menu-item index="2-4-2">item two</el-menu-item>
        <el-menu-item index="2-4-3">item three</el-menu-item>
      </el-sub-menu>
    </el-sub-menu>
    <el-menu-item index="3" disabled>Info</el-menu-item>
    <el-menu-item index="4">Orders</el-menu-item>
  </el-menu>
  <div class="h-6" />
  <el-menu
    :default-active="activeIndex2"
    class="el-menu-demo"
    mode="horizontal"
    background-color="#545c64"
    text-color="#fff"
    active-text-color="#ffd04b"
    @select="handleSelect"
  >
    <el-menu-item index="1">Processing Center</el-menu-item>
    <el-sub-menu index="2">
      <template #title>Workspace</template>
      <el-menu-item index="2-1">item one</el-menu-item>
      <el-menu-item index="2-2">item two</el-menu-item>
      <el-menu-item index="2-3">item three</el-menu-item>
      <el-sub-menu index="2-4">
        <template #title>item four</template>
        <el-menu-item index="2-4-1">item one</el-menu-item>
        <el-menu-item index="2-4-2">item two</el-menu-item>
        <el-menu-item index="2-4-3">item three</el-menu-item>
      </el-sub-menu>
    </el-sub-menu>
    <el-menu-item index="3" disabled>Info</el-menu-item>
    <el-menu-item index="4">Orders</el-menu-item>
  </el-menu>
</template>

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

const activeIndex = ref('1')
const activeIndex2 = ref('1')
const handleSelect = (key: string, keyPath: string[]) => {
  console.log(key, keyPath)
}
</script>
```

隐藏源代码

## 左右 [​](#左右)

您可以将菜单项放置在左边或右边。

-   ![Element logo](https://element-plus.org/images/element-plus-logo.svg)
-   Processing Center
-   Workspace

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtbWVudVxuICAgIDpkZWZhdWx0LWFjdGl2ZT1cImFjdGl2ZUluZGV4XCJcbiAgICBjbGFzcz1cImVsLW1lbnUtZGVtb1wiXG4gICAgbW9kZT1cImhvcml6b250YWxcIlxuICAgIDplbGxpcHNpcz1cImZhbHNlXCJcbiAgICBAc2VsZWN0PVwiaGFuZGxlU2VsZWN0XCJcbiAgPlxuICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIwXCI+XG4gICAgICA8aW1nXG4gICAgICAgIHN0eWxlPVwid2lkdGg6IDEwMHB4XCJcbiAgICAgICAgc3JjPVwiL2ltYWdlcy9lbGVtZW50LXBsdXMtbG9nby5zdmdcIlxuICAgICAgICBhbHQ9XCJFbGVtZW50IGxvZ29cIlxuICAgICAgLz5cbiAgICA8L2VsLW1lbnUtaXRlbT5cbiAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMVwiPlByb2Nlc3NpbmcgQ2VudGVyPC9lbC1tZW51LWl0ZW0+XG4gICAgPGVsLXN1Yi1tZW51IGluZGV4PVwiMlwiPlxuICAgICAgPHRlbXBsYXRlICN0aXRsZT5Xb3Jrc3BhY2U8L3RlbXBsYXRlPlxuICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjItMVwiPml0ZW0gb25lPC9lbC1tZW51LWl0ZW0+XG4gICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMi0yXCI+aXRlbSB0d288L2VsLW1lbnUtaXRlbT5cbiAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIyLTNcIj5pdGVtIHRocmVlPC9lbC1tZW51LWl0ZW0+XG4gICAgICA8ZWwtc3ViLW1lbnUgaW5kZXg9XCIyLTRcIj5cbiAgICAgICAgPHRlbXBsYXRlICN0aXRsZT5pdGVtIGZvdXI8L3RlbXBsYXRlPlxuICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMi00LTFcIj5pdGVtIG9uZTwvZWwtbWVudS1pdGVtPlxuICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMi00LTJcIj5pdGVtIHR3bzwvZWwtbWVudS1pdGVtPlxuICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMi00LTNcIj5pdGVtIHRocmVlPC9lbC1tZW51LWl0ZW0+XG4gICAgICA8L2VsLXN1Yi1tZW51PlxuICAgIDwvZWwtc3ViLW1lbnU+XG4gIDwvZWwtbWVudT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGFjdGl2ZUluZGV4ID0gcmVmKCcxJylcbmNvbnN0IGhhbmRsZVNlbGVjdCA9IChrZXk6IHN0cmluZywga2V5UGF0aDogc3RyaW5nW10pID0+IHtcbiAgY29uc29sZS5sb2coa2V5LCBrZXlQYXRoKVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZWwtbWVudS0taG9yaXpvbnRhbCA+IC5lbC1tZW51LWl0ZW06bnRoLWNoaWxkKDEpIHtcbiAgbWFyZ2luLXJpZ2h0OiBhdXRvO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/menu/left-and-right.vue)_

vue

```
<template>
  <el-menu
    :default-active="activeIndex"
    class="el-menu-demo"
    mode="horizontal"
    :ellipsis="false"
    @select="handleSelect"
  >
    <el-menu-item index="0">
      <img
        style="width: 100px"
        src="/images/element-plus-logo.svg"
        alt="Element logo"
      />
    </el-menu-item>
    <el-menu-item index="1">Processing Center</el-menu-item>
    <el-sub-menu index="2">
      <template #title>Workspace</template>
      <el-menu-item index="2-1">item one</el-menu-item>
      <el-menu-item index="2-2">item two</el-menu-item>
      <el-menu-item index="2-3">item three</el-menu-item>
      <el-sub-menu index="2-4">
        <template #title>item four</template>
        <el-menu-item index="2-4-1">item one</el-menu-item>
        <el-menu-item index="2-4-2">item two</el-menu-item>
        <el-menu-item index="2-4-3">item three</el-menu-item>
      </el-sub-menu>
    </el-sub-menu>
  </el-menu>
</template>

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

const activeIndex = ref('1')
const handleSelect = (key: string, keyPath: string[]) => {
  console.log(key, keyPath)
}
</script>

<style scoped>
.el-menu--horizontal > .el-menu-item:nth-child(1) {
  margin-right: auto;
}
</style>
```

隐藏源代码

## 侧栏 [​](#侧栏)

垂直菜单，可内嵌子菜单。

通过 el-menu-item-group 组件可以实现菜单进行分组，分组名可以通过 title 属性直接设定，也可以通过具名 slot 来设定。

##### Default colors

-   Navigator One

    -   Group One

        -   item one
        -   item two
    -   Group Two

        -   item three
    -   item four

        -   item one
-   Navigator Two
-   Navigator Three
-   Navigator Four

##### Custom colors

-   Navigator One

    -   Group One

        -   item one
        -   item two
    -   Group Two

        -   item three
    -   item four

        -   item one
-   Navigator Two
-   Navigator Three
-   Navigator Four

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcm93IGNsYXNzPVwidGFjXCI+XG4gICAgPGVsLWNvbCA6c3Bhbj1cIjEyXCI+XG4gICAgICA8aDUgY2xhc3M9XCJtYi0yXCI+RGVmYXVsdCBjb2xvcnM8L2g1PlxuICAgICAgPGVsLW1lbnVcbiAgICAgICAgZGVmYXVsdC1hY3RpdmU9XCIyXCJcbiAgICAgICAgY2xhc3M9XCJlbC1tZW51LXZlcnRpY2FsLWRlbW9cIlxuICAgICAgICBAb3Blbj1cImhhbmRsZU9wZW5cIlxuICAgICAgICBAY2xvc2U9XCJoYW5kbGVDbG9zZVwiXG4gICAgICA+XG4gICAgICAgIDxlbC1zdWItbWVudSBpbmRleD1cIjFcIj5cbiAgICAgICAgICA8dGVtcGxhdGUgI3RpdGxlPlxuICAgICAgICAgICAgPGVsLWljb24+PGxvY2F0aW9uIC8+PC9lbC1pY29uPlxuICAgICAgICAgICAgPHNwYW4+TmF2aWdhdG9yIE9uZTwvc3Bhbj5cbiAgICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgICAgIDxlbC1tZW51LWl0ZW0tZ3JvdXAgdGl0bGU9XCJHcm91cCBPbmVcIj5cbiAgICAgICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIxLTFcIj5pdGVtIG9uZTwvZWwtbWVudS1pdGVtPlxuICAgICAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjEtMlwiPml0ZW0gdHdvPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgICAgPC9lbC1tZW51LWl0ZW0tZ3JvdXA+XG4gICAgICAgICAgPGVsLW1lbnUtaXRlbS1ncm91cCB0aXRsZT1cIkdyb3VwIFR3b1wiPlxuICAgICAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjEtM1wiPml0ZW0gdGhyZWU8L2VsLW1lbnUtaXRlbT5cbiAgICAgICAgICA8L2VsLW1lbnUtaXRlbS1ncm91cD5cbiAgICAgICAgICA8ZWwtc3ViLW1lbnUgaW5kZXg9XCIxLTRcIj5cbiAgICAgICAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+aXRlbSBmb3VyPC90ZW1wbGF0ZT5cbiAgICAgICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIxLTQtMVwiPml0ZW0gb25lPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgICAgPC9lbC1zdWItbWVudT5cbiAgICAgICAgPC9lbC1zdWItbWVudT5cbiAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjJcIj5cbiAgICAgICAgICA8ZWwtaWNvbj48aWNvbi1tZW51IC8+PC9lbC1pY29uPlxuICAgICAgICAgIDxzcGFuPk5hdmlnYXRvciBUd288L3NwYW4+XG4gICAgICAgIDwvZWwtbWVudS1pdGVtPlxuICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiM1wiIGRpc2FibGVkPlxuICAgICAgICAgIDxlbC1pY29uPjxkb2N1bWVudCAvPjwvZWwtaWNvbj5cbiAgICAgICAgICA8c3Bhbj5OYXZpZ2F0b3IgVGhyZWU8L3NwYW4+XG4gICAgICAgIDwvZWwtbWVudS1pdGVtPlxuICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiNFwiPlxuICAgICAgICAgIDxlbC1pY29uPjxzZXR0aW5nIC8+PC9lbC1pY29uPlxuICAgICAgICAgIDxzcGFuPk5hdmlnYXRvciBGb3VyPC9zcGFuPlxuICAgICAgICA8L2VsLW1lbnUtaXRlbT5cbiAgICAgIDwvZWwtbWVudT5cbiAgICA8L2VsLWNvbD5cbiAgICA8ZWwtY29sIDpzcGFuPVwiMTJcIj5cbiAgICAgIDxoNSBjbGFzcz1cIm1iLTJcIj5DdXN0b20gY29sb3JzPC9oNT5cbiAgICAgIDxlbC1tZW51XG4gICAgICAgIGFjdGl2ZS10ZXh0LWNvbG9yPVwiI2ZmZDA0YlwiXG4gICAgICAgIGJhY2tncm91bmQtY29sb3I9XCIjNTQ1YzY0XCJcbiAgICAgICAgY2xhc3M9XCJlbC1tZW51LXZlcnRpY2FsLWRlbW9cIlxuICAgICAgICBkZWZhdWx0LWFjdGl2ZT1cIjJcIlxuICAgICAgICB0ZXh0LWNvbG9yPVwiI2ZmZlwiXG4gICAgICAgIEBvcGVuPVwiaGFuZGxlT3BlblwiXG4gICAgICAgIEBjbG9zZT1cImhhbmRsZUNsb3NlXCJcbiAgICAgID5cbiAgICAgICAgPGVsLXN1Yi1tZW51IGluZGV4PVwiMVwiPlxuICAgICAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+XG4gICAgICAgICAgICA8ZWwtaWNvbj48bG9jYXRpb24gLz48L2VsLWljb24+XG4gICAgICAgICAgICA8c3Bhbj5OYXZpZ2F0b3IgT25lPC9zcGFuPlxuICAgICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgICAgPGVsLW1lbnUtaXRlbS1ncm91cCB0aXRsZT1cIkdyb3VwIE9uZVwiPlxuICAgICAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjEtMVwiPml0ZW0gb25lPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMS0yXCI+aXRlbSB0d288L2VsLW1lbnUtaXRlbT5cbiAgICAgICAgICA8L2VsLW1lbnUtaXRlbS1ncm91cD5cbiAgICAgICAgICA8ZWwtbWVudS1pdGVtLWdyb3VwIHRpdGxlPVwiR3JvdXAgVHdvXCI+XG4gICAgICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMS0zXCI+aXRlbSB0aHJlZTwvZWwtbWVudS1pdGVtPlxuICAgICAgICAgIDwvZWwtbWVudS1pdGVtLWdyb3VwPlxuICAgICAgICAgIDxlbC1zdWItbWVudSBpbmRleD1cIjEtNFwiPlxuICAgICAgICAgICAgPHRlbXBsYXRlICN0aXRsZT5pdGVtIGZvdXI8L3RlbXBsYXRlPlxuICAgICAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjEtNC0xXCI+aXRlbSBvbmU8L2VsLW1lbnUtaXRlbT5cbiAgICAgICAgICA8L2VsLXN1Yi1tZW51PlxuICAgICAgICA8L2VsLXN1Yi1tZW51PlxuICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMlwiPlxuICAgICAgICAgIDxlbC1pY29uPjxpY29uLW1lbnUgLz48L2VsLWljb24+XG4gICAgICAgICAgPHNwYW4+TmF2aWdhdG9yIFR3bzwvc3Bhbj5cbiAgICAgICAgPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIzXCIgZGlzYWJsZWQ+XG4gICAgICAgICAgPGVsLWljb24+PGRvY3VtZW50IC8+PC9lbC1pY29uPlxuICAgICAgICAgIDxzcGFuPk5hdmlnYXRvciBUaHJlZTwvc3Bhbj5cbiAgICAgICAgPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCI0XCI+XG4gICAgICAgICAgPGVsLWljb24+PHNldHRpbmcgLz48L2VsLWljb24+XG4gICAgICAgICAgPHNwYW4+TmF2aWdhdG9yIEZvdXI8L3NwYW4+XG4gICAgICAgIDwvZWwtbWVudS1pdGVtPlxuICAgICAgPC9lbC1tZW51PlxuICAgIDwvZWwtY29sPlxuICA8L2VsLXJvdz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQge1xuICBEb2N1bWVudCxcbiAgTWVudSBhcyBJY29uTWVudSxcbiAgTG9jYXRpb24sXG4gIFNldHRpbmcsXG59IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5jb25zdCBoYW5kbGVPcGVuID0gKGtleTogc3RyaW5nLCBrZXlQYXRoOiBzdHJpbmdbXSkgPT4ge1xuICBjb25zb2xlLmxvZyhrZXksIGtleVBhdGgpXG59XG5jb25zdCBoYW5kbGVDbG9zZSA9IChrZXk6IHN0cmluZywga2V5UGF0aDogc3RyaW5nW10pID0+IHtcbiAgY29uc29sZS5sb2coa2V5LCBrZXlQYXRoKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/menu/vertical.vue)_

vue

```
<template>
  <el-row class="tac">
    <el-col :span="12">
      <h5 class="mb-2">Default colors</h5>
      <el-menu
        default-active="2"
        class="el-menu-vertical-demo"
        @open="handleOpen"
        @close="handleClose"
      >
        <el-sub-menu index="1">
          <template #title>
            <el-icon><location /></el-icon>
            <span>Navigator One</span>
          </template>
          <el-menu-item-group title="Group One">
            <el-menu-item index="1-1">item one</el-menu-item>
            <el-menu-item index="1-2">item two</el-menu-item>
          </el-menu-item-group>
          <el-menu-item-group title="Group Two">
            <el-menu-item index="1-3">item three</el-menu-item>
          </el-menu-item-group>
          <el-sub-menu index="1-4">
            <template #title>item four</template>
            <el-menu-item index="1-4-1">item one</el-menu-item>
          </el-sub-menu>
        </el-sub-menu>
        <el-menu-item index="2">
          <el-icon><icon-menu /></el-icon>
          <span>Navigator Two</span>
        </el-menu-item>
        <el-menu-item index="3" disabled>
          <el-icon><document /></el-icon>
          <span>Navigator Three</span>
        </el-menu-item>
        <el-menu-item index="4">
          <el-icon><setting /></el-icon>
          <span>Navigator Four</span>
        </el-menu-item>
      </el-menu>
    </el-col>
    <el-col :span="12">
      <h5 class="mb-2">Custom colors</h5>
      <el-menu
        active-text-color="#ffd04b"
        background-color="#545c64"
        class="el-menu-vertical-demo"
        default-active="2"
        text-color="#fff"
        @open="handleOpen"
        @close="handleClose"
      >
        <el-sub-menu index="1">
          <template #title>
            <el-icon><location /></el-icon>
            <span>Navigator One</span>
          </template>
          <el-menu-item-group title="Group One">
            <el-menu-item index="1-1">item one</el-menu-item>
            <el-menu-item index="1-2">item two</el-menu-item>
          </el-menu-item-group>
          <el-menu-item-group title="Group Two">
            <el-menu-item index="1-3">item three</el-menu-item>
          </el-menu-item-group>
          <el-sub-menu index="1-4">
            <template #title>item four</template>
            <el-menu-item index="1-4-1">item one</el-menu-item>
          </el-sub-menu>
        </el-sub-menu>
        <el-menu-item index="2">
          <el-icon><icon-menu /></el-icon>
          <span>Navigator Two</span>
        </el-menu-item>
        <el-menu-item index="3" disabled>
          <el-icon><document /></el-icon>
          <span>Navigator Three</span>
        </el-menu-item>
        <el-menu-item index="4">
          <el-icon><setting /></el-icon>
          <span>Navigator Four</span>
        </el-menu-item>
      </el-menu>
    </el-col>
  </el-row>
</template>

<script lang="ts" setup>
import {
  Document,
  Menu as IconMenu,
  Location,
  Setting,
} from '@element-plus/icons-vue'

const handleOpen = (key: string, keyPath: string[]) => {
  console.log(key, keyPath)
}
const handleClose = (key: string, keyPath: string[]) => {
  console.log(key, keyPath)
}
</script>
```

隐藏源代码

## Collapse 折叠面板 [​](#collapse-折叠面板)

垂直导航菜单可以被折叠

expandcollapse

-   Navigator One

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cImlzQ29sbGFwc2VcIiBzdHlsZT1cIm1hcmdpbi1ib3R0b206IDIwcHhcIj5cbiAgICA8ZWwtcmFkaW8tYnV0dG9uIDp2YWx1ZT1cImZhbHNlXCI+ZXhwYW5kPC9lbC1yYWRpby1idXR0b24+XG4gICAgPGVsLXJhZGlvLWJ1dHRvbiA6dmFsdWU9XCJ0cnVlXCI+Y29sbGFwc2U8L2VsLXJhZGlvLWJ1dHRvbj5cbiAgPC9lbC1yYWRpby1ncm91cD5cbiAgPGVsLW1lbnVcbiAgICBkZWZhdWx0LWFjdGl2ZT1cIjJcIlxuICAgIGNsYXNzPVwiZWwtbWVudS12ZXJ0aWNhbC1kZW1vXCJcbiAgICA6Y29sbGFwc2U9XCJpc0NvbGxhcHNlXCJcbiAgICBAb3Blbj1cImhhbmRsZU9wZW5cIlxuICAgIEBjbG9zZT1cImhhbmRsZUNsb3NlXCJcbiAgPlxuICAgIDxlbC1zdWItbWVudSBpbmRleD1cIjFcIj5cbiAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+XG4gICAgICAgIDxlbC1pY29uPjxsb2NhdGlvbiAvPjwvZWwtaWNvbj5cbiAgICAgICAgPHNwYW4+TmF2aWdhdG9yIE9uZTwvc3Bhbj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8ZWwtbWVudS1pdGVtLWdyb3VwPlxuICAgICAgICA8dGVtcGxhdGUgI3RpdGxlPjxzcGFuPkdyb3VwIE9uZTwvc3Bhbj48L3RlbXBsYXRlPlxuICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMS0xXCI+aXRlbSBvbmU8L2VsLW1lbnUtaXRlbT5cbiAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjEtMlwiPml0ZW0gdHdvPC9lbC1tZW51LWl0ZW0+XG4gICAgICA8L2VsLW1lbnUtaXRlbS1ncm91cD5cbiAgICAgIDxlbC1tZW51LWl0ZW0tZ3JvdXAgdGl0bGU9XCJHcm91cCBUd29cIj5cbiAgICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjEtM1wiPml0ZW0gdGhyZWU8L2VsLW1lbnUtaXRlbT5cbiAgICAgIDwvZWwtbWVudS1pdGVtLWdyb3VwPlxuICAgICAgPGVsLXN1Yi1tZW51IGluZGV4PVwiMS00XCI+XG4gICAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+PHNwYW4+aXRlbSBmb3VyPC9zcGFuPjwvdGVtcGxhdGU+XG4gICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIxLTQtMVwiPml0ZW0gb25lPC9lbC1tZW51LWl0ZW0+XG4gICAgICA8L2VsLXN1Yi1tZW51PlxuICAgIDwvZWwtc3ViLW1lbnU+XG4gICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjJcIj5cbiAgICAgIDxlbC1pY29uPjxpY29uLW1lbnUgLz48L2VsLWljb24+XG4gICAgICA8dGVtcGxhdGUgI3RpdGxlPk5hdmlnYXRvciBUd288L3RlbXBsYXRlPlxuICAgIDwvZWwtbWVudS1pdGVtPlxuICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIzXCIgZGlzYWJsZWQ+XG4gICAgICA8ZWwtaWNvbj48ZG9jdW1lbnQgLz48L2VsLWljb24+XG4gICAgICA8dGVtcGxhdGUgI3RpdGxlPk5hdmlnYXRvciBUaHJlZTwvdGVtcGxhdGU+XG4gICAgPC9lbC1tZW51LWl0ZW0+XG4gICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjRcIj5cbiAgICAgIDxlbC1pY29uPjxzZXR0aW5nIC8+PC9lbC1pY29uPlxuICAgICAgPHRlbXBsYXRlICN0aXRsZT5OYXZpZ2F0b3IgRm91cjwvdGVtcGxhdGU+XG4gICAgPC9lbC1tZW51LWl0ZW0+XG4gIDwvZWwtbWVudT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQge1xuICBEb2N1bWVudCxcbiAgTWVudSBhcyBJY29uTWVudSxcbiAgTG9jYXRpb24sXG4gIFNldHRpbmcsXG59IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuXG5jb25zdCBpc0NvbGxhcHNlID0gcmVmKHRydWUpXG5jb25zdCBoYW5kbGVPcGVuID0gKGtleTogc3RyaW5nLCBrZXlQYXRoOiBzdHJpbmdbXSkgPT4ge1xuICBjb25zb2xlLmxvZyhrZXksIGtleVBhdGgpXG59XG5jb25zdCBoYW5kbGVDbG9zZSA9IChrZXk6IHN0cmluZywga2V5UGF0aDogc3RyaW5nW10pID0+IHtcbiAgY29uc29sZS5sb2coa2V5LCBrZXlQYXRoKVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5lbC1tZW51LXZlcnRpY2FsLWRlbW86bm90KC5lbC1tZW51LS1jb2xsYXBzZSkge1xuICB3aWR0aDogMjAwcHg7XG4gIG1pbi1oZWlnaHQ6IDQwMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/menu/collapse.vue)_

vue

```
<template>
  <el-radio-group v-model="isCollapse" style="margin-bottom: 20px">
    <el-radio-button :value="false">expand</el-radio-button>
    <el-radio-button :value="true">collapse</el-radio-button>
  </el-radio-group>
  <el-menu
    default-active="2"
    class="el-menu-vertical-demo"
    :collapse="isCollapse"
    @open="handleOpen"
    @close="handleClose"
  >
    <el-sub-menu index="1">
      <template #title>
        <el-icon><location /></el-icon>
        <span>Navigator One</span>
      </template>
      <el-menu-item-group>
        <template #title><span>Group One</span></template>
        <el-menu-item index="1-1">item one</el-menu-item>
        <el-menu-item index="1-2">item two</el-menu-item>
      </el-menu-item-group>
      <el-menu-item-group title="Group Two">
        <el-menu-item index="1-3">item three</el-menu-item>
      </el-menu-item-group>
      <el-sub-menu index="1-4">
        <template #title><span>item four</span></template>
        <el-menu-item index="1-4-1">item one</el-menu-item>
      </el-sub-menu>
    </el-sub-menu>
    <el-menu-item index="2">
      <el-icon><icon-menu /></el-icon>
      <template #title>Navigator Two</template>
    </el-menu-item>
    <el-menu-item index="3" disabled>
      <el-icon><document /></el-icon>
      <template #title>Navigator Three</template>
    </el-menu-item>
    <el-menu-item index="4">
      <el-icon><setting /></el-icon>
      <template #title>Navigator Four</template>
    </el-menu-item>
  </el-menu>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import {
  Document,
  Menu as IconMenu,
  Location,
  Setting,
} from '@element-plus/icons-vue'

const isCollapse = ref(true)
const handleOpen = (key: string, keyPath: string[]) => {
  console.log(key, keyPath)
}
const handleClose = (key: string, keyPath: string[]) => {
  console.log(key, keyPath)
}
</script>

<style>
.el-menu-vertical-demo:not(.el-menu--collapse) {
  width: 200px;
  min-height: 400px;
}
</style>
```

隐藏源代码

## 弹出层偏移量 2.4.4 [​](#弹出层偏移量)

当提供了 popperOffset 配置，会覆盖 Menu 的 `popper-offset`.

-   Processing Center
-   Workspace

-   Override Popper Offset

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtbWVudVxuICAgIGVsbGlwc2lzXG4gICAgY2xhc3M9XCJlbC1tZW51LXBvcHBlci1kZW1vXCJcbiAgICBtb2RlPVwiaG9yaXpvbnRhbFwiXG4gICAgOnBvcHBlci1vZmZzZXQ9XCIxNlwiXG4gICAgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCJcbiAgPlxuICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIxXCI+UHJvY2Vzc2luZyBDZW50ZXI8L2VsLW1lbnUtaXRlbT5cbiAgICA8ZWwtc3ViLW1lbnUgaW5kZXg9XCIyXCI+XG4gICAgICA8dGVtcGxhdGUgI3RpdGxlPldvcmtzcGFjZTwvdGVtcGxhdGU+XG4gICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMi0xXCI+aXRlbSBvbmU8L2VsLW1lbnUtaXRlbT5cbiAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIyLTJcIj5pdGVtIHR3bzwvZWwtbWVudS1pdGVtPlxuICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjItM1wiPml0ZW0gdGhyZWU8L2VsLW1lbnUtaXRlbT5cbiAgICAgIDxlbC1zdWItbWVudSBpbmRleD1cIjItNFwiPlxuICAgICAgICA8dGVtcGxhdGUgI3RpdGxlPml0ZW0gZm91cjwvdGVtcGxhdGU+XG4gICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIyLTQtMVwiPml0ZW0gb25lPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIyLTQtMlwiPml0ZW0gdHdvPC9lbC1tZW51LWl0ZW0+XG4gICAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIyLTQtM1wiPml0ZW0gdGhyZWU8L2VsLW1lbnUtaXRlbT5cbiAgICAgIDwvZWwtc3ViLW1lbnU+XG4gICAgPC9lbC1zdWItbWVudT5cbiAgICA8ZWwtc3ViLW1lbnUgaW5kZXg9XCIzXCIgOnBvcHBlci1vZmZzZXQ9XCI4XCI+XG4gICAgICA8dGVtcGxhdGUgI3RpdGxlPk92ZXJyaWRlIFBvcHBlciBPZmZzZXQ8L3RlbXBsYXRlPlxuICAgICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjMtMVwiPml0ZW0gb25lPC9lbC1tZW51LWl0ZW0+XG4gICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMy0yXCI+aXRlbSB0d288L2VsLW1lbnUtaXRlbT5cbiAgICAgIDxlbC1tZW51LWl0ZW0gaW5kZXg9XCIzLTNcIj5pdGVtIHRocmVlPC9lbC1tZW51LWl0ZW0+XG4gICAgICA8ZWwtc3ViLW1lbnUgaW5kZXg9XCIzLTRcIiA6cG9wcGVyLW9mZnNldD1cIjIwXCI+XG4gICAgICAgIDx0ZW1wbGF0ZSAjdGl0bGU+b3ZlcnJpZGUgY2hpbGQ8L3RlbXBsYXRlPlxuICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMy00LTFcIj5pdGVtIG9uZTwvZWwtbWVudS1pdGVtPlxuICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMy00LTJcIj5pdGVtIHR3bzwvZWwtbWVudS1pdGVtPlxuICAgICAgICA8ZWwtbWVudS1pdGVtIGluZGV4PVwiMy00LTNcIj5pdGVtIHRocmVlPC9lbC1tZW51LWl0ZW0+XG4gICAgICA8L2VsLXN1Yi1tZW51PlxuICAgIDwvZWwtc3ViLW1lbnU+XG4gICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjRcIiBkaXNhYmxlZD5JbmZvPC9lbC1tZW51LWl0ZW0+XG4gICAgPGVsLW1lbnUtaXRlbSBpbmRleD1cIjVcIj5PcmRlcnM8L2VsLW1lbnUtaXRlbT5cbiAgPC9lbC1tZW51PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/menu/popper-offset.vue)_

vue

```
<template>
  <el-menu
    ellipsis
    class="el-menu-popper-demo"
    mode="horizontal"
    :popper-offset="16"
    style="max-width: 600px"
  >
    <el-menu-item index="1">Processing Center</el-menu-item>
    <el-sub-menu index="2">
      <template #title>Workspace</template>
      <el-menu-item index="2-1">item one</el-menu-item>
      <el-menu-item index="2-2">item two</el-menu-item>
      <el-menu-item index="2-3">item three</el-menu-item>
      <el-sub-menu index="2-4">
        <template #title>item four</template>
        <el-menu-item index="2-4-1">item one</el-menu-item>
        <el-menu-item index="2-4-2">item two</el-menu-item>
        <el-menu-item index="2-4-3">item three</el-menu-item>
      </el-sub-menu>
    </el-sub-menu>
    <el-sub-menu index="3" :popper-offset="8">
      <template #title>Override Popper Offset</template>
      <el-menu-item index="3-1">item one</el-menu-item>
      <el-menu-item index="3-2">item two</el-menu-item>
      <el-menu-item index="3-3">item three</el-menu-item>
      <el-sub-menu index="3-4" :popper-offset="20">
        <template #title>override child</template>
        <el-menu-item index="3-4-1">item one</el-menu-item>
        <el-menu-item index="3-4-2">item two</el-menu-item>
        <el-menu-item index="3-4-3">item three</el-menu-item>
      </el-sub-menu>
    </el-sub-menu>
    <el-menu-item index="4" disabled>Info</el-menu-item>
    <el-menu-item index="5">Orders</el-menu-item>
  </el-menu>
</template>

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

隐藏源代码

## 菜单 API [​](#菜单-api)

### Menu Attributes [​](#menu-attributes)

| 属性名 | 说明 | 类型 | Default |
| --- | --- | --- | --- |
| mode | 菜单展示模式 | `enum` | vertical |
| collapse | 是否水平折叠收起菜单（仅在 mode 为 vertical 时可用） | `boolean` | false |
| ellipsis | 是否省略多余的子项（仅在横向模式生效） | `boolean` | true |
| ellipsis-icon 2.4.4 | 自定义省略图标 (仅在水平模式下可用) | `string` / `Component` | — |
| popper-offset 2.4.4 | 弹出层的偏移量(对所有子菜单有效) | `number` | 6 |
| default-active | 页面加载时默认激活菜单的 index | `string` | '' |
| default-openeds | 默认打开的 sub-menu 的 index 的数组 | `array` | \[\] |
| unique-opened | 是否只保持一个子菜单的展开 | `boolean` | false |
| menu-trigger | 子菜单打开的触发方式，只在 `mode` 为 horizontal 时有效。 | `enum` | hover |
| router | 是否启用 `vue-router` 模式。 启用该模式会在激活导航时以 index 作为 path 进行路由跳转 使用 `default-active` 来设置加载时的激活项。 | `boolean` | false |
| collapse-transition | 是否开启折叠动画 | `boolean` | true |
| popper-effect 2.2.26 | Tooltip 主题，内置了 `dark` / `light` 两种主题，当菜单折叠时生效。 | `enum` / `string` | dark |
| close-on-click-outside 2.4.4 | 可选，单击外部时是否折叠菜单 | `boolean` | false |
| popper-class 2.5.0 | 用于所有弹出菜单和标题提示的自定义类名 | `string` | — |
| popper-style 2.11.5 | 用于所有弹出菜单和标题提示的自定义样式 | `string` / `object` | — |
| show-timeout 2.5.0 | 菜单出现前的延迟 | `number` | 300 |
| hide-timeout 2.5.0 | 菜单消失前的延迟 | `number` | 300 |
| background-color deprecated | 菜单的背景颜色 (十六进制格式) (推荐在样式类中使用 `--el-menu-bg-color`) | `string` | #ffffff |
| text-color deprecated | 菜单的文字颜色 (十六进制格式) (推荐在样式类中使用 `--el-menu-text-color`) | `string` | #303133 |
| active-text-color deprecated | 活动菜单项的文本颜色（十六进制格式）（推荐使用 css var `--el-menu-active-color`） | `string` | #409eff |
| persistent 2.9.5 | 当菜单处于非活动状态且 `persistent` 为 `false` 时，下拉菜单将被销毁 | `boolean` | true |

### Menu Events [​](#menu-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| select | 菜单激活回调 | `Function` |
| open | sub-menu 展开的回调 | `Function` |
| close | sub-menu 收起的回调 | `Function` |

### Menu Slots [​](#menu-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | SubMenu / Menu-Item / Menu-Item-Group |

### Menu Exposes [​](#menu-exposes)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| open | 打开一个特定的子菜单，参数是要打开的子菜单的索引 | `Function` |
| close | 关闭一个特定的子菜单，参数是要关闭子菜单的索引 | `Function` |
| handleResize | 手动触发菜单宽度重新计算 | `Function` |
| updateActiveIndex 2.9.8 | 通过索引激活指定菜单 | `Function` |

## SubMenu API [​](#submenu-api)

### SubMenu Attributes [​](#submenu-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| index required | 唯一标志 | `string` | — |
| popper-class | 为 popper 添加类名 | `string` | — |
| popper-style 2.11.5 | 为 popper 添加自定义样式 | `string` / `object` | — |
| show-timeout | 子菜单出现之前的延迟，(继承 menu 的 `show-timeout` 配置) | `number` | — |
| hide-timeout | 子菜单消失之前的延迟，(继承 menu 的 `hide-timeout` 配置) | `number` | — |
| disabled | 是否禁用 | `boolean` | false |
| teleported | 是否将弹出菜单挂载到 body 上，第一级SubMenu默认值为 true，其他SubMenus 的值为 false | `boolean` | undefined |
| popper-offset | 弹出窗口的偏移量 (覆盖 `popper`的菜单) | `number` | — |
| expand-close-icon | 父菜单展开且子菜单关闭时的图标， `expand-close-icon` 和 `expand-open-icon` 需要一起配置才能生效 | `string` / `Component` | — |
| expand-open-icon | 父菜单展开且子菜单打开时的图标， `expand-open-icon` 和 `expand-close-icon` 需要一起配置才能生效 | `string` / `Component` | — |
| collapse-close-icon | 父菜单收起且子菜单关闭时的图标， `collapse-close-icon` 和 `collapse-open-icon` 需要一起配置才能生效 | `string` / `Component` | — |
| collapse-open-icon | 父菜单收起且子菜单打开时的图标， `collapse-open-icon` 和 `collapse-close-icon` 需要一起配置才能生效 | `string` / `Component` | — |

### SubMenu Slots [​](#submenu-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 自定义默认内容 | SubMenu / Menu-Item / Menu-Item-Group |
| title | 自定义标题内容 | — |

## Menu-Item API [​](#menu-item-api)

### Menu-Item Attributes [​](#menu-item-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| index required | 唯一标志 | `string` | — |
| route | Vue Route 路由位置参数 | `string` / `object` | — |
| disabled | 是否禁用 | `boolean` | false |

### Menu-Item Events [​](#menu-item-events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| click | 点击菜单项时回调函数, 参数为菜单项实例 | `Function` |

### Menu-Item Slots [​](#menu-item-slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 自定义默认内容 |
| title | 自定义标题内容 |

## Menu-Item-Group API [​](#menu-item-group-api)

### Menu-Item-Group Attributes [​](#menu-item-group-attributes)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| title | 组标题 | `string` | — |

### Menu-Item-Group Slots [​](#menu-item-group-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 默认插槽内容 | Menu-Item |
| title | 自定义组标题内容 | — |

## 类型声明 [​](#类型声明)

显示类型声明

ts

```
/**
 * @param index index of activated menu
 * @param indexPath index path of activated menu
 * @param item the selected menu item
 * @param routerResult result returned by `vue-router` if `router` is enabled
 */
type MenuSelectEvent = (
  index: string,
  indexPath: string[],
  item: MenuItemClicked,
  routerResult?: Promise<void | NavigationFailure>
) => void

/**
 * @param index index of expanded sub-menu
 * @param indexPath index path of expanded sub-menu
 */
type MenuOpenEvent = (index: string, indexPath: string[]) => void

/**
 * @param index index of collapsed sub-menu
 * @param indexPath index path of collapsed sub-menu
 */
type MenuCloseEvent = (index: string, indexPath: string[]) => void

interface MenuItemRegistered {
  index: string
  indexPath: string[]
  active: boolean
}

interface MenuItemClicked {
  index: string
  indexPath: string[]
  route?: RouteLocationRaw
}
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/menu) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/menu.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/menu.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/17698194?v=4&size=64)](https://github.com/nieyuyao)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/41532842?v=4&size=64)](https://github.com/feiyuOL)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/59312002?v=4&size=64)](https://github.com/meet-student)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/43257608?v=4&size=64)](https://github.com/Liao-js)[![](https://avatars.githubusercontent.com/u/30396440?v=4&size=64)](https://github.com/wen-lun)[![](https://avatars.githubusercontent.com/u/19513904?v=4&size=64)](https://github.com/ShirleyYoung19)[![](https://avatars.githubusercontent.com/u/148513444?v=4&size=64)](https://github.com/ikkkp)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/102006695?v=4&size=64)](https://github.com/cuongle-hdwebsoft)[![](https://avatars.githubusercontent.com/u/26295849?v=4&size=64)](https://github.com/CeceWall)[![](https://avatars.githubusercontent.com/u/36811055?v=4&size=64)](https://github.com/iDestin)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/19643456?v=4&size=64)](https://github.com/ParkerFiend)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)[![](https://avatars.githubusercontent.com/u/145281501?v=4&size=64)](https://github.com/typed-sigterm)[![](https://avatars.githubusercontent.com/u/63504321?v=4&size=64)](https://github.com/Lucky-Ya-Q)[![](https://avatars.githubusercontent.com/u/87300515?v=4&size=64)](https://github.com/WindBearr)[![](https://avatars.githubusercontent.com/u/49601167?v=4&size=64)](https://github.com/jianjunyuu)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/26268346?v=4&size=64)](https://github.com/Jimmyzm)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/15604293?v=4&size=64)](https://github.com/Liiked)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/9036838?v=4&size=64)](https://github.com/jiankian)[![](https://avatars.githubusercontent.com/u/45283723?v=4&size=64)](https://github.com/oliver139)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/58544605?v=4&size=64)](https://github.com/dan-sotnik)[![](https://avatars.githubusercontent.com/u/128784464?v=4&size=64)](https://github.com/super622)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/16005946?v=4&size=64)](https://github.com/jpenna)[![](https://avatars.githubusercontent.com/u/63645337?v=4&size=64)](https://github.com/baboon-king)

[Dropdown 下拉菜单](https://element-plus.org/zh-CN/component/dropdown)

[Page Header 页头](https://element-plus.org/zh-CN/component/page-header)




---
## [navigation/page-header] Page Header 页头
> 官方文档: https://element-plus.org/zh-CN/component/page-header.html

---

# Page Header 页头 [​](#page-header-页头)

更新日志待解决

0

如果页面的路径比较简单，推荐使用页头组件而非面包屑组件。

## 完整示例 [​](#完整示例)

homepage /[route 1](https://element-plus.org/zh-CN/component/page-header.html)/route 2/

Back

![](https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png) Title Sub title Default

PrintEdit

<table class="el-descriptions__table"><tbody><tr><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Username</span><span class="el-descriptions__content"> kooriookami</span></td><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Telephone</span><span class="el-descriptions__content"> 18100000000</span></td><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Place</span><span class="el-descriptions__content">Suzhou</span></td></tr><tr><td style="width:;min-width:;" class="el-descriptions__cell"><span style="" class="el-descriptions__label">Remarks</span><span class="el-descriptions__content"><span class="el-tag el-tag--primary el-tag--small el-tag--light" style=""><span class="el-tag__content">School</span></span></span></td><td style="width:;min-width:;" class="el-descriptions__cell" colspan="2"><span style="" class="el-descriptions__label">Address</span><span class="el-descriptions__content"> No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province</span></td></tr></tbody></table>

Element Plus team uses **weekly** release strategy under normal circumstance, but critical bug fixes would require hotfix so the actual release number **could be** more than 1 per week.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGFyaWEtbGFiZWw9XCJBIGNvbXBsZXRlIGV4YW1wbGUgb2YgcGFnZSBoZWFkZXJcIj5cbiAgICA8ZWwtcGFnZS1oZWFkZXIgQGJhY2s9XCJvbkJhY2tcIj5cbiAgICAgIDx0ZW1wbGF0ZSAjYnJlYWRjcnVtYj5cbiAgICAgICAgPGVsLWJyZWFkY3J1bWIgc2VwYXJhdG9yPVwiL1wiPlxuICAgICAgICAgIDxlbC1icmVhZGNydW1iLWl0ZW0gOnRvPVwieyBwYXRoOiAnLi9wYWdlLWhlYWRlci5odG1sJyB9XCI+XG4gICAgICAgICAgICBob21lcGFnZVxuICAgICAgICAgIDwvZWwtYnJlYWRjcnVtYi1pdGVtPlxuICAgICAgICAgIDxlbC1icmVhZGNydW1iLWl0ZW0+XG4gICAgICAgICAgICA8YSBocmVmPVwiLi9wYWdlLWhlYWRlci5odG1sXCI+cm91dGUgMTwvYT5cbiAgICAgICAgICA8L2VsLWJyZWFkY3J1bWItaXRlbT5cbiAgICAgICAgICA8ZWwtYnJlYWRjcnVtYi1pdGVtPnJvdXRlIDI8L2VsLWJyZWFkY3J1bWItaXRlbT5cbiAgICAgICAgPC9lbC1icmVhZGNydW1iPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDx0ZW1wbGF0ZSAjY29udGVudD5cbiAgICAgICAgPGRpdiBjbGFzcz1cImZsZXggaXRlbXMtY2VudGVyXCI+XG4gICAgICAgICAgPGVsLWF2YXRhclxuICAgICAgICAgICAgY2xhc3M9XCJtci0zXCJcbiAgICAgICAgICAgIDpzaXplPVwiMzJcIlxuICAgICAgICAgICAgc3JjPVwiaHR0cHM6Ly9jdWJlLmVsZW1lY2RuLmNvbS8wLzg4LzAzYjBkMzk1ODNmNDgyMDY3NjhhNzUzNGU1NWJjcG5nLnBuZ1wiXG4gICAgICAgICAgLz5cbiAgICAgICAgICA8c3BhbiBjbGFzcz1cInRleHQtbGFyZ2UgZm9udC02MDAgbXItM1wiPiBUaXRsZSA8L3NwYW4+XG4gICAgICAgICAgPHNwYW5cbiAgICAgICAgICAgIGNsYXNzPVwidGV4dC1zbSBtci0yXCJcbiAgICAgICAgICAgIHN0eWxlPVwiY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3ItcmVndWxhcilcIlxuICAgICAgICAgID5cbiAgICAgICAgICAgIFN1YiB0aXRsZVxuICAgICAgICAgIDwvc3Bhbj5cbiAgICAgICAgICA8ZWwtdGFnPkRlZmF1bHQ8L2VsLXRhZz5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgPHRlbXBsYXRlICNleHRyYT5cbiAgICAgICAgPGRpdiBjbGFzcz1cImZsZXggaXRlbXMtY2VudGVyXCI+XG4gICAgICAgICAgPGVsLWJ1dHRvbj5QcmludDwvZWwtYnV0dG9uPlxuICAgICAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBjbGFzcz1cIm1sLTJcIj5FZGl0PC9lbC1idXR0b24+XG4gICAgICAgIDwvZGl2PlxuICAgICAgPC90ZW1wbGF0ZT5cblxuICAgICAgPGVsLWRlc2NyaXB0aW9ucyA6Y29sdW1uPVwiM1wiIHNpemU9XCJzbWFsbFwiIGNsYXNzPVwibXQtNFwiPlxuICAgICAgICA8ZWwtZGVzY3JpcHRpb25zLWl0ZW0gbGFiZWw9XCJVc2VybmFtZVwiPlxuICAgICAgICAgIGtvb3Jpb29rYW1pXG4gICAgICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgICAgIDxlbC1kZXNjcmlwdGlvbnMtaXRlbSBsYWJlbD1cIlRlbGVwaG9uZVwiPlxuICAgICAgICAgIDE4MTAwMDAwMDAwXG4gICAgICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgICAgIDxlbC1kZXNjcmlwdGlvbnMtaXRlbSBsYWJlbD1cIlBsYWNlXCI+U3V6aG91PC9lbC1kZXNjcmlwdGlvbnMtaXRlbT5cbiAgICAgICAgPGVsLWRlc2NyaXB0aW9ucy1pdGVtIGxhYmVsPVwiUmVtYXJrc1wiPlxuICAgICAgICAgIDxlbC10YWcgc2l6ZT1cInNtYWxsXCI+U2Nob29sPC9lbC10YWc+XG4gICAgICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgICAgIDxlbC1kZXNjcmlwdGlvbnMtaXRlbSBsYWJlbD1cIkFkZHJlc3NcIj5cbiAgICAgICAgICBOby4xMTg4LCBXdXpob25nIEF2ZW51ZSwgV3V6aG9uZyBEaXN0cmljdCwgU3V6aG91LCBKaWFuZ3N1IFByb3ZpbmNlXG4gICAgICAgIDwvZWwtZGVzY3JpcHRpb25zLWl0ZW0+XG4gICAgICA8L2VsLWRlc2NyaXB0aW9ucz5cbiAgICAgIDxwIGNsYXNzPVwibXQtNCB0ZXh0LXNtXCI+XG4gICAgICAgIEVsZW1lbnQgUGx1cyB0ZWFtIHVzZXMgPGI+d2Vla2x5PC9iPiByZWxlYXNlIHN0cmF0ZWd5IHVuZGVyIG5vcm1hbFxuICAgICAgICBjaXJjdW1zdGFuY2UsIGJ1dCBjcml0aWNhbCBidWcgZml4ZXMgd291bGQgcmVxdWlyZSBob3RmaXggc28gdGhlIGFjdHVhbFxuICAgICAgICByZWxlYXNlIG51bWJlciA8Yj5jb3VsZCBiZTwvYj4gbW9yZSB0aGFuIDEgcGVyIHdlZWsuXG4gICAgICA8L3A+XG4gICAgPC9lbC1wYWdlLWhlYWRlcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgRWxOb3RpZmljYXRpb24gYXMgbm90aWZ5IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvbkJhY2sgPSAoKSA9PiB7XG4gIG5vdGlmeSgnQmFjaycpXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/page-header/complete.vue)_

vue

```
<template>
  <div aria-label="A complete example of page header">
    <el-page-header @back="onBack">
      <template #breadcrumb>
        <el-breadcrumb separator="/">
          <el-breadcrumb-item :to="{ path: './page-header.html' }">
            homepage
          </el-breadcrumb-item>
          <el-breadcrumb-item>
            <a href="./page-header.html">route 1</a>
          </el-breadcrumb-item>
          <el-breadcrumb-item>route 2</el-breadcrumb-item>
        </el-breadcrumb>
      </template>
      <template #content>
        <div class="flex items-center">
          <el-avatar
            class="mr-3"
            :size="32"
            src="https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png"
          />
          <span class="text-large font-600 mr-3"> Title </span>
          <span
            class="text-sm mr-2"
            style="color: var(--el-text-color-regular)"
          >
            Sub title
          </span>
          <el-tag>Default</el-tag>
        </div>
      </template>
      <template #extra>
        <div class="flex items-center">
          <el-button>Print</el-button>
          <el-button type="primary" class="ml-2">Edit</el-button>
        </div>
      </template>

      <el-descriptions :column="3" size="small" class="mt-4">
        <el-descriptions-item label="Username">
          kooriookami
        </el-descriptions-item>
        <el-descriptions-item label="Telephone">
          18100000000
        </el-descriptions-item>
        <el-descriptions-item label="Place">Suzhou</el-descriptions-item>
        <el-descriptions-item label="Remarks">
          <el-tag size="small">School</el-tag>
        </el-descriptions-item>
        <el-descriptions-item label="Address">
          No.1188, Wuzhong Avenue, Wuzhong District, Suzhou, Jiangsu Province
        </el-descriptions-item>
      </el-descriptions>
      <p class="mt-4 text-sm">
        Element Plus team uses <b>weekly</b> release strategy under normal
        circumstance, but critical bug fixes would require hotfix so the actual
        release number <b>could be</b> more than 1 per week.
      </p>
    </el-page-header>
  </div>
</template>

<script setup lang="ts">
import { ElNotification as notify } from 'element-plus'

const onBack = () => {
  notify('Back')
}
</script>
```

隐藏源代码

## 基础用法 [​](#基础用法)

简单场景下的标准页头。

Back

Title

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcGFnZS1oZWFkZXIgQGJhY2s9XCJnb0JhY2tcIj5cbiAgICA8dGVtcGxhdGUgI2NvbnRlbnQ+XG4gICAgICA8c3BhbiBjbGFzcz1cInRleHQtbGFyZ2UgZm9udC02MDAgbXItM1wiPiBUaXRsZSA8L3NwYW4+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1wYWdlLWhlYWRlcj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5jb25zdCBnb0JhY2sgPSAoKSA9PiB7XG4gIGNvbnNvbGUubG9nKCdnbyBiYWNrJylcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/page-header/basic.vue)_

vue

```
<template>
  <el-page-header @back="goBack">
    <template #content>
      <span class="text-large font-600 mr-3"> Title </span>
    </template>
  </el-page-header>
</template>

<script lang="ts" setup>
const goBack = () => {
  console.log('go back')
}
</script>
```

隐藏源代码

## 自定义图标 [​](#自定义图标)

默认图标可能无法满足您的需求，您可以通过设置`icon`属性来自定义图标，示例如下。

Back

Title

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcGFnZS1oZWFkZXIgOmljb249XCJBcnJvd0xlZnRcIj5cbiAgICA8dGVtcGxhdGUgI2NvbnRlbnQ+XG4gICAgICA8c3BhbiBjbGFzcz1cInRleHQtbGFyZ2UgZm9udC02MDAgbXItM1wiPiBUaXRsZSA8L3NwYW4+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1wYWdlLWhlYWRlcj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBBcnJvd0xlZnQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/page-header/custom-icon.vue)_

vue

```
<template>
  <el-page-header :icon="ArrowLeft">
    <template #content>
      <span class="text-large font-600 mr-3"> Title </span>
    </template>
  </el-page-header>
</template>

<script lang="ts" setup>
import { ArrowLeft } from '@element-plus/icons-vue'
</script>
```

隐藏源代码

## 无图标 [​](#无图标)

有时，页面全是元素，您可能不想展示页面上方的图标，您可以设置`icon`属性值为`""`来去除它。

Back

Title

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcGFnZS1oZWFkZXIgaWNvbj1cIlwiPlxuICAgIDx0ZW1wbGF0ZSAjY29udGVudD5cbiAgICAgIDxzcGFuIGNsYXNzPVwidGV4dC1sYXJnZSBmb250LTYwMCBtci0zXCI+IFRpdGxlIDwvc3Bhbj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLXBhZ2UtaGVhZGVyPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/page-header/no-icon.vue)_

vue

```
<template>
  <el-page-header icon="">
    <template #content>
      <span class="text-large font-600 mr-3"> Title </span>
    </template>
  </el-page-header>
</template>
```

隐藏源代码

## 面包屑导航 [​](#面包屑导航)

使用页头组件，您可以通过添加插槽 `breadcrumb` 来设置面包屑路由导航。

homepage /[route 1](https://element-plus.org/zh-CN/component/page-header.html)/route 2/

Back

Title

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcGFnZS1oZWFkZXI+XG4gICAgPHRlbXBsYXRlICNicmVhZGNydW1iPlxuICAgICAgPGVsLWJyZWFkY3J1bWIgc2VwYXJhdG9yPVwiL1wiPlxuICAgICAgICA8ZWwtYnJlYWRjcnVtYi1pdGVtIDp0bz1cInsgcGF0aDogJy4vcGFnZS1oZWFkZXIuaHRtbCcgfVwiPlxuICAgICAgICAgIGhvbWVwYWdlXG4gICAgICAgIDwvZWwtYnJlYWRjcnVtYi1pdGVtPlxuICAgICAgICA8ZWwtYnJlYWRjcnVtYi1pdGVtXG4gICAgICAgICAgPjxhIGhyZWY9XCIuL3BhZ2UtaGVhZGVyLmh0bWxcIj5yb3V0ZSAxPC9hPjwvZWwtYnJlYWRjcnVtYi1pdGVtXG4gICAgICAgID5cbiAgICAgICAgPGVsLWJyZWFkY3J1bWItaXRlbT5yb3V0ZSAyPC9lbC1icmVhZGNydW1iLWl0ZW0+XG4gICAgICA8L2VsLWJyZWFkY3J1bWI+XG4gICAgPC90ZW1wbGF0ZT5cbiAgICA8dGVtcGxhdGUgI2NvbnRlbnQ+XG4gICAgICA8c3BhbiBjbGFzcz1cInRleHQtbGFyZ2UgZm9udC02MDAgbXItM1wiPiBUaXRsZSA8L3NwYW4+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1wYWdlLWhlYWRlcj5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/page-header/breadcrumb.vue)_

vue

```
<template>
  <el-page-header>
    <template #breadcrumb>
      <el-breadcrumb separator="/">
        <el-breadcrumb-item :to="{ path: './page-header.html' }">
          homepage
        </el-breadcrumb-item>
        <el-breadcrumb-item
          ><a href="./page-header.html">route 1</a></el-breadcrumb-item
        >
        <el-breadcrumb-item>route 2</el-breadcrumb-item>
      </el-breadcrumb>
    </template>
    <template #content>
      <span class="text-large font-600 mr-3"> Title </span>
    </template>
  </el-page-header>
</template>
```

隐藏源代码

## 额外操作部分 [​](#额外操作部分)

头部可能会变得很复杂，您可以在头部添加更多的区块，以允许丰富的交互。

Back

![](https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png) Title Sub title Default

PrintEdit

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcGFnZS1oZWFkZXIgaWNvbj1cIlwiPlxuICAgIDx0ZW1wbGF0ZSAjY29udGVudD5cbiAgICAgIDxkaXYgY2xhc3M9XCJmbGV4IGl0ZW1zLWNlbnRlclwiPlxuICAgICAgICA8ZWwtYXZhdGFyXG4gICAgICAgICAgOnNpemU9XCIzMlwiXG4gICAgICAgICAgY2xhc3M9XCJtci0zXCJcbiAgICAgICAgICBzcmM9XCJodHRwczovL2N1YmUuZWxlbWVjZG4uY29tLzAvODgvMDNiMGQzOTU4M2Y0ODIwNjc2OGE3NTM0ZTU1YmNwbmcucG5nXCJcbiAgICAgICAgLz5cbiAgICAgICAgPHNwYW4gY2xhc3M9XCJ0ZXh0LWxhcmdlIGZvbnQtNjAwIG1yLTNcIj4gVGl0bGUgPC9zcGFuPlxuICAgICAgICA8c3BhbiBjbGFzcz1cInRleHQtc20gbXItMlwiIHN0eWxlPVwiY29sb3I6IHZhcigtLWVsLXRleHQtY29sb3ItcmVndWxhcilcIj5cbiAgICAgICAgICBTdWIgdGl0bGVcbiAgICAgICAgPC9zcGFuPlxuICAgICAgICA8ZWwtdGFnPkRlZmF1bHQ8L2VsLXRhZz5cbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gICAgPHRlbXBsYXRlICNleHRyYT5cbiAgICAgIDxkaXYgY2xhc3M9XCJmbGV4IGl0ZW1zLWNlbnRlclwiPlxuICAgICAgICA8ZWwtYnV0dG9uPlByaW50PC9lbC1idXR0b24+XG4gICAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBjbGFzcz1cIm1sLTJcIj5FZGl0PC9lbC1idXR0b24+XG4gICAgICA8L2Rpdj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLXBhZ2UtaGVhZGVyPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/page-header/additional-sections.vue)_

vue

```
<template>
  <el-page-header icon="">
    <template #content>
      <div class="flex items-center">
        <el-avatar
          :size="32"
          class="mr-3"
          src="https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png"
        />
        <span class="text-large font-600 mr-3"> Title </span>
        <span class="text-sm mr-2" style="color: var(--el-text-color-regular)">
          Sub title
        </span>
        <el-tag>Default</el-tag>
      </div>
    </template>
    <template #extra>
      <div class="flex items-center">
        <el-button>Print</el-button>
        <el-button type="primary" class="ml-2">Edit</el-button>
      </div>
    </template>
  </el-page-header>
</template>
```

隐藏源代码

## 主要内容 [​](#主要内容)

有时我们想让页头显示一些协同响应内容，我们可以使用 `default` 插槽。

Back

Title

Your additional content can be added with default slot, You may put as many content as you want here.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcGFnZS1oZWFkZXI+XG4gICAgPHRlbXBsYXRlICNjb250ZW50PlxuICAgICAgPHNwYW4gY2xhc3M9XCJ0ZXh0LWxhcmdlIGZvbnQtNjAwIG1yLTNcIj4gVGl0bGUgPC9zcGFuPlxuICAgIDwvdGVtcGxhdGU+XG4gICAgPGRpdiBjbGFzcz1cIm10LTQgdGV4dC1zbSBmb250LWJvbGRcIj5cbiAgICAgIFlvdXIgYWRkaXRpb25hbCBjb250ZW50IGNhbiBiZSBhZGRlZCB3aXRoIGRlZmF1bHQgc2xvdCwgWW91IG1heSBwdXQgYXNcbiAgICAgIG1hbnkgY29udGVudCBhcyB5b3Ugd2FudCBoZXJlLlxuICAgIDwvZGl2PlxuICA8L2VsLXBhZ2UtaGVhZGVyPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/page-header/main-content.vue)_

vue

```
<template>
  <el-page-header>
    <template #content>
      <span class="text-large font-600 mr-3"> Title </span>
    </template>
    <div class="mt-4 text-sm font-bold">
      Your additional content can be added with default slot, You may put as
      many content as you want here.
    </div>
  </el-page-header>
</template>
```

隐藏源代码

## 组件插槽结构 [​](#组件插槽结构)

本组件由这些部件构成：

vue

```
<template>
  <el-page-header>
    <!-- Line 1 -->
    <template #breadcrumb />
    <!-- Line 2 -->
    <template #icon />
    <template #title />
    <template #content />
    <template #extra />
    <!-- Lines after 2 -->
    <template #default />
  </el-page-header>
</template>
```

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| icon | Page Header 的图标 Icon 组件 | `string` / `Component` | Back |
| title | Page Header 的主标题，默认是 Back (内置 a11y) | `string` | '' |
| content | Page Header 的内容 | `string` | '' |

### 事件 [​](#事件)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| back | 点击左侧区域触发 | `Function` |

### 插槽 [​](#插槽)

| 名称 | 说明 |
| --- | --- |
| icon | 图标内容 |
| title | 标题内容 |
| content | 内容 |
| extra | 扩展设置 |
| breadcrumb | 面包屑导航内容 |
| default | 默认内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/page-header) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/page-header.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/page-header.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/20151622?v=4&size=64)](https://github.com/william-xue)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/17726809?v=4&size=64)](https://github.com/LiZhequ)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)

[Menu 菜单](https://element-plus.org/zh-CN/component/menu)

[Steps 步骤条](https://element-plus.org/zh-CN/component/steps)




---
## [navigation/steps] Steps 步骤条
> 官方文档: https://element-plus.org/zh-CN/component/steps.html

---

# Steps 步骤条 [​](#steps-步骤条)

更新日志待解决

4

引导用户按照流程完成任务的分步导航条， 可根据实际应用场景设定步骤，步骤不得少于 2 步。

## 基础用法 [​](#基础用法)

简单的步骤条。

设置 `active` 属性，接受一个 `Number`，表明步骤的 index，从 0 开始。 需要定宽的步骤条时，设置 `space` 属性即可，它接受 `Number`， 单位为 `px`， 如果不设置，则为自适应。 设置 `finish-status` 属性可以改变已经完成的步骤的状态。

Step 1

Step 2

Step 3

Next step

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3RlcHMgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCIgOmFjdGl2ZT1cImFjdGl2ZVwiIGZpbmlzaC1zdGF0dXM9XCJzdWNjZXNzXCI+XG4gICAgPGVsLXN0ZXAgdGl0bGU9XCJTdGVwIDFcIiAvPlxuICAgIDxlbC1zdGVwIHRpdGxlPVwiU3RlcCAyXCIgLz5cbiAgICA8ZWwtc3RlcCB0aXRsZT1cIlN0ZXAgM1wiIC8+XG4gIDwvZWwtc3RlcHM+XG5cbiAgPGVsLWJ1dHRvbiBzdHlsZT1cIm1hcmdpbi10b3A6IDEycHhcIiBAY2xpY2s9XCJuZXh0XCI+TmV4dCBzdGVwPC9lbC1idXR0b24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBhY3RpdmUgPSByZWYoMClcblxuY29uc3QgbmV4dCA9ICgpID0+IHtcbiAgaWYgKGFjdGl2ZS52YWx1ZSsrID4gMikgYWN0aXZlLnZhbHVlID0gMFxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/steps/basic.vue)_

vue

```
<template>
  <el-steps style="max-width: 600px" :active="active" finish-status="success">
    <el-step title="Step 1" />
    <el-step title="Step 2" />
    <el-step title="Step 3" />
  </el-steps>

  <el-button style="margin-top: 12px" @click="next">Next step</el-button>
</template>

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

const active = ref(0)

const next = () => {
  if (active.value++ > 2) active.value = 0
}
</script>
```

隐藏源代码

## 含状态的步骤条 [​](#含状态的步骤条)

每一步骤显示出该步骤的状态。

也可以使用 `title` 具名插槽，可以用 `slot` 的方式来取代属性的设置， 在本文档最后的列表中有所有的插槽可供参考。

Done

Processing

Step 3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3RlcHNcbiAgICBzdHlsZT1cIm1heC13aWR0aDogNjAwcHhcIlxuICAgIDpzcGFjZT1cIjIwMFwiXG4gICAgOmFjdGl2ZT1cIjFcIlxuICAgIGZpbmlzaC1zdGF0dXM9XCJzdWNjZXNzXCJcbiAgPlxuICAgIDxlbC1zdGVwIHRpdGxlPVwiRG9uZVwiIC8+XG4gICAgPGVsLXN0ZXAgdGl0bGU9XCJQcm9jZXNzaW5nXCIgLz5cbiAgICA8ZWwtc3RlcCB0aXRsZT1cIlN0ZXAgM1wiIC8+XG4gIDwvZWwtc3RlcHM+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/steps/with-status.vue)_

vue

```
<template>
  <el-steps
    style="max-width: 600px"
    :space="200"
    :active="1"
    finish-status="success"
  >
    <el-step title="Done" />
    <el-step title="Processing" />
    <el-step title="Step 3" />
  </el-steps>
</template>
```

隐藏源代码

## 居中的步骤条 [​](#居中的步骤条)

标题和描述可以居中。

1

Step 1

Some description

2

Step 2

Some description

3

Step 3

Some description

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3RlcHMgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCIgOmFjdGl2ZT1cIjJcIiBhbGlnbi1jZW50ZXI+XG4gICAgPGVsLXN0ZXAgdGl0bGU9XCJTdGVwIDFcIiBkZXNjcmlwdGlvbj1cIlNvbWUgZGVzY3JpcHRpb25cIiAvPlxuICAgIDxlbC1zdGVwIHRpdGxlPVwiU3RlcCAyXCIgZGVzY3JpcHRpb249XCJTb21lIGRlc2NyaXB0aW9uXCIgLz5cbiAgICA8ZWwtc3RlcCB0aXRsZT1cIlN0ZXAgM1wiIGRlc2NyaXB0aW9uPVwiU29tZSBkZXNjcmlwdGlvblwiIC8+XG4gIDwvZWwtc3RlcHM+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/steps/centered.vue)_

vue

```
<template>
  <el-steps style="max-width: 600px" :active="2" align-center>
    <el-step title="Step 1" description="Some description" />
    <el-step title="Step 2" description="Some description" />
    <el-step title="Step 3" description="Some description" />
  </el-steps>
</template>
```

隐藏源代码

## 带描述的步骤栏 [​](#带描述的步骤栏)

每一步都有描述。

1

Step 1

Some description

2

Step 2

Some description

3

Step 3

Some description

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3RlcHMgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCIgOmFjdGl2ZT1cIjFcIj5cbiAgICA8ZWwtc3RlcCB0aXRsZT1cIlN0ZXAgMVwiIGRlc2NyaXB0aW9uPVwiU29tZSBkZXNjcmlwdGlvblwiIC8+XG4gICAgPGVsLXN0ZXAgdGl0bGU9XCJTdGVwIDJcIiBkZXNjcmlwdGlvbj1cIlNvbWUgZGVzY3JpcHRpb25cIiAvPlxuICAgIDxlbC1zdGVwIHRpdGxlPVwiU3RlcCAzXCIgZGVzY3JpcHRpb249XCJTb21lIGRlc2NyaXB0aW9uXCIgLz5cbiAgPC9lbC1zdGVwcz5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/steps/with-description.vue)_

vue

```
<template>
  <el-steps style="max-width: 600px" :active="1">
    <el-step title="Step 1" description="Some description" />
    <el-step title="Step 2" description="Some description" />
    <el-step title="Step 3" description="Some description" />
  </el-steps>
</template>
```

隐藏源代码

## 带图标的步骤条 [​](#带图标的步骤条)

可以在步骤栏中使用各种自定义图标。

通过 `icon` 属性来设置图标， 图标的类型可以参考 Icon 组件的文档， 除此以外，还能通过具名 `slot` 来使用自定义的图标。

Step 1

Step 2

Step 3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3RlcHMgc3R5bGU9XCJtYXgtd2lkdGg6IDYwMHB4XCIgOmFjdGl2ZT1cIjFcIj5cbiAgICA8ZWwtc3RlcCB0aXRsZT1cIlN0ZXAgMVwiIDppY29uPVwiRWRpdFwiIC8+XG4gICAgPGVsLXN0ZXAgdGl0bGU9XCJTdGVwIDJcIiA6aWNvbj1cIlVwbG9hZFwiIC8+XG4gICAgPGVsLXN0ZXAgdGl0bGU9XCJTdGVwIDNcIiA6aWNvbj1cIlBpY3R1cmVcIiAvPlxuICA8L2VsLXN0ZXBzPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IEVkaXQsIFBpY3R1cmUsIFVwbG9hZCB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/steps/with-icon.vue)_

vue

```
<template>
  <el-steps style="max-width: 600px" :active="1">
    <el-step title="Step 1" :icon="Edit" />
    <el-step title="Step 2" :icon="Upload" />
    <el-step title="Step 3" :icon="Picture" />
  </el-steps>
</template>

<script lang="ts" setup>
import { Edit, Picture, Upload } from '@element-plus/icons-vue'
</script>
```

隐藏源代码

## 垂直的步骤条 [​](#垂直的步骤条)

垂直方向的步骤条。

只需要在 `el-steps` 元素中设置 `direction` 属性为 `vertical` 即可。

1

Step 1

2

Step 2

3

Step 3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwiaGVpZ2h0OiAzMDBweDsgbWF4LXdpZHRoOiA2MDBweFwiPlxuICAgIDxlbC1zdGVwcyBkaXJlY3Rpb249XCJ2ZXJ0aWNhbFwiIDphY3RpdmU9XCIxXCI+XG4gICAgICA8ZWwtc3RlcCB0aXRsZT1cIlN0ZXAgMVwiIC8+XG4gICAgICA8ZWwtc3RlcCB0aXRsZT1cIlN0ZXAgMlwiIC8+XG4gICAgICA8ZWwtc3RlcCB0aXRsZT1cIlN0ZXAgM1wiIC8+XG4gICAgPC9lbC1zdGVwcz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/steps/vertical.vue)_

vue

```
<template>
  <div style="height: 300px; max-width: 600px">
    <el-steps direction="vertical" :active="1">
      <el-step title="Step 1" />
      <el-step title="Step 2" />
      <el-step title="Step 3" />
    </el-steps>
  </div>
</template>
```

隐藏源代码

## 简洁风格的步骤条 [​](#简洁风格的步骤条)

设置 `simple` 可应用简洁风格，该条件下 `align-center` / `description` / `direction` / `space` 都将失效。

Step 1

Step 2

Step 3

Step 1

Step 2

Step 3

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtc3RlcHNcbiAgICBjbGFzcz1cIm1iLTRcIlxuICAgIHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiXG4gICAgOnNwYWNlPVwiMjAwXCJcbiAgICA6YWN0aXZlPVwiMVwiXG4gICAgc2ltcGxlXG4gID5cbiAgICA8ZWwtc3RlcCB0aXRsZT1cIlN0ZXAgMVwiIDppY29uPVwiRWRpdFwiIC8+XG4gICAgPGVsLXN0ZXAgdGl0bGU9XCJTdGVwIDJcIiA6aWNvbj1cIlVwbG9hZEZpbGxlZFwiIC8+XG4gICAgPGVsLXN0ZXAgdGl0bGU9XCJTdGVwIDNcIiA6aWNvbj1cIlBpY3R1cmVcIiAvPlxuICA8L2VsLXN0ZXBzPlxuXG4gIDxlbC1zdGVwcyBzdHlsZT1cIm1heC13aWR0aDogNjAwcHhcIiA6YWN0aXZlPVwiMVwiIGZpbmlzaC1zdGF0dXM9XCJzdWNjZXNzXCIgc2ltcGxlPlxuICAgIDxlbC1zdGVwIHRpdGxlPVwiU3RlcCAxXCIgLz5cbiAgICA8ZWwtc3RlcCB0aXRsZT1cIlN0ZXAgMlwiIC8+XG4gICAgPGVsLXN0ZXAgdGl0bGU9XCJTdGVwIDNcIiAvPlxuICA8L2VsLXN0ZXBzPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IEVkaXQsIFBpY3R1cmUsIFVwbG9hZEZpbGxlZCB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/steps/simple.vue)_

vue

```
<template>
  <el-steps
    class="mb-4"
    style="max-width: 600px"
    :space="200"
    :active="1"
    simple
  >
    <el-step title="Step 1" :icon="Edit" />
    <el-step title="Step 2" :icon="UploadFilled" />
    <el-step title="Step 3" :icon="Picture" />
  </el-steps>

  <el-steps style="max-width: 600px" :active="1" finish-status="success" simple>
    <el-step title="Step 1" />
    <el-step title="Step 2" />
    <el-step title="Step 3" />
  </el-steps>
</template>

<script lang="ts" setup>
import { Edit, Picture, UploadFilled } from '@element-plus/icons-vue'
</script>
```

隐藏源代码

## Steps API [​](#steps-api)

### Steps Attributes [​](#steps-attributes)

| 属性名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| space | 每个 step 的间距，不填写将自适应间距。 支持百分比。 | `number` / `string` | '' |
| direction | 显示方向 | `enum` | horizontal |
| active | 设置当前激活步骤 | `number` | 0 |
| process-status | 设置当前步骤的状态 | `enum` | process |
| finish-status | 设置结束步骤的状态 | `enum` | finish |
| align-center | 进行居中对齐 | `boolean` | — |
| simple | 是否应用简洁风格 | `boolean` | — |

### Steps Events [​](#steps-events)

| 插槽名 | 说明 | 参数： |
| --- | --- | --- |
| change | 当活动步骤发生变化时触发 | `Function` |

### Steps Slots [​](#steps-slots)

| 属性名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 默认插槽 | Step |

## Step API [​](#step-api)

### Step Attributes [​](#step-attributes)

| 插槽名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| title | 标题 | `string` | '' |
| description | 描述文案 | `string` | '' |
| icon | Step 组件的自定义图标。 也支持 slot 方式写入 | `string` / `Component` | — |
| status | 设置当前步骤的状态， 不设置则根据 steps 确定状态 | `enum` | '' |

### Step Slots [​](#step-slots)

| 方法名 | 描述 |
| --- | --- |
| icon | 自定义图标 |
| title | 自定义标题 |
| description | 自定义描述文案 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/steps) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/steps.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/steps.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/33646534?v=4&size=64)](https://github.com/SevenDreamYang)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/126545033?v=4&size=64)](https://github.com/dhj-l)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/57785259?v=4&size=64)](https://github.com/w2xi)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/57086651?v=4&size=64)](https://github.com/Simon-He95)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/19829491?v=4&size=64)](https://github.com/z-ao)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/4318293?v=4&size=64)](https://github.com/cn-troy)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)

[Page Header 页头](https://element-plus.org/zh-CN/component/page-header)

[Tabs 标签页](https://element-plus.org/zh-CN/component/tabs)




---
## [navigation/tabs] Tabs 标签页
> 官方文档: https://element-plus.org/zh-CN/component/tabs.html

---

# Tabs 标签页 [​](#tabs-标签页)

更新日志待解决

9

分隔内容上有关联但属于不同类别的数据集合。

## 基础用法 [​](#基础用法)

基础的、简洁的标签页。

Tabs 组件提供了选项卡功能， 默认选中第一个标签页，你也可以通过 `value` 属性来指定当前选中的标签页。

User

Config

Role

Task

User

Config

Role

Task

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFicyB2LW1vZGVsPVwiYWN0aXZlTmFtZVwiIGNsYXNzPVwiZGVtby10YWJzXCIgQHRhYi1jbGljaz1cImhhbmRsZUNsaWNrXCI+XG4gICAgPGVsLXRhYi1wYW5lIGxhYmVsPVwiVXNlclwiIG5hbWU9XCJmaXJzdFwiPlVzZXI8L2VsLXRhYi1wYW5lPlxuICAgIDxlbC10YWItcGFuZSBsYWJlbD1cIkNvbmZpZ1wiIG5hbWU9XCJzZWNvbmRcIj5Db25maWc8L2VsLXRhYi1wYW5lPlxuICAgIDxlbC10YWItcGFuZSBsYWJlbD1cIlJvbGVcIiBuYW1lPVwidGhpcmRcIj5Sb2xlPC9lbC10YWItcGFuZT5cbiAgICA8ZWwtdGFiLXBhbmUgbGFiZWw9XCJUYXNrXCIgbmFtZT1cImZvdXJ0aFwiPlRhc2s8L2VsLXRhYi1wYW5lPlxuICA8L2VsLXRhYnM+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IFRhYnNQYW5lQ29udGV4dCB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgYWN0aXZlTmFtZSA9IHJlZignZmlyc3QnKVxuXG5jb25zdCBoYW5kbGVDbGljayA9ICh0YWI6IFRhYnNQYW5lQ29udGV4dCwgZXZlbnQ6IEV2ZW50KSA9PiB7XG4gIGNvbnNvbGUubG9nKHRhYiwgZXZlbnQpXG59XG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLmRlbW8tdGFicyA+IC5lbC10YWJzX19jb250ZW50IHtcbiAgcGFkZGluZzogMzJweDtcbiAgY29sb3I6ICM2Yjc3OGM7XG4gIGZvbnQtc2l6ZTogMzJweDtcbiAgZm9udC13ZWlnaHQ6IDYwMDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tabs/basic.vue)_

vue

```
<template>
  <el-tabs v-model="activeName" class="demo-tabs" @tab-click="handleClick">
    <el-tab-pane label="User" name="first">User</el-tab-pane>
    <el-tab-pane label="Config" name="second">Config</el-tab-pane>
    <el-tab-pane label="Role" name="third">Role</el-tab-pane>
    <el-tab-pane label="Task" name="fourth">Task</el-tab-pane>
  </el-tabs>
</template>

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

import type { TabsPaneContext } from 'element-plus'

const activeName = ref('first')

const handleClick = (tab: TabsPaneContext, event: Event) => {
  console.log(tab, event)
}
</script>

<style>
.demo-tabs > .el-tabs__content {
  padding: 32px;
  color: #6b778c;
  font-size: 32px;
  font-weight: 600;
}
</style>
```

隐藏源代码

## 卡片风格的标签 [​](#卡片风格的标签)

你可以设置具有卡片风格的标签。

只需要设置 `type` 属性为 `card` 就可以使选项卡改变为标签风格。

User

Config

Role

Task

User

Config

Role

Task

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFic1xuICAgIHYtbW9kZWw9XCJhY3RpdmVOYW1lXCJcbiAgICB0eXBlPVwiY2FyZFwiXG4gICAgY2xhc3M9XCJkZW1vLXRhYnNcIlxuICAgIEB0YWItY2xpY2s9XCJoYW5kbGVDbGlja1wiXG4gID5cbiAgICA8ZWwtdGFiLXBhbmUgbGFiZWw9XCJVc2VyXCIgbmFtZT1cImZpcnN0XCI+VXNlcjwvZWwtdGFiLXBhbmU+XG4gICAgPGVsLXRhYi1wYW5lIGxhYmVsPVwiQ29uZmlnXCIgbmFtZT1cInNlY29uZFwiPkNvbmZpZzwvZWwtdGFiLXBhbmU+XG4gICAgPGVsLXRhYi1wYW5lIGxhYmVsPVwiUm9sZVwiIG5hbWU9XCJ0aGlyZFwiPlJvbGU8L2VsLXRhYi1wYW5lPlxuICAgIDxlbC10YWItcGFuZSBsYWJlbD1cIlRhc2tcIiBuYW1lPVwiZm91cnRoXCI+VGFzazwvZWwtdGFiLXBhbmU+XG4gIDwvZWwtdGFicz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmltcG9ydCB0eXBlIHsgVGFic1BhbmVDb250ZXh0IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBhY3RpdmVOYW1lID0gcmVmKCdmaXJzdCcpXG5cbmNvbnN0IGhhbmRsZUNsaWNrID0gKHRhYjogVGFic1BhbmVDb250ZXh0LCBldmVudDogRXZlbnQpID0+IHtcbiAgY29uc29sZS5sb2codGFiLCBldmVudClcbn1cbjwvc2NyaXB0PlxuXG48c3R5bGU+XG4uZGVtby10YWJzID4gLmVsLXRhYnNfX2NvbnRlbnQge1xuICBwYWRkaW5nOiAzMnB4O1xuICBjb2xvcjogIzZiNzc4YztcbiAgZm9udC1zaXplOiAzMnB4O1xuICBmb250LXdlaWdodDogNjAwO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tabs/card-style.vue)_

vue

```
<template>
  <el-tabs
    v-model="activeName"
    type="card"
    class="demo-tabs"
    @tab-click="handleClick"
  >
    <el-tab-pane label="User" name="first">User</el-tab-pane>
    <el-tab-pane label="Config" name="second">Config</el-tab-pane>
    <el-tab-pane label="Role" name="third">Role</el-tab-pane>
    <el-tab-pane label="Task" name="fourth">Task</el-tab-pane>
  </el-tabs>
</template>

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

import type { TabsPaneContext } from 'element-plus'

const activeName = ref('first')

const handleClick = (tab: TabsPaneContext, event: Event) => {
  console.log(tab, event)
}
</script>

<style>
.demo-tabs > .el-tabs__content {
  padding: 32px;
  color: #6b778c;
  font-size: 32px;
  font-weight: 600;
}
</style>
```

隐藏源代码

## 带有边框的卡片风格 [​](#带有边框的卡片风格)

你还可以设置标签页为带有边框的卡片

将 `type` 设置为 `border-card`。

User

Config

Role

Task

User

Config

Role

Task

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFicyB0eXBlPVwiYm9yZGVyLWNhcmRcIj5cbiAgICA8ZWwtdGFiLXBhbmUgbGFiZWw9XCJVc2VyXCI+VXNlcjwvZWwtdGFiLXBhbmU+XG4gICAgPGVsLXRhYi1wYW5lIGxhYmVsPVwiQ29uZmlnXCI+Q29uZmlnPC9lbC10YWItcGFuZT5cbiAgICA8ZWwtdGFiLXBhbmUgbGFiZWw9XCJSb2xlXCI+Um9sZTwvZWwtdGFiLXBhbmU+XG4gICAgPGVsLXRhYi1wYW5lIGxhYmVsPVwiVGFza1wiPlRhc2s8L2VsLXRhYi1wYW5lPlxuICA8L2VsLXRhYnM+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tabs/border-card.vue)_

vue

```
<template>
  <el-tabs type="border-card">
    <el-tab-pane label="User">User</el-tab-pane>
    <el-tab-pane label="Config">Config</el-tab-pane>
    <el-tab-pane label="Role">Role</el-tab-pane>
    <el-tab-pane label="Task">Task</el-tab-pane>
  </el-tabs>
</template>
```

隐藏源代码

## 标签位置的设置 [​](#标签位置的设置)

可以通过 `tab-position` 设置标签的位置

标签一共有四个方向的设置 `tabPosition="left|right|top|bottom"`

toprightbottomleft

User

Config

Role

Task

User

Config

Role

Task

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cInRhYlBvc2l0aW9uXCIgc3R5bGU9XCJtYXJnaW4tYm90dG9tOiAzMHB4XCI+XG4gICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cInRvcFwiPnRvcDwvZWwtcmFkaW8tYnV0dG9uPlxuICAgIDxlbC1yYWRpby1idXR0b24gdmFsdWU9XCJyaWdodFwiPnJpZ2h0PC9lbC1yYWRpby1idXR0b24+XG4gICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cImJvdHRvbVwiPmJvdHRvbTwvZWwtcmFkaW8tYnV0dG9uPlxuICAgIDxlbC1yYWRpby1idXR0b24gdmFsdWU9XCJsZWZ0XCI+bGVmdDwvZWwtcmFkaW8tYnV0dG9uPlxuICA8L2VsLXJhZGlvLWdyb3VwPlxuXG4gIDxlbC10YWJzIDp0YWItcG9zaXRpb249XCJ0YWJQb3NpdGlvblwiIHN0eWxlPVwiaGVpZ2h0OiAyMDBweFwiIGNsYXNzPVwiZGVtby10YWJzXCI+XG4gICAgPGVsLXRhYi1wYW5lIGxhYmVsPVwiVXNlclwiPlVzZXI8L2VsLXRhYi1wYW5lPlxuICAgIDxlbC10YWItcGFuZSBsYWJlbD1cIkNvbmZpZ1wiPkNvbmZpZzwvZWwtdGFiLXBhbmU+XG4gICAgPGVsLXRhYi1wYW5lIGxhYmVsPVwiUm9sZVwiPlJvbGU8L2VsLXRhYi1wYW5lPlxuICAgIDxlbC10YWItcGFuZSBsYWJlbD1cIlRhc2tcIj5UYXNrPC9lbC10YWItcGFuZT5cbiAgPC9lbC10YWJzPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBUYWJzSW5zdGFuY2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHRhYlBvc2l0aW9uID0gcmVmPFRhYnNJbnN0YW5jZVsndGFiUG9zaXRpb24nXT4oJ2xlZnQnKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5kZW1vLXRhYnMgPiAuZWwtdGFic19fY29udGVudCB7XG4gIHBhZGRpbmc6IDMycHg7XG4gIGNvbG9yOiAjNmI3NzhjO1xuICBmb250LXNpemU6IDMycHg7XG4gIGZvbnQtd2VpZ2h0OiA2MDA7XG59XG5cbi5lbC10YWJzLS1yaWdodCAuZWwtdGFic19fY29udGVudCxcbi5lbC10YWJzLS1sZWZ0IC5lbC10YWJzX19jb250ZW50IHtcbiAgaGVpZ2h0OiAxMDAlO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tabs/tab-position.vue)_

vue

```
<template>
  <el-radio-group v-model="tabPosition" style="margin-bottom: 30px">
    <el-radio-button value="top">top</el-radio-button>
    <el-radio-button value="right">right</el-radio-button>
    <el-radio-button value="bottom">bottom</el-radio-button>
    <el-radio-button value="left">left</el-radio-button>
  </el-radio-group>

  <el-tabs :tab-position="tabPosition" style="height: 200px" class="demo-tabs">
    <el-tab-pane label="User">User</el-tab-pane>
    <el-tab-pane label="Config">Config</el-tab-pane>
    <el-tab-pane label="Role">Role</el-tab-pane>
    <el-tab-pane label="Task">Task</el-tab-pane>
  </el-tabs>
</template>

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

import type { TabsInstance } from 'element-plus'

const tabPosition = ref<TabsInstance['tabPosition']>('left')
</script>

<style>
.demo-tabs > .el-tabs__content {
  padding: 32px;
  color: #6b778c;
  font-size: 32px;
  font-weight: 600;
}

.el-tabs--right .el-tabs__content,
.el-tabs--left .el-tabs__content {
  height: 100%;
}
</style>
```

隐藏源代码

## 自定义标签页的内容 [​](#自定义标签页的内容)

可以通过具名插槽来实现自定义标签页的内容

Route

Config

Role

Task

Route

Config

Role

Task

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFicyB0eXBlPVwiYm9yZGVyLWNhcmRcIiBjbGFzcz1cImRlbW8tdGFic1wiPlxuICAgIDxlbC10YWItcGFuZT5cbiAgICAgIDx0ZW1wbGF0ZSAjbGFiZWw+XG4gICAgICAgIDxzcGFuIGNsYXNzPVwiY3VzdG9tLXRhYnMtbGFiZWxcIj5cbiAgICAgICAgICA8ZWwtaWNvbj48Y2FsZW5kYXIgLz48L2VsLWljb24+XG4gICAgICAgICAgPHNwYW4+Um91dGU8L3NwYW4+XG4gICAgICAgIDwvc3Bhbj5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgICBSb3V0ZVxuICAgIDwvZWwtdGFiLXBhbmU+XG4gICAgPGVsLXRhYi1wYW5lIGxhYmVsPVwiQ29uZmlnXCI+Q29uZmlnPC9lbC10YWItcGFuZT5cbiAgICA8ZWwtdGFiLXBhbmUgbGFiZWw9XCJSb2xlXCI+Um9sZTwvZWwtdGFiLXBhbmU+XG4gICAgPGVsLXRhYi1wYW5lIGxhYmVsPVwiVGFza1wiPlRhc2s8L2VsLXRhYi1wYW5lPlxuICA8L2VsLXRhYnM+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgQ2FsZW5kYXIgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcbjwvc2NyaXB0PlxuXG48c3R5bGU+XG4uZGVtby10YWJzID4gLmVsLXRhYnNfX2NvbnRlbnQge1xuICBwYWRkaW5nOiAzMnB4O1xuICBjb2xvcjogIzZiNzc4YztcbiAgZm9udC1zaXplOiAzMnB4O1xuICBmb250LXdlaWdodDogNjAwO1xufVxuLmRlbW8tdGFicyAuY3VzdG9tLXRhYnMtbGFiZWwgLmVsLWljb24ge1xuICB2ZXJ0aWNhbC1hbGlnbjogbWlkZGxlO1xufVxuLmRlbW8tdGFicyAuY3VzdG9tLXRhYnMtbGFiZWwgc3BhbiB7XG4gIHZlcnRpY2FsLWFsaWduOiBtaWRkbGU7XG4gIG1hcmdpbi1sZWZ0OiA0cHg7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tabs/custom-tab.vue)_

vue

```
<template>
  <el-tabs type="border-card" class="demo-tabs">
    <el-tab-pane>
      <template #label>
        <span class="custom-tabs-label">
          <el-icon><calendar /></el-icon>
          <span>Route</span>
        </span>
      </template>
      Route
    </el-tab-pane>
    <el-tab-pane label="Config">Config</el-tab-pane>
    <el-tab-pane label="Role">Role</el-tab-pane>
    <el-tab-pane label="Task">Task</el-tab-pane>
  </el-tabs>
</template>

<script lang="ts" setup>
import { Calendar } from '@element-plus/icons-vue'
</script>

<style>
.demo-tabs > .el-tabs__content {
  padding: 32px;
  color: #6b778c;
  font-size: 32px;
  font-weight: 600;
}
.demo-tabs .custom-tabs-label .el-icon {
  vertical-align: middle;
}
.demo-tabs .custom-tabs-label span {
  vertical-align: middle;
  margin-left: 4px;
}
</style>
```

隐藏源代码

## 动态增减标签页 [​](#动态增减标签页)

增减标签页按钮只能在选项卡样式的标签页下使用

Tab 1

Tab 2

Tab 1 content

Tab 2 content

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFic1xuICAgIHYtbW9kZWw9XCJlZGl0YWJsZVRhYnNWYWx1ZVwiXG4gICAgdHlwZT1cImNhcmRcIlxuICAgIGVkaXRhYmxlXG4gICAgY2xhc3M9XCJkZW1vLXRhYnNcIlxuICAgIEBlZGl0PVwiaGFuZGxlVGFic0VkaXRcIlxuICA+XG4gICAgPGVsLXRhYi1wYW5lXG4gICAgICB2LWZvcj1cIml0ZW0gaW4gZWRpdGFibGVUYWJzXCJcbiAgICAgIDprZXk9XCJpdGVtLm5hbWVcIlxuICAgICAgOmxhYmVsPVwiaXRlbS50aXRsZVwiXG4gICAgICA6bmFtZT1cIml0ZW0ubmFtZVwiXG4gICAgPlxuICAgICAge3sgaXRlbS5jb250ZW50IH19XG4gICAgPC9lbC10YWItcGFuZT5cbiAgPC9lbC10YWJzPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBUYWJQYW5lTmFtZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxubGV0IHRhYkluZGV4ID0gMlxuY29uc3QgZWRpdGFibGVUYWJzVmFsdWUgPSByZWYoJzInKVxuY29uc3QgZWRpdGFibGVUYWJzID0gcmVmKFtcbiAge1xuICAgIHRpdGxlOiAnVGFiIDEnLFxuICAgIG5hbWU6ICcxJyxcbiAgICBjb250ZW50OiAnVGFiIDEgY29udGVudCcsXG4gIH0sXG4gIHtcbiAgICB0aXRsZTogJ1RhYiAyJyxcbiAgICBuYW1lOiAnMicsXG4gICAgY29udGVudDogJ1RhYiAyIGNvbnRlbnQnLFxuICB9LFxuXSlcblxuY29uc3QgaGFuZGxlVGFic0VkaXQgPSAoXG4gIHRhcmdldE5hbWU6IFRhYlBhbmVOYW1lIHwgdW5kZWZpbmVkLFxuICBhY3Rpb246ICdyZW1vdmUnIHwgJ2FkZCdcbikgPT4ge1xuICBpZiAoYWN0aW9uID09PSAnYWRkJykge1xuICAgIGNvbnN0IG5ld1RhYk5hbWUgPSBgJHsrK3RhYkluZGV4fWBcbiAgICBlZGl0YWJsZVRhYnMudmFsdWUucHVzaCh7XG4gICAgICB0aXRsZTogJ05ldyBUYWInLFxuICAgICAgbmFtZTogbmV3VGFiTmFtZSxcbiAgICAgIGNvbnRlbnQ6ICdOZXcgVGFiIGNvbnRlbnQnLFxuICAgIH0pXG4gICAgZWRpdGFibGVUYWJzVmFsdWUudmFsdWUgPSBuZXdUYWJOYW1lXG4gIH0gZWxzZSBpZiAoYWN0aW9uID09PSAncmVtb3ZlJykge1xuICAgIGNvbnN0IHRhYnMgPSBlZGl0YWJsZVRhYnMudmFsdWVcbiAgICBsZXQgYWN0aXZlTmFtZSA9IGVkaXRhYmxlVGFic1ZhbHVlLnZhbHVlXG4gICAgaWYgKGFjdGl2ZU5hbWUgPT09IHRhcmdldE5hbWUpIHtcbiAgICAgIHRhYnMuZm9yRWFjaCgodGFiLCBpbmRleCkgPT4ge1xuICAgICAgICBpZiAodGFiLm5hbWUgPT09IHRhcmdldE5hbWUpIHtcbiAgICAgICAgICBjb25zdCBuZXh0VGFiID0gdGFic1tpbmRleCArIDFdIHx8IHRhYnNbaW5kZXggLSAxXVxuICAgICAgICAgIGlmIChuZXh0VGFiKSB7XG4gICAgICAgICAgICBhY3RpdmVOYW1lID0gbmV4dFRhYi5uYW1lXG4gICAgICAgICAgfVxuICAgICAgICB9XG4gICAgICB9KVxuICAgIH1cblxuICAgIGVkaXRhYmxlVGFic1ZhbHVlLnZhbHVlID0gYWN0aXZlTmFtZVxuICAgIGVkaXRhYmxlVGFicy52YWx1ZSA9IHRhYnMuZmlsdGVyKCh0YWIpID0+IHRhYi5uYW1lICE9PSB0YXJnZXROYW1lKVxuICB9XG59XG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLmRlbW8tdGFicyA+IC5lbC10YWJzX19jb250ZW50IHtcbiAgcGFkZGluZzogMzJweDtcbiAgY29sb3I6ICM2Yjc3OGM7XG4gIGZvbnQtc2l6ZTogMzJweDtcbiAgZm9udC13ZWlnaHQ6IDYwMDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tabs/dynamic-tabs.vue)_

vue

```
<template>
  <el-tabs
    v-model="editableTabsValue"
    type="card"
    editable
    class="demo-tabs"
    @edit="handleTabsEdit"
  >
    <el-tab-pane
      v-for="item in editableTabs"
      :key="item.name"
      :label="item.title"
      :name="item.name"
    >
      {{ item.content }}
    </el-tab-pane>
  </el-tabs>
</template>

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

import type { TabPaneName } from 'element-plus'

let tabIndex = 2
const editableTabsValue = ref('2')
const editableTabs = ref([
  {
    title: 'Tab 1',
    name: '1',
    content: 'Tab 1 content',
  },
  {
    title: 'Tab 2',
    name: '2',
    content: 'Tab 2 content',
  },
])

const handleTabsEdit = (
  targetName: TabPaneName | undefined,
  action: 'remove' | 'add'
) => {
  if (action === 'add') {
    const newTabName = `${++tabIndex}`
    editableTabs.value.push({
      title: 'New Tab',
      name: newTabName,
      content: 'New Tab content',
    })
    editableTabsValue.value = newTabName
  } else if (action === 'remove') {
    const tabs = editableTabs.value
    let activeName = editableTabsValue.value
    if (activeName === targetName) {
      tabs.forEach((tab, index) => {
        if (tab.name === targetName) {
          const nextTab = tabs[index + 1] || tabs[index - 1]
          if (nextTab) {
            activeName = nextTab.name
          }
        }
      })
    }

    editableTabsValue.value = activeName
    editableTabs.value = tabs.filter((tab) => tab.name !== targetName)
  }
}
</script>

<style>
.demo-tabs > .el-tabs__content {
  padding: 32px;
  color: #6b778c;
  font-size: 32px;
  font-weight: 600;
}
</style>
```

隐藏源代码

## 添加按钮自定义图标 2.4.0 [​](#添加按钮自定义图标)

Tab 1

Tab 2

Tab 1 content

Tab 2 content

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiYWRkSWNvblxuPHRlbXBsYXRlPlxuICA8ZWwtdGFic1xuICAgIHYtbW9kZWw9XCJlZGl0YWJsZVRhYnNWYWx1ZVwiXG4gICAgdHlwZT1cImNhcmRcIlxuICAgIGNsYXNzPVwiZGVtby10YWJzXCJcbiAgICBlZGl0YWJsZVxuICAgIEBlZGl0PVwiaGFuZGxlVGFic0VkaXRcIlxuICA+XG4gICAgPHRlbXBsYXRlICNhZGQtaWNvbj5cbiAgICAgIDxlbC1pY29uPjxTZWxlY3QgLz48L2VsLWljb24+XG4gICAgPC90ZW1wbGF0ZT5cbiAgICA8ZWwtdGFiLXBhbmVcbiAgICAgIHYtZm9yPVwiaXRlbSBpbiBlZGl0YWJsZVRhYnNcIlxuICAgICAgOmtleT1cIml0ZW0ubmFtZVwiXG4gICAgICA6bGFiZWw9XCJpdGVtLnRpdGxlXCJcbiAgICAgIDpuYW1lPVwiaXRlbS5uYW1lXCJcbiAgICA+XG4gICAgICB7eyBpdGVtLmNvbnRlbnQgfX1cbiAgICA8L2VsLXRhYi1wYW5lPlxuICA8L2VsLXRhYnM+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgU2VsZWN0IH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmltcG9ydCB0eXBlIHsgVGFiUGFuZU5hbWUgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmxldCB0YWJJbmRleCA9IDJcbmNvbnN0IGVkaXRhYmxlVGFic1ZhbHVlID0gcmVmKCcyJylcbmNvbnN0IGVkaXRhYmxlVGFicyA9IHJlZihbXG4gIHtcbiAgICB0aXRsZTogJ1RhYiAxJyxcbiAgICBuYW1lOiAnMScsXG4gICAgY29udGVudDogJ1RhYiAxIGNvbnRlbnQnLFxuICB9LFxuICB7XG4gICAgdGl0bGU6ICdUYWIgMicsXG4gICAgbmFtZTogJzInLFxuICAgIGNvbnRlbnQ6ICdUYWIgMiBjb250ZW50JyxcbiAgfSxcbl0pXG5cbmNvbnN0IGhhbmRsZVRhYnNFZGl0ID0gKFxuICB0YXJnZXROYW1lOiBUYWJQYW5lTmFtZSB8IHVuZGVmaW5lZCxcbiAgYWN0aW9uOiAncmVtb3ZlJyB8ICdhZGQnXG4pID0+IHtcbiAgaWYgKGFjdGlvbiA9PT0gJ2FkZCcpIHtcbiAgICBjb25zdCBuZXdUYWJOYW1lID0gYCR7Kyt0YWJJbmRleH1gXG4gICAgZWRpdGFibGVUYWJzLnZhbHVlLnB1c2goe1xuICAgICAgdGl0bGU6ICdOZXcgVGFiJyxcbiAgICAgIG5hbWU6IG5ld1RhYk5hbWUsXG4gICAgICBjb250ZW50OiAnTmV3IFRhYiBjb250ZW50JyxcbiAgICB9KVxuICAgIGVkaXRhYmxlVGFic1ZhbHVlLnZhbHVlID0gbmV3VGFiTmFtZVxuICB9IGVsc2UgaWYgKGFjdGlvbiA9PT0gJ3JlbW92ZScpIHtcbiAgICBjb25zdCB0YWJzID0gZWRpdGFibGVUYWJzLnZhbHVlXG4gICAgbGV0IGFjdGl2ZU5hbWUgPSBlZGl0YWJsZVRhYnNWYWx1ZS52YWx1ZVxuICAgIGlmIChhY3RpdmVOYW1lID09PSB0YXJnZXROYW1lKSB7XG4gICAgICB0YWJzLmZvckVhY2goKHRhYiwgaW5kZXgpID0+IHtcbiAgICAgICAgaWYgKHRhYi5uYW1lID09PSB0YXJnZXROYW1lKSB7XG4gICAgICAgICAgY29uc3QgbmV4dFRhYiA9IHRhYnNbaW5kZXggKyAxXSB8fCB0YWJzW2luZGV4IC0gMV1cbiAgICAgICAgICBpZiAobmV4dFRhYikge1xuICAgICAgICAgICAgYWN0aXZlTmFtZSA9IG5leHRUYWIubmFtZVxuICAgICAgICAgIH1cbiAgICAgICAgfVxuICAgICAgfSlcbiAgICB9XG5cbiAgICBlZGl0YWJsZVRhYnNWYWx1ZS52YWx1ZSA9IGFjdGl2ZU5hbWVcbiAgICBlZGl0YWJsZVRhYnMudmFsdWUgPSB0YWJzLmZpbHRlcigodGFiKSA9PiB0YWIubmFtZSAhPT0gdGFyZ2V0TmFtZSlcbiAgfVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5kZW1vLXRhYnMgPiAuZWwtdGFic19fY29udGVudCB7XG4gIHBhZGRpbmc6IDMycHg7XG4gIGNvbG9yOiAjNmI3NzhjO1xuICBmb250LXNpemU6IDMycHg7XG4gIGZvbnQtd2VpZ2h0OiA2MDA7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tabs/customized-add-button-icon.vue)_

vue

```
addIcon
<template>
  <el-tabs
    v-model="editableTabsValue"
    type="card"
    class="demo-tabs"
    editable
    @edit="handleTabsEdit"
  >
    <template #add-icon>
      <el-icon><Select /></el-icon>
    </template>
    <el-tab-pane
      v-for="item in editableTabs"
      :key="item.name"
      :label="item.title"
      :name="item.name"
    >
      {{ item.content }}
    </el-tab-pane>
  </el-tabs>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Select } from '@element-plus/icons-vue'

import type { TabPaneName } from 'element-plus'

let tabIndex = 2
const editableTabsValue = ref('2')
const editableTabs = ref([
  {
    title: 'Tab 1',
    name: '1',
    content: 'Tab 1 content',
  },
  {
    title: 'Tab 2',
    name: '2',
    content: 'Tab 2 content',
  },
])

const handleTabsEdit = (
  targetName: TabPaneName | undefined,
  action: 'remove' | 'add'
) => {
  if (action === 'add') {
    const newTabName = `${++tabIndex}`
    editableTabs.value.push({
      title: 'New Tab',
      name: newTabName,
      content: 'New Tab content',
    })
    editableTabsValue.value = newTabName
  } else if (action === 'remove') {
    const tabs = editableTabs.value
    let activeName = editableTabsValue.value
    if (activeName === targetName) {
      tabs.forEach((tab, index) => {
        if (tab.name === targetName) {
          const nextTab = tabs[index + 1] || tabs[index - 1]
          if (nextTab) {
            activeName = nextTab.name
          }
        }
      })
    }

    editableTabsValue.value = activeName
    editableTabs.value = tabs.filter((tab) => tab.name !== targetName)
  }
}
</script>

<style>
.demo-tabs > .el-tabs__content {
  padding: 32px;
  color: #6b778c;
  font-size: 32px;
  font-weight: 600;
}
</style>
```

隐藏源代码

## 增加标签页触发器自定义 [​](#增加标签页触发器自定义)

add tab

Tab 1

Tab 2

Tab 1 content

Tab 2 content

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwibWFyZ2luLWJvdHRvbTogMjBweFwiPlxuICAgIDxlbC1idXR0b24gc2l6ZT1cInNtYWxsXCIgQGNsaWNrPVwiYWRkVGFiKGVkaXRhYmxlVGFic1ZhbHVlKVwiPlxuICAgICAgYWRkIHRhYlxuICAgIDwvZWwtYnV0dG9uPlxuICA8L2Rpdj5cbiAgPGVsLXRhYnNcbiAgICB2LW1vZGVsPVwiZWRpdGFibGVUYWJzVmFsdWVcIlxuICAgIHR5cGU9XCJjYXJkXCJcbiAgICBjbGFzcz1cImRlbW8tdGFic1wiXG4gICAgY2xvc2FibGVcbiAgICBAdGFiLXJlbW92ZT1cInJlbW92ZVRhYlwiXG4gID5cbiAgICA8ZWwtdGFiLXBhbmVcbiAgICAgIHYtZm9yPVwiaXRlbSBpbiBlZGl0YWJsZVRhYnNcIlxuICAgICAgOmtleT1cIml0ZW0ubmFtZVwiXG4gICAgICA6bGFiZWw9XCJpdGVtLnRpdGxlXCJcbiAgICAgIDpuYW1lPVwiaXRlbS5uYW1lXCJcbiAgICA+XG4gICAgICB7eyBpdGVtLmNvbnRlbnQgfX1cbiAgICA8L2VsLXRhYi1wYW5lPlxuICA8L2VsLXRhYnM+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IFRhYlBhbmVOYW1lIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5sZXQgdGFiSW5kZXggPSAyXG5jb25zdCBlZGl0YWJsZVRhYnNWYWx1ZSA9IHJlZignMicpXG5jb25zdCBlZGl0YWJsZVRhYnMgPSByZWYoW1xuICB7XG4gICAgdGl0bGU6ICdUYWIgMScsXG4gICAgbmFtZTogJzEnLFxuICAgIGNvbnRlbnQ6ICdUYWIgMSBjb250ZW50JyxcbiAgfSxcbiAge1xuICAgIHRpdGxlOiAnVGFiIDInLFxuICAgIG5hbWU6ICcyJyxcbiAgICBjb250ZW50OiAnVGFiIDIgY29udGVudCcsXG4gIH0sXG5dKVxuXG5jb25zdCBhZGRUYWIgPSAodGFyZ2V0TmFtZTogc3RyaW5nKSA9PiB7XG4gIGNvbnN0IG5ld1RhYk5hbWUgPSBgJHsrK3RhYkluZGV4fWBcbiAgZWRpdGFibGVUYWJzLnZhbHVlLnB1c2goe1xuICAgIHRpdGxlOiAnTmV3IFRhYicsXG4gICAgbmFtZTogbmV3VGFiTmFtZSxcbiAgICBjb250ZW50OiAnTmV3IFRhYiBjb250ZW50JyxcbiAgfSlcbiAgZWRpdGFibGVUYWJzVmFsdWUudmFsdWUgPSBuZXdUYWJOYW1lXG59XG5jb25zdCByZW1vdmVUYWIgPSAodGFyZ2V0TmFtZTogVGFiUGFuZU5hbWUpID0+IHtcbiAgY29uc3QgdGFicyA9IGVkaXRhYmxlVGFicy52YWx1ZVxuICBsZXQgYWN0aXZlTmFtZSA9IGVkaXRhYmxlVGFic1ZhbHVlLnZhbHVlXG4gIGlmIChhY3RpdmVOYW1lID09PSB0YXJnZXROYW1lKSB7XG4gICAgdGFicy5mb3JFYWNoKCh0YWIsIGluZGV4KSA9PiB7XG4gICAgICBpZiAodGFiLm5hbWUgPT09IHRhcmdldE5hbWUpIHtcbiAgICAgICAgY29uc3QgbmV4dFRhYiA9IHRhYnNbaW5kZXggKyAxXSB8fCB0YWJzW2luZGV4IC0gMV1cbiAgICAgICAgaWYgKG5leHRUYWIpIHtcbiAgICAgICAgICBhY3RpdmVOYW1lID0gbmV4dFRhYi5uYW1lXG4gICAgICAgIH1cbiAgICAgIH1cbiAgICB9KVxuICB9XG5cbiAgZWRpdGFibGVUYWJzVmFsdWUudmFsdWUgPSBhY3RpdmVOYW1lXG4gIGVkaXRhYmxlVGFicy52YWx1ZSA9IHRhYnMuZmlsdGVyKCh0YWIpID0+IHRhYi5uYW1lICE9PSB0YXJnZXROYW1lKVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5kZW1vLXRhYnMgPiAuZWwtdGFic19fY29udGVudCB7XG4gIHBhZGRpbmc6IDMycHg7XG4gIGNvbG9yOiAjNmI3NzhjO1xuICBmb250LXNpemU6IDMycHg7XG4gIGZvbnQtd2VpZ2h0OiA2MDA7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tabs/customized-trigger.vue)_

vue

```
<template>
  <div style="margin-bottom: 20px">
    <el-button size="small" @click="addTab(editableTabsValue)">
      add tab
    </el-button>
  </div>
  <el-tabs
    v-model="editableTabsValue"
    type="card"
    class="demo-tabs"
    closable
    @tab-remove="removeTab"
  >
    <el-tab-pane
      v-for="item in editableTabs"
      :key="item.name"
      :label="item.title"
      :name="item.name"
    >
      {{ item.content }}
    </el-tab-pane>
  </el-tabs>
</template>

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

import type { TabPaneName } from 'element-plus'

let tabIndex = 2
const editableTabsValue = ref('2')
const editableTabs = ref([
  {
    title: 'Tab 1',
    name: '1',
    content: 'Tab 1 content',
  },
  {
    title: 'Tab 2',
    name: '2',
    content: 'Tab 2 content',
  },
])

const addTab = (targetName: string) => {
  const newTabName = `${++tabIndex}`
  editableTabs.value.push({
    title: 'New Tab',
    name: newTabName,
    content: 'New Tab content',
  })
  editableTabsValue.value = newTabName
}
const removeTab = (targetName: TabPaneName) => {
  const tabs = editableTabs.value
  let activeName = editableTabsValue.value
  if (activeName === targetName) {
    tabs.forEach((tab, index) => {
      if (tab.name === targetName) {
        const nextTab = tabs[index + 1] || tabs[index - 1]
        if (nextTab) {
          activeName = nextTab.name
        }
      }
    })
  }

  editableTabsValue.value = activeName
  editableTabs.value = tabs.filter((tab) => tab.name !== targetName)
}
</script>

<style>
.demo-tabs > .el-tabs__content {
  padding: 32px;
  color: #6b778c;
  font-size: 32px;
  font-weight: 600;
}
</style>
```

隐藏源代码

## 默认值2.11.9 [​](#默认值)

User

Config

Role

Task

default-value: third
active:

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFic1xuICAgIHYtbW9kZWw9XCJhY3RpdmVOYW1lXCJcbiAgICBjbGFzcz1cImRlbW8tdGFic1wiXG4gICAgZGVmYXVsdC12YWx1ZT1cInRoaXJkXCJcbiAgICBAdGFiLWNsaWNrPVwiaGFuZGxlQ2xpY2tcIlxuICA+XG4gICAgPGVsLXRhYi1wYW5lXG4gICAgICB2LWZvcj1cInRhYiBpbiB0YWJzXCJcbiAgICAgIDprZXk9XCJ0YWIubmFtZVwiXG4gICAgICA6bGFiZWw9XCJ0YWIubGFiZWxcIlxuICAgICAgOm5hbWU9XCJ0YWIubmFtZVwiXG4gICAgPlxuICAgICAgZGVmYXVsdC12YWx1ZTogdGhpcmRcbiAgICAgIDxiciAvPlxuICAgICAgYWN0aXZlOiB7eyBhY3RpdmVOYW1lIH19XG4gICAgPC9lbC10YWItcGFuZT5cbiAgPC9lbC10YWJzPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBUYWJzUGFuZUNvbnRleHQgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IHRhYnMgPSByZWYoW1xuICB7IGxhYmVsOiAnVXNlcicsIG5hbWU6ICdmaXJzdCcgfSxcbiAgeyBsYWJlbDogJ0NvbmZpZycsIG5hbWU6ICdzZWNvbmQnIH0sXG4gIHsgbGFiZWw6ICdSb2xlJywgbmFtZTogJ3RoaXJkJyB9LFxuICB7IGxhYmVsOiAnVGFzaycsIG5hbWU6ICdmb3VydGgnIH0sXG5dKVxuXG5jb25zdCBhY3RpdmVOYW1lID0gcmVmKClcblxuY29uc3QgaGFuZGxlQ2xpY2sgPSAodGFiOiBUYWJzUGFuZUNvbnRleHQsIGV2ZW50OiBFdmVudCkgPT4ge1xuICBjb25zb2xlLmxvZyh0YWIsIGV2ZW50KVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5kZW1vLXRhYnMgPiAuZWwtdGFic19fY29udGVudCB7XG4gIHBhZGRpbmc6IDMycHg7XG4gIGNvbG9yOiAjNmI3NzhjO1xuICBmb250LXNpemU6IDMycHg7XG4gIGZvbnQtd2VpZ2h0OiA2MDA7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tabs/default-value.vue)_

vue

```
<template>
  <el-tabs
    v-model="activeName"
    class="demo-tabs"
    default-value="third"
    @tab-click="handleClick"
  >
    <el-tab-pane
      v-for="tab in tabs"
      :key="tab.name"
      :label="tab.label"
      :name="tab.name"
    >
      default-value: third
      <br />
      active: {{ activeName }}
    </el-tab-pane>
  </el-tabs>
</template>

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

import type { TabsPaneContext } from 'element-plus'

const tabs = ref([
  { label: 'User', name: 'first' },
  { label: 'Config', name: 'second' },
  { label: 'Role', name: 'third' },
  { label: 'Task', name: 'fourth' },
])

const activeName = ref()

const handleClick = (tab: TabsPaneContext, event: Event) => {
  console.log(tab, event)
}
</script>

<style>
.demo-tabs > .el-tabs__content {
  padding: 32px;
  color: #6b778c;
  font-size: 32px;
  font-weight: 600;
}
</style>
```

隐藏源代码

## Tabs API [​](#tabs-api)

### Tabs Attributes [​](#tabs-attributes)

| 属性名 | 说明 | 类型 | Default |
| --- | --- | --- | --- |
| model-value / v-model | 绑定值，选中选项卡的 name，默认值是第一个 tab 的 name | `string` / `number` | — |
| default-value 2.11.9 | 在初始渲染时处于激活状态的标签的值。 （避免初始化时变动） | `string` / `number` |  |
| type | 风格类型 | `enum` | '' |
| closable | 标签是否可关闭 | `boolean` | false |
| addable | 标签是否可增加 | `boolean` | false |
| editable | 标签是否同时可增加和关闭 | `boolean` | false |
| tab-position | 选项卡所在位置 | `enum` | top |
| stretch | 标签的宽度是否自撑开 | `boolean` | false |
| before-leave | 切换标签之前的钩子函数， 若返回 `false` 或者返回被 reject 的 `Promise`，则阻止切换。 | `Function` | () => true |
| tabindex 2.11.7 | tabs 的 tabindex | `string` / `number` | 0 |

### Tabs Events [​](#tabs-events)

| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| tab-click | tab 被选中时触发 | `Function` |
| tab-change | `activeName` 改变时触发 | `Function` |
| tab-remove | 点击 tab 移除按钮时触发 | `Function` |
| tab-add | 点击 tab 新增按钮时触发 | `Function` |
| edit | 点击 tab 的新增或移除按钮后触发 | `Function` |

### Tabs Slots [​](#tabs-slots)

| 插槽名 | 说明 | 子标签 |
| --- | --- | --- |
| default | 默认插槽 | Tab-pane |
| add-icon 2.5.4 | 自定义添加按钮图标 | — |
| addIcon 2.4.0 deprecated | 自定义添加按钮图标 | — |

### Tabs Exposes [​](#tabs-exposes)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| currentName | 当前活动的面板名称 | `object` |
| tabNavRef 2.9.10 | tab-nav 组件实例 | `object` |

## Tab-nav API [​](#tab-nav-api)

### Tab-nav Exposes [​](#tab-nav-exposes)

| 方法名 | 说明 | 类型 |
| --- | --- | --- |
| scrollToActiveTab | 滚动到活动标签 | `Function` |
| removeFocus | 移除聚焦状态 | `Function` |
| tabListRef 2.9.10 | el\_tabs\_\_nav html 元素 | `object` |
| tabBarRef 2.9.10 | el\_tabs\_\_nav bar 实例 | `object` |

## Tab-bar API [​](#tab-bar-api)

### Tab-bar Exposes [​](#tab-bar-exposes)

| 属性名 | 详情 | 类型 |
| --- | --- | --- |
| ref 2.9.10 | 选项卡根 HTML 元素 | `object` |
| update 2.9.10 | 手动更新标签栏样式的方法，返回更新后的样式 | `Function` |

## Tab-pane API [​](#tab-pane-api)

### Tab-pane Attributes [​](#tab-pane-attributes)

| 名称 | 详情 | Type | 默认值 |
| --- | --- | --- | --- |
| label | 选项卡标题 | `string` | '' |
| disabled | 是否禁用 | `boolean` | false |
| name | 与选项卡绑定值 value 对应的标识符，表示选项卡别名。默认值是tab面板的序列号，如第一个 tab 是 0 | `string` / `number` | — |
| closable | 标签是否可关闭 | `boolean` | false |
| lazy | 标签是否延迟渲染 | `boolean` | false |

### Tab-pane Slots [​](#tab-pane-slots)

| Name | Description |
| --- | --- |
| default | Tab-pane 的内容 |
| label | Tab-pane 的标题内容 |

## 常见问题 [​](#常见问题)

#### 如何使用可排序/可拖动的 tabs？ [​](#如何使用可排序-可拖动的-tabs)

我们已对外暴露了实现该功能所需的必要能力。 您可以查看 [示例](https://tinyurl.com/2jkyw82j) 来用原生的方式实现。 或使用 [SortableJs](https://github.com/SortableJS/Sortable), [示例](https://tinyurl.com/2r8js24y)。

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/tabs) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/tabs.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/tabs.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/33254923?v=4&size=64)](https://github.com/yicheny)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/57785259?v=4&size=64)](https://github.com/w2xi)[![](https://avatars.githubusercontent.com/u/9784767?v=4&size=64)](https://github.com/maicss)[![](https://avatars.githubusercontent.com/u/8479810?v=4&size=64)](https://github.com/xinconan)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/43257608?v=4&size=64)](https://github.com/Liao-js)[![](https://avatars.githubusercontent.com/u/129492349?v=4&size=64)](https://github.com/Yolo-00)[![](https://avatars.githubusercontent.com/u/42017165?v=4&size=64)](https://github.com/Mario34)[![](https://avatars.githubusercontent.com/u/1532716?v=4&size=64)](https://github.com/godxiaoji)[![](https://avatars.githubusercontent.com/u/48897151?v=4&size=64)](https://github.com/RadiumAg)[![](https://avatars.githubusercontent.com/u/44231913?v=4&size=64)](https://github.com/THUzxj)[![](https://avatars.githubusercontent.com/u/26913795?v=4&size=64)](https://github.com/Lionad-Morotar)[![](https://avatars.githubusercontent.com/u/20185706?v=4&size=64)](https://github.com/xiahouwei)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)[![](https://avatars.githubusercontent.com/u/45936772?v=4&size=64)](https://github.com/KawaiiZapic)[![](https://avatars.githubusercontent.com/u/1321817?v=4&size=64)](https://github.com/oliverzy)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/34835258?v=4&size=64)](https://github.com/codingories)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/5283258?v=4&size=64)](https://github.com/satrong)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/36768323?v=4&size=64)](https://github.com/bigsnowballhehe)[![](https://avatars.githubusercontent.com/u/53803716?v=4&size=64)](https://github.com/MrpandaLiu)[![](https://avatars.githubusercontent.com/u/36811055?v=4&size=64)](https://github.com/iDestin)[![](https://avatars.githubusercontent.com/u/33464433?v=4&size=64)](https://github.com/cfmj)

[Steps 步骤条](https://element-plus.org/zh-CN/component/steps)

[Alert 提示](https://element-plus.org/zh-CN/component/alert)




---

<!-- ============================================ -->
<!-- 类别: 反馈组件 -->
<!-- ============================================ -->

## [feedback/alert] Alert 提示
> 官方文档: https://element-plus.org/zh-CN/component/alert.html

---

# Alert 提示 [​](#alert-提示)

更新日志待解决

0

用于页面中展示重要的提示信息。

## 基础用法 [​](#基础用法)

Alert 组件不属于浮层元素，不会自动消失或关闭。

Alert 组件提供5种类型，由 `type` 属性指定，默认值为 `info`。 `primary` 已被添加到2.9.11。

Primary alert

Success alert

Info alert

Warning alert

Error alert

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIlByaW1hcnkgYWxlcnRcIiB0eXBlPVwicHJpbWFyeVwiIC8+XG4gICAgPGVsLWFsZXJ0IHRpdGxlPVwiU3VjY2VzcyBhbGVydFwiIHR5cGU9XCJzdWNjZXNzXCIgLz5cbiAgICA8ZWwtYWxlcnQgdGl0bGU9XCJJbmZvIGFsZXJ0XCIgdHlwZT1cImluZm9cIiAvPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIldhcm5pbmcgYWxlcnRcIiB0eXBlPVwid2FybmluZ1wiIC8+XG4gICAgPGVsLWFsZXJ0IHRpdGxlPVwiRXJyb3IgYWxlcnRcIiB0eXBlPVwiZXJyb3JcIiAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZWwtYWxlcnQge1xuICBtYXJnaW46IDIwcHggMCAwO1xufVxuLmVsLWFsZXJ0OmZpcnN0LWNoaWxkIHtcbiAgbWFyZ2luOiAwO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/alert/basic.vue)_

vue

```
<template>
  <div style="max-width: 600px">
    <el-alert title="Primary alert" type="primary" />
    <el-alert title="Success alert" type="success" />
    <el-alert title="Info alert" type="info" />
    <el-alert title="Warning alert" type="warning" />
    <el-alert title="Error alert" type="error" />
  </div>
</template>

<style scoped>
.el-alert {
  margin: 20px 0 0;
}
.el-alert:first-child {
  margin: 0;
}
</style>
```

隐藏源代码

## 主题 [​](#主题)

Alert 组件提供了两个不同的主题：`light` 和 `dark`。

通过设置 `effect` 属性来改变主题，默认为 `light`。

Primary alert

Success alert

Info alert

Warning alert

Error alert

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIlByaW1hcnkgYWxlcnRcIiB0eXBlPVwicHJpbWFyeVwiIGVmZmVjdD1cImRhcmtcIiAvPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIlN1Y2Nlc3MgYWxlcnRcIiB0eXBlPVwic3VjY2Vzc1wiIGVmZmVjdD1cImRhcmtcIiAvPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIkluZm8gYWxlcnRcIiB0eXBlPVwiaW5mb1wiIGVmZmVjdD1cImRhcmtcIiAvPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIldhcm5pbmcgYWxlcnRcIiB0eXBlPVwid2FybmluZ1wiIGVmZmVjdD1cImRhcmtcIiAvPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIkVycm9yIGFsZXJ0XCIgdHlwZT1cImVycm9yXCIgZWZmZWN0PVwiZGFya1wiIC8+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlIHNjb3BlZD5cbi5lbC1hbGVydCB7XG4gIG1hcmdpbjogMjBweCAwIDA7XG59XG4uZWwtYWxlcnQ6Zmlyc3QtY2hpbGQge1xuICBtYXJnaW46IDA7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/alert/theme.vue)_

vue

```
<template>
  <div style="max-width: 600px">
    <el-alert title="Primary alert" type="primary" effect="dark" />
    <el-alert title="Success alert" type="success" effect="dark" />
    <el-alert title="Info alert" type="info" effect="dark" />
    <el-alert title="Warning alert" type="warning" effect="dark" />
    <el-alert title="Error alert" type="error" effect="dark" />
  </div>
</template>

<style scoped>
.el-alert {
  margin: 20px 0 0;
}
.el-alert:first-child {
  margin: 0;
}
</style>
```

隐藏源代码

## 自定义关闭按钮 [​](#自定义关闭按钮)

你可以自定义关闭按钮为文字或其他符号。

你可以设置 Alert 组件是否为可关闭状态， 关闭按钮的内容以及关闭时的回调函数同样可以定制。 `closable` 属性决定 Alert 组件是否可关闭， 该属性接受一个 `Boolean`，默认为 `false`。 你可以设置 `close-text` 属性来代替右侧的关闭图标， 需要注意的是 `close-text` 必须是一个字符串。 当 Alert 组件被关闭时会触发 `close` 事件。

Unclosable alert

Customized close text

Gotcha

Alert with callback

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIlVuY2xvc2FibGUgYWxlcnRcIiB0eXBlPVwic3VjY2Vzc1wiIDpjbG9zYWJsZT1cImZhbHNlXCIgLz5cbiAgICA8ZWwtYWxlcnQgdGl0bGU9XCJDdXN0b21pemVkIGNsb3NlIHRleHRcIiB0eXBlPVwiaW5mb1wiIGNsb3NlLXRleHQ9XCJHb3RjaGFcIiAvPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIkFsZXJ0IHdpdGggY2FsbGJhY2tcIiB0eXBlPVwid2FybmluZ1wiIEBjbG9zZT1cImhlbGxvXCIgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuY29uc3QgaGVsbG8gPSAoKSA9PiB7XG4gIC8vIGVzbGludC1kaXNhYmxlLW5leHQtbGluZSBuby1hbGVydFxuICBhbGVydCgnSGVsbG8gV29ybGQhJylcbn1cbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmVsLWFsZXJ0IHtcbiAgbWFyZ2luOiAyMHB4IDAgMDtcbn1cbi5lbC1hbGVydDpmaXJzdC1jaGlsZCB7XG4gIG1hcmdpbjogMDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/alert/close-button.vue)_

vue

```
<template>
  <div style="max-width: 600px">
    <el-alert title="Unclosable alert" type="success" :closable="false" />
    <el-alert title="Customized close text" type="info" close-text="Gotcha" />
    <el-alert title="Alert with callback" type="warning" @close="hello" />
  </div>
</template>

<script lang="ts" setup>
const hello = () => {
  // eslint-disable-next-line no-alert
  alert('Hello World!')
}
</script>

<style scoped>
.el-alert {
  margin: 20px 0 0;
}
.el-alert:first-child {
  margin: 0;
}
</style>
```

隐藏源代码

## 使用图标 [​](#使用图标)

你可以通过为 Alert 组件添加图标来提高可读性。

通过设置 `show-icon` 属性来显示 Alert 的 icon，这能更有效地向用户展示你的显示意图。 或者你可以使用 `icon` slot 自定义 icon 内容。

Primary alert

Success alert

Info alert

Warning alert

Error alert

Error alert with custom icon

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIlByaW1hcnkgYWxlcnRcIiB0eXBlPVwicHJpbWFyeVwiIHNob3ctaWNvbiAvPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIlN1Y2Nlc3MgYWxlcnRcIiB0eXBlPVwic3VjY2Vzc1wiIHNob3ctaWNvbiAvPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIkluZm8gYWxlcnRcIiB0eXBlPVwiaW5mb1wiIHNob3ctaWNvbiAvPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIldhcm5pbmcgYWxlcnRcIiB0eXBlPVwid2FybmluZ1wiIHNob3ctaWNvbiAvPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIkVycm9yIGFsZXJ0XCIgdHlwZT1cImVycm9yXCIgc2hvdy1pY29uIC8+XG4gICAgPGVsLWFsZXJ0IHRpdGxlPVwiRXJyb3IgYWxlcnQgd2l0aCBjdXN0b20gaWNvblwiIHR5cGU9XCJlcnJvclwiIHNob3ctaWNvbj5cbiAgICAgIDx0ZW1wbGF0ZSAjaWNvbj5cbiAgICAgICAgPEJlbGwgLz5cbiAgICAgIDwvdGVtcGxhdGU+XG4gICAgPC9lbC1hbGVydD5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgQmVsbCB9IGZyb20gJ0BlbGVtZW50LXBsdXMvaWNvbnMtdnVlJ1xuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZWwtYWxlcnQge1xuICBtYXJnaW46IDIwcHggMCAwO1xufVxuLmVsLWFsZXJ0OmZpcnN0LWNoaWxkIHtcbiAgbWFyZ2luOiAwO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/alert/icon.vue)_

vue

```
<template>
  <div style="max-width: 600px">
    <el-alert title="Primary alert" type="primary" show-icon />
    <el-alert title="Success alert" type="success" show-icon />
    <el-alert title="Info alert" type="info" show-icon />
    <el-alert title="Warning alert" type="warning" show-icon />
    <el-alert title="Error alert" type="error" show-icon />
    <el-alert title="Error alert with custom icon" type="error" show-icon>
      <template #icon>
        <Bell />
      </template>
    </el-alert>
  </div>
</template>

<script lang="ts" setup>
import { Bell } from '@element-plus/icons-vue'
</script>

<style scoped>
.el-alert {
  margin: 20px 0 0;
}
.el-alert:first-child {
  margin: 0;
}
</style>
```

隐藏源代码

## 文字居中 [​](#文字居中)

使用 `center` 属性来让文字水平居中。

Primary alert

Success alert

Info alert

Warning alert

Error alert

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIlByaW1hcnkgYWxlcnRcIiB0eXBlPVwicHJpbWFyeVwiIGNlbnRlciBzaG93LWljb24gLz5cbiAgICA8ZWwtYWxlcnQgdGl0bGU9XCJTdWNjZXNzIGFsZXJ0XCIgdHlwZT1cInN1Y2Nlc3NcIiBjZW50ZXIgc2hvdy1pY29uIC8+XG4gICAgPGVsLWFsZXJ0IHRpdGxlPVwiSW5mbyBhbGVydFwiIHR5cGU9XCJpbmZvXCIgY2VudGVyIHNob3ctaWNvbiAvPlxuICAgIDxlbC1hbGVydCB0aXRsZT1cIldhcm5pbmcgYWxlcnRcIiB0eXBlPVwid2FybmluZ1wiIGNlbnRlciBzaG93LWljb24gLz5cbiAgICA8ZWwtYWxlcnQgdGl0bGU9XCJFcnJvciBhbGVydFwiIHR5cGU9XCJlcnJvclwiIGNlbnRlciBzaG93LWljb24gLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c3R5bGUgc2NvcGVkPlxuLmVsLWFsZXJ0IHtcbiAgbWFyZ2luOiAyMHB4IDAgMDtcbn1cbi5lbC1hbGVydDpmaXJzdC1jaGlsZCB7XG4gIG1hcmdpbjogMDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/alert/center.vue)_

vue

```
<template>
  <div style="max-width: 600px">
    <el-alert title="Primary alert" type="primary" center show-icon />
    <el-alert title="Success alert" type="success" center show-icon />
    <el-alert title="Info alert" type="info" center show-icon />
    <el-alert title="Warning alert" type="warning" center show-icon />
    <el-alert title="Error alert" type="error" center show-icon />
  </div>
</template>

<style scoped>
.el-alert {
  margin: 20px 0 0;
}
.el-alert:first-child {
  margin: 0;
}
</style>
```

隐藏源代码

## 文字描述 [​](#文字描述)

为 Alert 组件添加一个更加详细的描述来使用户了解更多信息。

除了必填的 `title` 属性外，你可以设置 `description` 属性来帮助你更好地介绍，我们称之为辅助性文字。 辅助性文字只能存放文本内容，当内容超出长度限制时会自动换行显示。

With description

This is a description.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiPlxuICAgIDxlbC1hbGVydFxuICAgICAgdGl0bGU9XCJXaXRoIGRlc2NyaXB0aW9uXCJcbiAgICAgIHR5cGU9XCJzdWNjZXNzXCJcbiAgICAgIGRlc2NyaXB0aW9uPVwiVGhpcyBpcyBhIGRlc2NyaXB0aW9uLlwiXG4gICAgLz5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/alert/description.vue)_

vue

```
<template>
  <div style="max-width: 600px">
    <el-alert
      title="With description"
      type="success"
      description="This is a description."
    />
  </div>
</template>
```

隐藏源代码

## 带图标和描述 [​](#带图标和描述)

在最后, 这是一个带有图标和描述的例子。

Primary alert

More text description

Success alert

More text description

Info alert

More text description

Warning alert

More text description

Error alert

More text description

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwibWF4LXdpZHRoOiA2MDBweFwiPlxuICAgIDxlbC1hbGVydFxuICAgICAgdGl0bGU9XCJQcmltYXJ5IGFsZXJ0XCJcbiAgICAgIHR5cGU9XCJwcmltYXJ5XCJcbiAgICAgIGRlc2NyaXB0aW9uPVwiTW9yZSB0ZXh0IGRlc2NyaXB0aW9uXCJcbiAgICAgIHNob3ctaWNvblxuICAgIC8+XG4gICAgPGVsLWFsZXJ0XG4gICAgICB0aXRsZT1cIlN1Y2Nlc3MgYWxlcnRcIlxuICAgICAgdHlwZT1cInN1Y2Nlc3NcIlxuICAgICAgZGVzY3JpcHRpb249XCJNb3JlIHRleHQgZGVzY3JpcHRpb25cIlxuICAgICAgc2hvdy1pY29uXG4gICAgLz5cbiAgICA8ZWwtYWxlcnRcbiAgICAgIHRpdGxlPVwiSW5mbyBhbGVydFwiXG4gICAgICB0eXBlPVwiaW5mb1wiXG4gICAgICBkZXNjcmlwdGlvbj1cIk1vcmUgdGV4dCBkZXNjcmlwdGlvblwiXG4gICAgICBzaG93LWljb25cbiAgICAvPlxuICAgIDxlbC1hbGVydFxuICAgICAgdGl0bGU9XCJXYXJuaW5nIGFsZXJ0XCJcbiAgICAgIHR5cGU9XCJ3YXJuaW5nXCJcbiAgICAgIGRlc2NyaXB0aW9uPVwiTW9yZSB0ZXh0IGRlc2NyaXB0aW9uXCJcbiAgICAgIHNob3ctaWNvblxuICAgIC8+XG4gICAgPGVsLWFsZXJ0XG4gICAgICB0aXRsZT1cIkVycm9yIGFsZXJ0XCJcbiAgICAgIHR5cGU9XCJlcnJvclwiXG4gICAgICBkZXNjcmlwdGlvbj1cIk1vcmUgdGV4dCBkZXNjcmlwdGlvblwiXG4gICAgICBzaG93LWljb25cbiAgICAvPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+PC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4uZWwtYWxlcnQge1xuICBtYXJnaW46IDIwcHggMCAwO1xufVxuLmVsLWFsZXJ0OmZpcnN0LWNoaWxkIHtcbiAgbWFyZ2luOiAwO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/alert/icon-description.vue)_

vue

```
<template>
  <div style="max-width: 600px">
    <el-alert
      title="Primary alert"
      type="primary"
      description="More text description"
      show-icon
    />
    <el-alert
      title="Success alert"
      type="success"
      description="More text description"
      show-icon
    />
    <el-alert
      title="Info alert"
      type="info"
      description="More text description"
      show-icon
    />
    <el-alert
      title="Warning alert"
      type="warning"
      description="More text description"
      show-icon
    />
    <el-alert
      title="Error alert"
      type="error"
      description="More text description"
      show-icon
    />
  </div>
</template>

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

<style scoped>
.el-alert {
  margin: 20px 0 0;
}
.el-alert:first-child {
  margin: 0;
}
</style>
```

隐藏源代码

## Alert API [​](#alert-api)

### 属性 [​](#属性)

| 名称 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| title | Alert 标题。 | `string` | — |
| type | Alert 类型。 | `enum` | info |
| description | 描述性文本 | `string` | — |
| closable | 是否可以关闭 | `boolean` | true |
| center | 文字是否居中 | ::: | false |
| close-text | 自定义关闭按钮文本 | `string` | — |
| show-icon | 是否显示类型图标 | `boolean` | false |
| effect | 主题样式 | `enum` | light |

### Events [​](#events)

| 名称 | 描述 | 类型 |
| --- | --- | --- |
| close | 关闭 Alert 时触发的事件 | `Function` |

### Slots [​](#slots)

| 名称 | 描述 |
| --- | --- |
| default | Alert 内容描述 |
| title | 标题的内容 |
| icon 2.9.7 | icon 的内容 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/alert) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/alert.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/alert.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/8479810?v=4&size=64)](https://github.com/xinconan)[![](https://avatars.githubusercontent.com/u/21235555?v=4&size=64)](https://github.com/zhangenming)[![](https://avatars.githubusercontent.com/u/109908413?v=4&size=64)](https://github.com/sleepyShen1989)[![](https://avatars.githubusercontent.com/u/32354856?v=4&size=64)](https://github.com/baiwusanyu-c)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/20987775?v=4&size=64)](https://github.com/cbbfcd)[![](https://avatars.githubusercontent.com/u/134276765?v=4&size=64)](https://github.com/zwgwf)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/36007710?v=4&size=64)](https://github.com/sleepyfive)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)

[Tabs 标签页](https://element-plus.org/zh-CN/component/tabs)

[Dialog 对话框](https://element-plus.org/zh-CN/component/dialog)




---
## [feedback/dialog] Dialog 对话框
> 官方文档: https://element-plus.org/zh-CN/component/dialog.html

---

# Dialog 对话框 [​](#dialog-对话框)

更新日志待解决

28

在保留当前页面状态的情况下，告知用户并承载相关操作。

## 基础用法 [​](#基础用法)

Dialog 弹出一个对话框，适合需要定制性更大的场景。

需要设置 `model-value / v-model` 属性，它接收 `Boolean`，当为 `true` 时显示 Dialog。 Dialog 分为两个部分：`body` 和 `footer`，`footer` 需要具名为 `footer` 的 `slot`。 `title` 属性用于定义标题，它是可选的，默认值为空。 最后，本例还展示了 `before-close` 的用法。

Click to open the Dialog

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cImRpYWxvZ1Zpc2libGUgPSB0cnVlXCI+XG4gICAgQ2xpY2sgdG8gb3BlbiB0aGUgRGlhbG9nXG4gIDwvZWwtYnV0dG9uPlxuXG4gIDxlbC1kaWFsb2dcbiAgICB2LW1vZGVsPVwiZGlhbG9nVmlzaWJsZVwiXG4gICAgdGl0bGU9XCJUaXBzXCJcbiAgICB3aWR0aD1cIjUwMFwiXG4gICAgOmJlZm9yZS1jbG9zZT1cImhhbmRsZUNsb3NlXCJcbiAgPlxuICAgIDxzcGFuPlRoaXMgaXMgYSBtZXNzYWdlPC9zcGFuPlxuICAgIDx0ZW1wbGF0ZSAjZm9vdGVyPlxuICAgICAgPGRpdiBjbGFzcz1cImRpYWxvZy1mb290ZXJcIj5cbiAgICAgICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJkaWFsb2dWaXNpYmxlID0gZmFsc2VcIj5DYW5jZWw8L2VsLWJ1dHRvbj5cbiAgICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiIEBjbGljaz1cImRpYWxvZ1Zpc2libGUgPSBmYWxzZVwiPlxuICAgICAgICAgIENvbmZpcm1cbiAgICAgICAgPC9lbC1idXR0b24+XG4gICAgICA8L2Rpdj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLWRpYWxvZz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBFbE1lc3NhZ2VCb3ggfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGRpYWxvZ1Zpc2libGUgPSByZWYoZmFsc2UpXG5cbmNvbnN0IGhhbmRsZUNsb3NlID0gKGRvbmU6ICgpID0+IHZvaWQpID0+IHtcbiAgRWxNZXNzYWdlQm94LmNvbmZpcm0oJ0FyZSB5b3Ugc3VyZSB0byBjbG9zZSB0aGlzIGRpYWxvZz8nKVxuICAgIC50aGVuKCgpID0+IHtcbiAgICAgIGRvbmUoKVxuICAgIH0pXG4gICAgLmNhdGNoKCgpID0+IHtcbiAgICAgIC8vIGNhdGNoIGVycm9yXG4gICAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/basic-usage.vue)_

vue

```
<template>
  <el-button plain @click="dialogVisible = true">
    Click to open the Dialog
  </el-button>

  <el-dialog
    v-model="dialogVisible"
    title="Tips"
    width="500"
    :before-close="handleClose"
  >
    <span>This is a message</span>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="dialogVisible = false">Cancel</el-button>
        <el-button type="primary" @click="dialogVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElMessageBox } from 'element-plus'

const dialogVisible = ref(false)

const handleClose = (done: () => void) => {
  ElMessageBox.confirm('Are you sure to close this dialog?')
    .then(() => {
      done()
    })
    .catch(() => {
      // catch error
    })
}
</script>
```

隐藏源代码

TIP

`before-close` 只会在用户点击关闭按钮或者对话框的遮罩区域时被调用。 如果你在 `footer` 具名 slot 里添加了用于关闭 Dialog 的按钮，那么可以在按钮的点击回调函数里加入 `before-close` 的相关逻辑。

## 自定义内容 [​](#自定义内容)

对话框的内容可以是任何东西，甚至是一个表格或表单。 此示例显示如何在 Dialog 中使用 Element Plus 的表格和表单。

Open a Table nested Dialog Open a Form nested Dialog

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJkaWFsb2dUYWJsZVZpc2libGUgPSB0cnVlXCI+XG4gICAgICBPcGVuIGEgVGFibGUgbmVzdGVkIERpYWxvZ1xuICAgIDwvZWwtYnV0dG9uPlxuXG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgcGxhaW4gQGNsaWNrPVwiZGlhbG9nRm9ybVZpc2libGUgPSB0cnVlXCI+XG4gICAgICBPcGVuIGEgRm9ybSBuZXN0ZWQgRGlhbG9nXG4gICAgPC9lbC1idXR0b24+XG4gIDwvZGl2PlxuXG4gIDxlbC1kaWFsb2cgdi1tb2RlbD1cImRpYWxvZ1RhYmxlVmlzaWJsZVwiIHRpdGxlPVwiU2hpcHBpbmcgYWRkcmVzc1wiIHdpZHRoPVwiODAwXCI+XG4gICAgPGVsLXRhYmxlIDpkYXRhPVwiZ3JpZERhdGFcIj5cbiAgICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcGVydHk9XCJkYXRlXCIgbGFiZWw9XCJEYXRlXCIgd2lkdGg9XCIxNTBcIiAvPlxuICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wZXJ0eT1cIm5hbWVcIiBsYWJlbD1cIk5hbWVcIiB3aWR0aD1cIjIwMFwiIC8+XG4gICAgICA8ZWwtdGFibGUtY29sdW1uIHByb3BlcnR5PVwiYWRkcmVzc1wiIGxhYmVsPVwiQWRkcmVzc1wiIC8+XG4gICAgPC9lbC10YWJsZT5cbiAgPC9lbC1kaWFsb2c+XG5cbiAgPGVsLWRpYWxvZyB2LW1vZGVsPVwiZGlhbG9nRm9ybVZpc2libGVcIiB0aXRsZT1cIlNoaXBwaW5nIGFkZHJlc3NcIiB3aWR0aD1cIjUwMFwiPlxuICAgIDxlbC1mb3JtIDptb2RlbD1cImZvcm1cIj5cbiAgICAgIDxlbC1mb3JtLWl0ZW0gbGFiZWw9XCJQcm9tb3Rpb24gbmFtZVwiIDpsYWJlbC13aWR0aD1cImZvcm1MYWJlbFdpZHRoXCI+XG4gICAgICAgIDxlbC1pbnB1dCB2LW1vZGVsPVwiZm9ybS5uYW1lXCIgYXV0b2NvbXBsZXRlPVwib2ZmXCIgLz5cbiAgICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIlpvbmVzXCIgOmxhYmVsLXdpZHRoPVwiZm9ybUxhYmVsV2lkdGhcIj5cbiAgICAgICAgPGVsLXNlbGVjdCB2LW1vZGVsPVwiZm9ybS5yZWdpb25cIiBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3QgYSB6b25lXCI+XG4gICAgICAgICAgPGVsLW9wdGlvbiBsYWJlbD1cIlpvbmUgTm8uMVwiIHZhbHVlPVwic2hhbmdoYWlcIiAvPlxuICAgICAgICAgIDxlbC1vcHRpb24gbGFiZWw9XCJab25lIE5vLjJcIiB2YWx1ZT1cImJlaWppbmdcIiAvPlxuICAgICAgICA8L2VsLXNlbGVjdD5cbiAgICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgIDwvZWwtZm9ybT5cbiAgICA8dGVtcGxhdGUgI2Zvb3Rlcj5cbiAgICAgIDxkaXYgY2xhc3M9XCJkaWFsb2ctZm9vdGVyXCI+XG4gICAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwiZGlhbG9nRm9ybVZpc2libGUgPSBmYWxzZVwiPkNhbmNlbDwvZWwtYnV0dG9uPlxuICAgICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwiZGlhbG9nRm9ybVZpc2libGUgPSBmYWxzZVwiPlxuICAgICAgICAgIENvbmZpcm1cbiAgICAgICAgPC9lbC1idXR0b24+XG4gICAgICA8L2Rpdj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLWRpYWxvZz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWFjdGl2ZSwgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBkaWFsb2dUYWJsZVZpc2libGUgPSByZWYoZmFsc2UpXG5jb25zdCBkaWFsb2dGb3JtVmlzaWJsZSA9IHJlZihmYWxzZSlcbmNvbnN0IGZvcm1MYWJlbFdpZHRoID0gJzE0MHB4J1xuXG5jb25zdCBmb3JtID0gcmVhY3RpdmUoe1xuICBuYW1lOiAnJyxcbiAgcmVnaW9uOiAnJyxcbiAgZGF0ZTE6ICcnLFxuICBkYXRlMjogJycsXG4gIGRlbGl2ZXJ5OiBmYWxzZSxcbiAgdHlwZTogW10sXG4gIHJlc291cmNlOiAnJyxcbiAgZGVzYzogJycsXG59KVxuXG5jb25zdCBncmlkRGF0YSA9IFtcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAyJyxcbiAgICBuYW1lOiAnSm9obiBTbWl0aCcsXG4gICAgYWRkcmVzczogJ05vLjE1MTgsICBKaW5zaGFqaWFuZyBSb2FkLCBQdXR1byBEaXN0cmljdCcsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wNCcsXG4gICAgbmFtZTogJ0pvaG4gU21pdGgnLFxuICAgIGFkZHJlc3M6ICdOby4xNTE4LCAgSmluc2hhamlhbmcgUm9hZCwgUHV0dW8gRGlzdHJpY3QnLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgIG5hbWU6ICdKb2huIFNtaXRoJyxcbiAgICBhZGRyZXNzOiAnTm8uMTUxOCwgIEppbnNoYWppYW5nIFJvYWQsIFB1dHVvIERpc3RyaWN0JyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTAzJyxcbiAgICBuYW1lOiAnSm9obiBTbWl0aCcsXG4gICAgYWRkcmVzczogJ05vLjE1MTgsICBKaW5zaGFqaWFuZyBSb2FkLCBQdXR1byBEaXN0cmljdCcsXG4gIH0sXG5dXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/customization-content.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" plain @click="dialogTableVisible = true">
      Open a Table nested Dialog
    </el-button>

    <el-button class="!ml-0" plain @click="dialogFormVisible = true">
      Open a Form nested Dialog
    </el-button>
  </div>

  <el-dialog v-model="dialogTableVisible" title="Shipping address" width="800">
    <el-table :data="gridData">
      <el-table-column property="date" label="Date" width="150" />
      <el-table-column property="name" label="Name" width="200" />
      <el-table-column property="address" label="Address" />
    </el-table>
  </el-dialog>

  <el-dialog v-model="dialogFormVisible" title="Shipping address" width="500">
    <el-form :model="form">
      <el-form-item label="Promotion name" :label-width="formLabelWidth">
        <el-input v-model="form.name" autocomplete="off" />
      </el-form-item>
      <el-form-item label="Zones" :label-width="formLabelWidth">
        <el-select v-model="form.region" placeholder="Please select a zone">
          <el-option label="Zone No.1" value="shanghai" />
          <el-option label="Zone No.2" value="beijing" />
        </el-select>
      </el-form-item>
    </el-form>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="dialogFormVisible = false">Cancel</el-button>
        <el-button type="primary" @click="dialogFormVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

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

const dialogTableVisible = ref(false)
const dialogFormVisible = ref(false)
const formLabelWidth = '140px'

const form = reactive({
  name: '',
  region: '',
  date1: '',
  date2: '',
  delivery: false,
  type: [],
  resource: '',
  desc: '',
})

const gridData = [
  {
    date: '2016-05-02',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
  {
    date: '2016-05-04',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
  {
    date: '2016-05-01',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
  {
    date: '2016-05-03',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
]
</script>
```

隐藏源代码

## 自定义头部 [​](#自定义头部)

`header` 可用于自定义显示标题的区域。 为了保持可用性，除了使用此插槽外，使用 `title` 属性，或使用 `titleId` 插槽属性来指定哪些元素应该读取为对话框标题。

Open Dialog with customized header

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cInZpc2libGUgPSB0cnVlXCI+XG4gICAgT3BlbiBEaWFsb2cgd2l0aCBjdXN0b21pemVkIGhlYWRlclxuICA8L2VsLWJ1dHRvbj5cblxuICA8ZWwtZGlhbG9nIHYtbW9kZWw9XCJ2aXNpYmxlXCIgOnNob3ctY2xvc2U9XCJmYWxzZVwiIHdpZHRoPVwiNTAwXCI+XG4gICAgPHRlbXBsYXRlICNoZWFkZXI9XCJ7IGNsb3NlLCB0aXRsZUlkLCB0aXRsZUNsYXNzIH1cIj5cbiAgICAgIDxkaXYgY2xhc3M9XCJteS1oZWFkZXJcIj5cbiAgICAgICAgPGg0IDppZD1cInRpdGxlSWRcIiA6Y2xhc3M9XCJ0aXRsZUNsYXNzXCI+VGhpcyBpcyBhIGN1c3RvbSBoZWFkZXIhPC9oND5cbiAgICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwiZGFuZ2VyXCIgQGNsaWNrPVwiY2xvc2VcIj5cbiAgICAgICAgICA8ZWwtaWNvbiBjbGFzcz1cImVsLWljb24tLWxlZnRcIj48Q2lyY2xlQ2xvc2VGaWxsZWQgLz48L2VsLWljb24+XG4gICAgICAgICAgQ2xvc2VcbiAgICAgICAgPC9lbC1idXR0b24+XG4gICAgICA8L2Rpdj5cbiAgICA8L3RlbXBsYXRlPlxuICAgIFRoaXMgaXMgZGlhbG9nIGNvbnRlbnQuXG4gIDwvZWwtZGlhbG9nPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IENpcmNsZUNsb3NlRmlsbGVkIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmNvbnN0IHZpc2libGUgPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cblxuPHN0eWxlIHNjb3BlZD5cbi5teS1oZWFkZXIge1xuICBkaXNwbGF5OiBmbGV4O1xuICBmbGV4LWRpcmVjdGlvbjogcm93O1xuICBqdXN0aWZ5LWNvbnRlbnQ6IHNwYWNlLWJldHdlZW47XG4gIGdhcDogMTZweDtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/customization-header.vue)_

vue

```
<template>
  <el-button plain @click="visible = true">
    Open Dialog with customized header
  </el-button>

  <el-dialog v-model="visible" :show-close="false" width="500">
    <template #header="{ close, titleId, titleClass }">
      <div class="my-header">
        <h4 :id="titleId" :class="titleClass">This is a custom header!</h4>
        <el-button type="danger" @click="close">
          <el-icon class="el-icon--left"><CircleCloseFilled /></el-icon>
          Close
        </el-button>
      </div>
    </template>
    This is dialog content.
  </el-dialog>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { CircleCloseFilled } from '@element-plus/icons-vue'

const visible = ref(false)
</script>

<style scoped>
.my-header {
  display: flex;
  flex-direction: row;
  justify-content: space-between;
  gap: 16px;
}
</style>
```

隐藏源代码

## 嵌套的对话框 [​](#嵌套的对话框)

如果需要在一个 Dialog 内部嵌套另一个 Dialog，需要使用 `append-to-body` 属性。

通常我们不建议使用嵌套对话框。 如果你需要在页面上呈现多个对话框，你可以简单地打平它们，以便它们彼此之间是平级关系。 如果必须要在一个对话框内展示另一个对话框，可以将内部嵌套的对话框属性 `append-to-body` 设置为 true，嵌套的对话框将附加到 body 而不是其父节点，这样两个对话框都可以被正确地渲染。

Open the outer Dialog

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm91dGVyVmlzaWJsZSA9IHRydWVcIj5cbiAgICBPcGVuIHRoZSBvdXRlciBEaWFsb2dcbiAgPC9lbC1idXR0b24+XG5cbiAgPGVsLWRpYWxvZyB2LW1vZGVsPVwib3V0ZXJWaXNpYmxlXCIgdGl0bGU9XCJPdXRlciBEaWFsb2dcIiB3aWR0aD1cIjgwMFwiPlxuICAgIDxzcGFuPlRoaXMgaXMgdGhlIG91dGVyIERpYWxvZzwvc3Bhbj5cbiAgICA8ZWwtZGlhbG9nXG4gICAgICB2LW1vZGVsPVwiaW5uZXJWaXNpYmxlXCJcbiAgICAgIHdpZHRoPVwiNTAwXCJcbiAgICAgIHRpdGxlPVwiSW5uZXIgRGlhbG9nXCJcbiAgICAgIGFwcGVuZC10by1ib2R5XG4gICAgPlxuICAgICAgPHNwYW4+VGhpcyBpcyB0aGUgaW5uZXIgRGlhbG9nPC9zcGFuPlxuICAgIDwvZWwtZGlhbG9nPlxuICAgIDx0ZW1wbGF0ZSAjZm9vdGVyPlxuICAgICAgPGRpdiBjbGFzcz1cImRpYWxvZy1mb290ZXJcIj5cbiAgICAgICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJvdXRlclZpc2libGUgPSBmYWxzZVwiPkNhbmNlbDwvZWwtYnV0dG9uPlxuICAgICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwiaW5uZXJWaXNpYmxlID0gdHJ1ZVwiPlxuICAgICAgICAgIE9wZW4gdGhlIGlubmVyIERpYWxvZ1xuICAgICAgICA8L2VsLWJ1dHRvbj5cbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtZGlhbG9nPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3Qgb3V0ZXJWaXNpYmxlID0gcmVmKGZhbHNlKVxuY29uc3QgaW5uZXJWaXNpYmxlID0gcmVmKGZhbHNlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/nested-dialog.vue)_

vue

```
<template>
  <el-button plain @click="outerVisible = true">
    Open the outer Dialog
  </el-button>

  <el-dialog v-model="outerVisible" title="Outer Dialog" width="800">
    <span>This is the outer Dialog</span>
    <el-dialog
      v-model="innerVisible"
      width="500"
      title="Inner Dialog"
      append-to-body
    >
      <span>This is the inner Dialog</span>
    </el-dialog>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="outerVisible = false">Cancel</el-button>
        <el-button type="primary" @click="innerVisible = true">
          Open the inner Dialog
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

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

const outerVisible = ref(false)
const innerVisible = ref(false)
</script>
```

隐藏源代码

## 内容居中 [​](#内容居中)

对话框的内容可以居中。

将`center`设置为`true`即可使标题和底部居中。 `center`仅影响标题和底部区域。 Dialog 的内容是任意的，在一些情况下，内容并不适合居中布局。 如果需要内容也水平居中，请自行为其添加 CSS 样式。

Click to open the Dialog

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cImNlbnRlckRpYWxvZ1Zpc2libGUgPSB0cnVlXCI+XG4gICAgQ2xpY2sgdG8gb3BlbiB0aGUgRGlhbG9nXG4gIDwvZWwtYnV0dG9uPlxuXG4gIDxlbC1kaWFsb2cgdi1tb2RlbD1cImNlbnRlckRpYWxvZ1Zpc2libGVcIiB0aXRsZT1cIldhcm5pbmdcIiB3aWR0aD1cIjUwMFwiIGNlbnRlcj5cbiAgICA8c3Bhbj5cbiAgICAgIEl0IHNob3VsZCBiZSBub3RlZCB0aGF0IHRoZSBjb250ZW50IHdpbGwgbm90IGJlIGFsaWduZWQgaW4gY2VudGVyIGJ5XG4gICAgICBkZWZhdWx0XG4gICAgPC9zcGFuPlxuICAgIDx0ZW1wbGF0ZSAjZm9vdGVyPlxuICAgICAgPGRpdiBjbGFzcz1cImRpYWxvZy1mb290ZXJcIj5cbiAgICAgICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJjZW50ZXJEaWFsb2dWaXNpYmxlID0gZmFsc2VcIj5DYW5jZWw8L2VsLWJ1dHRvbj5cbiAgICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiIEBjbGljaz1cImNlbnRlckRpYWxvZ1Zpc2libGUgPSBmYWxzZVwiPlxuICAgICAgICAgIENvbmZpcm1cbiAgICAgICAgPC9lbC1idXR0b24+XG4gICAgICA8L2Rpdj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLWRpYWxvZz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGNlbnRlckRpYWxvZ1Zpc2libGUgPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/centered-content.vue)_

vue

```
<template>
  <el-button plain @click="centerDialogVisible = true">
    Click to open the Dialog
  </el-button>

  <el-dialog v-model="centerDialogVisible" title="Warning" width="500" center>
    <span>
      It should be noted that the content will not be aligned in center by
      default
    </span>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="centerDialogVisible = false">Cancel</el-button>
        <el-button type="primary" @click="centerDialogVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

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

const centerDialogVisible = ref(false)
</script>
```

隐藏源代码

TIP

Dialog 的内容是懒渲染的——在被第一次打开之前，传入的默认 slot 不会被立即渲染到 DOM 上。 因此，如果需要执行 DOM 操作，或通过 `ref` 获取相应组件，请在 `open` 事件回调中进行。

## 居中对话框 [​](#居中对话框)

从屏幕中心打开对话框。

设置 `align-center` 为 `true` 使对话框水平垂直居中。 由于对话框垂直居中在弹性盒子中，所以`top`属性将不起作用。

Click to open the Dialog

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cImNlbnRlckRpYWxvZ1Zpc2libGUgPSB0cnVlXCI+XG4gICAgQ2xpY2sgdG8gb3BlbiB0aGUgRGlhbG9nXG4gIDwvZWwtYnV0dG9uPlxuXG4gIDxlbC1kaWFsb2dcbiAgICB2LW1vZGVsPVwiY2VudGVyRGlhbG9nVmlzaWJsZVwiXG4gICAgdGl0bGU9XCJXYXJuaW5nXCJcbiAgICB3aWR0aD1cIjUwMFwiXG4gICAgYWxpZ24tY2VudGVyXG4gID5cbiAgICA8c3Bhbj5PcGVuIHRoZSBkaWFsb2cgZnJvbSB0aGUgY2VudGVyIGZyb20gdGhlIHNjcmVlbjwvc3Bhbj5cbiAgICA8dGVtcGxhdGUgI2Zvb3Rlcj5cbiAgICAgIDxkaXYgY2xhc3M9XCJkaWFsb2ctZm9vdGVyXCI+XG4gICAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwiY2VudGVyRGlhbG9nVmlzaWJsZSA9IGZhbHNlXCI+Q2FuY2VsPC9lbC1idXR0b24+XG4gICAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBAY2xpY2s9XCJjZW50ZXJEaWFsb2dWaXNpYmxlID0gZmFsc2VcIj5cbiAgICAgICAgICBDb25maXJtXG4gICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1kaWFsb2c+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBjZW50ZXJEaWFsb2dWaXNpYmxlID0gcmVmKGZhbHNlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/align-center.vue)_

vue

```
<template>
  <el-button plain @click="centerDialogVisible = true">
    Click to open the Dialog
  </el-button>

  <el-dialog
    v-model="centerDialogVisible"
    title="Warning"
    width="500"
    align-center
  >
    <span>Open the dialog from the center from the screen</span>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="centerDialogVisible = false">Cancel</el-button>
        <el-button type="primary" @click="centerDialogVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

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

const centerDialogVisible = ref(false)
</script>
```

隐藏源代码

## 关闭时销毁 [​](#关闭时销毁)

启用此功能时，默认栏位下的内容将使用 `v-if` 指令销毁。 当出现性能问题时，可以启用此功能。

需要注意的是，当这个属性被启用时，在 `transition.beforeEnter` 事件卸载前，除了 `overlay`、`header (可选)`与`footer(可选)` ，Dialog 内不会有其它任何其它的 DOM 节点存在。

Click to open Dialog

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cImNlbnRlckRpYWxvZ1Zpc2libGUgPSB0cnVlXCI+XG4gICAgQ2xpY2sgdG8gb3BlbiBEaWFsb2dcbiAgPC9lbC1idXR0b24+XG5cbiAgPGVsLWRpYWxvZ1xuICAgIHYtbW9kZWw9XCJjZW50ZXJEaWFsb2dWaXNpYmxlXCJcbiAgICB0aXRsZT1cIk5vdGljZVwiXG4gICAgd2lkdGg9XCI1MDBcIlxuICAgIGRlc3Ryb3ktb24tY2xvc2VcbiAgICBjZW50ZXJcbiAgPlxuICAgIDxzcGFuPlxuICAgICAgTm90aWNlOiBiZWZvcmUgdGhlIGRpYWxvZyBpcyBvcGVuZWQgZm9yIHRoZSBmaXJzdCB0aW1lLCB0aGlzIG5vZGUgYW5kIHRoZVxuICAgICAgb25lIGJlbG93IHdpbGwgbm90IGJlIHJlbmRlcmVkLlxuICAgIDwvc3Bhbj5cbiAgICA8ZGl2PlxuICAgICAgPHN0cm9uZz5FeHRyYSBjb250ZW50IChOb3QgcmVuZGVyZWQpPC9zdHJvbmc+XG4gICAgPC9kaXY+XG4gICAgPHRlbXBsYXRlICNmb290ZXI+XG4gICAgICA8ZGl2IGNsYXNzPVwiZGlhbG9nLWZvb3RlclwiPlxuICAgICAgICA8ZWwtYnV0dG9uIEBjbGljaz1cImNlbnRlckRpYWxvZ1Zpc2libGUgPSBmYWxzZVwiPkNhbmNlbDwvZWwtYnV0dG9uPlxuICAgICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwiY2VudGVyRGlhbG9nVmlzaWJsZSA9IGZhbHNlXCI+XG4gICAgICAgICAgQ29uZmlybVxuICAgICAgICA8L2VsLWJ1dHRvbj5cbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtZGlhbG9nPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgY2VudGVyRGlhbG9nVmlzaWJsZSA9IHJlZihmYWxzZSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/destroy-on-close.vue)_

vue

```
<template>
  <el-button plain @click="centerDialogVisible = true">
    Click to open Dialog
  </el-button>

  <el-dialog
    v-model="centerDialogVisible"
    title="Notice"
    width="500"
    destroy-on-close
    center
  >
    <span>
      Notice: before the dialog is opened for the first time, this node and the
      one below will not be rendered.
    </span>
    <div>
      <strong>Extra content (Not rendered)</strong>
    </div>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="centerDialogVisible = false">Cancel</el-button>
        <el-button type="primary" @click="centerDialogVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

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

const centerDialogVisible = ref(false)
</script>
```

隐藏源代码

## 可拖拽对话框 [​](#可拖拽对话框)

试着拖动一下`header`部分吧

设置`draggable`属性为`true`以做到拖拽 设置 `overflow` 2.5.4 为 `true` 可以让拖拽范围超出可视区。

Open a draggable Dialog Open a overflow draggable Dialog Open a custom dragging style Dialog

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJkaWFsb2dWaXNpYmxlID0gdHJ1ZVwiPlxuICAgICAgT3BlbiBhIGRyYWdnYWJsZSBEaWFsb2dcbiAgICA8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJkaWFsb2dPdmVyZmxvd1Zpc2libGUgPSB0cnVlXCI+XG4gICAgICBPcGVuIGEgb3ZlcmZsb3cgZHJhZ2dhYmxlIERpYWxvZ1xuICAgIDwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gY2xhc3M9XCIhbWwtMFwiIHBsYWluIEBjbGljaz1cImN1c3RvbURyYWdnaW5nVmlzaWJsZSA9IHRydWVcIj5cbiAgICAgIE9wZW4gYSBjdXN0b20gZHJhZ2dpbmcgc3R5bGUgRGlhbG9nXG4gICAgPC9lbC1idXR0b24+XG4gIDwvZGl2PlxuXG4gIDxlbC1kaWFsb2cgdi1tb2RlbD1cImRpYWxvZ1Zpc2libGVcIiB0aXRsZT1cIlRpcHNcIiB3aWR0aD1cIjUwMFwiIGRyYWdnYWJsZT5cbiAgICA8c3Bhbj5JdCdzIGEgZHJhZ2dhYmxlIERpYWxvZzwvc3Bhbj5cbiAgICA8dGVtcGxhdGUgI2Zvb3Rlcj5cbiAgICAgIDxkaXYgY2xhc3M9XCJkaWFsb2ctZm9vdGVyXCI+XG4gICAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwiZGlhbG9nVmlzaWJsZSA9IGZhbHNlXCI+Q2FuY2VsPC9lbC1idXR0b24+XG4gICAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBAY2xpY2s9XCJkaWFsb2dWaXNpYmxlID0gZmFsc2VcIj5cbiAgICAgICAgICBDb25maXJtXG4gICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1kaWFsb2c+XG5cbiAgPGVsLWRpYWxvZ1xuICAgIHYtbW9kZWw9XCJkaWFsb2dPdmVyZmxvd1Zpc2libGVcIlxuICAgIHRpdGxlPVwiVGlwc1wiXG4gICAgd2lkdGg9XCI1MDBcIlxuICAgIGRyYWdnYWJsZVxuICAgIG92ZXJmbG93XG4gID5cbiAgICA8c3Bhbj5JdCdzIGEgb3ZlcmZsb3cgZHJhZ2dhYmxlIERpYWxvZzwvc3Bhbj5cbiAgICA8dGVtcGxhdGUgI2Zvb3Rlcj5cbiAgICAgIDxkaXYgY2xhc3M9XCJkaWFsb2ctZm9vdGVyXCI+XG4gICAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwiZGlhbG9nT3ZlcmZsb3dWaXNpYmxlID0gZmFsc2VcIj5DYW5jZWw8L2VsLWJ1dHRvbj5cbiAgICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiIEBjbGljaz1cImRpYWxvZ092ZXJmbG93VmlzaWJsZSA9IGZhbHNlXCI+XG4gICAgICAgICAgQ29uZmlybVxuICAgICAgICA8L2VsLWJ1dHRvbj5cbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtZGlhbG9nPlxuXG4gIDxlbC1kaWFsb2dcbiAgICB2LW1vZGVsPVwiY3VzdG9tRHJhZ2dpbmdWaXNpYmxlXCJcbiAgICBjbGFzcz1cImN1c3RvbS1kcmFnZ2luZy1zdHlsZVwiXG4gICAgdGl0bGU9XCJDdXN0b20gRHJhZ2dpbmcgU3R5bGVcIlxuICAgIHdpZHRoPVwiNTAwXCJcbiAgICBkcmFnZ2FibGVcbiAgPlxuICAgIDxzcGFuXG4gICAgICA+VGhpcyBkaWFsb2cgaGFzIGN1c3RvbSBkcmFnZ2luZyBzdHlsZXMuIFRyeSBkcmFnZ2luZyBpdCB0byBzZWUgdGhlXG4gICAgICBlZmZlY3RzITwvc3BhblxuICAgID5cbiAgICA8dGVtcGxhdGUgI2Zvb3Rlcj5cbiAgICAgIDxkaXYgY2xhc3M9XCJkaWFsb2ctZm9vdGVyXCI+XG4gICAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwiY3VzdG9tRHJhZ2dpbmdWaXNpYmxlID0gZmFsc2VcIj5DYW5jZWw8L2VsLWJ1dHRvbj5cbiAgICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiIEBjbGljaz1cImN1c3RvbURyYWdnaW5nVmlzaWJsZSA9IGZhbHNlXCI+XG4gICAgICAgICAgQ29uZmlybVxuICAgICAgICA8L2VsLWJ1dHRvbj5cbiAgICAgIDwvZGl2PlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtZGlhbG9nPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgZGlhbG9nVmlzaWJsZSA9IHJlZihmYWxzZSlcbmNvbnN0IGRpYWxvZ092ZXJmbG93VmlzaWJsZSA9IHJlZihmYWxzZSlcbmNvbnN0IGN1c3RvbURyYWdnaW5nVmlzaWJsZSA9IHJlZihmYWxzZSlcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuOmdsb2JhbCguY3VzdG9tLWRyYWdnaW5nLXN0eWxlLmlzLWRyYWdnaW5nKSB7XG4gIGJvcmRlcjogMnB4IGRhc2hlZCB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbiAgb3BhY2l0eTogMC42NTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/draggable-dialog.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" plain @click="dialogVisible = true">
      Open a draggable Dialog
    </el-button>
    <el-button class="!ml-0" plain @click="dialogOverflowVisible = true">
      Open a overflow draggable Dialog
    </el-button>
    <el-button class="!ml-0" plain @click="customDraggingVisible = true">
      Open a custom dragging style Dialog
    </el-button>
  </div>

  <el-dialog v-model="dialogVisible" title="Tips" width="500" draggable>
    <span>It's a draggable Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="dialogVisible = false">Cancel</el-button>
        <el-button type="primary" @click="dialogVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>

  <el-dialog
    v-model="dialogOverflowVisible"
    title="Tips"
    width="500"
    draggable
    overflow
  >
    <span>It's a overflow draggable Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="dialogOverflowVisible = false">Cancel</el-button>
        <el-button type="primary" @click="dialogOverflowVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>

  <el-dialog
    v-model="customDraggingVisible"
    class="custom-dragging-style"
    title="Custom Dragging Style"
    width="500"
    draggable
  >
    <span
      >This dialog has custom dragging styles. Try dragging it to see the
      effects!</span
    >
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="customDraggingVisible = false">Cancel</el-button>
        <el-button type="primary" @click="customDraggingVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

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

const dialogVisible = ref(false)
const dialogOverflowVisible = ref(false)
const customDraggingVisible = ref(false)
</script>

<style scoped>
:global(.custom-dragging-style.is-dragging) {
  border: 2px dashed var(--el-color-primary);
  opacity: 0.65;
}
</style>
```

隐藏源代码

TIP

当 `modal` 的值为 false 时，请一定要确保 `append-to-body` 属性为 **true**，由于 `Dialog` 使用 `position: relative` 定位，当外层的遮罩层被移除时，`Dialog` 则会根据当前 DOM 上的祖先节点来定位，因此可能造成定位问题。

## 全屏 [​](#全屏)

设置 `fullscreen` 属性来打开全屏对话框。

Open the fullscreen Dialog

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cImRpYWxvZ1Zpc2libGUgPSB0cnVlXCI+XG4gICAgT3BlbiB0aGUgZnVsbHNjcmVlbiBEaWFsb2dcbiAgPC9lbC1idXR0b24+XG5cbiAgPGVsLWRpYWxvZyB2LW1vZGVsPVwiZGlhbG9nVmlzaWJsZVwiIGZ1bGxzY3JlZW4+XG4gICAgPHNwYW4+SXQncyBhIGZ1bGxzY3JlZW4gRGlhbG9nPC9zcGFuPlxuICAgIDx0ZW1wbGF0ZSAjZm9vdGVyPlxuICAgICAgPGRpdiBjbGFzcz1cImRpYWxvZy1mb290ZXJcIj5cbiAgICAgICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJkaWFsb2dWaXNpYmxlID0gZmFsc2VcIj5DYW5jZWw8L2VsLWJ1dHRvbj5cbiAgICAgICAgPGVsLWJ1dHRvbiB0eXBlPVwicHJpbWFyeVwiIEBjbGljaz1cImRpYWxvZ1Zpc2libGUgPSBmYWxzZVwiPlxuICAgICAgICAgIENvbmZpcm1cbiAgICAgICAgPC9lbC1idXR0b24+XG4gICAgICA8L2Rpdj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLWRpYWxvZz5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGRpYWxvZ1Zpc2libGUgPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/fullscreen.vue)_

vue

```
<template>
  <el-button plain @click="dialogVisible = true">
    Open the fullscreen Dialog
  </el-button>

  <el-dialog v-model="dialogVisible" fullscreen>
    <span>It's a fullscreen Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="dialogVisible = false">Cancel</el-button>
        <el-button type="primary" @click="dialogVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

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

const dialogVisible = ref(false)
</script>
```

隐藏源代码

TIP

如果 `fullscreen` 为 true，则 `width`、`top` 和 `draggable` 属性无效。

## 模态框 [​](#模态框)

将 `modal` 设置为 `false` 会隐藏对话框的模态（覆盖层）。

从版本 2.10.5 起，新增了 `modal-penetrable`属性，该属性可设置为“可穿透”（即允许穿透）。

Open the modal Dialog

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cImRpYWxvZ1Zpc2libGUgPSB0cnVlXCI+XG4gICAgT3BlbiB0aGUgbW9kYWwgRGlhbG9nXG4gIDwvZWwtYnV0dG9uPlxuXG4gIDxlbC1kaWFsb2cgdi1tb2RlbD1cImRpYWxvZ1Zpc2libGVcIiA6bW9kYWw9XCJmYWxzZVwiIG1vZGFsLXBlbmV0cmFibGU+XG4gICAgPHNwYW4+SXQncyBhIG1vZGFsIERpYWxvZzwvc3Bhbj5cbiAgICA8dGVtcGxhdGUgI2Zvb3Rlcj5cbiAgICAgIDxkaXYgY2xhc3M9XCJkaWFsb2ctZm9vdGVyXCI+XG4gICAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwiZGlhbG9nVmlzaWJsZSA9IGZhbHNlXCI+Q2FuY2VsPC9lbC1idXR0b24+XG4gICAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBAY2xpY2s9XCJkaWFsb2dWaXNpYmxlID0gZmFsc2VcIj5cbiAgICAgICAgICBDb25maXJtXG4gICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1kaWFsb2c+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBkaWFsb2dWaXNpYmxlID0gcmVmKGZhbHNlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/modal.vue)_

vue

```
<template>
  <el-button plain @click="dialogVisible = true">
    Open the modal Dialog
  </el-button>

  <el-dialog v-model="dialogVisible" :modal="false" modal-penetrable>
    <span>It's a modal Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="dialogVisible = false">Cancel</el-button>
        <el-button type="primary" @click="dialogVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

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

const dialogVisible = ref(false)
</script>
```

隐藏源代码

## 自定义动画 2.10.5 [​](#自定义动画)

通过 `transition` 属性自定义对话框动画，该属性可以接受以下任意一种值：

-   动画名称（字符串）

-   Vue 过渡配置（对象）

示例包括缩放（scale）、滑动（slide）、淡入淡出（fade）、弹跳（bounce）动画，以及带有自定义事件处理器的基于对象的配置。

Default Scale Slide Bounce Object Config

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1idXR0b24gcGxhaW4gQGNsaWNrPVwib3BlbkRpYWxvZygnZmFkZScpXCI+IERlZmF1bHQgPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBwbGFpbiBAY2xpY2s9XCJvcGVuRGlhbG9nKCdzY2FsZScpXCI+IFNjYWxlIDwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gcGxhaW4gQGNsaWNrPVwib3BlbkRpYWxvZygnc2xpZGUnKVwiPiBTbGlkZSA8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5EaWFsb2coJ2JvdW5jZScpXCI+IEJvdW5jZSA8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5EaWFsb2dXaXRoT2JqZWN0XCI+IE9iamVjdCBDb25maWcgPC9lbC1idXR0b24+XG4gIDwvZGl2PlxuXG4gIDxlbC1kaWFsb2dcbiAgICB2LW1vZGVsPVwiZGlhbG9nVmlzaWJsZVwiXG4gICAgY2xhc3M9XCJjdXN0b20tdHJhbnNpdGlvbi1kaWFsb2dcIlxuICAgIDp0aXRsZT1cImAke2N1cnJlbnRBbmltYXRpb259IEFuaW1hdGlvbiBEaWFsb2dgXCJcbiAgICB3aWR0aD1cIjMwJVwiXG4gICAgOnRyYW5zaXRpb249XCJ0cmFuc2l0aW9uQ29uZmlnXCJcbiAgPlxuICAgIDxkaXY+XG4gICAgICA8cD5cbiAgICAgICAgQ3VycmVudCBhbmltYXRpb246IDxzdHJvbmc+e3sgY3VycmVudEFuaW1hdGlvbiB9fTwvc3Ryb25nPlxuICAgICAgPC9wPlxuICAgICAgPHA+XG4gICAgICAgIFRoaXMgZGlhbG9nIGRlbW9uc3RyYXRlcyB0aGUge3sgY3VycmVudEFuaW1hdGlvbiB9fSBhbmltYXRpb24gZWZmZWN0LlxuICAgICAgPC9wPlxuICAgICAgPHAgdi1pZj1cImlzT2JqZWN0Q29uZmlnXCI+XG4gICAgICAgIDxzdHJvbmc+VXNpbmcgb2JqZWN0IGNvbmZpZ3VyYXRpb246PC9zdHJvbmc+PGJyIC8+XG4gICAgICAgIDxjb2RlPnt7IEpTT04uc3RyaW5naWZ5KHRyYW5zaXRpb25Db25maWcsIG51bGwsIDIpIH19PC9jb2RlPlxuICAgICAgPC9wPlxuICAgIDwvZGl2PlxuICAgIDx0ZW1wbGF0ZSAjZm9vdGVyPlxuICAgICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJkaWFsb2dWaXNpYmxlID0gZmFsc2VcIj5DYW5jZWw8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBAY2xpY2s9XCJkaWFsb2dWaXNpYmxlID0gZmFsc2VcIj5cbiAgICAgICAgQ29uZmlybVxuICAgICAgPC9lbC1idXR0b24+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1kaWFsb2c+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgY29tcHV0ZWQsIHJlZiB9IGZyb20gJ3Z1ZSdcblxuaW1wb3J0IHR5cGUgeyBEaWFsb2dUcmFuc2l0aW9uIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBkaWFsb2dWaXNpYmxlID0gcmVmKGZhbHNlKVxuY29uc3QgY3VycmVudEFuaW1hdGlvbiA9IHJlZignZmFkZScpXG5jb25zdCBpc09iamVjdENvbmZpZyA9IHJlZihmYWxzZSlcblxuY29uc3QgdHJhbnNpdGlvbkNvbmZpZyA9IGNvbXB1dGVkPERpYWxvZ1RyYW5zaXRpb24+KCgpID0+IHtcbiAgaWYgKGlzT2JqZWN0Q29uZmlnLnZhbHVlKSB7XG4gICAgcmV0dXJuIHtcbiAgICAgIG5hbWU6ICdkaWFsb2ctY3VzdG9tLW9iamVjdCcsXG4gICAgICBhcHBlYXI6IHRydWUsXG4gICAgICBtb2RlOiAnb3V0LWluJyxcbiAgICAgIGR1cmF0aW9uOiA1MDAsXG4gICAgfVxuICB9XG4gIHJldHVybiBgZGlhbG9nLSR7Y3VycmVudEFuaW1hdGlvbi52YWx1ZX1gXG59KVxuXG5jb25zdCBvcGVuRGlhbG9nID0gKHR5cGU6IHN0cmluZykgPT4ge1xuICBjdXJyZW50QW5pbWF0aW9uLnZhbHVlID0gdHlwZVxuICBpc09iamVjdENvbmZpZy52YWx1ZSA9IGZhbHNlXG4gIGRpYWxvZ1Zpc2libGUudmFsdWUgPSB0cnVlXG59XG5cbmNvbnN0IG9wZW5EaWFsb2dXaXRoT2JqZWN0ID0gKCkgPT4ge1xuICBjdXJyZW50QW5pbWF0aW9uLnZhbHVlID0gJ29iamVjdC1jb25maWcnXG4gIGlzT2JqZWN0Q29uZmlnLnZhbHVlID0gdHJ1ZVxuICBkaWFsb2dWaXNpYmxlLnZhbHVlID0gdHJ1ZVxufVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG5jb2RlIHtcbiAgYmFja2dyb3VuZDogdmFyKC0tZWwtYmctY29sb3ItcGFnZSk7XG4gIHBhZGRpbmc6IDRweCA4cHg7XG4gIGJvcmRlci1yYWRpdXM6IDRweDtcbiAgZm9udC1zaXplOiAxMnB4O1xuICBkaXNwbGF5OiBibG9jaztcbiAgbWFyZ2luLXRvcDogOHB4O1xufVxuPC9zdHlsZT5cblxuPHN0eWxlPlxuLyogU2NhbGUgQW5pbWF0aW9uICovXG4uZGlhbG9nLXNjYWxlLWVudGVyLWFjdGl2ZSxcbi5kaWFsb2ctc2NhbGUtbGVhdmUtYWN0aXZlLFxuLmRpYWxvZy1zY2FsZS1lbnRlci1hY3RpdmUgLmVsLWRpYWxvZyxcbi5kaWFsb2ctc2NhbGUtbGVhdmUtYWN0aXZlIC5lbC1kaWFsb2cge1xuICB0cmFuc2l0aW9uOiBhbGwgMC4ycyBjdWJpYy1iZXppZXIoMC42NDUsIDAuMDQ1LCAwLjM1NSwgMSk7XG59XG5cbi5kaWFsb2ctc2NhbGUtZW50ZXItZnJvbSxcbi5kaWFsb2ctc2NhbGUtbGVhdmUtdG8ge1xuICBvcGFjaXR5OiAwO1xufVxuXG4uZGlhbG9nLXNjYWxlLWVudGVyLWZyb20gLmVsLWRpYWxvZyxcbi5kaWFsb2ctc2NhbGUtbGVhdmUtdG8gLmVsLWRpYWxvZyB7XG4gIHRyYW5zZm9ybTogc2NhbGUoMC41KTtcbiAgb3BhY2l0eTogMDtcbn1cblxuLyogU2xpZGUgQW5pbWF0aW9uICovXG4uZGlhbG9nLXNsaWRlLWVudGVyLWFjdGl2ZSxcbi5kaWFsb2ctc2xpZGUtbGVhdmUtYWN0aXZlLFxuLmRpYWxvZy1zbGlkZS1lbnRlci1hY3RpdmUgLmVsLWRpYWxvZyxcbi5kaWFsb2ctc2xpZGUtbGVhdmUtYWN0aXZlIC5lbC1kaWFsb2cge1xuICB0cmFuc2l0aW9uOiBhbGwgMC4zcyBjdWJpYy1iZXppZXIoMC4yNSwgMC40NiwgMC40NSwgMC45NCk7XG59XG5cbi5kaWFsb2ctc2xpZGUtZW50ZXItZnJvbSxcbi5kaWFsb2ctc2xpZGUtbGVhdmUtdG8ge1xuICBvcGFjaXR5OiAwO1xufVxuXG4uZGlhbG9nLXNsaWRlLWVudGVyLWZyb20gLmVsLWRpYWxvZyxcbi5kaWFsb2ctc2xpZGUtbGVhdmUtdG8gLmVsLWRpYWxvZyB7XG4gIHRyYW5zZm9ybTogdHJhbnNsYXRlWSgtMTAwcHgpO1xuICBvcGFjaXR5OiAwO1xufVxuXG4vKiBCb3VuY2UgQW5pbWF0aW9uICovXG4uZGlhbG9nLWJvdW5jZS1lbnRlci1hY3RpdmUsXG4uZGlhbG9nLWJvdW5jZS1sZWF2ZS1hY3RpdmUsXG4uZGlhbG9nLWJvdW5jZS1lbnRlci1hY3RpdmUgLmVsLWRpYWxvZyxcbi5kaWFsb2ctYm91bmNlLWxlYXZlLWFjdGl2ZSAuZWwtZGlhbG9nIHtcbiAgdHJhbnNpdGlvbjogYWxsIDAuNXMgY3ViaWMtYmV6aWVyKDAuMTc1LCAwLjg4NSwgMC4zMiwgMS4yNzUpO1xufVxuXG4uZGlhbG9nLWJvdW5jZS1lbnRlci1mcm9tLFxuLmRpYWxvZy1ib3VuY2UtbGVhdmUtdG8ge1xuICBvcGFjaXR5OiAwO1xufVxuXG4uZGlhbG9nLWJvdW5jZS1lbnRlci1mcm9tIC5lbC1kaWFsb2csXG4uZGlhbG9nLWJvdW5jZS1sZWF2ZS10byAuZWwtZGlhbG9nIHtcbiAgdHJhbnNmb3JtOiBzY2FsZSgwLjMpIHRyYW5zbGF0ZVkoLTUwcHgpO1xuICBvcGFjaXR5OiAwO1xufVxuXG4vKiBPYmplY3QgQ29uZmlndXJhdGlvbiBBbmltYXRpb24gKi9cbi5kaWFsb2ctY3VzdG9tLW9iamVjdC1lbnRlci1hY3RpdmUsXG4uZGlhbG9nLWN1c3RvbS1vYmplY3QtbGVhdmUtYWN0aXZlLFxuLmRpYWxvZy1jdXN0b20tb2JqZWN0LWVudGVyLWFjdGl2ZSAuZWwtZGlhbG9nLFxuLmRpYWxvZy1jdXN0b20tb2JqZWN0LWxlYXZlLWFjdGl2ZSAuZWwtZGlhbG9nIHtcbiAgdHJhbnNpdGlvbjogYWxsIDAuNXMgY3ViaWMtYmV6aWVyKDAuMjUsIDAuOCwgMC4yNSwgMSk7XG59XG5cbi5kaWFsb2ctY3VzdG9tLW9iamVjdC1lbnRlci1mcm9tLFxuLmRpYWxvZy1jdXN0b20tb2JqZWN0LWxlYXZlLXRvIHtcbiAgb3BhY2l0eTogMDtcbn1cblxuLmRpYWxvZy1jdXN0b20tb2JqZWN0LWVudGVyLWZyb20gLmVsLWRpYWxvZyxcbi5kaWFsb2ctY3VzdG9tLW9iamVjdC1sZWF2ZS10byAuZWwtZGlhbG9nIHtcbiAgdHJhbnNmb3JtOiByb3RhdGUoMTgwZGVnKSBzY2FsZSgwLjUpO1xuICBvcGFjaXR5OiAwO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/custom-animation.vue)_

vue

```
<template>
  <div>
    <el-button plain @click="openDialog('fade')"> Default </el-button>
    <el-button plain @click="openDialog('scale')"> Scale </el-button>
    <el-button plain @click="openDialog('slide')"> Slide </el-button>
    <el-button plain @click="openDialog('bounce')"> Bounce </el-button>
    <el-button plain @click="openDialogWithObject"> Object Config </el-button>
  </div>

  <el-dialog
    v-model="dialogVisible"
    class="custom-transition-dialog"
    :title="`${currentAnimation} Animation Dialog`"
    width="30%"
    :transition="transitionConfig"
  >
    <div>
      <p>
        Current animation: <strong>{{ currentAnimation }}</strong>
      </p>
      <p>
        This dialog demonstrates the {{ currentAnimation }} animation effect.
      </p>
      <p v-if="isObjectConfig">
        <strong>Using object configuration:</strong><br />
        <code>{{ JSON.stringify(transitionConfig, null, 2) }}</code>
      </p>
    </div>
    <template #footer>
      <el-button @click="dialogVisible = false">Cancel</el-button>
      <el-button type="primary" @click="dialogVisible = false">
        Confirm
      </el-button>
    </template>
  </el-dialog>
</template>

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

import type { DialogTransition } from 'element-plus'

const dialogVisible = ref(false)
const currentAnimation = ref('fade')
const isObjectConfig = ref(false)

const transitionConfig = computed<DialogTransition>(() => {
  if (isObjectConfig.value) {
    return {
      name: 'dialog-custom-object',
      appear: true,
      mode: 'out-in',
      duration: 500,
    }
  }
  return `dialog-${currentAnimation.value}`
})

const openDialog = (type: string) => {
  currentAnimation.value = type
  isObjectConfig.value = false
  dialogVisible.value = true
}

const openDialogWithObject = () => {
  currentAnimation.value = 'object-config'
  isObjectConfig.value = true
  dialogVisible.value = true
}
</script>

<style scoped>
code {
  background: var(--el-bg-color-page);
  padding: 4px 8px;
  border-radius: 4px;
  font-size: 12px;
  display: block;
  margin-top: 8px;
}
</style>

<style>
/* Scale Animation */
.dialog-scale-enter-active,
.dialog-scale-leave-active,
.dialog-scale-enter-active .el-dialog,
.dialog-scale-leave-active .el-dialog {
  transition: all 0.2s cubic-bezier(0.645, 0.045, 0.355, 1);
}

.dialog-scale-enter-from,
.dialog-scale-leave-to {
  opacity: 0;
}

.dialog-scale-enter-from .el-dialog,
.dialog-scale-leave-to .el-dialog {
  transform: scale(0.5);
  opacity: 0;
}

/* Slide Animation */
.dialog-slide-enter-active,
.dialog-slide-leave-active,
.dialog-slide-enter-active .el-dialog,
.dialog-slide-leave-active .el-dialog {
  transition: all 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94);
}

.dialog-slide-enter-from,
.dialog-slide-leave-to {
  opacity: 0;
}

.dialog-slide-enter-from .el-dialog,
.dialog-slide-leave-to .el-dialog {
  transform: translateY(-100px);
  opacity: 0;
}

/* Bounce Animation */
.dialog-bounce-enter-active,
.dialog-bounce-leave-active,
.dialog-bounce-enter-active .el-dialog,
.dialog-bounce-leave-active .el-dialog {
  transition: all 0.5s cubic-bezier(0.175, 0.885, 0.32, 1.275);
}

.dialog-bounce-enter-from,
.dialog-bounce-leave-to {
  opacity: 0;
}

.dialog-bounce-enter-from .el-dialog,
.dialog-bounce-leave-to .el-dialog {
  transform: scale(0.3) translateY(-50px);
  opacity: 0;
}

/* Object Configuration Animation */
.dialog-custom-object-enter-active,
.dialog-custom-object-leave-active,
.dialog-custom-object-enter-active .el-dialog,
.dialog-custom-object-leave-active .el-dialog {
  transition: all 0.5s cubic-bezier(0.25, 0.8, 0.25, 1);
}

.dialog-custom-object-enter-from,
.dialog-custom-object-leave-to {
  opacity: 0;
}

.dialog-custom-object-enter-from .el-dialog,
.dialog-custom-object-leave-to .el-dialog {
  transform: rotate(180deg) scale(0.5);
  opacity: 0;
}
</style>
```

隐藏源代码

TIP

动画类会根据过渡名称动态生成。 为了更细致地控制动画行为，你可以明确地定义这些类。 详情请参见 [自定义过渡类（custom-transition-classes）](https://vuejs.org/guide/built-ins/transition.html#custom-transition-classes)。

## Events [​](#events)

打开开发者控制台(ctrl + shift + J)，查看事件的顺序。

Open the event Dialog

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cImRpYWxvZ1Zpc2libGUgPSB0cnVlXCI+XG4gICAgT3BlbiB0aGUgZXZlbnQgRGlhbG9nXG4gIDwvZWwtYnV0dG9uPlxuXG4gIDxlbC1kaWFsb2dcbiAgICB2LW1vZGVsPVwiZGlhbG9nVmlzaWJsZVwiXG4gICAgbW9kYWwtY2xhc3M9XCJvdmVyaWRlLWFuaW1hdGlvblwiXG4gICAgOmJlZm9yZS1jbG9zZT1cIlxuICAgICAgKGRvbmVGbikgPT4ge1xuICAgICAgICA7KGNvbnNvbGUubG9nKCdiZWZvcmUtY2xvc2UnKSwgZG9uZUZuKCkpXG4gICAgICB9XG4gICAgXCJcbiAgICBAb3Blbj1cImNvbnNvbGUubG9nKCdvcGVuJylcIlxuICAgIEBvcGVuLWF1dG8tZm9jdXM9XCJjb25zb2xlLmxvZygnb3Blbi1hdXRvLWZvY3VzJylcIlxuICAgIEBvcGVuZWQ9XCJjb25zb2xlLmxvZygnb3BlbmVkJylcIlxuICAgIEBjbG9zZT1cImNvbnNvbGUubG9nKCdjbG9zZScpXCJcbiAgICBAY2xvc2UtYXV0by1mb2N1cz1cImNvbnNvbGUubG9nKCdjbG9zZS1hdXRvLWZvY3VzJylcIlxuICAgIEBjbG9zZWQ9XCJjb25zb2xlLmxvZygnY2xvc2VkJylcIlxuICA+XG4gICAgPHNwYW4+SXQncyBhIGV2ZW50IERpYWxvZzwvc3Bhbj5cbiAgICA8dGVtcGxhdGUgI2Zvb3Rlcj5cbiAgICAgIDxkaXYgY2xhc3M9XCJkaWFsb2ctZm9vdGVyXCI+XG4gICAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwiZGlhbG9nVmlzaWJsZSA9IGZhbHNlXCI+Q2FuY2VsPC9lbC1idXR0b24+XG4gICAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBAY2xpY2s9XCJkaWFsb2dWaXNpYmxlID0gZmFsc2VcIj5cbiAgICAgICAgICBDb25maXJtXG4gICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1kaWFsb2c+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBkaWFsb2dWaXNpYmxlID0gcmVmKGZhbHNlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/dialog/events.vue)_

vue

```
<template>
  <el-button plain @click="dialogVisible = true">
    Open the event Dialog
  </el-button>

  <el-dialog
    v-model="dialogVisible"
    modal-class="overide-animation"
    :before-close="
      (doneFn) => {
        ;(console.log('before-close'), doneFn())
      }
    "
    @open="console.log('open')"
    @open-auto-focus="console.log('open-auto-focus')"
    @opened="console.log('opened')"
    @close="console.log('close')"
    @close-auto-focus="console.log('close-auto-focus')"
    @closed="console.log('closed')"
  >
    <span>It's a event Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <el-button @click="dialogVisible = false">Cancel</el-button>
        <el-button type="primary" @click="dialogVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-dialog>
</template>

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

const dialogVisible = ref(false)
</script>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| model-value / v-model | 是否显示 Dialog | `boolean` | false |
| title | Dialog 对话框 Dialog 的标题， 也可通过具名 slot （见下表）传入 | `string` | '' |
| width | 对话框的宽度，默认值为 50% | `string` / `number` | '' |
| fullscreen | 是否为全屏 Dialog | `boolean` | false |
| top | dialog CSS 中的 margin-top 值，默认为 15vh | `string` | '' |
| modal | 是否需要遮罩层 | `boolean` | true |
| modal-penetrable 2.10.5 | 是否允许穿透遮罩层。 modal 属性必须为 `false`。 | `boolean` | false |
| modal-class | 遮罩的自定义类名 | `string` | — |
| header-class 2.9.3 | header 部分的自定义 class 名 | `string` | — |
| body-class 2.9.3 | body 部分的自定义 class 名 | `string` | — |
| footer-class 2.9.3 | footer 部分的自定义 class 名 | `string` | — |
| append-to-body | Dialog 自身是否插入至 body 元素上。 嵌套的 Dialog 必须指定该属性并赋值为 `true` | `boolean` | false |
| append-to 2.4.3 | Dialog 挂载到哪个 DOM 元素 将覆盖 `append-to-body` | `CSSSelector` / `HTMLElement` | body |
| lock-scroll | 是否在 Dialog 出现时将 body 滚动锁定 | `boolean` | true |
| open-delay | dialog 打开的延时时间，单位毫秒 | `number` | 0 |
| close-delay | dialog 关闭的延时时间，单位毫秒 | `number` | 0 |
| close-on-click-modal | 是否可以通过点击 modal 关闭 Dialog | `boolean` | true |
| close-on-press-escape | 是否可以通过按下 ESC 关闭 Dialog | `boolean` | true |
| show-close | 是否显示关闭按钮 | `boolean` | true |
| before-close | 关闭前的回调，会暂停 Dialog 的关闭. 回调函数内执行 done 参数方法的时候才是真正关闭对话框的时候. | `Function` | — |
| draggable | 为 Dialog 启用可拖拽功能 | `boolean` | false |
| overflow 2.5.4 | 拖动范围可以超出可视区 | `boolean` | false |
| center | 是否让 Dialog 的 header 和 footer 部分居中排列 | `boolean` | false |
| align-center 2.2.16 | 是否水平垂直对齐对话框 | `boolean` | false |
| destroy-on-close | 当关闭 Dialog 时，销毁其中的元素 | `boolean` | false |
| close-icon | 自定义关闭图标，默认 Close | `string` / `Component` | — |
| z-index | 和原生的 CSS 的 z-index 相同，改变 z 轴的顺序 | `number` | — |
| header-aria-level a11y | header 的 `aria-level` 属性 | `string` | 2 |
| transition 2.10.5 | 对话框动画的自定义过渡配置。 可以是一个字符串（过渡名称），也可以是一个包含 Vue 过渡属性的对象。 | `string` / `object` | dialog-fade |
| custom-class deprecated | Dialog 的自定义类名 | `string` | '' |

WARNING

`custom-class` 已被 **弃用**, 之后将会在 2.4.0 **移除**, 请使用 `class`.

### Slots [​](#slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 对话框的默认内容 |
| header | 对话框标题的内容；会替换标题部分，但不会移除关闭按钮。 |
| footer | Dialog 按钮操作区的内容 |
| title deprecated | 与 header 作用相同 请使用 header |

WARNING

`title` 已被**弃用**，并将在 3.0.0 版本中**移除**，请使用 `header` 代替。

### 事件 [​](#事件)

| 名称 | 详情 | Type |
| --- | --- | --- |
| open | Dialog 打开的回调 | `Function` |
| opened | Dialog 打开动画结束时的回调 | `Function` |
| close | Dialog 关闭的回调 | `Function` |
| closed | Dialog 关闭动画结束时的回调 | `Function` |
| open-auto-focus | 输入焦点聚焦在 Dialog 内容时的回调 | `Function` |
| close-auto-focus | 输入焦点从 Dialog 内容失焦时的回调 | `Function` |

### Exposes [​](#exposes)

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| resetPosition 2.8.1 | 重置位置 | `Function` |
| handleClose 2.9.8 | 关闭对话框 | `Function` |

## FAQ [​](#faq)

#### 在 SFC 文件中使用对话框，scope 样式不会生效 [​](#在-sfc-文件中使用对话框-scope-样式不会生效)

典型议题：[#10515](https://github.com/element-plus/element-plus/issues/10515)

PS：既然对话框是使用 `Teleport` 渲染的，建议在全局范围写入根节点的样式。

#### 当对话框被显示及隐藏时，页面元素会来回移动（抖动） [​](#当对话框被显示及隐藏时-页面元素会来回移动-抖动)

典型议题：[#10481](https://github.com/element-plus/element-plus/issues/10481)

PS：建议将滚动区域放置在一个挂载的 vue 节点，如 `<div id="app" />` 下，并对 body 使用 `overflow: hidden` 样式。

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/dialog) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/dialog.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/dialog.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/1539496?v=4&size=64)](https://github.com/donga-gao)[![](https://avatars.githubusercontent.com/u/108655466?v=4&size=64)](https://github.com/Karolis-Stoncius)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/138789658?v=4&size=64)](https://github.com/StudiousGao)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/88474826?v=4&size=64)](https://github.com/wsVIC)[![](https://avatars.githubusercontent.com/u/54931083?v=4&size=64)](https://github.com/wjp980108)[![](https://avatars.githubusercontent.com/u/48633709?v=4&size=64)](https://github.com/cosine7)[![](https://avatars.githubusercontent.com/u/44218347?v=4&size=64)](https://github.com/yuuuuuyu)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/35426360?v=4&size=64)](https://github.com/Jungzl)[![](https://avatars.githubusercontent.com/u/30278419?v=4&size=64)](https://github.com/nothing-sy)[![](https://avatars.githubusercontent.com/u/23433168?v=4&size=64)](https://github.com/hunter-fl)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/4075314?v=4&size=64)](https://github.com/Giwayume)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/31959015?v=4&size=64)](https://github.com/Hfutsora)[![](https://avatars.githubusercontent.com/u/11536903?v=4&size=64)](https://github.com/zhoucan38)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/1411614?v=4&size=64)](https://github.com/spx443812507)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/234919486?v=4&size=64)](https://github.com/linzx-jess)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/57352899?v=4&size=64)](https://github.com/VisualYuki)[![](https://avatars.githubusercontent.com/u/45616067?v=4&size=64)](https://github.com/elioist)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)[![](https://avatars.githubusercontent.com/u/52314078?v=4&size=64)](https://github.com/vaebe)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)

[Alert 提示](https://element-plus.org/zh-CN/component/alert)

[Drawer 抽屉](https://element-plus.org/zh-CN/component/drawer)




---
## [feedback/drawer] Drawer 抽屉
> 官方文档: https://element-plus.org/zh-CN/component/drawer.html

---

# Drawer 抽屉 [​](#drawer-抽屉)

更新日志待解决

8

有些时候, `Dialog` 组件并不满足我们的需求, 比如你的表单很长, 亦或是你需要临时展示一些文档, `Drawer` 拥有和 `Dialog` 几乎相同的 API, 在 UI 上带来不一样的体验.

TIP

在 Vue 3 之后的版本 v-model 可以用于任何一个组件，`visible.sync` 已被移除，请使用 `v-model="visibilityBinding"` 来控制抽屉组件的显示和隐藏状态。

## 基础用法 [​](#基础用法)

呼出一个临时的侧边栏, 可以从多个方向呼出

你必须像 `Dialog`一样为 `Drawer` 设置 `model-value` 属性来控制 `Drawer` 的显示与隐藏状态，该属性接受一个 `boolean` 类型。 `Drawer` 包含三部分: `title` & `body` & `footer`, 其中 `title` 是一个具名 slot, 你还可以通过 `title` 属性来设置标题, 默认情况下它是一个空字符串, 其中 `body` 部分是 `Drawer` 组件的主区域, 它包含了用户定义的主要内容. footer和title用法一致, 用来显示页脚信息. 当 `Drawer` 打开时，默认设置是**从右至左**打开 **30%** 浏览器宽度。 你可以通过传入对应的 `direction` 和 `size` 属性来修改这一默认行为。 下面一个示例将展示如何使用 `before-close` API，更多详细用法请参考页面底部的 API 部分。

left to rightright to lefttop to bottombottom to top

open with footer

cancelconfirm

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cImRpcmVjdGlvblwiPlxuICAgIDxlbC1yYWRpbyB2YWx1ZT1cImx0clwiPmxlZnQgdG8gcmlnaHQ8L2VsLXJhZGlvPlxuICAgIDxlbC1yYWRpbyB2YWx1ZT1cInJ0bFwiPnJpZ2h0IHRvIGxlZnQ8L2VsLXJhZGlvPlxuICAgIDxlbC1yYWRpbyB2YWx1ZT1cInR0YlwiPnRvcCB0byBib3R0b208L2VsLXJhZGlvPlxuICAgIDxlbC1yYWRpbyB2YWx1ZT1cImJ0dFwiPmJvdHRvbSB0byB0b3A8L2VsLXJhZGlvPlxuICA8L2VsLXJhZGlvLWdyb3VwPlxuXG4gIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBzdHlsZT1cIm1hcmdpbi1sZWZ0OiAxNnB4XCIgQGNsaWNrPVwiZHJhd2VyID0gdHJ1ZVwiPlxuICAgIG9wZW5cbiAgPC9lbC1idXR0b24+XG4gIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBzdHlsZT1cIm1hcmdpbi1sZWZ0OiAxNnB4XCIgQGNsaWNrPVwiZHJhd2VyMiA9IHRydWVcIj5cbiAgICB3aXRoIGZvb3RlclxuICA8L2VsLWJ1dHRvbj5cblxuICA8ZWwtZHJhd2VyXG4gICAgdi1tb2RlbD1cImRyYXdlclwiXG4gICAgdGl0bGU9XCJJIGFtIHRoZSB0aXRsZVwiXG4gICAgOmRpcmVjdGlvbj1cImRpcmVjdGlvblwiXG4gICAgOmJlZm9yZS1jbG9zZT1cImhhbmRsZUNsb3NlXCJcbiAgPlxuICAgIDxzcGFuPkhpLCB0aGVyZSE8L3NwYW4+XG4gIDwvZWwtZHJhd2VyPlxuICA8ZWwtZHJhd2VyIHYtbW9kZWw9XCJkcmF3ZXIyXCIgOmRpcmVjdGlvbj1cImRpcmVjdGlvblwiPlxuICAgIDx0ZW1wbGF0ZSAjaGVhZGVyPlxuICAgICAgPGg0PnNldCB0aXRsZSBieSBzbG90PC9oND5cbiAgICA8L3RlbXBsYXRlPlxuICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD5cbiAgICAgIDxkaXY+XG4gICAgICAgIDxlbC1yYWRpbyB2LW1vZGVsPVwicmFkaW8xXCIgdmFsdWU9XCJPcHRpb24gMVwiIHNpemU9XCJsYXJnZVwiPlxuICAgICAgICAgIE9wdGlvbiAxXG4gICAgICAgIDwvZWwtcmFkaW8+XG4gICAgICAgIDxlbC1yYWRpbyB2LW1vZGVsPVwicmFkaW8xXCIgdmFsdWU9XCJPcHRpb24gMlwiIHNpemU9XCJsYXJnZVwiPlxuICAgICAgICAgIE9wdGlvbiAyXG4gICAgICAgIDwvZWwtcmFkaW8+XG4gICAgICA8L2Rpdj5cbiAgICA8L3RlbXBsYXRlPlxuICAgIDx0ZW1wbGF0ZSAjZm9vdGVyPlxuICAgICAgPGRpdiBzdHlsZT1cImZsZXg6IGF1dG9cIj5cbiAgICAgICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJjYW5jZWxDbGlja1wiPmNhbmNlbDwvZWwtYnV0dG9uPlxuICAgICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwiY29uZmlybUNsaWNrXCI+Y29uZmlybTwvZWwtYnV0dG9uPlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1kcmF3ZXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgRWxNZXNzYWdlQm94IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbXBvcnQgdHlwZSB7IERyYXdlclByb3BzIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBkcmF3ZXIgPSByZWYoZmFsc2UpXG5jb25zdCBkcmF3ZXIyID0gcmVmKGZhbHNlKVxuY29uc3QgZGlyZWN0aW9uID0gcmVmPERyYXdlclByb3BzWydkaXJlY3Rpb24nXT4oJ3J0bCcpXG5jb25zdCByYWRpbzEgPSByZWYoJ09wdGlvbiAxJylcbmNvbnN0IGhhbmRsZUNsb3NlID0gKGRvbmU6ICgpID0+IHZvaWQpID0+IHtcbiAgRWxNZXNzYWdlQm94LmNvbmZpcm0oJ0FyZSB5b3Ugc3VyZSB5b3Ugd2FudCB0byBjbG9zZSB0aGlzPycpXG4gICAgLnRoZW4oKCkgPT4ge1xuICAgICAgZG9uZSgpXG4gICAgfSlcbiAgICAuY2F0Y2goKCkgPT4ge1xuICAgICAgLy8gY2F0Y2ggZXJyb3JcbiAgICB9KVxufVxuZnVuY3Rpb24gY2FuY2VsQ2xpY2soKSB7XG4gIGRyYXdlcjIudmFsdWUgPSBmYWxzZVxufVxuZnVuY3Rpb24gY29uZmlybUNsaWNrKCkge1xuICBFbE1lc3NhZ2VCb3guY29uZmlybShgQXJlIHlvdSBjb25maXJtIHRvIGNob3NlICR7cmFkaW8xLnZhbHVlfSA/YClcbiAgICAudGhlbigoKSA9PiB7XG4gICAgICBkcmF3ZXIyLnZhbHVlID0gZmFsc2VcbiAgICB9KVxuICAgIC5jYXRjaCgoKSA9PiB7XG4gICAgICAvLyBjYXRjaCBlcnJvclxuICAgIH0pXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/drawer/basic-usage.vue)_

vue

```
<template>
  <el-radio-group v-model="direction">
    <el-radio value="ltr">left to right</el-radio>
    <el-radio value="rtl">right to left</el-radio>
    <el-radio value="ttb">top to bottom</el-radio>
    <el-radio value="btt">bottom to top</el-radio>
  </el-radio-group>

  <el-button type="primary" style="margin-left: 16px" @click="drawer = true">
    open
  </el-button>
  <el-button type="primary" style="margin-left: 16px" @click="drawer2 = true">
    with footer
  </el-button>

  <el-drawer
    v-model="drawer"
    title="I am the title"
    :direction="direction"
    :before-close="handleClose"
  >
    <span>Hi, there!</span>
  </el-drawer>
  <el-drawer v-model="drawer2" :direction="direction">
    <template #header>
      <h4>set title by slot</h4>
    </template>
    <template #default>
      <div>
        <el-radio v-model="radio1" value="Option 1" size="large">
          Option 1
        </el-radio>
        <el-radio v-model="radio1" value="Option 2" size="large">
          Option 2
        </el-radio>
      </div>
    </template>
    <template #footer>
      <div style="flex: auto">
        <el-button @click="cancelClick">cancel</el-button>
        <el-button type="primary" @click="confirmClick">confirm</el-button>
      </div>
    </template>
  </el-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElMessageBox } from 'element-plus'

import type { DrawerProps } from 'element-plus'

const drawer = ref(false)
const drawer2 = ref(false)
const direction = ref<DrawerProps['direction']>('rtl')
const radio1 = ref('Option 1')
const handleClose = (done: () => void) => {
  ElMessageBox.confirm('Are you sure you want to close this?')
    .then(() => {
      done()
    })
    .catch(() => {
      // catch error
    })
}
function cancelClick() {
  drawer2.value = false
}
function confirmClick() {
  ElMessageBox.confirm(`Are you confirm to chose ${radio1.value} ?`)
    .then(() => {
      drawer2.value = false
    })
    .catch(() => {
      // catch error
    })
}
</script>
```

隐藏源代码

## 不添加 Title [​](#不添加-title)

当你不需要标题的时候，你可以将它移除。

通过设置 `with-header` 属性为 **false** 来控制是否显示标题。 如果你的应用需要具备可访问性，请务必设置好 `title`。

open

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwiZHJhd2VyID0gdHJ1ZVwiPiBvcGVuIDwvZWwtYnV0dG9uPlxuXG4gIDxlbC1kcmF3ZXIgdi1tb2RlbD1cImRyYXdlclwiIHRpdGxlPVwiSSBhbSB0aGUgdGl0bGVcIiA6d2l0aC1oZWFkZXI9XCJmYWxzZVwiPlxuICAgIDxzcGFuPkhpIHRoZXJlITwvc3Bhbj5cbiAgPC9lbC1kcmF3ZXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBkcmF3ZXIgPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/drawer/no-title.vue)_

vue

```
<template>
  <el-button type="primary" @click="drawer = true"> open </el-button>

  <el-drawer v-model="drawer" title="I am the title" :with-header="false">
    <span>Hi there!</span>
  </el-drawer>
</template>

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

const drawer = ref(false)
</script>
```

隐藏源代码

## 自定义内容 [​](#自定义内容)

像 `Dialog` 组件一样，`Drawer` 也可以用来显示多种不同的交互。

Open Drawer with nested table Open Drawer with nested form

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHRleHQgQGNsaWNrPVwidGFibGUgPSB0cnVlXCI+XG4gICAgT3BlbiBEcmF3ZXIgd2l0aCBuZXN0ZWQgdGFibGVcbiAgPC9lbC1idXR0b24+XG4gIDxlbC1idXR0b24gdGV4dCBAY2xpY2s9XCJkaWFsb2cgPSB0cnVlXCI+XG4gICAgT3BlbiBEcmF3ZXIgd2l0aCBuZXN0ZWQgZm9ybVxuICA8L2VsLWJ1dHRvbj5cbiAgPGVsLWRyYXdlclxuICAgIHYtbW9kZWw9XCJ0YWJsZVwiXG4gICAgdGl0bGU9XCJJIGhhdmUgYSBuZXN0ZWQgdGFibGUgaW5zaWRlIVwiXG4gICAgZGlyZWN0aW9uPVwicnRsXCJcbiAgICBzaXplPVwiNTAlXCJcbiAgPlxuICAgIDxlbC10YWJsZSA6ZGF0YT1cImdyaWREYXRhXCI+XG4gICAgICA8ZWwtdGFibGUtY29sdW1uIHByb3BlcnR5PVwiZGF0ZVwiIGxhYmVsPVwiRGF0ZVwiIHdpZHRoPVwiMTUwXCIgLz5cbiAgICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcGVydHk9XCJuYW1lXCIgbGFiZWw9XCJOYW1lXCIgd2lkdGg9XCIyMDBcIiAvPlxuICAgICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wZXJ0eT1cImFkZHJlc3NcIiBsYWJlbD1cIkFkZHJlc3NcIiAvPlxuICAgIDwvZWwtdGFibGU+XG4gIDwvZWwtZHJhd2VyPlxuXG4gIDxlbC1kcmF3ZXJcbiAgICB2LW1vZGVsPVwiZGlhbG9nXCJcbiAgICB0aXRsZT1cIkkgaGF2ZSBhIG5lc3RlZCBmb3JtIGluc2lkZSFcIlxuICAgIDpiZWZvcmUtY2xvc2U9XCJoYW5kbGVDbG9zZVwiXG4gICAgZGlyZWN0aW9uPVwibHRyXCJcbiAgICBjbGFzcz1cImRlbW8tZHJhd2VyXCJcbiAgPlxuICAgIDxkaXYgY2xhc3M9XCJkZW1vLWRyYXdlcl9fY29udGVudFwiPlxuICAgICAgPGVsLWZvcm0gOm1vZGVsPVwiZm9ybVwiPlxuICAgICAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiTmFtZVwiIDpsYWJlbC13aWR0aD1cImZvcm1MYWJlbFdpZHRoXCI+XG4gICAgICAgICAgPGVsLWlucHV0IHYtbW9kZWw9XCJmb3JtLm5hbWVcIiBhdXRvY29tcGxldGU9XCJvZmZcIiAvPlxuICAgICAgICA8L2VsLWZvcm0taXRlbT5cbiAgICAgICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIkFyZWFcIiA6bGFiZWwtd2lkdGg9XCJmb3JtTGFiZWxXaWR0aFwiPlxuICAgICAgICAgIDxlbC1zZWxlY3RcbiAgICAgICAgICAgIHYtbW9kZWw9XCJmb3JtLnJlZ2lvblwiXG4gICAgICAgICAgICBwbGFjZWhvbGRlcj1cIlBsZWFzZSBzZWxlY3QgYWN0aXZpdHkgYXJlYVwiXG4gICAgICAgICAgPlxuICAgICAgICAgICAgPGVsLW9wdGlvbiBsYWJlbD1cIkFyZWExXCIgdmFsdWU9XCJzaGFuZ2hhaVwiIC8+XG4gICAgICAgICAgICA8ZWwtb3B0aW9uIGxhYmVsPVwiQXJlYTJcIiB2YWx1ZT1cImJlaWppbmdcIiAvPlxuICAgICAgICAgIDwvZWwtc2VsZWN0PlxuICAgICAgICA8L2VsLWZvcm0taXRlbT5cbiAgICAgIDwvZWwtZm9ybT5cbiAgICAgIDxkaXYgY2xhc3M9XCJkZW1vLWRyYXdlcl9fZm9vdGVyXCI+XG4gICAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwiY2FuY2VsRm9ybVwiPkNhbmNlbDwvZWwtYnV0dG9uPlxuICAgICAgICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgOmxvYWRpbmc9XCJsb2FkaW5nXCIgQGNsaWNrPVwib25DbGlja1wiPlxuICAgICAgICAgIHt7IGxvYWRpbmcgPyAnU3VibWl0dGluZyAuLi4nIDogJ1N1Ym1pdCcgfX1cbiAgICAgICAgPC9lbC1idXR0b24+XG4gICAgICA8L2Rpdj5cbiAgICA8L2Rpdj5cbiAgPC9lbC1kcmF3ZXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVhY3RpdmUsIHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVsTWVzc2FnZUJveCB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3QgZm9ybUxhYmVsV2lkdGggPSAnODBweCdcbmxldCB0aW1lclxuXG5jb25zdCB0YWJsZSA9IHJlZihmYWxzZSlcbmNvbnN0IGRpYWxvZyA9IHJlZihmYWxzZSlcbmNvbnN0IGxvYWRpbmcgPSByZWYoZmFsc2UpXG5cbmNvbnN0IGZvcm0gPSByZWFjdGl2ZSh7XG4gIG5hbWU6ICcnLFxuICByZWdpb246ICcnLFxuICBkYXRlMTogJycsXG4gIGRhdGUyOiAnJyxcbiAgZGVsaXZlcnk6IGZhbHNlLFxuICB0eXBlOiBbXSxcbiAgcmVzb3VyY2U6ICcnLFxuICBkZXNjOiAnJyxcbn0pXG5cbmNvbnN0IGdyaWREYXRhID0gW1xuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDInLFxuICAgIG5hbWU6ICdQZXRlciBQYXJrZXInLFxuICAgIGFkZHJlc3M6ICdRdWVlbnMsIE5ldyBZb3JrIENpdHknLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDQnLFxuICAgIG5hbWU6ICdQZXRlciBQYXJrZXInLFxuICAgIGFkZHJlc3M6ICdRdWVlbnMsIE5ldyBZb3JrIENpdHknLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgIG5hbWU6ICdQZXRlciBQYXJrZXInLFxuICAgIGFkZHJlc3M6ICdRdWVlbnMsIE5ldyBZb3JrIENpdHknLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDMnLFxuICAgIG5hbWU6ICdQZXRlciBQYXJrZXInLFxuICAgIGFkZHJlc3M6ICdRdWVlbnMsIE5ldyBZb3JrIENpdHknLFxuICB9LFxuXVxuXG5jb25zdCBvbkNsaWNrID0gKCkgPT4ge1xuICBsb2FkaW5nLnZhbHVlID0gdHJ1ZVxuICBzZXRUaW1lb3V0KCgpID0+IHtcbiAgICBsb2FkaW5nLnZhbHVlID0gZmFsc2VcbiAgICBkaWFsb2cudmFsdWUgPSBmYWxzZVxuICB9LCA0MDApXG59XG5cbmNvbnN0IGhhbmRsZUNsb3NlID0gKGRvbmUpID0+IHtcbiAgaWYgKGxvYWRpbmcudmFsdWUpIHtcbiAgICByZXR1cm5cbiAgfVxuICBFbE1lc3NhZ2VCb3guY29uZmlybSgnRG8geW91IHdhbnQgdG8gc3VibWl0PycpXG4gICAgLnRoZW4oKCkgPT4ge1xuICAgICAgbG9hZGluZy52YWx1ZSA9IHRydWVcbiAgICAgIHRpbWVyID0gc2V0VGltZW91dCgoKSA9PiB7XG4gICAgICAgIGRvbmUoKVxuICAgICAgICAvLyDliqjnlLvlhbPpl63pnIDopoHkuIDlrprnmoTml7bpl7RcbiAgICAgICAgc2V0VGltZW91dCgoKSA9PiB7XG4gICAgICAgICAgbG9hZGluZy52YWx1ZSA9IGZhbHNlXG4gICAgICAgIH0sIDQwMClcbiAgICAgIH0sIDIwMDApXG4gICAgfSlcbiAgICAuY2F0Y2goKCkgPT4ge1xuICAgICAgLy8gY2F0Y2ggZXJyb3JcbiAgICB9KVxufVxuXG5jb25zdCBjYW5jZWxGb3JtID0gKCkgPT4ge1xuICBsb2FkaW5nLnZhbHVlID0gZmFsc2VcbiAgZGlhbG9nLnZhbHVlID0gZmFsc2VcbiAgY2xlYXJUaW1lb3V0KHRpbWVyKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/drawer/customization-content.vue)_

vue

```
<template>
  <el-button text @click="table = true">
    Open Drawer with nested table
  </el-button>
  <el-button text @click="dialog = true">
    Open Drawer with nested form
  </el-button>
  <el-drawer
    v-model="table"
    title="I have a nested table inside!"
    direction="rtl"
    size="50%"
  >
    <el-table :data="gridData">
      <el-table-column property="date" label="Date" width="150" />
      <el-table-column property="name" label="Name" width="200" />
      <el-table-column property="address" label="Address" />
    </el-table>
  </el-drawer>

  <el-drawer
    v-model="dialog"
    title="I have a nested form inside!"
    :before-close="handleClose"
    direction="ltr"
    class="demo-drawer"
  >
    <div class="demo-drawer__content">
      <el-form :model="form">
        <el-form-item label="Name" :label-width="formLabelWidth">
          <el-input v-model="form.name" autocomplete="off" />
        </el-form-item>
        <el-form-item label="Area" :label-width="formLabelWidth">
          <el-select
            v-model="form.region"
            placeholder="Please select activity area"
          >
            <el-option label="Area1" value="shanghai" />
            <el-option label="Area2" value="beijing" />
          </el-select>
        </el-form-item>
      </el-form>
      <div class="demo-drawer__footer">
        <el-button @click="cancelForm">Cancel</el-button>
        <el-button type="primary" :loading="loading" @click="onClick">
          {{ loading ? 'Submitting ...' : 'Submit' }}
        </el-button>
      </div>
    </div>
  </el-drawer>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
import { ElMessageBox } from 'element-plus'

const formLabelWidth = '80px'
let timer

const table = ref(false)
const dialog = ref(false)
const loading = ref(false)

const form = reactive({
  name: '',
  region: '',
  date1: '',
  date2: '',
  delivery: false,
  type: [],
  resource: '',
  desc: '',
})

const gridData = [
  {
    date: '2016-05-02',
    name: 'Peter Parker',
    address: 'Queens, New York City',
  },
  {
    date: '2016-05-04',
    name: 'Peter Parker',
    address: 'Queens, New York City',
  },
  {
    date: '2016-05-01',
    name: 'Peter Parker',
    address: 'Queens, New York City',
  },
  {
    date: '2016-05-03',
    name: 'Peter Parker',
    address: 'Queens, New York City',
  },
]

const onClick = () => {
  loading.value = true
  setTimeout(() => {
    loading.value = false
    dialog.value = false
  }, 400)
}

const handleClose = (done) => {
  if (loading.value) {
    return
  }
  ElMessageBox.confirm('Do you want to submit?')
    .then(() => {
      loading.value = true
      timer = setTimeout(() => {
        done()
        // 动画关闭需要一定的时间
        setTimeout(() => {
          loading.value = false
        }, 400)
      }, 2000)
    })
    .catch(() => {
      // catch error
    })
}

const cancelForm = () => {
  loading.value = false
  dialog.value = false
  clearTimeout(timer)
}
</script>
```

隐藏源代码

## 自定义头部 [​](#自定义头部)

`header` 可用于自定义显示标题的区域。 为了保持可用性，除了使用此插槽外，使用 `title` 属性，或使用 `titleId` 插槽属性来指定哪些元素应该读取为抽屉标题。

Open Drawer with customized header

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIEBjbGljaz1cInZpc2libGUgPSB0cnVlXCI+XG4gICAgT3BlbiBEcmF3ZXIgd2l0aCBjdXN0b21pemVkIGhlYWRlclxuICA8L2VsLWJ1dHRvbj5cbiAgPGVsLWRyYXdlciB2LW1vZGVsPVwidmlzaWJsZVwiIDpzaG93LWNsb3NlPVwiZmFsc2VcIj5cbiAgICA8dGVtcGxhdGUgI2hlYWRlcj1cInsgY2xvc2UsIHRpdGxlSWQsIHRpdGxlQ2xhc3MgfVwiPlxuICAgICAgPGg0IDppZD1cInRpdGxlSWRcIiA6Y2xhc3M9XCJ0aXRsZUNsYXNzXCI+VGhpcyBpcyBhIGN1c3RvbSBoZWFkZXIhPC9oND5cbiAgICAgIDxlbC1idXR0b24gdHlwZT1cImRhbmdlclwiIEBjbGljaz1cImNsb3NlXCI+XG4gICAgICAgIDxlbC1pY29uIGNsYXNzPVwiZWwtaWNvbi0tbGVmdFwiPjxDaXJjbGVDbG9zZUZpbGxlZCAvPjwvZWwtaWNvbj5cbiAgICAgICAgQ2xvc2VcbiAgICAgIDwvZWwtYnV0dG9uPlxuICAgIDwvdGVtcGxhdGU+XG4gICAgVGhpcyBpcyBkcmF3ZXIgY29udGVudC5cbiAgPC9lbC1kcmF3ZXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgQ2lyY2xlQ2xvc2VGaWxsZWQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgdmlzaWJsZSA9IHJlZihmYWxzZSlcbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/drawer/customization-header.vue)_

vue

```
<template>
  <el-button @click="visible = true">
    Open Drawer with customized header
  </el-button>
  <el-drawer v-model="visible" :show-close="false">
    <template #header="{ close, titleId, titleClass }">
      <h4 :id="titleId" :class="titleClass">This is a custom header!</h4>
      <el-button type="danger" @click="close">
        <el-icon class="el-icon--left"><CircleCloseFilled /></el-icon>
        Close
      </el-button>
    </template>
    This is drawer content.
  </el-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { CircleCloseFilled } from '@element-plus/icons-vue'

const visible = ref(false)
</script>
```

隐藏源代码

## 可调整抽屉2.11.0 [​](#可调整抽屉)

尝试拖动边缘部分。

设置`resizable`属性为`true`以做到拖拽

toprightbottomleft

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcmFkaW8tZ3JvdXAgdi1tb2RlbD1cImRpcmVjdGlvblwiIEBjaGFuZ2U9XCJkcmF3ZXIgPSB0cnVlXCI+XG4gICAgPGVsLXJhZGlvLWJ1dHRvbiB2YWx1ZT1cInR0YlwiPnRvcDwvZWwtcmFkaW8tYnV0dG9uPlxuICAgIDxlbC1yYWRpby1idXR0b24gdmFsdWU9XCJydGxcIj5yaWdodDwvZWwtcmFkaW8tYnV0dG9uPlxuICAgIDxlbC1yYWRpby1idXR0b24gdmFsdWU9XCJidHRcIj5ib3R0b208L2VsLXJhZGlvLWJ1dHRvbj5cbiAgICA8ZWwtcmFkaW8tYnV0dG9uIHZhbHVlPVwibHRyXCI+bGVmdDwvZWwtcmFkaW8tYnV0dG9uPlxuICA8L2VsLXJhZGlvLWdyb3VwPlxuXG4gIDxlbC1kcmF3ZXIgdi1tb2RlbD1cImRyYXdlclwiIDpkaXJlY3Rpb249XCJkaXJlY3Rpb25cIiByZXNpemFibGU+XG4gICAgVGhpcyBpcyBkcmF3ZXIgY29udGVudC5cbiAgPC9lbC1kcmF3ZXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5pbXBvcnQgdHlwZSB7IERyYXdlclByb3BzIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBkaXJlY3Rpb24gPSByZWY8RHJhd2VyUHJvcHNbJ2RpcmVjdGlvbiddPigpXG5jb25zdCBkcmF3ZXIgPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/drawer/resizable.vue)_

vue

```
<template>
  <el-radio-group v-model="direction" @change="drawer = true">
    <el-radio-button value="ttb">top</el-radio-button>
    <el-radio-button value="rtl">right</el-radio-button>
    <el-radio-button value="btt">bottom</el-radio-button>
    <el-radio-button value="ltr">left</el-radio-button>
  </el-radio-group>

  <el-drawer v-model="drawer" :direction="direction" resizable>
    This is drawer content.
  </el-drawer>
</template>

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

import type { DrawerProps } from 'element-plus'

const direction = ref<DrawerProps['direction']>()
const drawer = ref(false)
</script>
```

隐藏源代码

## 嵌套抽屉 [​](#嵌套抽屉)

你可以像 `Dialog` 一样拥有多层嵌套的 `Drawer`

如果你需要在不同图层中多个抽屉，你必须设置 `append-to-body` 属性到 **true**

open

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwiZHJhd2VyID0gdHJ1ZVwiPiBvcGVuIDwvZWwtYnV0dG9uPlxuXG4gIDxlbC1kcmF3ZXIgdi1tb2RlbD1cImRyYXdlclwiIHRpdGxlPVwiSSdtIG91dGVyIERyYXdlclwiIHNpemU9XCI1MCVcIj5cbiAgICA8ZGl2PlxuICAgICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJpbm5lckRyYXdlciA9IHRydWVcIj5DbGljayBtZSE8L2VsLWJ1dHRvbj5cbiAgICAgIDxlbC1kcmF3ZXJcbiAgICAgICAgdi1tb2RlbD1cImlubmVyRHJhd2VyXCJcbiAgICAgICAgdGl0bGU9XCJJJ20gaW5uZXIgRHJhd2VyXCJcbiAgICAgICAgOmFwcGVuZC10by1ib2R5PVwidHJ1ZVwiXG4gICAgICAgIDpiZWZvcmUtY2xvc2U9XCJoYW5kbGVDbG9zZVwiXG4gICAgICA+XG4gICAgICAgIDxwPl8oOtC344Kd4oigKV88L3A+XG4gICAgICA8L2VsLWRyYXdlcj5cbiAgICA8L2Rpdj5cbiAgPC9lbC1kcmF3ZXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgRWxNZXNzYWdlQm94IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBkcmF3ZXIgPSByZWYoZmFsc2UpXG5jb25zdCBpbm5lckRyYXdlciA9IHJlZihmYWxzZSlcblxuY29uc3QgaGFuZGxlQ2xvc2UgPSAoZG9uZTogKCkgPT4gdm9pZCkgPT4ge1xuICBFbE1lc3NhZ2VCb3guY29uZmlybSgnWW91IHN0aWxsIGhhdmUgdW5zYXZlZCBkYXRhLCBwcm9jZWVkPycpXG4gICAgLnRoZW4oKCkgPT4ge1xuICAgICAgZG9uZSgpXG4gICAgfSlcbiAgICAuY2F0Y2goKCkgPT4ge1xuICAgICAgLy8gY2F0Y2ggZXJyb3JcbiAgICB9KVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/drawer/nested-drawer.vue)_

vue

```
<template>
  <el-button type="primary" @click="drawer = true"> open </el-button>

  <el-drawer v-model="drawer" title="I'm outer Drawer" size="50%">
    <div>
      <el-button @click="innerDrawer = true">Click me!</el-button>
      <el-drawer
        v-model="innerDrawer"
        title="I'm inner Drawer"
        :append-to-body="true"
        :before-close="handleClose"
      >
        <p>_(:зゝ∠)_</p>
      </el-drawer>
    </div>
  </el-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElMessageBox } from 'element-plus'

const drawer = ref(false)
const innerDrawer = ref(false)

const handleClose = (done: () => void) => {
  ElMessageBox.confirm('You still have unsaved data, proceed?')
    .then(() => {
      done()
    })
    .catch(() => {
      // catch error
    })
}
</script>
```

隐藏源代码

## 模态框 [​](#模态框)

将 `modal` 设置为 `false` 将隐藏抽屉的模态层（遮罩层）。

从版本 2.11.7 起，新增了 `modal-penetrable` 属性，该属性可设置为“可穿透”。

Open the modal Drawer

Cancel Confirm

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cImRyYXdlclZpc2libGUgPSB0cnVlXCI+XG4gICAgT3BlbiB0aGUgbW9kYWwgRHJhd2VyXG4gIDwvZWwtYnV0dG9uPlxuXG4gIDxlbC1kcmF3ZXIgdi1tb2RlbD1cImRyYXdlclZpc2libGVcIiA6bW9kYWw9XCJmYWxzZVwiIG1vZGFsLXBlbmV0cmFibGU+XG4gICAgPHNwYW4+SXQncyBhIG1vZGFsIERyYXdlcjwvc3Bhbj5cbiAgICA8dGVtcGxhdGUgI2Zvb3Rlcj5cbiAgICAgIDxkaXYgY2xhc3M9XCJkcmF3ZXItZm9vdGVyXCI+XG4gICAgICAgIDxlbC1idXR0b24gQGNsaWNrPVwiZHJhd2VyVmlzaWJsZSA9IGZhbHNlXCI+Q2FuY2VsPC9lbC1idXR0b24+XG4gICAgICAgIDxlbC1idXR0b24gdHlwZT1cInByaW1hcnlcIiBAY2xpY2s9XCJkcmF3ZXJWaXNpYmxlID0gZmFsc2VcIj5cbiAgICAgICAgICBDb25maXJtXG4gICAgICAgIDwvZWwtYnV0dG9uPlxuICAgICAgPC9kaXY+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1kcmF3ZXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBkcmF3ZXJWaXNpYmxlID0gcmVmKGZhbHNlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/drawer/modal.vue)_

vue

```
<template>
  <el-button plain @click="drawerVisible = true">
    Open the modal Drawer
  </el-button>

  <el-drawer v-model="drawerVisible" :modal="false" modal-penetrable>
    <span>It's a modal Drawer</span>
    <template #footer>
      <div class="drawer-footer">
        <el-button @click="drawerVisible = false">Cancel</el-button>
        <el-button type="primary" @click="drawerVisible = false">
          Confirm
        </el-button>
      </div>
    </template>
  </el-drawer>
</template>

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

const drawerVisible = ref(false)
</script>
```

隐藏源代码

TIP

Drawer 的内容是懒渲染的，即在第一次被打开之前，传入的默认 slot 不会被渲染到 DOM 上。 因此，如果需要执行 DOM 操作，或通过 `ref` 获取相应组件，请在 `open` 事件回调中进行。

TIP

Drawer 提供了一个名为 `destroy-on-close` 的 API，这是一个标志变量，用于指示在 Drawer 关闭后是否销毁其中的子内容。 当你需要每次打开抽屉都要调用 `mounted` 生命周期时，可以使用此 API。

## API [​](#api)

### 属性 [​](#属性)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| model-value / v-model | 是否显示 Drawer | `boolean` | false |
| append-to-body | Drawer 自身是否插入至 body 元素上。嵌套的 Drawer 必须指定该属性并赋值为 **true** | `boolean` | false |
| append-to 2.8.0 | 挂载到哪个 DOM 元素 将覆盖 `append-to-body` | `CSSSelector` / `HTMLElement` | body |
| lock-scroll | 是否在 Drawer 出现时将 body 滚动锁定 | `boolean` | true |
| before-close | 关闭前的回调，会暂停 Drawer 的关闭 | `Function` | — |
| close-on-click-modal | 是否可以通过点击 modal 关闭 Drawer | `boolean` | true |
| close-on-press-escape | 是否可以通过按下 ESC 关闭 Drawer | `boolean` | true |
| open-delay | Drawer 打开的延时时间，单位毫秒 | `number` | 0 |
| close-delay | Drawer 关闭的延时时间，单位毫秒 | `number` | 0 |
| destroy-on-close | 控制是否在关闭 Drawer 之后将子元素全部销毁 | `boolean` | false |
| modal | 是否需要遮罩层 | `boolean` | true |
| modal-penetrable 2.11.7 | 是否允许穿透遮罩层。 modal 属性必须为 `false`。 | `boolean` | false |
| direction | Drawer 打开的方向 | `enum` | rtl |
| resizable 2.11.0 | 为抽屉启用可调整大小的功能 | `boolean` | false |
| show-close | 是否显示关闭按钮 | `boolean` | true |
| size | Drawer 窗体的大小, 当使用 `number` 类型时, 以像素为单位, 当使用 `string` 类型时, 请传入 'x%', 否则便会以 `number` 类型解释 | `number` / `string` | 30% |
| title | Drawer 的标题，也可通过具名 slot （见下表）传入 | `string` | — |
| with-header | 控制是否显示 header 栏, 默认为 true, 当此项为 false 时, title attribute 和 title slot 均不生效 | `boolean` | true |
| modal-class | 遮罩层的自定义类名 | `string` | — |
| header-class 2.9.3 | header 部分的自定义 class 名 | `string` | — |
| body-class 2.9.3 | body 部分的自定义 class 名 | `string` | — |
| footer-class 2.9.3 | footer 部分的自定义 class 名 | `string` | — |
| z-index | 设置 z-index | `number` | — |
| header-aria-level a11y | header 的 `aria-level` 属性 | `string` | 2 |
| custom-class deprecated | Drawer 的自定义类名 | `string` | — |

WARNING

`custom-class` 已被 **弃用**，**将会于** 2.3.0 移除, 请使用 `class`。

### 事件 [​](#事件)

| 事件名称 | 说明 | 类型 |
| --- | --- | --- |
| open | Drawer 打开的回调 | `Function` |
| opened | Drawer 打开动画结束时的回调 | `Function` |
| close | Drawer 关闭的回调 | `Function` |
| closed | Drawer 关闭动画结束时的回调 | `Function` |
| open-auto-focus | 输入焦点聚焦在 Drawer 内容时的回调 | `Function` |
| close-auto-focus | 输入焦点从 Drawer 内容失焦时的回调 | `Function` |
| resize-start 2.11.8 | 当开始调整大小时触发（当启用 `resizable` 时） | `Function` |
| resize 2.11.8 | 调整大小时触发（启用 `resizable` 时） | `Function` |
| resize-end 2.11.8 | 当调整大小结束时触发（当启用 `resizable` 时） | `Function` |

### 插槽 [​](#插槽)

| 名称 | 说明 |
| --- | --- |
| default | Drawer 的内容 |
| header | Drawer 标题的内容；会替换标题部分，但不会移除关闭按钮。 |
| footer | Drawer 页脚部分 |
| title deprecated | 与 header 作用相同 请使用 header |

WARNING

`title` 已被**弃用**，并将在 3.0.0 版本中**移除**，请使用 `header` 代替。

### 暴露 [​](#暴露)

| 名称 | 详情 |
| --- | --- |
| handleClose | 用于关闭 Drawer, 该方法会调用传入的 `before-close` 方法 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/drawer) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/drawer.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/drawer.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/82012629?v=4&size=64)](https://github.com/0song)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/138789658?v=4&size=64)](https://github.com/StudiousGao)[![](https://avatars.githubusercontent.com/u/69580637?v=4&size=64)](https://github.com/jevin98)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/80906525?v=4&size=64)](https://github.com/drylint)[![](https://avatars.githubusercontent.com/u/108655466?v=4&size=64)](https://github.com/Karolis-Stoncius)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/43806319?v=4&size=64)](https://github.com/qianjiachun)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/23442840?v=4&size=64)](https://github.com/liunnn1994)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/87807886?v=4&size=64)](https://github.com/briver0825)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)

[Dialog 对话框](https://element-plus.org/zh-CN/component/dialog)

[Loading 加载](https://element-plus.org/zh-CN/component/loading)




---
## [feedback/loading] Loading 加载
> 官方文档: https://element-plus.org/zh-CN/component/loading.html

---

# Loading 加载 [​](#loading-加载)

更新日志待解决

12

加载数据时显示动效。

## 区域加载 [​](#区域加载)

在需要的时候展示加载动画，防止页面失去响应提高用户体验（例如表格）。

Element Plus 提供了两种调用 Loading 的方法：指令和服务。 对于自定义指令 `v-loading`，只需要绑定 `boolean` 值即可。 默认状况下，Loading 遮罩会插入到绑定元素的子节点。 通过添加 `body` 修饰符，可以使遮罩插入至 Dom 中的 body 上。

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_1_column_1" width="180"><col name="el-table_1_column_2" width="180"><col name="el-table_1_column_3" width="533"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">John Smith</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No.1518, Jinshajiang Road, Putuo District</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">John Smith</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No.1518, Jinshajiang Road, Putuo District</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_1_column_1 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_1_column_2 el-table__cell"><div class="cell">John Smith</div></td><td colspan="1" rowspan="1" class="el-table_1_column_3 el-table__cell"><div class="cell">No.1518, Jinshajiang Road, Putuo District</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGUgdi1sb2FkaW5nPVwibG9hZGluZ1wiIDpkYXRhPVwidGFibGVEYXRhXCIgc3R5bGU9XCJ3aWR0aDogMTAwJVwiPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImRhdGVcIiBsYWJlbD1cIkRhdGVcIiB3aWR0aD1cIjE4MFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIHdpZHRoPVwiMTgwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhZGRyZXNzXCIgbGFiZWw9XCJBZGRyZXNzXCIgLz5cbiAgPC9lbC10YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGxvYWRpbmcgPSByZWYodHJ1ZSlcblxuY29uc3QgdGFibGVEYXRhID0gW1xuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDInLFxuICAgIG5hbWU6ICdKb2huIFNtaXRoJyxcbiAgICBhZGRyZXNzOiAnTm8uMTUxOCwgIEppbnNoYWppYW5nIFJvYWQsIFB1dHVvIERpc3RyaWN0JyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA0JyxcbiAgICBuYW1lOiAnSm9obiBTbWl0aCcsXG4gICAgYWRkcmVzczogJ05vLjE1MTgsICBKaW5zaGFqaWFuZyBSb2FkLCBQdXR1byBEaXN0cmljdCcsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgbmFtZTogJ0pvaG4gU21pdGgnLFxuICAgIGFkZHJlc3M6ICdOby4xNTE4LCAgSmluc2hhamlhbmcgUm9hZCwgUHV0dW8gRGlzdHJpY3QnLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbmJvZHkge1xuICBtYXJnaW46IDA7XG59XG4uZXhhbXBsZS1zaG93Y2FzZSAuZWwtbG9hZGluZy1tYXNrIHtcbiAgei1pbmRleDogOTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/loading/basic.vue)_

vue

```
<template>
  <el-table v-loading="loading" :data="tableData" style="width: 100%">
    <el-table-column prop="date" label="Date" width="180" />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" />
  </el-table>
</template>

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

const loading = ref(true)

const tableData = [
  {
    date: '2016-05-02',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
  {
    date: '2016-05-04',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
  {
    date: '2016-05-01',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
]
</script>

<style>
body {
  margin: 0;
}
.example-showcase .el-loading-mask {
  z-index: 9;
}
</style>
```

隐藏源代码

## 自定义加载中组件内容 [​](#自定义加载中组件内容)

你可以自定义加载中组件的文字，图标，以及背景颜色。

在绑定了`v-loading`指令的元素上添加`element-loading-text`属性，其值会被渲染为加载文案，并显示在加载图标的下方。 类似地，`element-loading-spinner`、`element-loading-background` 和 `element-loading-svg` 属性分别用来设定 svg 图标、背景色值、加载图标。

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_2_column_4" width="180"><col name="el-table_2_column_5" width="180"><col name="el-table_2_column_6" width="533"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_2_column_4 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_2_column_5 el-table__cell"><div class="cell">John Smith</div></td><td colspan="1" rowspan="1" class="el-table_2_column_6 el-table__cell"><div class="cell">No.1518, Jinshajiang Road, Putuo District</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_2_column_4 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_2_column_5 el-table__cell"><div class="cell">John Smith</div></td><td colspan="1" rowspan="1" class="el-table_2_column_6 el-table__cell"><div class="cell">No.1518, Jinshajiang Road, Putuo District</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_2_column_4 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_2_column_5 el-table__cell"><div class="cell">John Smith</div></td><td colspan="1" rowspan="1" class="el-table_2_column_6 el-table__cell"><div class="cell">No.1518, Jinshajiang Road, Putuo District</div></td></tr></tbody></table>

Loading...

|
Date

 |

Name

 |

Address

 |
| --- | --- | --- |

<table class="el-table__body" cellspacing="0" cellpadding="0" border="0" style="table-layout: fixed; width: 893px;"><colgroup><col name="el-table_3_column_7" width="180"><col name="el-table_3_column_8" width="180"><col name="el-table_3_column_9" width="533"></colgroup><tbody tabindex="-1"><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_3_column_7 el-table__cell"><div class="cell">2016-05-02</div></td><td colspan="1" rowspan="1" class="el-table_3_column_8 el-table__cell"><div class="cell">John Smith</div></td><td colspan="1" rowspan="1" class="el-table_3_column_9 el-table__cell"><div class="cell">No.1518, Jinshajiang Road, Putuo District</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_3_column_7 el-table__cell"><div class="cell">2016-05-04</div></td><td colspan="1" rowspan="1" class="el-table_3_column_8 el-table__cell"><div class="cell">John Smith</div></td><td colspan="1" rowspan="1" class="el-table_3_column_9 el-table__cell"><div class="cell">No.1518, Jinshajiang Road, Putuo District</div></td></tr><tr style="" class="el-table__row"><td colspan="1" rowspan="1" class="el-table_3_column_7 el-table__cell"><div class="cell">2016-05-01</div></td><td colspan="1" rowspan="1" class="el-table_3_column_8 el-table__cell"><div class="cell">John Smith</div></td><td colspan="1" rowspan="1" class="el-table_3_column_9 el-table__cell"><div class="cell">No.1518, Jinshajiang Road, Putuo District</div></td></tr></tbody></table>

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdGFibGVcbiAgICB2LWxvYWRpbmc9XCJsb2FkaW5nXCJcbiAgICBlbGVtZW50LWxvYWRpbmctdGV4dD1cIkxvYWRpbmcuLi5cIlxuICAgIDplbGVtZW50LWxvYWRpbmctc3Bpbm5lcj1cInN2Z1wiXG4gICAgZWxlbWVudC1sb2FkaW5nLXN2Zy12aWV3LWJveD1cIi0xMCwgLTEwLCA1MCwgNTBcIlxuICAgIGVsZW1lbnQtbG9hZGluZy1iYWNrZ3JvdW5kPVwicmdiYSgxMjIsIDEyMiwgMTIyLCAwLjgpXCJcbiAgICA6ZGF0YT1cInRhYmxlRGF0YVwiXG4gICAgc3R5bGU9XCJ3aWR0aDogMTAwJVwiXG4gID5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJkYXRlXCIgbGFiZWw9XCJEYXRlXCIgd2lkdGg9XCIxODBcIiAvPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cIm5hbWVcIiBsYWJlbD1cIk5hbWVcIiB3aWR0aD1cIjE4MFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwiYWRkcmVzc1wiIGxhYmVsPVwiQWRkcmVzc1wiIC8+XG4gIDwvZWwtdGFibGU+XG4gIDxlbC10YWJsZVxuICAgIHYtbG9hZGluZz1cImxvYWRpbmdcIlxuICAgIDplbGVtZW50LWxvYWRpbmctc3ZnPVwic3ZnXCJcbiAgICBjbGFzcz1cImN1c3RvbS1sb2FkaW5nLXN2Z1wiXG4gICAgZWxlbWVudC1sb2FkaW5nLXN2Zy12aWV3LWJveD1cIi0xMCwgLTEwLCA1MCwgNTBcIlxuICAgIDpkYXRhPVwidGFibGVEYXRhXCJcbiAgICBzdHlsZT1cIndpZHRoOiAxMDAlXCJcbiAgPlxuICAgIDxlbC10YWJsZS1jb2x1bW4gcHJvcD1cImRhdGVcIiBsYWJlbD1cIkRhdGVcIiB3aWR0aD1cIjE4MFwiIC8+XG4gICAgPGVsLXRhYmxlLWNvbHVtbiBwcm9wPVwibmFtZVwiIGxhYmVsPVwiTmFtZVwiIHdpZHRoPVwiMTgwXCIgLz5cbiAgICA8ZWwtdGFibGUtY29sdW1uIHByb3A9XCJhZGRyZXNzXCIgbGFiZWw9XCJBZGRyZXNzXCIgLz5cbiAgPC9lbC10YWJsZT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGxvYWRpbmcgPSByZWYodHJ1ZSlcbmNvbnN0IHN2ZyA9IGBcbiAgICAgICAgPHBhdGggY2xhc3M9XCJwYXRoXCIgZD1cIlxuICAgICAgICAgIE0gMzAgMTVcbiAgICAgICAgICBMIDI4IDE3XG4gICAgICAgICAgTSAyNS42MSAyNS42MVxuICAgICAgICAgIEEgMTUgMTUsIDAsIDAsIDEsIDE1IDMwXG4gICAgICAgICAgQSAxNSAxNSwgMCwgMSwgMSwgMjcuOTkgNy41XG4gICAgICAgICAgTCAxNSAxNVxuICAgICAgICBcIiBzdHlsZT1cInN0cm9rZS13aWR0aDogNHB4OyBmaWxsOiByZ2JhKDAsIDAsIDAsIDApXCIvPlxuICAgICAgYFxuY29uc3QgdGFibGVEYXRhID0gW1xuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDInLFxuICAgIG5hbWU6ICdKb2huIFNtaXRoJyxcbiAgICBhZGRyZXNzOiAnTm8uMTUxOCwgIEppbnNoYWppYW5nIFJvYWQsIFB1dHVvIERpc3RyaWN0JyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA0JyxcbiAgICBuYW1lOiAnSm9obiBTbWl0aCcsXG4gICAgYWRkcmVzczogJ05vLjE1MTgsICBKaW5zaGFqaWFuZyBSb2FkLCBQdXR1byBEaXN0cmljdCcsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMScsXG4gICAgbmFtZTogJ0pvaG4gU21pdGgnLFxuICAgIGFkZHJlc3M6ICdOby4xNTE4LCAgSmluc2hhamlhbmcgUm9hZCwgUHV0dW8gRGlzdHJpY3QnLFxuICB9LFxuXVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5leGFtcGxlLXNob3djYXNlIC5lbC1sb2FkaW5nLW1hc2sge1xuICB6LWluZGV4OiA5O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/loading/customization.vue)_

vue

```
<template>
  <el-table
    v-loading="loading"
    element-loading-text="Loading..."
    :element-loading-spinner="svg"
    element-loading-svg-view-box="-10, -10, 50, 50"
    element-loading-background="rgba(122, 122, 122, 0.8)"
    :data="tableData"
    style="width: 100%"
  >
    <el-table-column prop="date" label="Date" width="180" />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" />
  </el-table>
  <el-table
    v-loading="loading"
    :element-loading-svg="svg"
    class="custom-loading-svg"
    element-loading-svg-view-box="-10, -10, 50, 50"
    :data="tableData"
    style="width: 100%"
  >
    <el-table-column prop="date" label="Date" width="180" />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" />
  </el-table>
</template>

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

const loading = ref(true)
const svg = `
        <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: rgba(0, 0, 0, 0)"/>
      `
const tableData = [
  {
    date: '2016-05-02',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
  {
    date: '2016-05-04',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
  {
    date: '2016-05-01',
    name: 'John Smith',
    address: 'No.1518,  Jinshajiang Road, Putuo District',
  },
]
</script>

<style>
.example-showcase .el-loading-mask {
  z-index: 9;
}
</style>
```

隐藏源代码

WARNING

虽然 `element-loading-spinner / element-loading-svg` 属性支持传入的 HTML 片段，但是动态在网站上渲染任意的 HTML 是非常危险的，因为很容易导致 [XSS 攻击](https://en.wikipedia.org/wiki/Cross-site_scripting)。 请确保 `element-loading-spinner / element-loading-svg`的内容是可信的， **不要**将用户提交的内容赋值给 `element-loading-spinner / element-loading-svg` 属性。

## 让加载组件铺满整个屏幕 [​](#让加载组件铺满整个屏幕)

加载数据时显示全屏动画。

当使用指令方式时，全屏遮罩需要添加`fullscreen`修饰符（遮罩会插入至 body 上） 此时若需要锁定屏幕的滚动，可以使用`lock`修饰符； 当使用服务方式时，遮罩默认即为全屏，无需额外设置。

As a directive As a service

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uXG4gICAgdi1sb2FkaW5nLmZ1bGxzY3JlZW4ubG9jaz1cImZ1bGxzY3JlZW5Mb2FkaW5nXCJcbiAgICB0eXBlPVwicHJpbWFyeVwiXG4gICAgQGNsaWNrPVwib3BlbkZ1bGxTY3JlZW4xXCJcbiAgPlxuICAgIEFzIGEgZGlyZWN0aXZlXG4gIDwvZWwtYnV0dG9uPlxuICA8ZWwtYnV0dG9uIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwib3BlbkZ1bGxTY3JlZW4yXCI+IEFzIGEgc2VydmljZSA8L2VsLWJ1dHRvbj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBFbExvYWRpbmcgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IGZ1bGxzY3JlZW5Mb2FkaW5nID0gcmVmKGZhbHNlKVxuY29uc3Qgb3BlbkZ1bGxTY3JlZW4xID0gKCkgPT4ge1xuICBmdWxsc2NyZWVuTG9hZGluZy52YWx1ZSA9IHRydWVcbiAgc2V0VGltZW91dCgoKSA9PiB7XG4gICAgZnVsbHNjcmVlbkxvYWRpbmcudmFsdWUgPSBmYWxzZVxuICB9LCAyMDAwKVxufVxuXG5jb25zdCBvcGVuRnVsbFNjcmVlbjIgPSAoKSA9PiB7XG4gIGNvbnN0IGxvYWRpbmcgPSBFbExvYWRpbmcuc2VydmljZSh7XG4gICAgbG9jazogdHJ1ZSxcbiAgICB0ZXh0OiAnTG9hZGluZycsXG4gICAgYmFja2dyb3VuZDogJ3JnYmEoMCwgMCwgMCwgMC43KScsXG4gIH0pXG4gIHNldFRpbWVvdXQoKCkgPT4ge1xuICAgIGxvYWRpbmcuY2xvc2UoKVxuICB9LCAyMDAwKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/loading/fullscreen.vue)_

vue

```
<template>
  <el-button
    v-loading.fullscreen.lock="fullscreenLoading"
    type="primary"
    @click="openFullScreen1"
  >
    As a directive
  </el-button>
  <el-button type="primary" @click="openFullScreen2"> As a service </el-button>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElLoading } from 'element-plus'

const fullscreenLoading = ref(false)
const openFullScreen1 = () => {
  fullscreenLoading.value = true
  setTimeout(() => {
    fullscreenLoading.value = false
  }, 2000)
}

const openFullScreen2 = () => {
  const loading = ElLoading.service({
    lock: true,
    text: 'Loading',
    background: 'rgba(0, 0, 0, 0.7)',
  })
  setTimeout(() => {
    loading.close()
  }, 2000)
}
</script>
```

隐藏源代码

## 以服务的方式来调用 [​](#以服务的方式来调用)

Loading 还可以以服务的方式调用。 你可以像这样引入 Loading 服务：

ts

```
import { ElLoading } from 'element-plus'
```

在你需要的时候通过下面的方式调用：

ts

```
ElLoading.service(options)
```

其中`options`参数为 Loading 的配置项，具体见下表。 `LoadingService` 会返回一个 Loading 实例，可通过调用该实例的 `close` 方法来关闭它：

ts

```
const loadingInstance = ElLoading.service(options)
nextTick(() => {
  // Loading should be closed asynchronously
  loadingInstance.close()
})
```

需要注意的是，以服务的方式调用的全屏 Loading 是单例的。 若在前一个全屏 Loading 关闭前再次调用全屏 Loading，并不会创建一个新的 Loading 实例，而是返回现有全屏 Loading 的实例：

ts

```
const loadingInstance1 = ElLoading.service({ fullscreen: true })
const loadingInstance2 = ElLoading.service({ fullscreen: true })
console.log(loadingInstance1 === loadingInstance2) // true
```

此时调用它们中任意一个的 `close` 方法都能关闭这个全屏 Loading。

如果完整引入了 Element Plus，那么 `app.config.globalProperties` 上会有一个全局方法`$loading`， 它的调用方式为：`this.$loading(options)`，同样会返回一个 Loading 实例。

## 应用程序上下文 2.9.10 [​](#应用程序上下文)

现在 Loading 接受一条 `context` 作为消息构造器的第二个参数，允许你将当前应用的上下文注入到 Loading 中，这将允许你继承应用程序的所有属性。

你可以像这样使用它：

TIP

如果您全局注册了 ELLoading 组件，它将自动继承应用的上下文环境。

ts

```
import { getCurrentInstance } from 'vue'
import { ElLoading } from 'element-plus'

// in your setup method
const { appContext } = getCurrentInstance()!
ElLoading.service({}, appContext)
```

## API [​](#api)

### 配置项 [​](#配置项)

| 名称 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| target | Loading 需要覆盖的 DOM 节点。 可传入一个 DOM 对象或字符串； 若传入字符串，则会将其作为参数传入 `document.querySelector`以获取到对应 DOM 节点 | `string` / `HTMLElement` | document.body |
| body | 同 `v-loading` 指令中的 `body` 修饰符 | `boolean` | false |
| fullscreen | 同 `v-loading` 指令中的 `fullscreen` 修饰符 | `boolean` | true |
| lock | 同 `v-loading` 指令中的 `lock` 修饰符 | `boolean` | false |
| text | 显示在加载图标下方的加载文案 | `string` / `VNode` / `array` | — |
| spinner | 自定义加载图标类名 | `string` | — |
| background | 遮罩背景色 | `string` | — |
| customClass | Loading 的自定义类名 | `string` | — |
| svg | 自定义 SVG 元素覆盖默认加载器 | `string` | — |
| svgViewBox | 设置用于加载 svg 元素的 viewBox 属性 | `string` | — |
| beforeClose 2.7.8 | Loading 关闭之前执行的函数。 如果此函数返回 false ，关闭过程将被中止。 反之，loading 将被关闭。 | `Function` | — |
| closed 2.7.8 | Loading 完全关闭后触发的函数 | `Function` | — |

### 指令 [​](#指令)

| 名称 | 说明 | 类型 |
| --- | --- | --- |
| v-loading | 是否显示动画 | `boolean` / `LoadingOptions` |
| element-loading-text | 显示在加载图标下方的加载文案 | `string` |
| element-loading-spinner | 自定义加载图标 | `string` |
| element-loading-svg | 自定义加载图标 (与 element-loading-spinner 相同) | `string` |
| element-loading-svg-view-box | 设置用于加载 svg 元素的 viewBox 属性 | `string` |
| element-loading-background | 背景遮罩的颜色 | `string` |
| element-loading-custom-class | loading 的自定义类名 | `string` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/loading) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/loading.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/loading.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/69580637?v=4&size=64)](https://github.com/jevin98)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/130739557?v=4&size=64)](https://github.com/pan2-2)[![](https://avatars.githubusercontent.com/u/25472916?v=4&size=64)](https://github.com/wiidede)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/20919760?v=4&size=64)](https://github.com/zcmk123)[![](https://avatars.githubusercontent.com/u/134276765?v=4&size=64)](https://github.com/zwgwf)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/25458528?v=4&size=64)](https://github.com/weidehai)[![](https://avatars.githubusercontent.com/u/16174159?v=4&size=64)](https://github.com/anguiao)[![](https://avatars.githubusercontent.com/u/2755933?v=4&size=64)](https://github.com/BiosSun)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)

[Drawer 抽屉](https://element-plus.org/zh-CN/component/drawer)

[Message 消息提示](https://element-plus.org/zh-CN/component/message)




---
## [feedback/message] Message 消息提示
> 官方文档: https://element-plus.org/zh-CN/component/message.html

---

# Message 消息提示 [​](#message-消息提示)

更新日志待解决

21

常用于主动操作后的反馈提示。 与 Notification 的区别是后者更多用于系统级通知的被动提醒。

## 基础用法 [​](#基础用法)

默认情况下在顶部显示并在 3 秒后消失。 您可以使用 `placement` 属性控制位置。

Message 在配置上与 Notification 非常类似，所以部分 options 在此不做详尽解释。 文末有 options 列表，可以结合 Notification 的文档理解它们。 Element Plus 注册了一个全局的 `$message`方法用于调用。 Message 可以接收一个字符串或一个 VNode 作为参数，它会被显示为正文内容。

Show message VNode

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiA6cGxhaW49XCJ0cnVlXCIgQGNsaWNrPVwib3BlblwiPlxuICAgICAgU2hvdyBtZXNzYWdlXG4gICAgPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgOnBsYWluPVwidHJ1ZVwiIEBjbGljaz1cIm9wZW5WblwiPlZOb2RlPC9lbC1idXR0b24+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IGggfSBmcm9tICd2dWUnXG5pbXBvcnQgeyBFbE1lc3NhZ2UgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IG9wZW4gPSAoKSA9PiB7XG4gIEVsTWVzc2FnZSgnVGhpcyBpcyBhIG1lc3NhZ2UuJylcbn1cblxuY29uc3Qgb3BlblZuID0gKCkgPT4ge1xuICBFbE1lc3NhZ2Uoe1xuICAgIG1lc3NhZ2U6IGgoJ3AnLCB7IHN0eWxlOiAnbGluZS1oZWlnaHQ6IDE7IGZvbnQtc2l6ZTogMTRweCcgfSwgW1xuICAgICAgaCgnc3BhbicsIG51bGwsICdNZXNzYWdlIGNhbiBiZSAnKSxcbiAgICAgIGgoJ2knLCB7IHN0eWxlOiAnY29sb3I6IHRlYWwnIH0sICdWTm9kZScpLFxuICAgIF0pLFxuICB9KVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message/basic.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" :plain="true" @click="open">
      Show message
    </el-button>
    <el-button class="!ml-0" :plain="true" @click="openVn">VNode</el-button>
  </div>
</template>

<script lang="ts" setup>
import { h } from 'vue'
import { ElMessage } from 'element-plus'

const open = () => {
  ElMessage('This is a message.')
}

const openVn = () => {
  ElMessage({
    message: h('p', { style: 'line-height: 1; font-size: 14px' }, [
      h('span', null, 'Message can be '),
      h('i', { style: 'color: teal' }, 'VNode'),
    ]),
  })
}
</script>
```

隐藏源代码

## 不同状态 [​](#不同状态)

用来显示「成功、警告、消息、错误」类的操作反馈。

当需要自定义更多属性时，Message 也可以接收一个对象为参数。 比如，设置 `type` 字段可以定义不同的状态，默认为`info`。 此时正文内容以 `message` 的值传入。 同时，我们也为 Message 的各种 type 注册了方法，可以在不传入 type 字段的情况下像 `open4` 那样直接调用。 `primary` 已被添加到2.9.11。

PrimarySuccessWarningInfoError

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiA6cGxhaW49XCJ0cnVlXCIgQGNsaWNrPVwib3BlbjVcIj5QcmltYXJ5PC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgOnBsYWluPVwidHJ1ZVwiIEBjbGljaz1cIm9wZW4yXCI+U3VjY2VzczwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gY2xhc3M9XCIhbWwtMFwiIDpwbGFpbj1cInRydWVcIiBAY2xpY2s9XCJvcGVuM1wiPldhcm5pbmc8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiA6cGxhaW49XCJ0cnVlXCIgQGNsaWNrPVwib3BlbjFcIj5JbmZvPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgOnBsYWluPVwidHJ1ZVwiIEBjbGljaz1cIm9wZW40XCI+RXJyb3I8L2VsLWJ1dHRvbj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRWxNZXNzYWdlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvcGVuMSA9ICgpID0+IHtcbiAgRWxNZXNzYWdlKCdUaGlzIGlzIGEgaW5mbyBtZXNzYWdlLicpXG59XG5jb25zdCBvcGVuMiA9ICgpID0+IHtcbiAgRWxNZXNzYWdlKHtcbiAgICBtZXNzYWdlOiAnQ29uZ3JhdHMsIHRoaXMgaXMgYSBzdWNjZXNzIG1lc3NhZ2UuJyxcbiAgICB0eXBlOiAnc3VjY2VzcycsXG4gIH0pXG59XG5jb25zdCBvcGVuMyA9ICgpID0+IHtcbiAgRWxNZXNzYWdlKHtcbiAgICBtZXNzYWdlOiAnV2FybmluZywgdGhpcyBpcyBhIHdhcm5pbmcgbWVzc2FnZS4nLFxuICAgIHR5cGU6ICd3YXJuaW5nJyxcbiAgfSlcbn1cbmNvbnN0IG9wZW40ID0gKCkgPT4ge1xuICBFbE1lc3NhZ2UuZXJyb3IoJ09vcHMsIHRoaXMgaXMgYSBlcnJvciBtZXNzYWdlLicpXG59XG5jb25zdCBvcGVuNSA9ICgpID0+IHtcbiAgRWxNZXNzYWdlLnByaW1hcnkoJ1RoaXMgaXMgYSBwcmltYXJ5IG1lc3NhZ2UuJylcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message/different-types.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" :plain="true" @click="open5">Primary</el-button>
    <el-button class="!ml-0" :plain="true" @click="open2">Success</el-button>
    <el-button class="!ml-0" :plain="true" @click="open3">Warning</el-button>
    <el-button class="!ml-0" :plain="true" @click="open1">Info</el-button>
    <el-button class="!ml-0" :plain="true" @click="open4">Error</el-button>
  </div>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus'

const open1 = () => {
  ElMessage('This is a info message.')
}
const open2 = () => {
  ElMessage({
    message: 'Congrats, this is a success message.',
    type: 'success',
  })
}
const open3 = () => {
  ElMessage({
    message: 'Warning, this is a warning message.',
    type: 'warning',
  })
}
const open4 = () => {
  ElMessage.error('Oops, this is a error message.')
}
const open5 = () => {
  ElMessage.primary('This is a primary message.')
}
</script>
```

隐藏源代码

## Plain 2.6.3 [​](#plain)

设置 `plain` 为 plain 背景。

PrimarySuccessWarningInfoError

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiA6cGxhaW49XCJ0cnVlXCIgQGNsaWNrPVwib3BlbjVcIj5QcmltYXJ5PC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgOnBsYWluPVwidHJ1ZVwiIEBjbGljaz1cIm9wZW4xXCI+U3VjY2VzczwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gY2xhc3M9XCIhbWwtMFwiIDpwbGFpbj1cInRydWVcIiBAY2xpY2s9XCJvcGVuMlwiPldhcm5pbmc8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiA6cGxhaW49XCJ0cnVlXCIgQGNsaWNrPVwib3BlbjNcIj5JbmZvPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgOnBsYWluPVwidHJ1ZVwiIEBjbGljaz1cIm9wZW40XCI+RXJyb3I8L2VsLWJ1dHRvbj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRWxNZXNzYWdlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvcGVuMSA9ICgpID0+IHtcbiAgRWxNZXNzYWdlKHtcbiAgICBtZXNzYWdlOiAnQ29uZ3JhdHMsIHRoaXMgaXMgYSBzdWNjZXNzIG1lc3NhZ2UuJyxcbiAgICB0eXBlOiAnc3VjY2VzcycsXG4gICAgcGxhaW46IHRydWUsXG4gIH0pXG59XG5jb25zdCBvcGVuMiA9ICgpID0+IHtcbiAgRWxNZXNzYWdlKHtcbiAgICBtZXNzYWdlOiAnV2FybmluZywgdGhpcyBpcyBhIHdhcm5pbmcgbWVzc2FnZS4nLFxuICAgIHR5cGU6ICd3YXJuaW5nJyxcbiAgICBwbGFpbjogdHJ1ZSxcbiAgfSlcbn1cbmNvbnN0IG9wZW4zID0gKCkgPT4ge1xuICBFbE1lc3NhZ2Uoe1xuICAgIG1lc3NhZ2U6ICdUaGlzIGlzIGEgaW5mbyBtZXNzYWdlLicsXG4gICAgdHlwZTogJ2luZm8nLFxuICAgIHBsYWluOiB0cnVlLFxuICB9KVxufVxuY29uc3Qgb3BlbjQgPSAoKSA9PiB7XG4gIEVsTWVzc2FnZSh7XG4gICAgbWVzc2FnZTogJ09vcHMsIHRoaXMgaXMgYSBlcnJvciBtZXNzYWdlLicsXG4gICAgdHlwZTogJ2Vycm9yJyxcbiAgICBwbGFpbjogdHJ1ZSxcbiAgfSlcbn1cbmNvbnN0IG9wZW41ID0gKCkgPT4ge1xuICBFbE1lc3NhZ2Uoe1xuICAgIG1lc3NhZ2U6ICdUaGlzIGlzIGEgcHJpbWFyeSBtZXNzYWdlLicsXG4gICAgdHlwZTogJ3ByaW1hcnknLFxuICAgIHBsYWluOiB0cnVlLFxuICB9KVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message/plain.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" :plain="true" @click="open5">Primary</el-button>
    <el-button class="!ml-0" :plain="true" @click="open1">Success</el-button>
    <el-button class="!ml-0" :plain="true" @click="open2">Warning</el-button>
    <el-button class="!ml-0" :plain="true" @click="open3">Info</el-button>
    <el-button class="!ml-0" :plain="true" @click="open4">Error</el-button>
  </div>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus'

const open1 = () => {
  ElMessage({
    message: 'Congrats, this is a success message.',
    type: 'success',
    plain: true,
  })
}
const open2 = () => {
  ElMessage({
    message: 'Warning, this is a warning message.',
    type: 'warning',
    plain: true,
  })
}
const open3 = () => {
  ElMessage({
    message: 'This is a info message.',
    type: 'info',
    plain: true,
  })
}
const open4 = () => {
  ElMessage({
    message: 'Oops, this is a error message.',
    type: 'error',
    plain: true,
  })
}
const open5 = () => {
  ElMessage({
    message: 'This is a primary message.',
    type: 'primary',
    plain: true,
  })
}
</script>
```

隐藏源代码

## 可关闭的消息提示 [​](#可关闭的消息提示)

可以添加关闭按钮。

默认的 Message 是不可以被人工关闭的。 如果你需要手动关闭功能，你可以把 `showClose` 设置为 true 此外，和 Notification 一样，Message 拥有可控的 `duration`， 默认的关闭时间为 3000 毫秒，当把这个属性的值设置为`0`便表示该消息不会被自动关闭。

PrimarySuccessWarningInfoError Won't close automatically

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiA6cGxhaW49XCJ0cnVlXCIgQGNsaWNrPVwib3BlbjZcIj5QcmltYXJ5PC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgOnBsYWluPVwidHJ1ZVwiIEBjbGljaz1cIm9wZW4yXCI+U3VjY2VzczwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gY2xhc3M9XCIhbWwtMFwiIDpwbGFpbj1cInRydWVcIiBAY2xpY2s9XCJvcGVuM1wiPldhcm5pbmc8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiA6cGxhaW49XCJ0cnVlXCIgQGNsaWNrPVwib3BlbjFcIj5JbmZvPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgOnBsYWluPVwidHJ1ZVwiIEBjbGljaz1cIm9wZW40XCI+RXJyb3I8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiA6cGxhaW49XCJ0cnVlXCIgQGNsaWNrPVwib3BlbjVcIj5cbiAgICAgIFdvbid0IGNsb3NlIGF1dG9tYXRpY2FsbHlcbiAgICA8L2VsLWJ1dHRvbj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRWxNZXNzYWdlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvcGVuMSA9ICgpID0+IHtcbiAgRWxNZXNzYWdlKHtcbiAgICBzaG93Q2xvc2U6IHRydWUsXG4gICAgbWVzc2FnZTogJ1RoaXMgaXMgYSBpbmZvIG1lc3NhZ2UuJyxcbiAgfSlcbn1cbmNvbnN0IG9wZW4yID0gKCkgPT4ge1xuICBFbE1lc3NhZ2Uoe1xuICAgIHNob3dDbG9zZTogdHJ1ZSxcbiAgICBtZXNzYWdlOiAnQ29uZ3JhdHMsIHRoaXMgaXMgYSBzdWNjZXNzIG1lc3NhZ2UuJyxcbiAgICB0eXBlOiAnc3VjY2VzcycsXG4gIH0pXG59XG5jb25zdCBvcGVuMyA9ICgpID0+IHtcbiAgRWxNZXNzYWdlKHtcbiAgICBzaG93Q2xvc2U6IHRydWUsXG4gICAgbWVzc2FnZTogJ1dhcm5pbmcsIHRoaXMgaXMgYSB3YXJuaW5nIG1lc3NhZ2UuJyxcbiAgICB0eXBlOiAnd2FybmluZycsXG4gIH0pXG59XG5jb25zdCBvcGVuNCA9ICgpID0+IHtcbiAgRWxNZXNzYWdlKHtcbiAgICBzaG93Q2xvc2U6IHRydWUsXG4gICAgbWVzc2FnZTogJ09vcHMsIHRoaXMgaXMgYSBlcnJvciBtZXNzYWdlLicsXG4gICAgdHlwZTogJ2Vycm9yJyxcbiAgfSlcbn1cbmNvbnN0IG9wZW41ID0gKCkgPT4ge1xuICBFbE1lc3NhZ2Uoe1xuICAgIHNob3dDbG9zZTogdHJ1ZSxcbiAgICBtZXNzYWdlOiAnT29wcywgdGhpcyBpcyBhIG1lc3NhZ2UgdGhhdCBkb2VzIG5vdCBhdXRvbWF0aWNhbGx5IGNsb3NlLicsXG4gICAgZHVyYXRpb246IDAsXG4gIH0pXG59XG5jb25zdCBvcGVuNiA9ICgpID0+IHtcbiAgRWxNZXNzYWdlKHtcbiAgICBzaG93Q2xvc2U6IHRydWUsXG4gICAgbWVzc2FnZTogJ1RoaXMgaXMgYSBwcmltYXJ5IG1lc3NhZ2UuJyxcbiAgICB0eXBlOiAncHJpbWFyeScsXG4gIH0pXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message/closable.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" :plain="true" @click="open6">Primary</el-button>
    <el-button class="!ml-0" :plain="true" @click="open2">Success</el-button>
    <el-button class="!ml-0" :plain="true" @click="open3">Warning</el-button>
    <el-button class="!ml-0" :plain="true" @click="open1">Info</el-button>
    <el-button class="!ml-0" :plain="true" @click="open4">Error</el-button>
    <el-button class="!ml-0" :plain="true" @click="open5">
      Won't close automatically
    </el-button>
  </div>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus'

const open1 = () => {
  ElMessage({
    showClose: true,
    message: 'This is a info message.',
  })
}
const open2 = () => {
  ElMessage({
    showClose: true,
    message: 'Congrats, this is a success message.',
    type: 'success',
  })
}
const open3 = () => {
  ElMessage({
    showClose: true,
    message: 'Warning, this is a warning message.',
    type: 'warning',
  })
}
const open4 = () => {
  ElMessage({
    showClose: true,
    message: 'Oops, this is a error message.',
    type: 'error',
  })
}
const open5 = () => {
  ElMessage({
    showClose: true,
    message: 'Oops, this is a message that does not automatically close.',
    duration: 0,
  })
}
const open6 = () => {
  ElMessage({
    showClose: true,
    message: 'This is a primary message.',
    type: 'primary',
  })
}
</script>
```

隐藏源代码

## 使用 HTML 片段作为正文内容 [​](#使用-html-片段作为正文内容)

`message` 还支持使用 HTML 字符串作为正文内容。

将`dangerouslyUseHTMLString`属性设置为 true,`message` 就会被当作 HTML 片段处理。

Use HTML string

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIDpwbGFpbj1cInRydWVcIiBAY2xpY2s9XCJvcGVuSFRNTFwiPlVzZSBIVE1MIHN0cmluZzwvZWwtYnV0dG9uPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IEVsTWVzc2FnZSB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3Qgb3BlbkhUTUwgPSAoKSA9PiB7XG4gIEVsTWVzc2FnZSh7XG4gICAgZGFuZ2Vyb3VzbHlVc2VIVE1MU3RyaW5nOiB0cnVlLFxuICAgIG1lc3NhZ2U6ICc8c3Ryb25nPlRoaXMgaXMgPGk+SFRNTDwvaT4gc3RyaW5nPC9zdHJvbmc+JyxcbiAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message/raw-html.vue)_

vue

```
<template>
  <el-button :plain="true" @click="openHTML">Use HTML string</el-button>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus'

const openHTML = () => {
  ElMessage({
    dangerouslyUseHTMLString: true,
    message: '<strong>This is <i>HTML</i> string</strong>',
  })
}
</script>
```

隐藏源代码

WARNING

`message` 属性虽然支持传入 HTML 片段，但是在网站上动态渲染任意 HTML 是非常危险的，因为容易导致 [XSS 攻击](https://en.wikipedia.org/wiki/Cross-site_scripting)。 因此在 `dangerouslyUseHTMLString` 打开的情况下，请确保 `message` 的内容是可信的，**永远不要**将用户提交的内容赋值给 `message` 属性。

## 分组消息合并 [​](#分组消息合并)

合并相同内容的消息。

设置 `grouping` 为 true，内容相同的 `message` 将被合并。

Show message

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIDpwbGFpbj1cInRydWVcIiBAY2xpY2s9XCJvcGVuXCI+U2hvdyBtZXNzYWdlPC9lbC1idXR0b24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRWxNZXNzYWdlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvcGVuID0gKCkgPT4ge1xuICBFbE1lc3NhZ2Uoe1xuICAgIG1lc3NhZ2U6ICdUaGlzIGlzIGEgbWVzc2FnZS4nLFxuICAgIGdyb3VwaW5nOiB0cnVlLFxuICAgIHR5cGU6ICdzdWNjZXNzJyxcbiAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message/grouping.vue)_

vue

```
<template>
  <el-button :plain="true" @click="open">Show message</el-button>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus'

const open = () => {
  ElMessage({
    message: 'This is a message.',
    grouping: true,
    type: 'success',
  })
}
</script>
```

隐藏源代码

## Placement 2.11.0 [​](#placement)

控制消息出现的位置。 消息可以显示在查看端口的顶部(默认) 或其他位置。

Top Top Left Top Right Bottom Bottom Left Bottom Right

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiA6cGxhaW49XCJ0cnVlXCIgQGNsaWNrPVwib3Blbk1zZygpXCI+IFRvcCA8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiA6cGxhaW49XCJ0cnVlXCIgQGNsaWNrPVwib3Blbk1zZygndG9wLWxlZnQnKVwiPlxuICAgICAgVG9wIExlZnRcbiAgICA8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiA6cGxhaW49XCJ0cnVlXCIgQGNsaWNrPVwib3Blbk1zZygndG9wLXJpZ2h0JylcIj5cbiAgICAgIFRvcCBSaWdodFxuICAgIDwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gY2xhc3M9XCIhbWwtMFwiIDpwbGFpbj1cInRydWVcIiBAY2xpY2s9XCJvcGVuTXNnKCdib3R0b20nKVwiPlxuICAgICAgQm90dG9tXG4gICAgPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgOnBsYWluPVwidHJ1ZVwiIEBjbGljaz1cIm9wZW5Nc2coJ2JvdHRvbS1sZWZ0JylcIj5cbiAgICAgIEJvdHRvbSBMZWZ0XG4gICAgPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgOnBsYWluPVwidHJ1ZVwiIEBjbGljaz1cIm9wZW5Nc2coJ2JvdHRvbS1yaWdodCcpXCI+XG4gICAgICBCb3R0b20gUmlnaHRcbiAgICA8L2VsLWJ1dHRvbj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRWxNZXNzYWdlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbXBvcnQgdHlwZSB7IE1lc3NhZ2VQbGFjZW1lbnQsIE1lc3NhZ2VUeXBlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5sZXQgdG9wQ291bnQgPSAwXG5sZXQgYm90dG9tQ291bnQgPSAwXG5sZXQgdG9wTGVmdENvdW50ID0gMFxubGV0IHRvcFJpZ2h0Q291bnQgPSAwXG5sZXQgYm90dG9tTGVmdENvdW50ID0gMFxubGV0IGJvdHRvbVJpZ2h0Q291bnQgPSAwXG5cbmNvbnN0IG9wZW5Nc2cgPSAocGxhY2VtZW50OiBNZXNzYWdlUGxhY2VtZW50ID0gJ3RvcCcpID0+IHtcbiAgbGV0IGNvdW50ID0gMFxuICBsZXQgdHlwZTogTWVzc2FnZVR5cGUgPSAnc3VjY2VzcydcblxuICBzd2l0Y2ggKHBsYWNlbWVudCkge1xuICAgIGNhc2UgJ3RvcCc6XG4gICAgICBjb3VudCA9ICsrdG9wQ291bnRcbiAgICAgIHR5cGUgPSAnc3VjY2VzcydcbiAgICAgIGJyZWFrXG4gICAgY2FzZSAnYm90dG9tJzpcbiAgICAgIGNvdW50ID0gKytib3R0b21Db3VudFxuICAgICAgdHlwZSA9ICd3YXJuaW5nJ1xuICAgICAgYnJlYWtcbiAgICBjYXNlICd0b3AtbGVmdCc6XG4gICAgICBjb3VudCA9ICsrdG9wTGVmdENvdW50XG4gICAgICB0eXBlID0gJ2luZm8nXG4gICAgICBicmVha1xuICAgIGNhc2UgJ3RvcC1yaWdodCc6XG4gICAgICBjb3VudCA9ICsrdG9wUmlnaHRDb3VudFxuICAgICAgdHlwZSA9ICdwcmltYXJ5J1xuICAgICAgYnJlYWtcbiAgICBjYXNlICdib3R0b20tbGVmdCc6XG4gICAgICBjb3VudCA9ICsrYm90dG9tTGVmdENvdW50XG4gICAgICB0eXBlID0gJ3dhcm5pbmcnXG4gICAgICBicmVha1xuICAgIGNhc2UgJ2JvdHRvbS1yaWdodCc6XG4gICAgICBjb3VudCA9ICsrYm90dG9tUmlnaHRDb3VudFxuICAgICAgdHlwZSA9ICdlcnJvcidcbiAgICAgIGJyZWFrXG4gIH1cblxuICBFbE1lc3NhZ2Uoe1xuICAgIG1lc3NhZ2U6IGBUaGlzIGlzIGEgbWVzc2FnZSBmcm9tIHRoZSAke3BsYWNlbWVudH0gJHtjb3VudH1gLFxuICAgIHR5cGUsXG4gICAgcGxhY2VtZW50LFxuICB9KVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message/placement.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" :plain="true" @click="openMsg()"> Top </el-button>
    <el-button class="!ml-0" :plain="true" @click="openMsg('top-left')">
      Top Left
    </el-button>
    <el-button class="!ml-0" :plain="true" @click="openMsg('top-right')">
      Top Right
    </el-button>
    <el-button class="!ml-0" :plain="true" @click="openMsg('bottom')">
      Bottom
    </el-button>
    <el-button class="!ml-0" :plain="true" @click="openMsg('bottom-left')">
      Bottom Left
    </el-button>
    <el-button class="!ml-0" :plain="true" @click="openMsg('bottom-right')">
      Bottom Right
    </el-button>
  </div>
</template>

<script lang="ts" setup>
import { ElMessage } from 'element-plus'

import type { MessagePlacement, MessageType } from 'element-plus'

let topCount = 0
let bottomCount = 0
let topLeftCount = 0
let topRightCount = 0
let bottomLeftCount = 0
let bottomRightCount = 0

const openMsg = (placement: MessagePlacement = 'top') => {
  let count = 0
  let type: MessageType = 'success'

  switch (placement) {
    case 'top':
      count = ++topCount
      type = 'success'
      break
    case 'bottom':
      count = ++bottomCount
      type = 'warning'
      break
    case 'top-left':
      count = ++topLeftCount
      type = 'info'
      break
    case 'top-right':
      count = ++topRightCount
      type = 'primary'
      break
    case 'bottom-left':
      count = ++bottomLeftCount
      type = 'warning'
      break
    case 'bottom-right':
      count = ++bottomRightCount
      type = 'error'
      break
  }

  ElMessage({
    message: `This is a message from the ${placement} ${count}`,
    type,
    placement,
  })
}
</script>
```

隐藏源代码

## 全局方法 [​](#全局方法)

Element Plus 为 `app.config.globalProperties` 添加了全局方法 `$message`。 因此在 vue 实例中你可以使用当前页面中的调用方式调用 `Message`

## 单独引用 [​](#单独引用)

ts

```
import { ElMessage } from 'element-plus'
```

此时调用方法为 `ElMessage(options)`。 我们也为每个 type 定义了各自的方法，如 `ElMessage.success(options)`。 并且可以调用 `ElMessage.closeAll()` 手动关闭所有实例。

## 应用程序上下文继承 2.0.3 [​](#应用程序上下文继承)

现在 Message 接受一条 `context` 作为消息构造器的第二个参数，允许你将当前应用的上下文注入到 Message 中，这将允许你继承应用程序的所有属性。

你可以像这样使用它：

TIP

如果您全局注册了 ElMessage 组件，它将自动继承应用的上下文环境。

ts

```
import { getCurrentInstance } from 'vue'
import { ElMessage } from 'element-plus'

// 在你的 setup 方法中
const { appContext } = getCurrentInstance()!
ElMessage({}, appContext)
```

## API [​](#api)

### Message 配置项 [​](#message-配置项)

| 名称 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| message | 消息文字 | `string` / `VNode` / `Function` | '' |
| type | 消息类型 | `enum` | info |
| plain 2.6.3 | 是否纯色 | `boolean` | false |
| icon | 自定义图标，该属性会覆盖 `type` 的图标。 | `string` / `Component` | — |
| dangerouslyUseHTMLString | 是否将 message 属性作为 HTML 片段处理 | `boolean` | false |
| customClass | 自定义类名 | `string` | '' |
| duration | 显示时间，单位为毫秒。 设为 0 则不会自动关闭 | `number` | 3000 |
| showClose | 是否显示关闭按钮 | `boolean` | false |
| onClose | 关闭时的回调函数, 参数为被关闭的 message 实例 | `Function` | — |
| offset | 设置到视口边缘的距离（当位置为'top'时为顶部，当位置为'bottom'时为底部） | `number` | 16 |
| placement 2.11.0 | 消息放置位置 | `enum` | top |
| appendTo | 设置 message 的根元素，默认为 `document.body` | `CSSSelector` / `HTMLElement` | — |
| grouping | 合并内容相同的消息，不支持 VNode 类型的消息 | `boolean` | false |
| repeatNum | 重复次数，类似于 Badge 。当和 `grouping` 属性一起使用时作为初始数量使用 | `number` | 1 |

### Message 方法 [​](#message-方法)

调用 `Message` 或 `this.$message` 会返回当前 Message 的实例。 如果需要手动关闭实例，可以调用它的 `close` 方法。

| 名称 | 描述 | 类型 |
| --- | --- | --- |
| close | 关闭当前的 Message | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/message) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/message.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/message.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/57785259?v=4&size=64)](https://github.com/w2xi)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/47303530?v=4&size=64)](https://github.com/romankaravia)[![](https://avatars.githubusercontent.com/u/71749650?v=4&size=64)](https://github.com/qeTM)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/137589237?v=4&size=64)](https://github.com/zero-years)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/132551120?v=4&size=64)](https://github.com/YiMo1)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/35138018?v=4&size=64)](https://github.com/tuskermanshu)[![](https://avatars.githubusercontent.com/u/49558643?v=4&size=64)](https://github.com/jumtp)[![](https://avatars.githubusercontent.com/u/47104575?v=4&size=64)](https://github.com/linxianxi)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/48512251?v=4&size=64)](https://github.com/lete114)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/2883231?v=4&size=64)](https://github.com/HerringtonDarkholme)[![](https://avatars.githubusercontent.com/u/31462942?v=4&size=64)](https://github.com/zhazhanitian)[![](https://avatars.githubusercontent.com/u/49446662?v=4&size=64)](https://github.com/codespikey)[![](https://avatars.githubusercontent.com/u/5445667?v=4&size=64)](https://github.com/iceshou)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/134276765?v=4&size=64)](https://github.com/zwgwf)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/191817983?v=4&size=64)](https://github.com/zhuft-moon)[![](https://avatars.githubusercontent.com/u/38075730?v=4&size=64)](https://github.com/c0dedance)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)

[Loading 加载](https://element-plus.org/zh-CN/component/loading)

[Message Box 消息弹出框](https://element-plus.org/zh-CN/component/message-box)




---
## [feedback/message-box] Message Box 消息弹出框
> 官方文档: https://element-plus.org/zh-CN/component/message-box.html

---

# MessageBox 消息弹框 [​](#messagebox-消息弹框)

更新日志待解决

13

模拟系统的消息提示框而实现的一套模态对话框组件，用于消息提示、确认消息和提交内容。

TIP

从设计上来说，MessageBox 的作用是美化系统自带的 `alert`、`confirm` 和 `prompt`，因此适合展示较为简单的内容。 如果需要弹出较为复杂的内容，请使用 Dialog。

## 消息提示 [​](#消息提示)

当用户进行操作时会被触发，该对话框中断用户操作，直到用户确认知晓后才可关闭。

调用 `ElMessageBox.alert` 方法以打开 alert 框。 它模拟了系统的 `alert`，无法通过按下 ESC 或点击框外关闭。 此例中接收了两个参数，`message`和`title`。 值得一提的是，窗口被关闭后，它默认会返回一个`Promise`对象便于进行后续操作的处理。 若不确定浏览器是否支持`Promise`，可自行引入第三方 polyfill 或像本例一样使用回调进行后续处理。

Click to open the Message Box

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj5DbGljayB0byBvcGVuIHRoZSBNZXNzYWdlIEJveDwvZWwtYnV0dG9uPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IEVsTWVzc2FnZSwgRWxNZXNzYWdlQm94IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5pbXBvcnQgdHlwZSB7IEFjdGlvbiB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3Qgb3BlbiA9ICgpID0+IHtcbiAgRWxNZXNzYWdlQm94LmFsZXJ0KCdUaGlzIGlzIGEgbWVzc2FnZScsICdUaXRsZScsIHtcbiAgICAvLyBpZiB5b3Ugd2FudCB0byBkaXNhYmxlIGl0cyBhdXRvZm9jdXNcbiAgICAvLyBhdXRvZm9jdXM6IGZhbHNlLFxuICAgIGNvbmZpcm1CdXR0b25UZXh0OiAnT0snLFxuICAgIGNhbGxiYWNrOiAoYWN0aW9uOiBBY3Rpb24pID0+IHtcbiAgICAgIEVsTWVzc2FnZSh7XG4gICAgICAgIHR5cGU6ICdpbmZvJyxcbiAgICAgICAgbWVzc2FnZTogYGFjdGlvbjogJHthY3Rpb259YCxcbiAgICAgIH0pXG4gICAgfSxcbiAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message-box/alert.vue)_

vue

```
<template>
  <el-button plain @click="open">Click to open the Message Box</el-button>
</template>

<script lang="ts" setup>
import { ElMessage, ElMessageBox } from 'element-plus'

import type { Action } from 'element-plus'

const open = () => {
  ElMessageBox.alert('This is a message', 'Title', {
    // if you want to disable its autofocus
    // autofocus: false,
    confirmButtonText: 'OK',
    callback: (action: Action) => {
      ElMessage({
        type: 'info',
        message: `action: ${action}`,
      })
    },
  })
}
</script>
```

隐藏源代码

## 确认消息 [​](#确认消息)

提示用户确认其已经触发的动作，并询问是否进行此操作时会用到此对话框。

调用 `ElMessageBox.confirm` 方法以打开 confirm 框。它模拟了系统的 `confirm`。 Message Box 组件也拥有极高的定制性，我们可以传入 `options` 作为第三个参数，它是一个字面量对象。 `type` 字段表明消息类型，可以为`success`，`error`，`info`和 `warning` 需要注意的是，第二个参数 `title` 必须定义为 `String` 类型，如果是 `Object`，会被当做为 `options`使用。 在这里我们返回了一个 `Promise` 来处理后续响应。 `primary` 已被添加到2.9.11。

Click to open the Message Box

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj5DbGljayB0byBvcGVuIHRoZSBNZXNzYWdlIEJveDwvZWwtYnV0dG9uPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IEVsTWVzc2FnZSwgRWxNZXNzYWdlQm94IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvcGVuID0gKCkgPT4ge1xuICBFbE1lc3NhZ2VCb3guY29uZmlybShcbiAgICAncHJveHkgd2lsbCBwZXJtYW5lbnRseSBkZWxldGUgdGhlIGZpbGUuIENvbnRpbnVlPycsXG4gICAgJ1dhcm5pbmcnLFxuICAgIHtcbiAgICAgIGNvbmZpcm1CdXR0b25UZXh0OiAnT0snLFxuICAgICAgY2FuY2VsQnV0dG9uVGV4dDogJ0NhbmNlbCcsXG4gICAgICB0eXBlOiAnd2FybmluZycsXG4gICAgfVxuICApXG4gICAgLnRoZW4oKCkgPT4ge1xuICAgICAgRWxNZXNzYWdlKHtcbiAgICAgICAgdHlwZTogJ3N1Y2Nlc3MnLFxuICAgICAgICBtZXNzYWdlOiAnRGVsZXRlIGNvbXBsZXRlZCcsXG4gICAgICB9KVxuICAgIH0pXG4gICAgLmNhdGNoKCgpID0+IHtcbiAgICAgIEVsTWVzc2FnZSh7XG4gICAgICAgIHR5cGU6ICdpbmZvJyxcbiAgICAgICAgbWVzc2FnZTogJ0RlbGV0ZSBjYW5jZWxlZCcsXG4gICAgICB9KVxuICAgIH0pXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message-box/confirm.vue)_

vue

```
<template>
  <el-button plain @click="open">Click to open the Message Box</el-button>
</template>

<script lang="ts" setup>
import { ElMessage, ElMessageBox } from 'element-plus'

const open = () => {
  ElMessageBox.confirm(
    'proxy will permanently delete the file. Continue?',
    'Warning',
    {
      confirmButtonText: 'OK',
      cancelButtonText: 'Cancel',
      type: 'warning',
    }
  )
    .then(() => {
      ElMessage({
        type: 'success',
        message: 'Delete completed',
      })
    })
    .catch(() => {
      ElMessage({
        type: 'info',
        message: 'Delete canceled',
      })
    })
}
</script>
```

隐藏源代码

## 提交内容 [​](#提交内容)

当需要用户输入内容时，可以使用 Prompt 类型的消息框。

调用 `ElMessageBox.prompt` 方法以打开 prompt 框。它模拟了系统的 `prompt`。 可以用 `inputPattern` 字段自己规定匹配模式， 使用 `inputValidator` 来指定验证方法，它应该返回 `Boolean` 或 `String`。 返回 `false` 或 `String` 表示验证失败， 返回的字符串将用作 `inputErrorMessage`，用来提示用户错误原因。 此外，可以用 `inputPlaceholder` 字段来定义输入框的占位符。

Click to open Message Box

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj5DbGljayB0byBvcGVuIE1lc3NhZ2UgQm94PC9lbC1idXR0b24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRWxNZXNzYWdlLCBFbE1lc3NhZ2VCb3ggfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IG9wZW4gPSAoKSA9PiB7XG4gIEVsTWVzc2FnZUJveC5wcm9tcHQoJ1BsZWFzZSBpbnB1dCB5b3VyIGUtbWFpbCcsICdUaXAnLCB7XG4gICAgY29uZmlybUJ1dHRvblRleHQ6ICdPSycsXG4gICAgY2FuY2VsQnV0dG9uVGV4dDogJ0NhbmNlbCcsXG4gICAgaW5wdXRQYXR0ZXJuOlxuICAgICAgL1tcXHchIyQlJicqKy89P15fYHt8fX4tXSsoPzpcXC5bXFx3ISMkJSYnKisvPT9eX2B7fH1+LV0rKSpAKD86W1xcd10oPzpbXFx3LV0qW1xcd10pP1xcLikrW1xcd10oPzpbXFx3LV0qW1xcd10pPy8sXG4gICAgaW5wdXRFcnJvck1lc3NhZ2U6ICdJbnZhbGlkIEVtYWlsJyxcbiAgfSlcbiAgICAudGhlbigoeyB2YWx1ZSB9KSA9PiB7XG4gICAgICBFbE1lc3NhZ2Uoe1xuICAgICAgICB0eXBlOiAnc3VjY2VzcycsXG4gICAgICAgIG1lc3NhZ2U6IGBZb3VyIGVtYWlsIGlzOiR7dmFsdWV9YCxcbiAgICAgIH0pXG4gICAgfSlcbiAgICAuY2F0Y2goKCkgPT4ge1xuICAgICAgRWxNZXNzYWdlKHtcbiAgICAgICAgdHlwZTogJ2luZm8nLFxuICAgICAgICBtZXNzYWdlOiAnSW5wdXQgY2FuY2VsZWQnLFxuICAgICAgfSlcbiAgICB9KVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message-box/prompt.vue)_

vue

```
<template>
  <el-button plain @click="open">Click to open Message Box</el-button>
</template>

<script lang="ts" setup>
import { ElMessage, ElMessageBox } from 'element-plus'

const open = () => {
  ElMessageBox.prompt('Please input your e-mail', 'Tip', {
    confirmButtonText: 'OK',
    cancelButtonText: 'Cancel',
    inputPattern:
      /[\w!#$%&'*+/=?^_`{|}~-]+(?:\.[\w!#$%&'*+/=?^_`{|}~-]+)*@(?:[\w](?:[\w-]*[\w])?\.)+[\w](?:[\w-]*[\w])?/,
    inputErrorMessage: 'Invalid Email',
  })
    .then(({ value }) => {
      ElMessage({
        type: 'success',
        message: `Your email is:${value}`,
      })
    })
    .catch(() => {
      ElMessage({
        type: 'info',
        message: 'Input canceled',
      })
    })
}
</script>
```

隐藏源代码

## 使用 VNode [​](#使用-vnode)

`message` 可以是 VNode。

Common VNodeDynamic props

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuXCI+Q29tbW9uIFZOb2RlPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgcGxhaW4gQGNsaWNrPVwib3BlbjFcIj5EeW5hbWljIHByb3BzPC9lbC1idXR0b24+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IGgsIHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVsTWVzc2FnZUJveCwgRWxTd2l0Y2ggfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IG9wZW4gPSAoKSA9PiB7XG4gIEVsTWVzc2FnZUJveCh7XG4gICAgdGl0bGU6ICdNZXNzYWdlJyxcbiAgICBtZXNzYWdlOiBoKCdwJywgbnVsbCwgW1xuICAgICAgaCgnc3BhbicsIG51bGwsICdNZXNzYWdlIGNhbiBiZSAnKSxcbiAgICAgIGgoJ2knLCB7IHN0eWxlOiAnY29sb3I6IHRlYWwnIH0sICdWTm9kZScpLFxuICAgIF0pLFxuICB9KVxufVxuXG5jb25zdCBvcGVuMSA9ICgpID0+IHtcbiAgY29uc3QgY2hlY2tlZCA9IHJlZjxib29sZWFuIHwgc3RyaW5nIHwgbnVtYmVyPihmYWxzZSlcbiAgRWxNZXNzYWdlQm94KHtcbiAgICB0aXRsZTogJ01lc3NhZ2UnLFxuICAgIC8vIFNob3VsZCBwYXNzIGEgZnVuY3Rpb24gaWYgVk5vZGUgY29udGFpbnMgZHluYW1pYyBwcm9wc1xuICAgIG1lc3NhZ2U6ICgpID0+XG4gICAgICBoKEVsU3dpdGNoLCB7XG4gICAgICAgIG1vZGVsVmFsdWU6IGNoZWNrZWQudmFsdWUsXG4gICAgICAgICdvblVwZGF0ZTptb2RlbFZhbHVlJzogKHZhbDogYm9vbGVhbiB8IHN0cmluZyB8IG51bWJlcikgPT4ge1xuICAgICAgICAgIGNoZWNrZWQudmFsdWUgPSB2YWxcbiAgICAgICAgfSxcbiAgICAgIH0pLFxuICB9KVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message-box/use-vnode.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" plain @click="open">Common VNode</el-button>
    <el-button class="!ml-0" plain @click="open1">Dynamic props</el-button>
  </div>
</template>

<script lang="ts" setup>
import { h, ref } from 'vue'
import { ElMessageBox, ElSwitch } from 'element-plus'

const open = () => {
  ElMessageBox({
    title: 'Message',
    message: h('p', null, [
      h('span', null, 'Message can be '),
      h('i', { style: 'color: teal' }, 'VNode'),
    ]),
  })
}

const open1 = () => {
  const checked = ref<boolean | string | number>(false)
  ElMessageBox({
    title: 'Message',
    // Should pass a function if VNode contains dynamic props
    message: () =>
      h(ElSwitch, {
        modelValue: checked.value,
        'onUpdate:modelValue': (val: boolean | string | number) => {
          checked.value = val
        },
      }),
  })
}
</script>
```

隐藏源代码

## 使用带有事件处理函数的 VNode 2.14.0 [​](#使用带有事件处理函数的-vnode)

在 `message` 中可以接收 `{ confirm, cancel, close }` 作为参数，使自定义内容能够以编程方式触发相同的 MessageBox 操作，并自动关闭实例。

Click to open Message Box

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj5DbGljayB0byBvcGVuIE1lc3NhZ2UgQm94PC9lbC1idXR0b24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgaCB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVsQnV0dG9uLCBFbE1lc3NhZ2UsIEVsTWVzc2FnZUJveCB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3Qgb3BlbiA9ICgpID0+IHtcbiAgRWxNZXNzYWdlQm94LmNvbmZpcm0oXG4gICAgKHsgY29uZmlybSwgY2FuY2VsLCBjbG9zZSB9KSA9PiB7XG4gICAgICByZXR1cm4gaCgnZGl2JywgW1xuICAgICAgICBoKFxuICAgICAgICAgICdwJyxcbiAgICAgICAgICB7IHN0eWxlOiAnbWFyZ2luLWJvdHRvbTogOHB4JyB9LFxuICAgICAgICAgICdDdXN0b20gYnV0dG9ucyB3aXRoIE1lc3NhZ2VCb3ggYWN0aW9uIGhhbmRsZXJzJ1xuICAgICAgICApLFxuICAgICAgICBoKFxuICAgICAgICAgIEVsQnV0dG9uLFxuICAgICAgICAgIHtcbiAgICAgICAgICAgIHR5cGU6ICdwcmltYXJ5JyxcbiAgICAgICAgICAgIG9uQ2xpY2s6ICgpID0+IHtcbiAgICAgICAgICAgICAgY29uZmlybSgpXG4gICAgICAgICAgICB9LFxuICAgICAgICAgIH0sXG4gICAgICAgICAgKCkgPT4gJ1Jlc29sdmUnXG4gICAgICAgICksXG4gICAgICAgIGgoXG4gICAgICAgICAgRWxCdXR0b24sXG4gICAgICAgICAge1xuICAgICAgICAgICAgdHlwZTogJ2RhbmdlcicsXG4gICAgICAgICAgICBvbkNsaWNrOiAoKSA9PiB7XG4gICAgICAgICAgICAgIGNhbmNlbCgpXG4gICAgICAgICAgICB9LFxuICAgICAgICAgIH0sXG4gICAgICAgICAgKCkgPT4gJ1JlamVjdCdcbiAgICAgICAgKSxcbiAgICAgICAgaChcbiAgICAgICAgICBFbEJ1dHRvbixcbiAgICAgICAgICB7XG4gICAgICAgICAgICBvbkNsaWNrOiAoKSA9PiB7XG4gICAgICAgICAgICAgIGNsb3NlKClcbiAgICAgICAgICAgIH0sXG4gICAgICAgICAgfSxcbiAgICAgICAgICAoKSA9PiAnQ2xvc2UnXG4gICAgICAgICksXG4gICAgICBdKVxuICAgIH0sXG4gICAge1xuICAgICAgdGl0bGU6ICdNZXNzYWdlJyxcbiAgICAgIHNob3dDb25maXJtQnV0dG9uOiBmYWxzZSxcbiAgICAgIHNob3dDYW5jZWxCdXR0b246IGZhbHNlLFxuICAgICAgZGlzdGluZ3Vpc2hDYW5jZWxBbmRDbG9zZTogdHJ1ZSxcbiAgICB9XG4gIClcbiAgICAudGhlbigoYWN0aW9uKSA9PiB7XG4gICAgICBFbE1lc3NhZ2Uoe1xuICAgICAgICB0eXBlOiAnc3VjY2VzcycsXG4gICAgICAgIG1lc3NhZ2U6IGByZXNvbHZlZDogJHthY3Rpb259YCxcbiAgICAgIH0pXG4gICAgfSlcbiAgICAuY2F0Y2goKHJlYXNvbikgPT4ge1xuICAgICAgRWxNZXNzYWdlKHtcbiAgICAgICAgdHlwZTogJ2Vycm9yJyxcbiAgICAgICAgbWVzc2FnZTogYHJlamVjdGVkOiAke3JlYXNvbn1gLFxuICAgICAgfSlcbiAgICB9KVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message-box/use-vnode-with-action-handlers.vue)_

vue

```
<template>
  <el-button plain @click="open">Click to open Message Box</el-button>
</template>

<script lang="ts" setup>
import { h } from 'vue'
import { ElButton, ElMessage, ElMessageBox } from 'element-plus'

const open = () => {
  ElMessageBox.confirm(
    ({ confirm, cancel, close }) => {
      return h('div', [
        h(
          'p',
          { style: 'margin-bottom: 8px' },
          'Custom buttons with MessageBox action handlers'
        ),
        h(
          ElButton,
          {
            type: 'primary',
            onClick: () => {
              confirm()
            },
          },
          () => 'Resolve'
        ),
        h(
          ElButton,
          {
            type: 'danger',
            onClick: () => {
              cancel()
            },
          },
          () => 'Reject'
        ),
        h(
          ElButton,
          {
            onClick: () => {
              close()
            },
          },
          () => 'Close'
        ),
      ])
    },
    {
      title: 'Message',
      showConfirmButton: false,
      showCancelButton: false,
      distinguishCancelAndClose: true,
    }
  )
    .then((action) => {
      ElMessage({
        type: 'success',
        message: `resolved: ${action}`,
      })
    })
    .catch((reason) => {
      ElMessage({
        type: 'error',
        message: `rejected: ${reason}`,
      })
    })
}
</script>
```

隐藏源代码

## 个性化 [​](#个性化)

消息弹框可以被定制来展示各种内容。

上面提到的三个方法都是对 `ElMessageBox` 方法的二次包装。 本例直接调用 `ElMessageBox` 方法，使用了 `showCancelButton` 字段，用于显示取消按钮。 另外可使用 `cancelButtonClass` 为其添加自定义样式，使用 `cancelButtonText` 来自定义取消按钮文本（Confirm 按钮也具有相同的字段，在文末的 API 说明中有完整的字段列表）。 此例还使用了 `beforeClose` 属性， 当 beforeClose 被赋值且被赋值为一个回调函数时，在消息弹框被关闭之前将会被调用，并且可以通过该方法来阻止弹框被关闭。 它是一个接收三个参数：`action`、`instance` 和`done` 的方法。 使用它能够在关闭前对实例进行一些操作，比如为确定按钮添加 `loading` 状态等；此时若需要关闭实例，可以调用 `done` 方法（若在 `beforeClose` 中没有调用 `done`，则弹框便不会关闭）。

Click to open Message Box

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj5DbGljayB0byBvcGVuIE1lc3NhZ2UgQm94PC9lbC1idXR0b24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgaCB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVsTWVzc2FnZSwgRWxNZXNzYWdlQm94IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvcGVuID0gKCkgPT4ge1xuICBFbE1lc3NhZ2VCb3goe1xuICAgIHRpdGxlOiAnTWVzc2FnZScsXG4gICAgbWVzc2FnZTogaCgncCcsIG51bGwsIFtcbiAgICAgIGgoJ3NwYW4nLCBudWxsLCAnTWVzc2FnZSBjYW4gYmUgJyksXG4gICAgICBoKCdpJywgeyBzdHlsZTogJ2NvbG9yOiB0ZWFsJyB9LCAnVk5vZGUnKSxcbiAgICBdKSxcbiAgICBzaG93Q2FuY2VsQnV0dG9uOiB0cnVlLFxuICAgIGNvbmZpcm1CdXR0b25UZXh0OiAnT0snLFxuICAgIGNhbmNlbEJ1dHRvblRleHQ6ICdDYW5jZWwnLFxuICAgIGJlZm9yZUNsb3NlOiAoYWN0aW9uLCBpbnN0YW5jZSwgZG9uZSkgPT4ge1xuICAgICAgaWYgKGFjdGlvbiA9PT0gJ2NvbmZpcm0nKSB7XG4gICAgICAgIGluc3RhbmNlLmNvbmZpcm1CdXR0b25Mb2FkaW5nID0gdHJ1ZVxuICAgICAgICBpbnN0YW5jZS5jb25maXJtQnV0dG9uVGV4dCA9ICdMb2FkaW5nLi4uJ1xuICAgICAgICBzZXRUaW1lb3V0KCgpID0+IHtcbiAgICAgICAgICBkb25lKClcbiAgICAgICAgICBzZXRUaW1lb3V0KCgpID0+IHtcbiAgICAgICAgICAgIGluc3RhbmNlLmNvbmZpcm1CdXR0b25Mb2FkaW5nID0gZmFsc2VcbiAgICAgICAgICB9LCAzMDApXG4gICAgICAgIH0sIDMwMDApXG4gICAgICB9IGVsc2Uge1xuICAgICAgICBkb25lKClcbiAgICAgIH1cbiAgICB9LFxuICB9KS50aGVuKChhY3Rpb24pID0+IHtcbiAgICBFbE1lc3NhZ2Uoe1xuICAgICAgdHlwZTogJ2luZm8nLFxuICAgICAgbWVzc2FnZTogYGFjdGlvbjogJHthY3Rpb259YCxcbiAgICB9KVxuICB9KVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message-box/customization.vue)_

vue

```
<template>
  <el-button plain @click="open">Click to open Message Box</el-button>
</template>

<script lang="ts" setup>
import { h } from 'vue'
import { ElMessage, ElMessageBox } from 'element-plus'

const open = () => {
  ElMessageBox({
    title: 'Message',
    message: h('p', null, [
      h('span', null, 'Message can be '),
      h('i', { style: 'color: teal' }, 'VNode'),
    ]),
    showCancelButton: true,
    confirmButtonText: 'OK',
    cancelButtonText: 'Cancel',
    beforeClose: (action, instance, done) => {
      if (action === 'confirm') {
        instance.confirmButtonLoading = true
        instance.confirmButtonText = 'Loading...'
        setTimeout(() => {
          done()
          setTimeout(() => {
            instance.confirmButtonLoading = false
          }, 300)
        }, 3000)
      } else {
        done()
      }
    },
  }).then((action) => {
    ElMessage({
      type: 'info',
      message: `action: ${action}`,
    })
  })
}
</script>
```

隐藏源代码

## 使用 HTML 片段 [​](#使用-html-片段)

`message` 支持传入 HTML 字符串来作为正文内容。

将 `dangerouslyUseHTMLString` 属性设置为 true，`message` 属性就会被当作 HTML 片段处理。

Click to open Message Box

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj5DbGljayB0byBvcGVuIE1lc3NhZ2UgQm94PC9lbC1idXR0b24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRWxNZXNzYWdlQm94IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvcGVuID0gKCkgPT4ge1xuICBFbE1lc3NhZ2VCb3guYWxlcnQoXG4gICAgJzxzdHJvbmc+cHJveHkgaXMgPGk+SFRNTDwvaT4gc3RyaW5nPC9zdHJvbmc+JyxcbiAgICAnSFRNTCBTdHJpbmcnLFxuICAgIHtcbiAgICAgIGRhbmdlcm91c2x5VXNlSFRNTFN0cmluZzogdHJ1ZSxcbiAgICB9XG4gIClcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message-box/use-html.vue)_

vue

```
<template>
  <el-button plain @click="open">Click to open Message Box</el-button>
</template>

<script lang="ts" setup>
import { ElMessageBox } from 'element-plus'

const open = () => {
  ElMessageBox.alert(
    '<strong>proxy is <i>HTML</i> string</strong>',
    'HTML String',
    {
      dangerouslyUseHTMLString: true,
    }
  )
}
</script>
```

隐藏源代码

WARNING

`message` 属性虽然支持传入 HTML 片段，但是在网站上动态渲染任意 HTML 是非常危险的，因为容易导致 [XSS 攻击](https://en.wikipedia.org/wiki/Cross-site_scripting)。 因此在 `dangerouslyUseHTMLString` 打开的情况下，请确保 `message` 的内容是可信的，**永远不要**将用户提交的内容赋值给 `message` 属性。

## 区分取消操作与关闭操作 [​](#区分取消操作与关闭操作)

有些场景下，点击取消按钮与点击关闭按钮有着不同的含义。

默认情况下，当用户触发取消（点击取消按钮）和触发关闭（点击关闭按钮或遮罩层、按下 ESC 键）时，Promise 的 reject 回调和 `callback` 回调的参数均为 'cancel'。 如果将`distinguishCancelAndClose`属性设置为 true，则上述两种行为的参数分别为 'cancel' 和 'close'。

Click to open Message Box

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj5DbGljayB0byBvcGVuIE1lc3NhZ2UgQm94PC9lbC1idXR0b24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRWxNZXNzYWdlLCBFbE1lc3NhZ2VCb3ggfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmltcG9ydCB0eXBlIHsgQWN0aW9uIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvcGVuID0gKCkgPT4ge1xuICBFbE1lc3NhZ2VCb3guY29uZmlybShcbiAgICAnWW91IGhhdmUgdW5zYXZlZCBjaGFuZ2VzLCBzYXZlIGFuZCBwcm9jZWVkPycsXG4gICAgJ0NvbmZpcm0nLFxuICAgIHtcbiAgICAgIGRpc3Rpbmd1aXNoQ2FuY2VsQW5kQ2xvc2U6IHRydWUsXG4gICAgICBjb25maXJtQnV0dG9uVGV4dDogJ1NhdmUnLFxuICAgICAgY2FuY2VsQnV0dG9uVGV4dDogJ0Rpc2NhcmQgQ2hhbmdlcycsXG4gICAgfVxuICApXG4gICAgLnRoZW4oKCkgPT4ge1xuICAgICAgRWxNZXNzYWdlKHtcbiAgICAgICAgdHlwZTogJ2luZm8nLFxuICAgICAgICBtZXNzYWdlOiAnQ2hhbmdlcyBzYXZlZC4gUHJvY2VlZGluZyB0byBhIG5ldyByb3V0ZS4nLFxuICAgICAgfSlcbiAgICB9KVxuICAgIC5jYXRjaCgoYWN0aW9uOiBBY3Rpb24pID0+IHtcbiAgICAgIEVsTWVzc2FnZSh7XG4gICAgICAgIHR5cGU6ICdpbmZvJyxcbiAgICAgICAgbWVzc2FnZTpcbiAgICAgICAgICBhY3Rpb24gPT09ICdjYW5jZWwnXG4gICAgICAgICAgICA/ICdDaGFuZ2VzIGRpc2NhcmRlZC4gUHJvY2VlZGluZyB0byBhIG5ldyByb3V0ZS4nXG4gICAgICAgICAgICA6ICdTdGF5IGluIHRoZSBjdXJyZW50IHJvdXRlJyxcbiAgICAgIH0pXG4gICAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message-box/distinguishable-close-cancel.vue)_

vue

```
<template>
  <el-button plain @click="open">Click to open Message Box</el-button>
</template>

<script lang="ts" setup>
import { ElMessage, ElMessageBox } from 'element-plus'

import type { Action } from 'element-plus'

const open = () => {
  ElMessageBox.confirm(
    'You have unsaved changes, save and proceed?',
    'Confirm',
    {
      distinguishCancelAndClose: true,
      confirmButtonText: 'Save',
      cancelButtonText: 'Discard Changes',
    }
  )
    .then(() => {
      ElMessage({
        type: 'info',
        message: 'Changes saved. Proceeding to a new route.',
      })
    })
    .catch((action: Action) => {
      ElMessage({
        type: 'info',
        message:
          action === 'cancel'
            ? 'Changes discarded. Proceeding to a new route.'
            : 'Stay in the current route',
      })
    })
}
</script>
```

隐藏源代码

## 内容居中 [​](#内容居中)

消息弹框支持使用居中布局。

将 `center` 属性设置为 `true` 可将内容居中显示。

Click to open Message Box

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj5DbGljayB0byBvcGVuIE1lc3NhZ2UgQm94PC9lbC1idXR0b24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRWxNZXNzYWdlLCBFbE1lc3NhZ2VCb3ggfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IG9wZW4gPSAoKSA9PiB7XG4gIEVsTWVzc2FnZUJveC5jb25maXJtKFxuICAgICdwcm94eSB3aWxsIHBlcm1hbmVudGx5IGRlbGV0ZSB0aGUgZmlsZS4gQ29udGludWU/JyxcbiAgICAnV2FybmluZycsXG4gICAge1xuICAgICAgY29uZmlybUJ1dHRvblRleHQ6ICdPSycsXG4gICAgICBjYW5jZWxCdXR0b25UZXh0OiAnQ2FuY2VsJyxcbiAgICAgIHR5cGU6ICd3YXJuaW5nJyxcbiAgICAgIGNlbnRlcjogdHJ1ZSxcbiAgICB9XG4gIClcbiAgICAudGhlbigoKSA9PiB7XG4gICAgICBFbE1lc3NhZ2Uoe1xuICAgICAgICB0eXBlOiAnc3VjY2VzcycsXG4gICAgICAgIG1lc3NhZ2U6ICdEZWxldGUgY29tcGxldGVkJyxcbiAgICAgIH0pXG4gICAgfSlcbiAgICAuY2F0Y2goKCkgPT4ge1xuICAgICAgRWxNZXNzYWdlKHtcbiAgICAgICAgdHlwZTogJ2luZm8nLFxuICAgICAgICBtZXNzYWdlOiAnRGVsZXRlIGNhbmNlbGVkJyxcbiAgICAgIH0pXG4gICAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message-box/centered-content.vue)_

vue

```
<template>
  <el-button plain @click="open">Click to open Message Box</el-button>
</template>

<script lang="ts" setup>
import { ElMessage, ElMessageBox } from 'element-plus'

const open = () => {
  ElMessageBox.confirm(
    'proxy will permanently delete the file. Continue?',
    'Warning',
    {
      confirmButtonText: 'OK',
      cancelButtonText: 'Cancel',
      type: 'warning',
      center: true,
    }
  )
    .then(() => {
      ElMessage({
        type: 'success',
        message: 'Delete completed',
      })
    })
    .catch(() => {
      ElMessage({
        type: 'info',
        message: 'Delete canceled',
      })
    })
}
</script>
```

隐藏源代码

## 自定义图标 [​](#自定义图标)

图标可以使用任意Vue 组件或 [渲染函数 (JSX)](https://vuejs.org/guide/extras/render-function.html)来自定义。

Click to open Message Box

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj5DbGljayB0byBvcGVuIE1lc3NhZ2UgQm94PC9lbC1idXR0b24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgbWFya1JhdyB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVsTWVzc2FnZSwgRWxNZXNzYWdlQm94IH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuaW1wb3J0IHsgRGVsZXRlIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmNvbnN0IG9wZW4gPSAoKSA9PiB7XG4gIEVsTWVzc2FnZUJveC5jb25maXJtKFxuICAgICdJdCB3aWxsIHBlcm1hbmVudGx5IGRlbGV0ZSB0aGUgZmlsZS4gQ29udGludWU/JyxcbiAgICAnV2FybmluZycsXG4gICAge1xuICAgICAgY29uZmlybUJ1dHRvblRleHQ6ICdPSycsXG4gICAgICBjYW5jZWxCdXR0b25UZXh0OiAnQ2FuY2VsJyxcbiAgICAgIHR5cGU6ICd3YXJuaW5nJyxcbiAgICAgIGljb246IG1hcmtSYXcoRGVsZXRlKSxcbiAgICB9XG4gIClcbiAgICAudGhlbigoKSA9PiB7XG4gICAgICBFbE1lc3NhZ2Uoe1xuICAgICAgICB0eXBlOiAnc3VjY2VzcycsXG4gICAgICAgIG1lc3NhZ2U6ICdEZWxldGUgY29tcGxldGVkJyxcbiAgICAgIH0pXG4gICAgfSlcbiAgICAuY2F0Y2goKCkgPT4ge1xuICAgICAgRWxNZXNzYWdlKHtcbiAgICAgICAgdHlwZTogJ2luZm8nLFxuICAgICAgICBtZXNzYWdlOiAnRGVsZXRlIGNhbmNlbGVkJyxcbiAgICAgIH0pXG4gICAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message-box/customized-icon.vue)_

vue

```
<template>
  <el-button plain @click="open">Click to open Message Box</el-button>
</template>

<script lang="ts" setup>
import { markRaw } from 'vue'
import { ElMessage, ElMessageBox } from 'element-plus'
import { Delete } from '@element-plus/icons-vue'

const open = () => {
  ElMessageBox.confirm(
    'It will permanently delete the file. Continue?',
    'Warning',
    {
      confirmButtonText: 'OK',
      cancelButtonText: 'Cancel',
      type: 'warning',
      icon: markRaw(Delete),
    }
  )
    .then(() => {
      ElMessage({
        type: 'success',
        message: 'Delete completed',
      })
    })
    .catch(() => {
      ElMessage({
        type: 'info',
        message: 'Delete canceled',
      })
    })
}
</script>
```

隐藏源代码

## 可拖放 [​](#可拖放)

设置 MessageBox 可以拖拽。

设置`draggable`属性为`true`来开启拖拽弹窗能力。 设置 `overflow` 2.5.4 为 `true` 可以让拖拽范围超出可视区。

Open a draggable Message Box Open a overflow draggable Message Box Open a custom dragging style Message Box

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuXCI+XG4gICAgICBPcGVuIGEgZHJhZ2dhYmxlIE1lc3NhZ2UgQm94XG4gICAgPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgcGxhaW4gQGNsaWNrPVwib3BlbjJcIj5cbiAgICAgIE9wZW4gYSBvdmVyZmxvdyBkcmFnZ2FibGUgTWVzc2FnZSBCb3hcbiAgICA8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuM1wiPlxuICAgICAgT3BlbiBhIGN1c3RvbSBkcmFnZ2luZyBzdHlsZSBNZXNzYWdlIEJveFxuICAgIDwvZWwtYnV0dG9uPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBFbE1lc3NhZ2UsIEVsTWVzc2FnZUJveCB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3Qgb3BlbiA9ICgpID0+IHtcbiAgRWxNZXNzYWdlQm94LmNvbmZpcm0oXG4gICAgJ3Byb3h5IHdpbGwgcGVybWFuZW50bHkgZGVsZXRlIHRoZSBmaWxlLiBDb250aW51ZT8nLFxuICAgICdXYXJuaW5nJyxcbiAgICB7XG4gICAgICBjb25maXJtQnV0dG9uVGV4dDogJ09LJyxcbiAgICAgIGNhbmNlbEJ1dHRvblRleHQ6ICdDYW5jZWwnLFxuICAgICAgdHlwZTogJ3dhcm5pbmcnLFxuICAgICAgZHJhZ2dhYmxlOiB0cnVlLFxuICAgIH1cbiAgKVxuICAgIC50aGVuKCgpID0+IHtcbiAgICAgIEVsTWVzc2FnZSh7XG4gICAgICAgIHR5cGU6ICdzdWNjZXNzJyxcbiAgICAgICAgbWVzc2FnZTogJ0RlbGV0ZSBjb21wbGV0ZWQnLFxuICAgICAgfSlcbiAgICB9KVxuICAgIC5jYXRjaCgoKSA9PiB7XG4gICAgICBFbE1lc3NhZ2Uoe1xuICAgICAgICB0eXBlOiAnaW5mbycsXG4gICAgICAgIG1lc3NhZ2U6ICdEZWxldGUgY2FuY2VsZWQnLFxuICAgICAgfSlcbiAgICB9KVxufVxuXG5jb25zdCBvcGVuMiA9ICgpID0+IHtcbiAgRWxNZXNzYWdlQm94LmNvbmZpcm0oXG4gICAgJ3Byb3h5IHdpbGwgcGVybWFuZW50bHkgZGVsZXRlIHRoZSBmaWxlLiBDb250aW51ZT8nLFxuICAgICdXYXJuaW5nJyxcbiAgICB7XG4gICAgICBjb25maXJtQnV0dG9uVGV4dDogJ09LJyxcbiAgICAgIGNhbmNlbEJ1dHRvblRleHQ6ICdDYW5jZWwnLFxuICAgICAgdHlwZTogJ3dhcm5pbmcnLFxuICAgICAgZHJhZ2dhYmxlOiB0cnVlLFxuICAgICAgb3ZlcmZsb3c6IHRydWUsXG4gICAgfVxuICApXG4gICAgLnRoZW4oKCkgPT4ge1xuICAgICAgRWxNZXNzYWdlKHtcbiAgICAgICAgdHlwZTogJ3N1Y2Nlc3MnLFxuICAgICAgICBtZXNzYWdlOiAnRGVsZXRlIGNvbXBsZXRlZCcsXG4gICAgICB9KVxuICAgIH0pXG4gICAgLmNhdGNoKCgpID0+IHtcbiAgICAgIEVsTWVzc2FnZSh7XG4gICAgICAgIHR5cGU6ICdpbmZvJyxcbiAgICAgICAgbWVzc2FnZTogJ0RlbGV0ZSBjYW5jZWxlZCcsXG4gICAgICB9KVxuICAgIH0pXG59XG5cbmNvbnN0IG9wZW4zID0gKCkgPT4ge1xuICBFbE1lc3NhZ2VCb3guY29uZmlybShcbiAgICAnVGhpcyBtZXNzYWdlIGJveCBoYXMgY3VzdG9tIGRyYWdnaW5nIHN0eWxlcy4gVHJ5IGRyYWdnaW5nIGl0IHRvIHNlZSB0aGUgZWZmZWN0cyEnLFxuICAgICdDdXN0b20gRHJhZ2dpbmcgU3R5bGUnLFxuICAgIHtcbiAgICAgIGNvbmZpcm1CdXR0b25UZXh0OiAnT0snLFxuICAgICAgY2FuY2VsQnV0dG9uVGV4dDogJ0NhbmNlbCcsXG4gICAgICB0eXBlOiAnaW5mbycsXG4gICAgICBkcmFnZ2FibGU6IHRydWUsXG4gICAgICBjdXN0b21DbGFzczogJ2N1c3RvbS1kcmFnZ2luZy1tZXNzYWdlLWJveCcsXG4gICAgfVxuICApXG4gICAgLnRoZW4oKCkgPT4ge1xuICAgICAgRWxNZXNzYWdlKHtcbiAgICAgICAgdHlwZTogJ3N1Y2Nlc3MnLFxuICAgICAgICBtZXNzYWdlOiAnQWN0aW9uIGNvbXBsZXRlZCcsXG4gICAgICB9KVxuICAgIH0pXG4gICAgLmNhdGNoKCgpID0+IHtcbiAgICAgIEVsTWVzc2FnZSh7XG4gICAgICAgIHR5cGU6ICdpbmZvJyxcbiAgICAgICAgbWVzc2FnZTogJ0FjdGlvbiBjYW5jZWxlZCcsXG4gICAgICB9KVxuICAgIH0pXG59XG48L3NjcmlwdD5cblxuPHN0eWxlPlxuLmN1c3RvbS1kcmFnZ2luZy1tZXNzYWdlLWJveC5pcy1kcmFnZ2luZyB7XG4gIGJvcmRlcjogMnB4IGRhc2hlZCB2YXIoLS1lbC1jb2xvci1wcmltYXJ5KTtcbiAgb3BhY2l0eTogMC42NTtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/message-box/draggable.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" plain @click="open">
      Open a draggable Message Box
    </el-button>
    <el-button class="!ml-0" plain @click="open2">
      Open a overflow draggable Message Box
    </el-button>
    <el-button class="!ml-0" plain @click="open3">
      Open a custom dragging style Message Box
    </el-button>
  </div>
</template>

<script lang="ts" setup>
import { ElMessage, ElMessageBox } from 'element-plus'

const open = () => {
  ElMessageBox.confirm(
    'proxy will permanently delete the file. Continue?',
    'Warning',
    {
      confirmButtonText: 'OK',
      cancelButtonText: 'Cancel',
      type: 'warning',
      draggable: true,
    }
  )
    .then(() => {
      ElMessage({
        type: 'success',
        message: 'Delete completed',
      })
    })
    .catch(() => {
      ElMessage({
        type: 'info',
        message: 'Delete canceled',
      })
    })
}

const open2 = () => {
  ElMessageBox.confirm(
    'proxy will permanently delete the file. Continue?',
    'Warning',
    {
      confirmButtonText: 'OK',
      cancelButtonText: 'Cancel',
      type: 'warning',
      draggable: true,
      overflow: true,
    }
  )
    .then(() => {
      ElMessage({
        type: 'success',
        message: 'Delete completed',
      })
    })
    .catch(() => {
      ElMessage({
        type: 'info',
        message: 'Delete canceled',
      })
    })
}

const open3 = () => {
  ElMessageBox.confirm(
    'This message box has custom dragging styles. Try dragging it to see the effects!',
    'Custom Dragging Style',
    {
      confirmButtonText: 'OK',
      cancelButtonText: 'Cancel',
      type: 'info',
      draggable: true,
      customClass: 'custom-dragging-message-box',
    }
  )
    .then(() => {
      ElMessage({
        type: 'success',
        message: 'Action completed',
      })
    })
    .catch(() => {
      ElMessage({
        type: 'info',
        message: 'Action canceled',
      })
    })
}
</script>

<style>
.custom-dragging-message-box.is-dragging {
  border: 2px dashed var(--el-color-primary);
  opacity: 0.65;
}
</style>
```

隐藏源代码

## 全局方法 [​](#全局方法)

如果你完整引入了 Element，它会为 `app.config.globalProperties` 添加如下全局方法：`$msgbox`、 `$alert`、 `$confirm` 和 `$prompt`。 因此在 Vue 实例中可以采用本页面中的方式来调用`MessageBox`。 参数如下：

-   `$msgbox(options)`
-   `$alert(message, title, options)` 或 `$alert(message, options)`
-   `$confirm(message, title, options)` 或 `$confirm(message, options)`
-   `$prompt(message, title, options)` 或 `$prompt(message, options)`

## 应用程序上下文继承 \> 2.0.4 [​](#应用程序上下文继承-2-0-4)

现在，消息框构造函数支持将 `context` 作为第二个参数（如果你使用的是消息框变体，则为第四个参数），这样你就可以向消息中注入当前应用的上下文，从而继承应用中的所有属性。

ts

```
import { getCurrentInstance } from 'vue'
import { ElMessageBox } from 'element-plus'

// 在你的 setup 方法中
const { appContext } = getCurrentInstance()!
// 你可以像这样传递参数：
ElMessageBox({}, appContext)
// 或者正在使用不同的调用方式
ElMessageBox.alert('Hello world!', 'Title', {}, appContext)
```

## 按需引入 [​](#按需引入)

如果您需要按需引入 `MessageBox`：

ts

```
import { ElMessageBox } from 'element-plus'
```

那么对应于上述四个全局方法的调用方法依次为：`ElMessageBox`、`ElMessageBox.alert`、`ElMessageBox.confirm` 和 `ElMessageBox.prompt`。 参数同上所述。

## API [​](#api)

### 配置项 [​](#配置项)

| 属性名 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| autofocus | 打开 MessageBox 时是否自动获得焦点 | `boolean` | true |
| title | MessageBox 的标题 | `string` | '' |
| message | MessageBox 的正文内容 | `string` / `VNode` / `Function` 2.2.17 / `Function` 2.14.0 | — |
| dangerouslyUseHTMLString | 是否将 `message` 作为 HTML 片段处理 | `boolean` | false |
| type | 消息类型，用于图标显示 | `enum` | '' |
| icon | 自定义图标组件，会覆盖 `type` 的类型 | `string` / `Component` | '' |
| closeIcon 2.9.5 | 自定义关闭图标组件，默认是 Close | `string` / `Component` | '' |
| customClass | MessageBox 的自定义类名 | `string` | '' |
| customStyle | MessageBox 的自定义内联样式 | `CSSProperties` | {} |
| modal | 是否需要遮罩层 | `boolean` | true |
| modalClass | 遮罩的自定义类名 | string | — |
| callback | 若不使用 Promise，可以使用此参数指定 MessageBox 关闭后的回调 | `Function` | null |
| showClose | MessageBox 是否显示右上角关闭按钮 | `boolean` | true |
| beforeClose | messageBox 关闭前的回调，会暂停消息弹出框的关闭过程。 | `Function` | null |
| distinguishCancelAndClose | 是否将取消（点击取消按钮）与关闭（点击关闭按钮或遮罩层、按下 Esc 键）进行区分 | `boolean` | false |
| lockScroll | 是否在 MessageBox 出现时将 body 滚动锁定 | `boolean` | true |
| showCancelButton | 是否显示取消按钮 | `boolean` | false（以 confirm 和 prompt 方式调用时为 true） |
| showConfirmButton | 是否显示确定按钮 | `boolean` | true |
| cancelButtonText | 取消按钮的文本内容 | `string` | 取消 |
| confirmButtonText | 确定按钮的文本内容 | `string` | 确定 |
| cancelButtonType 2.13.1 | 取消按钮的类型 | `enum` | — |
| confirmButtonType 2.13.1 | 确认按钮类型 | `enum` | primary |
| cancelButtonLoadingIcon 2.7.7 | 取消按钮的加载图标内容 | `string` / `Component` | Loading |
| confirmButtonLoadingIcon 2.7.7 | 确认按钮的加载图标内容 | `string` / `Component` | Loading |
| cancelButtonClass | 取消按钮的自定义类名 | `string` | '' |
| confirmButtonClass | 确定按钮的自定义类名 | `string` | '' |
| closeOnClickModal | 是否可通过点击遮罩层关闭 MessageBox | `boolean` | true（以 alert 方式调用时为 false） |
| closeOnPressEscape | 是否可通过按下 ESC 键关闭 MessageBox | `boolean` | true（以 alert 方式调用时为 false） |
| closeOnHashChange | 是否在 hash 改变时关闭 MessageBox | `boolean` | true |
| showInput | 是否显示输入框 | `boolean` | false（以 prompt 方式调用时为 true） |
| inputPlaceholder | 输入框占位文本 | `string` | '' |
| inputType | 输入类型，更多信息请参见 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types) | `string` | text |
| inputValue | 输入框的初始文本 | `string` | '' |
| inputPattern | 输入框的校验表达式 | `regexp` | null |
| inputValidator | 输入框的校验函数。 应该返回一个 boolean 或者 string， 如果返回的是一个 string 类型，那么该返回值会被赋值给 inputErrorMessage 用于向用户展示错误消息。 | `Function`/ `undefined` | undefined |
| inputErrorMessage | 校验未通过时的提示文本 | `string` | 输入的数据不合法! |
| center | 是否居中布局 | `boolean` | false |
| draggable | MessageBox 是否可拖放 | `boolean` | false |
| overflow 2.5.4 | MessageBox 拖动范围可以超出可视区 | `boolean` | false |
| roundButton | 是否使用圆角按钮 | `boolean` | false |
| buttonSize | 自定义确认按钮及取消按钮的大小 | `string` | default |
| appendTo 2.2.19 | 设置组件的根元素 | `CSSSelector` / `HTMLElement` | ::: |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/message-box) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/message-box.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/message-box.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/50739490?v=4&size=64)](https://github.com/Chuck-Lau)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/10278227?v=4&size=64)](https://github.com/HeftyKoo)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/182307812?v=4&size=64)](https://github.com/whcanic)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/13410410?v=4&size=64)](https://github.com/jaa134)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/12488719?v=4&size=64)](https://github.com/a3660980)[![](https://avatars.githubusercontent.com/u/65892539?v=4&size=64)](https://github.com/xionkq)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/29518699?v=4&size=64)](https://github.com/reiwang01)[![](https://avatars.githubusercontent.com/u/66702442?v=4&size=64)](https://github.com/danny-hebert)[![](https://avatars.githubusercontent.com/u/25543909?v=4&size=64)](https://github.com/MMmaXingXing)[![](https://avatars.githubusercontent.com/u/60056876?v=4&size=64)](https://github.com/LinZhanMing)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/43326199?v=4&size=64)](https://github.com/Wiensss)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/46836729?v=4&size=64)](https://github.com/yuzhang9804)[![](https://avatars.githubusercontent.com/u/15833290?v=4&size=64)](https://github.com/zhousg)[![](https://avatars.githubusercontent.com/u/29992752?v=4&size=64)](https://github.com/llllllllllx)[![](https://avatars.githubusercontent.com/u/31462942?v=4&size=64)](https://github.com/zhazhanitian)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/234919486?v=4&size=64)](https://github.com/linzx-jess)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/57785259?v=4&size=64)](https://github.com/w2xi)[![](https://avatars.githubusercontent.com/u/52314078?v=4&size=64)](https://github.com/vaebe)[![](https://avatars.githubusercontent.com/u/78132554?v=4&size=64)](https://github.com/momei-LJM)[![](https://avatars.githubusercontent.com/u/8591261?v=4&size=64)](https://github.com/zeyongTsai)[![](https://avatars.githubusercontent.com/u/22388686?v=4&size=64)](https://github.com/TomatoDroid)[![](https://avatars.githubusercontent.com/u/121680374?v=4&size=64)](https://github.com/kaine0923)

[Message 消息提示](https://element-plus.org/zh-CN/component/message)

[Notification 通知](https://element-plus.org/zh-CN/component/notification)




---
## [feedback/notification] Notification 通知
> 官方文档: https://element-plus.org/zh-CN/component/notification.html

---

# Notification 通知 [​](#notification-通知)

更新日志待解决

2

悬浮出现在页面角落，显示全局的通知提醒消息。

## 基础用法 [​](#基础用法)

Element Plus 注册了 `$notify` 方法并且它接受一个 Object 作为其参数。 在最简单的情况下，你可以通过设置 `title` 和 `message` 属性来设置通知的标题和正文内容。 默认情况下，通知在4500毫秒后自动关闭，但你可以通过设置 `duration` 属性来自定义通知的展示时间。 如果你将它设置为 `0`，那么通知将不会自动关闭。 需要注意的是 `duration` 接收一个 `Number`，单位为毫秒。

Closes automatically Won't close automatically

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuMVwiPlxuICAgICAgQ2xvc2VzIGF1dG9tYXRpY2FsbHlcbiAgICA8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuMlwiPlxuICAgICAgV29uJ3QgY2xvc2UgYXV0b21hdGljYWxseVxuICAgIDwvZWwtYnV0dG9uPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBoIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgRWxOb3RpZmljYXRpb24gfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IG9wZW4xID0gKCkgPT4ge1xuICBFbE5vdGlmaWNhdGlvbih7XG4gICAgdGl0bGU6ICdUaXRsZScsXG4gICAgbWVzc2FnZTogaCgnaScsIHsgc3R5bGU6ICdjb2xvcjogdGVhbCcgfSwgJ1RoaXMgaXMgYSByZW1pbmRlcicpLFxuICB9KVxufVxuXG5jb25zdCBvcGVuMiA9ICgpID0+IHtcbiAgRWxOb3RpZmljYXRpb24oe1xuICAgIHRpdGxlOiAnUHJvbXB0JyxcbiAgICBtZXNzYWdlOiAnVGhpcyBpcyBhIG1lc3NhZ2UgdGhhdCBkb2VzIG5vdCBhdXRvbWF0aWNhbGx5IGNsb3NlJyxcbiAgICBkdXJhdGlvbjogMCxcbiAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/notification/basic.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" plain @click="open1">
      Closes automatically
    </el-button>
    <el-button class="!ml-0" plain @click="open2">
      Won't close automatically
    </el-button>
  </div>
</template>

<script lang="ts" setup>
import { h } from 'vue'
import { ElNotification } from 'element-plus'

const open1 = () => {
  ElNotification({
    title: 'Title',
    message: h('i', { style: 'color: teal' }, 'This is a reminder'),
  })
}

const open2 = () => {
  ElNotification({
    title: 'Prompt',
    message: 'This is a message that does not automatically close',
    duration: 0,
  })
}
</script>
```

隐藏源代码

## 不同类型的通知 [​](#不同类型的通知)

我们提供了四种不同类型的提醒框：success、warning、info 和error。

Element Plus 为 Notification 组件准备了5种通知类型：`primary`,`success`, `warning`, `info`, `error`。 他们可以设置 `type` 字段来修改，除上述的四个值之外的值会被忽略。 同时，我们也为 Notification 的各种 type 注册了单独的方法，可以在不传入 `type` 字段的情况下像 `open3` 和 `open4` 那样直接调用。 `primary` 已被添加到2.9.11。

PrimarySuccessWarningInfoError

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuNVwiPlByaW1hcnk8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuMVwiPlN1Y2Nlc3M8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuMlwiPldhcm5pbmc8L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuM1wiPkluZm88L2VsLWJ1dHRvbj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuNFwiPkVycm9yPC9lbC1idXR0b24+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IEVsTm90aWZpY2F0aW9uIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvcGVuMSA9ICgpID0+IHtcbiAgRWxOb3RpZmljYXRpb24oe1xuICAgIHRpdGxlOiAnU3VjY2VzcycsXG4gICAgbWVzc2FnZTogJ1RoaXMgaXMgYSBzdWNjZXNzIG1lc3NhZ2UnLFxuICAgIHR5cGU6ICdzdWNjZXNzJyxcbiAgfSlcbn1cblxuY29uc3Qgb3BlbjIgPSAoKSA9PiB7XG4gIEVsTm90aWZpY2F0aW9uKHtcbiAgICB0aXRsZTogJ1dhcm5pbmcnLFxuICAgIG1lc3NhZ2U6ICdUaGlzIGlzIGEgd2FybmluZyBtZXNzYWdlJyxcbiAgICB0eXBlOiAnd2FybmluZycsXG4gIH0pXG59XG5cbmNvbnN0IG9wZW4zID0gKCkgPT4ge1xuICBFbE5vdGlmaWNhdGlvbih7XG4gICAgdGl0bGU6ICdJbmZvJyxcbiAgICBtZXNzYWdlOiAnVGhpcyBpcyBhbiBpbmZvIG1lc3NhZ2UnLFxuICAgIHR5cGU6ICdpbmZvJyxcbiAgfSlcbn1cblxuY29uc3Qgb3BlbjQgPSAoKSA9PiB7XG4gIEVsTm90aWZpY2F0aW9uKHtcbiAgICB0aXRsZTogJ0Vycm9yJyxcbiAgICBtZXNzYWdlOiAnVGhpcyBpcyBhbiBlcnJvciBtZXNzYWdlJyxcbiAgICB0eXBlOiAnZXJyb3InLFxuICB9KVxufVxuXG5jb25zdCBvcGVuNSA9ICgpID0+IHtcbiAgRWxOb3RpZmljYXRpb24oe1xuICAgIHRpdGxlOiAnUHJpbWFyeScsXG4gICAgbWVzc2FnZTogJ1RoaXMgaXMgYSBwcmltYXJ5IG1lc3NhZ2UnLFxuICAgIHR5cGU6ICdwcmltYXJ5JyxcbiAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/notification/different-types.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" plain @click="open5">Primary</el-button>
    <el-button class="!ml-0" plain @click="open1">Success</el-button>
    <el-button class="!ml-0" plain @click="open2">Warning</el-button>
    <el-button class="!ml-0" plain @click="open3">Info</el-button>
    <el-button class="!ml-0" plain @click="open4">Error</el-button>
  </div>
</template>

<script lang="ts" setup>
import { ElNotification } from 'element-plus'

const open1 = () => {
  ElNotification({
    title: 'Success',
    message: 'This is a success message',
    type: 'success',
  })
}

const open2 = () => {
  ElNotification({
    title: 'Warning',
    message: 'This is a warning message',
    type: 'warning',
  })
}

const open3 = () => {
  ElNotification({
    title: 'Info',
    message: 'This is an info message',
    type: 'info',
  })
}

const open4 = () => {
  ElNotification({
    title: 'Error',
    message: 'This is an error message',
    type: 'error',
  })
}

const open5 = () => {
  ElNotification({
    title: 'Primary',
    message: 'This is a primary message',
    type: 'primary',
  })
}
</script>
```

隐藏源代码

## 自定义消息弹出的位置 [​](#自定义消息弹出的位置)

可以让 Notification 从屏幕四角中的任意一角弹出

使用 `position` 属性设置 Notification 的弹出位置， 支持四个选项：`top-right`、`top-left`、`bottom-right` 和 `bottom-left`， 默认为 `top-right`。

Top Right Bottom Right Bottom Left Top Left

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuMVwiPiBUb3AgUmlnaHQgPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgcGxhaW4gQGNsaWNrPVwib3BlbjJcIj4gQm90dG9tIFJpZ2h0IDwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gY2xhc3M9XCIhbWwtMFwiIHBsYWluIEBjbGljaz1cIm9wZW4zXCI+IEJvdHRvbSBMZWZ0IDwvZWwtYnV0dG9uPlxuICAgIDxlbC1idXR0b24gY2xhc3M9XCIhbWwtMFwiIHBsYWluIEBjbGljaz1cIm9wZW40XCI+IFRvcCBMZWZ0IDwvZWwtYnV0dG9uPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBFbE5vdGlmaWNhdGlvbiB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3Qgb3BlbjEgPSAoKSA9PiB7XG4gIEVsTm90aWZpY2F0aW9uKHtcbiAgICB0aXRsZTogJ0N1c3RvbSBQb3NpdGlvbicsXG4gICAgbWVzc2FnZTogXCJJJ20gYXQgdGhlIHRvcCByaWdodCBjb3JuZXJcIixcbiAgfSlcbn1cblxuY29uc3Qgb3BlbjIgPSAoKSA9PiB7XG4gIEVsTm90aWZpY2F0aW9uKHtcbiAgICB0aXRsZTogJ0N1c3RvbSBQb3NpdGlvbicsXG4gICAgbWVzc2FnZTogXCJJJ20gYXQgdGhlIGJvdHRvbSByaWdodCBjb3JuZXJcIixcbiAgICBwb3NpdGlvbjogJ2JvdHRvbS1yaWdodCcsXG4gIH0pXG59XG5cbmNvbnN0IG9wZW4zID0gKCkgPT4ge1xuICBFbE5vdGlmaWNhdGlvbih7XG4gICAgdGl0bGU6ICdDdXN0b20gUG9zaXRpb24nLFxuICAgIG1lc3NhZ2U6IFwiSSdtIGF0IHRoZSBib3R0b20gbGVmdCBjb3JuZXJcIixcbiAgICBwb3NpdGlvbjogJ2JvdHRvbS1sZWZ0JyxcbiAgfSlcbn1cblxuY29uc3Qgb3BlbjQgPSAoKSA9PiB7XG4gIEVsTm90aWZpY2F0aW9uKHtcbiAgICB0aXRsZTogJ0N1c3RvbSBQb3NpdGlvbicsXG4gICAgbWVzc2FnZTogXCJJJ20gYXQgdGhlIHRvcCBsZWZ0IGNvcm5lclwiLFxuICAgIHBvc2l0aW9uOiAndG9wLWxlZnQnLFxuICB9KVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/notification/positioning.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" plain @click="open1"> Top Right </el-button>
    <el-button class="!ml-0" plain @click="open2"> Bottom Right </el-button>
    <el-button class="!ml-0" plain @click="open3"> Bottom Left </el-button>
    <el-button class="!ml-0" plain @click="open4"> Top Left </el-button>
  </div>
</template>

<script lang="ts" setup>
import { ElNotification } from 'element-plus'

const open1 = () => {
  ElNotification({
    title: 'Custom Position',
    message: "I'm at the top right corner",
  })
}

const open2 = () => {
  ElNotification({
    title: 'Custom Position',
    message: "I'm at the bottom right corner",
    position: 'bottom-right',
  })
}

const open3 = () => {
  ElNotification({
    title: 'Custom Position',
    message: "I'm at the bottom left corner",
    position: 'bottom-left',
  })
}

const open4 = () => {
  ElNotification({
    title: 'Custom Position',
    message: "I'm at the top left corner",
    position: 'top-left',
  })
}
</script>
```

隐藏源代码

## 有位置偏移的通知栏 [​](#有位置偏移的通知栏)

能够设置偏移量来使 Notification 偏移默认位置。

Notification 提供设置偏移量的功能，通过设置 `offset` 字段，可以使弹出的消息距屏幕边缘偏移一段距离。 注意在同一时刻，每一个的 Notification 实例应当具有一个相同的偏移量。

Notification with offset

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj4gTm90aWZpY2F0aW9uIHdpdGggb2Zmc2V0IDwvZWwtYnV0dG9uPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IEVsTm90aWZpY2F0aW9uIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvcGVuID0gKCkgPT4ge1xuICBFbE5vdGlmaWNhdGlvbi5zdWNjZXNzKHtcbiAgICB0aXRsZTogJ1N1Y2Nlc3MnLFxuICAgIG1lc3NhZ2U6ICdUaGlzIGlzIGEgc3VjY2VzcyBtZXNzYWdlJyxcbiAgICBvZmZzZXQ6IDEwMCxcbiAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/notification/offsetting.vue)_

vue

```
<template>
  <el-button plain @click="open"> Notification with offset </el-button>
</template>

<script lang="ts" setup>
import { ElNotification } from 'element-plus'

const open = () => {
  ElNotification.success({
    title: 'Success',
    message: 'This is a success message',
    offset: 100,
  })
}
</script>
```

隐藏源代码

## 使用 HTML 片段作为正文内容 [​](#使用-html-片段作为正文内容)

`message` 支持传入 HTML 字符串来作为正文内容。

将 `dangerouslyUseHTMLString` 属性设置为 true，`message` 属性就会被当作 HTML 片段处理。

Use HTML String

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj4gVXNlIEhUTUwgU3RyaW5nIDwvZWwtYnV0dG9uPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IEVsTm90aWZpY2F0aW9uIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBvcGVuID0gKCkgPT4ge1xuICBFbE5vdGlmaWNhdGlvbih7XG4gICAgdGl0bGU6ICdIVE1MIFN0cmluZycsXG4gICAgZGFuZ2Vyb3VzbHlVc2VIVE1MU3RyaW5nOiB0cnVlLFxuICAgIG1lc3NhZ2U6ICc8c3Ryb25nPlRoaXMgaXMgPGk+SFRNTDwvaT4gc3RyaW5nPC9zdHJvbmc+JyxcbiAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/notification/raw-html.vue)_

vue

```
<template>
  <el-button plain @click="open"> Use HTML String </el-button>
</template>

<script lang="ts" setup>
import { ElNotification } from 'element-plus'

const open = () => {
  ElNotification({
    title: 'HTML String',
    dangerouslyUseHTMLString: true,
    message: '<strong>This is <i>HTML</i> string</strong>',
  })
}
</script>
```

隐藏源代码

WARNING

`message` 属性虽然支持传入 HTML 片段，但是在网站上动态渲染任意 HTML 是非常危险的，因为容易导致 [XSS 攻击](https://en.wikipedia.org/wiki/Cross-site_scripting)。 因此在 `dangerouslyUseHTMLString` 打开的情况下，请确保 `message` 的内容是可信的，**永远不要**将用户提交的内容赋值给 `message` 属性。

## 函数形式的 message 2.9.0 [​](#函数形式的-message)

`message` 可以是 VNode。

在2.9.0之后， `message` 支持返回值为 VNode的函数。

Common VNodeDynamic props

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwiZmxleCBmbGV4LXdyYXAgZ2FwLTFcIj5cbiAgICA8ZWwtYnV0dG9uIGNsYXNzPVwiIW1sLTBcIiBwbGFpbiBAY2xpY2s9XCJvcGVuXCI+Q29tbW9uIFZOb2RlPC9lbC1idXR0b24+XG4gICAgPGVsLWJ1dHRvbiBjbGFzcz1cIiFtbC0wXCIgcGxhaW4gQGNsaWNrPVwib3BlbjFcIj5EeW5hbWljIHByb3BzPC9lbC1idXR0b24+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IGgsIHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEVsTm90aWZpY2F0aW9uLCBFbFN3aXRjaCB9IGZyb20gJ2VsZW1lbnQtcGx1cydcblxuY29uc3Qgb3BlbiA9ICgpID0+IHtcbiAgRWxOb3RpZmljYXRpb24oe1xuICAgIHRpdGxlOiAnVXNlIFZub2RlJyxcbiAgICBtZXNzYWdlOiBoKCdwJywgbnVsbCwgW1xuICAgICAgaCgnc3BhbicsIG51bGwsICdNZXNzYWdlIGNhbiBiZSAnKSxcbiAgICAgIGgoJ2knLCB7IHN0eWxlOiAnY29sb3I6IHRlYWwnIH0sICdWTm9kZScpLFxuICAgIF0pLFxuICB9KVxufVxuXG5jb25zdCBvcGVuMSA9ICgpID0+IHtcbiAgY29uc3QgY2hlY2tlZCA9IHJlZjxib29sZWFuIHwgc3RyaW5nIHwgbnVtYmVyPihmYWxzZSlcbiAgRWxOb3RpZmljYXRpb24oe1xuICAgIHRpdGxlOiAnVXNlIFZub2RlJyxcbiAgICAvLyBTaG91bGQgcGFzcyBhIGZ1bmN0aW9uIGlmIFZOb2RlIGNvbnRhaW5zIGR5bmFtaWMgcHJvcHNcbiAgICBtZXNzYWdlOiAoKSA9PlxuICAgICAgaChFbFN3aXRjaCwge1xuICAgICAgICBtb2RlbFZhbHVlOiBjaGVja2VkLnZhbHVlLFxuICAgICAgICAnb25VcGRhdGU6bW9kZWxWYWx1ZSc6ICh2YWw6IGJvb2xlYW4gfCBzdHJpbmcgfCBudW1iZXIpID0+IHtcbiAgICAgICAgICBjaGVja2VkLnZhbHVlID0gdmFsXG4gICAgICAgIH0sXG4gICAgICB9KSxcbiAgfSlcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/notification/use-vnode.vue)_

vue

```
<template>
  <div class="flex flex-wrap gap-1">
    <el-button class="!ml-0" plain @click="open">Common VNode</el-button>
    <el-button class="!ml-0" plain @click="open1">Dynamic props</el-button>
  </div>
</template>

<script lang="ts" setup>
import { h, ref } from 'vue'
import { ElNotification, ElSwitch } from 'element-plus'

const open = () => {
  ElNotification({
    title: 'Use Vnode',
    message: h('p', null, [
      h('span', null, 'Message can be '),
      h('i', { style: 'color: teal' }, 'VNode'),
    ]),
  })
}

const open1 = () => {
  const checked = ref<boolean | string | number>(false)
  ElNotification({
    title: 'Use Vnode',
    // Should pass a function if VNode contains dynamic props
    message: () =>
      h(ElSwitch, {
        modelValue: checked.value,
        'onUpdate:modelValue': (val: boolean | string | number) => {
          checked.value = val
        },
      }),
  })
}
</script>
```

隐藏源代码

## 隐藏关闭按钮 [​](#隐藏关闭按钮)

通知的关闭按钮可以被设置为隐藏。

将 `showClose` 属性设置为 `false` 即可隐藏关闭按钮。

Hide close button

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHBsYWluIEBjbGljaz1cIm9wZW5cIj4gSGlkZSBjbG9zZSBidXR0b24gPC9lbC1idXR0b24+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuaW1wb3J0IHsgRWxOb3RpZmljYXRpb24gfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmNvbnN0IG9wZW4gPSAoKSA9PiB7XG4gIEVsTm90aWZpY2F0aW9uLnN1Y2Nlc3Moe1xuICAgIHRpdGxlOiAnSW5mbycsXG4gICAgbWVzc2FnZTogJ1RoaXMgaXMgYSBtZXNzYWdlIHdpdGhvdXQgY2xvc2UgYnV0dG9uJyxcbiAgICBzaG93Q2xvc2U6IGZhbHNlLFxuICB9KVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/notification/no-close.vue)_

vue

```
<template>
  <el-button plain @click="open"> Hide close button </el-button>
</template>

<script lang="ts" setup>
import { ElNotification } from 'element-plus'

const open = () => {
  ElNotification.success({
    title: 'Info',
    message: 'This is a message without close button',
    showClose: false,
  })
}
</script>
```

隐藏源代码

## 全局方法 [​](#全局方法)

Element Plus 为 `app.config.globalProperties` 添加了全局方法 `$notify`。 因此在 Vue instance 中可以采用本页面中的方式调用 `Notification`。

## 单独引用 [​](#单独引用)

javascript

```
import { ElNotification } from 'element-plus'
import { CloseBold } from '@element-plus/icons-vue'

ElNotification({
  title: 'Title',
  message: 'This is a message',
  closeIcon: CloseBold,
})
```

你可以在对应的处理函数内调用 `ElNotification(options)` 来呼出通知栏。 我们也提前定义了多个 type 的单独调用方法，如 `ElNotification.success(options)`。 当你需要关闭页面上所有的通知栏的时候，可以调用 `ElNotification.closeAll()` 来关闭所有的实例。 在 2.10.5 版本中，你可以通过调用 `ElNotification.updateOffsets(position)` 手动更新所有通知实例在特定方向上的偏移量。

## 应用程序上下文继承 \> 2.0.4 [​](#应用程序上下文继承-2-0-4)

现在 Notification 接受一条 `context` 作为消息构造器的第二个参数，允许你将当前应用的上下文注入到 Notification 中，这将允许你继承应用程序的所有属性。

你可以像这样使用它：

TIP

如果您全局注册了 ElNotification 组件，它将自动继承应用的上下文环境。

ts

```
import { getCurrentInstance } from 'vue'
import { ElNotification } from 'element-plus'

// 在你的 setup 方法中
const { appContext } = getCurrentInstance()!
ElNotification({}, appContext)
```

## API [​](#api)

### 配置项 [​](#配置项)

| 名称 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| title | title | `string` | '' |
| message | 通知栏正文内容 | `string` / `VNode` / `Function` | '' |
| dangerouslyUseHTMLString | 是否将 message 属性作为 HTML 片段处理 | `boolean` | false |
| type | 通知的类型 | `enum` | '' |
| icon | 自定义图标。 若设置了 `type`，则 `icon` 会被覆盖 | `string` / `Component` | — |
| customClass | 自定义类名 | `string` | '' |
| duration | 显示时间, 单位为毫秒。 值为 0 则不会自动关闭 | `number` | 4500 |
| position | 自定义弹出位置 | `enum` | top-right |
| showClose | 是否显示关闭按钮 | `boolean` | true |
| onClose | 关闭时的回调函数 | `Function` | — |
| onClick | 点击 Notification 时的回调函数 | `Function` | — |
| offset | 相对屏幕顶部的偏移量 偏移的距离，在同一时刻，所有的 Notification 实例应当具有一个相同的偏移量 | `number` | 0 |
| appendTo | 设置 notification 的根元素，默认为 `document.body` | `CSSSelector` / `HTMLElement` | — |
| zIndex | 初始 zIndex | `number` | 0 |
| closeIcon 2.9.8 | 自定义关闭图标 | `string` / `Component` | Close |

### 方法 [​](#方法)

`Notification` 和 `this.$notify` 都返回当前的 Notification 实例。 如果需要手动关闭实例，可以调用它的 `close` 方法。

| 名称 | 详情 | 类型 |
| --- | --- | --- |
| close | 关闭当前的 Notification | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/notification) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/notification.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/notification.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/57785259?v=4&size=64)](https://github.com/w2xi)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/14144811?v=4&size=64)](https://github.com/cn-xufei)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/132551120?v=4&size=64)](https://github.com/YiMo1)[![](https://avatars.githubusercontent.com/u/43703884?v=4&size=64)](https://github.com/DDDDD12138)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/31533594?v=4&size=64)](https://github.com/Gnalvin)[![](https://avatars.githubusercontent.com/u/10301686?v=4&size=64)](https://github.com/acfinity)[![](https://avatars.githubusercontent.com/u/169252980?v=4&size=64)](https://github.com/xiaochenchen-igg-com)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/49446662?v=4&size=64)](https://github.com/codespikey)[![](https://avatars.githubusercontent.com/u/43257608?v=4&size=64)](https://github.com/Liao-js)[![](https://avatars.githubusercontent.com/u/15535177?v=4&size=64)](https://github.com/liuzi6612)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/32129111?v=4&size=64)](https://github.com/Vgbire)[![](https://avatars.githubusercontent.com/u/33176053?v=4&size=64)](https://github.com/Ryan2128)[![](https://avatars.githubusercontent.com/u/57524062?v=4&size=64)](https://github.com/Ther-su)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)

[Message Box 消息弹出框](https://element-plus.org/zh-CN/component/message-box)

[Popconfirm 气泡确认框](https://element-plus.org/zh-CN/component/popconfirm)




---
## [feedback/popconfirm] Popconfirm 气泡确认框
> 官方文档: https://element-plus.org/zh-CN/component/popconfirm.html

---

# Popconfirm 气泡确认框 [​](#popconfirm-气泡确认框)

更新日志待解决

4

点击某个元素弹出一个简单的气泡确认框

## 展示位置 [​](#展示位置)

Popconfirm 提供 9 种展示位置。

使用 `title` 属性来设置点击参考元素时显示的信息。 由 `placement` 属性决定 Popconfirm 的位置。 该属性值格式为：`[方向]-[对齐位置]`，可供选择的四个方向分别是`top`、`left`、`right`、`bottom`，可供选择的三种对齐方式分别是`start`、`end`、`null`，默认的对齐方式为null。 以 `placement="left-end"` 为例，气泡确认框会显示在悬停元素的左侧，且提示信息的底部与悬停元素的底部对齐。

top-starttoptop-end

left-startright-start

leftright

left-endright-end

bottom-startbottombottom-end

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwicG9wY29uZmlybS1iYXNlLWJveFwiPlxuICAgIDxkaXYgY2xhc3M9XCJyb3cgY2VudGVyXCI+XG4gICAgICA8ZWwtcG9wY29uZmlybVxuICAgICAgICBjbGFzcz1cImJveC1pdGVtXCJcbiAgICAgICAgdGl0bGU9XCJUb3AgTGVmdCBwcm9tcHRzIGluZm9cIlxuICAgICAgICBwbGFjZW1lbnQ9XCJ0b3Atc3RhcnRcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT5cbiAgICAgICAgICA8ZWwtYnV0dG9uPnRvcC1zdGFydDwvZWwtYnV0dG9uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1wb3Bjb25maXJtPlxuICAgICAgPGVsLXBvcGNvbmZpcm1cbiAgICAgICAgY2xhc3M9XCJib3gtaXRlbVwiXG4gICAgICAgIHRpdGxlPVwiVG9wIENlbnRlciBwcm9tcHRzIGluZm9cIlxuICAgICAgICBwbGFjZW1lbnQ9XCJ0b3BcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT5cbiAgICAgICAgICA8ZWwtYnV0dG9uPnRvcDwvZWwtYnV0dG9uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1wb3Bjb25maXJtPlxuICAgICAgPGVsLXBvcGNvbmZpcm1cbiAgICAgICAgY2xhc3M9XCJib3gtaXRlbVwiXG4gICAgICAgIHRpdGxlPVwiVG9wIFJpZ2h0IHByb21wdHMgaW5mb1wiXG4gICAgICAgIHBsYWNlbWVudD1cInRvcC1lbmRcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT5cbiAgICAgICAgICA8ZWwtYnV0dG9uPnRvcC1lbmQ8L2VsLWJ1dHRvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtcG9wY29uZmlybT5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwicm93XCI+XG4gICAgICA8ZWwtcG9wY29uZmlybVxuICAgICAgICBjbGFzcz1cImJveC1pdGVtXCJcbiAgICAgICAgdGl0bGU9XCJMZWZ0IFRvcCBwcm9tcHRzIGluZm9cIlxuICAgICAgICBwbGFjZW1lbnQ9XCJsZWZ0LXN0YXJ0XCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+XG4gICAgICAgICAgPGVsLWJ1dHRvbj5sZWZ0LXN0YXJ0PC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXBvcGNvbmZpcm0+XG4gICAgICA8ZWwtcG9wY29uZmlybVxuICAgICAgICBjbGFzcz1cImJveC1pdGVtXCJcbiAgICAgICAgdGl0bGU9XCJSaWdodCBUb3AgcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwicmlnaHQtc3RhcnRcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT5cbiAgICAgICAgICA8ZWwtYnV0dG9uPnJpZ2h0LXN0YXJ0PC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXBvcGNvbmZpcm0+XG4gICAgPC9kaXY+XG4gICAgPGRpdiBjbGFzcz1cInJvd1wiPlxuICAgICAgPGVsLXBvcGNvbmZpcm1cbiAgICAgICAgY2xhc3M9XCJib3gtaXRlbVwiXG4gICAgICAgIHRpdGxlPVwiTGVmdCBDZW50ZXIgcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwibGVmdFwiXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjcmVmZXJlbmNlPlxuICAgICAgICAgIDxlbC1idXR0b24gY2xhc3M9XCJtdC0zIG1iLTNcIj5sZWZ0PC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXBvcGNvbmZpcm0+XG4gICAgICA8ZWwtcG9wY29uZmlybVxuICAgICAgICBjbGFzcz1cImJveC1pdGVtXCJcbiAgICAgICAgdGl0bGU9XCJSaWdodCBDZW50ZXIgcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwicmlnaHRcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT5cbiAgICAgICAgICA8ZWwtYnV0dG9uPnJpZ2h0PC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXBvcGNvbmZpcm0+XG4gICAgPC9kaXY+XG4gICAgPGRpdiBjbGFzcz1cInJvd1wiPlxuICAgICAgPGVsLXBvcGNvbmZpcm1cbiAgICAgICAgY2xhc3M9XCJib3gtaXRlbVwiXG4gICAgICAgIHRpdGxlPVwiTGVmdCBCb3R0b20gcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwibGVmdC1lbmRcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT5cbiAgICAgICAgICA8ZWwtYnV0dG9uPmxlZnQtZW5kPC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXBvcGNvbmZpcm0+XG4gICAgICA8ZWwtcG9wY29uZmlybVxuICAgICAgICBjbGFzcz1cImJveC1pdGVtXCJcbiAgICAgICAgdGl0bGU9XCJSaWdodCBCb3R0b20gcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwicmlnaHQtZW5kXCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+XG4gICAgICAgICAgPGVsLWJ1dHRvbj5yaWdodC1lbmQ8L2VsLWJ1dHRvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtcG9wY29uZmlybT5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwicm93IGNlbnRlclwiPlxuICAgICAgPGVsLXBvcGNvbmZpcm1cbiAgICAgICAgY2xhc3M9XCJib3gtaXRlbVwiXG4gICAgICAgIHRpdGxlPVwiQm90dG9tIExlZnQgcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwiYm90dG9tLXN0YXJ0XCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+IDxlbC1idXR0b24+Ym90dG9tLXN0YXJ0PC9lbC1idXR0b24+PC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtcG9wY29uZmlybT5cbiAgICAgIDxlbC1wb3Bjb25maXJtXG4gICAgICAgIGNsYXNzPVwiYm94LWl0ZW1cIlxuICAgICAgICB0aXRsZT1cIkJvdHRvbSBDZW50ZXIgcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwiYm90dG9tXCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+IDxlbC1idXR0b24+Ym90dG9tPC9lbC1idXR0b24+PC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtcG9wY29uZmlybT5cbiAgICAgIDxlbC1wb3Bjb25maXJtXG4gICAgICAgIGNsYXNzPVwiYm94LWl0ZW1cIlxuICAgICAgICB0aXRsZT1cIkJvdHRvbSBSaWdodCBwcm9tcHRzIGluZm9cIlxuICAgICAgICBwbGFjZW1lbnQ9XCJib3R0b20tZW5kXCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+XG4gICAgICAgICAgPGVsLWJ1dHRvbj5ib3R0b20tZW5kPC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXBvcGNvbmZpcm0+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlPlxuLnBvcGNvbmZpcm0tYmFzZS1ib3gge1xuICB3aWR0aDogNjAwcHg7XG59XG5cbi5wb3Bjb25maXJtLWJhc2UtYm94IC5yb3cge1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBqdXN0aWZ5LWNvbnRlbnQ6IHNwYWNlLWJldHdlZW47XG59XG5cbi5wb3Bjb25maXJtLWJhc2UtYm94IC5jZW50ZXIge1xuICBqdXN0aWZ5LWNvbnRlbnQ6IGNlbnRlcjtcbn1cblxuLnBvcGNvbmZpcm0tYmFzZS1ib3ggLmJveC1pdGVtIHtcbiAgd2lkdGg6IDExMHB4O1xuICBtYXJnaW4tdG9wOiAxMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/popconfirm/placement.vue)_

vue

```
<template>
  <div class="popconfirm-base-box">
    <div class="row center">
      <el-popconfirm
        class="box-item"
        title="Top Left prompts info"
        placement="top-start"
      >
        <template #reference>
          <el-button>top-start</el-button>
        </template>
      </el-popconfirm>
      <el-popconfirm
        class="box-item"
        title="Top Center prompts info"
        placement="top"
      >
        <template #reference>
          <el-button>top</el-button>
        </template>
      </el-popconfirm>
      <el-popconfirm
        class="box-item"
        title="Top Right prompts info"
        placement="top-end"
      >
        <template #reference>
          <el-button>top-end</el-button>
        </template>
      </el-popconfirm>
    </div>
    <div class="row">
      <el-popconfirm
        class="box-item"
        title="Left Top prompts info"
        placement="left-start"
      >
        <template #reference>
          <el-button>left-start</el-button>
        </template>
      </el-popconfirm>
      <el-popconfirm
        class="box-item"
        title="Right Top prompts info"
        placement="right-start"
      >
        <template #reference>
          <el-button>right-start</el-button>
        </template>
      </el-popconfirm>
    </div>
    <div class="row">
      <el-popconfirm
        class="box-item"
        title="Left Center prompts info"
        placement="left"
      >
        <template #reference>
          <el-button class="mt-3 mb-3">left</el-button>
        </template>
      </el-popconfirm>
      <el-popconfirm
        class="box-item"
        title="Right Center prompts info"
        placement="right"
      >
        <template #reference>
          <el-button>right</el-button>
        </template>
      </el-popconfirm>
    </div>
    <div class="row">
      <el-popconfirm
        class="box-item"
        title="Left Bottom prompts info"
        placement="left-end"
      >
        <template #reference>
          <el-button>left-end</el-button>
        </template>
      </el-popconfirm>
      <el-popconfirm
        class="box-item"
        title="Right Bottom prompts info"
        placement="right-end"
      >
        <template #reference>
          <el-button>right-end</el-button>
        </template>
      </el-popconfirm>
    </div>
    <div class="row center">
      <el-popconfirm
        class="box-item"
        title="Bottom Left prompts info"
        placement="bottom-start"
      >
        <template #reference> <el-button>bottom-start</el-button></template>
      </el-popconfirm>
      <el-popconfirm
        class="box-item"
        title="Bottom Center prompts info"
        placement="bottom"
      >
        <template #reference> <el-button>bottom</el-button></template>
      </el-popconfirm>
      <el-popconfirm
        class="box-item"
        title="Bottom Right prompts info"
        placement="bottom-end"
      >
        <template #reference>
          <el-button>bottom-end</el-button>
        </template>
      </el-popconfirm>
    </div>
  </div>
</template>

<style>
.popconfirm-base-box {
  width: 600px;
}

.popconfirm-base-box .row {
  display: flex;
  align-items: center;
  justify-content: space-between;
}

.popconfirm-base-box .center {
  justify-content: center;
}

.popconfirm-base-box .box-item {
  width: 110px;
  margin-top: 10px;
}
</style>
```

隐藏源代码

## 基础用法 [​](#基础用法)

Popconfirm 的属性与 Popover 很类似， 因此对于重复属性，请参考 Popover 的文档，在此文档中不做详尽解释。

在 Popconfirm 中，只有 `title` 属性可用，`content` 属性会被忽略。

Delete

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcG9wY29uZmlybSB0aXRsZT1cIkFyZSB5b3Ugc3VyZSB0byBkZWxldGUgdGhpcz9cIj5cbiAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT5cbiAgICAgIDxlbC1idXR0b24+RGVsZXRlPC9lbC1idXR0b24+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1wb3Bjb25maXJtPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/popconfirm/basic-usage.vue)_

vue

```
<template>
  <el-popconfirm title="Are you sure to delete this?">
    <template #reference>
      <el-button>Delete</el-button>
    </template>
  </el-popconfirm>
</template>
```

隐藏源代码

## 自定义弹出框的内容 [​](#自定义弹出框的内容)

可以在 Popconfirm 中自定义内容。

Delete

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcG9wY29uZmlybVxuICAgIHdpZHRoPVwiMjIwXCJcbiAgICA6aWNvbj1cIkluZm9GaWxsZWRcIlxuICAgIGljb24tY29sb3I9XCIjNjI2QUVGXCJcbiAgICB0aXRsZT1cIkFyZSB5b3Ugc3VyZSB0byBkZWxldGUgdGhpcz9cIlxuICAgIEBjYW5jZWw9XCJvbkNhbmNlbFwiXG4gID5cbiAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT5cbiAgICAgIDxlbC1idXR0b24+RGVsZXRlPC9lbC1idXR0b24+XG4gICAgPC90ZW1wbGF0ZT5cbiAgICA8dGVtcGxhdGUgI2FjdGlvbnM9XCJ7IGNvbmZpcm0sIGNhbmNlbCB9XCI+XG4gICAgICA8ZWwtYnV0dG9uIHNpemU9XCJzbWFsbFwiIEBjbGljaz1cImNhbmNlbFwiPk5vITwvZWwtYnV0dG9uPlxuICAgICAgPGVsLWJ1dHRvblxuICAgICAgICB0eXBlPVwiZGFuZ2VyXCJcbiAgICAgICAgc2l6ZT1cInNtYWxsXCJcbiAgICAgICAgOmRpc2FibGVkPVwiIWNsaWNrZWRcIlxuICAgICAgICBAY2xpY2s9XCJjb25maXJtXCJcbiAgICAgID5cbiAgICAgICAgWWVzP1xuICAgICAgPC9lbC1idXR0b24+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1wb3Bjb25maXJtPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IEluZm9GaWxsZWQgfSBmcm9tICdAZWxlbWVudC1wbHVzL2ljb25zLXZ1ZSdcblxuY29uc3QgY2xpY2tlZCA9IHJlZihmYWxzZSlcbmZ1bmN0aW9uIG9uQ2FuY2VsKCkge1xuICBjbGlja2VkLnZhbHVlID0gdHJ1ZVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/popconfirm/customize.vue)_

vue

```
<template>
  <el-popconfirm
    width="220"
    :icon="InfoFilled"
    icon-color="#626AEF"
    title="Are you sure to delete this?"
    @cancel="onCancel"
  >
    <template #reference>
      <el-button>Delete</el-button>
    </template>
    <template #actions="{ confirm, cancel }">
      <el-button size="small" @click="cancel">No!</el-button>
      <el-button
        type="danger"
        size="small"
        :disabled="!clicked"
        @click="confirm"
      >
        Yes?
      </el-button>
    </template>
  </el-popconfirm>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { InfoFilled } from '@element-plus/icons-vue'

const clicked = ref(false)
function onCancel() {
  clicked.value = true
}
</script>
```

隐藏源代码

## 多种让 Popconfirm 出现的方法 [​](#多种让-popconfirm-出现的方法)

点击按钮触发事件

Delete

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcG9wY29uZmlybVxuICAgIGNvbmZpcm0tYnV0dG9uLXRleHQ9XCJZZXNcIlxuICAgIGNhbmNlbC1idXR0b24tdGV4dD1cIk5vXCJcbiAgICA6aWNvbj1cIkluZm9GaWxsZWRcIlxuICAgIGljb24tY29sb3I9XCIjNjI2QUVGXCJcbiAgICB0aXRsZT1cIkFyZSB5b3Ugc3VyZSB0byBkZWxldGUgdGhpcz9cIlxuICAgIEBjb25maXJtPVwiY29uZmlybUV2ZW50XCJcbiAgICBAY2FuY2VsPVwiY2FuY2VsRXZlbnRcIlxuICA+XG4gICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+XG4gICAgICA8ZWwtYnV0dG9uPkRlbGV0ZTwvZWwtYnV0dG9uPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtcG9wY29uZmlybT5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+XG5pbXBvcnQgeyBJbmZvRmlsbGVkIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG5cbmNvbnN0IGNvbmZpcm1FdmVudCA9ICgpID0+IHtcbiAgY29uc29sZS5sb2coJ2NvbmZpcm0hJylcbn1cbmNvbnN0IGNhbmNlbEV2ZW50ID0gKCkgPT4ge1xuICBjb25zb2xlLmxvZygnY2FuY2VsIScpXG59XG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/popconfirm/trigger-event.vue)_

vue

```
<template>
  <el-popconfirm
    confirm-button-text="Yes"
    cancel-button-text="No"
    :icon="InfoFilled"
    icon-color="#626AEF"
    title="Are you sure to delete this?"
    @confirm="confirmEvent"
    @cancel="cancelEvent"
  >
    <template #reference>
      <el-button>Delete</el-button>
    </template>
  </el-popconfirm>
</template>

<script setup lang="ts">
import { InfoFilled } from '@element-plus/icons-vue'

const confirmEvent = () => {
  console.log('confirm!')
}
const cancelEvent = () => {
  console.log('cancel!')
}
</script>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| title | 标题 | `string` | — |
| effect 2.11.2 | Tooltip 主题，内置了 `dark` / `light` 两种 | `enum` / `string` | light |
| confirm-button-text | 确认按钮文字 | `string` | — |
| cancel-button-text | 取消按钮文字 | `string` | — |
| confirm-button-type | 确认按钮类型 | `enum` | primary |
| cancel-button-type | 取消按钮类型 | `enum` | text |
| icon | 自定义图标 | `string` / `Component` | QuestionFilled |
| icon-color | Icon 颜色 | `string` | #f90 |
| hide-icon | 是否隐藏 Icon | `boolean` | false |
| hide-after | 关闭时的延迟 | `number` | 200 |
| teleported | 是否将 popover 的下拉列表插入至 body 元素 | `boolean` | true |
| persistent | 当 popover 组件长时间不触发且 `persistent` 属性设置为 `false` 时, popover 将会被删除 | `boolean` | false |
| width | 弹层宽度，最小宽度 150px | `string` / `number` | 150 |
| [tooltip](https://element-plus.org/zh-CN/component/tooltip#attributes) | 继承自 Tooltip 的所有属性，但不包括：`popper-class`、`popper-style`、`fallback-placements` | — | — |

### Events [​](#events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| confirm | 点击确认按钮时触发 | `Function` |
| cancel | 点击取消按钮时触发 | `Function` |

### Slots [​](#slots)

| 插槽名 | 说明 | 类型 |
| --- | --- | --- |
| reference | 触发 Popconfirm 显示的 HTML 元素 | — |
| actions 2.8.1 | 页脚的内容 | `object` |

### 暴露 [​](#暴露)

| 方法名 | 详情 | Type |
| --- | --- | --- |
| popperRef 2.10.7 | el-popper 组件实例 | `object` |
| hide 2.10.7 | hide popconfirm | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/popconfirm) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/popconfirm.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/popconfirm.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/31238760?v=4&size=64)](https://github.com/cloydlau)[![](https://avatars.githubusercontent.com/u/24540820?v=4&size=64)](https://github.com/catanswer)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/145281501?v=4&size=64)](https://github.com/typed-sigterm)[![](https://avatars.githubusercontent.com/u/26999792?v=4&size=64)](https://github.com/plainheart)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/13634675?v=4&size=64)](https://github.com/virgosoy)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/10731096?v=4&size=64)](https://github.com/zazzaz)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)

[Notification 通知](https://element-plus.org/zh-CN/component/notification)

[Popover 弹出框](https://element-plus.org/zh-CN/component/popover)




---
## [feedback/popover] Popover 弹出框
> 官方文档: https://element-plus.org/zh-CN/component/popover.html

---

# Popover 弹出框 [​](#popover-弹出框)

更新日志待解决

25

## 展示位置 [​](#展示位置)

Popover 弹出框提供 9 种展示位置。

使用 `content` 属性来设置悬停时显示的信息。 由 `placement` 属性决定 Popover 弹出框的位置。 该属性值格式为：`[方向]-[对齐位置]`，可供选择的四个方向分别是`top`、`left`、`right`、`bottom`，可供选择的三种对齐方式分别是`start`、`end`、`null`，默认的对齐方式为null。 以 `placement="left-end"` 为例，Popover 弹出框会显示在悬停元素的左侧，且提示信息的底部与悬停元素的底部对齐。

top-starttoptop-end

left-startright-start

leftright

left-endright-end

bottom-startbottombottom-end

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwicG9wb3Zlci1iYXNlLWJveFwiPlxuICAgIDxkaXYgY2xhc3M9XCJyb3cgY2VudGVyXCI+XG4gICAgICA8ZWwtcG9wb3ZlclxuICAgICAgICB0aXRsZT1cIlRpdGxlXCJcbiAgICAgICAgY29udGVudD1cIlRvcCBMZWZ0IHByb21wdHMgaW5mb1wiXG4gICAgICAgIHBsYWNlbWVudD1cInRvcC1zdGFydFwiXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjcmVmZXJlbmNlPlxuICAgICAgICAgIDxlbC1idXR0b24+dG9wLXN0YXJ0PC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXBvcG92ZXI+XG4gICAgICA8ZWwtcG9wb3ZlclxuICAgICAgICB0aXRsZT1cIlRpdGxlXCJcbiAgICAgICAgY29udGVudD1cIlRvcCBDZW50ZXIgcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwidG9wXCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+XG4gICAgICAgICAgPGVsLWJ1dHRvbj50b3A8L2VsLWJ1dHRvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtcG9wb3Zlcj5cbiAgICAgIDxlbC1wb3BvdmVyXG4gICAgICAgIHRpdGxlPVwiVGl0bGVcIlxuICAgICAgICBjb250ZW50PVwiVG9wIFJpZ2h0IHByb21wdHMgaW5mb1wiXG4gICAgICAgIHBsYWNlbWVudD1cInRvcC1lbmRcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT5cbiAgICAgICAgICA8ZWwtYnV0dG9uPnRvcC1lbmQ8L2VsLWJ1dHRvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtcG9wb3Zlcj5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwicm93XCI+XG4gICAgICA8ZWwtcG9wb3ZlclxuICAgICAgICB0aXRsZT1cIlRpdGxlXCJcbiAgICAgICAgY29udGVudD1cIkxlZnQgVG9wIHByb21wdHMgaW5mb1wiXG4gICAgICAgIHBsYWNlbWVudD1cImxlZnQtc3RhcnRcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT5cbiAgICAgICAgICA8ZWwtYnV0dG9uPmxlZnQtc3RhcnQ8L2VsLWJ1dHRvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtcG9wb3Zlcj5cbiAgICAgIDxlbC1wb3BvdmVyXG4gICAgICAgIHRpdGxlPVwiVGl0bGVcIlxuICAgICAgICBjb250ZW50PVwiUmlnaHQgVG9wIHByb21wdHMgaW5mb1wiXG4gICAgICAgIHBsYWNlbWVudD1cInJpZ2h0LXN0YXJ0XCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+XG4gICAgICAgICAgPGVsLWJ1dHRvbj5yaWdodC1zdGFydDwvZWwtYnV0dG9uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1wb3BvdmVyPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJyb3dcIj5cbiAgICAgIDxlbC1wb3BvdmVyXG4gICAgICAgIHRpdGxlPVwiVGl0bGVcIlxuICAgICAgICBjb250ZW50PVwiTGVmdCBDZW50ZXIgcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwibGVmdFwiXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjcmVmZXJlbmNlPlxuICAgICAgICAgIDxlbC1idXR0b24gY2xhc3M9XCJtdC0zIG1iLTNcIj5sZWZ0PC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXBvcG92ZXI+XG4gICAgICA8ZWwtcG9wb3ZlclxuICAgICAgICB0aXRsZT1cIlRpdGxlXCJcbiAgICAgICAgY29udGVudD1cIlJpZ2h0IENlbnRlciBwcm9tcHRzIGluZm9cIlxuICAgICAgICBwbGFjZW1lbnQ9XCJyaWdodFwiXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjcmVmZXJlbmNlPlxuICAgICAgICAgIDxlbC1idXR0b24+cmlnaHQ8L2VsLWJ1dHRvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtcG9wb3Zlcj5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwicm93XCI+XG4gICAgICA8ZWwtcG9wb3ZlclxuICAgICAgICB0aXRsZT1cIlRpdGxlXCJcbiAgICAgICAgY29udGVudD1cIkxlZnQgQm90dG9tIHByb21wdHMgaW5mb1wiXG4gICAgICAgIHBsYWNlbWVudD1cImxlZnQtZW5kXCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+XG4gICAgICAgICAgPGVsLWJ1dHRvbj5sZWZ0LWVuZDwvZWwtYnV0dG9uPlxuICAgICAgICA8L3RlbXBsYXRlPlxuICAgICAgPC9lbC1wb3BvdmVyPlxuICAgICAgPGVsLXBvcG92ZXJcbiAgICAgICAgdGl0bGU9XCJUaXRsZVwiXG4gICAgICAgIGNvbnRlbnQ9XCJSaWdodCBCb3R0b20gcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwicmlnaHQtZW5kXCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+XG4gICAgICAgICAgPGVsLWJ1dHRvbj5yaWdodC1lbmQ8L2VsLWJ1dHRvbj5cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDwvZWwtcG9wb3Zlcj5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwicm93IGNlbnRlclwiPlxuICAgICAgPGVsLXBvcG92ZXJcbiAgICAgICAgdGl0bGU9XCJUaXRsZVwiXG4gICAgICAgIGNvbnRlbnQ9XCJCb3R0b20gTGVmdCBwcm9tcHRzIGluZm9cIlxuICAgICAgICBwbGFjZW1lbnQ9XCJib3R0b20tc3RhcnRcIlxuICAgICAgPlxuICAgICAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT4gPGVsLWJ1dHRvbj5ib3R0b20tc3RhcnQ8L2VsLWJ1dHRvbj48L3RlbXBsYXRlPlxuICAgICAgPC9lbC1wb3BvdmVyPlxuICAgICAgPGVsLXBvcG92ZXJcbiAgICAgICAgdGl0bGU9XCJUaXRsZVwiXG4gICAgICAgIGNvbnRlbnQ9XCJCb3R0b20gQ2VudGVyIHByb21wdHMgaW5mb1wiXG4gICAgICAgIHBsYWNlbWVudD1cImJvdHRvbVwiXG4gICAgICA+XG4gICAgICAgIDx0ZW1wbGF0ZSAjcmVmZXJlbmNlPiA8ZWwtYnV0dG9uPmJvdHRvbTwvZWwtYnV0dG9uPjwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXBvcG92ZXI+XG4gICAgICA8ZWwtcG9wb3ZlclxuICAgICAgICB0aXRsZT1cIlRpdGxlXCJcbiAgICAgICAgY29udGVudD1cIkJvdHRvbSBSaWdodCBwcm9tcHRzIGluZm9cIlxuICAgICAgICBwbGFjZW1lbnQ9XCJib3R0b20tZW5kXCJcbiAgICAgID5cbiAgICAgICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+XG4gICAgICAgICAgPGVsLWJ1dHRvbj5ib3R0b20tZW5kPC9lbC1idXR0b24+XG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICA8L2VsLXBvcG92ZXI+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlPlxuLnBvcG92ZXItYmFzZS1ib3gge1xuICB3aWR0aDogNjAwcHg7XG59XG5cbi5wb3BvdmVyLWJhc2UtYm94IC5yb3cge1xuICBkaXNwbGF5OiBmbGV4O1xuICBhbGlnbi1pdGVtczogY2VudGVyO1xuICBqdXN0aWZ5LWNvbnRlbnQ6IHNwYWNlLWJldHdlZW47XG59XG5cbi5wb3BvdmVyLWJhc2UtYm94IC5jZW50ZXIge1xuICBqdXN0aWZ5LWNvbnRlbnQ6IGNlbnRlcjtcbn1cbjwvc3R5bGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/popover/placement.vue)_

vue

```
<template>
  <div class="popover-base-box">
    <div class="row center">
      <el-popover
        title="Title"
        content="Top Left prompts info"
        placement="top-start"
      >
        <template #reference>
          <el-button>top-start</el-button>
        </template>
      </el-popover>
      <el-popover
        title="Title"
        content="Top Center prompts info"
        placement="top"
      >
        <template #reference>
          <el-button>top</el-button>
        </template>
      </el-popover>
      <el-popover
        title="Title"
        content="Top Right prompts info"
        placement="top-end"
      >
        <template #reference>
          <el-button>top-end</el-button>
        </template>
      </el-popover>
    </div>
    <div class="row">
      <el-popover
        title="Title"
        content="Left Top prompts info"
        placement="left-start"
      >
        <template #reference>
          <el-button>left-start</el-button>
        </template>
      </el-popover>
      <el-popover
        title="Title"
        content="Right Top prompts info"
        placement="right-start"
      >
        <template #reference>
          <el-button>right-start</el-button>
        </template>
      </el-popover>
    </div>
    <div class="row">
      <el-popover
        title="Title"
        content="Left Center prompts info"
        placement="left"
      >
        <template #reference>
          <el-button class="mt-3 mb-3">left</el-button>
        </template>
      </el-popover>
      <el-popover
        title="Title"
        content="Right Center prompts info"
        placement="right"
      >
        <template #reference>
          <el-button>right</el-button>
        </template>
      </el-popover>
    </div>
    <div class="row">
      <el-popover
        title="Title"
        content="Left Bottom prompts info"
        placement="left-end"
      >
        <template #reference>
          <el-button>left-end</el-button>
        </template>
      </el-popover>
      <el-popover
        title="Title"
        content="Right Bottom prompts info"
        placement="right-end"
      >
        <template #reference>
          <el-button>right-end</el-button>
        </template>
      </el-popover>
    </div>
    <div class="row center">
      <el-popover
        title="Title"
        content="Bottom Left prompts info"
        placement="bottom-start"
      >
        <template #reference> <el-button>bottom-start</el-button></template>
      </el-popover>
      <el-popover
        title="Title"
        content="Bottom Center prompts info"
        placement="bottom"
      >
        <template #reference> <el-button>bottom</el-button></template>
      </el-popover>
      <el-popover
        title="Title"
        content="Bottom Right prompts info"
        placement="bottom-end"
      >
        <template #reference>
          <el-button>bottom-end</el-button>
        </template>
      </el-popover>
    </div>
  </div>
</template>

<style>
.popover-base-box {
  width: 600px;
}

.popover-base-box .row {
  display: flex;
  align-items: center;
  justify-content: space-between;
}

.popover-base-box .center {
  justify-content: center;
}
</style>
```

隐藏源代码

## 基础用法 [​](#基础用法)

Popover 是在 `ElTooltip` 基础上开发出来的。 因此对于重复属性，请参考 Tooltip 的文档，在此文档中不做详尽解释。

`trigger` 属性被用来决定 popover 的触发方式，支持的触发方式： `hover`、`click`、`focus` 或 `contextmenu`。 如果你想手动控制它，可以设置 `:visible` 属性。

Hover to activateClick to activateFocus to activatecontextmenu to activate Manual to activate

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcG9wb3ZlclxuICAgIHBsYWNlbWVudD1cInRvcC1zdGFydFwiXG4gICAgdGl0bGU9XCJUaXRsZVwiXG4gICAgOndpZHRoPVwiMjAwXCJcbiAgICB0cmlnZ2VyPVwiaG92ZXJcIlxuICAgIGNvbnRlbnQ9XCJ0aGlzIGlzIGNvbnRlbnQsIHRoaXMgaXMgY29udGVudCwgdGhpcyBpcyBjb250ZW50XCJcbiAgPlxuICAgIDx0ZW1wbGF0ZSAjcmVmZXJlbmNlPlxuICAgICAgPGVsLWJ1dHRvbiBjbGFzcz1cIm0tMlwiPkhvdmVyIHRvIGFjdGl2YXRlPC9lbC1idXR0b24+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1wb3BvdmVyPlxuXG4gIDxlbC1wb3BvdmVyXG4gICAgcGxhY2VtZW50PVwiYm90dG9tXCJcbiAgICB0aXRsZT1cIlRpdGxlXCJcbiAgICA6d2lkdGg9XCIyMDBcIlxuICAgIHRyaWdnZXI9XCJjbGlja1wiXG4gICAgY29udGVudD1cInRoaXMgaXMgY29udGVudCwgdGhpcyBpcyBjb250ZW50LCB0aGlzIGlzIGNvbnRlbnRcIlxuICA+XG4gICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+XG4gICAgICA8ZWwtYnV0dG9uIGNsYXNzPVwibS0yXCI+Q2xpY2sgdG8gYWN0aXZhdGU8L2VsLWJ1dHRvbj5cbiAgICA8L3RlbXBsYXRlPlxuICA8L2VsLXBvcG92ZXI+XG5cbiAgPGVsLXBvcG92ZXJcbiAgICByZWY9XCJwb3BvdmVyXCJcbiAgICBwbGFjZW1lbnQ9XCJyaWdodFwiXG4gICAgdGl0bGU9XCJUaXRsZVwiXG4gICAgOndpZHRoPVwiMjAwXCJcbiAgICB0cmlnZ2VyPVwiZm9jdXNcIlxuICAgIGNvbnRlbnQ9XCJ0aGlzIGlzIGNvbnRlbnQsIHRoaXMgaXMgY29udGVudCwgdGhpcyBpcyBjb250ZW50XCJcbiAgPlxuICAgIDx0ZW1wbGF0ZSAjcmVmZXJlbmNlPlxuICAgICAgPGVsLWJ1dHRvbiBjbGFzcz1cIm0tMlwiPkZvY3VzIHRvIGFjdGl2YXRlPC9lbC1idXR0b24+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1wb3BvdmVyPlxuXG4gIDxlbC1wb3BvdmVyXG4gICAgcmVmPVwicG9wb3ZlclwiXG4gICAgdGl0bGU9XCJUaXRsZVwiXG4gICAgOndpZHRoPVwiMjAwXCJcbiAgICB0cmlnZ2VyPVwiY29udGV4dG1lbnVcIlxuICAgIGNvbnRlbnQ9XCJ0aGlzIGlzIGNvbnRlbnQsIHRoaXMgaXMgY29udGVudCwgdGhpcyBpcyBjb250ZW50XCJcbiAgPlxuICAgIDx0ZW1wbGF0ZSAjcmVmZXJlbmNlPlxuICAgICAgPGVsLWJ1dHRvbiBjbGFzcz1cIm0tMlwiPmNvbnRleHRtZW51IHRvIGFjdGl2YXRlPC9lbC1idXR0b24+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1wb3BvdmVyPlxuXG4gIDxlbC1wb3BvdmVyXG4gICAgOnZpc2libGU9XCJ2aXNpYmxlXCJcbiAgICBwbGFjZW1lbnQ9XCJib3R0b21cIlxuICAgIHRpdGxlPVwiVGl0bGVcIlxuICAgIDp3aWR0aD1cIjIwMFwiXG4gICAgY29udGVudD1cInRoaXMgaXMgY29udGVudCwgdGhpcyBpcyBjb250ZW50LCB0aGlzIGlzIGNvbnRlbnRcIlxuICA+XG4gICAgPHRlbXBsYXRlICNyZWZlcmVuY2U+XG4gICAgICA8ZWwtYnV0dG9uIGNsYXNzPVwibS0yXCIgQGNsaWNrPVwidmlzaWJsZSA9ICF2aXNpYmxlXCI+XG4gICAgICAgIE1hbnVhbCB0byBhY3RpdmF0ZVxuICAgICAgPC9lbC1idXR0b24+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC1wb3BvdmVyPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmlzaWJsZSA9IHJlZihmYWxzZSlcbjwvc2NyaXB0PlxuXG48c3R5bGUgc2NvcGVkPlxuLmVsLWJ1dHRvbiArIC5lbC1idXR0b24ge1xuICBtYXJnaW4tbGVmdDogOHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/popover/basic-usage.vue)_

vue

```
<template>
  <el-popover
    placement="top-start"
    title="Title"
    :width="200"
    trigger="hover"
    content="this is content, this is content, this is content"
  >
    <template #reference>
      <el-button class="m-2">Hover to activate</el-button>
    </template>
  </el-popover>

  <el-popover
    placement="bottom"
    title="Title"
    :width="200"
    trigger="click"
    content="this is content, this is content, this is content"
  >
    <template #reference>
      <el-button class="m-2">Click to activate</el-button>
    </template>
  </el-popover>

  <el-popover
    ref="popover"
    placement="right"
    title="Title"
    :width="200"
    trigger="focus"
    content="this is content, this is content, this is content"
  >
    <template #reference>
      <el-button class="m-2">Focus to activate</el-button>
    </template>
  </el-popover>

  <el-popover
    ref="popover"
    title="Title"
    :width="200"
    trigger="contextmenu"
    content="this is content, this is content, this is content"
  >
    <template #reference>
      <el-button class="m-2">contextmenu to activate</el-button>
    </template>
  </el-popover>

  <el-popover
    :visible="visible"
    placement="bottom"
    title="Title"
    :width="200"
    content="this is content, this is content, this is content"
  >
    <template #reference>
      <el-button class="m-2" @click="visible = !visible">
        Manual to activate
      </el-button>
    </template>
  </el-popover>
</template>

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

const visible = ref(false)
</script>

<style scoped>
.el-button + .el-button {
  margin-left: 8px;
}
</style>
```

隐藏源代码

## 虚拟触发 [​](#虚拟触发)

像 Tooltip一样，Popover 可以由虚拟元素触发，这个功能就很适合使用在触发元素和展示内容元素是分开的场景。通常我们使用 `#reference` 来放置我们的触发元素， 用 `triggering-element` API，您可以任意设置您的触发元素 但注意到触发元素应该是接受 `mouse` 和 `keyboard` 事件的元素。

WARNING

`v-popover` 将被废弃，请使用 `virtual-ref` 作为替代。

Click me

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHJlZj1cImJ1dHRvblJlZlwiIHYtY2xpY2stb3V0c2lkZT1cIm9uQ2xpY2tPdXRzaWRlXCI+XG4gICAgQ2xpY2sgbWVcbiAgPC9lbC1idXR0b24+XG5cbiAgPGVsLXBvcG92ZXJcbiAgICByZWY9XCJwb3BvdmVyUmVmXCJcbiAgICA6dmlydHVhbC1yZWY9XCJidXR0b25SZWZcIlxuICAgIHRyaWdnZXI9XCJjbGlja1wiXG4gICAgdGl0bGU9XCJXaXRoIHRpdGxlXCJcbiAgICB2aXJ0dWFsLXRyaWdnZXJpbmdcbiAgPlxuICAgIDxzcGFuPiBTb21lIGNvbnRlbnQgPC9zcGFuPlxuICA8L2VsLXBvcG92ZXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgQ2xpY2tPdXRzaWRlIGFzIHZDbGlja091dHNpZGUgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmltcG9ydCB0eXBlIHsgUG9wb3Zlckluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBidXR0b25SZWYgPSByZWYoKVxuY29uc3QgcG9wb3ZlclJlZiA9IHJlZjxQb3BvdmVySW5zdGFuY2U+KClcbmNvbnN0IG9uQ2xpY2tPdXRzaWRlID0gKCkgPT4ge1xuICBwb3BvdmVyUmVmLnZhbHVlPy5oaWRlKClcbn1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/popover/virtual-triggering.vue)_

vue

```
<template>
  <el-button ref="buttonRef" v-click-outside="onClickOutside">
    Click me
  </el-button>

  <el-popover
    ref="popoverRef"
    :virtual-ref="buttonRef"
    trigger="click"
    title="With title"
    virtual-triggering
  >
    <span> Some content </span>
  </el-popover>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ClickOutside as vClickOutside } from 'element-plus'

import type { PopoverInstance } from 'element-plus'

const buttonRef = ref()
const popoverRef = ref<PopoverInstance>()
const onClickOutside = () => {
  popoverRef.value?.hide()
}
</script>
```

隐藏源代码

## 内容可扩展 [​](#内容可扩展)

可以在 Popover 中嵌套其它组件， 以下为嵌套表格的例子。

利用插槽取代 `content` 属性

Click to activate![](https://avatars.githubusercontent.com/u/72015883?v=4)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IHN0eWxlPVwiZGlzcGxheTogZmxleDsgYWxpZ24taXRlbXM6IGNlbnRlclwiPlxuICAgIDxlbC1wb3BvdmVyIHBsYWNlbWVudD1cInJpZ2h0XCIgOndpZHRoPVwiNDAwXCIgdHJpZ2dlcj1cImNsaWNrXCI+XG4gICAgICA8dGVtcGxhdGUgI3JlZmVyZW5jZT5cbiAgICAgICAgPGVsLWJ1dHRvbiBzdHlsZT1cIm1hcmdpbi1yaWdodDogMTZweFwiPkNsaWNrIHRvIGFjdGl2YXRlPC9lbC1idXR0b24+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgICAgPGVsLXRhYmxlIDpkYXRhPVwiZ3JpZERhdGFcIj5cbiAgICAgICAgPGVsLXRhYmxlLWNvbHVtbiB3aWR0aD1cIjE1MFwiIHByb3BlcnR5PVwiZGF0ZVwiIGxhYmVsPVwiZGF0ZVwiIC8+XG4gICAgICAgIDxlbC10YWJsZS1jb2x1bW4gd2lkdGg9XCIxMDBcIiBwcm9wZXJ0eT1cIm5hbWVcIiBsYWJlbD1cIm5hbWVcIiAvPlxuICAgICAgICA8ZWwtdGFibGUtY29sdW1uIHdpZHRoPVwiMzAwXCIgcHJvcGVydHk9XCJhZGRyZXNzXCIgbGFiZWw9XCJhZGRyZXNzXCIgLz5cbiAgICAgIDwvZWwtdGFibGU+XG4gICAgPC9lbC1wb3BvdmVyPlxuXG4gICAgPGVsLXBvcG92ZXJcbiAgICAgIDp3aWR0aD1cIjMwMFwiXG4gICAgICBwb3BwZXItc3R5bGU9XCJib3gtc2hhZG93OiByZ2IoMTQgMTggMjIgLyAzNSUpIDBweCAxMHB4IDM4cHggLTEwcHgsIHJnYigxNCAxOCAyMiAvIDIwJSkgMHB4IDEwcHggMjBweCAtMTVweDsgcGFkZGluZzogMjBweDtcIlxuICAgID5cbiAgICAgIDx0ZW1wbGF0ZSAjcmVmZXJlbmNlPlxuICAgICAgICA8ZWwtYXZhdGFyIHNyYz1cImh0dHBzOi8vYXZhdGFycy5naXRodWJ1c2VyY29udGVudC5jb20vdS83MjAxNTg4Mz92PTRcIiAvPlxuICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgIDx0ZW1wbGF0ZSAjZGVmYXVsdD5cbiAgICAgICAgPGRpdlxuICAgICAgICAgIGNsYXNzPVwiZGVtby1yaWNoLWNvbmVudFwiXG4gICAgICAgICAgc3R5bGU9XCJkaXNwbGF5OiBmbGV4OyBnYXA6IDE2cHg7IGZsZXgtZGlyZWN0aW9uOiBjb2x1bW5cIlxuICAgICAgICA+XG4gICAgICAgICAgPGVsLWF2YXRhclxuICAgICAgICAgICAgOnNpemU9XCI2MFwiXG4gICAgICAgICAgICBzcmM9XCJodHRwczovL2F2YXRhcnMuZ2l0aHVidXNlcmNvbnRlbnQuY29tL3UvNzIwMTU4ODM/dj00XCJcbiAgICAgICAgICAgIHN0eWxlPVwibWFyZ2luLWJvdHRvbTogOHB4XCJcbiAgICAgICAgICAvPlxuICAgICAgICAgIDxkaXY+XG4gICAgICAgICAgICA8cFxuICAgICAgICAgICAgICBjbGFzcz1cImRlbW8tcmljaC1jb250ZW50X19uYW1lXCJcbiAgICAgICAgICAgICAgc3R5bGU9XCJtYXJnaW46IDA7IGZvbnQtd2VpZ2h0OiA1MDBcIlxuICAgICAgICAgICAgPlxuICAgICAgICAgICAgICBFbGVtZW50IFBsdXNcbiAgICAgICAgICAgIDwvcD5cbiAgICAgICAgICAgIDxwXG4gICAgICAgICAgICAgIGNsYXNzPVwiZGVtby1yaWNoLWNvbnRlbnRfX21lbnRpb25cIlxuICAgICAgICAgICAgICBzdHlsZT1cIm1hcmdpbjogMDsgZm9udC1zaXplOiAxNHB4OyBjb2xvcjogdmFyKC0tZWwtY29sb3ItaW5mbylcIlxuICAgICAgICAgICAgPlxuICAgICAgICAgICAgICBAZWxlbWVudC1wbHVzXG4gICAgICAgICAgICA8L3A+XG4gICAgICAgICAgPC9kaXY+XG5cbiAgICAgICAgICA8cCBjbGFzcz1cImRlbW8tcmljaC1jb250ZW50X19kZXNjXCIgc3R5bGU9XCJtYXJnaW46IDBcIj5cbiAgICAgICAgICAgIEVsZW1lbnQgUGx1cywgYSBWdWUgMyBiYXNlZCBjb21wb25lbnQgbGlicmFyeSBmb3IgZGV2ZWxvcGVycyxcbiAgICAgICAgICAgIGRlc2lnbmVycyBhbmQgcHJvZHVjdCBtYW5hZ2Vyc1xuICAgICAgICAgIDwvcD5cbiAgICAgICAgPC9kaXY+XG4gICAgICA8L3RlbXBsYXRlPlxuICAgIDwvZWwtcG9wb3Zlcj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IGxhbmc9XCJ0c1wiIHNldHVwPlxuY29uc3QgZ3JpZERhdGEgPSBbXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMicsXG4gICAgbmFtZTogJ0phY2snLFxuICAgIGFkZHJlc3M6ICdOZXcgWW9yayBDaXR5JyxcbiAgfSxcbiAge1xuICAgIGRhdGU6ICcyMDE2LTA1LTA0JyxcbiAgICBuYW1lOiAnSmFjaycsXG4gICAgYWRkcmVzczogJ05ldyBZb3JrIENpdHknLFxuICB9LFxuICB7XG4gICAgZGF0ZTogJzIwMTYtMDUtMDEnLFxuICAgIG5hbWU6ICdKYWNrJyxcbiAgICBhZGRyZXNzOiAnTmV3IFlvcmsgQ2l0eScsXG4gIH0sXG4gIHtcbiAgICBkYXRlOiAnMjAxNi0wNS0wMycsXG4gICAgbmFtZTogJ0phY2snLFxuICAgIGFkZHJlc3M6ICdOZXcgWW9yayBDaXR5JyxcbiAgfSxcbl1cbjwvc2NyaXB0PlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/popover/nested-information.vue)_

vue

```
<template>
  <div style="display: flex; align-items: center">
    <el-popover placement="right" :width="400" trigger="click">
      <template #reference>
        <el-button style="margin-right: 16px">Click to activate</el-button>
      </template>
      <el-table :data="gridData">
        <el-table-column width="150" property="date" label="date" />
        <el-table-column width="100" property="name" label="name" />
        <el-table-column width="300" property="address" label="address" />
      </el-table>
    </el-popover>

    <el-popover
      :width="300"
      popper-style="box-shadow: rgb(14 18 22 / 35%) 0px 10px 38px -10px, rgb(14 18 22 / 20%) 0px 10px 20px -15px; padding: 20px;"
    >
      <template #reference>
        <el-avatar src="https://avatars.githubusercontent.com/u/72015883?v=4" />
      </template>
      <template #default>
        <div
          class="demo-rich-conent"
          style="display: flex; gap: 16px; flex-direction: column"
        >
          <el-avatar
            :size="60"
            src="https://avatars.githubusercontent.com/u/72015883?v=4"
            style="margin-bottom: 8px"
          />
          <div>
            <p
              class="demo-rich-content__name"
              style="margin: 0; font-weight: 500"
            >
              Element Plus
            </p>
            <p
              class="demo-rich-content__mention"
              style="margin: 0; font-size: 14px; color: var(--el-color-info)"
            >
              @element-plus
            </p>
          </div>

          <p class="demo-rich-content__desc" style="margin: 0">
            Element Plus, a Vue 3 based component library for developers,
            designers and product managers
          </p>
        </div>
      </template>
    </el-popover>
  </div>
</template>

<script lang="ts" setup>
const gridData = [
  {
    date: '2016-05-02',
    name: 'Jack',
    address: 'New York City',
  },
  {
    date: '2016-05-04',
    name: 'Jack',
    address: 'New York City',
  },
  {
    date: '2016-05-01',
    name: 'Jack',
    address: 'New York City',
  },
  {
    date: '2016-05-03',
    name: 'Jack',
    address: 'New York City',
  },
]
</script>
```

隐藏源代码

## 嵌套操作 [​](#嵌套操作)

当然，你还可以嵌套操作， 它比使用dialog更加轻量。

Delete

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtcG9wb3ZlciA6dmlzaWJsZT1cInZpc2libGVcIiBwbGFjZW1lbnQ9XCJ0b3BcIiA6d2lkdGg9XCIxODBcIj5cbiAgICA8cD5BcmUgeW91IHN1cmUgdG8gZGVsZXRlIHRoaXM/PC9wPlxuICAgIDxkaXYgc3R5bGU9XCJ0ZXh0LWFsaWduOiByaWdodDsgbWFyZ2luOiAwXCI+XG4gICAgICA8ZWwtYnV0dG9uIHNpemU9XCJzbWFsbFwiIHRleHQgQGNsaWNrPVwidmlzaWJsZSA9IGZhbHNlXCI+Y2FuY2VsPC9lbC1idXR0b24+XG4gICAgICA8ZWwtYnV0dG9uIHNpemU9XCJzbWFsbFwiIHR5cGU9XCJwcmltYXJ5XCIgQGNsaWNrPVwidmlzaWJsZSA9IGZhbHNlXCI+XG4gICAgICAgIGNvbmZpcm1cbiAgICAgIDwvZWwtYnV0dG9uPlxuICAgIDwvZGl2PlxuICAgIDx0ZW1wbGF0ZSAjcmVmZXJlbmNlPlxuICAgICAgPGVsLWJ1dHRvbiBAY2xpY2s9XCJ2aXNpYmxlID0gdHJ1ZVwiPkRlbGV0ZTwvZWwtYnV0dG9uPlxuICAgIDwvdGVtcGxhdGU+XG4gIDwvZWwtcG9wb3Zlcj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZpc2libGUgPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/popover/nested-operation.vue)_

vue

```
<template>
  <el-popover :visible="visible" placement="top" :width="180">
    <p>Are you sure to delete this?</p>
    <div style="text-align: right; margin: 0">
      <el-button size="small" text @click="visible = false">cancel</el-button>
      <el-button size="small" type="primary" @click="visible = false">
        confirm
      </el-button>
    </div>
    <template #reference>
      <el-button @click="visible = true">Delete</el-button>
    </template>
  </el-popover>
</template>

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

const visible = ref(false)
</script>
```

隐藏源代码

## 指令 [​](#指令)

您可以使用指令性方式弹出窗口，但这种方法**不再推荐** ，因为这使得应用程序变得复杂， 您可以参考虚拟触发来实现一样的效果。

Click me

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtYnV0dG9uIHYtcG9wb3Zlcj1cInBvcG92ZXJSZWZcIiB2LWNsaWNrLW91dHNpZGU9XCJvbkNsaWNrT3V0c2lkZVwiPlxuICAgIENsaWNrIG1lXG4gIDwvZWwtYnV0dG9uPlxuXG4gIDxlbC1wb3BvdmVyXG4gICAgcmVmPVwicG9wb3ZlclJlZlwiXG4gICAgdHJpZ2dlcj1cImNsaWNrXCJcbiAgICB0aXRsZT1cIldpdGggdGl0bGVcIlxuICAgIHZpcnR1YWwtdHJpZ2dlcmluZ1xuICAgIHBlcnNpc3RlbnRcbiAgPlxuICAgIDxzcGFuPiBTb21lIGNvbnRlbnQgPC9zcGFuPlxuICA8L2VsLXBvcG92ZXI+XG48L3RlbXBsYXRlPlxuXG48c2NyaXB0IHNldHVwIGxhbmc9XCJ0c1wiPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuaW1wb3J0IHsgQ2xpY2tPdXRzaWRlIGFzIHZDbGlja091dHNpZGUgfSBmcm9tICdlbGVtZW50LXBsdXMnXG5cbmltcG9ydCB0eXBlIHsgUG9wb3Zlckluc3RhbmNlIH0gZnJvbSAnZWxlbWVudC1wbHVzJ1xuXG5jb25zdCBwb3BvdmVyUmVmID0gcmVmPFBvcG92ZXJJbnN0YW5jZT4oKVxuY29uc3Qgb25DbGlja091dHNpZGUgPSAoKSA9PiB7XG4gIHBvcG92ZXJSZWYudmFsdWU/LmhpZGUoKVxufVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/popover/directive-usage.vue)_

vue

```
<template>
  <el-button v-popover="popoverRef" v-click-outside="onClickOutside">
    Click me
  </el-button>

  <el-popover
    ref="popoverRef"
    trigger="click"
    title="With title"
    virtual-triggering
    persistent
  >
    <span> Some content </span>
  </el-popover>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ClickOutside as vClickOutside } from 'element-plus'

import type { PopoverInstance } from 'element-plus'

const popoverRef = ref<PopoverInstance>()
const onClickOutside = () => {
  popoverRef.value?.hide()
}
</script>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | Default |
| --- | --- | --- | --- |
| trigger | popover 触发方式，在受控模式下无效。 | `enum` / `array` | hover |
| trigger-keys 2.9.8 | 当通过鼠标点击使触发元素获得焦点时，可以定义一组键盘按键代码，通过键盘控制气泡框的显示，在受控模式下无效。 | `Array` | \['Enter','Space'\] |
| title | 标题 | `string` | — |
| effect | Tooltip 主题，Element Plus 内置了 `dark` / `light` 两种主题 | `enum` / `string` | light |
| content | 显示的内容，也可以通过写入默认 `slot` 修改显示内容 | `string` | '' |
| width | 宽度 | `string` / `number` | 150 |
| placement | 出现位置 | `enum` | bottom |
| disabled | Popover 是否可用 | `boolean` | false |
| visible / v-model:visible | Popover 是否显示 | `boolean` / `null` | null |
| offset | 浮层偏移量, `Popover` 是在 `Tooltip`,基础上开发的， `Popover`的 offset 是 `undefined`, 但`Tooltip` 的 offset 是12 | `number` | undefined |
| transition | 定义渐变动画，默认是 el-fade-in-linear | `string` | — |
| show-arrow | 是否显示 Tooltip 箭头， 欲了解更多信息，请参考 [ElPopper](https://github.com/element-plus/element-plus/tree/dev/packages/components/popper) | `boolean` | true |
| popper-options | [popper.js](https://popper.js.org/docs/v2/) 的参数 | `object` | `{modifiers: [{name: 'computeStyles',options: {gpuAcceleration: false}}]}` |
| popper-class | 为 popper 添加类名 | `string` | — |
| popper-style | 为 popper 自定义样式 | `string` / `object` | — |
| show-after | 延迟显示时间（以毫秒为单位），在受控模式下无效。 | `number` | 0 |
| hide-after | 消失延迟时间（以毫秒为单位），在受控模式下无效。 | `number` | 200 |
| auto-close | 隐藏提示框的超时时间（以毫秒为单位），在受控模式下无效。 | `number` | 0 |
| tabindex | Popover 组件的 [tabindex](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Global_attributes/tabindex) | `number` / `string` | 0 |
| teleported | 是否将 popover 的下拉列表插入至 body 元素 | `boolean` | true |
| append-to 2.8.4 | 指示 Tooltip 的内容将附加在哪一个网页元素上 | `CSSSelector` / `HTMLElement` | body |
| persistent | 当 popover 组件长时间不触发且 `persistent` 属性设置为 `false` 时, popover 将会被删除 | `boolean` | true |
| virtual-triggering | 是否启用虚拟触发器 | `boolean` | — |
| virtual-ref | 代表 tooltip 所要附加的参照元素 | `HTMLElement` | — |
| [tooltip](https://element-plus.org/zh-CN/component/tooltip#attributes) | 继承自 Tooltip 的所有属性 | ::: | — |

### Slots [​](#slots)

| 插槽名 | 说明 | Type |
| --- | --- | --- |
| default | 弹出框的内容，2.13.4 及之后版本可以接收 hide 参数。 | `object` |
| reference | 触发弹出框的 HTML 元素，只接受单个根元素。 | \- |

### Events [​](#events)

| 事件名 | 说明 | 类型 |
| --- | --- | --- |
| show | 显示时触发 | `Function` |
| before-enter | 显示动画播放前触发 | `Function` |
| after-enter | 显示动画播放完毕后触发 | `Function` |
| hide | 隐藏时触发 | `Function` |
| before-leave | 隐藏动画播放前触发 | `Function` |
| after-leave | 隐藏动画播放完毕后触发 | `Function` |

### Exposes [​](#exposes)

| 名称 | 详情 | Type |
| --- | --- | --- |
| hide | 隐藏 popover | `Function` |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/popover) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/popover.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/popover.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/200161722?v=4&size=64)](https://github.com/changchi666)[![](https://avatars.githubusercontent.com/u/62818957?v=4&size=64)](https://github.com/ZacharyBear)[![](https://avatars.githubusercontent.com/u/179441993?v=4&size=64)](https://github.com/lw56777)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/30046649?v=4&size=64)](https://github.com/MrWeilian)[![](https://avatars.githubusercontent.com/u/169252980?v=4&size=64)](https://github.com/xiaochenchen-igg-com)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/21095710?v=4&size=64)](https://github.com/zouhangwithsweet)[![](https://avatars.githubusercontent.com/u/10802869?v=4&size=64)](https://github.com/Chris-Kin)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/140705167?v=4&size=64)](https://github.com/zhongli-kira)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/60031458?v=4&size=64)](https://github.com/sefaun)[![](https://avatars.githubusercontent.com/u/24362871?v=4&size=64)](https://github.com/Benleie)[![](https://avatars.githubusercontent.com/u/234136872?v=4&size=64)](https://github.com/z-kunf)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/56570859?v=4&size=64)](https://github.com/XSUV)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/84843371?v=4&size=64)](https://github.com/ignaceshi)[![](https://avatars.githubusercontent.com/u/36811055?v=4&size=64)](https://github.com/iDestin)[![](https://avatars.githubusercontent.com/u/643976?v=4&size=64)](https://github.com/ghiscoding)

[Popconfirm 气泡确认框](https://element-plus.org/zh-CN/component/popconfirm)

[Tooltip 文字提示](https://element-plus.org/zh-CN/component/tooltip)




---
## [feedback/tooltip] Tooltip 文字提示
> 官方文档: https://element-plus.org/zh-CN/component/tooltip.html

---

# Tooltip 文字提示 [​](#tooltip-文字提示)

更新日志待解决

26

常用于展示鼠标 hover 时的提示信息。

## 基础用法 [​](#基础用法)

在这里我们提供 9 种不同方向的展示方式，可以通过以下完整示例来理解，选择你要的效果。

使用 `content` 属性来决定 `hover` 时的提示信息。 由 `placement` 属性决定展示效果： `placement`属性值为：`[方向]-[对齐位置]`；四个方向：`top`、`left`、`right`、`bottom`；三种对齐位置：`start`, `end`，默认为空。 如 `placement="left-end"`，则提示信息出现在目标元素的左侧，且提示信息的底部与目标元素的底部对齐。

top-starttoptop-end

left-startright-start

leftright

left-endright-end

bottom-startbottombottom-end

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwidG9vbHRpcC1iYXNlLWJveFwiPlxuICAgIDxkaXYgY2xhc3M9XCJyb3cgY2VudGVyXCI+XG4gICAgICA8ZWwtdG9vbHRpcFxuICAgICAgICBjbGFzcz1cImJveC1pdGVtXCJcbiAgICAgICAgZWZmZWN0PVwiZGFya1wiXG4gICAgICAgIGNvbnRlbnQ9XCJUb3AgTGVmdCBwcm9tcHRzIGluZm9cIlxuICAgICAgICBwbGFjZW1lbnQ9XCJ0b3Atc3RhcnRcIlxuICAgICAgPlxuICAgICAgICA8ZWwtYnV0dG9uPnRvcC1zdGFydDwvZWwtYnV0dG9uPlxuICAgICAgPC9lbC10b29sdGlwPlxuICAgICAgPGVsLXRvb2x0aXBcbiAgICAgICAgY2xhc3M9XCJib3gtaXRlbVwiXG4gICAgICAgIGVmZmVjdD1cImRhcmtcIlxuICAgICAgICBjb250ZW50PVwiVG9wIENlbnRlciBwcm9tcHRzIGluZm9cIlxuICAgICAgICBwbGFjZW1lbnQ9XCJ0b3BcIlxuICAgICAgPlxuICAgICAgICA8ZWwtYnV0dG9uPnRvcDwvZWwtYnV0dG9uPlxuICAgICAgPC9lbC10b29sdGlwPlxuICAgICAgPGVsLXRvb2x0aXBcbiAgICAgICAgY2xhc3M9XCJib3gtaXRlbVwiXG4gICAgICAgIGVmZmVjdD1cImRhcmtcIlxuICAgICAgICBjb250ZW50PVwiVG9wIFJpZ2h0IHByb21wdHMgaW5mb1wiXG4gICAgICAgIHBsYWNlbWVudD1cInRvcC1lbmRcIlxuICAgICAgPlxuICAgICAgICA8ZWwtYnV0dG9uPnRvcC1lbmQ8L2VsLWJ1dHRvbj5cbiAgICAgIDwvZWwtdG9vbHRpcD5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwicm93XCI+XG4gICAgICA8ZWwtdG9vbHRpcCBjbGFzcz1cImJveC1pdGVtXCIgZWZmZWN0PVwiZGFya1wiIHBsYWNlbWVudD1cImxlZnQtc3RhcnRcIj5cbiAgICAgICAgPHRlbXBsYXRlICNjb250ZW50PlxuICAgICAgICAgIExlZnQgVG9wXG4gICAgICAgICAgPGJyIC8+XG4gICAgICAgICAgcHJvbXB0cyBpbmZvXG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDxlbC1idXR0b24+bGVmdC1zdGFydDwvZWwtYnV0dG9uPlxuICAgICAgPC9lbC10b29sdGlwPlxuICAgICAgPGVsLXRvb2x0aXAgY2xhc3M9XCJib3gtaXRlbVwiIGVmZmVjdD1cImRhcmtcIiBwbGFjZW1lbnQ9XCJyaWdodC1zdGFydFwiPlxuICAgICAgICA8dGVtcGxhdGUgI2NvbnRlbnQ+XG4gICAgICAgICAgUmlnaHQgVG9wXG4gICAgICAgICAgPGJyIC8+XG4gICAgICAgICAgcHJvbXB0cyBpbmZvXG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDxlbC1idXR0b24+cmlnaHQtc3RhcnQ8L2VsLWJ1dHRvbj5cbiAgICAgIDwvZWwtdG9vbHRpcD5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwicm93XCI+XG4gICAgICA8ZWwtdG9vbHRpcCBjbGFzcz1cImJveC1pdGVtXCIgZWZmZWN0PVwiZGFya1wiIHBsYWNlbWVudD1cImxlZnRcIj5cbiAgICAgICAgPHRlbXBsYXRlICNjb250ZW50PlxuICAgICAgICAgIExlZnQgQ2VudGVyXG4gICAgICAgICAgPGJyIC8+XG4gICAgICAgICAgcHJvbXB0cyBpbmZvXG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDxlbC1idXR0b24gY2xhc3M9XCJtdC0zIG1iLTNcIj5sZWZ0PC9lbC1idXR0b24+XG4gICAgICA8L2VsLXRvb2x0aXA+XG4gICAgICA8ZWwtdG9vbHRpcCBjbGFzcz1cImJveC1pdGVtXCIgZWZmZWN0PVwiZGFya1wiIHBsYWNlbWVudD1cInJpZ2h0XCI+XG4gICAgICAgIDx0ZW1wbGF0ZSAjY29udGVudD5cbiAgICAgICAgICBSaWdodCBDZW50ZXJcbiAgICAgICAgICA8YnIgLz5cbiAgICAgICAgICBwcm9tcHRzIGluZm9cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPGVsLWJ1dHRvbj5yaWdodDwvZWwtYnV0dG9uPlxuICAgICAgPC9lbC10b29sdGlwPlxuICAgIDwvZGl2PlxuICAgIDxkaXYgY2xhc3M9XCJyb3dcIj5cbiAgICAgIDxlbC10b29sdGlwIGNsYXNzPVwiYm94LWl0ZW1cIiBlZmZlY3Q9XCJkYXJrXCIgcGxhY2VtZW50PVwibGVmdC1lbmRcIj5cbiAgICAgICAgPHRlbXBsYXRlICNjb250ZW50PlxuICAgICAgICAgIExlZnQgQm90dG9tXG4gICAgICAgICAgPGJyIC8+XG4gICAgICAgICAgcHJvbXB0cyBpbmZvXG4gICAgICAgIDwvdGVtcGxhdGU+XG4gICAgICAgIDxlbC1idXR0b24+bGVmdC1lbmQ8L2VsLWJ1dHRvbj5cbiAgICAgIDwvZWwtdG9vbHRpcD5cbiAgICAgIDxlbC10b29sdGlwIGNsYXNzPVwiYm94LWl0ZW1cIiBlZmZlY3Q9XCJkYXJrXCIgcGxhY2VtZW50PVwicmlnaHQtZW5kXCI+XG4gICAgICAgIDx0ZW1wbGF0ZSAjY29udGVudD5cbiAgICAgICAgICBSaWdodCBCb3R0b21cbiAgICAgICAgICA8YnIgLz5cbiAgICAgICAgICBwcm9tcHRzIGluZm9cbiAgICAgICAgPC90ZW1wbGF0ZT5cbiAgICAgICAgPGVsLWJ1dHRvbj5yaWdodC1lbmQ8L2VsLWJ1dHRvbj5cbiAgICAgIDwvZWwtdG9vbHRpcD5cbiAgICA8L2Rpdj5cbiAgICA8ZGl2IGNsYXNzPVwicm93IGNlbnRlclwiPlxuICAgICAgPGVsLXRvb2x0aXBcbiAgICAgICAgY2xhc3M9XCJib3gtaXRlbVwiXG4gICAgICAgIGVmZmVjdD1cImRhcmtcIlxuICAgICAgICBjb250ZW50PVwiQm90dG9tIExlZnQgcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwiYm90dG9tLXN0YXJ0XCJcbiAgICAgID5cbiAgICAgICAgPGVsLWJ1dHRvbj5ib3R0b20tc3RhcnQ8L2VsLWJ1dHRvbj5cbiAgICAgIDwvZWwtdG9vbHRpcD5cbiAgICAgIDxlbC10b29sdGlwXG4gICAgICAgIGNsYXNzPVwiYm94LWl0ZW1cIlxuICAgICAgICBlZmZlY3Q9XCJkYXJrXCJcbiAgICAgICAgY29udGVudD1cIkJvdHRvbSBDZW50ZXIgcHJvbXB0cyBpbmZvXCJcbiAgICAgICAgcGxhY2VtZW50PVwiYm90dG9tXCJcbiAgICAgID5cbiAgICAgICAgPGVsLWJ1dHRvbj5ib3R0b208L2VsLWJ1dHRvbj5cbiAgICAgIDwvZWwtdG9vbHRpcD5cbiAgICAgIDxlbC10b29sdGlwXG4gICAgICAgIGNsYXNzPVwiYm94LWl0ZW1cIlxuICAgICAgICBlZmZlY3Q9XCJkYXJrXCJcbiAgICAgICAgY29udGVudD1cIkJvdHRvbSBSaWdodCBwcm9tcHRzIGluZm9cIlxuICAgICAgICBwbGFjZW1lbnQ9XCJib3R0b20tZW5kXCJcbiAgICAgID5cbiAgICAgICAgPGVsLWJ1dHRvbj5ib3R0b20tZW5kPC9lbC1idXR0b24+XG4gICAgICA8L2VsLXRvb2x0aXA+XG4gICAgPC9kaXY+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlPlxuLnRvb2x0aXAtYmFzZS1ib3gge1xuICB3aWR0aDogNjAwcHg7XG59XG4udG9vbHRpcC1iYXNlLWJveCAucm93IHtcbiAgZGlzcGxheTogZmxleDtcbiAgYWxpZ24taXRlbXM6IGNlbnRlcjtcbiAganVzdGlmeS1jb250ZW50OiBzcGFjZS1iZXR3ZWVuO1xufVxuLnRvb2x0aXAtYmFzZS1ib3ggLmNlbnRlciB7XG4gIGp1c3RpZnktY29udGVudDogY2VudGVyO1xufVxuLnRvb2x0aXAtYmFzZS1ib3ggLmJveC1pdGVtIHtcbiAgd2lkdGg6IDExMHB4O1xuICBtYXJnaW4tdG9wOiAxMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tooltip/basic.vue)_

vue

```
<template>
  <div class="tooltip-base-box">
    <div class="row center">
      <el-tooltip
        class="box-item"
        effect="dark"
        content="Top Left prompts info"
        placement="top-start"
      >
        <el-button>top-start</el-button>
      </el-tooltip>
      <el-tooltip
        class="box-item"
        effect="dark"
        content="Top Center prompts info"
        placement="top"
      >
        <el-button>top</el-button>
      </el-tooltip>
      <el-tooltip
        class="box-item"
        effect="dark"
        content="Top Right prompts info"
        placement="top-end"
      >
        <el-button>top-end</el-button>
      </el-tooltip>
    </div>
    <div class="row">
      <el-tooltip class="box-item" effect="dark" placement="left-start">
        <template #content>
          Left Top
          <br />
          prompts info
        </template>
        <el-button>left-start</el-button>
      </el-tooltip>
      <el-tooltip class="box-item" effect="dark" placement="right-start">
        <template #content>
          Right Top
          <br />
          prompts info
        </template>
        <el-button>right-start</el-button>
      </el-tooltip>
    </div>
    <div class="row">
      <el-tooltip class="box-item" effect="dark" placement="left">
        <template #content>
          Left Center
          <br />
          prompts info
        </template>
        <el-button class="mt-3 mb-3">left</el-button>
      </el-tooltip>
      <el-tooltip class="box-item" effect="dark" placement="right">
        <template #content>
          Right Center
          <br />
          prompts info
        </template>
        <el-button>right</el-button>
      </el-tooltip>
    </div>
    <div class="row">
      <el-tooltip class="box-item" effect="dark" placement="left-end">
        <template #content>
          Left Bottom
          <br />
          prompts info
        </template>
        <el-button>left-end</el-button>
      </el-tooltip>
      <el-tooltip class="box-item" effect="dark" placement="right-end">
        <template #content>
          Right Bottom
          <br />
          prompts info
        </template>
        <el-button>right-end</el-button>
      </el-tooltip>
    </div>
    <div class="row center">
      <el-tooltip
        class="box-item"
        effect="dark"
        content="Bottom Left prompts info"
        placement="bottom-start"
      >
        <el-button>bottom-start</el-button>
      </el-tooltip>
      <el-tooltip
        class="box-item"
        effect="dark"
        content="Bottom Center prompts info"
        placement="bottom"
      >
        <el-button>bottom</el-button>
      </el-tooltip>
      <el-tooltip
        class="box-item"
        effect="dark"
        content="Bottom Right prompts info"
        placement="bottom-end"
      >
        <el-button>bottom-end</el-button>
      </el-tooltip>
    </div>
  </div>
</template>

<style>
.tooltip-base-box {
  width: 600px;
}
.tooltip-base-box .row {
  display: flex;
  align-items: center;
  justify-content: space-between;
}
.tooltip-base-box .center {
  justify-content: center;
}
.tooltip-base-box .box-item {
  width: 110px;
  margin-top: 10px;
}
</style>
```

隐藏源代码

## 主题 [​](#主题)

Tooltip 组件内置了两个主题：`dark`和`light`。

TIP

要使用自定义主题，您必须知道您的工具提示在哪里渲染， 如果您的工具提示被呈现为根元素，您将需要全局设置css规则。

建议您使用自定义主题并同时显示箭头时不使用线性渐变背景颜色。 因为弹出箭头和内容是两个不同的元素， 弹出箭头的样式需要单独设置， 当它到渐变背景颜色时，会看起来很奇怪。

通过设置 `effect` 来修改主题，默认值为 `dark`.

DarkLightCustomized theme

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdG9vbHRpcCBjb250ZW50PVwiVG9wIGNlbnRlclwiIHBsYWNlbWVudD1cInRvcFwiPlxuICAgIDxlbC1idXR0b24+RGFyazwvZWwtYnV0dG9uPlxuICA8L2VsLXRvb2x0aXA+XG4gIDxlbC10b29sdGlwIGNvbnRlbnQ9XCJCb3R0b20gY2VudGVyXCIgcGxhY2VtZW50PVwiYm90dG9tXCIgZWZmZWN0PVwibGlnaHRcIj5cbiAgICA8ZWwtYnV0dG9uPkxpZ2h0PC9lbC1idXR0b24+XG4gIDwvZWwtdG9vbHRpcD5cblxuICA8ZWwtdG9vbHRpcCBjb250ZW50PVwiQm90dG9tIGNlbnRlclwiIGVmZmVjdD1cImN1c3RvbWl6ZWRcIj5cbiAgICA8ZWwtYnV0dG9uPkN1c3RvbWl6ZWQgdGhlbWU8L2VsLWJ1dHRvbj5cbiAgPC9lbC10b29sdGlwPlxuPC90ZW1wbGF0ZT5cblxuPHN0eWxlPlxuLmVsLXBvcHBlci5pcy1jdXN0b21pemVkIHtcbiAgLyogU2V0IHBhZGRpbmcgdG8gZW5zdXJlIHRoZSBoZWlnaHQgaXMgMzJweCAqL1xuICBwYWRkaW5nOiA2cHggMTJweDtcbiAgYmFja2dyb3VuZDogbGluZWFyLWdyYWRpZW50KDkwZGVnLCByZ2IoMTU5LCAyMjksIDE1MSksIHJnYigyMDQsIDIyOSwgMTI5KSk7XG59XG5cbi5lbC1wb3BwZXIuaXMtY3VzdG9taXplZCAuZWwtcG9wcGVyX19hcnJvdzo6YmVmb3JlIHtcbiAgYmFja2dyb3VuZDogbGluZWFyLWdyYWRpZW50KDQ1ZGVnLCAjYjJlNjhkLCAjYmNlNjg5KTtcbiAgcmlnaHQ6IDA7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tooltip/theme.vue)_

vue

```
<template>
  <el-tooltip content="Top center" placement="top">
    <el-button>Dark</el-button>
  </el-tooltip>
  <el-tooltip content="Bottom center" placement="bottom" effect="light">
    <el-button>Light</el-button>
  </el-tooltip>

  <el-tooltip content="Bottom center" effect="customized">
    <el-button>Customized theme</el-button>
  </el-tooltip>
</template>

<style>
.el-popper.is-customized {
  /* Set padding to ensure the height is 32px */
  padding: 6px 12px;
  background: linear-gradient(90deg, rgb(159, 229, 151), rgb(204, 229, 129));
}

.el-popper.is-customized .el-popper__arrow::before {
  background: linear-gradient(45deg, #b2e68d, #bce689);
  right: 0;
}
</style>
```

隐藏源代码

## 更多内容的文字提示 [​](#更多内容的文字提示)

展示多行文本或者是设置文本内容的格式

用具名 slot `content`，替代`tooltip`中的`content`属性。

Top center

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdG9vbHRpcCBwbGFjZW1lbnQ9XCJ0b3BcIj5cbiAgICA8dGVtcGxhdGUgI2NvbnRlbnQ+IG11bHRpcGxlIGxpbmVzPGJyIC8+c2Vjb25kIGxpbmUgPC90ZW1wbGF0ZT5cbiAgICA8ZWwtYnV0dG9uPlRvcCBjZW50ZXI8L2VsLWJ1dHRvbj5cbiAgPC9lbC10b29sdGlwPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tooltip/rich-content.vue)_

vue

```
<template>
  <el-tooltip placement="top">
    <template #content> multiple lines<br />second line </template>
    <el-button>Top center</el-button>
  </el-tooltip>
</template>
```

隐藏源代码

## 高级扩展 [​](#高级扩展)

除了这些基本设置外，还有一些属性可以让使用者更好的定制自己的效果：

`transition` 属性可以定制显隐的动画效果，默认为`fade-in-linear`。

如果需要关闭 `tooltip` 功能，`disabled` 属性可以满足这个需求， 你只需要将其设置为 `true`。

事实上，Tooltip 是一个基于 [ElPopper](https://github.com/element-plus/element-plus/tree/dev/packages/components/popper) 的扩展，您可以使用 ElPopper 中允许的任何属性。

click to close tooltip function

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdG9vbHRpcFxuICAgIDpkaXNhYmxlZD1cImRpc2FibGVkXCJcbiAgICBjb250ZW50PVwiY2xpY2sgdG8gY2xvc2UgdG9vbHRpcCBmdW5jdGlvblwiXG4gICAgcGxhY2VtZW50PVwiYm90dG9tXCJcbiAgICBlZmZlY3Q9XCJsaWdodFwiXG4gID5cbiAgICA8ZWwtYnV0dG9uIEBjbGljaz1cImRpc2FibGVkID0gIWRpc2FibGVkXCI+XG4gICAgICBjbGljayB0byB7eyBkaXNhYmxlZCA/ICdhY3RpdmUnIDogJ2Nsb3NlJyB9fSB0b29sdGlwIGZ1bmN0aW9uXG4gICAgPC9lbC1idXR0b24+XG4gIDwvZWwtdG9vbHRpcD5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IGRpc2FibGVkID0gcmVmKGZhbHNlKVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tooltip/advanced-usage.vue)_

vue

```
<template>
  <el-tooltip
    :disabled="disabled"
    content="click to close tooltip function"
    placement="bottom"
    effect="light"
  >
    <el-button @click="disabled = !disabled">
      click to {{ disabled ? 'active' : 'close' }} tooltip function
    </el-button>
  </el-tooltip>
</template>

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

const disabled = ref(false)
</script>
```

隐藏源代码

TIP

Tooltip 内不支持 `router-link` 组件，请使用 `vm.$router.push` 代替。

tooltip 内不支持 disabled form 元素，参考 [MDN](https://developer.mozilla.org/en-US/docs/Web/Events/mouseenter)， 请在 disabled form 元素外层添加一层包裹元素。

## 显示 HTML 内容 [​](#显示-html-内容)

内容属性可以设置为 HTML 字符串。

WARNING

`content` 属性虽然支持传入 HTML 片段，但是在网站上动态渲染任意 HTML 是非常危险的，因为容易导致 [XSS 攻击](https://en.wikipedia.org/wiki/Cross-site_scripting)。 因此在 `raw-content` 打开的情况下，请确保 `content` 的内容是可信的，**永远不要**将用户提交的内容赋值给 `content` 属性。

hover me

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdG9vbHRpcFxuICAgIGNvbnRlbnQ9XCI8c3Bhbj5UaGUgY29udGVudCBjYW4gYmUgPHN0cm9uZz5IVE1MPC9zdHJvbmc+PC9zcGFuPlwiXG4gICAgcmF3LWNvbnRlbnRcbiAgPlxuICAgIDxlbC1idXR0b24+aG92ZXIgbWU8L2VsLWJ1dHRvbj5cbiAgPC9lbC10b29sdGlwPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tooltip/html-content.vue)_

vue

```
<template>
  <el-tooltip
    content="<span>The content can be <strong>HTML</strong></span>"
    raw-content
  >
    <el-button>hover me</el-button>
  </el-tooltip>
</template>
```

隐藏源代码

## 虚拟触发 [​](#虚拟触发)

有时候我们想把 tooltip 的触发元素放在别的地方，而不需要写在一起，这时候就可以使用虚拟触发。

TIP

需要注意的是，虚拟触发的 tooltip 是受控组件，因此你必须自己去控制 tooltip 是否显示，**你将无法**通过点击空白处来关闭 tooltip。

test

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdG9vbHRpcFxuICAgIDp2aXNpYmxlPVwidmlzaWJsZVwiXG4gICAgY29udGVudD1cIkJvdHRvbSBjZW50ZXJcIlxuICAgIHBsYWNlbWVudD1cImJvdHRvbVwiXG4gICAgZWZmZWN0PVwibGlnaHRcIlxuICAgIHRyaWdnZXI9XCJjbGlja1wiXG4gICAgdmlydHVhbC10cmlnZ2VyaW5nXG4gICAgOnZpcnR1YWwtcmVmPVwidHJpZ2dlclJlZlwiXG4gIC8+XG4gIDxlbC1idXR0b24gQGNsaWNrPVwidmlzaWJsZSA9ICF2aXNpYmxlXCI+dGVzdDwvZWwtYnV0dG9uPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IG9uTW91bnRlZCwgb25Vbm1vdW50ZWQsIHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgdmlzaWJsZSA9IHJlZihmYWxzZSlcbmNvbnN0IHBvc2l0aW9uID0gcmVmKHtcbiAgdG9wOiAwLFxuICBsZWZ0OiAwLFxuICBib3R0b206IDAsXG4gIHJpZ2h0OiAwLFxufSBhcyBET01SZWN0KVxuXG5jb25zdCB0cmlnZ2VyUmVmID0gcmVmKHtcbiAgZ2V0Qm91bmRpbmdDbGllbnRSZWN0OiAoKSA9PiBwb3NpdGlvbi52YWx1ZSxcbn0pXG5cbmNvbnN0IG1vdXNlbW92ZUhhbmRsZXIgPSAoeyBjbGllbnRYLCBjbGllbnRZIH06IE1vdXNlRXZlbnQpID0+IHtcbiAgcG9zaXRpb24udmFsdWUgPSBET01SZWN0LmZyb21SZWN0KHtcbiAgICB4OiBjbGllbnRYLFxuICAgIHk6IGNsaWVudFksXG4gIH0pXG59XG5cbm9uTW91bnRlZCgoKSA9PiB7XG4gIGRvY3VtZW50LmFkZEV2ZW50TGlzdGVuZXIoJ21vdXNlbW92ZScsIG1vdXNlbW92ZUhhbmRsZXIpXG59KVxuXG5vblVubW91bnRlZCgoKSA9PiB7XG4gIGRvY3VtZW50LnJlbW92ZUV2ZW50TGlzdGVuZXIoJ21vdXNlbW92ZScsIG1vdXNlbW92ZUhhbmRsZXIpXG59KVxuPC9zY3JpcHQ+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tooltip/virtual-trigger.vue)_

vue

```
<template>
  <el-tooltip
    :visible="visible"
    content="Bottom center"
    placement="bottom"
    effect="light"
    trigger="click"
    virtual-triggering
    :virtual-ref="triggerRef"
  />
  <el-button @click="visible = !visible">test</el-button>
</template>

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue'

const visible = ref(false)
const position = ref({
  top: 0,
  left: 0,
  bottom: 0,
  right: 0,
} as DOMRect)

const triggerRef = ref({
  getBoundingClientRect: () => position.value,
})

const mousemoveHandler = ({ clientX, clientY }: MouseEvent) => {
  position.value = DOMRect.fromRect({
    x: clientX,
    y: clientY,
  })
}

onMounted(() => {
  document.addEventListener('mousemove', mousemoveHandler)
})

onUnmounted(() => {
  document.removeEventListener('mousemove', mousemoveHandler)
})
</script>
```

隐藏源代码

## 单例模式 [​](#单例模式)

Tooltip 可以作为单例，也就是是说你可以同时有多个触发同一个 tooltip 的触发元素，这个功能是在 `虚拟触发` 的基础上开发的。

TIP

已知问题：使用单例模式时，弹出窗口会从意料之外的位置弹出。

Click to open tooltipClick to open tooltipClick to open tooltip

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxlbC1idXR0b25cbiAgICAgIHYtZm9yPVwiaSBpbiAzXCJcbiAgICAgIDprZXk9XCJpXCJcbiAgICAgIEBtb3VzZW92ZXI9XCIoZSkgPT4gKGJ1dHRvblJlZiA9IGUuY3VycmVudFRhcmdldClcIlxuICAgICAgQGNsaWNrPVwidmlzaWJsZSA9ICF2aXNpYmxlXCJcbiAgICAgID5DbGljayB0byBvcGVuIHRvb2x0aXA8L2VsLWJ1dHRvblxuICAgID5cbiAgPC9kaXY+XG5cbiAgPGVsLXRvb2x0aXBcbiAgICByZWY9XCJ0b29sdGlwUmVmXCJcbiAgICA6dmlzaWJsZT1cInZpc2libGVcIlxuICAgIDpwb3BwZXItb3B0aW9ucz1cIntcbiAgICAgIG1vZGlmaWVyczogW1xuICAgICAgICB7XG4gICAgICAgICAgbmFtZTogJ2NvbXB1dGVTdHlsZXMnLFxuICAgICAgICAgIG9wdGlvbnM6IHtcbiAgICAgICAgICAgIGFkYXB0aXZlOiBmYWxzZSxcbiAgICAgICAgICAgIGVuYWJsZWQ6IGZhbHNlLFxuICAgICAgICAgIH0sXG4gICAgICAgIH0sXG4gICAgICBdLFxuICAgIH1cIlxuICAgIDp2aXJ0dWFsLXJlZj1cImJ1dHRvblJlZlwiXG4gICAgdmlydHVhbC10cmlnZ2VyaW5nXG4gICAgcG9wcGVyLWNsYXNzPVwic2luZ2xldG9uLXRvb2x0aXBcIlxuICA+XG4gICAgPHRlbXBsYXRlICNjb250ZW50PlxuICAgICAgPHNwYW4+IFNvbWUgY29udGVudCA8L3NwYW4+XG4gICAgPC90ZW1wbGF0ZT5cbiAgPC9lbC10b29sdGlwPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlZiB9IGZyb20gJ3Z1ZSdcblxuY29uc3QgYnV0dG9uUmVmID0gcmVmKClcbmNvbnN0IHRvb2x0aXBSZWYgPSByZWYoKVxuXG5jb25zdCB2aXNpYmxlID0gcmVmKGZhbHNlKVxuPC9zY3JpcHQ+XG5cbjxzdHlsZT5cbi5zaW5nbGV0b24tdG9vbHRpcCB7XG4gIHRyYW5zaXRpb246IHRyYW5zZm9ybSAwLjNzIHZhcigtLWVsLXRyYW5zaXRpb24tZnVuY3Rpb24tZmFzdC1iZXppZXIpO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tooltip/singleton.vue)_

vue

```
<template>
  <div>
    <el-button
      v-for="i in 3"
      :key="i"
      @mouseover="(e) => (buttonRef = e.currentTarget)"
      @click="visible = !visible"
      >Click to open tooltip</el-button
    >
  </div>

  <el-tooltip
    ref="tooltipRef"
    :visible="visible"
    :popper-options="{
      modifiers: [
        {
          name: 'computeStyles',
          options: {
            adaptive: false,
            enabled: false,
          },
        },
      ],
    }"
    :virtual-ref="buttonRef"
    virtual-triggering
    popper-class="singleton-tooltip"
  >
    <template #content>
      <span> Some content </span>
    </template>
  </el-tooltip>
</template>

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

const buttonRef = ref()
const tooltipRef = ref()

const visible = ref(false)
</script>

<style>
.singleton-tooltip {
  transition: transform 0.3s var(--el-transition-function-fast-bezier);
}
</style>
```

隐藏源代码

## 受控模式 [​](#受控模式)

Tooltip 可以通过父组件使用 `:visible` 来控制它的显示与关闭。

Hover me

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdG9vbHRpcCA6dmlzaWJsZT1cInZpc2libGVcIj5cbiAgICA8dGVtcGxhdGUgI2NvbnRlbnQ+XG4gICAgICA8c3Bhbj5Db250ZW50PC9zcGFuPlxuICAgIDwvdGVtcGxhdGU+XG4gICAgPGVsLWJ1dHRvbiBAbW91c2VlbnRlcj1cInZpc2libGUgPSB0cnVlXCIgQG1vdXNlbGVhdmU9XCJ2aXNpYmxlID0gZmFsc2VcIj5cbiAgICAgIEhvdmVyIG1lXG4gICAgPC9lbC1idXR0b24+XG4gIDwvZWwtdG9vbHRpcD5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgc2V0dXAgbGFuZz1cInRzXCI+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5cbmNvbnN0IHZpc2libGUgPSByZWYoZmFsc2UpXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tooltip/controlled.vue)_

vue

```
<template>
  <el-tooltip :visible="visible">
    <template #content>
      <span>Content</span>
    </template>
    <el-button @mouseenter="visible = true" @mouseleave="visible = false">
      Hover me
    </el-button>
  </el-tooltip>
</template>

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

const visible = ref(false)
</script>
```

隐藏源代码

## 自定义动画 [​](#自定义动画)

Tooltip 可以自定义动画，您可以使用 `transition` 设置所需的动画效果。

TIP

过渡效果的更多信息可以在 [Vue 过渡效果](https://vuejs.org/guide/built-ins/transition.html#css-based-transitions) 中找到。

trigger me

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdG9vbHRpcCBjb250ZW50PVwiSSBhbSBhbiBlbC10b29sdGlwXCIgdHJhbnNpdGlvbj1cInNsaWRlLWZhZGVcIj5cbiAgICA8ZWwtYnV0dG9uPnRyaWdnZXIgbWU8L2VsLWJ1dHRvbj5cbiAgPC9lbC10b29sdGlwPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD48L3NjcmlwdD5cblxuPHN0eWxlPlxuLnNsaWRlLWZhZGUtZW50ZXItYWN0aXZlIHtcbiAgdHJhbnNpdGlvbjogYWxsIDAuM3MgZWFzZS1vdXQ7XG59XG5cbi5zbGlkZS1mYWRlLWxlYXZlLWFjdGl2ZSB7XG4gIHRyYW5zaXRpb246IGFsbCAwLjhzIGN1YmljLWJlemllcigxLCAwLjUsIDAuOCwgMSk7XG59XG5cbi5zbGlkZS1mYWRlLWVudGVyLWZyb20sXG4uc2xpZGUtZmFkZS1sZWF2ZS10byB7XG4gIHRyYW5zZm9ybTogdHJhbnNsYXRlWCgxMjBweCk7XG4gIG9wYWNpdHk6IDA7XG59XG48L3N0eWxlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tooltip/animations.vue)_

vue

```
<template>
  <el-tooltip content="I am an el-tooltip" transition="slide-fade">
    <el-button>trigger me</el-button>
  </el-tooltip>
</template>

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

<style>
.slide-fade-enter-active {
  transition: all 0.3s ease-out;
}

.slide-fade-leave-active {
  transition: all 0.8s cubic-bezier(1, 0.5, 0.8, 1);
}

.slide-fade-enter-from,
.slide-fade-leave-to {
  transform: translateX(120px);
  opacity: 0;
}
</style>
```

隐藏源代码

## 使用 `append-to` [​](#使用-append-to)

您必须等待 DOM 加载后才能使用 `targetElement`。

Click to open tooltip

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtdG9vbHRpcFxuICAgIDphcHBlbmQtdG89XCJ0YXJnZXRFbGVtZW50XCJcbiAgICB0cmlnZ2VyPVwiY2xpY2tcIlxuICAgIGNvbnRlbnQ9XCJBcHBlbmQgdG8gLnRhcmdldFwiXG4gICAgcGxhY2VtZW50PVwidG9wXCJcbiAgPlxuICAgIDxlbC1idXR0b24gY2xhc3M9XCJ0YXJnZXRcIj5DbGljayB0byBvcGVuIHRvb2x0aXA8L2VsLWJ1dHRvbj5cbiAgPC9lbC10b29sdGlwPlxuPC90ZW1wbGF0ZT5cblxuPHNjcmlwdCBsYW5nPVwidHNcIiBzZXR1cD5cbmltcG9ydCB7IG9uTW91bnRlZCwgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCB0YXJnZXRFbGVtZW50ID0gcmVmKCcnKVxuXG5vbk1vdW50ZWQoKCkgPT4ge1xuICB0YXJnZXRFbGVtZW50LnZhbHVlID0gJy50YXJnZXQnXG59KVxuPC9zY3JpcHQ+XG5cbjxzdHlsZSBzY29wZWQ+XG4udGFyZ2V0IHtcbiAgcG9zaXRpb246IHJlbGF0aXZlO1xuICBtYXJnaW4tdG9wOiAyMHB4O1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/tooltip/append-to.vue)_

vue

```
<template>
  <el-tooltip
    :append-to="targetElement"
    trigger="click"
    content="Append to .target"
    placement="top"
  >
    <el-button class="target">Click to open tooltip</el-button>
  </el-tooltip>
</template>

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

const targetElement = ref('')

onMounted(() => {
  targetElement.value = '.target'
})
</script>

<style scoped>
.target {
  position: relative;
  margin-top: 20px;
}
</style>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 名称 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| append-to | 指示 Tooltip 的内容将附加在哪一个网页元素上 | `CSSSelector` / `HTMLElement` | — |
| effect | Tooltip 主题，内置了 `dark` / `light` 两种 | `enum` | dark |
| content | 显示的内容，也可被 `slot#content` 覆盖 | `string` | '' |
| raw-content | `content` 中的内容是否作为 HTML 字符串处理 | `boolean` | false |
| placement | Tooltip 组件出现的位置 | `enum` | bottom |
| fallback-placements | Tooltip 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | `array` | — |
| visible / v-model:visible | Tooltip 组件可见性 | `boolean` | — |
| disabled | Tooltip 组件是否禁用 | `boolean` | — |
| offset | Tooltip 出现位置的偏移量 | `number` | 12 |
| transition | 动画名称 | `string` | — |
| popper-options | [popper.js](https://popper.js.org/docs/v2/) 参数 | `object` 请参考 [popper.js](https://popper.js.org/docs/v2/) 文档 | {} |
| arrow-offset 2.9.10 | 控制Tooltip的箭头相对于弹出窗口的偏移(添加)。 | `number` | 5 |
| show-after | 延迟显示时间（以毫秒为单位），在受控模式下无效。 | `number` | 0 |
| show-arrow | tooltip 的内容是否有箭头 | `boolean` | true |
| hide-after | 消失延迟时间（以毫秒为单位），在受控模式下无效。 | `number` | 200 |
| auto-close | 隐藏提示框的超时时间（以毫秒为单位），在受控模式下无效。 | `number` | 0 |
| popper-class | 为 Tooltip 的 popper 添加自定义类名 | `string` | — |
| popper-style | 为 Tooltip 的 popper 添加自定义样式 | `string` / `object` | — |
| enterable | 鼠标是否可进入到 tooltip 中 | `boolean` | true |
| teleported | 是否使用 teleport。设置成 `true`则会被追加到 `append-to` 的位置 | `boolean` | true |
| trigger | 提示框的触发方式（用于显示），在受控模式下无效。 | `enum` / `array` | hover |
| virtual-triggering | 用来标识虚拟触发是否被启用 | `boolean` | — |
| virtual-ref | 标识虚拟触发时的触发元素 | `HTMLElement` | — |
| trigger-keys | 当通过鼠标点击使触发元素获得焦点时，可以定义一组键盘按键代码，通过键盘控制提示框的显示，在受控模式下无效。 | `Array` | \['Enter','Space'\] |
| persistent | 当tooltip未激活且 `persistent` 为 `false` 时，tooltip将被销毁。 | `boolean` | — |
| aria-label a11y | 和 `aria-label` 属性保持一致 | `string` | — |
| focus-on-target 2.11.2 | 当通过悬停触发提示时，是否聚焦触发元素，以提升可访问性 | false | false |

### 事件 [​](#事件)

| 插槽名 | 说明 | 类型 |
| --- | --- | --- |
| before-show | 在显示提示框之前触发。 将触发原因作为参数传入。 | `Function` |
| show | 在提示框显示时触发。 将触发原因作为参数传入。 | `Function` |
| before-hide | 在提示框隐藏之前触发。 将触发原因作为参数传入。 | `Function` |
| hide | 在提示框隐藏时触发。 将触发原因作为参数传入。 | `Function` |

### Slots [​](#slots)

| 名称 | 详情 |
| --- | --- |
| default | 提示框触发及参考元素，只接受单个根元素。 |
| content | 自定义内容 |

### Exposes [​](#exposes)

| 方法名 | 详情 | Type |
| --- | --- | --- |
| popperRef | el-popper 组件实例 | `object` |
| contentRef | el-tooltip-content 组件实例 | `object` |
| isFocusInsideContent | 验证当前焦点事件是否在 el-tooltip-content 中触发 | `Function` |
| updatePopper | 更新 el-popper组件实例 | `Function` |
| onOpen | onClose 方法控制 el-tooltip 显示状态 | `Function` |
| onClose | onClose 方法控制 el-tooltip 显示状态 | `Function` |
| hide | 提供 hide 方法 | `Function` |

## FAQ [​](#faq)

#### 如何在嵌套了 tooltip 的情况下允许输入框输入空格？ [​](#如何在嵌套了-tooltip-的情况下允许输入框输入空格)

典型问题： [#20907](https://github.com/element-plus/element-plus/issues/20907)

vue

```
<template>
  <el-tooltip content="tooltip content" placement="top" :trigger-keys="[]">
    <el-input v-model="value" placeholder="" />
  </el-tooltip>
</template>
```

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/tooltip) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/tooltip.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/tooltip.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/57385187?v=4&size=64)](https://github.com/opengraphica)[![](https://avatars.githubusercontent.com/u/25458528?v=4&size=64)](https://github.com/weidehai)[![](https://avatars.githubusercontent.com/u/26672484?v=4&size=64)](https://github.com/msidolphin)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/117748716?v=4&size=64)](https://github.com/thinkasany)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/39730999?v=4&size=64)](https://github.com/buqiyuan)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/109521682?v=4&size=64)](https://github.com/snowbitx)[![](https://avatars.githubusercontent.com/u/54931083?v=4&size=64)](https://github.com/wjp980108)[![](https://avatars.githubusercontent.com/u/33827314?v=4&size=64)](https://github.com/gjfei)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/120718501?v=4&size=64)](https://github.com/xiaowhang)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/7897937?v=4&size=64)](https://github.com/myronliu347)[![](https://avatars.githubusercontent.com/u/70570907?v=4&size=64)](https://github.com/chouchouji)[![](https://avatars.githubusercontent.com/u/28584349?v=4&size=64)](https://github.com/wangcch)[![](https://avatars.githubusercontent.com/u/46702192?v=4&size=64)](https://github.com/Lck6de1p)[![](https://avatars.githubusercontent.com/u/23100055?v=4&size=64)](https://github.com/holazz)[![](https://avatars.githubusercontent.com/u/26035718?v=4&size=64)](https://github.com/SnowingFox)[![](https://avatars.githubusercontent.com/u/169252980?v=4&size=64)](https://github.com/xiaochenchen-igg-com)[![](https://avatars.githubusercontent.com/u/49635988?v=4&size=64)](https://github.com/BgaSol)[![](https://avatars.githubusercontent.com/u/6134068?v=4&size=64)](https://github.com/CarterLi)[![](https://avatars.githubusercontent.com/u/44761321?v=4&size=64)](https://github.com/xiaoxian521)[![](https://avatars.githubusercontent.com/u/49236612?v=4&size=64)](https://github.com/hhparty)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/62818957?v=4&size=64)](https://github.com/ZacharyBear)[![](https://avatars.githubusercontent.com/u/34681550?v=4&size=64)](https://github.com/zhixiaotong)[![](https://avatars.githubusercontent.com/u/27413795?v=4&size=64)](https://github.com/SpanManX)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/19850462?v=4&size=64)](https://github.com/jeff-fe)[![](https://avatars.githubusercontent.com/u/56570859?v=4&size=64)](https://github.com/XSUV)[![](https://avatars.githubusercontent.com/u/18349295?v=4&size=64)](https://github.com/zt123123)[![](https://avatars.githubusercontent.com/u/30518686?v=4&size=64)](https://github.com/emojiiii)[![](https://avatars.githubusercontent.com/u/23303044?v=4&size=64)](https://github.com/imswk)[![](https://avatars.githubusercontent.com/u/30256102?v=4&size=64)](https://github.com/leon-kfd)[![](https://avatars.githubusercontent.com/u/234136872?v=4&size=64)](https://github.com/z-kunf)[![](https://avatars.githubusercontent.com/u/140705167?v=4&size=64)](https://github.com/zhongli-kira)[![](https://avatars.githubusercontent.com/u/5755214?v=4&size=64)](https://github.com/aghArdeshir)[![](https://avatars.githubusercontent.com/u/8591261?v=4&size=64)](https://github.com/zeyongTsai)[![](https://avatars.githubusercontent.com/u/27912232?v=4&size=64)](https://github.com/Fuphoenixes)[![](https://avatars.githubusercontent.com/u/2849255?v=4&size=64)](https://github.com/mg5566)[![](https://avatars.githubusercontent.com/u/30114549?v=4&size=64)](https://github.com/loosheng)[![](https://avatars.githubusercontent.com/u/166272183?v=4&size=64)](https://github.com/voyagerFeng)[![](https://avatars.githubusercontent.com/u/32354856?v=4&size=64)](https://github.com/baiwusanyu-c)[![](https://avatars.githubusercontent.com/u/60056876?v=4&size=64)](https://github.com/LinZhanMing)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/11409069?v=4&size=64)](https://github.com/freedomlang)

[Popover 弹出框](https://element-plus.org/zh-CN/component/popover)

[Divider 分割线](https://element-plus.org/zh-CN/component/divider)




---

<!-- ============================================ -->
<!-- 类别: 其他组件 -->
<!-- ============================================ -->

## [others/divider] Divider 分割线
> 官方文档: https://element-plus.org/zh-CN/component/divider.html

---

# Divider 分割线 [​](#divider-分割线)

更新日志待解决

1

区隔内容的分割线。

## 基础用法 [​](#基础用法)

对不同段落的文本进行分割。

I sit at my window this morning where the world like a passer-by stops for a moment, nods to me and goes.

There little thoughts are the rustle of leaves; they have their whisper of joy in my mind.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxzcGFuPlxuICAgICAgSSBzaXQgYXQgbXkgd2luZG93IHRoaXMgbW9ybmluZyB3aGVyZSB0aGUgd29ybGQgbGlrZSBhIHBhc3Nlci1ieSBzdG9wcyBmb3JcbiAgICAgIGEgbW9tZW50LCBub2RzIHRvIG1lIGFuZCBnb2VzLlxuICAgIDwvc3Bhbj5cbiAgICA8ZWwtZGl2aWRlciAvPlxuICAgIDxzcGFuPlxuICAgICAgVGhlcmUgbGl0dGxlIHRob3VnaHRzIGFyZSB0aGUgcnVzdGxlIG9mIGxlYXZlczsgdGhleSBoYXZlIHRoZWlyIHdoaXNwZXIgb2ZcbiAgICAgIGpveSBpbiBteSBtaW5kLlxuICAgIDwvc3Bhbj5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuIn0=)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/divider/basic-usage.vue)_

vue

```
<template>
  <div>
    <span>
      I sit at my window this morning where the world like a passer-by stops for
      a moment, nods to me and goes.
    </span>
    <el-divider />
    <span>
      There little thoughts are the rustle of leaves; they have their whisper of
      joy in my mind.
    </span>
  </div>
</template>
```

隐藏源代码

## 设置文案 [​](#设置文案)

可以在分割线上自定义文本内容。

What you are you do not see, what you see is your shadow.

Rabindranath Tagore

My wishes are fools, they shout across thy song, my Master. Let me but listen.

I cannot choose the best. The best chooses me.

Rabindranath Tagore

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxzcGFuPldoYXQgeW91IGFyZSB5b3UgZG8gbm90IHNlZSwgd2hhdCB5b3Ugc2VlIGlzIHlvdXIgc2hhZG93LiA8L3NwYW4+XG4gICAgPGVsLWRpdmlkZXIgY29udGVudC1wb3NpdGlvbj1cImxlZnRcIj5SYWJpbmRyYW5hdGggVGFnb3JlPC9lbC1kaXZpZGVyPlxuICAgIDxzcGFuPlxuICAgICAgTXkgd2lzaGVzIGFyZSBmb29scywgdGhleSBzaG91dCBhY3Jvc3MgdGh5IHNvbmcsIG15IE1hc3Rlci4gTGV0IG1lIGJ1dFxuICAgICAgbGlzdGVuLlxuICAgIDwvc3Bhbj5cbiAgICA8ZWwtZGl2aWRlcj5cbiAgICAgIDxlbC1pY29uPjxzdGFyLWZpbGxlZCAvPjwvZWwtaWNvbj5cbiAgICA8L2VsLWRpdmlkZXI+XG4gICAgPHNwYW4+SSBjYW5ub3QgY2hvb3NlIHRoZSBiZXN0LiBUaGUgYmVzdCBjaG9vc2VzIG1lLjwvc3Bhbj5cbiAgICA8ZWwtZGl2aWRlciBjb250ZW50LXBvc2l0aW9uPVwicmlnaHRcIj5SYWJpbmRyYW5hdGggVGFnb3JlPC9lbC1kaXZpZGVyPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzY3JpcHQgbGFuZz1cInRzXCIgc2V0dXA+XG5pbXBvcnQgeyBTdGFyRmlsbGVkIH0gZnJvbSAnQGVsZW1lbnQtcGx1cy9pY29ucy12dWUnXG48L3NjcmlwdD5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/divider/custom-content.vue)_

vue

```
<template>
  <div>
    <span>What you are you do not see, what you see is your shadow. </span>
    <el-divider content-position="left">Rabindranath Tagore</el-divider>
    <span>
      My wishes are fools, they shout across thy song, my Master. Let me but
      listen.
    </span>
    <el-divider>
      <el-icon><star-filled /></el-icon>
    </el-divider>
    <span>I cannot choose the best. The best chooses me.</span>
    <el-divider content-position="right">Rabindranath Tagore</el-divider>
  </div>
</template>

<script lang="ts" setup>
import { StarFilled } from '@element-plus/icons-vue'
</script>
```

隐藏源代码

## 虚线 [​](#虚线)

您可以设置分隔符的样式。

What language is thine, O sea?

The language of eternal question.

What language is thy answer, O sky?

The language of eternal silence.

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxzcGFuPldoYXQgbGFuZ3VhZ2UgaXMgdGhpbmUsIE8gc2VhPzwvc3Bhbj5cbiAgICA8ZWwtZGl2aWRlciBib3JkZXItc3R5bGU9XCJkYXNoZWRcIiAvPlxuICAgIDxzcGFuPlRoZSBsYW5ndWFnZSBvZiBldGVybmFsIHF1ZXN0aW9uLjwvc3Bhbj5cbiAgPC9kaXY+XG4gIDxlbC1kaXZpZGVyIGJvcmRlci1zdHlsZT1cImRvdHRlZFwiIC8+XG4gIDxzcGFuPldoYXQgbGFuZ3VhZ2UgaXMgdGh5IGFuc3dlciwgTyBza3k/PC9zcGFuPlxuICA8ZWwtZGl2aWRlciBib3JkZXItc3R5bGU9XCJkb3VibGVcIiAvPlxuICA8c3Bhbj5UaGUgbGFuZ3VhZ2Ugb2YgZXRlcm5hbCBzaWxlbmNlLjwvc3Bhbj5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/divider/line-dashed.vue)_

vue

```
<template>
  <div>
    <span>What language is thine, O sea?</span>
    <el-divider border-style="dashed" />
    <span>The language of eternal question.</span>
  </div>
  <el-divider border-style="dotted" />
  <span>What language is thy answer, O sky?</span>
  <el-divider border-style="double" />
  <span>The language of eternal silence.</span>
</template>
```

隐藏源代码

## 垂直分隔线 [​](#垂直分隔线)

Rain

Home

Grass

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZGl2PlxuICAgIDxzcGFuPlJhaW48L3NwYW4+XG4gICAgPGVsLWRpdmlkZXIgZGlyZWN0aW9uPVwidmVydGljYWxcIiAvPlxuICAgIDxzcGFuPkhvbWU8L3NwYW4+XG4gICAgPGVsLWRpdmlkZXIgZGlyZWN0aW9uPVwidmVydGljYWxcIiBib3JkZXItc3R5bGU9XCJkYXNoZWRcIiAvPlxuICAgIDxzcGFuPkdyYXNzPC9zcGFuPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/divider/vertical-divider.vue)_

vue

```
<template>
  <div>
    <span>Rain</span>
    <el-divider direction="vertical" />
    <span>Home</span>
    <el-divider direction="vertical" border-style="dashed" />
    <span>Grass</span>
  </div>
</template>
```

隐藏源代码

## API [​](#api)

### Attributes [​](#attributes)

| 属性名 | 说明 | 类型 | 默认 |
| --- | --- | --- | --- |
| direction | 设置分割线方向 | `enum` | horizontal |
| border-style | 设置分隔符样式 | `enum` [css/border-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-style) | solid |
| content-position | 自定义分隔线内容的位置 | `enum` | center |

### Slots [​](#slots)

| 插槽名 | 说明 |
| --- | --- |
| default | 设置分割线文案的位置 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/divider) • [样式](https://github.com/element-plus/element-plus/tree/dev/packages/theme-chalk/src/divider.scss) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/divider.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/6481596?v=4&size=64)](https://github.com/sxzz)[![](https://avatars.githubusercontent.com/u/25154432?v=4&size=64)](https://github.com/YunYouJun)[![](https://avatars.githubusercontent.com/u/15975785?v=4&size=64)](https://github.com/jw-foss)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/20151622?v=4&size=64)](https://github.com/william-xue)[![](https://avatars.githubusercontent.com/u/27342882?v=4&size=64)](https://github.com/ryuhangyeong)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/61937205?v=4&size=64)](https://github.com/keeplearning66)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/23251408?v=4&size=64)](https://github.com/chenxch)[![](https://avatars.githubusercontent.com/u/144010?v=4&size=64)](https://github.com/purepear)[![](https://avatars.githubusercontent.com/u/88016243?v=4&size=64)](https://github.com/wzrove)[![](https://avatars.githubusercontent.com/u/21104054?v=4&size=64)](https://github.com/Alanscut)[![](https://avatars.githubusercontent.com/u/12124478?v=4&size=64)](https://github.com/Hades-li)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/29560987?v=4&size=64)](https://github.com/adaex)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/17680888?v=4&size=64)](https://github.com/iamkun)[![](https://avatars.githubusercontent.com/u/52314078?v=4&size=64)](https://github.com/vaebe)

[Tooltip 文字提示](https://element-plus.org/zh-CN/component/tooltip)

[Watermark 水印](https://element-plus.org/zh-CN/component/watermark)




---
## [others/watermark] Watermark 水印
> 官方文档: https://element-plus.org/zh-CN/component/watermark.html

---

# Watermark 水印 [​](#watermark-水印)

更新日志待解决

0

在页面上添加文本或图片等水印信息

## 基础用法 [​](#基础用法)

最简单的用法。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlYWN0aXZlLCB3YXRjaCB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IGlzRGFyayB9IGZyb20gJ34vY29tcG9zYWJsZXMvZGFyaydcblxuY29uc3QgZm9udCA9IHJlYWN0aXZlKHtcbiAgY29sb3I6ICdyZ2JhKDAsIDAsIDAsIC4xNSknLFxufSlcblxud2F0Y2goXG4gIGlzRGFyayxcbiAgKCkgPT4ge1xuICAgIGZvbnQuY29sb3IgPSBpc0RhcmsudmFsdWVcbiAgICAgID8gJ3JnYmEoMjU1LCAyNTUsIDI1NSwgLjE1KSdcbiAgICAgIDogJ3JnYmEoMCwgMCwgMCwgLjE1KSdcbiAgfSxcbiAge1xuICAgIGltbWVkaWF0ZTogdHJ1ZSxcbiAgfVxuKVxuPC9zY3JpcHQ+XG5cbjx0ZW1wbGF0ZT5cbiAgPGVsLXdhdGVybWFyayA6Zm9udD1cImZvbnRcIj5cbiAgICA8ZGl2IHN0eWxlPVwiaGVpZ2h0OiA1MDBweFwiIC8+XG4gIDwvZWwtd2F0ZXJtYXJrPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/watermark/basic.vue)_

vue

```
<script setup lang="ts">
import { reactive, watch } from 'vue'
import { isDark } from '~/composables/dark'

const font = reactive({
  color: 'rgba(0, 0, 0, .15)',
})

watch(
  isDark,
  () => {
    font.color = isDark.value
      ? 'rgba(255, 255, 255, .15)'
      : 'rgba(0, 0, 0, .15)'
  },
  {
    immediate: true,
  }
)
</script>

<template>
  <el-watermark :font="font">
    <div style="height: 500px" />
  </el-watermark>
</template>
```

隐藏源代码

## 多行水印 [​](#多行水印)

使用 `content`设置一个字符串数组来指定多行文本水印内容

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlYWN0aXZlLCB3YXRjaCB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IGlzRGFyayB9IGZyb20gJ34vY29tcG9zYWJsZXMvZGFyaydcblxuY29uc3QgZm9udCA9IHJlYWN0aXZlKHtcbiAgY29sb3I6ICdyZ2JhKDAsIDAsIDAsIC4xNSknLFxufSlcblxud2F0Y2goXG4gIGlzRGFyayxcbiAgKCkgPT4ge1xuICAgIGZvbnQuY29sb3IgPSBpc0RhcmsudmFsdWVcbiAgICAgID8gJ3JnYmEoMjU1LCAyNTUsIDI1NSwgLjE1KSdcbiAgICAgIDogJ3JnYmEoMCwgMCwgMCwgLjE1KSdcbiAgfSxcbiAge1xuICAgIGltbWVkaWF0ZTogdHJ1ZSxcbiAgfVxuKVxuPC9zY3JpcHQ+XG5cbjx0ZW1wbGF0ZT5cbiAgPGVsLXdhdGVybWFyayA6Zm9udD1cImZvbnRcIiA6Y29udGVudD1cIlsnRWxlbWVudCsnLCAnRWxlbWVudCBQbHVzJ11cIj5cbiAgICA8ZGl2IHN0eWxlPVwiaGVpZ2h0OiA1MDBweFwiIC8+XG4gIDwvZWwtd2F0ZXJtYXJrPlxuPC90ZW1wbGF0ZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/watermark/multi-line.vue)_

vue

```
<script setup lang="ts">
import { reactive, watch } from 'vue'
import { isDark } from '~/composables/dark'

const font = reactive({
  color: 'rgba(0, 0, 0, .15)',
})

watch(
  isDark,
  () => {
    font.color = isDark.value
      ? 'rgba(255, 255, 255, .15)'
      : 'rgba(0, 0, 0, .15)'
  },
  {
    immediate: true,
  }
)
</script>

<template>
  <el-watermark :font="font" :content="['Element+', 'Element Plus']">
    <div style="height: 500px" />
  </el-watermark>
</template>
```

隐藏源代码

## 图片水印 [​](#图片水印)

通过 `image` 指定图像地址。 为了确保图像清晰展示而不是被拉伸，请设置宽度和高度，建议使用至少两倍的宽度和高度的图片来保证显示效果。

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHRlbXBsYXRlPlxuICA8ZWwtd2F0ZXJtYXJrXG4gICAgOndpZHRoPVwiMTMwXCJcbiAgICA6aGVpZ2h0PVwiMzBcIlxuICAgIGltYWdlPVwiaHR0cHM6Ly9lbGVtZW50LXBsdXMub3JnL2ltYWdlcy9lbGVtZW50LXBsdXMtbG9nby5zdmdcIlxuICA+XG4gICAgPGRpdiBzdHlsZT1cImhlaWdodDogNTAwcHhcIiAvPlxuICA8L2VsLXdhdGVybWFyaz5cbjwvdGVtcGxhdGU+XG4ifQ==)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/watermark/image.vue)_

vue

```
<template>
  <el-watermark
    :width="130"
    :height="30"
    image="https://element-plus.org/images/element-plus-logo.svg"
  >
    <div style="height: 500px" />
  </el-watermark>
</template>
```

隐藏源代码

## 自定义配置 [​](#自定义配置)

配置自定义参数预览水印效果。

# Element Plus

## A Vue 3 based component library for designers and developers

![示例图片](https://element-plus.org/images/hamburger.png)

TS

JS

_[](https://element-plus.run/#eyJBcHAudnVlIjoiPHNjcmlwdCBzZXR1cCBsYW5nPVwidHNcIj5cbmltcG9ydCB7IHJlYWN0aXZlLCB3YXRjaCB9IGZyb20gJ3Z1ZSdcbmltcG9ydCB7IGlzRGFyayB9IGZyb20gJ34vY29tcG9zYWJsZXMvZGFyaydcblxuY29uc3QgY29uZmlnID0gcmVhY3RpdmUoe1xuICBjb250ZW50OiAnRWxlbWVudCBQbHVzJyxcbiAgZm9udDoge1xuICAgIGZvbnRTaXplOiAxNixcbiAgICBjb2xvcjogJ3JnYmEoMCwgMCwgMCwgMC4xNSknLFxuICB9LFxuICB6SW5kZXg6IC0xLFxuICByb3RhdGU6IC0yMixcbiAgZ2FwOiBbMTAwLCAxMDBdIGFzIFtudW1iZXIsIG51bWJlcl0sXG4gIG9mZnNldDogW10gYXMgdW5rbm93biBhcyBbbnVtYmVyLCBudW1iZXJdLFxufSlcblxud2F0Y2goXG4gIGlzRGFyayxcbiAgKHZhbHVlKSA9PiB7XG4gICAgY29uZmlnLmZvbnQuY29sb3IgPSB2YWx1ZVxuICAgICAgPyAncmdiYSgyNTUsIDI1NSwgMjU1LCAuMTUpJ1xuICAgICAgOiAncmdiYSgwLCAwLCAwLCAuMTUpJ1xuICB9LFxuICB7IGltbWVkaWF0ZTogdHJ1ZSB9XG4pXG48L3NjcmlwdD5cblxuPHRlbXBsYXRlPlxuICA8ZGl2IGNsYXNzPVwid3JhcHBlclwiPlxuICAgIDxlbC13YXRlcm1hcmtcbiAgICAgIGNsYXNzPVwid2F0ZXJtYXJrXCJcbiAgICAgIDpjb250ZW50PVwiY29uZmlnLmNvbnRlbnRcIlxuICAgICAgOmZvbnQ9XCJjb25maWcuZm9udFwiXG4gICAgICA6ei1pbmRleD1cImNvbmZpZy56SW5kZXhcIlxuICAgICAgOnJvdGF0ZT1cImNvbmZpZy5yb3RhdGVcIlxuICAgICAgOmdhcD1cImNvbmZpZy5nYXBcIlxuICAgICAgOm9mZnNldD1cImNvbmZpZy5vZmZzZXRcIlxuICAgID5cbiAgICAgIDxkaXYgY2xhc3M9XCJ3YXRlcm1hcmstY29udGFpbmVyXCI+XG4gICAgICAgIDxoMT5FbGVtZW50IFBsdXM8L2gxPlxuICAgICAgICA8aDI+QSBWdWUgMyBiYXNlZCBjb21wb25lbnQgbGlicmFyeSBmb3IgZGVzaWduZXJzIGFuZCBkZXZlbG9wZXJzPC9oMj5cbiAgICAgICAgPGltZyBzcmM9XCIvaW1hZ2VzL2hhbWJ1cmdlci5wbmdcIiBhbHQ9XCLnpLrkvovlm77niYdcIiAvPlxuICAgICAgPC9kaXY+XG4gICAgPC9lbC13YXRlcm1hcms+XG4gICAgPGVsLWZvcm1cbiAgICAgIGNsYXNzPVwiZm9ybVwiXG4gICAgICA6bW9kZWw9XCJjb25maWdcIlxuICAgICAgbGFiZWwtcG9zaXRpb249XCJ0b3BcIlxuICAgICAgbGFiZWwtd2lkdGg9XCI1MHB4XCJcbiAgICA+XG4gICAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiQ29udGVudFwiPlxuICAgICAgICA8ZWwtaW5wdXQgdi1tb2RlbD1cImNvbmZpZy5jb250ZW50XCIgLz5cbiAgICAgIDwvZWwtZm9ybS1pdGVtPlxuICAgICAgPGVsLWZvcm0taXRlbSBsYWJlbD1cIkNvbG9yXCI+XG4gICAgICAgIDxlbC1jb2xvci1waWNrZXIgdi1tb2RlbD1cImNvbmZpZy5mb250LmNvbG9yXCIgc2hvdy1hbHBoYSAvPlxuICAgICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiRm9udFNpemVcIj5cbiAgICAgICAgPGVsLXNsaWRlciB2LW1vZGVsPVwiY29uZmlnLmZvbnQuZm9udFNpemVcIiAvPlxuICAgICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiekluZGV4XCI+XG4gICAgICAgIDxlbC1zbGlkZXIgdi1tb2RlbD1cImNvbmZpZy56SW5kZXhcIiAvPlxuICAgICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiUm90YXRlXCI+XG4gICAgICAgIDxlbC1zbGlkZXIgdi1tb2RlbD1cImNvbmZpZy5yb3RhdGVcIiA6bWluPVwiLTE4MFwiIDptYXg9XCIxODBcIiAvPlxuICAgICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiR2FwXCI+XG4gICAgICAgIDxlbC1zcGFjZT5cbiAgICAgICAgICA8ZWwtaW5wdXQtbnVtYmVyIHYtbW9kZWw9XCJjb25maWcuZ2FwWzBdXCIgY29udHJvbHMtcG9zaXRpb249XCJyaWdodFwiIC8+XG4gICAgICAgICAgPGVsLWlucHV0LW51bWJlciB2LW1vZGVsPVwiY29uZmlnLmdhcFsxXVwiIGNvbnRyb2xzLXBvc2l0aW9uPVwicmlnaHRcIiAvPlxuICAgICAgICA8L2VsLXNwYWNlPlxuICAgICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgICA8ZWwtZm9ybS1pdGVtIGxhYmVsPVwiT2Zmc2V0XCI+XG4gICAgICAgIDxlbC1zcGFjZT5cbiAgICAgICAgICA8ZWwtaW5wdXQtbnVtYmVyXG4gICAgICAgICAgICB2LW1vZGVsPVwiY29uZmlnLm9mZnNldFswXVwiXG4gICAgICAgICAgICBwbGFjZWhvbGRlcj1cIm9mZnNldExlZnRcIlxuICAgICAgICAgICAgY29udHJvbHMtcG9zaXRpb249XCJyaWdodFwiXG4gICAgICAgICAgLz5cbiAgICAgICAgICA8ZWwtaW5wdXQtbnVtYmVyXG4gICAgICAgICAgICB2LW1vZGVsPVwiY29uZmlnLm9mZnNldFsxXVwiXG4gICAgICAgICAgICBwbGFjZWhvbGRlcj1cIm9mZnNldFRvcFwiXG4gICAgICAgICAgICBjb250cm9scy1wb3NpdGlvbj1cInJpZ2h0XCJcbiAgICAgICAgICAvPlxuICAgICAgICA8L2VsLXNwYWNlPlxuICAgICAgPC9lbC1mb3JtLWl0ZW0+XG4gICAgPC9lbC1mb3JtPlxuICA8L2Rpdj5cbjwvdGVtcGxhdGU+XG5cbjxzdHlsZSBzY29wZWQ+XG4ud3JhcHBlciB7XG4gIGRpc3BsYXk6IGZsZXg7XG59XG4ud2F0ZXJtYXJrIHtcbiAgZGlzcGxheTogZmxleDtcbiAgZmxleDogYXV0bztcbn1cbi53YXRlcm1hcmstY29udGFpbmVyIHtcbiAgZmxleDogYXV0bztcbn1cbi5mb3JtIHtcbiAgd2lkdGg6IDMzMHB4O1xuICBtYXJnaW4tbGVmdDogMjBweDtcbiAgYm9yZGVyLWxlZnQ6IDFweCBzb2xpZCAjZWVlO1xuICBwYWRkaW5nLWxlZnQ6IDIwcHg7XG59XG5cbmltZyB7XG4gIHotaW5kZXg6IDEwO1xuICB3aWR0aDogMTAwJTtcbiAgbWF4LXdpZHRoOiAzMDBweDtcbiAgcG9zaXRpb246IHJlbGF0aXZlO1xufVxuPC9zdHlsZT5cbiJ9)__[](https://github.com/element-plus/element-plus/edit/dev/docs/examples/watermark/custom.vue)_

vue

```
<script setup lang="ts">
import { reactive, watch } from 'vue'
import { isDark } from '~/composables/dark'

const config = reactive({
  content: 'Element Plus',
  font: {
    fontSize: 16,
    color: 'rgba(0, 0, 0, 0.15)',
  },
  zIndex: -1,
  rotate: -22,
  gap: [100, 100] as [number, number],
  offset: [] as unknown as [number, number],
})

watch(
  isDark,
  (value) => {
    config.font.color = value
      ? 'rgba(255, 255, 255, .15)'
      : 'rgba(0, 0, 0, .15)'
  },
  { immediate: true }
)
</script>

<template>
  <div class="wrapper">
    <el-watermark
      class="watermark"
      :content="config.content"
      :font="config.font"
      :z-index="config.zIndex"
      :rotate="config.rotate"
      :gap="config.gap"
      :offset="config.offset"
    >
      <div class="watermark-container">
        <h1>Element Plus</h1>
        <h2>A Vue 3 based component library for designers and developers</h2>
        <img src="/images/hamburger.png" alt="示例图片" />
      </div>
    </el-watermark>
    <el-form
      class="form"
      :model="config"
      label-position="top"
      label-width="50px"
    >
      <el-form-item label="Content">
        <el-input v-model="config.content" />
      </el-form-item>
      <el-form-item label="Color">
        <el-color-picker v-model="config.font.color" show-alpha />
      </el-form-item>
      <el-form-item label="FontSize">
        <el-slider v-model="config.font.fontSize" />
      </el-form-item>
      <el-form-item label="zIndex">
        <el-slider v-model="config.zIndex" />
      </el-form-item>
      <el-form-item label="Rotate">
        <el-slider v-model="config.rotate" :min="-180" :max="180" />
      </el-form-item>
      <el-form-item label="Gap">
        <el-space>
          <el-input-number v-model="config.gap[0]" controls-position="right" />
          <el-input-number v-model="config.gap[1]" controls-position="right" />
        </el-space>
      </el-form-item>
      <el-form-item label="Offset">
        <el-space>
          <el-input-number
            v-model="config.offset[0]"
            placeholder="offsetLeft"
            controls-position="right"
          />
          <el-input-number
            v-model="config.offset[1]"
            placeholder="offsetTop"
            controls-position="right"
          />
        </el-space>
      </el-form-item>
    </el-form>
  </div>
</template>

<style scoped>
.wrapper {
  display: flex;
}
.watermark {
  display: flex;
  flex: auto;
}
.watermark-container {
  flex: auto;
}
.form {
  width: 330px;
  margin-left: 20px;
  border-left: 1px solid #eee;
  padding-left: 20px;
}

img {
  z-index: 10;
  width: 100%;
  max-width: 300px;
  position: relative;
}
</style>
```

隐藏源代码

## API [​](#api)

### 属性 [​](#属性)

| 属性名 | 描述 | 类型 | 默认值 |
| --- | --- | --- | --- |
| width | 水印的宽度， `content` 的默认值是它自己的宽度 | `number` | 120 |
| height | 水印的高度， `content` 的默认值是它自己的高度 | `number` | 64 |
| rotate | 水印的旋转角度, 单位 `°` | `number` | \-22 |
| z-index | 水印元素的z-index值 | `number` | 9 |
| image | 水印图片，建议使用 2x 或 3x 图像 | `string` | — |
| content | 水印文本内容 | `string`/`array` | Element Plus |
| font | 文字样式 | [Font](#font) | [字体](#font) |
| gap | 水印之间的间距 | `array` | \[100, 100\] |
| offset | 水印从容器左上角的偏移 默认值为 `gap/2` | `array` | \[gap\[0\]/2, gap\[1\]/2\] |

### Font [​](#font)

| 名称 | 详情 | 类型 | 默认 |
| --- | --- | --- | --- |
| color | 字体颜色 | `string` | rgba(0,0,0,.15) |
| fontSize | 字体大小 | `number` / `string` | 16 |
| fontWeight | 字重 | `enum` | normal |
| fontFamily | 字体 | `string` | sans-serif |
| fontGap 2.11.5 | 字体间隙 | `number` | 3 |
| fontStyle | 字体样式 | `enum` | normal |
| textAlign | 文本对齐 | `enum` | center |
| textBaseline | 文本基线 | `enum` | hanging |

### Slots [​](#slots)

| 名称 | 详情 |
| --- | --- |
| 默认 | 添加水印的容器 |

## 源代码 [​](#源代码)

[组件](https://github.com/element-plus/element-plus/tree/dev/packages/components/watermark) • [文档](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/watermark.md)

## 贡献者 [​](#贡献者)

[![](https://avatars.githubusercontent.com/u/24516654?v=4&size=64)](https://github.com/btea)[![](https://avatars.githubusercontent.com/u/58726932?v=4&size=64)](https://github.com/rzzf)[![](https://avatars.githubusercontent.com/u/93767616?v=4&size=64)](https://github.com/makedopamine)[![](https://avatars.githubusercontent.com/u/226283245?v=4&size=64)](https://github.com/E66Crisp)[![](https://avatars.githubusercontent.com/u/56016153?v=4&size=64)](https://github.com/zzjiaxiang)[![](https://avatars.githubusercontent.com/u/45450994?v=4&size=64)](https://github.com/warmthsea)[![](https://avatars.githubusercontent.com/u/128720752?v=4&size=64)](https://github.com/cjn021)[![](https://avatars.githubusercontent.com/u/54931083?v=4&size=64)](https://github.com/wjp980108)[![](https://avatars.githubusercontent.com/u/52928534?v=4&size=64)](https://github.com/alonely-boy)[![](https://avatars.githubusercontent.com/u/45616067?v=4&size=64)](https://github.com/elioist)[![](https://avatars.githubusercontent.com/u/46493087?v=4&size=64)](https://github.com/FrontEndDog)[![](https://avatars.githubusercontent.com/u/29867660?v=4&size=64)](https://github.com/yuhengshen)[![](https://avatars.githubusercontent.com/u/91417411?v=4&size=64)](https://github.com/Dsaquel)[![](https://avatars.githubusercontent.com/u/34408516?v=4&size=64)](https://github.com/betavs)[![](https://avatars.githubusercontent.com/u/1532716?v=4&size=64)](https://github.com/godxiaoji)[![](https://avatars.githubusercontent.com/u/27912232?v=4&size=64)](https://github.com/Fuphoenixes)[![](https://avatars.githubusercontent.com/u/66096254?v=4&size=64)](https://github.com/IceyWu)[![](https://avatars.githubusercontent.com/u/23313167?v=4&size=64)](https://github.com/tolking)[![](https://avatars.githubusercontent.com/u/22388686?v=4&size=64)](https://github.com/TomatoDroid)[![](https://avatars.githubusercontent.com/u/38392315?v=4&size=64)](https://github.com/kooriookami)[![](https://avatars.githubusercontent.com/u/56141625?v=4&size=64)](https://github.com/micaiguai)[![](https://avatars.githubusercontent.com/u/145281501?v=4&size=64)](https://github.com/typed-sigterm)[![](https://avatars.githubusercontent.com/u/75473409?v=4&size=64)](https://github.com/lxKylin)[![](https://avatars.githubusercontent.com/u/69044080?v=4&size=64)](https://github.com/wzc520pyfm)

[Divider 分割线](https://element-plus.org/zh-CN/component/divider)




---
