Element Plus 不兼容变化（中文简体）

[sxzz]

• 中文简体
• English

本文档将列举与 Element UI 2.x 的不兼容变化。

开发环境

Vue CLI

如果您正在使用 Vue CLI 作为构建工具，请升级至最新版本，v4 与 v5 皆可。

Webpack 4

如果您正在使用 Webpack 4 作为构建工具，请添加以下配置。

// webpack.config.js
module.exports = {
  resolve: {
    extensions: ['.ts', '.js', '.mjs', '.json'],
  },
  module: {
    rules: [
      {
        test: /\.mjs$/i,
        include: /node_modules/,
        type: 'javascript/auto',
      },
    ],
  },
}

Webpack 5

如果您正在使用 Webpack 5 作为构建工具，请添加以下配置。

// webpack.config.js
module.exports = {
  resolve: {
    extensions: ['.ts', '.js', '.mjs', '.json'],
  },
  module: {
    rules: [
      {
        test: /\.mjs$/i,
        resolve: { byDependency: { esm: { fullySpecified: false } } },
      },
    ],
  },
}

兼容性

Element Plus 对浏览器的最低要求如下：

Edge ≥ 79	Firefox ≥ 78	Chrome ≥ 64	Safari ≥ 12

如果想在低版本浏览器上正常使用 Element Plus，请自行使用 Babel、ESBuild 或其他转换工具，并引入相应的 polyfill。

值得注意的是，Element Plus 使用到了 ResizeObserver，需要您自行引入 resize-observer-polyfill。详情请参阅 ResizeObserver 的兼容性。更多细节请参阅文档。

删除 Font Icon

基于类名的 Font Icon 已被移除，这意味着您需要把所有 el-icon- 相关的代码迁移至 SVG Font，并请参考以下对比表格。更多关于 SVG 图标的细节，您可以参阅此篇文档。您也可以使用 unplugin-icons 插件来进行自动导入。

Element UI

<template>
  <el-button type="primary" icon="el-icon-search">Search</el-button>
</template>

Element Plus

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

<template>
  <el-button type="primary" :icon="Search">Search</el-button>
</template>

组件名称	旧名称 (类型)	新名称 (类型)
Avatar	icon (string)	icon (string / Component)
Button	icon (string)	icon (string / Component)
DatePicker	prefix-icon (string)	prefix-icon (string / Component)
DatePicker	clear-icon (string)	clear-icon (string / Component)
Input	prefix-icon (string)	prefix-icon (string / Component)
Input	suffix-icon (string)	suffix-icon (string / Component)
MessageBox	icon-class (string)	icon (string / Component)
Message	icon-class (string)	icon (string / Component)
Notification	icon-class (string)	icon (string / Component)
PageHeader	icon (string)	icon (string / Component)
Select	clear-icon (string)	clear-icon (string / Component)
Select V2	clear-icon (string)	clear-icon (string / Component)
TimePicker	prefix-icon (string)	prefix-icon (string / Component)
TimePicker	clear-icon (string)	clear-icon (string / Component)
TimeSelect	prefix-icon (string)	prefix-icon (string / Component)
TimeSelect	clear-icon (string)	clear-icon (string / Component)
Timeline	icon (string)	icon (string / Component)
Tree	icon-class (string)	icon (string / Component)

发布包

Element Plus 的源代码 /packages 已在 npm 发布包删除。如有需要，请自行复制源代码。

安装

导入

Element Plus 的导入路径与 Element UI 不同，请参考如下代码，更多方式请参阅 安装文档。

import ElementPlus from 'element-plus'
import 'element-plus/theme-chalk/index.css'

// 如果您需要引入 SCSS 版本，请使用如下代码（请使用最新版本的 Sass）
// import 'element-plus/theme-chalk/src/index.scss'

全局配置

全局配置 Vue.prototype.$ELEMENT 已删除，请更改为以下方式

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

createApp(App)
  .use(ElementPlus, {
    // 配置项
  })
  .mount('#app')

或使用 config-provider 组件，示例代码如下

<template>
  <el-config-provider :size="small">
    <el-button>按钮</el-button>
  </el-config-provider>
</template>

设计

组件 size 体系由 default / medium / small / mini 切换为更自然的 large / default / small，以 default 为基础，需要加大则选择 large，需要缩小则选择 small。Padding 方面则优化为更通用的 4px 体系，采用 4/8 px 作为原子单位控制整个系统的 padding 一致性。即大组件 padding 也大，小组件 padding 也小。

主要涉及的组件为 Button、Radio、Checkbox、Input、Select、DatePicker、Form 等表单组件和 Table、Tag 等其他有 size 属性的组件。主要涉及属性为 padding 和 margin 属性修改、 font-size 等字体和图标大小修改等。

自定义样式

如您仅使用编译后的 CSS，无变量定制需求，则无需阅读下文。

Sass

Sass 为了实现模块化，使用 @use 替代 @import，@import将在未来几年逐步淘汰它，并最终将其从语言中完全删除。Sass 文档

在 .scss文件中，导入所有样式：

@use 'element-plus/theme-chalk/src/index.scss' as *;

由于 @use存在作用域，在使用变量时需将其导出，或通过 @forward转发变量。

譬如：

@use "'element-plus/theme-chalk/src/common/var.scss'" as *;

