使用 Vite 的 Vue Storybook

Storybook for Vue & Vite 是一个 framework，它可以轻松地为使用 Vite 构建的 Vue 应用单独开发和测试 UI 组件。

¥Storybook for Vue & Vite is a framework that makes it easy to develop and test UI components in isolation for Vue applications built with Vite.

安装

¥Install

要在现有的 Vue 项目中安装 Storybook，请在项目根目录下运行以下命令：

¥To install Storybook in an existing Vue project, run this command in your project's root directory:

npm create storybook@latest

接下来，你可以开始使用 写故事、运行测试 和 组件文档。要更好地控制安装过程，请参阅 安装指南。

¥You can then get started writing stories, running tests and documenting your components. For more control over the installation process, refer to the installation guide.

要求

¥Requirements

• 

  Vue ≥ 3

• 

  Vite ≥ 5

运行 Storybook

¥Run Storybook

要为特定项目运行 Storybook，请运行以下命令：

¥To run Storybook for a particular project, run the following:

npm run storybook

要构建 Storybook，请运行：

¥To build Storybook, run:

npm run build-storybook

你将在配置的 outputDir（默认为 storybook-static）中找到输出。

¥You will find the output in the configured outputDir (default is storybook-static).

配置

¥Configure

Storybook for Vue 3 with Vite 旨在开箱即用，只需极少的配置。本节介绍框架的配置选项。

¥Storybook for Vue 3 with Vite is designed to work out of the box with minimal configuration. This section covers configuration options for the framework.

扩展 Vue 应用

¥Extending the Vue application

Storybook 为你的组件预览创建一个 Vue 3 应用。使用全局自定义组件 (app.component)、指令 (app.directive)、扩展 (app.use) 或其他应用方法时，你需要在 ./storybook/preview.js|ts 文件中对其进行配置。

¥Storybook creates a Vue 3 application for your component preview. When using global custom components (app.component), directives (app.directive), extensions (app.use), or other application methods, you will need to configure those in the ./storybook/preview.js|ts file.

因此，Storybook 为你提供了从此包导出的 setup 函数。此函数以回调的形式接收你的 Storybook 实例，你可以与其交互并添加自定义配置。

¥Therefore, Storybook provides you with a setup function exported from this package. This function receives your Storybook instance as a callback, which you can interact with and add your custom configuration.

import { setup } from '@storybook/vue3-vite';
 
setup((app) => {
  app.use(MyPlugin);
  app.component('my-component', MyComponent);
  app.mixin({
    // My mixin
  });
});

使用 vue-component-meta

¥Using vue-component-meta

vue-component-meta 是由 Vue 团队维护的工具，可从 Vue 组件中提取元数据。Storybook 可以使用它来为你的故事和文档生成 controls。它是 vue-docgen-api 的功能更全面的替代方案，推荐用于大多数项目。

¥vue-component-meta is a tool maintained by the Vue team that extracts metadata from Vue components. Storybook can use it to generate the controls for your stories and documentation. It's a more full-featured alternative to vue-docgen-api and is recommended for most projects.

如果你想使用 vue-component-meta，你可以在 .storybook/main.js|ts 文件中进行配置：

¥If you want to use vue-component-meta, you can configure it in your .storybook/main.js|ts file:

import type { StorybookConfig } from '@storybook/vue3-vite';
 
const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: 'vue-component-meta',
    },
  },
};
 
export default config;

vue-component-meta 具有许多优点并支持更多文档功能，例如：

¥vue-component-meta comes with many benefits and enables more documentation features, such as:

支持多种组件类型

¥Support for multiple component types

vue-component-meta 支持来自 .vue、.ts、.tsx、.js 和 .jsx 文件的所有类型的 Vue 组件（包括 SFC、函数式、组合/选项 API 组件）。

¥vue-component-meta supports all types of Vue components (including SFC, functional, composition/options API components) from .vue, .ts, .tsx, .js, and .jsx files.

它还支持默认和命名组件导出。

¥It also supports both default and named component exports.

Prop 描述和 JSDoc 标签注释

¥Prop description and JSDoc tag annotations

要描述 prop（包括标签），你可以在组件的 props 定义中使用 JSDoc 注释：

¥To describe a prop, including tags, you can use JSDoc comments in your component's props definition:

<script setup lang="ts">
  interface MyComponentProps {
    /** The name of the user */
    name: string;
    /**
 
      * The category of the component
 
      *       * @since 8.0.0
      */
    category?: string;
  }
 
  withDefaults(defineProps<MyComponentProps>(), {
    category: 'Uncategorized',
  });
</script>

上面的 props 定义将生成以下控件：

¥The props definition above will generate the following controls:

事件类型提取

¥Events types extraction

要为发出的事件提供类型，你可以在组件的 defineEmits 调用中使用 TypeScript 类型（包括 JSDoc 注释）：

¥To provide a type for an emitted event, you can use TypeScript types (including JSDoc comments) in your component's defineEmits call:

<script setup lang="ts">
  type MyChangeEvent = 'change';
 
  interface MyEvents {
    /** Fired when item is changed */
    (event: MyChangeEvent, item?: Item): void;
    /** Fired when item is deleted */
    (event: 'delete', id: string): void;
    /** Fired when item is upserted into list */
    (e: 'upsert', id: string): void;
  }
 
  const emit = defineEmits<MyEvents>();
</script>

这将生成以下控件：

¥Which will generate the following controls:

插槽类型提取

¥Slots types extraction

插槽类型会自动从组件定义中提取并显示在控制面板中。

