vue組件庫自動生成文檔-vue-styleguidist(二）

寫在前面：周末的日子是讓人輕松和愉快的，正好有更多的時間去總結歸納一周的事情，先將未完成部分繼續上吧

前面的一章已經介紹了關於vue-styleguist的配置的問題，本章將繼續如何在vue中去編寫自己的組件demo和生成自己的表格呢～

git 地址：https://github.com/YYNGUFD/vue-styleguide-demo

官網已經很明確了，

https://vue-styleguidist.github.io/docs/Documenting.html 關於在組件的.vue中的相關內容的詳細介紹

本次記錄僅僅只是加深印象哈哈哈

組件規范

要生成組件文檔以及組件運行demo就不得不提的一件事情就是，組件props的編寫規范以及運行規范，主要規范在引用數據類型的定義和默認賦值中，如Array類型和Object類型的數據，在prop進行默認賦值的時候，必須進行規范的自定義賦值，因為在生成文檔校驗是否規范，如果不規范，則會進行報錯提醒。如下面的規范格式

//正確規范賦值
 attrs: {
      type: Object,
      default: function () {
        return {};
      }
    },
//不規范賦值
 attrs: {
      type: Object,
      default:{}
    },

　　只有將組件的所有內容全部規范化后，才能繼續下一步，進行生成文檔

組件名稱設置

使用關鍵字@displayName

<script>
    /**
     * 關於on-off組件的說明
     * @displayName on-off組件
     */
 export default {}　　

設置顯示：

 

 props組件暴露字段顯示

• @values 表示當前屬性存在幾個值
• @ignore 設置后將忽略此屬性生成文檔
• @model 此屬性將用在頁面的v-model中
• @since 當前的設置版本
• @see 設置當前提示鏈接

props: {
   /**
     * 開關的默認狀態
     * @values false,true
     * @since Version 1.2.0
      
     */
    isDefault: {
      type: Boolean,
      default: true
    },
    /**
     * 左側標題提示
     *  @see See [當前提示鏈接](https://vue-styleguidist.github.io/docs/Documenting.html#methods)
     */
    title: {
      type: String,
      default: '設為默認地址'
    },
    /**
     * 標題樣式設置
     * @values  'font-size:18px;color:red;'
     */
    titleClass: {
      type: String
    }
     /**
     * @ignore 忽略props的該屬性，將不會出現在可視化api上
     */
    size:{
      type:String
    }
  },

顯示

 

 Events 事件暴露

在組件中向外暴露的事件，通過$emit的事件

• 在頁面的events中定義的暴露事件

   <!--
      在頁面中進行emit的事件
        @event isDefault
        @property {Boolean} on - true 為打開
        @property {Boolean} on - false 為關閉
    -->
    <button @click="$emit('isDefault', on)"></button>

• 在methods中暴露$emit

 /**
       * 操作控件時返回的狀態
       * @event isDefault 
       * @property {Boolean} on  true 表示打開
       * @property {Boolean} on  false 表示關閉
       */
      this.$emit('isDefault', this.on)

顯示效果：

 

 

slot的顯示

頁面中的插槽

• @slot 插槽標識 插槽的名字
• @binding 插槽中綁定的參數

 <!--
      @slot Use this slot body
            @binding {Boolean} newType 當前狀態
            @binding {Object} titleClass 當前的狀態
    -->
    <slot :newType="on" :titleClass="titleClass"></slot>
     <!--
      @slot Use this slot footer
            @binding {Boolean} newType 當前狀態
            @binding {Object} titleClass 當前的狀態
    -->
    <slot :newType="on" :titleClass="titleClass" name="footer"></slot>

methods

 在組件中存在一些重要的方法，可能需要給用戶的使用進行查看，因此需要進行一定的方法暴露，vue-styleguist提供了這樣的一個關鍵字進行暴露

 /**
     * @public 向外暴露的函數
     * @param {string} text 文本的值
     * @arg {Object} obj 文本的啥
     * @argument {object} nma 對象參數
     */
    changeOnOff (text,obj,nma) {
        }

  readme.md文檔

vue-styleguist組件文檔在進行編譯時候會自動編譯和加載.md 文檔，並將解析結果在頁面中展示。

去掉readme.md文件的解析 利用@example文件進行解析

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

編寫組件demo

我們希望我們的組件在運行的時候能夠有示例代碼

• 在.vue的文件尾部使用<docs></docs>的標簽進行編寫案例代碼
• 或者直接在readme.md文檔中進行編寫
• 兩種的示例代碼方式是一樣的
• 可通過new vue({})的方式進行構造實例代碼

1.jsx noeditor

編寫的demo 代碼能夠進行編輯改變狀態

``` jsx noeditor
 new Vue({
    data(){
      return {
        attrs:{
            leftValue: '左短',
            rightValue: '右短',
            allStyle:{
              width:'500px',
              border:'1px solid #000'
            }
        },
         attrs1:{
            leftValue: '左長左長左長左長左長左長左長左長左長左長左長左長左長左長左長左長左長左長左長左長',
            rightValue: '右短右短',
        }
      }
    }, 
    template: `
     <rLayout  :attrs=attrs></rLayout>
     <rLayout  :attrs=attrs1></rLayout>
  `
})
```

2.jsx static 僅僅代碼展示作用 比較適合當props為對象函數時候，在此進行props的對象說明

 

3.即可在readmd.md文件中進行編寫，也可以在文檔<docs></docs>文檔中編寫,還有許多其他的類似組件編寫，可參考https://vue-styleguidist.github.io/docs/Documenting.html#usage-examples-and-readme-files

4.可以單獨寫example.vue的文件，在readme.md的文件中進行引入即可

```[import](./example.vue)
Text typed here will be entirely ignored. You can use it to describe the example imported for maintenance purposes
```

案例demo運行注意點：

• 案例demo 運行環境說明，因為在編譯中依賴於vue-styleguidist 的環境，因此需要在vue-styleguidist 文件夾下的環境運行，如果組件文檔和當前的運行環境不在一個里面，組件內所依賴的三方插件文檔可能就會報錯等
• 如果在配置文檔中忽略了某些文件，如select組件，其他的組件調用該組件時也將會失效，忽略的組件一旦忽略，將不會進行編譯和執行