SuperAPI AI 工具集

vuejs-modern

编程与开发

查看项目

更新于 10-28 16:10

技能介绍

用途

本技能面向 Vue 3 应用开发,旨在强制执行 Vue 3.5.x 核心最佳实践,使用严格 TypeScript,并在处理既有代码时具备迁移意识。它适用于构建、审查、迁移和调试 Vue 3 项目,要求新代码只生成现代模式,对遗留模式进行增量重构。

主要能力

  • 检测项目中的 Vue 版本家族与工具链,依据 package.json、锁文件、vite.config.、vue.config. 及 TypeScript 配置。
  • 确认任务属于 Vue 核心范围(单文件组件、响应式、侦听器、SSR 与 hydration、组件契约);Nuxt 专属规则交由 nuxt-modern 技能处理。
  • 使用严格 TypeScript,SFC 默认采用 script setup 加 lang="ts"。
  • 应用 Vue 3.5 模式,参考 references/vue-3-5-modern-patterns.md。
  • 拒绝遗留输出,更新既有代码时按 references/vue-3-legacy-replacements.md 的迁移映射处理。
  • 通过目标项目可用的类型检查、lint 和测试验证行为。

使用方式

按需加载参考文档:读取 references/vue-3-5-modern-patterns.md 获取 Vue 3.5+ 标准配方与 API 用法;读取 references/vue-3-legacy-replacements.md 获取迁移映射、兼容例外与现代化顺序。核心工作流包括:检测版本与工具链、确认任务范围、以严格 TypeScript 实现、应用 3.5 模式、拒绝遗留输出并应用迁移映射、执行验证。

实现规则摘要

  • 新代码使用 Composition API 与编译器宏;优先 defineModel() 处理组件 v-model 契约;优先 useTemplateRef() 处理字符串模板引用。
  • 在 script setup 中合理使用响应式 props 解构;侦听解构 props 时使用 getter 源,不得直接传值;组合式函数接受值、ref 或 getter 输入时使用 MaybeRefOrGetter<T> 与 toValue();在侦听器回调中,于任何 await 边界之前同步注册 onWatcherCleanup();优先使用精确 getter 作为侦听源,仅在必要时使用数值 deep。
  • SSR 与 hydration:使用 useId() 生成 SSR 安全 ID;对首屏下方重型异步组件使用惰性 hydration 策略;谨慎使用 data-allow-mismatch 并记录每种不匹配类型的理由;当目标在同一渲染 tick 稍后创建时使用 Teleport defer。
  • 性能与构建卫生:优先高杠杆优化(稳定 props、代码分割、大列表虚拟化、受控的深层响应式);在构建配置中明确编译时标志;避免无测量依据的过早微优化。
  • 遗留规避:新代码不生成 Options API、类式组件、mixins、filters 或以 this 为中心的组件逻辑;在 defineModel() 可行时不生成手动 modelValue 与 update:modelValue 样板;在 useTemplateRef() 可用且合适时不生成 ref(null) 模板引用模式;不生成在异步边界之后注册清理的侦听器代码。允许在既有代码库中为有限兼容性临时保留遗留模式,但须记录每个保留模式、保留原因及后续现代化路径。

版本约定

默认基线为 Vue 3.5.x 稳定版;Vue 3.6 beta 特性视为非默认,除非用户明确要求,否则不生成;指导内容兼容 Vue 3.5 补丁级更新,包括当前 bugfix 行为。

输出要求

生成或审查代码时始终包含:环境说明(检测到的 Vue 版本家族、TypeScript 状态与关键工具链)、版本说明(使用的 3.5.x 基线及是否刻意排除 beta 行为)、模式说明(选用了哪些现代 API 及原因)、遗留说明(移除或有意保留的遗留模式及兼容性理由)、验证说明(运行的检查类型与结果)。

适用场景

适用于 Vue 3.5.x 项目的新功能开发、代码审查、从旧模式向现代模式迁移、以及调试涉及响应式、侦听器、SSR/hydration 和组件契约的问题。不适用于 Nuxt 专属目录/运行时策略(交由 nuxt-modern)和 Tailwind 深度实现指导(交由 tailwind-modern)。

限制

不编码 Nuxt 专属策略;不提供 Tailwind 深度实现指导;Vue 3.6 beta 特性默认不生成;遗留模式仅在有限兼容场景下临时保留并需记录迁移路径。