Vue 3 + TypeScript 组件封装艺术：从原理到实践

在现代前端开发中，组件化开发已成为主流模式。Vue 3 配合 TypeScript 的组合，为我们提供了更强大的类型系统和更优秀的开发体验。本文将深入探讨如何基于 Vue 3 和 TypeScript 进行高质量的组件封装，并通过实际案例展示最佳实践。

一、为什么要封装组件？

1.1 组件封装的优势 • 代码复用：避免重复造轮子

• 统一维护：一处修改，多处生效

• 团队协作：明确接口规范，降低沟通成本

• 类型安全：TypeScript 提供完善的类型检查

1.2 Vue 3 组合式 API 的优势

// 传统选项式 API vs 组合式 API
export default {
  data() {
    return { count: 0 }
  },
  methods: {
    increment() {
      this.count++
    }
  }
}

// 组合式 API
import { ref } from 'vue'
const count = ref(0)
const increment = () => count.value++

二、基础组件封装实战

2.1 创建一个按钮组件

// src/components/BasicButton.vue
<template>
  <button 
    :class="['basic-btn', type]"
    :disabled="disabled"
    @click="handleClick"
  >
    <slot></slot>
  </button>
</template>

<script lang="ts" setup>
import { withDefaults } from 'vue'

interface Props {
  type?: 'primary' | 'danger' | 'default'
  disabled?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  type: 'default',
  disabled: false
})

const emit = defineEmits<{
  (e: 'click', event: MouseEvent): void
}>()

const handleClick = (event: MouseEvent) => {
  if (!props.disabled) {
    emit('click', event)
  }
}
</script>

<style scoped>
.basic-btn {
  padding: 8px 16px;
  border-radius: 4px;
  cursor: pointer;
  transition: all 0.3s;
  
  &.primary {
    background-color: #409eff;
    color: white;
  }
  
  &.danger {
    background-color: #f56c6c;
    color: white;
  }
  
  &[disabled] {
    opacity: 0.5;
    cursor: not-allowed;
  }
}
</style>

2.2 使用组件

<template>
  <BasicButton 
    type="primary" 
    @click="handleClick"
  >
    提交表单
  </BasicButton>
</template>

<script lang="ts" setup>
import BasicButton from '@/components/BasicButton.vue'

const handleClick = (event: MouseEvent) => {
  console.log('按钮被点击', event)
}
</script>

三、高级组件封装技巧

3.1 带插槽和复杂逻辑的模态框组件

// src/components/AdvancedModal.vue
<template>
  <transition name="fade">
    <div class="modal-mask" v-show="modelValue">
      <div class="modal-container">
        <div class="modal-header">
          <h3>{{ title }}</h3>
          <button class="close-btn" @click="close">×</button>
        </div>
        
        <div class="modal-body">
          <slot name="body"></slot>
        </div>
        
        <div class="modal-footer">
          <slot name="footer">
            <BasicButton @click="close">取消</BasicButton>
            <BasicButton type="primary" @click="confirm">确认</BasicButton>
          </slot>
        </div>
      </div>
    </div>
  </transition>
</template>

<script lang="ts" setup>
import { watch } from 'vue'
import BasicButton from './BasicButton.vue'

interface Props {
  modelValue: boolean
  title?: string
}

const props = withDefaults(defineProps<Props>(), {
  title: '提示'
})

const emit = defineEmits<{
  (e: 'update:modelValue', value: boolean): void
  (e: 'confirm'): void
  (e: 'close'): void
}>()

const close = () => {
  emit('update:modelValue', false)
  emit('close')
}

const confirm = () => {
  emit('confirm')
  close()
}

// 监听外部变化
watch(() => props.modelValue, (newVal) => {
  if (newVal) {
    document.body.style.overflow = 'hidden'
  } else {
    document.body.style.overflow = ''
  }
})
</script>

<style scoped>
.modal-mask {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background-color: rgba(0, 0, 0, 0.5);
  display: flex;
  justify-content: center;
  align-items: center;
  z-index: 1000;
}

.modal-container {
  background: white;
  border-radius: 8px;
  width: 50%;
  min-width: 300px;
  max-width: 600px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.33);
}

