TypeScript泛型实战：类型体操在Vue3组件库设计中的工程应用

TypeScript泛型是构建类型安全组件库的核心工具。Vue3配合TypeScript开发组件库时，泛型约束、条件类型和映射类型能够实现Props类型自动推导、表单数据类型联动、API响应类型安全等高级场景。本文从实际组件库开发中提炼泛型设计模式，提供可直接复用的类型定义方案。

泛型约束与条件类型推导

组件库的基础场景是根据Props配置自动推导事件回调的参数类型。通过泛型约束（Generic Constraints）可以建立Props与Emits之间的类型关联。

// 定义列配置类型
interface TableColumn<T> {
  prop: keyof T
  label: string
  width?: number
  formatter?: (value: T[keyof T], row: T) => string
}

// 条件类型：根据是否传入formatter推导返回值
type ColumnResult<T, C extends TableColumn<T>> =
  C extends { formatter: infer F }
    ? F extends (value: any, row: T) => infer R
      ? R
      : T[keyof T]
    : T[keyof T]

// 使用示例
interface UserRow {
  id: number
  name: string
  status: 0 | 1
}

const columns: TableColumn<UserRow>[] = [
  { prop: 'id', label: 'ID' },
  { prop: 'name', label: '姓名' },
  {
    prop: 'status',
    label: '状态',
    formatter: (val) => val === 1 ? '启用' : '禁用'
  }
]

泛型参数T约束了列配置中prop字段只能是数据对象的key，formatter的value参数类型自动推导为对应字段的类型。传错字段名或formatter参数类型不匹配时，编译阶段直接报错。

映射类型与工具类型实战

表单组件库需要根据字段配置自动生成表单数据结构。映射类型（Mapped Types）可以将配置类型转换为数据类型。

// 表单字段配置
type FormField = {
  type: 'input' | 'select' | 'date'
  required: boolean
  options?: { label: string; value: string }[]
}

// 映射类型：将字段配置转为表单数据类型
type FormData<T extends Record<string, FormField>> = {
  [K in keyof T]: T[K] extends { type: 'select'; options: infer O }
    ? O extends { value: infer V }[] ? V : string
    : T[K] extends { type: 'date' }
      ? string
      : string
}

// Partial化工具：可选字段自动标记
type OptionalFormData<T extends Record<string, FormField>> = {
  [K in keyof T as T[K] extends { required: true } ? K : never]: FormData<T>[K]
} & {
  [K in keyof T as T[K] extends { required: true } ? never : K]?: FormData<T>[K]
}

// 实际使用
const formConfig = {
  username: { type: 'input', required: true },
  role: { type: 'select', required: true, options: [
    { label: '管理员', value: 'admin' },
    { label: '用户', value: 'user' }
  ]},
  birthday: { type: 'date', required: false }
}

type MyFormData = OptionalFormData<typeof formConfig>
// 推导结果：
// { username: string; role: string; birthday?: string }

Vue3组件Props类型安全设计

Vue3的defineProps配合TypeScript泛型，可以实现Props类型的完整推导。组件库中的通用组件通过泛型暴露配置接口。

//useTable.ts - 表格组合式函数
import { ref, type Ref } from 'vue'

interface UseTableOptions<T> {
  data: Ref<T[]>
  rowKey: keyof T
  selectable?: boolean
}

interface UseTableReturn<T> {
  selectedRows: Ref<T[]>
  toggleRow: (row: T) => void
  isSelected: (row: T) => boolean
  getSelectedKeys: () => T[keyof T][]
}

export function useTable<T extends Record<string, any>>(
  options: UseTableOptions<T>
): UseTableReturn<T> {
  const selectedRows = ref<T[]>([]) as Ref<T[]>

  const toggleRow = (row: T) => {
    const idx = selectedRows.value.findIndex(
      r => r[options.rowKey] === row[options.rowKey]
    )
    if (idx >= 0) {
      selectedRows.value.splice(idx, 1)
    } else {
      selectedRows.value.push(row)
    }
  }

  const isSelected = (row: T) =>
    selectedRows.value.some(r => r[options.rowKey] === row[options.rowKey])

  const getSelectedKeys = () =>
    selectedRows.value.map(r => r[options.rowKey])

  return { selectedRows, toggleRow, isSelected, getSelectedKeys }
}

API请求层泛型封装

前端工程化中API层类型安全是高频需求。通过泛型封装请求函数，实现请求参数和响应数据的类型联动。

// request.ts - 泛型请求封装
interface ApiResponse<T> {
  code: number
  data: T
  message: string
}

interface RequestOptions {
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE'
  params?: Record<string, any>
  body?: Record<string, any>
}

async function request<T>(
  url: string,
  options: RequestOptions = {}
): Promise<T> {
  const response = await fetch(url, {
    method: options.method || 'GET',
    headers: { 'Content-Type': 'application/json' },
    body: options.body ? JSON.stringify(options.body) : undefined,
  })
  const result: ApiResponse<T> = await response.json()
  if (result.code !== 0) {
    throw new Error(result.message)
  }
  return result.data
}

// API定义层 - 每个接口类型完整推导
interface UserListParams {
  page: number
  pageSize: number
  keyword?: string
}

interface UserListItem {
  id: number
  name: string
  email: string
}

// 请求参数和返回值类型完整约束
export const userApi = {
  getList: (params: UserListParams) =>
    request<{ list: UserListItem[]; total: number }>('/api/users', { params }),

  getById: (id: number) =>
    request<UserListItem>(`/api/users/${id}`),

  create: (data: Omit<UserListItem, 'id'>) =>
    request<UserListItem>('/api/users', { method: 'POST', body: data }),
}

组件库类型导出与版本兼容

组件库发布npm包时，类型定义文件的质量直接影响使用方的开发体验。需要在package.json中正确配置types入口。

// package.json
{
  "name": "@yunthe/ui-components",
  "version": "1.0.0",
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/types/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/types/index.d.ts"
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "types": "./dist/types/utils.d.ts"
    }
  },
  "files": ["dist"]
}

// tsconfig.json - 确保生成声明文件
{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "dist/types",
    "emitDeclarationOnly": false,
    "isolatedModules": true,
    "stripInternal": true
  }
}

类型体操在组件库中的应用远不止上述场景。高阶组件的类型透传、插槽内容的类型约束、动态组件的props校验、组合式函数的返回值类型推导，都可以通过泛型约束和条件类型实现。关键原则是让类型系统承担更多的校验工作，将运行时可能出现的类型错误提前到编译阶段暴露。组件库迭代过程中保持类型定义向后兼容，通过版本号和changelog标注类型变更，避免使用方在升级时遇到类型报错。