基于 VuePress 2.x 与 ElementPlus 的组件库文档搭建实践

1. 前言

计划使用 VuePress 2.x 结合 ElementPlus 实现一个封装组件库的文档说明网站。本文将详细介绍如何搭建环境、配置项目以及解决过程中遇到的问题。

2. Vuepress项目初始化

2.1 准备工作

创建一个名为 VuePressTest 的项目目录，然后进入该目录并安装依赖：

bash 复制代码

mkdir VuePressTest && cd VuePressTest
npm init -y
npm install -D vuepress@next
npm install

2.2 配置

在项目根目录下的 package.json 文件中添加以下脚本：

json 复制代码

{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  }
}

2.3 示例

在项目根目录下创建 docs/README.md 文件，并添加以下内容：

yaml 复制代码

---
home: true
heroImage: https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/element-index.png
heroText: Element
features:
- title: 一致性 Consistency
  details: 与现实生活一致：与现实生活的流程、逻辑保持一致，遵循用户习惯的语言和概念
- title: 反馈 Feedback
  details: 通过界面样式和交互动效让用户可以清晰的感知自己的操作
- title: 效率 Efficiency
  details: 界面简单直白，让用户快速识别而非回忆，减少用户记忆负担。
footer: by饿了么
---

运行 npm run dev 命令后，效果如下：

3. 使用Element-Plus

3.1 安装

css 复制代码

npm install element-plus --save

3.2 配置

在 .vuepress 目录下创建 clientAppEnhance.ts 文件，引入 ElementPlus：

javascript 复制代码

import { defineClientAppEnhance } from '@vuepress/client'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

export default defineClientAppEnhance(({ app, router, siteData }) => {
    app.use(ElementPlus)
})

3.3 示例

修改 docs/README.md 文件，添加一个 ElementPlus 按钮组件：

yaml 复制代码

---
home: true
---
<el-button type="primary" :icon="Edit">我是Element-Plus</el-button>

运行项目后，效果如下：

3.4 Webpack 下的 .mjs 文件报错处理

当前项目使用 Vite 打包工具可以正常启动，但如果使用 Webpack 打包，运行 npm run dev 时可能会出现与 ElementPlus 相关的报错，错误信息如下：

vbnet 复制代码

(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*. mjs' file, or a '*.js' file where the package. json contains '"type": "module"'). 
The extension in the request is mandatory for it to be fully specified. 
Add the extension to the request.

根据 Webpack 官方文档的解释，需要将 Rule.resolve.fullySpecified 选项设置为 false 来解决这个问题。在 config.ts 文件中添加以下配置：

typescript 复制代码

import { defineUserConfig } from 'vuepress'
import type { DefaultThemeOptions } from 'vuepress'

export default defineUserConfig<DefaultThemeOptions>({
  bundler: '@vuepress/webpack', // 指定使用 Webpack 打包
  bundlerConfig: {
    chainWebpack: (config, isServer, isBuild) => {
      config.module
        .rule('mjs')
        .test(/.m?jsx?$/)
        .resolve.set('fullySpecified', false)
    }
  }
})

3.5 ElementPlus 组件图标显示

在前面的按钮示例中，设置 :icon="Edit" 图标并未生效，这是因为 ElementPlus 的图标需要单独引入。

首先安装图标库：

bash 复制代码

npm install @element-plus/icons-vue

然后修改 .vuepress/clientAppEnhance.ts 文件，注册所有图标组件：

javascript 复制代码

import { defineClientAppEnhance } from '@vuepress/client'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import * as ElIcons from '@element-plus/icons-vue'

export default defineClientAppEnhance(({ app, router, siteData }) => {
  app.use(ElementPlus)
  
  // 全局注册 ElementPlus 图标组件
  Object.keys(ElIcons).forEach(key => {
    app.component(key, ElIcons[key])
  })
})

修改按钮示例，使用已注册的图标：

yaml 复制代码

---
home: true
---

<el-button type="primary" icon="Edit">带图标的按钮</el-button>

添加图标后的效果如下：

4. Markdown 中使用 Vue

如果要对自己封装的组件进行说明，最好能像 ElementPlus 文档那样，既有组件示例，又能查看源码。VuePress 支持在 Markdown 文件中直接使用 Vue 组件。

4.1 自定义组件

在 .vuepress 目录下创建 components 文件夹，然后在其中创建 Test.vue 组件：

xml 复制代码

<template>
  <div class="test-component">
    <h1>在 Markdown 中引入自定义组件</h1>
    <el-button type="success">这是一个 ElementPlus 按钮</el-button>
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    // 组件逻辑
    return {}
  }
})
</script>

<style lang="less" scoped>
.test-component {
  padding: 20px;
  border: 1px solid #eaeaea;
  border-radius: 4px;
  margin: 20px 0;
}
</style>

4.2 自动注册 Vue 组件

安装组件自动注册插件：

css 复制代码

npm i -D @vuepress/plugin-register-components@next

在 config.ts 中配置插件：

typescript 复制代码

import { defineUserConfig } from 'vuepress'
import type { DefaultThemeOptions } from 'vuepress'
import { path } from '@vuepress/utils'

export default defineUserConfig<DefaultThemeOptions>({
  plugins: [
    [
      '@vuepress/register-components',
      {
        componentsDir: path.resolve(__dirname, './components'),
      },
    ],
  ],
})

4.3 基本使用

在 docs/README.md 文件中引入自定义组件：

yaml 复制代码

---
home: true
---

<Test />

引入组件后的效果如下：