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有以下几个特点：

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

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 组件，则可以将 的每次使用重定向到 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