vue

用途

该技能为 Vue 3 项目提供框架层面的编码约定与架构指导，适用于编写或审查 Vue 组件、响应式逻辑、可组合函数与 TypeScript 类型集成等任务。其定位是：编码技能负责工作流，语言技能负责 JS/TS 选择，本技能负责组件架构、响应式模式与框架 API 用法。

核心理念

组合式 API 是默认选择，<script setup> 是默认语法。若使用选项式 API，需要有明确理由。Vue 3 鼓励显式、可组合的代码：优先 ref() 而非 reactive()，优先可组合函数而非 mixin，优先类型化 props 而非仅运行时校验。每个主题在对应参考文件中包含扩展示例、理由与边界情况。

参考文件

响应式：ref 解包、侦听器、计算属性边界情况
单文件组件：编译器宏目录、作用域样式、模板引用
组件：props、emits、插槽、provide/inject
可组合函数：设计模式、组合方式、限制
TypeScript：工具类型表、泛型组件、事件类型
性能：更新优化、大列表、性能分析

响应式

响应式原语选择：ref() 为默认选择，适用于任意值类型；reactive() 用于无需解构的相关状态分组；shallowRef() 用于大型不可变结构或外部状态集成；shallowReactive() 仅根级响应式；computed() 用于派生状态，依赖变化前缓存。ref() 是主要 API：可用于原始类型，可从可组合函数返回值中解构而不丢失响应性，可重新赋值，脚本中统一使用 .value，模板中自动解包顶层 ref。reactive() 的局限：不能持有原始类型，重新赋值会丢失响应性，解构原始类型会丢失响应性（如需解构用 toRefs()）。不要将 reactive() 作为主要原语。

Ref 解包规则：模板中顶层 ref 自动解包；普通对象中非顶层 ref 不解包；reactive() 对象内嵌套 ref 自动解包；reactive 数组/集合内 ref 不解包，需 .value。

计算属性：保持 getter 纯净，无副作用；拆分复杂计算；缓存值，依赖变化时重算；3.4+ 计算属性稳定性，仅在返回值实际变化时触发副作用，避免从计算属性返回新对象；可写计算属性较少使用，需 get/set 形式。

侦听器：watch() 与 watchEffect() 的选择依据是是否需要旧值、是否惰性执行、是否侦听特定源、是否需要条件侦听。watch() 选项包括 immediate、deep，以及侦听 getter、多个源；两者均支持 onCleanup 清理。

DOM 更新时机：响应式状态变更批量更新到下一 tick，使用 nextTick() 处理 DOM 更新后逻辑。

单文件组件

块顺序：始终 <script setup> 在前，<template> 其次，<style> 最后。

编译器宏：<script setup> 中无需导入的宏包括 defineProps()、defineEmits()、defineModel()；defineOptions() 用于 name、inheritAttrs 等选项。

模板语法：指令简写保持一致，:prop、@event、#slot；条件渲染 v-if/v-else-if/v-else 用于少变条件，v-show 用于频繁切换；模板引用 3.5+ 用 useTemplateRef，3.5 之前用 ref。

作用域样式：默认使用 <style scoped>，全局样式仅在 App.vue 或布局中使用；子组件根元素受父子双方作用域样式影响；深度选择器 .parent :deep(.child-class) 少量使用；CSS modules 用 <style module>；v-bind(color) 可在样式中使用响应式值。

组件

命名：始终多词名称，如 TodoItem 而非 Item；SFC 模板中 PascalCase；文件名 PascalCase；展示型组件用 Base 前缀；紧密耦合子组件用父前缀；层级最高词在前以分组；使用完整单词，不用缩写；每个文件一个组件；无子组件用自闭合标签；JS/TS 导入用 PascalCase。

Props：TypeScript 项目用 defineProps<T>() 类型式，JS 项目用对象语法，不提交数组语法；声明用 camelCase，模板用 kebab-case；不直接修改 props，转换用 computed()，本地副本用 ref() 加初始值；单向数据流；3.5+ 解构 props 具响应性；解构 props 传可组合函数用 getter。

