📌 Upgrade Changes 升级变化 (2.7.2)

[kooriookami]

To make it easier for users to upgrade Element Plus, this issue will document the upgrade changes from version 2.5.0.

为了更好地方便用户升级 Element Plus，此 issue 将记录从 2.5.0 版本开始的升级变化。

[kooriookami]

2.5.0

2024-01-10

Compatibility 兼容性

Please make sure your browser supports ES2021 and related CSS features such as flex gap.

请确保您的浏览器支持 ES2021 及相关 CSS 特性，如 flex gap 等。

Chrome	Edge	Firefox	Safari
Chrome ≥ 85	Edge ≥ 85	Firefox ≥ 79	Safari ≥ 14.1

select & select-v2 #15352

The default width of components are 100%. Inline forms could cause the components width to be non-adaptive. It is recommended to manually set a fixed width style, for example:

组件默认宽度为100%，行内表单会造成组件宽度无法自适应。建议手动设置固定宽度样式，例如：

.el-form--inline {
  .el-form-item {
    & > .el-input, .el-cascader, .el-select, .el-date-editor, .el-autocomplete {
      width: 240px;
    }
  }
}

[kooriookami]

2.5.4

2024-02-02

tabs #15733

The addIcon slot was changed to add-icon.

addIcon 插槽改为 add-icon。

[kooriookami]

2.6.0

2024-03-01

checkbox & radio #15525

Distinguish between label and value in Group mode (compatible with label only usage). label is used as display text only, value is used as option value.

true-label and false-label are replaced with true-value and false-value in checkbox.

区分 Group 模式下 label 与 value 的作用（兼容只使用 label 的用法）。label 仅作为显示文本，value 作为选项值。

checkbox 中 true-label 与 false-label 替换为 true-value 与 false-value。

select & select-v2 #15995

When there is an empty string value in options, the empty string will be matched, otherwise it will not be matched.

In single select mode, clear select returns undefined, consistent with select-v2.

当 options 中存在 value 为空字符串的情况，会匹配空字符串，否则不匹配。

单选模式下清空 select 会返回 undefined，和 select-v2 一致。

button #16002

Remove focus styles.

移除 focus 样式。

[kooriookami]

2.7.0

2024-04-12

empty-values & value-on-clear #16361

In order to support custom clear value and conditions for determining the empty value, two props are added.

empty-values is an array of empty value judgments, the default value is ['', undefined, null]. If you think the empty string is meaningful, write [undefined, null].

value-on-clear is the clear return value, the default value is undefined. In the date component is null. If you want to set undefined, use () => undefined.

为了支持自定义清空值和确定空值的条件，添加了两个参数。

empty-values 为空值判断数组，默认值为 ['', undefined, null]。如果你认为空字符串是有意义的，请写作 [undefined, null]。

value-on-clear 为清空返回值，默认值为 undefined。日期组件中为 null。如果你想设置 undefined，请使用 () => undefined。

Support empty-values and value-on-clear props components list:

支持 empty-values 和 value-on-clear 参数的组件列表：

• cascader
• config-provider
• date-picker
• select
• select-v2
• time-picker
• time-select
• tree-select

Demo

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

Deprecate the dynamic recognition of empty string usage of #15995, as it is not possible to determine if an empty string exists by options in a remote search. Please use empty-values instead.

废弃 #15995 动态识别空字符串的用法，因为在远程搜索中，无法通过选项判断是否存在空字符串。请使用 empty-values 替代。

[kooriookami]

2.7.2

2024-04-26

aria #16598

label prop was changed to aria-label in a11y.

A11y 中的 label 参数改为 aria-label。

Changed components List:

改动组件列表：

• autocomplete
• checkbox-group
• color-picker
• input-number
• input
• radio
• rate
• slider
• switch
• time-picker

The controls prop was changed to aria-controls in checkbox.

checkbox 的 controls 参数改为 aria-controls。