设计并实现一个 Vue 组件库，支持主题定制、按需引入、TypeScript 类型提示和自动化测试。

嘿，大家好！我是你们今天的讲师，准备好一起踏上 Vue 组件库开发的奇妙旅程了吗？ 这次咱们要打造一个功能齐全、逼格满满的组件库，让你的项目从此告别 UI 难题！

第一站：架构设计，搭好组件库的骨架

咱们先来聊聊组件库的整体架构，这就像盖房子，地基必须稳固。一个好的架构能让你的组件库易于维护、扩展，还能提高开发效率。

• 目录结构：

  my-vue-component-lib/
  ├── packages/              # 组件代码
  │   ├── button/           # Button 组件
  │   │   ├── index.ts      # 组件入口
  │   │   ├── src/          # 组件源码
  │   │   │   └── Button.vue
  │   │   └── style/        # 组件样式
  │   │       └── index.scss
  │   ├── input/            # Input 组件
  │   │   ...
  │   └── ...
  ├── src/                   # 全局组件注册，指令，工具函数等
  │   ├── index.ts           # 导出所有组件
  │   └── utils/           # 一些公共方法
  ├── typings/              # 类型定义
  │   └── vue-shim.d.ts     # 声明 Vue 组件类型
  ├── theme/                 # 主题相关
  │   ├── index.scss         # 全局样式变量
  │   └── themes/
  │       ├── default.scss   # 默认主题
  │       └── dark.scss      # 暗黑主题
  ├── tests/                 # 测试用例
  │   ├── unit/             # 单元测试
  │   │   └── Button.spec.ts
  │   └── e2e/              # 端到端测试
  ├── build/                 # 构建脚本
  │   ├── rollup.config.js
  │   └── ...
  ├── docs/                  # 组件文档 (可选)
  ├── .eslintrc.js           # ESLint 配置
  ├── .prettierrc.js         # Prettier 配置
  ├── tsconfig.json          # TypeScript 配置
  ├── package.json           # 包信息
  └── README.md              # 说明文档

  这个结构清晰明了，packages 目录存放各个组件的代码，src 目录是全局组件注册和工具函数，theme 目录负责主题定制，tests 目录是测试用例，build 目录则是构建脚本。

• 技术栈：

  技术	用途
  Vue 3	组件框架
  TypeScript	类型检查，提高代码质量
  SCSS	CSS 预处理器，方便编写样式
  Rollup	打包工具，用于生成组件库的各种格式文件
  Jest/Vitest	单元测试框架
  Cypress/Playwright	端到端测试框架
  ESLint/Prettier	代码风格检查和格式化

第二站：组件开发，打造核心竞争力

咱们从最简单的 Button 组件开始，一步步构建组件库的核心。

• Button 组件代码：

  <!-- packages/button/src/Button.vue -->
  <template>
    <button
      class="my-button"
      :class="[type ? `my-button--${type}` : '', { 'my-button--plain': plain, 'my-button--round': round, 'my-button--circle': circle }]"
      :disabled="disabled"
      @click="$emit('click', $event)"
    >
      <slot></slot>
    </button>
  </template>
  
  <script lang="ts">
  import { defineComponent } from 'vue';
  
  export default defineComponent({
    name: 'MyButton',
    props: {
      type: {
        type: String,
        default: ''
      },
      plain: {
        type: Boolean,
        default: false
      },
      round: {
        type: Boolean,
        default: false
      },
      circle: {
        type: Boolean,
        default: false
      },
      disabled: {
        type: Boolean,
        default: false
      }
    },
    emits: ['click']
  });
  </script>
  
  <style lang="scss">
  @import "../../theme/index.scss";
  
  .my-button {
    display: inline-block;
    padding: 10px 20px;
    border-radius: 4px;
    border: 1px solid $--border-color-base;
    background-color: $--background-color-base;
    color: $--text-color-primary;
    font-size: 14px;
    cursor: pointer;
    transition: all 0.3s ease;
  
    &:hover {
      opacity: 0.8;
    }
  
    &--primary {
      background-color: $--color-primary;
      color: #fff;
      border-color: $--color-primary;
    }
  
    &--success {
      background-color: $--color-success;
      color: #fff;
      border-color: $--color-success;
    }
  
    &--warning {
      background-color: $--color-warning;
      color: #fff;
      border-color: $--color-warning;
    }
  
    &--danger {
      background-color: $--color-danger;
      color: #fff;
      border-color: $--color-danger;
    }
  
    &--plain {
      background-color: #fff;
    }
  
    &--round {
      border-radius: 20px;
    }
  
    &--circle {
      border-radius: 50%;
      padding: 10px; /* 调整padding以适应圆形 */
    }
  
    &:disabled {
      opacity: 0.5;
      cursor: not-allowed;
    }
  }
  </style>

  这个 Button 组件支持 type (primary, success, warning, danger)，plain，round，circle 和 disabled 属性，还使用了 slot 允许自定义内容。

