1. 首页
  2. IT资讯

如何开发一个基于 Vue 的 ui 组件库(二)

遗留问题

书接上回,说道利用 sideEffects 字段,只需读取源文件即可实现按需加载,还有个坑忘了说…

文档中的样式打包后会丢失…

因为我们只注意到了作为组件库的源代码,而忘了我们的文档是通过 vuepress 编译,即底层也是基于 webpack 进行打包。所以 sideEffects 中也要加上文档中的文件。

组件文档该写些什么?

在编写组件库文档时,有两个必不可少的部分。

  • 组件预览,最好有相应的代码
  • 组件 api,即 props、events、slots 等接口和参数的说明

如何同时展示 demo 和 code?

  • 最【一力降十会】的方法当然就是复制粘贴一把梭…
如何开发一个基于 Vue 的 ui 组件库(二)

这样实现简单是简单,不过维护时要同时改至少两份代码。比如 vant 的展示文档 和 cube-ui 的展示文档。

  • 进阶一点儿的方法就是嵌入 CodepenJSFiddleCodeSandboxiframe

但是组件库中一般有大量的组件,不可能为每个组件都维护一份小代码片段,并且别忘了这可是三个平台(硬点一个吼不吼啊~?)。

  • 因此各种组件库使用的最多的方法还是自己编写组件。(下一小节详解)
  • 当然也有例外比如 vux 只有 demo 没有 code。

业界的文档组件

  • 最普遍的方式还是基于 markdown-it,将自己的 vue 组件插入文档中。
  • muse-ui 的 demo-block 组件
  • muse-ui 的 markdown-it 配置
  • ant-design-vue 的 demoBox 组件
  • ant-design-vue 的 markdown-it 配置
  • element 的 demo-Block 组件
  • element 的 markdown-it 配置
  • 比较有意思的是 mand-mobile 的文档编写方式。demo 的文档放在组件目录中,然后由 Doc 组件读取各个组件的 demo。
  • mand-mobile 的展示文档
  • mand-mobile 的 Doc 组件
  • 那么对于我们使用 vuepress 编写文档的开发者来说咋办咧?

在 vuepress 中展示 demo 和 code

首先让我们来分析一下:这两份重复的代码应该以谁为主?即我们应该只编写 demo 的代码还是 code 的代码?先有鸡还是先有蛋?物质决定意识还是意识决定物质?

至少在编写 demo 和 code 这个问题中,我认为 demo 才是“本源”,为什么?

  • 这是最普遍的方式,各大组件库基本这么干
  • 这是最自然的方式,因为 vuepress 会编译 md 中的 vue 组件
  • 若是反过来,文档中以 code 为主,再由 code 生成 demo 会有一些不便
  • 如何预处理代码:babel、scss 等?
  • 如何插入生成的组件到文档中?
  • 感兴趣的话可以看看这个插件 vuepress-plugin-demo-block

一开始我只在 .vuepress/components/ 中建了个组件自娱自乐,后来看到了 vuepress-plugin-demo-block,但觉得由 code 生成 demo 有点儿绕。

于是自己搞了个插件 vuepress-plugin-demo-code,有需要的读者老爷可以自取~

组件的 api 文档

解决了 demo 和 code 的重复编写问题,接下来是另一个令人无发可脱的问题:如何自动生成并同步 .vue 组件的 api 文档?

手动维护肯定是不行的,还好有一个炒鸡好用的库 vuese。vuese 会基于 ast 分析你的 .vue 文件,提取其中的 props、events、slots 等接口和参数的说明。

为了将其集成到 vuepress 中,我又整了个 markdown-it 插件 markdown-it-vuese。

只需使用以下的语法在导入已经存在的 *.vue 文件的同时,使用 Vuese 自动生成文档。

<[vuese](@/filePath)

以上 to be continued…

参考资料

  • muse-ui 的 demo-block 组件
  • muse-ui 的 markdown-it 配置
  • ant-design-vue 的 demoBox 组件
  • ant-design-vue 的 markdown-it 配置
  • element 的 demo-Block 组件
  • element 的 markdown-it 配置
  • vux 的展示文档
  • vant 的展示文档
  • cube-ui 的展示文档
  • mand-mobile 的展示文档
  • mand-mobile 的 Doc 组件
  • vuepress-plugin-demo-code
  • vuepress-plugin-demo-block
  • vuese
  • markdown-it-vuese

原文始发于:如何开发一个基于 Vue 的 ui 组件库(二)

主题测试文章,只做测试使用。发布者:酒颂,转转请注明出处:http://www.cxybcw.com/25890.html

联系我们

13687733322

在线咨询:点击这里给我发消息

邮件:1877088071@qq.com

工作时间:周一至周五,9:30-18:30,节假日休息

QR code