@[TOC](Vue3 写法与规范指南)


# 一、项目结构规范
## 1.推荐目录结构
```markdown
src/
├── assets/              # 静态资源（图片、字体等）
├── components/           # 公共组件（PascalCase命名）
│   ├── Button.vue
│   └── UserCard.vue
├── composables/          # 组合式函数（逻辑复用）
│   └── useFetch.ts
├── router/               # 路由配置
│   └── index.ts
├── store/                # 状态管理（Pinia）
│   └── user.ts
├── utils/                # 工具函数
│   └── format.ts
├── views/                # 页面级组件
│   └── Home.vue
├── App.vue               # 根组件
└── main.ts               # 入口文件
```
## 2.命名规则
组件文件：PascalCase（如 UserProfile.vue）
文件夹：复数形式（如 components/ 而非 component/）
组合式函数：useXxx 前缀（如 useAuth.ts）
# 二、代码编写规范
## 1. Script 部分（Composition API）
**setup 语法糖**
```vue
<script setup lang="ts">
import { ref, computed, onMounted } from 'vue';
import { fetchUser } from '@/api/user';

// 响应式数据
const count = ref(0);
const user = ref<UserType | null>(null);

// 计算属性
const doubleCount = computed(() => count.value * 2);

// 生命周期
onMounted(async () => {
  user.value = await fetchUser(1);
});

// 类型定义
interface UserType {
  id: number;
  name: string;
}
</script>
```

**Props/Emits 类型化**
```ts
const props = defineProps<{
  modelValue: string;
  disabled?: boolean;
}>();
 
const emit = defineEmits<{
  (e: 'update:modelValue', value: string): void;
  (e: 'submit'): void;
}>();
```
## 2. Template 部分
**语义化标签**
```vue
<template>
  <article class="article-card">
    <header class="article-header">
      <h2>{{ title }}</h2>
    </header>
    <main class="article-content">
      <p>{{ content }}</p>
    </main>
  </article>
</template>
```
条件渲染与列表
```vue
<template>
  
  <template v-if="users.length">
    <ul>
      <li v-for="user in users" :key="user.id">
        {{ user.name }}
      </li>
    </ul>
  </template>
  <p v-else>No users found</p>
</template>
```
## 3. Style 部分
**Scoped CSS**
```vue
<style scoped>
.article-card {
  border: 1px solid #eee;
  transition: all 0.3s ease;
}
 
.article-card:hover {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
</style>
```
**CSS 命名规范（BEM 示例）**
```css
.article-card {}
.article-card__header {}
.article-card__header--active {}
```
# 三、高级特性规范
## 1. 组合式函数（Composables）
```ts
// composables/useCounter.ts
import { ref } from 'vue';
 
export function useCounter(initialValue = 0) {
  const count = ref(initialValue);
 
  const increment = () => count.value++;
  const decrement = () => count.value--;
 
  return { count, increment, decrement };
}
```
## 2. 组件通信
### 1.父子组件通讯
**1. 父传子：使用 props**
父组件通过属性（Props）向子组件传递数据。

```vue
父组件 (Parent.vue):
<template>
  <div>
    <ChildComponent :title="pageTitle" :user="currentUser" />
  </div>
</template>

<script setup>
import { ref, reactive } from 'vue'
import ChildComponent from './ChildComponent.vue'

const pageTitle = ref('欢迎来到我的应用')
const currentUser = reactive({
  name: '张三',
  id: 123
})
</script>
```

```vue
子组件 (ChildComponent.vue):
<template>
  <div>
    <h2>{{ title }}</h2>
    <p>用户: {{ user.name }} (ID: {{ user.id }})</p>
  </div>
</template>

<script setup>
// 定义接收的 props
const props = defineProps({
  title: {
    type: String,
    required: true
  },
  user: {
    type: Object,
    default: () => ({})
  }
})

// 在模板中直接使用 props.title 和 props.user
// 注意：在 <script setup> 中，props 是一个对象，需要通过 props.xxx 访问
</script>
```
**2. 子传父：使用 emit**
子组件通过触发自定义事件向父组件传递数据。


```vue
子组件 (ChildComponent.vue):
<template>
  <div>
    <button @click="handleClick">点击我通知父组件</button>
  </div>
</template>

<script setup>
// 定义组件可以触发的事件
const emit = defineEmits(['updateUser', 'customEvent'])

const handleClick = () => {
  // 触发事件，并传递数据
  emit('updateUser', { id: 456, name: '李四' })
  // 也可以触发不带参数的事件
  emit('customEvent')
}
</script>
```

