my-vue3-ui-lib

一个基于 Vue 3 + Vite + Storybook 的轻量级 UI 组件库示例，用于演示如何开发 Vue 组件、打包成可复用的库，并通过 Storybook 做文档化预览与交互展示。

技术栈

• 框架：Vue 3（<script setup> 语法）
• 构建工具：Vite（库模式打包）
• 组件文档：Storybook（@storybook/vue3-vite）
• 测试：Vitest + @storybook/addon-vitest + Playwright（用于运行基于 stories 的浏览器测试）

组件列表

当前库中主要包含以下组件（位于 src/lib）：

• BaseButton

  • 类型（type）：primary / success / danger
  • 尺寸（size）：small / medium / large
  • 用途：基础按钮，用于触发操作，支持在 Storybook 中查看不同类型和尺寸组合。

• Tag

  • 类型（type）：primary / success / warning / danger
  • 尺寸（size）：small / medium / large
  • 是否可关闭（closable）：boolean
  • 用途：状态/标签展示，支持可关闭标签，通过 close 事件向外通知。

所有组件通过入口 src/lib/index.js 统一导出：

• 具名导出：BaseButton, Tag
• 默认导出插件：提供 install(app)，一次性注册上述组件。

使用方式

假设你已经将本库发布到 npm，包名仍为 my-vue3-ui-lib。若只在本地/私有项目使用，可以通过 npm link 或本地路径依赖引入，使用方式相同。

1. 通过 npm 安装使用（推荐）

安装依赖：

npm install my-vue3-ui-lib
# 或
pnpm add my-vue3-ui-lib

在 Vue 3 应用入口中（例如 main.js）全局注册插件：

import { createApp } from 'vue'
import App from './App.vue'

import MyVue3UiLib from 'my-vue3-ui-lib'
import 'my-vue3-ui-lib/dist/my-vue3-ui-lib.css'

const app = createApp(App)

app.use(MyVue3UiLib)
app.mount('#app')

此时你可以在任意组件中直接使用：

<template>
  <BaseButton type="primary" size="medium">提交</BaseButton>
  <Tag type="success" closable @close="onTagClose">已完成</Tag>
</template>

也可以按需导入组件（依赖打包工具的 Tree-shaking 能力）：

import { BaseButton, Tag } from 'my-vue3-ui-lib'

2. 通过 <script> 标签直接引用（UMD）

构建后会在 dist/ 下生成：

• my-vue3-ui-lib.umd.js
• my-vue3-ui-lib.css

在不使用打包工具的场景，可以直接在页面中通过 CDN 或本地文件引入（示例为本地文件）：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>my-vue3-ui-lib demo</title>
    <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
    <link rel="stylesheet" href="./dist/my-vue3-ui-lib.css" />
    <script src="./dist/my-vue3-ui-lib.umd.js"></script>
  </head>
  <body>
    <div id="app">
      <base-button type="primary">按钮</base-button>
      <tag type="success">标签</tag>
    </div>

    <script>
      const app = Vue.createApp({})
      // UMD 形式下，全局变量名为 MyVue3UiLib
      app.use(MyVue3UiLib)
      app.mount('#app')
    </script>
  </body>
  </html>

与 Storybook 的配合使用

本项目集成了 Storybook，用于：

• 为每个组件编写 可交互的使用示例 和 文档说明
• 在浏览器中快速预览不同 props、状态组合
• 结合 Vitest 做 stories 级别的测试

相关文件位置：

• 组件 stories：src/stories/*.stories.js
• Storybook 配置：.storybook/
• Vitest + Storybook 集成配置：vite.config.js 中的 storybookTest 插件与 test.projects 配置

常用命令：

# 安装依赖
npm install

# 启动 Storybook 文档预览（推荐在开发组件时同时打开）
npm run storybook

# 启动 Vite 开发环境（示例应用 / 手动调试）
npm run dev

# 打包组件库（生成 ES / UMD + CSS）
npm run build

# 构建 Storybook 静态文档站点
npm run build-storybook

推荐的开发流程：

1. 在 src/lib 中开发或修改组件。
2. 在 src/stories 中为组件编写/更新 stories，描述典型用法和边界情况。
3. 启动 npm run storybook，实时查看组件效果，调整 API 与样式。
4. 通过 npm run build 打包出标准的组件库产物（ES + UMD），供业务项目或外部应用引用。

测试示例与说明

本项目使用 Vitest + @storybook/addon-vitest + Playwright 对 Storybook 中的 stories 进行测试。相关配置位于：

• vite.config.js 中的 test.projects[0]，名称为 storybook
• .storybook/vitest.setup.js：为 Storybook + Vitest 做必要的测试运行环境配置（如全局 mock、扩展等）

测试命令

在项目根目录下执行：

npm run test:storybook

该命令等价于：

vitest --project storybook

会使用 vite.config.js 中的 storybookTest 插件，自动查找并运行为 stories 编写的测试。

测试用例示例（基于 Storybook）

下面是一个示意性的测试用例（文件如 src/stories/Button.test.ts），展示如何对 Button 的 Story 进行测试（示例仅作文档说明，实际文件名/路径可根据需要调整）：

import { test, expect } from 'vitest'
import { composeStories } from '@storybook/testing-vue3'
import * as stories from './Button.stories'

const { Primary } = composeStories(stories)

test('BaseButton primary 渲染正确', async () => {
  const wrapper = await Primary.mount()

  expect(wrapper.text()).toContain('Primary')
  expect(wrapper.find('button').classes()).toContain('base-button--primary')
})

通过 @storybook/testing-vue3 的 composeStories，可以直接复用 stories 中已经配置好的 props、decorators 等，避免在测试中重复构造场景。

编写你自己的测试

1. 为组件编写或完善 Storybook stories（src/stories/*.stories.js 或 .tsx/.ts）。
2. 在相同目录下新增对应的测试文件，例如：
   • Button.stories.js ↔ Button.test.ts
3. 在测试文件中：
   • 使用 composeStories 或 composeStory 复用 stories
   • 使用 @storybook/test-runner 提供的工具（如需要）做更高级的浏览器级测试
4. 运行 npm run test:storybook，确保所有 story 级测试通过。