Storybook Vue 附加组件

一个 Storybook 附加组件，允许使用原生 Vue 语法编写 Stories，并将其编译为 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 模板编写 Stories，告别基于字符串的模板，正如 storybookjs/storybook#9768 中所期望的
• 编写 Story 模板时的语法高亮和完整的编辑器支持（包括 Volar）
• 在自定义的 docs 块中添加 Markdown 文档，直接在你的 stories.vue 文件中（详情见下文）
• 显示的组件只需声明一次（通过 <Stories :component="...">），而不是每个 Story 都需要声明
• 与 Storybook 的简单集成和自动的 Vite 支持
• 轻量：Vue Stories 会在运行时被转译成普通的 CSF Stories，开销极小

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

以惯用 Vue 模板形式编写 Stories 的方式深受出色的 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 添加到 stories patterns 中，并将 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 块，直接在你的 Story 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 的易读语法（例如 # 标题）、包含 Stories，并随时在文件中自由嵌入 JSX 组件块。更多信息请参阅 Storybook 文档。与标准的 MDX 文档页面有一些细微差异

• <Meta of=...> 标签不是必需的。
• 你无需导入 Stories 文件。只需按名称引用已定义的 Stories 即可。例如：

  <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 Stories，你可能希望通过将 storybook-vue-addon 添加到构建中，先将 Vue Stories 转译为经典的 CSF Stories。

// 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: 运行 playground（目前未使用）。
• release: 发布新版本到 npm。

赞助商

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