• 组件入口：

  // packages/button/index.ts
  import Button from './src/Button.vue';
  import { App } from 'vue';
  
  Button.install = (app: App) => {
    app.component(Button.name, Button);
  };
  
  export default Button;

  每个组件都需要一个入口文件，用于导出组件本身，并提供 install 方法，方便全局注册。

• 全局注册：

  // src/index.ts
  import { App } from 'vue';
  import Button from '../packages/button';
  // 导入其他组件...
  
  const components = [
    Button,
    // 其他组件...
  ];
  
  const install = (app: App) => {
    components.forEach(component => {
      app.component(component.name, component);
    });
  };
  
  export {
    Button,
    // 导出其他组件...
  };
  
  export default {
    install
  };

  src/index.ts 文件负责导出所有组件，并提供 install 方法进行全局注册。这样，用户就可以通过 app.use(MyComponentLib) 来注册所有组件了。

第三站：主题定制，让你的组件库与众不同

一个优秀的组件库，必须支持主题定制，让用户可以根据自己的品牌风格来调整组件的样式。

• SCSS 变量：

  // theme/index.scss
  $--color-primary: #409EFF;
  $--color-success: #67C23A;
  $--color-warning: #E6A23C;
  $--color-danger: #F56C6C;
  $--border-color-base: #DCDFE6;
  $--background-color-base: #FFFFFF;
  $--text-color-primary: #303133;

  在 theme/index.scss 文件中定义全局 SCSS 变量，这些变量会被所有组件的样式引用。

• 主题切换：

  // 动态切换主题 (示例)
  function setTheme(themeName) {
    const themeLink = document.getElementById('theme-link');
    if (themeLink) {
      themeLink.href = `theme/themes/${themeName}.scss`;
    } else {
      const link = document.createElement('link');
      link.rel = 'stylesheet';
      link.id = 'theme-link';
      link.href = `theme/themes/${themeName}.scss`;
      document.head.appendChild(link);
    }
  }
  
  // 使用：setTheme('dark');

  你可以通过动态切换 CSS 文件的方式来实现主题切换。也可以通过 CSS variables 实现更灵活的主题定制。

第四站：按需引入，优化你的项目体积

如果用户只使用了组件库中的几个组件，全局引入会浪费带宽和性能。按需引入可以只加载需要的组件，减少项目体积。

• ES Module：

  组件库应该以 ES Module 的格式发布，这样才能支持按需引入。Rollup 会帮你处理这个问题。

• 手动引入：

  用户可以直接从组件的入口文件引入需要的组件：

  import { Button } from 'my-vue-component-lib';
  
  export default {
      components:{
      }
  }
  

• 自动按需引入 (可选)：

  可以使用 unplugin-vue-components 和 unplugin-auto-import 插件来实现自动按需引入。这两个插件会自动检测你使用了哪些组件，并自动引入它们。

第五站：TypeScript 类型提示，提升你的开发体验

TypeScript 可以提供类型检查、代码补全等功能，提高开发效率和代码质量。