'\*' 代表无命名空间，也可以为其命名。

@use "'element-plus/theme-chalk/src/common/var.scss'" as vars;
vars.xxx

通过 @forward 语法转发应用变量：

@forward https://sass-lang.com/documentation/at-rules/forward

变量

• -background-color -> -bg-color
• -font-color -> -text-color

变量名称命名将会与 tailwindcss 中变量命名类似。

各组件的变量使用 @use 'sass:map'; 进行组织，对应组件的变量移动至对应组件名称下。

暴露出的变量请参见 element-plus/theme-chalk/src/common/var.scss。

例如 switch 组件的默认变量为：

$switch: () !default;
$switch: map.merge(
  (
    'on-color': var(--el-color-primary),
    'off-color': var(--el-border-color-base),
    'core-border-radius': 10px,
    'width': 40px,
    'height': 20px,
    'button-size': 16px,
  ),
  $switch
);

用户自定义变量：（将会自动覆盖并合并默认变量）

@forward 'element-plus/theme-chalk/src/common/var.scss' with (
  // 设置主题色
  $colors:
    (
      'primary': (
        'base': green,
      )
    ),
  // 覆盖 switch 组件变量
  $switch: ('height': 40px)
);

更多细节请参阅 自定义主题文档。

国际化

Element Plus 使用英语作为默认语言。如需修改默认语言，请参考 全局配置 小节，设置 locale 属性。

更多细节请参阅 此篇文档。

组件

由于 Vue 3 把 v-model 的属性名从 value 改为 model-value，所以如果您使用了 value 属性，请改为 model-value（v-model 无特殊说明不用修改），后面不再赘述。

Layout 布局

Row 行

类别	旧名称	新名称	描述
属性	type	已删除	仅支持 flex 布局

Dialog 对话框

类别	旧名称	新名称	描述
属性	visible	model-value / v-model	-

Menu 菜单

类别	旧名称	新名称	描述
组件名	ElSubmenu / el-submenu	ElSubMenu / el-sub-menu	-

Popconfirm 气泡确认框

类别	旧名称	新名称	描述
事件	on-confirm	confirm	仅 Element UI 版本低于 2.14.0 时
事件	on-cancel	cancel	仅 Element UI 版本低于 2.14.0 时

Timeline 时间线

类别	旧名称	新名称	描述
属性	reverse	已删除	自行 reverse 数组

Date Picker / Time Picker / DateTime Picker 日期时间选择器

类别	旧名称	新名称	描述
属性	picker-options	已删除	此属性已移至顶层
属性	picker-options.format	已删除	请使用顶层属性 format
属性	picker-options.selectableRange	disabled-hours / disabled-minutes / disabled-seconds	详见文档
属性	first-day-of-week	已删除	请使用 dayjs 的 locale 代替。
属性	default-time	-	仅支持 Date 对象

Tooltip 文字提示

类别	旧名称	新名称	描述
属性	popper-options	-	由于我们已将 popperjs 版本升级为 v2，所以本属性与 v1 完全不同。 请参阅 popperjs 文档。
属性	offset	-	默认值由 0 改为 12
属性	open-delay	show-after	-
属性	close-delay	hide-after	-
属性	hide-after	auto-close	-

Calendar 日历

类别	旧名称	新名称	描述
属性	value	model-value / v-model	仅支持 Date 对象
属性	range	-	仅支持 Date 对象，不必是一周的开始日期或结束日期
属性	first-day-of-week	已删除	请使用 dayjs 的 locale 代替。

Popover 弹出框

类别	旧名称	新名称	描述
属性	open-delay	show-after	-
属性	close-delay	hide-after	-
属性	hide-after	auto-close	-

Scrollbar 滚动条

类别	旧名称	新名称	描述
ref	wrap	wrap$	-

Form 表单

float 布局已经改为 flex 布局。

类别	旧名称	新名称	描述
方法	validate	-	校验失败的情况下，返回一个 reject 的 Promise，不再是 false。

更多关于新功能与不兼容变化的细节，请参阅此文档

模板

以下是快速上手模板，希望能更好地帮助到您。

• element-plus-vite-starter - Element Plus 与 Vite 快速上手模板。
• element-plus-webpack5-starter - Element Plus 与 Webpack 5 快速上手模板。
• element-plus-webpack4-starter - Element Plus 与 Webpack 4 快速上手模板。

[hooray]

dark 模式在这次正式版里还没更新么

[jw-foss]

Dark mode 预计在 2.1 版本会加入，实在抱歉 🙇

[hooray]

Dark mode 预计在 2.1 版本会加入，实在抱歉 🙇

好的，继续期待了

[Sunshop]

The first time support

[aslrz-club]

近段时间看到有个namespace属性，怎么没看到放到全局配置里

[sxzz]

近段时间看到有个namespace属性，怎么没看到放到全局配置里

还没全部做完

[hzm18]

nuxt3有支持计划吗？

[1750911700]

请问@element-plus/icons-vue 里面icon的按需加载有实现么，使用图示方式会报错

[sxzz]

nuxt3有支持计划吗？

nuxt 3 现在还在 beta，目前也没精力

[yangliguo7]

现在 icon 是需要单独作为依赖装载吗?

[baixiaoyu2997]

不兼容还有，datepicker format属性，大小写问题

[devbian]

还在用 webpack 3 的，还有救吗？