🎯 组件库项目规划与初始化

核心概念与价值
组件库是一系列可复用UI组件的集合，通常以npm包的形式发布。它能显著提升开发效率、保证UI风格一致性、提高代码质量并促进团队协作。

项目初始化与结构

1. 使用官方脚手架：推荐使用 create-vue 创建 TypeScript 就绪的 Vue 项目，它提供了搭建基于 Vite 且 TypeScript 就绪的 Vue 项目的选项。

   bash

   npm create vue@latest my-component-lib

2. 项目结构：初始化后的典型目录结构如下，你需要在 src/components 下存放组件，并创建入口文件 src/index.ts 用于集中导出所有组件。

   text

   my-component-lib/
   ├── src/
   │   ├── components/     # 组件源文件
   │   ├── index.ts       # 组件库主入口
   ├── package.json
   ├── tsconfig.json
   ├── vite.config.ts    # Vite 配置文件
   └── ...

⚙️ 开发环境与工具链配置

TypeScript 配置

1. tsconfig.json 关键配置：

   json

   {
     "compilerOptions": {
       "target": "esnext",
       "useDefineForClassFields": true,
       "module": "esnext",
       "moduleResolution": "node",
       "strict": true,
       "jsx": "preserve",
       "sourceMap": true,
       "resolveJsonModule": true,
       "esModuleInterop": true,
       "lib": ["esnext", "dom"],
       "baseUrl": ".",
       "paths": {
         "@/*": ["src/*"]
       },
       "isolatedModules": true
     },
     "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"]
   }

   • 确保 "strict": true 或至少开启 "noImplicitThis"，以便在组件选项中获得更好的 this 类型检查。

   • 如果使用路径别名，需要通过 compilerOptions.paths 选项为 TypeScript 配置。

2. Vue 组件类型声明：在 src/shims-vue.d.ts 文件中声明，让 TypeScript 识别 .vue 文件。

   typescript

   declare module '*.vue' {
     import { DefineComponent } from 'vue';
     const component: DefineComponent<{}, {}, any>;
     export default component;
   }

Vite 构建配置

1. 库模式：在 vite.config.ts 中配置，这是打包组件库的关键。

   typescript

   import { defineConfig } from 'vite';
   import vue from '@vitejs/plugin-vue';
   import { resolve } from 'path';
   import dts from 'vite-plugin-dts'; // 用于生成类型声明文件
   
   export default defineConfig({
     plugins: [
       vue(),
       dts({
         outputDir: 'dist/types', // 声明文件输出目录
         insertTypesEntry: true, // 生成类型入口
       }),
     ],
     build: {
       lib: {
         entry: resolve(__dirname, 'src/index.ts'), // 组件库入口
         name: 'MyComponentLib', // 库的全局变量名（UMD格式）
         fileName: (format) => `my-lib.${format}.js`, // 输出文件名
       },
       rollupOptions: {
         // 确保外部化处理那些你不想打包进库的依赖
         external: ['vue'],
         output: {
           globals: {
             vue: 'Vue',
           },
         },
       },
       minify: true, // 压缩代码
     },
   });

🧩 组件设计与开发

定义组件（使用 defineComponent）
使用 defineComponent 全局 API 定义组件，以便 TypeScript 正确地推导出组件选项内的类型。

• 组件入口 (src/index.ts)：集中导入和导出所有组件，并实现 install 方法用于全局注册。

  typescript

  import { App } from 'vue';
  // 导入组件
  import Button from './components/Button/index.vue';
  import Input from './components/Input/index.vue';
  
  // 组件列表
  const components = [Button, Input];
  
  // 定义 install 方法
  const install = (app: App): void => {
    components.forEach(component => {
      app.component(component.name || '', component);
    });
  };
  
  // 按需导出组件
  export { Button, Input };
  
  // 默认导出 install 方法
  export default { install };

• SFC 与 TypeScript：在单文件组件中，需要在 <script> 标签上加上 lang="ts" 的 attribute。

  vue

  <script setup lang="ts">
  // 启用了 TypeScript
  import { ref } from 'vue'
  const count = ref(1)
  </script>
  <template>
    <!-- 启用了类型检查和自动补全 -->
    {{ count.toFixed(2) }}
  </template>

开发一个示例 Button 组件
在 src/components/Button 目录下创建：