```vue
父组件 (Parent.vue):
<template>
  <div>
    <ChildComponent 
      @updateUser="handleUserUpdate" 
      @customEvent="handleCustomEvent" 
    />
    <p>当前用户: {{ user.name }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'

const user = ref({ name: '王五', id: 789 })

const handleUserUpdate = (newUser) => {
  // 接收子组件传递过来的数据
  user.value = newUser
  console.log('用户已更新:', newUser)
}

const handleCustomEvent = () => {
  console.log('自定义事件被触发了')
}
</script>
```
### 2.跨层级组件：provide/inject
当组件嵌套层级很深，逐层传递 props 会非常繁琐时，可以使用 provide 和 inject。

**使用 provide / inject**
祖先组件提供数据，后代组件（无论多深）注入并使用。

祖先组件 (App.vue 或 Layout.vue):
```vue

<template>
  <div>
    <DeeplyNestedChild />
  </div>
</template>

<script setup>
import { provide, ref } from 'vue'
import DeeplyNestedChild from './components/DeeplyNestedChild.vue'

// 提供一个响应式数据
const theme = ref('dark')
const appConfig = {
  apiUrl: 'https://api.example.com',
  version: '1.0.0'
}

// 第一个参数是 key (推荐使用 Symbol 或字符串)，第二个参数是提供的值
provide('THEME', theme)
provide('APP_CONFIG', appConfig)
</script>
```
后代组件 (DeeplyNestedChild.vue):
```vue
浅色版本
<template>
  <div :class="theme">
    <p>当前主题: {{ theme }}</p>
    <p>API 地址: {{ config.apiUrl }}</p>
  </div>
</template>

<script setup>
import { inject } from 'vue'

// 注入数据，第二个参数是默认值（可选但推荐）
const theme = inject('THEME', 'light')
const config = inject('APP_CONFIG', {})
</script>
```
**注意**
如果 provide 的是 ref 或 reactive 对象，inject 得到的数据会保持响应性。
为避免命名冲突，建议使用 Symbol 作为 key：
```javascript
浅色版本
// keys.js
export const THEME_KEY = Symbol()
export const CONFIG_KEY = Symbol()

// 在 provide 和 inject 时使用这些 Symbol
```

### 3.其他通信方式

 - **$refs (子 -> 父)**: 父组件可以通过 ref获取子组件的实例，从而直接调用子组件的方法或访问其数据。这种方式会增加耦合度，应谨慎使用。

 - **插槽 (Slots)**: 主要用于内容分发，但结合作用域插槽 (Scoped Slots)，可以实现父组件向子组件传递数据，同时由父组件决定如何渲染。常用于列表、表格等组件。
 - **v-model:** 是 props 和 emit 的语法糖，用于在表单组件上创建双向绑定。
## 3. 性能优化
虚拟滚动：长列表使用 vue-virtual-scroller
计算属性缓存：避免在模板中执行复杂计算
响应式优化：对大型对象使用 shallowRef
# 四、工具链配置
## 1. ESLint 配置（.eslintrc.js）
```js
module.exports = {
  extends: [
    'plugin:vue/vue3-recommended',
    '@vue/typescript/recommended'
  ],
  rules: {
    'vue/multi-word-component-names': 'off', // 允许单文件组件名
    '@typescript-eslint/no-explicit-any': 'warn'
  }
};
```
## 2. Prettier 配置（.prettierrc）
```json
{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "es5",
  "printWidth": 100
}
```
## 3. Git 规范
提交信息格式：<_type>: <_subject>
强制检查：使用 Husky + Commitlint
> feat: 添加用户登录功能 
> fix: 修复表单验证错误 
> chore: 更新依赖版本 

# 五、反模式警示
 避免混用 Options API 和 Composition API
```vue
<script>
export default {
  data() { return { count: 0 } } // 不要与 setup() 混用
}
</script>
<script setup>
const count = ref(0); //  冲突
</script>
```
 禁止直接修改 Props
```vue
<script setup>
const props = defineProps(['count']);
//  错误方式
props.count++;
//  正确方式：通过 emits
const emit = defineEmits(['update:count']);
emit('update:count', props.count + 1);
</script>
```
 避免深层响应式
```ts
//  性能开销大
const state = reactive({
  user: {
    profile: {
      name: 'Alice'
    }
  }
});

 
//  优化：对大型对象使用 shallowRef
const largeData = shallowRef({ /* ... */ });
```
遵循以上规范可显著提升代码可维护性和团队协作效率，建议结合 Vue Style Guide 官方文档使用。

组件文件：PascalCase（如 UserProfile.vue）文件夹：复数形式（如 components/ 而非 component/）组合式函数：useXxx 前缀（如 useAuth.ts）

Vue3 写法示例与规范指南

开发工具

Vue3规范指南详解项目结构、命名规则、代码编写规范与性能优化技巧。包含Composition API最佳实践、组件通信方式、ESLint配置等核心内容，助力开发者构建高效可维护的Vue3应用。

TypeScript

路由

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Vue3 写法示例与规范指南-腾讯云开发者社区-腾讯云

Vue3 写法示例与规范指南

Vue3 写法示例与规范指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