Emits：用 defineEmits() 声明，优先类型式；emit camelCase，监听 kebab-case；3.3+ 命名元组语法。

v-model：用 defineModel<T>()；命名 v-model 用 defineModel<string>('firstName')。

插槽：默认插槽、具名插槽、作用域插槽通过 slot props 传数据。

Provide / Inject：用 Symbol 键（InjectionKey<T>）保证类型安全；从共享 keys.ts 导出；提供 readonly() ref 防止消费者修改；需要修改时提供更新函数；始终提供默认值或处理 undefined。

模板规则：v-for 始终有 :key；不要在同一元素同时用 v-if 与 v-for；模板中仅简单表达式；多属性元素每行一个属性。

可组合函数

设计：始终 use 前缀，camelCase 命名，表示使用 Vue 响应式且必须在 setup() 或 <script setup> 内调用。

结构顺序：响应式状态、修改状态的逻辑、副作用生命周期钩子、返回 ref。

返回值：始终返回包含 ref 的普通对象，不返回 reactive() 对象。

输入参数：接受 ref、getter 和原始值，用 toValue() 与 MaybeRefOrGetter<T> 在 watchEffect 内规范化输入。

副作用与清理：在 onUnmounted() 中清理副作用；SSR 安全，DOM 相关副作用放在 onMounted()/onUnmounted()。

组合：可组合函数可调用其他可组合函数。

使用限制：必须在 <script setup> 或 setup() 内同步调用；例外是 <script setup> 在 await 后恢复活动实例，故 await 后可用；在生命周期钩子内可接受。

与替代方案对比：mixin 属性来源不清、命名冲突、隐式耦合；无渲染组件有额外实例开销；工具函数无响应式状态与生命周期钩子。

TypeScript

Props：用 defineProps<T>() 配合接口；3.5+ 解构默认值；3.4 及以下用 withDefaults；可变引用默认值（数组、对象）必须用工厂函数；3.3 起支持导入类型。

Emits：3.3+ 命名元组语法。

Refs：从初始值推断类型；联合类型用显式类型；可空用 ref<User | null>(null)；无初始值 ref<ResponseData>() 产生 Ref<ResponseData | undefined>。

Computed：类型推断，必要时用显式泛型。

Reactive：用接口注解，不用 reactive<T>() 泛型。

模板引用：3.5+ 用 useTemplateRef；组件引用用 InstanceType<typeof MyComponent>；3.5 之前用 ref。

Provide / Inject：用 InjectionKey<T>；字符串键需泛型注解。

泛型组件：<script setup> 上使用 generic 属性。

事件处理器：显式类型化 DOM 事件。

工具类型：Ref<T>、ComputedRef<T>、MaybeRefOrGetter<T>、InjectionKey<T>、PropType<T>、ComponentPublicInstance。

性能

页面加载：路由级代码分割用动态导入；组件级用 defineAsyncComponent()；优先可摇树依赖（lodash-es）；<script setup> 编译产物更利于压缩。

更新性能：props 稳定性，传派生布尔值；v-once 用于静态内容；v-memo 有条件跳过子树更新，用于大部分项不变的 v-for 列表；3.4+ 计算属性稳定性，避免返回新对象。

大列表：1000+ 项用虚拟滚动；大型不可变数据集用 shallowRef()；避免大列表中不必要的包装组件。

侦听性能：避免大对象 deep: true；昂贵回调节流/防抖。

性能分析：app.config.performance = true；使用 Chrome DevTools Performance 面板与 Vue DevTools profiler；先测量再优化。

应用方式

编写 Vue 代码时：静默应用所有约定，不逐条叙述；若现有代码库与约定矛盾，遵循代码库并一次性标记分歧；始终使用 <script setup>，除非有文档化理由不使用。审查 Vue 代码时：引用具体违规并内联展示修复；不空谈规则，指出问题与修复方法。

限制

该资料为技能说明文档，未提供价格、收费模式、独立安装命令或运行平台等信息，这些内容暂未提供。

技能介绍