vue组件文档（.md）中如何自动导入示例（.vue）详解

要在Vue组件文档（.md）中自动导入示例（.vue），需要安装vue-styleguidist这个插件。接下来，我们以vue-cli3创建的项目为例，来讲解如何实现自动导入示例。

第一步：安装vue-styleguidist插件

首先，在项目根目录下使用npm命令行安装vue-styleguidist插件。

npm install vue-styleguidist --save-dev

第二步：在项目中创建示例文件夹

在项目目录下创建一个名为“examples”的文件夹，用于保存示例.vue文件。

第三步：编写组件与示例

在src文件夹下创建一个名为“HelloWorld”的Vue组件，并在examples文件夹中创建一个名为“HelloWorld.vue”的示例文件。示例文件中的内容可以是这样的：

<template>
  <div>
    <HelloWorld msg="Hello World!"/>
  </div>
</template>

<script>
import HelloWorld from '../src/components/HelloWorld.vue'
export default {
  components: {
    HelloWorld
  }
}
</script>

注意，示例文件中要导入要演示的组件，并使用import语句将组件导入。这里导入的是位于src/components/HelloWorld.vue文件中的HelloWorld组件。

第四步：配置“styleguide.config.js”文件

在根目录中创建一个名为“styleguide.config.js”的文件，该文件用于配置vue-styleguidist插件的一些参数。

代码如下：

module.exports = {
  components: 'src/components/**/*.vue',  // 组件所在的目录
  exampleMode: 'expand', // 示例模式
  usageMode: 'expand' // 使用模式
}

在这里，我们要指定组件所在的目录、示例模式与使用模式。上面的配置会扫描src/components目录下的所有.vue文件，并将其编译为文档。

第五步：启动vue-styleguidist服务器

在命令行中输入下面的命令，以启动vue-styleguidist服务器。

node_modules/.bin/styleguidist server

当你看到控制台输出“Styleguidist server running”时，就代表服务器已经启动了。

第六步：访问文档

现在你可以通过访问http://localhost:6060来查看vue组件文档了。

接下来，我们以两个示例为例，来详细阐述如何实现自动导入示例。

示例一：基本示例

假设我们现在要编写一个名为“Button”的组件，并在其文档中提供一个名为“基本示例”的示例。

首先，我们在src/components目录下创建一个名为“Button.vue”的组件文件，并在examples目录下创建一个名为“Button.vue”的示例文件。

• Button.vue组件

<template>
  <button class="btn">{{text}}</button>
</template>

<script>
export default {
  name: 'Button',
  props: {
    text: {
      type: String,
      default: 'Button'
    }
  }
}
</script>

• Button.vue示例文件

<template>
  <Button text="Click Me!"/>
</template>

<script>
import Button from '../../src/components/Button.vue'
export default {
  components: {
    Button
  }
}
</script>

接着，我们需要在组件文档中引入示例文件。在Button.vue文档中加入以下代码块：

```demo
  name: Button Demo
  desc: Button Basic Demo
  code:
    src: ./examples/Button.vue
    lang: vue
```

这段代码块中包含以下参数：

• name: 示例名称。
• desc: 示例描述。
• code: 示例代码相关配置项。

其中，代码的src属性指定示例文件的路径，lang属性指定代码的语言类型。

示例二：多个示例

假设我们要在组件文档中提供多个示例，该怎么办呢？有时候我们可能需要提供不同场景下的演示，或者针对组件的不同属性进行演示，这时候我们需要展示多个示例。

以“Button”组件为例，我们需要创建两个示例：一是默认示例，一是半透明的示例。代码如下：

• Button.vue组件

<template>
  <button class="btn" :style="{opacity: opacity}" @click="handleClick">{{text}}</button>
</template>

<script>
export default {
  name: 'Button',
  props: {
    text: {
      type: String,
      default: 'Button'
    },
    opacity: {
      type: Number,
      default: 1
    }
  },
  methods: {
    handleClick() {
      alert(this.text)
    }
  }
}
</script>

• Button.vue示例文件

<template>
  <Button text="Default Button"/>
</template>

<script>
import Button from '../../src/components/Button.vue'
export default {
  components: {
    Button
  }
}
</script>

<template>
  <Button text="Translucent Button" :opacity="0.5"/>
</template>

<script>
import Button from '../../src/components/Button.vue'
export default {
  components: {
    Button
  }
}
</script>

接着，我们在Button.vue组件文档中加入以下代码块：

## 示例列表

### 默认演示

```demo
  name: Default Demo
  desc: Button Demo - Default
  code:
    src: ./examples/ButtonDefault.vue
    lang: vue
```

### 半透明演示

```demo
  name: Translucent Demo
  desc: Button Demo - Translucent
  code:
    src: ./examples/ButtonTranslucent.vue
    lang: vue
```

我们需要在“示例列表”中加入多个demo代码块，每个demo代码块中的参数都和之前所说的参数一样。

至此，我们就可以在Vue组件文档（.md）中自动导入示例（.vue）了。