💥 1.2.0-beta.1 Breaking Change

[jw-foss]

1.2.0-beta.1 带来的破坏性变动 | Breaking change introduced in 1.2.0-beta.1

• 移除 FontIcon | Deprecation of FontIcon epic: deprecation of icon font #3492
• 发布包的内容变化 | Release bundle breaking changes build!: simplify build & support esm import #4018
• 兼容性变化 | Compatibility breaking changes refactor(utils)!: remove resize-observer-polyfill #4058 fix(build): transform to es2018 syntax #4090

Shoutouts

• 感谢 @adaex @imswk @bastarder 完成 epic: deprecation of icon font #3492 | Shoutout to @adaex @imswk @bastarder for making epic: deprecation of icon font #3492
• 感谢 @sxzz 完成 build!: simplify build & support esm import #4018 | Shoutout to @sxzz for making build!: simplify build & support esm import #4018
• 感谢 @sxzz 完成 refactor(utils)!: remove resize-observer-polyfill #4058 | Shoutout to @sxzz for making refactor(utils)!: remove resize-observer-polyfill #4058 fix(build): transform to es2018 syntax #4090

为什么带来这些变动 | Breaking change explained.

移除 FontIcon | Deprecation of FontIcon

从 ElementUI 2.x 以来，Element 都在使用 FontIcon 作为组件内图标的展示，但这带来诸多问题：

• 体积问题 | bundle sizes
• 性能问题 | performance
• 可访问性 | a11y
• 可扩展性 | scalability
• 更多 | much more

体积问题 | bundle sizes

为了使用 Element Plus 内置的图标，用户往往需要引用一个 ~75KB 的字体文件，以及 1 个额外的网络请求，这个在大多数情况下属于完全不需要的开销，对体积以及首页加载速度很在意的用户来说，这属于是一个长久的痛点。

For using Element Plus built-in icons, users will need to import a font file ~75KB, in addition to 1 external network request, under most circumstances this is not necessary, for those who cares about the first screen loading and the bundle size this is a long existed pain point.

我们可以通过这个表格来查看这次的变化带来的体积减小程度 | We can know how much size reduction we have in this change

文件名 file name	改动前大小 before change	改动后大小 after change	大小差距 size diff
index.full.min.js	691 KB	718 KB	+ 27 KB
element-icons.ttf	50 KB	-	- 50 KB
element-icons.woff	25 KB	-	- 25 KB
总计 total	766 KB	718 KB	- 48 KB

性能问题 | performance

由于这次的改动，所有的 Font Icon 都被改为了 Inline Vue SVG 组件，也就是说所有的组件都是跟随你的打包代码一起放在同一个请求内，所以不会产生额外的网络请求去请求字体文件。所以也不会带来网络请求失败导致字体渲染不出来的小方块。

Per this change, all Font Icon was replaced with Inline Vue SVG component, meaning that all the SVG icons will be bundled into your code, it will not require an extra network request for the font file, which can avoid being not able to render the icon due to network failure.

可访问性 | a11y

SVG icon 对于 Font Icon 的一个最大的优势就是可访问性。SVG 元素是由语义化的 HTML 元素组成，比如 <title> 和 ，以便于 screenreader 和文字浏览器来访问和使用。与 Font Icon 不一样的点是，浏览器以处理图片的方式处理 SVG，而不是文字。并且 SVG 还与 WAI-ARIA 定义的可访问性属性兼容 - aria-labelledby

One major advantage of SVG icons over Icon fonts is their superior accessibility. SVGs are armed with built in semantic elements – like <title> and that makes it accessible to screen reader and text browsers. Unlike icon fonts, SVGs are treated as an image and not as a text. Moreover SVG is compatible with WAI-ARIA specifications – aria-labelledby attribute.

Copyright to https://www.lambdatest.com/blog/its-2019-lets-end-the-debate-on-icon-fonts-vs-svg-icons/

可扩展性 | scalability

