封装了一些组件，给同事使用时如何更好的提供文档？

先看看效果

完美的文档

自动提取组件的props，slot，event，method

再配合组件提示

props提示

slot提示

event提示

有了这些功能，同事恐怕不能拒绝使用了吧，推广组件再也不难了（推广组件的好处不用说了吧）

如何写呢？

文档工具：styleguidist

安装不必说了，传送门： vue-styleguidist.github.io/docs/Gettin…

配置：styleguide.config.js

module.exports = {
	// set your styleguidist configuration here
	title: 'lib 文档',
	components: 'dist/**/xb-*.vue',
        // 指定全局依赖，一般和main.js一样，比如import Vue from 'vue';
	require: [path.join(__dirname, 'styleguide/global.requires.js')],
	copyCodeButton:true,
	pagePerSection:true,
	styleguideDir:'styleguide/dist',
	styleguidePublicPath:'',
        //导航条，支持 md文件，href链接，components
	sections: [

		{
			name: '介绍',
			content: 'styleguide/docs/Documentation.md',
		},
		{
			name: '主页',
			href: '../',
		},
 
		 
		{
			name: '组件',
			sections: [
				{
					name: '弹窗',
					content: 'styleguide/docs/modal.md',
                                        //函数回调，动态获取组件列表
					components: () => getComponents('modal'),
					exampleMode: 'collapse', // 'hide' | 'collapse' | 'expand'
					usageMode: 'expand' // 'hide' | 'collapse' | 'expand'
				},
				 
			],
			sectionDepth: 1
		}
	],
	 
	exampleMode: 'collapse'
}

md文件编写

md文件最重要的就是示例代码支持，直接使用vue代码格式，就可以实现组件预览支持

**示例1**
```vue
<template>
<xb-form ref="form"  title="编辑" :hasButton="true" :form_data="form_data">
  <xb-form-item label="单行" name="test1" required  >
    <xb-input   v-model="form_data.test1" placeholder="请输入"/>
  </xb-form-item>
  <xb-form-item label="单行2" name="test2" :rules="test2rules" >
    <xb-input   v-model="form_data.test2" placeholder="请输入"/>
  </xb-form-item>
   
</xb-form>
</template>

<script>
export default {
  name: "edit-form",
  data(){
    return {
      form_data:{
      },
      
      test2rules:[
        {required:true,message:'必填'}
      ]
    }
  },
  methods:{
    submit(){
      

    }
  }
}
</script>

<style scoped>

</style>

如果导航配置的components为组件列表，就会自动识别组件里面的参数

sections: [
				{
					name: '弹窗',
					content: 'styleguide/docs/modal.md',
                                        //函数回调，动态获取组件列表
					components: () => getComponents('modal'),
					exampleMode: 'collapse', // 'hide' | 'collapse' | 'expand'
					usageMode: 'expand' // 'hide' | 'collapse' | 'expand'
				},
				 
			],

组件编写：直接看官方文档吧，就是在组件代码里面注释写好就行

<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>

代码提示工具：vue-docgen-web-types

代码提示是使用 web-types，webstorm默认就支持，vscode需要相关插件

安装：

{
  "web-types": "tours/web-types.json",
  "scripts": {
    "web-types": "vue-docgen-web-types"
  },
  "devDependencies": {

    "vue-docgen-api": "^4.46.0",
    "vue-docgen-web-types": "^0.1.7",
  }
}

配置：

web-types.config.js

module.exports = {
    components: 'dist/**/xb-*.vue',
    outFile:'tours/web-types.json'
}

运行命令：npm run web-types 自动生成web-types.json文件

有了这个文件，ide就会自动识别了

总结

这一套整下来，害怕组件不好用吗？