.modal-header {
  padding: 16px;
  border-bottom: 1px solid #eee;
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.modal-body {
  padding: 16px;
}

.modal-footer {
  padding: 16px;
  border-top: 1px solid #eee;
  display: flex;
  justify-content: flex-end;
  gap: 8px;
}

.close-btn {
  background: none;
  border: none;
  font-size: 20px;
  cursor: pointer;
}

.fade-enter-active,
.fade-leave-active {
  transition: opacity 0.3s ease;
}

.fade-enter-from,
.fade-leave-to {
  opacity: 0;
}
</style>

3.2 使用示例

<template>
  <button @click="showModal = true">打开模态框</button>
  
  <AdvancedModal 
    v-model="showModal" 
    title="删除确认"
    @confirm="handleConfirm"
  >
    <template #body>
      <p>确定要删除这条数据吗？此操作不可撤销。</p>
    </template>
    
    <template #footer>
      <BasicButton @click="showModal = false">取消</BasicButton>
      <BasicButton type="danger" @click="handleConfirm">永久删除</BasicButton>
    </template>
  </AdvancedModal>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import AdvancedModal from '@/components/AdvancedModal.vue'
import BasicButton from '@/components/BasicButton.vue'

const showModal = ref(false)

const handleConfirm = () => {
  console.log('执行删除操作')
  // 实际业务逻辑...
}
</script>

四、组件设计原则

4.1 单一职责原则 每个组件应该只关注一个特定的功能点

4.2 受控与非受控组件 • 受控组件：状态由父组件完全控制

• 非受控组件：内部维护自身状态

4.3 接口设计规范

interface Props {
  // 基本类型
  size?: 'small' | 'medium' | 'large'
  disabled?: boolean
  
  // 复杂类型
  data?: Record<string, any>[]
  
  // 函数类型
  formatter?: (value: any) => string
}

interface Emits {
  (e: 'change', value: string): void
  (e: 'update:modelValue', value: boolean): void
}

interface Slots {
  default?: () => VNode[]
  header?: (props: { title: string }) => VNode[]
}

五、TypeScript 高级技巧

5.1 泛型组件

// 可复用的列表组件
interface ListProps<T> {
  data: T[]
  itemKey: keyof T
}

defineProps<ListProps>()

5.2 类型推断优化

// 自动推断 props 默认值类型
const props = withDefaults(defineProps<{
  size?: 'small' | 'medium'
}>(), {
  size: 'medium' // 自动推断为 'small' | 'medium'
})

5.3 全局组件类型

// components.d.ts
declare module 'vue' {
  export interface GlobalComponents {
    BasicButton: typeof import('./components/BasicButton.vue')['default']
    AdvancedModal: typeof import('./components/AdvancedModal.vue')['default']
  }
}

六、测试与文档

6.1 单元测试示例

import { mount } from '@vue/test-utils'
import BasicButton from '@/components/BasicButton.vue'

test('emits click event when clicked', async () => {
  const wrapper = mount(BasicButton, {
    slots: {
      default: 'Click me'
    }
  })
  
  await wrapper.trigger('click')
  expect(wrapper.emitted()).toHaveProperty('click')
})

6.2 组件文档（使用 Vitepress）

## BasicButton 基础按钮

### 基础用法

```vue
<template>
  <BasicButton type="primary">主要按钮</BasicButton>
</template>
```

### Props

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|-------|
| type | 按钮类型 | `'primary' | 'danger' | 'default'` | `'default'` |
| disabled | 是否禁用 | `boolean` | `false` |

### Events

| 事件名 | 说明 | 回调参数 |
|-------|------|---------|
| click | 点击事件 | `MouseEvent` |

结语

通过本文的讲解，我们了解了 Vue 3 和 TypeScript 在组件封装方面的强大能力。从基础按钮到复杂模态框，从类型定义到测试文档，一个完整的组件开发生命周期已经清晰地展现在我们面前。

记住，好的组件设计应该是： • 直观的：接口设计符合直觉

• 灵活的：通过插槽和 props 提供定制能力

• 健壮的：完善的类型定义和错误处理

• 可测试的：易于编写单元测试