• 组件类型定义：

  // typings/vue-shim.d.ts
  import { defineComponent } from 'vue';
  
  declare module '@vue/runtime-core' {
    export interface GlobalComponents {
      MyButton: typeof defineComponent;
      // 其他组件...
    }
  }

  在 typings/vue-shim.d.ts 文件中声明全局组件类型，这样在 Vue 模板中就可以使用类型提示了。

• Props 类型定义：

  在组件的 props 中使用 TypeScript 类型定义，可以确保传入的 props 类型正确。

  // packages/button/src/Button.vue
  <script lang="ts">
  import { defineComponent, PropType } from 'vue';
  
  export default defineComponent({
    name: 'MyButton',
    props: {
      type: {
        type: String as PropType<'primary' | 'success' | 'warning' | 'danger'>,
        default: ''
      },
      plain: {
        type: Boolean,
        default: false
      },
      round: {
        type: Boolean,
        default: false
      },
      circle: {
        type: Boolean,
        default: false
      },
      disabled: {
        type: Boolean,
        default: false
      }
    },
    emits: ['click']
  });
  </script>

第六站：自动化测试，保证你的代码质量

自动化测试可以帮助你发现代码中的 bug，保证组件库的质量。

• 单元测试：

  使用 Jest/Vitest 对每个组件进行单元测试，测试组件的功能是否正常。

  // tests/unit/Button.spec.ts
  import { mount } from '@vue/test-utils';
  import Button from '../../packages/button/src/Button.vue';
  
  describe('Button.vue', () => {
    it('renders default button', () => {
      const wrapper = mount(Button);
      expect(wrapper.classes()).toContain('my-button');
    });
  
    it('renders primary button', () => {
      const wrapper = mount(Button, {
        props: {
          type: 'primary'
        }
      });
      expect(wrapper.classes()).toContain('my-button--primary');
    });
  
    it('emits click event', async () => {
      const wrapper = mount(Button);
      await wrapper.trigger('click');
      expect(wrapper.emitted()).toHaveProperty('click');
    });
  });

• 端到端测试：

  使用 Cypress/Playwright 对整个组件库进行端到端测试，测试组件在真实环境中的表现。

  // tests/e2e/button.spec.js
  describe('Button', () => {
    it('should render a button', () => {
      cy.visit('/');
      cy.get('.my-button').should('exist');
    });
  
    it('should click the button', () => {
      cy.visit('/');
      cy.get('.my-button').click();
      // 添加断言...
    });
  });

第七站：构建和发布，让全世界使用你的组件库

• Rollup 配置：

  // build/rollup.config.js
  import vue from 'rollup-plugin-vue';
  import scss from 'rollup-plugin-scss';
  import typescript from '@rollup/plugin-typescript';
  import { terser } from 'rollup-plugin-terser';
  
  export default {
    input: 'src/index.ts',
    output: [
      {
        format: 'es',
        dir: 'dist/es',
        entryFileNames: '[name].js',
        chunkFileNames: '[name]-[hash].js',
      },
      {
        format: 'cjs',
        dir: 'dist/lib',
        entryFileNames: '[name].js',
        chunkFileNames: '[name]-[hash].js',
      }
    ],
    plugins: [
      vue(),
      scss({ output: 'dist/style.css' }),
      typescript({
        tsconfig: './tsconfig.json',
        declaration: true,
        declarationDir: 'dist/types'
      }),
      terser()
    ],
    external: ['vue'] // 排除 Vue，减少打包体积
  };

  Rollup 配置文件用于指定打包的入口、输出格式、插件等。

• 发布到 npm：

  1. 修改 package.json 文件，设置 name、version、description、keywords、author、license、main、module、types 等信息。
  2. 运行 npm login 登录 npm 账号。
  3. 运行 npm publish 发布组件库。

总结：

开发一个 Vue 组件库需要考虑很多方面，包括架构设计、组件开发、主题定制、按需引入、TypeScript 类型提示、自动化测试和构建发布。希望这次讲座能帮助你更好地理解组件库的开发过程，并能动手实践，打造出属于自己的优秀组件库！

记住，写代码就像谈恋爱，要用心，要投入，还要不断地学习和改进。 祝大家编码愉快！