1. Button.vue：

   vue

   <template>
     <button :class="['my-btn', `my-btn--${type}`]" @click="handleClick">
       <slot></slot>
     </button>
   </template>
   
   <script setup lang="ts">
   import { withDefaults } from 'vue';
   
   // 定义 Props 类型
   interface Props {
     type?: 'primary' | 'default';
   }
   
   // 定义 Props 默认值
   const props = withDefaults(defineProps<Props>(), {
     type: 'default',
   });
   
   // 定义 Events
   const emit = defineEmits<{
     (e: 'click', event: MouseEvent): void;
   }>();
   
   // 点击事件处理
   const handleClick = (event: MouseEvent) => {
     emit('click', event);
   };
   </script>
   
   <style scoped>
   .my-btn {
     padding: 8px 16px;
     border: none;
     border-radius: 4px;
     cursor: pointer;
   }
   .my-btn--primary {
     background-color: blue;
     color: white;
   }
   .my-btn--default {
     background-color: #f0f0f0;
     color: #333;
   }
   </style>

2. index.ts：导出组件。

   typescript

   import Button from './Button.vue';
   export default Button;

📦 组件库打包与发布

完善 package.json 配置
确保 package.json 包含以下关键字段，这对于发布到 npm 和用户使用至关重要：

json

{
  "name": "my-vue3-component-lib",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/my-lib.umd.cjs",
  "module": "./dist/my-lib.es.js",
  "types": "./dist/types/index.d.ts",
  "files": [
    "dist"
  ],
  "exports": {
    ".": {
      "import": "./dist/my-lib.es.js",
      "require": "./dist/my-lib.umd.cjs",
      "types": "./dist/types/index.d.ts"
    }
  },
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc --noEmit && vite build", // 构建前可执行类型检查
    "prepublishOnly": "npm run build"
  },
  "peerDependencies": {
    "vue": "^3.3.0"
  },
  "devDependencies": {
    "vue": "^3.3.0",
    "@vitejs/plugin-vue": "^5.0.0",
    "vite": "^5.0.0",
    "vite-plugin-dts": "^3.0.0",
    "typescript": "^5.0.0",
    "vue-tsc": "^1.0.0"
  }
}

打包与发布

1. 执行构建命令：运行 npm run build 后，Vite 会根据配置在 dist 目录生成打包后的文件。

2. 发布到 npm：

   • 在 npm 官网注册账号。

   • 终端执行 npm login 登录。

   • 在项目根目录执行 npm publish 发布。

🚀 组件库的使用与文档化

在项目中使用
用户可以通过以下方式使用你发布的组件库：

1. 全局注册：

   typescript

   import { createApp } from 'vue';
   import App from './App.vue';
   import MyComponentLib from 'my-vue3-component-lib';
   import 'my-vue3-component-lib/dist/style.css'; // 如果有样式文件
   
   const app = createApp(App);
   app.use(MyComponentLib);
   app.mount('#app');

2. 按需导入：用户也可以单独导入某个组件。

   vue

   <script setup lang="ts">
   import { Button } from 'my-vue3-component-lib';
   </script>
   <template>
     <Button type="primary">点击我</Button>
   </template>

组件文档化
良好的文档对组件库至关重要。

• 工具选择：可以考虑使用 Storybook 或 VitePress 来搭建组件文档站点。

• 内容要点：文档应包含组件描述、Props/Events/Slots的API说明、使用示例等。可以考虑实现自动化文档生成，以保持文档与代码同步。

💎 进阶优化与最佳实践

1. 样式处理方案：

   • 每个组件关联独立的样式文件，并在组件中导入。

   • 在入口文件 src/index.ts 中统一导入所有样式，或在 package.json 中单独导出 CSS 文件。

2. 按需加载支持：可以考虑使用 unplugin-vue-components 等插件，使用户可以实现真正的按需导入，无需手动注册组件。

3. 单元测试：为组件编写单元测试（例如使用 Vitest + Testing Library）是保证组件库质量的重要手段。

4. 持续集成/部署 (CI/CD)：配置 GitHub Actions 等CI/CD流水线，自动化执行测试、构建和发布到 npm 的流程。

🧪 动手实践建议

• 从简单开始：先实现一两个基础组件（如 Button、Input），打通从开发、打包到发布的完整流程。

• 渐进式增强：后续逐步添加复杂组件（如 Modal、Form）、完善样式主题、加入图标库、国际化支持等。

• 参考优秀开源项目：学习像 Element Plus、Ant Design Vue、Vuetify 等成熟 Vue3 组件库的设计和实现。