Vue3 setup语法下Storybook 7.4 Autodocs配置问题咨询

方法1：结合TS接口与JSDoc注释定义事件 #

Storybook的autodocs对<script setup>里的defineEmits，需要通过TS接口承载注释信息，单独的JSDoc无法被正确识别。示例代码：

<script lang="ts" setup>
/**
 * 组件自定义事件集合
 */
interface ComponentEmits {
  /**
   * 按钮点击时触发，返回累计点击次数
   * @param count 当前点击次数
   */
  'btn-click': [count: number]
  /**
   * 输入框内容变化时触发，返回最新输入值
   * @param value 输入框当前内容
   */
  'input-change': [value: string]
}

const emit = defineEmits<ComponentEmits>()
</script>

autodocs会自动解析接口内的注释，生成对应的事件文档。

方法2：数组写法+事件上方JSDoc注释 #

如果不想使用TS接口，可直接在defineEmits的数组参数里，给每个事件字符串添加上方注释：

<script lang="ts" setup>
const emit = defineEmits([
  /**
   * 按钮点击时触发，返回累计点击次数
   * @param count 当前点击次数
   */
  'btn-click',
  /**
   * 输入框内容变化时触发，返回最新输入值
   * @param value 输入框当前内容
   */
  'input-change'
])
</script>

这种写法同样能被Storybook的autodocs抓取到注释信息。

方法3：确认Storybook基础配置 #

检查.storybook/main.ts，确保Vue3框架插件正确加载且autodocs功能开启：

import type { StorybookConfig } from '@storybook/vue3-vite'

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/vue3-vite',
    options: {},
  },
  docs: {
    autodocs: true, // 确保自动文档功能开启
  },
}

export default config

额外注意事项 #

• 组件文件需为.vue格式，且Storybook配置的扫描路径能覆盖到组件及对应的stories文件
• 避免使用defineEmits({})的对象写法，该写法的注释识别支持度较差，优先选择TS接口或数组写法
• Storybook 7.4的Vue3插件已内置上述支持，无需额外安装依赖

内容的提问来源于stack exchange，提问作者Roman Plischke