¥The slot types are automatically extracted from your component definition and displayed in the controls panel.

<template>
  <slot :num="123"></slot>
  <br />
  <slot name="named" str="str"></slot>
  <br />
  <slot name="no-bind"></slot>
  <br />
  <slot name="vbind" v-bind="{ num: 123, str: 'str' }"></slot>
</template>
 
<script setup lang="ts"></script>

如果你使用 defineSlots，你可以在组件的插槽定义中使用 JSDoc 注释描述每个插槽：

¥If you use defineSlots, you can describe each slot using JSDoc comments in your component's slots definition:

defineSlots<{
  /** Example description for default */
  default(props: { num: number }): any;
  /** Example description for named */
  named(props: { str: string }): any;
  /** Example description for no-bind */
  noBind(props: {}): any;
  /** Example description for vbind */
  vbind(props: { num: number; str: string }): any;
}>();

上面的定义将生成以下控件：

¥The definition above will generate the following controls:

公开的属性和方法

¥Exposed properties and methods

组件公开的属性和方法将自动提取并显示在 控件 面板中。

¥The properties and methods exposed by your component are automatically extracted and displayed in the Controls panel.

<script setup lang="ts">
  import { ref } from 'vue';
 
  const label = ref('Button');
  const count = ref(100);
 
  defineExpose({
    /** A label string */
    label,
    /** A count number */
    count,
  });
</script>

上面的定义将生成以下控件：

¥The definition above will generate the following controls:

覆盖默认配置

¥Override the default configuration

如果你正在使用依赖 tsconfig references 链接到其他现有配置文件（例如 tsconfig.app.json、tsconfig.node.json）的项目，我们建议你更新 .storybook/main.js|ts 配置文件并添加以下内容：

¥If you're working with a project that relies on tsconfig references to link to other existing configuration files (e.g., tsconfig.app.json, tsconfig.node.json), we recommend that you update your .storybook/main.js|ts configuration file and add the following:

import type { StorybookConfig } from '@storybook/vue3-vite';
 
const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: {
        plugin: 'vue-component-meta',
        tsconfig: 'tsconfig.app.json',
      },
    },
  },
};
 
export default config;

否则，你可能会遇到缺少组件类型/描述或无法解析的导入别名（如 @/some/import）的情况。

¥Otherwise, you might face missing component types/descriptions or unresolvable import aliases like @/some/import.

常见问题

¥FAQ

如何手动安装 Vue 框架？

¥How do I manually install the Vue framework?

首先，安装框架：

¥First, install the framework:

npm install --save-dev @storybook/vue3-vite

然后，更新你的 .storybook/main.js|ts 以更改框架属性：

¥Then, update your .storybook/main.js|ts to change the framework property:

import type { StorybookConfig } from '@storybook/vue3-vite';
 
const config: StorybookConfig = {
  // ...
  framework: '@storybook/vue3-vite', // 👈 Add this
};
 
export default config;

Storybook 无法与我的 Vue 2 项目配合使用

¥Storybook doesn't work with my Vue 2 project

Vue 2 已进入生命周期结束阶段（EOL）将于 2023 年 12 月 31 日停止使用，Vue 团队不再维护。因此，Storybook 不再支持 Vue 2。我们建议你将项目升级到 Vue 3，Storybook 完全支持该版本。如果那不是一个选项，你仍然可以通过使用以下命令安装最新版本的 Storybook 7 将 Storybook 与 Vue 2 一起使用：

¥Vue 2 entered End of Life (EOL) on December 31st, 2023, and is no longer maintained by the Vue team. As a result, Storybook no longer supports Vue 2. We recommend you upgrade your project to Vue 3, which Storybook fully supports. If that's not an option, you can still use Storybook with Vue 2 by installing the latest version of Storybook 7 with the following command:

npx storybook@^7 init

API

选项

¥Options

如果需要，你可以传递一个选项对象以进行其他配置：

¥You can pass an options object for additional configuration if needed:

import type { StorybookConfig } from '@storybook/vue3-vite';
 
const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: 'vue-component-meta',
    },
  },
};
 
export default config;

builder

类型：Record<string, any>

¥Type: Record<string, any>

配置 框架的构建器 的选项。对于此框架，可以在 Vite 构建器文档 中找到可用选项。

¥Configure options for the framework's builder. For this framework, available options can be found in the Vite builder docs.

docgen

类型：'vue-docgen-api' | 'vue-component-meta' | boolean

¥Type: 'vue-docgen-api' | 'vue-component-meta' | boolean

默认：'vue-docgen-api'

¥Default: 'vue-docgen-api'

自：8.0

¥Since: 8.0

选择在为组件生成控件时使用哪个 docgen 工具。有关更多信息，请参阅 使用 vue-component-meta。

¥Choose which docgen tool to use when generating controls for your components. See Using vue-component-meta for more information.

设置为 false 可完全禁用文档生成处理，以提高构建性能。

¥Set to false to disable docgen processing entirely for improved build performance.

import type { StorybookConfig } from '@storybook/vue3-vite';
 
const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: false, // Disable docgen for better performance
    },
  },
};
 
export default config;

何时禁用文档生成器 (docgen)？

¥When to disable docgen

禁用文档生成可以提高大型项目的构建性能，但 argTypes 将不会自动推断 会导致 控件 和 docs 等功能无法正常工作。要使用这些功能，需要使用 手动定义 argTypes。

¥Disabling docgen can improve build performance for large projects, but argTypes won't be inferred automatically, which will prevent features like Controls and docs from working as expected. To use those features, you will need to define argTypes manually.