diff --git a/drafts/018.how-to-build-a-vue-ui-lib-2.md b/drafts/018.how-to-build-a-vue-ui-lib-2.md deleted file mode 100644 index a8805cb..0000000 --- a/drafts/018.how-to-build-a-vue-ui-lib-2.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: 「18」如何开发一个基于 Vue 的 ui 组件库（二） -date: 2019-02-20 23:35:00 -tags: [vue] ---- - -## 编写文档 -在编写组件库文档时，有两个必不可少的部分。 - -* 组件预览，最好有相应的代码 -* 组件 api，即 props、events、slots 等接口参数的说明 - -### 如何同时展示 demo 和 code？ -* 最【一力降十会】的方法当然就是复制粘贴一把梭... - -复制粘贴一把梭 - -这样实现简单是简单，不过维护时要同时改至少两份代码。比如 [vant 的展示文档][8] 和 [cube-ui 的展示文档][9]。 - -* 进阶一点儿的方法就是嵌入 Codepen、JSFiddle 或 CodeSandbox 的 iframe。 - -组件库中一般有大量的组件，不可能为每个组件都维护一份小代码片段，并且别忘了这可是三个平台。 - -* 各种组件库使用的最多的方法还是自己编写组件。 - -* 当然也有例外： - * [vux 只有 demo 没有 code][7]。 - * - - -以上 to be continued... - -## 参考资料 -* [muse-ui 的 demo-block 组件][1] -* [muse-ui 的 markdown-it 配置][2] -* [ant-design-vue 的 demoBox 组件][3] -* [ant-design-vue 的 markdown-it 配置][4] -* [element 的 demo-Block 组件][5] -* [element 的 markdown-it 配置][6] -* [vux 的展示文档][7] -* [vant 的展示文档][8] -* [cube-ui 的展示文档][9] - -[1]: https://github.com/museui/muse-docs/blob/master/src/components/demo-block.vue -[2]: https://github.com/museui/muse-docs/blob/master/scripts/vue-markdown-loader.conf.js -[3]: https://github.com/vueComponent/ant-design-vue/blob/master/site/components/demoBox.vue -[4]: https://github.com/vueComponent/ant-design-vue/blob/master/webpack.base.config.js -[5]: https://github.com/ElemeFE/element/blob/master/examples/components/demo-block.vue -[6]: https://github.com/ElemeFE/element/blob/master/build/webpack.demo.js -[7]: https://doc.vux.li/zh-CN/components/actionsheet.html -[8]: https://youzan.github.io/vant/#/zh-CN/button -[9]: https://didi.github.io/cube-ui/#/zh-CN/docs/button diff --git a/posts/018.how-to-build-a-vue-ui-lib-2.md b/posts/018.how-to-build-a-vue-ui-lib-2.md new file mode 100644 index 0000000..7eb5451 --- /dev/null +++ b/posts/018.how-to-build-a-vue-ui-lib-2.md @@ -0,0 +1,112 @@ +--- +title: 「18」如何开发一个基于 Vue 的 ui 组件库（二） +date: 2019-02-20 23:35:00 +tags: [vue] +--- + +## 遗留问题 +书接上回，说道利用 `sideEffects` 字段，只需读取源文件即可实现按需加载，还有个坑忘了说... + +> 文档中的样式打包后会丢失... + +因为我们只注意到了作为组件库的源代码，而忘了我们的文档是通过 vuepress 编译，即底层也是基于 webpack 进行打包。所以 `sideEffects` 中也要加上文档中的文件。 + +## 组件文档该写些什么？ +在编写组件库文档时，有两个必不可少的部分。 + +* 组件预览，最好有相应的代码 +* 组件 api，即 props、events、slots 等接口和参数的说明 + +## 如何同时展示 demo 和 code？ +* 最【一力降十会】的方法当然就是复制粘贴一把梭... + +复制粘贴一把梭 + +这样实现简单是简单，不过维护时要同时改至少两份代码。比如 [vant 的展示文档][8] 和 [cube-ui 的展示文档][9]。 + +* 进阶一点儿的方法就是嵌入 `Codepen`、`JSFiddle` 或 `CodeSandbox` 的 `iframe`。 + +但是组件库中一般有大量的组件，不可能为每个组件都维护一份小代码片段，并且别忘了这可是三个平台（硬点一个吼不吼啊~？）。 + +* 因此各种组件库使用的最多的方法还是自己编写组件。（下一小节详解） + +* 当然也有例外比如 [vux 只有 demo 没有 code][7]。 + +## 业界的文档组件 +* 最普遍的方式还是基于 `markdown-it`，将自己的 vue 组件插入文档中。 + * [muse-ui 的 demo-block 组件][1] + * [muse-ui 的 markdown-it 配置][2] + * [ant-design-vue 的 demoBox 组件][3] + * [ant-design-vue 的 markdown-it 配置][4] + * [element 的 demo-Block 组件][5] + * [element 的 markdown-it 配置][6] + +* 比较有意思的是 mand-mobile 的文档编写方式。demo 的文档放在组件目录中，然后由 `Doc` 组件读取各个组件的 demo。 + * [mand-mobile 的展示文档][10] + * [mand-mobile 的 Doc 组件][11] + +* 那么对于我们使用 vuepress 编写文档的开发者来说咋办咧？ + +## 在 vuepress 中展示 demo 和 code +首先让我们来分析一下：这两份重复的代码应该以谁为主？即我们应该只编写 demo 的代码还是 code 的代码？先有鸡还是先有蛋？物质决定意识还是意识决定物质？ + +至少在编写 demo 和 code 这个问题中，我认为 demo 才是“本源”，为什么？ + +* 这是最普遍的方式，各大组件库基本这么干 +* 这是最自然的方式，因为 vuepress 会编译 md 中的 vue 组件 +* 若是反过来，文档中以 code 为主，再由 code 生成 demo 会有一些不便 + * 如何预处理代码：babel、scss 等？ + * 如何插入生成的组件到文档中？ + * 感兴趣的话可以看看这个插件 [vuepress-plugin-demo-block][13] + +一开始我只在 `.vuepress/components/` 中建了个组件自娱自乐，后来看到了 [vuepress-plugin-demo-block][13]，但觉得由 code 生成 demo 有点儿绕。 + +于是自己搞了个插件 [vuepress-plugin-demo-code][12]，有需要的读者老爷可以自取~ + +## 组件的 api 文档 +解决了 demo 和 code 的重复编写问题，接下来是另一个令人无发可脱的问题：如何自动生成并同步 `.vue` 组件的 api 文档？ + +手动维护肯定是不行的，还好有一个炒鸡好用的库 [vuese][14]。vuese 会基于 ast 分析你的 `.vue` 文件，提取其中的 props、events、slots 等接口和参数的说明。 + +为了将其集成到 vuepress 中，我又整了个 markdown-it 插件 [markdown-it-vuese][15]。 + +只需使用以下的语法在导入已经存在的 `*.vue` 文件的同时，使用 `Vuese` 自动生成文档。 + +```md +<[vuese](@/filePath) +``` + +以上 to be continued... + +## 参考资料 +* [muse-ui 的 demo-block 组件][1] +* [muse-ui 的 markdown-it 配置][2] +* [ant-design-vue 的 demoBox 组件][3] +* [ant-design-vue 的 markdown-it 配置][4] +* [element 的 demo-Block 组件][5] +* [element 的 markdown-it 配置][6] +* [vux 的展示文档][7] +* [vant 的展示文档][8] +* [cube-ui 的展示文档][9] +* [mand-mobile 的展示文档][10] +* [mand-mobile 的 Doc 组件][11] +* [vuepress-plugin-demo-code][12] +* [vuepress-plugin-demo-block][13] +* [vuese][14] +* [markdown-it-vuese][15] + +[1]: https://github.com/museui/muse-docs/blob/master/src/components/demo-block.vue +[2]: https://github.com/museui/muse-docs/blob/master/scripts/vue-markdown-loader.conf.js +[3]: https://github.com/vueComponent/ant-design-vue/blob/master/site/components/demoBox.vue +[4]: https://github.com/vueComponent/ant-design-vue/blob/master/webpack.base.config.js +[5]: https://github.com/ElemeFE/element/blob/master/examples/components/demo-block.vue +[6]: https://github.com/ElemeFE/element/blob/master/build/webpack.demo.js +[7]: https://doc.vux.li/zh-CN/components/actionsheet.html +[8]: https://youzan.github.io/vant/#/zh-CN/button +[9]: https://didi.github.io/cube-ui/#/zh-CN/docs/button +[10]: https://mand-mobile.gitee.io/docs/index.gitee.html#/zh-CN/docs/components/basic/button +[11]: https://github.com/didi/mand-mobile/blob/3e5d485ec3ff0cfa73f9246929af0436a0b8a9f4/site/theme/default/components/Doc.vue +[12]: https://github.com/BuptStEve/vuepress-plugin-demo-code +[13]: https://github.com/xiguaxigua/vuepress-plugin-demo-block +[14]: https://github.com/vuese/vuese +[15]: https://github.com/BuptStEve/markdown-it-vuese