0
点赞
收藏
分享

微信扫一扫

如何优雅的使用Vuepress编写组件示例(上)


前言✍️

  • 最近在搭自己的组件库,关于文档用的是​​Vuepress​
  • 官网在文档说明展示组件示例的方法有很多种,但种种都不合心意
  • 通过查阅网上的资料和​​Element​​的源码找出了我认为的一种最优解,借此机会分享一下
  • 该篇主要是对思路的分析和归纳,如果想直接看具体操作可以看到​​如何优雅的使用Vuepress编写组件示例(下)​​

实际效果✔️


先把最后的成品发出来给大家看看


  • ​优化前​

如何优雅的使用Vuepress编写组件示例(上)_html

  • ​优化后​

如何优雅的使用Vuepress编写组件示例(上)_代码块_02


可能对于效果没什么区别但是把markdown代码放出来就差别很大了


如何优雅的使用Vuepress编写组件示例(上)_自定义_03可以看到,页面不仅美观了些许,代码可以说是非常简洁了,具体是怎么做到的呢,请听我细细道来

开始动手✊

文档选择

  • 对于一个组件库来说,有一个合适的文档来展示组件​​demo​​​是最最基本的事情,由此我选择了​​Vuepress​​是觉得简洁大方
  • ​Vuepress​​​的诞生初衷是为了支持​​Vue​​​及其子项目的文档需求所以他的风格跟​​Vue​​的文档很像

着手展示

  • 在​​Vuepress​​​中,本来就支持在​​markdown​​​文件中编写符合​​Vue​​语法的代码
  • ​Vuepress​​​内部将​​markdown​​​语法转化成​​vue​​​进而通过内部集成的​​vue-loader​​​来得到最终的​​HTML​
  • 所以我们在​​.md​​​文件中既可以输入​​md​​​语法也可以输入​​Vue​​代码,这么一来就好办了啊(狗头)

如何优雅的使用Vuepress编写组件示例(上)_代码块_04

  • 啪!很快啊,不管三七二十一直接把自己的组件写上去了,虽然有点麻烦但最终效果还是我想呈现的那样(​​此时我还没发现事情的严重性​​)

如何优雅的使用Vuepress编写组件示例(上)_代码块_05

感觉麻烦

  • 当我写到第二个组件示例的时候,感觉事情有点不对了
  • 在我用上面那种方法来呈现​​demo​​的时候发现这种方法有很大的问题
  1. ​样式编写麻烦​​​对于文档组件例子的样式基本是都一样的都是一个框下面一个代码,但是用了上面那种呈现方式每次样式要重新写(再加上​​md​​文件没有代码提示太难受)
  2. ​代码重复​​​ 由上图可知我写一个​​button​​​的示例同样的代码写了两遍分别用于展示​​demo​​和展示代码
  3. ​页面杂乱​​​ 由上图可知在一个​​md​​​文件里又有​​md​​​语法又有​​vue​​语法实在是混乱
  4. ​没有集中管理​​​ 每一个例子按理说都有一个通用的东西(例如​​样式​​)没有集中管理,一改就要全部改

重新选择

第一种方法????‍♂️

上文所述直接在​​md​​​文件编写​​Vue​​​+​​md​​​的语法(​​淘汰!​​ 这种方法要复用的代码太多不方便)

第二种方法????‍♂️

每个​​demo​​​封装一个​​vue​​​组件分开维护,通过​​Vuepress​​​直接渲染的方式呈现,样式也统一在一个​​css​​里面导入进去,但是这种方法还是使文档存在组件的语法,页面多起来会很不好维护

# Button 按钮
<btn></btn>

## 使用
```html
<l-button>默认按钮</l-button>
<l-button type="primary">主色按钮</l-button>
<l-button type="success">成功按钮</l-button>
<l-button type="info">提示按钮</l-button>
<l-button type="warning">警告按钮</l-button>
<l-button type="danger">错误按钮</l-button>
```

第三种方法????‍♂️

