获课：xingkeit.top/8974/

Vue3 组合式 API + TS4：从零搭建规范前端组件的实战思路

选 Vue3 组合式 API 写组件，再加 TypeScript 做类型约束，是 2025 年前端工程化的标准答案。但问题不在"用什么"，而在"怎么用才规范"。这篇文章不贴代码，只讲思路和坑。

一、为什么必须是组合式 API + TS

选项式 API 在小组件里写着爽，但一旦组件超过 80 行，逻辑分散在 data、methods、computed、watch 里，维护起来就是灾难。组合式 API 的核心优势：按功能聚合代码。一个功能相关的响应式数据、计算属性、副作用，全部放在一起，阅读成本直降一半。

TypeScript 的价值不在"防错"，而在自文档化。当你看到一个函数的参数类型，就知道该传什么；看到一个接口定义，就知道数据长什么样。配合 VSCode 的智能提示，开发效率提升不是一点点。

二、组件拆分的第一原则：单一职责

一个组件只做一件事。

弹窗就是弹窗，别把表单逻辑塞进去。表格就是表格，别把业务判断写在模板里。拆分的依据不是"好不好看"，而是"变不变"。频繁变动的逻辑抽成独立函数或组合式函数，稳定的 UI 结构留在模板里。

举例：一个商品卡片组件，数据获取、价格格式化、收藏状态切换，这三件事应该各是一个独立的组合式函数，在 setup 里按需组合。这样测试的时候，每个函数都能单独验证。

三、类型定义是地基，不是装饰

TS4 最容易踩的坑：any 泛滥。

规范做法是：所有外部传入的 props，必须定义接口；所有组件内部的状态，必须标注类型；所有函数的参数和返回值，必须显式声明。 宁可多写一行类型，也不要用 any 偷懒。因为 any 会传染——一个 any 出现，TS 的类型收窄全部失效，等于没写。

特别注意 props 的类型定义。用 defineProps<接口>() 的泛型写法，而不是运行时声明。这样才能在父组件传参时获得完整的类型检查。

四、组合式函数才是真正的复用单元

Vue3 最被低估的能力：组合式函数（Composable）。

它本质上就是一个带响应式的普通函数。比如"获取列表数据"这个逻辑，在十个页面都要用，那就抽成一个 useList 函数，接收 URL 和参数，返回数据、加载状态、错误信息。任何组件需要列表，直接调用，不用复制粘贴。

命名约定：必须以 use 开头。这不是建议，是社区共识，也是 ESLint 规则能识别的唯一标识。

五、模板里的 TS 边界

模板中能用的 TS 能力有限。复杂的类型判断、类型收窄，不要放在模板里，用计算属性或方法承接。模板只负责展示，逻辑全部下沉到 script 层。

另外，v-if 和 v-for 不要同时出现在一个元素上。这条规则在 Vue3 里依然有效，TS 帮不了你，只能靠规范约束。

六、一句话总结

Vue3 组合式 API 解决的是代码组织问题，TS4 解决的是信任问题。两者结合，前端组件才能从"能跑就行"进化到"敢交给团队长期维护"。先定类型，再拆逻辑，最后写模板——顺序反了，后面全是债。