组件库——如何实现一个跨框架的组件库文档？

站长

2023年09月05日 23:29 · 阅读数 14

要搞一个跨框架的组件库文档怎么下手？最近笔者在建设公司内部的组件库，其中就需要为vue2、vue3、react技术栈的中台系统提供基础组件以接入。于是，一个跨框架组件库文档的需求就来了...

补充在线演示地址：组件库最终版本在线演示地址（已剥离公司、项目相关信息，与文中截图、代码演示可能有所差异，望理解）。详细了解可看笔者其余两篇文章～

源码了解

git仓库地址

背景介绍

需求背景概述：

内部需要做一个云产品以统一各种中后台系统（类似阿里云）。有一定的样式、布局规范，还有一些基于ui框架扩展的统一的基础组件。so，笔者需要做的就是做一个组件库，分别实现element-ui、element-plus、ant-design组件的二次封装，并提供组件库文档给到使用方接入。

本文主旨：

围绕 组件库文档 进行展开。组件库文档并不是自研，笔者采用的是 vitepress 来快速搭建静态组件文档站点，所以本文的一些技术攻坚也只针对于 vitepress 场景～
实现在 vitepress 中使用 vue2 + element-ui 组件、 react+antd组件。react 还是没做哈哈哈，不过实现思路跟 vue2 是一样的。
实现文档内各组件样式隔离。因为要把各框架的组件都放在 vitepress 的单页应用中（粗略看了下目前不支持multiple page：issues），这样依赖不可避免的就会出现 css 冲突，跟微前端的场景有点类似。

一、组件库开发思路

虽然跟本文主旨没太大关系，但是笔者觉得还是得提一下，这样可以更好的开展后续内容。

组件库开发流程图：组件库——如何实现一个跨框架的组件库文档？简单说明：

组件开发。组件库组件库，组件开发当然是核心！所以第一步就是开发组件。
组件demo。怎么理解demo？组件可能有很多不同的使用场景，不同的配置，demo就是罗列各种使用场景、配置，以此来演示如何使用组件。（好比button组件，传不同的type有不同的表现形式）
组件文档。文档就是最后一步了，把我们的组件demo放上去，把demo源码、各种配置、事件等进行罗列说明～

简单看看其中一个组件库的项目结构：组件库——如何实现一个跨框架的组件库文档？

所以整个组件库的开发，会涉及组件开发、组件demo开发、组件文档编写三大步骤！

二、`vitepress` 使用 `vue2` 组件

有用过 vitepress 的都知道，其是支持在 markdown 里直接写 vue3 代码的。这样我们可以在写文档之时直接写组件demo代码，非常的方便。但是，其只支持vue3。如果用 vitepress 作为组件库文档工具且需要呈现其他框架的组件，就需要适配一层了。（有句话说得好啊：没什么是加中间层解决不了的，一层不行就两层🤣）

1. 实现方案

开工之前，先大概了解下 markdown 中可直接用 vue3 的原理。文档地址组件库——如何实现一个跨框架的组件库文档？根据介绍，md文件最终编译成vue3的组件形式。从大体上看，vitepress 其实就是一个 vue3 + vite 的ssr应用，我们可以简单理解成 md文件 即是 .vue 文件。我们可以在里面写html、写vue3组件、写script、写style，灵活度非常高。

再看看尤大对其中一个关于vitepress使用vue2组件的issues的回答：组件库——如何实现一个跨框架的组件库文档？

这样一来，思路就很清晰了，方案也就更加确定了。我们可以包一层vue3，但更直接一点的是直接在vue3中挂载vue2的组件。这样也能达到一样的效果，而笔者采用的是后者。

思路步骤大致分为：

vue2组件产物。打包编写好的 vue2组件demo，最后得到的产物就是其对应的组件对象。
组件实例化。通过我们最熟悉的vue2实例化：new Vue(组件对象)，得到一个组件实例。
挂载dom。在 md 文件中提供一个 dom节点 进行挂载。

2、3串起来其实就是我们vue2项目中，在main.js里面挂载应用根节点那样～

new Vue(App).$mount('#app')
// 或者
new Vue({
  el: '#app',
  render: (h) => h(App),
})

2. 可行性分析

这里大致讲下整个实现思路的可行性，以便清晰的理解这个方案的实现。

进入讲解前，笔者先抛个问题，大家可以先想想：

vue同学看这里：从 .vue文件 到 页面渲染 的流程（经历了什么）？
react同学看这里：从 jsx 到 页面渲染 的流程（经历了什么）？

笔者作为一位 react 小菜鸡，就不在这里班门弄斧了～这里仅对 vue 的问题进行分析讲解！react大牛快来指点指点笔者react～（虽然主讲vue，从大体来看，两个框架从..到渲染流程多多少少有点相似，所以react也可以沿用vue2的思路的）

明确组件对象产物。就是 .vue 编译的产物。比如我们写的 .vue 文件如下

<template>
  <div>hello world</div>
</template>
<script>
export default {
  name: '组件名',
  data () { return {} },
  created () {}
  ...
}
</script>

编译后的产物大概是（也就是笔者说的组件对象）：

export defualt{
  name: '组件名',
  data () { return {} },
  created () {},
  render: () => h('div', 'hello world')
}

从 new Vue 到渲染：

也就是 new Vue(组件对象).$mount('#app') 的流程
- init。各种初始化、响应式数据、computed等的初始化
- $mount。开启挂载的全流程
- render。一定要明确，所有组件都有render函数，执行render的结果就是返回VNode
- patch。根据VNode，调用浏览器的各种api（如createElement等）创建真实的dom，挂载到我们提供的挂载节点上（这里省略diff的过程）

组件化流程（笔者之前一篇文章的图）：组件库——如何实现一个跨框架的组件库文档？这里大家可以不用特别关注，感兴趣的可以顺便了解下。如图，跟第一张图的区别就是多了个 “循环” 的过程。因为我们的应用都不会只有一个组件，应用最终的成型就是一颗组件树。Vue应用就是不断递归（图1）组件化的流程，整个应用就实现了对dom树的形成和挂载了。

讲到这里，大家很容易能想到，把 Vue2组件 挂载到 vitepress 的 Vue3应用 里，其实只要对上述流程进行一定的剥离就可以实现了。换句话说，Vue3应用什么都不用管，只需要提供一个节点，而我们把已经实例化的Vue2组件实例进行挂载即可。