Storybook项目：Vue3+Vite项目集成指南

最新推荐文章于 2025-06-11 08:53:22 发布

施笛娉Tabitha

最新推荐文章于 2025-06-11 08:53:22 发布

阅读量257

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00696/article/details/148323249

Storybook项目：Vue3+Vite项目集成指南

storybook 项目地址: https://gitcode.com/gh_mirrors/sto/storybook

前言

在现代前端开发中，组件化开发已经成为主流趋势。Storybook作为一款优秀的UI组件开发环境，能够帮助开发者独立构建、测试和文档化UI组件。本文将详细介绍如何在Vue3+Vite项目中集成和使用Storybook。

环境要求

在开始之前，请确保您的开发环境满足以下要求：

Vue版本 ≥ 3.0
Vite版本 ≥ 4.0
Storybook版本 ≥ 8.0

安装与初始化

全新项目初始化

对于尚未集成Storybook的Vue3+Vite项目，可以通过以下命令快速初始化：

npx storybook@latest init

该命令会自动检测项目类型并安装所有必要的依赖项，同时创建基础的Storybook配置文件。

已有Storybook项目升级

如果项目中已经存在Storybook，需要先升级到7+版本：

npx storybook@latest upgrade

升级完成后，系统会提示是否迁移到@storybook/vue3-vite框架。如果自动迁移失败，可以按照以下步骤手动迁移：

安装框架依赖：

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

修改.storybook/main.js|ts配置文件：

// .storybook/main.js
export default {
  framework: {
    name: '@storybook/vue3-vite',
    options: {}
  }
}

Vue应用扩展配置

Storybook会为组件预览创建一个独立的Vue3应用实例。如果您需要在全局范围内注册组件、指令或插件，可以在.storybook/preview.js文件中进行配置：

import { setup } from '@storybook/vue3';
import MyPlugin from './my-plugin';

setup((app) => {
  // 注册全局组件
  app.component('MyComponent', MyComponent);
  
  // 使用插件
  app.use(MyPlugin);
  
  // 添加全局mixin
  app.mixin({
    created() {
      console.log('Global mixin created hook');
    }
  });
});

组件文档生成工具

Storybook 8.0引入了对vue-component-meta的支持，这是Vue官方团队维护的组件元数据提取工具，相比传统的vue-docgen-api功能更加强大。

启用vue-component-meta

在.storybook/main.ts中配置：

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

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

export default config;

主要特性

全面的组件类型支持：
- 支持SFC、函数式组件、组合式API和选项式API
- 支持.vue、.ts、.tsx、.js和.jsx文件
- 支持默认导出和命名导出组件

完善的属性文档：

interface Props {
  /** 用户姓名 */
  name: string;
  /**
   * 组件分类
   * @since 8.0.0
   */
  category?: string;
}

事件类型提取：

interface Events {
  /** 当项目变更时触发 */
  (event: 'change', item?: Item): void;
  /** 当项目删除时触发 */
  (event: 'delete', id: string): void;
}

插槽文档生成：

defineSlots<{
  /** 默认插槽描述 */
  default(props: { num: number }): any;
  /** 具名插槽描述 */
  named(props: { str: string }): any;
}>();

暴露属性和方法：

defineExpose({
  /** 标签文本 */
  label: ref('Button'),
  /** 计数器 */
  count: ref(100)
});

特殊配置

对于使用TypeScript项目引用的项目，需要指定特定的tsconfig文件：

options: {
  docgen: {
    plugin: 'vue-component-meta',
    tsconfig: 'tsconfig.app.json'
  }
}

常见问题解决

Vue2项目支持

Vue2已于2023年12月31日停止维护。如果您的项目仍在使用Vue2，建议尽快升级到Vue3。如果暂时无法升级，可以安装Storybook 7的最后一个支持Vue2的版本：

npx storybook@7 init

高级配置

Storybook提供了丰富的配置选项，可以通过.storybook/main.ts文件进行定制：

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

const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: 'vue-component-meta',
      builder: {
        // Vite构建器特定配置
      }
    }
  }
};

export default config;