如何让你的vue组件更好的被使用（Vue-Styleguidist中文文档）

时间 2020-05-23

标签如何让你 vue 组件更好使用 styleguidist 中文文档繁體版

原文原文链接

近期新开项目，发现以前编写的组件不知道怎么用，要不看源码，要不就只能看之前的代码。因此找到Vue-styleguidist，把以前的组件都编写文档方便之后使用，就像看element-ui等组件库的文档同样，使你们的开发效率提高，推荐给各位。先上官方 demo 看看效果，多种样式供你选择。javascript

起步

安装

npm安装html

npm install --save-dev vue-styleguidist

若是使用的是Vue Cli，可使用其插件vue

vue add styleguidist

配置你的样式风格

建立一个styleguide.config.js文件在package.json同一级目录，这个是你的配置文件，在这个文件里，你能够：java

指定Styleguidist到你的vue组件文件夹
明确如何加载代码

若是使用了Vue cli能够跳过这个步骤。当安装vue-cli-plugin-styleguidist,styleguidist会从cli中获取相关内容，通知styleguidist组件目录node

添加npm脚本方便使用

添加这些脚本到package.json:react

{
  "scripts": {
     "styleguide": "vue-styleguidist server",
     "styleguide:build": "vue-styleguidist build"
  }
}

开始styleguidist

运行npm run styleguide启动styleguide开发服务
运行npm run styleguide:build构建一个固定版本

开始编写组件文档

编写组件文档

Vue styleguidist是基于组件源码和Readme文件中的注释声明进行生成组件文档。git

代码注释

Vue styleguidist会显示组件中JSDoc注释内容github

<template>
  <div class="Button">
    /* ... */
  </div>
</template>

<script>
  /**
   * The only true button.
   * @displayName Best Button
   */
  export default {
    name: 'Button',
    props: {
      /**
       * The color for the button.
       */
      color: {
        type: String,
        default: '#333'
      },
      /**
       * The size of the button
       * @values small, normal, large
       */
      size: {
        type: String,
        default: 'normal'
      },
      /**
       * Gets called when the user clicks on the button
       */
      onClick: {
        type: Function,
        default: event => {
          console.log('You have clicked me!', event.target)
        }
      }
    }
    /* ... */
  }
</script>

请注意使用了@displayName标签将该变组件名称，这是一个顶层的注释，必须出如今脚本标签export default以前。vue-cli

若是组件中建立了自定义的v-model，你必须添加model标签在注释中npm

<script>
  export default {
    name: 'my-checkbox',
    props: {
      /**
       * @model
       */
      value: String
    }
  }
</script>

在vue组件中，对组件的prop设置限定有效值是很常见的。例如，size只可以接受small，medium和large。这种状况，使用@values标签。

Events

编写事件的文档，在其触发事件的代码上方添加注释。若是不紧邻触发事件的代码，将会被忽略。

在脚本块中

若是事件已经显式明确了，则不须要告诉styleguidist事件名称

/**
 * Success event.
 */
this.$emit('success')

常量也会被识别出来

/**
 * Success event.
 */
const success = 'succ'
this.$emit(success)

若是使用的事件名称从对象中取出，则须要使用@event标签

/**
 * Success event.
 *
 * @event success
 */
this.$emit(EVENTS.success)

若是时间传入的有参数或属性，使用@propety标签的描述它。也可使用@arg或者@param。

/**
 * Triggers when the number changes
 *
 * @property {number} newValue new value set
 * @property {number} oldValue value that was set before the change
 */
this.$emit('change', newValue, oldValue)

在template中

被直接用在v-on表达式中触发的事件将自动被检测到。为了更好地文档说明他们，能够在template中，在$emit被调用的代码行上面添加注释。
注释块内编写文档须要包含一行@event click。剩下的注释块那内容和在脚本中注释同样便可。
@property用来描述参数。

<div>
  <!--
    trigered on click
    @event click
    @property {object} demo - example
    @property {number} called - test called
  -->
  <button @click="$emit('click', test)"></button>
</div>

插槽slot

styleguidist将自动检测到插槽部分。在插槽前一行添加用@slot注释描述。

