Varlet UI 组件库中 setup 模式与外部类型声明的最佳实践

背景介绍

Varlet UI 是一个基于 Vue 3 的移动端组件库，随着 Vue 3 的 Composition API 和 <script setup> 语法的普及，开发者希望将组件迁移到更现代的写法。但在迁移过程中遇到了类型声明和构建方面的一些技术挑战。

问题核心

在将 Row 组件从 Options API 迁移到 <script setup> 语法时，主要遇到了两个技术难点：

1. 类型声明外部化问题：当把组件的 props 类型定义提取到单独的文件中时，构建系统无法正确解析这些类型声明。

2. 组件实例暴露控制：<script setup> 默认会关闭组件实例的暴露，需要显式控制哪些属性和方法应该对外暴露。

技术解决方案

类型声明外部化的构建问题

在传统的 Options API 中，props 的类型定义直接写在组件内部。而在 <script setup> 中，我们更倾向于将类型定义提取到单独的 .ts 文件中：

// props.ts
export interface rowProps {
  gutter?: RowGutter;
  justify?: RowJustify;
  align?: RowAlign;
  onClick?: ListenerProp<(e: Event) => void>;
}

构建时出现问题的根本原因是 Varlet 的构建系统需要特殊处理这些外部类型引用。我们提出了几种解决方案：

1. 路径重定向方案：在构建过程中将 /es/ 路径重定向到 /src/ 路径，确保能找到源文件。

2. 编译顺序优化：先编译所有 .vue 文件，再处理其他文件类型，确保类型声明可用。

3. 宏声明预处理：在构建前处理类型宏声明，避免构建时的解析问题。

组件实例暴露控制

Vue 3 提供了多种方式控制组件实例的暴露：

1. defineExpose 编译器宏（<script setup> 中使用）：

defineExpose({
  publicMethod,
  publicProperty
})

2. expose() 函数（setup 函数中使用）：

setup(props, { expose }) {
  expose({
    publicMethod() {}
  })
}

3. 完全关闭暴露：

expose() // 不暴露任何内容

实践建议

1. 类型定义策略：

   • 简单类型可以直接内联在组件中
   • 复杂类型或复用类型可以提取到单独文件
   • 确保构建系统能正确处理类型引用

2. 组件暴露控制：

   • 明确设计组件的公共 API
   • 只暴露必要的属性和方法
   • 内部实现细节应该隐藏

3. 构建系统适配：

   • 需要扩展构建逻辑处理 setup 语法
   • 考虑类型声明的解析顺序
   • 处理宏定义的静态分析

总结

迁移到 <script setup> 语法可以带来更好的开发体验和类型支持，但也需要考虑构建系统的适配和组件设计模式的调整。Varlet UI 作为一个成熟的组件库，需要在现代化开发体验和稳定性之间找到平衡点。通过合理的类型定义策略和暴露控制，可以构建出既灵活又安全的组件 API。