在这次的改动前，对于 Element Plus 里带有图标的组件而言，如果用户想自定义图标，那么便需要用户通过设置一个如 icon-class 的属性来提供一个对应的字体类名来设置，如：el-icon-edit，对于那些不想要使用 Element Plus 自带图标的同学，将需要再额外引入一个字体文件，这将会带来额外的开销，对于很多用户来说这都是很不必要的。

Before this change, for those components with icons, if user wants to put another icon into the component, it will require the user to set the attribute like icon-class to give it a name represent the co-responding icon such as: el-icon-edit, for those who doesn't want the built-in icons, they will be needed to import an extra Font Icon file which is unnecessary.

在这次改动后，用户可以通过提供一个 Vue 组件的方式来为组件传递一个自己想要的图标，这大大的提高了组件的可扩展性，并且你还可以通过 Vue 组件为你的图标提供各种操作空间。如：

After this change, you can pass down a Vue component for getting one of your desired icon, it dramatically increased the scalability for all components with icons, you can also apply actions to your Vue component, for example:

<template>
  <el-button :icon="MyIcon">
  </el-button>
</template>
<script setup>
import { MyIcon } from 'some/icon/lib'
</script>

对于哪些 API 的变化请看下面的表格

You can checkout the table below to know the API changes

组件名 Component Name	改变前的 API 名字 API before change	改变后的 API 名字 API after change
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)
VirtualizedSelect	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)

旧版字体文件 ｜ Backup icon font file

您可以在这里下载旧版本的字体文件来让老项目保持兼容 Download backup icon font file here.

https://unpkg.com/element-plus@1.1.0-beta.24/theme-chalk/base.css
https://unpkg.com/browse/element-plus@1.1.0-beta.24/theme-chalk/fonts/

发布包内容变化 | Release bundle breaking changes

发布包的内容变化可以在 #4018 (comment) 查看

You can checkout the changes for releasing bundle changes at: #4018 (comment)

兼容性变化 | Compatibility breaking changes

兼容性变化可以在 #4058 (comment) 查看

You can checkout the changes for compatibility changes at: #4058 (comment)

下一步 | Next step

相信很多人都在吐槽为什么 Element Plus 的中文文档做的这么差，诸如此类的。我们已经完善了中文文档的内容。如有翻译问题各位也可以通过 Crowdin 向我们贡献文档内容，我们的目标从来就只有把 Element Plus 做得更加好用，感谢大家一直的支持以及耐心 🙏

[SonicMiso]

请问使用el-icon 如何动态加载图标？

[sxzz]

/cc @adaex @JeremyWuuuuu

[adaex]

@LeonTheProfessional 你可以使用图标组件名称的方式来注册组件，这样直接使用这个名字就可以加载图标了，例如：

<template>
  <el-icon><component is="icon-arrow-left" /></el-icon>
  <el-icon><component is="icon-arrow-right" /></el-icon>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
import { ArrowLeft, ArrowRight } from '@element-plus/icons'

export default defineComponent({
  components: {
    'icon-arrow-left': ArrowLeft,
    'icon-arrow-right': ArrowRight,
  },
})
</script>

也可以采用全局注册的方式，这样在任何页面中都可以使用你已经注册的图标名称:

import { ArrowLeft, ArrowRight } from '@element-plus/icons'

app.component('icon-arrow-left', ArrowLeft)
app.component('icon-arrow-right', ArrowRight)

更多技术细节可以参考: https://v3.cn.vuejs.org/guide/component-registration.html

[SonicMiso]

@adaex 首先谢谢你的解答。事实上，问题点在于，除了必然是element-plus 图标库的图标外，我事先并不可知需要用到哪些图标，所以第一种方案并不适用我的情况;第二种方案的问题在于并没有实现按需加载。
我真正想要的是类似于

  <el-menu-item
          :index="theOrphan.url"
          :class="{'submenu-title-noDropdown': isFirstLevel}"
        >
          <svg-icon
            v-if="menu.iconName"
            color="white"
            :data="require(`@icon/${menu.iconName}.svg`)"
          />
          <template #title>
            <span
              v-if="theOrphan.subMenuTtl"
            >{{ theOrphan.subMenuTtl }}</span>
          </template>
        </el-menu-item>

