Vue组件自动引入插件——unplugin-vue-components 快速接入教程

1. 简介

unplugin-vue-components是一款功能十分强大的插件，旨在简化组件的自动导入和使用，可以帮助我们在Vue项目中自动导入并注册我们使用的任何Vue组件，从而提高开发效率。

unplugin-vue-components使用Rollup API作为各种bundler/ebuild`工具API的抽象层，将Rollup风格的构建hooks和调用函数转换为与目标构建打包工具兼容的形式。这意味着一个插件（或称为unplugin）可以在Rollup、webpack 和 Vite 等多种打包工具之间通用，而无需为新的构建工具进行移植。

unplugin-vue-components采用unplugin，它几乎可以在任何地方使用，我们可以无需进行大量重写就能轻松地将其引入到项目中。

unplugin-vue-components有以下几个特点：

自动导入：当我们在模板中使用组件时，插件会自动找到并导入相应的组件，无需手动导入。
按需加载：支持按需加载，只导入实际使用的组件，减少打包体积。
支持多种组件库：可以与多种流行的 Vue 组件库（如 Element Plus、Ant Design Vue 等）兼容使用。
自定义配置：允许开发者根据项目需求进行自定义配置。

2. unplugin-vue-components 和全局注册有什么不同？

与全局注册不同的是，unplugin-vue-components可以静态分析我们的代码，在组件管理方面显得更加智能。全局注册会在bundler输出中会强制包含已注册的组件，无论这个组件是否被使用。这可能会显著增加最终代码的大小，从而降低性能。但是，unplugin-vue-components会分析我们的代码以查看组件的使用位置，从而使tree shaking和代码拆分更加合理有效。此外，unplugin-vue-components不需要我们手动注册每个组件，我们只需要指定components文件夹（如果我们使用的是src/components，则不需要指定）。

unplugin-vue-components还具有其它功能更强大的配置，我们可以借助它执行集成TypeScript类型、创建自定义函数以将组件重定向到特定库以及创建全局转换函数等操作，稍后在文中可以看到。

接下来我们正式开始使用它。

3. 创建一个Vue项目

首先，我们需要创建一个新的Vue项目，这个示例中我们使用Vite（node版本^18.0.0 || >=20.0.0）来创建：

yarn create vite my-vue-app --template vue

创建完成后启动项目：

cd my-vue-app
yarn
yarn dev

我们现在快速创建了一个最基础的Vue项目。

4. 引入unplugin-vue-components

创建好项目后，我们在项目中安装unplugin-vue-components：

npm i -D unplugin-vue-components

接下来，我们需要在vite.config.js配置文件中添加unplugin-vue-components。

import Components from 'unplugin-vue-components/vite'
export default defineConfig({
  // ...其它配置
  plugins: [
    Components({ /* 配置项 */}) 
  ]
})

在前言中我们讲过，unplugin-vue-components也支持webpack，所以如果我们使用的是webpack，我们需要在webpack.config.js中这样配置：

module.exports = {
  // ...其它配置
  plugins: [
    require('unplugin-vue-components/webpack')({ /* 配置项 */ })
  ]
}

默认情况下，我们是将组件放在src/components目录中，但是如果我们没有将组件放在这个目录下，我们需要配置一个新的路径。在unplugin-vue-components插件中提供了dirs参数来实现新路径配置，该参数是传值是一个数组类型：

import Components from 'unplugin-vue-components/vite'

export default defineConfig(
  plugins: [
    Components({dirs: ["src/example/dir/here", "other/example"]})
  ]
})

现在，我们就在项目中快速引入了unplugin-vue-components插件，我们可以删除项目中App.vue顶部的HelloWorld组件导入代码来测试一下插件是否生效。

5. 迁移到unplugin-vue-components

如果我们想要在现有项目中添加unplugin-vue-components插件，也只需要按照上面的步骤进行安装，然后在我们现有的bundler配置文件中正确的添加插件配置（因bundler而异）。

如果项目中的组件目录不是src/components路径，我们一样要在配置中添加dirs配置项，这步必不可少：

{
  dirs: ["src/example/dir/here","other/example"]
}

做完之后，我们就可以删除 import 和 register 语句了。

我们也可以选择逐渐删除导入语句，不用担心unplugin-vue-components会与现有语句冲突。

6. 和UI库搭配使用

在项目中，我们也会使用到各种UI组件库，但是默认情况下是无法从自动导入和注册UI库组件的，我们需要通过配置resolvers来实现自动导入。unplugin-vue-components插件中Resolvers 是根据组件名称将组件定向到特定包的函数，举个例子，如果我们使用Ant Design 中 Dropdown 组件，则可以将<Dropdown>的每次使用重定向到AntD中的Dropdown。

对于许多流行的UI库，unplugin-vue-components包括一个内置的解析器，你可以通过导入并传递给resolvers的config属性来使用它：

import Components from 'unplugin-vue-components/vite'
import { AntDesignVueResolver } from 'unplugin-vue-components/resolvers'

Components({
  resolvers: [
    AntDesignVueResolver(),
  ],
})

但是，如果没有内置的resolver怎么办呢？没事，我们也可以创建自定义的resolver，resolver本质上就是是采用指定组件名称的字符串并返回实际组件名称和包名称的函数。下面就是一个自定义resolver的示例，它将重定向以Example开头的任何组件的所有用法，并将它们重定向到example-package，并删除Example前缀：

Components({
  resolvers: [
    (componentName) => {
      if (componentName.startsWith("Example")) {
        return { name: componentName.slice(6), from: "example-package" };
      }
    },
  ],
});

我们也可以使用 resolver 函数做很多更高级的配置。例如，如果我们只想匹配 example-package 中的某些组件，我们可以添加一个数组来匹配来数组内的组件：

const ExampleElements = ["Dropdown", "Button", "Card"]; 

Components({
  resolvers: [
    (componentName) => {
      if (
        componentName.startsWith("Example") &&
        ExampleElements.includes(componentName.splice(6)) 
      ) {
        return { name: componentName.slice(6), from: "example-package" };
      }
    },
  ],
});

7. 配合TypeScript使用

如何在Vue的ts项目中使用unplugin-vue-components插件呢？我们只需要将components.d.ts添加到我们的tsconfig.js包含列表中。components.d.ts 是包含所有类型的文件，如果你不告诉 TypeScript 包含它，它不会做任何事情。

在大多数情况下，只要安装了unplugin-vue-components插件，就可以生效了。但是，如果你使用的库已经全局注册了组件并且不提供类型文件，unplugin-vue-components 也可以提供了解决方法。我们只要把非 unplugin-vue-components 导入的组件的类型添加到配置中即可。例如，如果你希望unplugin-vue-components包含来自example-package的ExampleComponentOne和ExampleComponentTwo的类型，你可以将配置更改为如下：

Components({
  dts: true, // 默认为true，自动启用
  types: [{
    from: 'example-package',
    names: ['ExampleComponentOne', 'ExampleComponentTwo'],
  }],
})

现在我们就获得了与使用unplugin-vue-components的任何其他组件相同的类型支持。

8. 自动导入JavaScript和其他非Vue文件

unplugin-vue-components插件默认不支持导入其他文件。但是，我们可以使用另一个unplugin工具来实现此功能：unplugin-auto-import。unplugin-auto-import允许我们无需导入JavaScript函数就能使用它们，虽然它比 unplugin-vue-components配置稍微复杂一些，但它的使用一样简单。

首先，我们需要安装unplugin-auto-import并将其添加到bundler的配置文件中。然后，我们需要在include属性中添加正则表达式来指定要包含的文件。其次，我们需要将预设和自定义包配置添加到imports属性上：

AutoImport({
  // 转换的目标文件
  include: [
    /\.[tj]sx?$/, // match .ts, .tsx, .js, .jsx
  ],
  // imports to include
  imports: [
    "example-preset", // 某些包unplugin-auto-import包含一个预设，我们可以这样使用
    {
      "example-package": [
        "namedImport", // 声明命名导入的方式
        ["alisedImport", "exampleAlias"], // Imports 别名。使用example-package中的函数aliasedImport并将其别名为 exampleAlias
        ["default", "exampleDefault"], // 使用default作为名称来获取default导出.
      ],
    },
  ],
  // auto-import 使用的本地目录.
  dirs: ["./src/assets/scripts"],
});

更多信息，可以参考unplugin-auto-import 使用文档.

9. 小结

在本文中，我们探讨了如何通过使用 unplugin-vue-components 和 unplugin-auto-import 等插件工具自动导入 Vue 组件来减少代码量，提高开发效率。建议大家在你的实际项目中实现这些工具，相信一定能从中有所收益。

原文：https://juejin.cn/post/7423420457657237567