Element Plus@1.0更新至@2.x的一些破坏性改动

林元明

2023-12-01

前言

Element Plus官方迁移指南

中间版本的更新策略：
element-plus 代码仓库，discussion 中查询"Breaking Change"，可以查看迁移必备的更改，例如：

Breaking changes made in 1.1.0-beta.1

1.2.0-beta.1 Breaking Change

1.3.0-beta.1 Breaking Change

Element Plus Breaking Changes

其它非破坏性改动，可参照更新日志或者官方文档。具体改动可通过id在git中查看，例如：

https://github.com/element-plus/element-plus/4554

以下改动为 @1.0.2-beta.42 迁移至 @2.2.5 ，个人总结的部分改动，以供参考

一、size

>= @1.3.0-beta.1

css property	large	default	small
height	40px	32px	24px
font-size	14px	14px	12px
padding - button	12px 19px	8px 15px	5px 11px
padding - input	1px 15px	1px 11px	1px 7px

< @1.3.0-beta.1

css property	large	medium	small	mini
height	40	36	32	28
font-size	14	14	12	12
padding	12 20	10 20	9 15	7 15

最简单的策略：

mini -> small
medium,small -> default
large -> large

二、dayjs

大概是在 @1.1.0 左右，无法直接使用 dayjs，需要引入，再使用。甚至某些中间版本需要额外安装 dayjs

可以在main.js中定义全局变量

import dayjs from 'dayjs'

app.config.globalProperties.$dayjs = dayjs

三、icon

1、安装依赖

yarn add @element-plus/icons-vue

2、引入

2.1、引入全部图标

import * as ElementPlusIconsVue from '@element-plus/icons-vue'

// for comp usage
for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
  app.component(key, component)
}

使用
component：

<el-icon><Plus /></el-icon>

string：

<script setup>
import { Edit } from '@element-plus/icons-vue'
</script>
<template>
	<el-button :icon="Edit" circle />
</template>

2.2、手动按需引入

引入的图标不多的话，可以选择手动引入所需图标

import { Edit, View, Delete, Plus, UploadFilled, Remove, ZoomIn } from '@element-plus/icons-vue'

// for component usage
for(const [key, comp] of Object.entries({ UploadFilled, Plus, Remove, ZoomIn })) {
  app.component(key, comp)
}

// for string usage
app.config.globalProperties.$epIcons = {
  Edit, View, Delete, DeleteFilled, Plus
}

使用：
component：

<el-icon><Plus /></el-icon>

string：

<el-button :icon="$epIcons.Edit" />

四、表单验证

element-plus@2.0.6及之后的版本，表单验证不再是同步执行的了在线示例
另外，element-plus@2.1.4及之后的版本，才可按照官方文档示例正常使用

const submitForm = async (formEl: FormInstance | undefined) => {
  if (!formEl) return
  await formEl.validate((valid, fields) => {
    if (valid) {
      console.log('submit!') // 位置1
    } else {
      console.log('error submit!', fields)
    }
  })
  // 位置2
}

上例中：
如果在“位置1”执行表单验证通过后的业务代码，可以去掉 async…await
如果在“位置2”执行，则需加上。否则，会直接跳过验证

这样，与异步校验的写法就一致了。element-plus@2.1.4及之后的推荐统一使用上例中的写法

五、国际化

Element Plus新版本提供了一个 Vue 组件 ConfigProvider 用于全局配置国际化的设置，具体参照官网。

六、其它

除了上述较大的改动，随着版本的更新，会有些琐碎的改动，需要自行注意

一下记录个人遇到的琐碎改动

el-input .el-input__inner 外多包了一层 .el-input__wrapper
el-upload 样式
el-dialog custom-class属性弃用

使用class取代即可

el-table fixed/scroll th设置了背景色#ffffff

如果设置了表头的颜色的话，表格可左右滚动时，固定项背景色可能不会被覆盖

.el-table th.el-table__cell,
.el-table__header-wrapper tr th.el-table-fixed-column--left,
.el-table__header-wrapper tr th.el-table-fixed-column--right,
.el-table.is-scrolling-left th.el-table-fixed-column--left,
.el-table.is-scrolling-right th.el-table-fixed-column--right {background-color:#d7e5fa}