Storybook Vue 插件

一个 Storybook 插件，允许使用原生 Vue 语法编写故事，并将其编译为 Storybook 的 CSF 格式。

示例：Button.stories.vue

<script setup lang="ts">
import Button from './Button.vue'
</script>
<template>
  <Stories
    title="Stories in Vue format 😍"
    :component="Button"
  >
    <Story title="Primary">
      <Button
        background="#ff0"
        label="Button"
      />
    </Story>
    <Story title="Secondary">
      <Button
        background="#ff0"
        label="😄👍😍💯"
      />
    </Story>
    <Story title="Tertiary">
      <Button
        background="#ff0"
        label="📚📕📈🤓"
      />
    </Story>
  </Stories>
</template>

功能

• 以惯用的 Vue 模板编写故事，告别基于字符串的模板，如 storybookjs/storybook#9768 中所愿。
• 编写故事模板的语法高亮和完整编辑器支持（包括 Volar）
• 在自定义的 docs 块中添加 Markdown 文档，直接在 stories.vue 文件中（有关详细信息，请参见下文）
• 要显示的组件只需声明一次（通过 <Stories :component="...">），而无需为每个故事声明。
• 与 Storybook 简单集成，并自动支持 Vite
• 轻量级：Vue 故事在运行时被转换为普通的 CSF 故事，开销最小。

此软件包目前处于早期 Alpha 阶段，仅支持 Storybook 的基本功能。与更高级功能和插件的兼容性正在开发中。如果您遇到任何错误或缺少集成，请提交问题。

以惯用的 Vue 模板编写故事的方式深受优秀的 Histoire 的启发。

安装

注意：目前仅支持 @storybook/vue3-vite 构建器（或已弃用的 @storybook/builder-vite 版本 0.2.7 或更高版本）。

1. 将 storybook-vue-addon 添加到您的开发依赖项中。

   # npm
   npm install --save-dev storybook-vue-addon
   
   # yarn
   yarn add -D storybook-vue-addon
   
   # pnpm
   pnpm add -D storybook-vue-addon
   

2. 在 .storybook/main.js 中，将 *.stories.vue 添加到故事模式中，并将 storybook-vue-addon 作为插件添加。

     "stories": [
       "../src/**/*.stories.mdx",
   -    "../src/**/*.stories.@(js|jsx|ts|tsx)"
   +    "../src/**/*.stories.@(js|jsx|ts|tsx|vue)"
     ],
     ...
     "addons": [
       "@storybook/addon-essentials",
   +   "storybook-vue-addon"
     ],
   
   

添加文档

您可以使用自定义的 docs 块，直接在您的故事 SFC 中添加组件文档。

<template>Define your stories here as above</template>

<docs lang="md">
import { Canvas } from '@storybook/blocks';

# Documentation

Everything in one place. Isn't it great?

You can render stories in the docs using the `<Canvas>` component.

<Canvas />
</docs>

您可以使用 Markdown 的易读语法（例如 # 标题）编写文档，包含故事，并在文件的任何位置自由嵌入 JSX 组件块。有关更多信息，请参阅 Storybook 文档。与标准 MDX 文档页面相比，有一些细微的差异。

• 不需要 <Meta of=...> 标签。
• 您无需导入故事文件。只需按名称引用已定义的故事。例如

  <template>
    <Stories>
      <Story title="Unchecked">
        <Checkbox label="Unchecked" />
      </Story>
    </Stories>
  </template>
  <docs>
    import { Canvas } from '@storybook/blocks';
    <Canvas of={Unchecked} />
  </docs>
  

TypeScript 支持

Volar 应该能够自动识别 Stories 和 Story 组件。也可以从 storybook-vue-addon 中导入它们。

import type { Stories, Story } from 'storybook-vue-addon/core'

手动使用

如果出于任何原因您在构建管道中处理 Storybook 故事，您可能希望首先通过将 storybook-vue-addon 添加到构建中来将 Vue 故事转换为经典的 CSF 故事。

// vite.config.ts
import VueStories from 'storybook-vue-addon/vite'

export default defineConfig({
  plugins: [
    VueStories({
      /* options */
    }),
  ],
})

示例：playground/

// rollup.config.js
import VueStories from 'storybook-vue-addon/rollup'

export default {
  plugins: [
    VueStories({
      /* options */
    }),
  ],
}

// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('storybook-vue-addon/webpack')({
      /* options */
    }),
  ],
}

// nuxt.config.js
export default {
  buildModules: [
    [
      'storybook-vue-addon/nuxt',
      {
        /* options */
      },
    ],
  ],
}

此模块适用于 Nuxt 2 和 Nuxt Vite。

// vue.config.js
module.exports = {
  configureWebpack: {
    plugins: [
      require('storybook-vue-addon/webpack')({
        /* options */
      }),
    ],
  },
}

// esbuild.config.js
import { build } from 'esbuild'
import VueStories from 'storybook-vue-addon/esbuild'

build({
  plugins: [VueStories()],
})

💻 开发

• 克隆此仓库
• 使用 corepack enable 启用 Corepack（对于 Node.js < 16.10，使用 npm i -g corepack）。
• 使用 pnpm install 安装依赖项。

命令

• build：构建所有内容。输出可以在 dist 中找到。
• build:types：为 Story 和 Stories 组件构建类型，以便在 components.d.ts 文件中更容易开发。
• dev：在监视模式下构建。
• lint：检查 eslint 和 prettier 问题。
• test：运行测试。
• example:vite：打开示例 Storybook（使用 vite）。您需要先运行 build 或 dev。
• play：运行游乐场（目前未使用）。
• release：发布新版本到 npm。

赞助商

感谢 Chromatic 提供了视觉测试平台，帮助我们审查 UI 更改并捕获视觉回归。