这种实现方式（以上是第三方库实现），也就是使用动态import的方式加载图标。

[emojiiii]

因为element-plus是基于组件的形式去开发了icon，在打包时就需要分析依赖了
或许element-plus应该把svg都提供在一个网络地址里面，再提供一个组件，通过url去使用网络地址里面的SVG ? @LeonTheProfessional

[SonicMiso]

@undefined-degisn icon存在服务器也可以动态加载啊，不一定要element-plus提供。

我刚刚已经通过vue的异步组件实现了，但也是当黑盒子用的，请经验者指教：

        <el-menu-item
          :index="theOrphan.url"
          :class="{'submenu-title-noDropdown': isFirstLevel}"
        >
<!--          <svg-icon-->
<!--            v-if="menu.iconName"-->
<!--            color="white"-->
<!--            :data="require(`@icon/${menu.iconName}.svg`)"-->
<!--          />-->
          <el-icon>
            <component :is="importIcon('CirclePlus')" />
          </el-icon>
          <template #title>
            <span
              v-if="theOrphan.subMenuTtl"
            >{{ theOrphan.subMenuTtl }}</span>
          </template>
        </el-menu-item>

  //异步加载Icon
     importIcon(name: string):any {
      return defineAsyncComponent(() => import('@element-plus/icons').then((module) => module[name]));
    },

看了一下请求，貌似也是直接从服务器把icon全要过来了（1M多的js文件），也没实现按需加载...

要是能直接import('@element-plus/icons/CirclePlus.vue')就好了

[LearnShare]

不太清楚为何开发团队会做出这样的决定，但这种破坏性改动的影响太大。
以我的项目为例，升级需要的改动有 74 个文件（160 处代码）。

同样存在 @LeonTheProfessional 提到的场景，对于按名称匹配的图标，按需自动加载不太行。

---

如果可能的话，我会推荐 SVG Sprites 这种方案。简要概括如下：

1. 每个图标保存为单独的文件，如 user.svg
2. 利用 svg-sprite-generator 等工具将多个图标合并为一个文件，如 icons.svg
3. 按名称匹配和使用图标

   <svg>
       <use xlink:href="path/to/icons.svg#user"></use>
   </svg>

4. 开发模式下可以引用包含所有图标的 icons.svg；编译发布时可选择按需重新编译，或者引入完整的 icons.svg

[darknesstm]

element plus基本是在内网环境下使用，对体积的敏感度不高吧…… 还不如利用浏览器缓存，单独的静态资源不更好么？

[linjiahao962889027]

正常的开发不应该是兼容的吗？为什么把font-icon给去除了，限制我所有组件的icon都不显示了，气死我了，我还不知道怎么修改。

[iamkun]

You can check the "旧版字体文件 ｜ Backup icon font file" section above, to download the archived font-icon file.

[oliverzy]

对于这个改动我是很欢迎的，Font Icon的扩展性确实不好，且显示不够锐利。对于上面有同学不理解，还是要自己看升级文档啊。
Element Plus是面向未来的组件库，毕竟现在也是beta阶段，有些Breaking Change是无可厚非的啊

[CaiWenlie]

75kb就痛点了。。。到现在还没有稳定版不算痛点吗，大问题不解决去搞小问题？

[jw-foss]

不积跬步无以至千里，我希望老祖宗的智慧你也能继承一点。 ;D

[CaiWenlie]

啊对对对，你爱咋改咋改吧，老祖宗十年才磨一剑，你这才几年呢对吧

[tracker1999]

感觉这不是Breaking Change是Destroy Change

[lingyuwai]

75KB。。。。 还是基于element-ui源码魔改element-plus中的组件吧