<template>
  <div class="modal">
    <div class="modal-container">
      <div class="modal-head">
        <!-- @slot Use this slot header -->
        <slot name="head"></slot>
      </div>
      <div class="modal-body">
        <!-- @slot Use this slot body -->
        <slot name="body"></slot>
      </div>
    </div>
  </div>
</template>

除了在给插槽添加描述外，还能够对插槽绑定的属性编写文档。这些属性使用关键字@binding。
格式要求以下：

<!--
  @binding {type} BindingName description of what the bindings is meant for
  -->

一个插槽文档的例子：

<div slot-scope="row" class="list-item1">
  {{row.item.text}}
  <!--
      @slot Menu Item footer
        @binding {object} icon icon of the menu item
        @binding {string} text text of the menu item
    -->
  <slot name="test" :icon="row.item.icon" :text="row.item.text" />
</div>

包含`mixin`和`extends`

若是导入了minxin或extends，也将会被styledist自动添加到你的组件文档中

使用案例和Readme文件

vue styleguidist将在组件的文件夹内查找例如Readme.md或{组件名}.md的文件，将其展现在你的组件文档中做为示例文档。一些使用语言标签vue,js,jsx或者javascript的代码块将被做为vue组件渲染。
若是想忽略组件的readme文件，使用@example [none] doclet。这样也可以解决多个组件在同一个文件夹内共享一个readme文件。这样将防止示例被屡次渲染。

<html>

<pre>
Vue component example:

<Button size="large">Push Me</Button>

One more with generic code fence:

<Button size="large">Push Me</Button>

You can disable an editor by passing a noeditor modifier:

<Button>Push Me</Button>

To render an example as highlighted source code add a static modifier:

<Button>Push Me</Button>

You can also initialize vue to construct more complex examples in two ways:

Create a new Vue instance

const names = require('dog-names').all;

new Vue({
  data(){
    return {
      list: names
    }
  },
  template: `
    <div>
      <RandomButton :variants="list" />
    </div>
  `
})

Single-file components with a language tag of vue (supports <style scoped>)

<template>
    <div class="wrapper">
      <Button id="dog-name-button" @click.native="pushButton">Push Me</Button>
      <hr />
      <p class="text-name">Next Dog Name: </p>
    </div>
  </template>

  <script>
    const dogNames = require('dog-names').all;

    // You can also use 'exports.default = {}' style module exports.
    export default {
      data() {
        return { numClicks: 0, dogName: dogNames[0] };
      },
      methods: {
        pushButton() {
          this.numClicks += 1;
          this.dogName = dogNames[this.numClicks];
        }
      }
    }
  </script>

  <style scoped>
    .wrapper {
      background: blue;
    }
    .text-name {
      color: red;
    }
  </style>

Examples with all other languages are rendered only as highlighted source code, not an actual component:

<Button size="large">Push Me</Button>

Any Markdown is allowed _here_.
</pre>
</html>

你也能够添加自定义代码块<docs></docs>在*.vue文件中,这样vue styleguidist也会建立描述文件。

使用注释添加外部示例

使用@example注释，添加外部示例文件。下面这个例子就是加载extra.examples.md文件的示例:

/**
 * Component is described here.
 *
 * @example ./extra.examples.md
 */
export default {
  name: 'Button'
  // ...
}

忽略示例文件

也可使用@example来忽略关联到readme文件，这样可以防止屡次渲染示例文。

/**
 * Component is described here.
 *
 * @example [none]
 */
export default {
  name: 'Button'
  // ...
}

公共方法

默认的组件中methods中的方法被视为私有的，是不会被公开的。可使用JSDoc中@public标签让方法视为公开，并展现在文档中。

/**
 * Insert text at cursor position.
 *
 * @param {string} text
 * @public
 */
insertAtCursor(text) {
  // ...
}

忽略`props`

默认状况下，组件中的全部属性props被认为是公开发的。在极少数状况下，想要只在文档中的移除部分属性说明。为此，可使用JSDoc的@ignore标签注释在属性前面，用于标记在文档中移除它。