在上面的基础上通过​​Vuepress​​​自带的​​<<< @/filepath​​导入代码块

## Button 按钮
<btn></btn>
## 使用
```html
<<< @/docs/.vuepress/components/btn.vue
`` `
  • 在尝试了上面三种方法之后还是觉得我不仅要在组件里面写代码还要在​​md​​​文件也要写,还是觉得有点麻烦的,有没有更好的办法可以让我只在​​md​​文件编辑,页面就直接更改呢?
  • 就在我快要想秃噜皮的时候瞄了一眼​​element​​的文档,看到这清一色统一的样式就在思考这些UI库都是怎么管理的呢
  • 打开​​element​​的源码突然恍然大悟????

第四种方法????‍♂️

真的是看一次企业级源码胜读十年书,怎么会有如此简便的写法,通过自定义容器来编辑,样式统一管理,文档干净简洁,就决定是他了!!????

### 禁用状态

按钮不可用状态。

:::demo 你可以使用`disabled`属性来定义按钮是否可用,它接受一个`Boolean`值。

```html
<el-row>
<el-button disabled>默认按钮</el-button>
<el-button type="primary" disabled>主要按钮</el-button>
<el-button type="success" disabled>成功按钮</el-button>
<el-button type="info" disabled>信息按钮</el-button>
<el-button type="warning" disabled>警告按钮</el-button>
<el-button type="danger" disabled>危险按钮</el-button>
</el-row>

<el-row>
<el-button plain disabled>朴素按钮</el-button>
<el-button type="primary" plain disabled>主要按钮</el-button>
<el-button type="success" plain disabled>成功按钮</el-button>
<el-button type="info" plain disabled>信息按钮</el-button>
<el-button type="warning" plain disabled>警告按钮</el-button>
<el-button type="danger" plain disabled>危险按钮</el-button>
</el-row>
```
:::

摸索摸索????

  • 说实话刚打开​​element​​​源码的时候还有点蒙不清楚这个​​:::demo​​是怎么来的
  • 于是观察​​element​​​文档发现通过这个自定义容器会自动编译成有​​demo-block​​类的组件
::: demo
xxx
:::

如何优雅的使用Vuepress编写组件示例(上)_html_06

  • 在源码搜索后找到对应的文件

如何优雅的使用Vuepress编写组件示例(上)_Vue.js_07

  • 接下来只要搞清楚他是怎么通过这句小小的代码编译转化成这个组件的就可以了
  • 咦~编译?什么时候会有编译?​​webpack​​处理?!!!
{
test: /\.md$/,
use: [
{
loader: 'vue-loader',
options: {
compilerOptions: {
preserveWhitespace: false
}
}
},
{
loader: path.resolve(__dirname, './md-loader/index.js')
}
]
}
  • 原来如此,从配置文件中可以看出,​​Markdown​​​先经由​​md-loader​​​处理,然后再交由​​vue-loader​​​处理。经过这两个​​loader​​​的处理,​​Markdown​​​就与​​Vue​​组件一样了
  • 虽然​​element​​​用的不是​​Vuepress​​​但底层都是关系到​​markdown​​​,那是不是可以参考一下让我们的​​Vuepress​​​也像​​element​​文档一样使用这个自定义容器呢?答案是可以的!!

李性分析????‍♂️

在看过​​element​​的源码后大概知道是怎么回事了

  • 第一步构建一个通用组件用于接收代码块来展示​​demo​​并且统一样式
  • 第二步设定一个​​Markdown​​​自定义容器来编写​​demo​​代码
  • 第三步把自定义容器转化成之前构建的通用组件,这样就可以在​​md​​使用自定义容器来实现上文效果
  • 第四步扩展​​markdown​​​渲染方法使我们输入的代码块可以输出内容为符合​​Vue Template​​语法的代码块
  • 第五步变成了​​vue​​​代码后交由​​Vuepress​​​的​​vue-loader​​处理编译为文档


举报

相关推荐

0 条评论