如何讓你的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——若是設置，鏈接將在新窗口打開

相關標籤/搜索

中文文檔

Chromium中文文檔