# Vue Style Guide

> 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 官方风格指南的代码。

- Skill: `tzf1003/vue-style-guide` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tzf1003/vue-style-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tzf1003/vue-style-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tzf1003 (https://skillmd.com/u/tzf1003)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tzf1003/vue-style-guide

---


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

## 概述

本技能基于 [Vue.js 官方风格指南](https://vuejs.org/style-guide/)，指导在 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`

```js
// ✅ 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` 移到容器元素上

```html
<!-- ✅ 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`）在项目中**要么全用要么全不用**，保持一致

### 多属性元素（必读）
- 有多个属性的元素应写成多行，每个属性占一行

```html
<!-- ✅ 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谨慎使用）。