props: {
    /**
    * @ignore
    */
    color: {
      type: String,
      default: '#333'
    }

使用JSDoc标签

在编写组件、属性或方法文档时，可使用如下JSDoc标签

@deprecated
@see，link
@author
@since
@version

displayName

除上面这些标签之外，可使用@displayName来该变组件在你的文档中显示的名称。可是看到他的名称被修改后，你在调用使用时，也须要使用被命名的名称，名称中的空格和符号在使用时不须要。举个例子，若是展现的名称被修改：

/**
 * @displayName Wonderful Button
 **/

要在示例中引用它时，就须要使用<WonderfulButton/>

方法的注释

当编写方法的文档时，你可使用：

@param，@arg，@argument
@event
@public

<template>
  <!-- -->
</template>

<script>
  /**
   * The only true button.
   * @version 1.0.1
   */
  export default {
    name: 'Button',
    props: {
      /**
       * The color for the button.
       * @see See [Wikipedia](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names)
       * @see See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) for a list of color names
       */
      color: {
        type: String,
        default: '#333'
      },
      /**
       * The size of the button
       * `small, normal, large`
       * @since Version 1.0.1
       */
      size: {
        type: String,
        default: 'normal'
      },
      /**
       * Gets called when the user clicks on the button
       */
      onClick: {
        type: Function,
        default: event => {
          console.log('You have clicked me!', event.target)
        }
      }
    },
    methods: {
      /**
       * Gets called when the user clicks on the button
       *
       * @param {SyntheticEvent} event The react `SyntheticEvent`
       * @param {Number} num Numbers of examples
       * @public This is a public method
       */
      launch(event, num) {
        /* ... */
      },
      // ...
      ignoreMethod() {
        /**
         * Success event.
         *
         * @event success
         * @type {object}
         */
        this.$emit('success', {})
      }
    }
    /* ... */
  }
</script>

组合组件

列表组件或者表格组件经常须要写成一个组合的api。例如，一个下拉菜单可读性强的编写方法是

<DropDown>
  <Choice val="1">value 1</Choice>
  <Choice val="2">value 2</Choice>
</DropDown>

要优于使用属性

<DropDown :choices="[{val:1,text:'value 1'}, {val:2,text:'value 2'}]"/>

vue styleguidist提供编写这种状况的方式：在主组件中添加@require。如今这个下拉菜单的组件是这样：

<template>
  <select>
    <slot />
  </select>
</template>
<script>
/**
 * @requires ./Choice.vue
 */
export default {
  name: 'DropDown'
}
</script>

定位你的组件并组织你的文档样式

相关配置将会在styleguidist.config.js中进行编写。

定位组件

styleguidist使用glob pattern匹配查询你的组件，默认状况下，查询的是src/components/**/*.vue。下面这个例子，可以检测到如src/components/Button/Button.vue.

module.exports = {
  components: 'src/components/**/[A-Z]*.vue'
}

但不会监测同时文件夹__tests__。

注意：全部的路径都是对配置文件的相对路径。
注意：使用 getComponentPathLine配置项将该变组件文档下显示的组件路径。
提示：使用 ignore配置项可能排除你不想在文档中看到的文件。

加载和暴露组件

styleguidist默认状况下在你文档的示例展现中加载你的组件并暴露给全局。若是不想所以形成全局污染，可使用locallyRegisterCompenents，这样就能保证你的组件只在该组件的ReadMe.md文件和<docs>块中注册。

分组

给你的组件进行分组在文档中展现。每一个分组都包含如下部分（全部的字段都是可选的）:

name——分组标题
content——包含分组概述内容Markdown文件的路径
components——这个和根节点下components配置项相同，能够为一个或多个glob pattern字符串，组件路径数组，或者是个返回组件路径数组或golb pattern字符串数组的函数。
sections——子分组的数组（支持循环嵌套）
exampleMode——文档中代码示例的标签初始化状态，决定是否展开。
usageMode——文档中属性和方法的标签初始化状态，决定是否展开
ignore——不该包含在分组中文件路径的glob pattern的字符串或数组
href——一个导航路径
external——若是设置，链接将在新窗口打开