vue-style-guide

name	vue-style-guide
description	Vue.js 官方代码规范编码指导技能。当用户在编写 Vue 组件、开发 Vue 项目、进行代码审查、设计组件结构、处理 Props/Emits/Computed 时，必须使用此技能来确保代码符合 Vue.js 官方风格指南。触发词：Vue 规范、Vue 代码风格、Vue 组件命名、Vue 最佳实践、SFC 规范、组件设计、Vue 开发规范、props 规范、Vue 模板规范、组合式 API 规范、Composition API 规范、Vue 文件结构。适用于所有 Vue 2/3 项目开发，帮助大模型生成符合 Vue 官方风格指南的代码。

Vue.js 官方风格指南编码规范技能

概述

本技能基于 Vue.js 官方风格指南，指导在 Vue 开发中遵循统一的编码规范。规约分四个优先级：

• 【A - 必要】：防止错误的规则，必须遵守，违反会引发 bug 或可读性极差的代码
• 【B - 强烈推荐】：改善可读性和开发体验的规则，违反应有充分理由
• 【C - 推荐】：多种同等好的选项中的一致性建议，选择后应保持整个项目一致
• 【D - 谨慎使用】：有风险的特性，应了解其使用场景和危害

规范体系总览

优先级	文件	内容摘要
A - 必要	references/01-priority-a-essential.md	组件命名、Props 定义、v-for key、v-if 与 v-for、作用域样式
B - 强烈推荐	references/02-priority-b-strongly-recommended.md	文件结构、命名风格、自闭合、属性顺序、简单表达式、指令缩写
C - 推荐	references/03-priority-c-recommended.md	选项顺序、属性顺序、空行、SFC 标签顺序
D - 谨慎使用	references/04-priority-d-use-with-caution.md	scoped 中的元素选择器、隐式父子通信

快速参考：最高频核心规则

组件命名（必读）

• 组件名必须是多个单词（除根 App 组件外）：TodoItem ✅ Item ❌
• SFC 文件名用 PascalCase 或 kebab-case，保持项目内一致：MyComponent.vue / my-component.vue
• 基础/通用组件以 Base、App 或 V 为前缀：BaseButton.vue、AppIcon.vue
• 单例组件（每页只用一次）以 The 为前缀：TheNavbar.vue、TheHeader.vue
• 紧密耦合的子组件以父组件名为前缀：TodoList.vue + TodoListItem.vue
• 组件名从最高层级词到描述修饰词排列：SearchButtonClear.vue ✅ ClearSearchButton.vue ❌
• JS/JSX 中组件名始终用 PascalCase
• 模板中 SFC/字符串模板用 PascalCase，in-DOM 模板用 kebab-case
• 组件名使用完整单词，避免缩写：StudentDashboardSettings.vue ✅ SdSettings.vue ❌

Props 规范（必读）

• 提交的代码中 prop 定义必须尽可能详细，至少指定类型
• Props 声明时使用 camelCase，in-DOM 模板使用时用 kebab-case
• 避免布尔 prop 歧义，使用 required: true 或显式 default

// ✅ Good
const props = defineProps({
  status: {
    type: String,
    required: true,
    validator: (value) => ['syncing', 'synced', 'error'].includes(value)
  }
})

// ❌ Bad
const props = defineProps(['status'])

v-for 与 v-if（必读）

• v-for 必须始终带 :key
• 绝不在同一元素上同时使用 v-if 和 v-for
  • 过滤列表：用 计算属性 预处理后再渲染
  • 条件显示整个列表：将 v-if 移到容器元素上

<!-- ✅ Good -->
<ul>
  <li v-for="user in activeUsers" :key="user.id">{{ user.name }}</li>
</ul>

<!-- ❌ Bad -->
<li v-for="user in users" v-if="user.isActive" :key="user.id">

样式作用域（必读）

• 应用级组件使用 <style scoped> 或 CSS Modules 或 BEM 等策略
• 组件库优先使用基于类的策略（非 scoped），方便外部覆盖样式
• scoped 样式中避免使用元素选择器，改用类选择器（性能更好）

SFC 文件结构（必读）

• 每个组件单独一个文件
• SFC 顶层标签顺序保持一致：<script> → <template> → <style>，<style> 始终最后

模板表达式（必读）

• 模板中只写简单表达式，复杂逻辑移入 computed 或 methods
• 复杂计算属性应拆分为多个简单的计算属性

指令缩写（必读）

• 指令缩写（: 代替 v-bind:，@ 代替 v-on:，# 代替 v-slot）在项目中要么全用要么全不用，保持一致

多属性元素（必读）

• 有多个属性的元素应写成多行，每个属性占一行

<!-- ✅ Good -->
<MyComponent
  foo="a"
  bar="b"
  baz="c"
/>

<!-- ❌ Bad -->
<MyComponent foo="a" bar="b" baz="c"/>

父子组件通信（必读）

• 优先使用 props down / events up 模式
• 避免通过 this.$parent 或直接修改 prop 对象进行隐式通信
• 使用 defineEmits 声明事件，通过 emit 通知父组件

如何使用本技能

生成 Vue 代码时，按照以下步骤：

1. 组件命名阶段：参照 references/01-priority-a-essential.md 和 references/02-priority-b-strongly-recommended.md 的命名部分
2. Props/Emits 设计：参照 references/01-priority-a-essential.md 的 Props 定义规则
3. 模板编写：参照 v-for、v-if、指令缩写、多属性元素规则
4. 组件选项排序：参照 references/03-priority-c-recommended.md
5. 样式编写：参照作用域样式规则和 references/04-priority-d-use-with-caution.md

当用户要求审查 Vue 代码时，逐项检查上述规范并给出具体改进建议，标注违反的规则优先级（A必要/B强烈推荐/C推荐/D谨慎使用）。