w wyl123ly 的博客
MD

前端-06-Vue

70 KB 2026.10.11 原文件

前端-06-Vue

这篇笔记讲什么

Vue 是一个用于构建用户界面的渐进式 JavaScript 框架(Progressive Framework),当前稳定版为 Vue 3.5.x(本库核实时间 2026-10-11,见 版本与官方资源速查)。

本篇只讲 Vue 3 的组合式 API(Composition API)与 <script setup>,不与 Vue 2 的选项式 API(Options API)混讲:Vue 2 已于 2023-12-31 停止维护,data(){} / methods:{} / this 那一套写法在新项目里不再作为教学主线。你在旧项目里仍会见到它,但请把它当作"另一门方言"单独学,不要把两种写法掺在同一个组件里。

读完你应该能:独立搭建 Vue 3 项目、用组合式 API 写出带路由与状态管理的完整应用、解释响应式系统为什么这样设计、并说出至少五个常见坑。


一、是什么:Vue 的定位与设计哲学

1.1 一句话定义

Vue 是一套用于构建用户界面的渐进式框架:核心只解决"数据变化 → 视图更新"这一件事,其余能力(路由、状态管理、构建工具、服务端渲染)都是可选的、按需加入的独立层。

"渐进式"的准确含义是你可以只用一个 <script> 标签引入 Vue,在现有页面上改造一小块区域,也可以用它写一整个单页应用(SPA)。框架不要求你一次接受全部约定。

1.2 三个核心设计哲学

哲学含义具体体现
声明式渲染(Declarative Rendering)你描述"视图应该长什么样",而不是"怎么一步步改 DOM"模板里写 {{ count }},改 count 视图自动更新
响应式系统(Reactivity System)数据与视图建立依赖关系,数据变则相关视图自动重渲染ref / reactive + 依赖追踪
组件化(Component-Based)把界面拆成可复用、可组合、自包含的单元单文件组件(SFC,Single-File Component)

1.3 声明式 vs 命令式:为什么不再需要 jQuery

这是理解前端框架价值的第一道分水岭。看同一个需求:点击按钮,列表加一项,并显示总数。

命令式(Imperative)——jQuery 或原生 DOM 的写法:

<!-- jQuery 写法:你必须自己规定每一步怎么改 DOM -->
<ul id="list"></ul>
<span id="total">0</span>
<button id="add">添加</button>

<script src="https://cdn.jsdelivr.net/npm/jquery@3/dist/jquery.min.js"></script>
<script>
  // 数据藏在 DOM 里:真实状态是"页面上一共有几个 li",而不是一个变量
  let count = 0;

  $('#add').on('click', function () {
    count++;
    // 第一步:手动创建 DOM 节点
    const $li = $('<li>').text('条目 ' + count);
    // 第二步:手动插入
    $('#list').append($li);
    // 第三步:手动同步"派生数据"(总数)
    $('#total').text(count);
  });
</script>

问题在于状态与视图是两份数据,你必须手动让它们保持一致。需求一旦变成"删除某一项后总数也要变、还要支持筛选",维护成本就爆炸了。

声明式(Declarative)——Vue 3 的写法:

<script setup lang="ts">
import { ref, computed } from 'vue'

// 唯一数据源:一个数组
const items = ref<string[]>([])
const total = computed(() => items.value.length)
// 视图里不再出现任何"怎么改 DOM"的代码
</script>

<template>
  <ul>
    <li v-for="(item, i) in items" :key="i">{{ item }}</li>
  </ul>
  <span>{{ total }}</span>
  <button @click="items.push(`条目 ${items.length + 1}`)">添加</button>
</template>

你只改数据,DOM 的增删改由框架负责。 删除项、加筛选,都只需改数组,视图自动跟上。

对比维度命令式(jQuery / 原生 DOM)声明式(Vue 3)
你写的是操作步骤(先创建、再插入、再更新计数)最终状态(视图 = f(数据))
状态存放在哪常散落在 DOM 与闭包变量中,容易不一致集中在响应式数据里,单一数据源
代码量随功能增长近似线性甚至更快增长(每个交互都要手动同步)主要随"状态数量"增长
定位 bug要同时排查数据与 DOM 是否同步基本只需排查数据对不对
性能精细可控,但靠人由框架的 diff 与批量更新策略决定
适合场景老项目小改造、极简静态页增强交互复杂、状态多的应用

记住这个心智模型

视图 = f(状态),即 。前端框架的一切设计(响应式、虚拟 DOM、diff)都是为了让你少写"同步代码"。

命令式操作 DOM 并没有"错",它只是把复杂度从框架转移给了你。

1.4 响应式系统的直觉

Vue 3 的响应式基于 ES6 的 Proxy:读取数据时收集依赖(记录"哪个渲染函数用到了我"),写入数据时触发依赖(通知相关渲染函数重新执行)。

宏观效果可以用一个不等式概括:手写 DOM 同步的代码量与状态数近似成线性关系,而声明式写法把这部分工作交给了框架。

1.5 与 React 的位置关系

两者都是声明式组件框架,解决同一类问题,差异主要在数据如何驱动更新:

维度Vue 3React 19
更新触发方式细粒度响应式,改数据自动精确更新用到的部分调用 setState 后从组件函数重新执行(默认整棵子树重跑)
模板独立模板语法(也可写渲染函数)JSX 内嵌在 JavaScript 里
状态写法ref / reactive 可变对象不可变更新(setX(newObj))
性能优化手段编译器静态提升 + 响应式依赖追踪,多数场景无需手写优化memo / useMemo / useCallback 等按需手动优化
心智模型数据变了,视图自己会变状态变了,重新执行组件函数,算出新视图

React 的对照细节见 前端-07-React。


二、为什么这样设计

2.1 为什么模板要单独存在,而不是像 React 那样全用 JS

Vue 的模板是可编译的:编译器能在构建期分析出哪些节点是静态的、哪些绑定依赖哪个变量,从而生成带优化的渲染函数。这让"绑定依赖某个 ref"这件事在编译期就部分确定,运行时开销更小。代价是你需要额外学一套模板语法,且逻辑复杂时要用渲染函数(h())兜底。

2.2 为什么要有 .value

ref(0) 返回的是一个对象 { value: 0 },而不是原始值本身。原因是原始值无法被 Proxy 拦截:let x = 0 只是一个普通变量,赋值 x = 1 时框架没有任何机会知道。用一个带 getter/setter 的包装对象,就能在读写时收集与触发依赖。在模板顶层会自动解包({{ count }} 不需要写 .value),在 JavaScript 里必须写。

2.3 为什么改 props 会报警告

组件之间的依赖关系必须是单向的(props down / events up)。如果子组件能改父组件传入的 props,那么"这个数据是谁改的"就无法追踪,数据流变成一张互相影响的网。Vue 因此在开发环境直接对 props 赋值报错,从机制上强迫你走 emit 或者本地副本。


三、核心内容

3.1 创建项目的两条路径

路径 A:官方脚手架 npm create vue@latest(推荐给需要 Router / Pinia / TS 的真实项目)

# 需要 Node.js 18+ 或 20+(具体下限以官方最新文档为准)
npm create vue@latest my-app

交互式问答会问你是否需要 TypeScript、JSX、Vue Router、Pinia、Vitest、ESLint、Prettier。选择"是"后它会自动安装依赖并配好 vite.config.ts。

cd my-app
npm install        # 若创建时未自动安装
npm run dev        # 启动开发服务器,默认 http://localhost:5173
npm run build      # 生产构建,产物在 dist/
npm run preview    # 本地预览生产产物

路径 B:Vite 手动搭建(推荐想搞清楚"脚手架到底做了什么"的同学)

# 用 Vite 的 vanilla-ts 模板起步,再手动加入 Vue
npm create vite@latest vue-manual -- --template vanilla-ts
cd vue-manual
npm install
npm install vue
npm install -D @vitejs/plugin-vue

两种路径的对比:

对比项npm create vue@latestVite 手动搭建
上手速度一条命令得到完整工程需要理解每个配置项
默认包含Router / Pinia / ESLint 等按需勾选只有最小可运行集
适合团队新项目、赶工期学习、需要完全掌控配置
学习价值低(黑盒)高(知道 @vitejs/plugin-vue 在干什么)
后续迁移配置较固定想加什么加什么

3.2 单文件组件(SFC)三段式结构

一个 .vue 文件最多由三块组成,编译时被分别处理:

<script setup lang="ts">
// ① 逻辑:编译成组件的 setup() 函数体
import { ref } from 'vue'
const msg = ref('你好')
</script>

<template>
  <!-- ② 结构:编译成 render() 渲染函数 -->
  <p>{{ msg }}</p>
</template>

<style scoped>
/* ③ 样式:抽成独立 CSS,并加上作用域属性选择器 */
p { color: #42b883; }
</style>
块编译产物关键点
<script setup>setup() 函数,顶层变量自动暴露给模板只能有一个;import 的组件可直接在模板用
<template>render() 函数(含静态提升等优化)只能有一个;必须有单一根节点(Vue 3 允许多根片段)
<style scoped>独立 CSS + data-v-xxxxxx 属性选择器可有多个;lang="scss" 需装预处理器

为什么要单文件:把一个组件的结构、逻辑、样式放在同一文件里,改一处功能不用在三个文件之间跳;同时每块都有明确的编译期语义,工具链能做静态分析。

3.3 模板语法

3.3.1 插值
<script setup lang="ts">
const msg = 'hello'
const n = 3
</script>

<template>
  <p>{{ msg }}</p>            <!-- 文本插值 -->
  <p>{{ n * 2 }}</p>          <!-- 可以放单个表达式 -->
  <p>{{ n > 2 ? '大' : '小' }}</p>
  <p v-once>{{ msg }}</p>     <!-- 只渲染一次,之后不再更新 -->
</template>

插值里只能放表达式

{{ if (n > 2) { } }}、{{ const a = 1 }} 都是语法错误——插值要求一个"值",不能是语句。需要复杂逻辑时应写进 computed。

3.3.2 v-bind 与简写 :
<script setup lang="ts">
import { ref, reactive } from 'vue'
const id = ref('box')
const isActive = ref(true)
const attrs = reactive({ 'data-role': 'card', title: '提示文字' })
const styleObj = reactive({ color: 'red', fontSize: '18px' })
</script>

<template>
  <div :id="id"></div>
  <!-- class 支持对象语法 -->
  <div class="base" :class="{ active: isActive, 'is-large': false }"></div>
  <!-- class 支持数组语法 -->
  <div :class="['base', isActive ? 'active' : '']"></div>
  <!-- style 支持对象与数组 -->
  <div :style="styleObj"></div>
  <div :style="[styleObj, { marginTop: '8px' }]"></div>
  <!-- 绑定多个属性:v-bind 不带参数 -->
  <div v-bind="attrs"></div>
</template>
3.3.3 v-on 与简写 @
<script setup lang="ts">
import { ref } from 'vue'
const count = ref(0)
function add(n: number, e: MouseEvent) {
  count.value += n
  console.log('事件对象:', e.type)
}
</script>

<template>
  <button @click="count++">加一</button>
  <!-- 需要传参又要事件对象时,显式传入 $event -->
  <button @click="add(2, $event)">加二</button>
  <!-- 修饰符 -->
  <form @submit.prevent="() => {}">
    <input @keyup.enter="count++" />
  </form>
  <div @click.self="count = 0">只有点自己才触发</div>
  <input @input.once="count++" />
</template>
修饰符作用典型场景
.prevent调用 event.preventDefault()表单提交、链接跳转
.stop调用 event.stopPropagation()阻止冒泡
.self仅当 event.target 是自身时触发弹窗遮罩点击关闭
.once最多触发一次一次性的引导动作
.capture用捕获模式监听外层优先拦截
.passive声明不调 preventDefault,改善滚动性能@scroll.passive、@touchmove.passive
.enter / .esc / .tab按键修饰符搜索框回车提交
.exact精确匹配修饰键组合@click.ctrl.exact
3.3.4 v-model 与修饰符

v-model 在原生表单元素上是"绑定值 + 监听输入"的语法糖:

<script setup lang="ts">
import { ref, reactive } from 'vue'
const text = ref('')
const age = ref<number | null>(null)
const bio = ref('')
const agree = ref(false)
const picked = ref<string[]>([])
const single = ref('a')
</script>

<template>
  <!-- 等价于 :value="text" @input="text = $event.target.value" -->
  <input v-model="text" placeholder="文本" />

  <!-- .lazy:从 input 事件改为 change 事件(失焦或回车后才同步) -->
  <input v-model.lazy="text" />

  <!-- .number:把输入自动转成 number(转换失败则返回原字符串) -->
  <input v-model.number="age" type="number" />

  <!-- .trim:自动去掉首尾空白 -->
  <input v-model.trim="bio" />

  <input type="checkbox" v-model="agree" />
  <input type="checkbox" v-model="picked" value="vue" /> Vue
  <input type="checkbox" v-model="picked" value="react" /> React
  <input type="radio" v-model="single" value="a" /> A
  <select v-model="single">
    <option value="a">A</option>
    <option value="b">B</option>
  </select>
</template>
3.3.5 v-if 与 v-show
<template>
  <p v-if="score >= 90">优秀</p>
  <p v-else-if="score >= 60">及格</p>
  <p v-else>不及格</p>

  <p v-show="visible">用 display 控制显隐</p>

  <!-- v-if 可以用在 template 上,批量控制一组节点且不产生额外 DOM -->
  <template v-if="visible">
    <h3>标题</h3>
    <p>正文</p>
  </template>
</template>
对比项v-ifv-show
实现方式创建 / 销毁节点(条件为假时节点不存在)节点始终存在,切换 display: none
初始渲染成本条件为假时更低(什么都不渲染)无论真假都要渲染一次
切换成本高(涉及组件销毁重建、生命周期重跑)低(只改 style)
内部组件状态切换后丢失(除非配 <KeepAlive>)保留
适用场景条件很少变、分支互斥且重需要频繁切换显隐
能否用于 template可以不可以(template 不渲染成元素,无处加 style)

选型口诀

频繁切换用 v-show,条件稳定用 v-if;初始时很久不显示的内容用 v-if(省渲染)。

3.3.6 v-for 与 key
<script setup lang="ts">
import { ref, reactive } from 'vue'
interface Todo { id: number; title: string }
const todos = ref<Todo[]>([
  { id: 1, title: '学 Vue' },
  { id: 2, title: '写笔记' },
])
const obj = reactive({ name: '张三', age: 20 })
</script>

<template>
  <!-- 数组:第二个参数是索引 -->
  <ul>
    <li v-for="(todo, index) in todos" :key="todo.id">
      {{ index + 1 }}. {{ todo.title }}
    </li>
  </ul>

  <!-- 对象:依次是值、键、索引 -->
  <p v-for="(value, key, i) in obj" :key="key">{{ i }} - {{ key }}: {{ value }}</p>

  <!-- 数字:从 1 开始 -->
  <span v-for="n in 3" :key="n">{{ n }}</span>

  <!-- v-for 优先级高于 v-if,二者同用时 v-if 会逐项求值(不推荐) -->
  <ul>
    <template v-for="todo in todos" :key="todo.id">
      <li v-if="todo.title">{{ todo.title }}</li>
    </template>
  </ul>
</template>

key 的作用:key 是框架做"节点复用"时的身份标识。列表增删时,框架靠 key 判断"哪一项还是原来那一项",从而复用 DOM 与组件实例、正确搬运节点。

写法行为风险
:key="item.id"按稳定身份复用推荐做法
:key="index"按位置复用列表中间插入 / 删除 / 排序时,状态会"串位"(输入框内容跑到别的行)
不写 key退化为就地复用与 index 类似,且有编译警告

什么时候 index 也不出错

只有列表只追加、不删除、不排序、项内无内部状态时,index 才碰巧安全。这类前提一旦被推翻就会出现难查的 bug,所以默认一律用业务 id。

3.3.7 v-html 的 XSS 风险
<script setup lang="ts">
import { ref } from 'vue'
const userInput = ref('<img src="x" onerror="alert(document.cookie)">')
</script>

<template>
  <div v-html="userInput"></div>
  <!-- 危险:上面这段会把攻击者提供的 onerror 脚本原样插入 DOM -->
</template>
方案是否执行脚本说明
{{ text }}不默认转义,最安全
v-html会内容按 HTML 解析,等价于 innerHTML
后端净化后再 v-html视净化规则需要白名单式的 HTML 净化库

v-html 的底线

永远不要对用户输入直接使用 v-html。 如果必须渲染富文本,请在服务端或客户端用白名单净化(只保留 p/a/strong 等安全标签与安全属性),并配合 Content-Security-Policy。前端框架不会替你做净化。

3.3.8 其他内置指令速查
指令作用备注
v-memo="[...]"依赖数组不变时跳过该子树更新配合 v-for 长列表使用
v-once只渲染一次,之后视为静态静态内容优化
v-pre跳过编译,原样输出展示模板代码时用
v-cloak编译完成前隐藏元素免构建引入时避免闪烁
v-text设置 textContent等价于插值

3.4 响应式系统

3.4.1 ref 与 reactive
<script setup lang="ts">
import { ref, reactive, toRefs } from 'vue'

// ref:可包装任意类型(原始值、对象、数组),通过 .value 读写
const count = ref(0)
const user = ref({ name: '张三' })
count.value++
user.value.name = '李四'

// reactive:只能包装对象/数组/Map/Set,直接读写属性
const form = reactive({ name: '', age: 0 })
form.name = '王五'

// toRefs:把 reactive 的每个属性转成 ref,便于解构
const { name, age } = toRefs(form)
name.value = '赵六'   // 仍然响应式,且与原对象联动
</script>

<template>
  <p>{{ count }}</p>      <!-- 模板顶层自动解包,不写 .value -->
  <p>{{ user.name }}</p>
  <p>{{ name }} {{ age }}</p>
</template>
对比项refreactive
可包装类型任意(含 string / number / boolean / null)仅对象类型(Object / Array / Map / Set)
读写方式脚本中必须 .value,模板中自动解包直接访问属性
整体替换支持:count.value = 1,user.value = {...}不支持重新赋值(会丢失响应式)
解构天然可解构(拿到的是 ref 本身)解构即失去响应式,需要 toRefs
传参给函数可整体传递并保持响应式传递后仍响应,但整体替换失效
类型推导泛型友好:`ref<User \null>(null)`依赖对象字面量的类型
官方推荐主推,统一风格适合逻辑上"就是一个表单对象"的场景

选型建议

不确定就选 ref:它适用于所有类型、能整体替换、可安全解构,团队风格也统一。

reactive 的适用场景很窄:一个字段固定、不需要整体替换、也不需要解构的表单对象。

3.4.2 为什么需要 .value,以及"忘记写"的后果
import { ref } from 'vue'
const count = ref(0)

count + 1          // ❌ 类型错误,也是逻辑错误:这是对象加数字
count.value + 1    // ✅

const list = ref<string[]>([])
list.push('a')     // ❌ 报错:ref 对象上没有 push
list.value.push('a') // ✅

在 <template> 里,只有顶层的 ref 会被自动解包;如果 ref 被嵌在对象或数组里,模板里要写 .value:

<script setup lang="ts">
import { ref, reactive } from 'vue'
const n = ref(0)
const box = reactive({ inner: ref(1) })   // 模板中:{{ box.inner }} 会自动解包
const arr = [ref(1), ref(2)]              // 数组中不解包,模板需写 arr[0].value
</script>

<template>
  <p>{{ n }}</p>             <!-- 自动解包 -->
  <p>{{ box.inner }}</p>     <!-- 嵌套在 reactive 里也会解包 -->
  <p>{{ arr[0].value }}</p>  <!-- 数组里不会解包 -->
</template>
3.4.3 computed:带缓存的派生值
<script setup lang="ts">
import { ref, computed } from 'vue'
const price = ref(100)
const qty = ref(2)

// 只读 computed
const total = computed(() => price.value * qty.value)

// 可写 computed(少见,但要会读)
const double = computed({
  get: () => qty.value * 2,
  set: (v: number) => { qty.value = v / 2 },
})
</script>

缓存机制:computed 内部维护一个"脏标记(dirty flag)"。第一次读取时求值并缓存结果;之后再次读取,只要依赖(price、qty)没有变化,就直接返回缓存,不会重新执行 getter。依赖变化时把标记置脏,下次读取才重算。

// 对比:方法与 computed 的执行次数
const price = ref(100)
const qty = ref(2)
const totalComputed = computed(() => { console.log('computed 执行'); return price.value * qty.value })
function totalMethod() { console.log('method 执行'); return price.value * qty.value }
// 模板中连续渲染 3 次 {{ totalComputed }} → 只打印 1 次
// 模板中连续渲染 3 次 {{ totalMethod() }} → 打印 3 次(每次渲染都重新调用)
// 只要 price / qty 不变,其它数据触发的重渲染也不会让 computed 重算
对比项computed方法 / 普通函数
缓存有(依赖不变不重算)无(每次渲染都执行)
依赖追踪自动无
适合从已有状态派生的值(合计、过滤后列表、是否全选)事件处理器、需要传参的逻辑
副作用禁止(getter 应是纯函数)可以有

computed 里不要写副作用

在 getter 里发请求、改其它状态、写 localStorage,会导致"求值时机不可预测"的难查 bug。需要副作用请用 watch 或 watchEffect。

3.4.4 watch 与 watchEffect
<script setup lang="ts">
import { ref, reactive, watch, watchEffect } from 'vue'

const keyword = ref('')
const user = reactive({ name: '张三', age: 20 })
const logs: string[] = []

// 1) 侦听单个 ref
watch(keyword, (newVal, oldVal) => {
  console.log(`关键词从 ${oldVal} 变为 ${newVal}`)
})

// 2) 侦听 getter 函数(可同时监听多个来源)
watch(
  () => [user.name, user.age] as const,
  ([name, age], [oldName, oldAge]) => {
    logs.push(`${oldName}/${oldAge} → ${name}/${age}`)
  },
)

// 3) 侦听 reactive 对象:默认深层侦听
watch(user, (newVal) => console.log('对象变了', newVal))

// 4) 选项:立即执行一次 + 深层侦听 + 回调时机
watch(
  keyword,
  (v) => console.log('immediate 首次就执行:', v),
  { immediate: true, deep: true, flush: 'post' },
)

// 5) 需要清理上一次副作用时,用 onCleanup
watch(keyword, async (kw, _old, onCleanup) => {
  let cancelled = false
  onCleanup(() => { cancelled = true })   // 竞态防护:旧请求作废
  const res = await fetch(`/api/search?q=${encodeURIComponent(kw)}`)
  const data = await res.json()
  if (!cancelled) console.log(data)
})

// 6) watchEffect:自动收集同步执行期间用到的依赖
const stop = watchEffect(() => {
  console.log('只要 keyword 变就执行:', keyword.value)
})
// 组件卸载时自动停止;手动停止调用 stop()
</script>
对比项computedwatchwatchEffect
返回值派生出的值无(用于副作用)无(用于副作用)
依赖来源自动收集显式指定自动收集
是否立即执行读取时惰性求值默认否(immediate: true 可改)是,立即执行一次
能否拿到旧值不涉及能(oldVal)不能
是否需缓存结果是否否
典型用途合计、过滤列表、按钮禁用判断需要旧值对比、需要精确控制触发条件、异步请求、写存储依赖容易漏写、只关心"变了就做点什么"
深层侦听自动侦听 reactive 对象时自动;侦听 ref 对象需 deep: true自动

选择顺序

能派生就用 computed,需要副作用才用 watch / watchEffect。 很多"必须 watch"的需求其实是 computed:比如"是否全选 = 已选数量 === 总数"。

3.4.5 解构 reactive 为什么丢失响应式
import { reactive, toRefs } from 'vue'

const state = reactive({ count: 0 })

// ❌ 解构出来的是普通数字,与 state 已经没有任何联系
let { count } = state
count++          // 只改了局部变量,state.count 仍是 0,视图不会变

// ✅ 方案一:toRefs 把每个属性转成 ref,保持联动
const { count: countRef } = toRefs(state)
countRef.value++
console.log(state.count) // 1

// ✅ 方案二:干脆一开始就用 ref
const count2 = ref(0)

原因:reactive 的响应式来自属性访问时的 Proxy 拦截。解构是一次性读取属性值,读到的只是当时的快照,之后对这个局部变量的修改不可能再经过 Proxy,自然无法触发更新。toRefs 返回的每个属性都是"指向原对象同一个属性的 ref",所以读写都会回到原对象。

3.5 组件通信

3.5.1 props 声明与校验
<!-- UserCard.vue -->
<script setup lang="ts">
// TypeScript 类型式声明(推荐;加上 export 可避免某些严格 tsconfig 下的类型解析问题)
export interface Props {
  name: string
  age?: number
  tags?: string[]
  status?: 'active' | 'banned'
}
const props = withDefaults(defineProps<Props>(), {
  age: 18,          // 对象/数组的默认值必须用工厂函数,见下方说明
  tags: () => [],
  status: 'active',
})
console.log(props.name)
</script>

<template>
  <div>
    <h3>{{ name }}</h3>
    <p>{{ age }} / {{ status }}</p>
    <span v-for="t in tags" :key="t">{{ t }}</span>
  </div>
</template>

运行时声明(无 TS 时使用,可写校验函数):

<script setup>
const props = defineProps({
  name: { type: String, required: true },
  age: {
    type: Number,
    default: 18,
    validator: (v) => v >= 0 && v <= 150,
  },
  tags: { type: Array, default: () => [] },   // 对象/数组默认值必须是工厂函数
})
</script>

props 是只读的

props.name = 'x' 在开发环境会直接报警告。需要基于 props 派生的可变数据时,用 computed(只读派生)或 ref(props.x) 建本地副本;当 props 变化需要同步时,用 watch(() => props.x, ...) 或 computed 的 get/set。

3.5.2 emit 自定义事件
<!-- SearchBox.vue:子组件只负责"通知",不关心父组件怎么处理 -->
<script setup lang="ts">
const emit = defineEmits<{
  (e: 'search', keyword: string): void
  (e: 'clear'): void
  (e: 'update:modelValue', value: string): void
}>()

function onSubmit(value: string) {
  emit('search', value)
  emit('update:modelValue', value)
}
</script>
<!-- 父组件 -->
<SearchBox
  @search="onSearch"
  @clear="keyword = ''"
  v-model="keyword"
/>

事件命名

在模板里监听用 kebab-case(@my-event),在 defineEmits 里声明用 camelCase('myEvent')会被自动匹配;但声明与监听写完全一致最不容易出错。原生事件名(click、change)不建议复用为自定义事件名。

3.5.3 组件上的 v-model 原理与 defineModel

v-model 用在组件上,本质是 modelValue prop + update:modelValue 事件的组合:

<!-- CustomInput.vue:手写实现,看清本质 -->
<script setup lang="ts">
const props = defineProps<{ modelValue: string; label?: string }>()
const emit = defineEmits<{ (e: 'update:modelValue', v: string): void }>()
</script>

<template>
  <label>
    {{ label }}
    <input
      :value="modelValue"
      @input="emit('update:modelValue', ($event.target as HTMLInputElement).value)"
    />
  </label>
</template>

Vue 3.4+ 提供了编译期宏 defineModel(),把上面的样板代码压成两行:

<!-- CustomInput2.vue -->
<script setup lang="ts">
const model = defineModel<string>({ required: true })
// 等价于:props.modelValue + emit('update:modelValue', v)
const title = defineModel<string>('title', { default: '' })  // 具名 v-model
</script>

<template>
  <input v-model="model" />
  <input v-model="title" />
</template>
<!-- 父组件使用 -->
<CustomInput2 v-model="name" v-model:title="pageTitle" />
写法代码量备注
props.modelValue + emit('update:modelValue')多,但零魔法任何 3.x 版本都可用
defineModel()极少Vue 3.4+ 稳定;旧版本需开启实验性选项,以官方最新文档为准
3.5.4 provide / inject

用于跨多层传递(避免 props 逐层透传,即"prop drilling"):

<!-- 祖先:App.vue -->
<script setup lang="ts">
import { provide, ref, readonly } from 'vue'

const theme = ref<'light' | 'dark'>('light')
function toggleTheme() {
  theme.value = theme.value === 'light' ? 'dark' : 'light'
}
// 用 readonly 包一层,防止后代组件直接改
provide('theme', readonly(theme))
provide('toggleTheme', toggleTheme)

// 更好的做法:用一个 Symbol 作 key,避免命名冲突
export const themeKey = Symbol('theme') as InjectionKey<Readonly<Ref<'light' | 'dark'>>>
</script>
<!-- 任意深度的后代:DeepChild.vue -->
<script setup lang="ts">
import { inject } from 'vue'
const theme = inject<Readonly<Ref<'light' | 'dark'>>>('theme', ref('light')) // 第二个参数是默认值
const toggle = inject<() => void>('toggleTheme')
</script>

<template>
  <button :class="theme" @click="toggle">切换主题(当前 {{ theme }})</button>
</template>
对比项props / emitprovide / inject
传递方向父子之间,逐层祖先到任意深度后代
显式程度高(看模板就知道数据从哪来)低(后代凭空拿到,需查 provide 处)
响应性天然传 ref / reactive 时才有
适合明确的父子协议主题、国际化、全局配置、表单上下文
3.5.5 defineExpose:把子组件内部方法暴露给父组件
<!-- Counter.vue -->
<script setup lang="ts">
import { ref } from 'vue'
const count = ref(0)
function reset() { count.value = 0 }
// 未暴露的内容父组件拿不到(<script setup> 默认封闭)
defineExpose({ count, reset })
</script>

<template><p>{{ count }}</p></template>
<!-- 父组件 -->
<script setup lang="ts">
import { ref } from 'vue'
import Counter from './Counter.vue'
// Vue 3.5+ 起可用 useTemplateRef 获取模板引用(更简洁,以官方最新文档为准)
const counterRef = ref<InstanceType<typeof Counter> | null>(null)
</script>

<template>
  <Counter ref="counterRef" />
  <button @click="counterRef?.reset()">重置子组件计数</button>
</template>

模板 ref 是最后手段

用 ref 调子组件方法会让父子耦合,破坏"props down / events up"。优先考虑用 prop 驱动子组件(例如传一个 resetFlag),只有聚焦输入框、调用图表实例方法这类"命令式操作"才用 ref。

3.5.6 插槽:默认 / 具名 / 作用域
<!-- BaseCard.vue -->
<script setup lang="ts">
defineProps<{ title: string }>()
const rows = [{ id: 1, name: '张三' }, { id: 2, name: '李四' }]
</script>

<template>
  <section class="card">
    <header>
      <!-- 具名插槽,带默认内容 -->
      <slot name="header">{{ title }}</slot>
    </header>

    <main>
      <!-- 默认插槽 -->
      <slot>默认内容:父组件没传就显示这句</slot>
    </main>

    <footer>
      <!-- 作用域插槽:把子组件数据"回传"给父组件决定怎么渲染 -->
      <slot name="row" v-for="row in rows" :key="row.id" :row="row" :index="row.id">
        {{ row.name }}
      </slot>
    </footer>
  </section>
</template>
<!-- 父组件使用 -->
<BaseCard title="用户列表">
  <template #header>
    <h2>自定义标题</h2>
  </template>

  <p>这段进入默认插槽</p>

  <!-- 作用域插槽:解构出子组件传来的数据 -->
  <template #row="{ row, index }">
    <div>{{ index }} - {{ row.name.toUpperCase() }}</div>
  </template>
</BaseCard>
插槽类型语法解决什么问题
默认插槽<slot /> / 父组件直接写内容内容由使用者决定
具名插槽<slot name="header" /> / #header一个组件有多个可定制区域
作用域插槽<slot :row="row" /> / #row="{ row }"结构由子组件管,渲染方式由父组件定(表格、列表组件必备)

3.6 生命周期钩子

组合式 API 的钩子都是"注册函数",必须在 setup(即 <script setup> 顶层同步代码)中调用。

钩子调用时机典型用途
onBeforeMount挂载前,DOM 还未创建很少用
onMounted组件挂载完成,DOM 可访问发请求、初始化图表、绑定 window 事件、取 DOM 尺寸
onBeforeUpdate数据变化、DOM 更新前更新前记录滚动位置
onUpdatedDOM 更新完成后依赖新 DOM 的操作(慎用,易造成循环)
onBeforeUnmount卸载前,实例仍可用保存草稿、解绑非响应式资源
onUnmounted卸载完成清理定时器 / 事件监听 / WebSocket / 第三方实例
onActivated / onDeactivated被 <KeepAlive> 缓存 / 停用时恢复/暂停轮询
onErrorCaptured捕获后代组件抛出的错误错误上报、兜底 UI

执行顺序(父组件包含子组件):

父 beforeCreate / setup
父 beforeMount
  子 setup
  子 beforeMount
  子 mounted
父 mounted

更新时:父 beforeUpdate → 子 beforeUpdate → 子 updated → 父 updated。

卸载时:父 beforeUnmount → 子 beforeUnmount → 子 unmounted → 父 unmounted。

为什么要清理副作用

组件卸载后,它注册的 setInterval、window.addEventListener、WebSocket、第三方图表实例仍然活着,回调里访问已销毁的响应式数据会造成内存泄漏与"幽灵更新"。凡是"组件外部的世界"注册的东西,都要在 onUnmounted(或 onScopeDispose)里注销。

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'

const width = ref(window.innerWidth)
const onResize = () => { width.value = window.innerWidth }

const timer = ref<number | undefined>()
let ws: WebSocket | null = null

onMounted(() => {
  window.addEventListener('resize', onResize)
  timer.value = window.setInterval(() => console.log('轮询中'), 5000)
  ws = new WebSocket('wss://example.com/feed')
})

onUnmounted(() => {
  // 三件事必须成对出现,否则就是内存泄漏
  window.removeEventListener('resize', onResize)
  if (timer.value !== undefined) window.clearInterval(timer.value)
  ws?.close()
})
</script>

<template><p>窗口宽度:{{ width }}</p></template>

更稳的写法:可组合函数里用作用域

把副作用封装进 composable 时,用 onScopeDispose(或 onUnmounted)清理,这样无论组件何时卸载都会自动收尾,见 。

3.7 组件设计原则

原则说明反例
props down / events up数据自上而下流,变更请求自下而上抛子组件直接改 props
单一职责一个组件只做一件事,超过约 200 行考虑拆分一个 800 行的"万能页面组件"
受控优先需要共享的状态交给父组件持有父子各存一份"同一个"数据
展示与逻辑分离纯展示组件只接收 props;数据获取交给容器组件或 composable列表项组件里发请求
用事件表达意图emit('submit', payload) 而不是 emit('click')事件名泄露实现细节
插槽换灵活度结构可变处留插槽,而不是加一堆 isXxx 开关 propsshowHeader、showFooter、hideTitle…

拆分判断法:如果一段 UI 满足以下任一条,就值得抽组件——① 在两处以上出现;② 有自己的内部状态;③ 数据获取/副作用逻辑让父组件变长;④ 修改它时你需要在文件里来回跳。

3.8 <script setup> 编译期宏

宏作用关键限制
defineProps声明 props只能调用一次;无需 import(编译器宏)
defineEmits声明自定义事件同上
defineExpose暴露实例属性/方法<script setup> 默认封闭,不暴露则父组件拿不到
defineModel声明 v-model 绑定的 prop(3.4+ 稳定)需编译器支持
defineOptions声明 name / inheritAttrs 等选项(3.3+)不能在 setup 里动态决定
withDefaults为类型式 props 提供默认值仅配合 defineProps<Props>() 使用
defineSlots声明插槽类型,给编辑器提示仅类型层面
useSlots / useAttrs运行时读取插槽 / 透传属性优先用 $slots` / `$attrs 模板变量

宏不能"搬进函数里"

编译器宏必须在 <script setup> 顶层调用,不能包在 if、函数或 try 里,否则编译报错。因为它们需要在编译期静态分析,而不是运行时执行。

3.9 Vue Router

核心对象:createRouter + createWebHistory;router-view 是路由出口,router-link 是声明式导航。

// src/router/index.ts
import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router'

const routes: RouteRecordRaw[] = [
  { path: '/', name: 'home', component: () => import('@/views/HomeView.vue') },
  {
    path: '/users',
    name: 'users',
    component: () => import('@/views/UserList.vue'),
    children: [
      // 嵌套路由:子路由渲染在父组件的 <router-view /> 里
      { path: ':id', name: 'user-detail', component: () => import('@/views/UserDetail.vue'), props: true },
    ],
  },
  // 动态参数 :id 必填;:pathMatch(.*)* 捕获未匹配路径(404)
  { path: '/:pathMatch(.*)*', name: 'not-found', component: () => import('@/views/NotFound.vue') },
]

export const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes,
  scrollBehavior: () => ({ top: 0 }),
})

动态参数与编程式导航:

<script setup lang="ts">
import { useRoute, useRouter } from 'vue-router'

const route = useRoute()
const router = useRouter()

// 读取参数:route.params.id 是 string | string[]
const id = computed(() => String(route.params.id))
const keyword = computed(() => String(route.query.q ?? ''))

async function goDetail(userId: number) {
  // 命名路由 + params,比手拼字符串更安全(路径改了不用改代码)
  await router.push({ name: 'user-detail', params: { id: userId } })
}
function goSearch() {
  // 更新 query 不会重新加载组件,适合搜索/分页
  router.replace({ query: { ...route.query, q: 'vue' } })
}
</script>

<template>
  <router-link :to="{ name: 'home' }">首页</router-link>
  <router-link :to="{ name: 'user-detail', params: { id: 1 } }">用户 1</router-link>
  <router-view v-slot="{ Component }">
    <KeepAlive>
      <component :is="Component" />
    </KeepAlive>
  </router-view>
</template>

三种路由守卫与权限控制示例:

// 1) 全局前置守卫:最常用于登录校验(在 router/index.ts 中注册)
router.beforeEach(async (to) => {
  const auth = useAuthStore()               // Pinia store
  const isPublic = to.meta.public === true  // 在路由上声明 meta.public
  if (isPublic) return true
  if (!auth.isLoggedIn) {
    // 返回一个 location 表示重定向;也可以 return false 取消导航
    return { name: 'login', query: { redirect: to.fullPath } }
  }
  if (to.meta.role && auth.role !== to.meta.role) return { name: 'forbidden' }
  return true
})

// 2) 全局解析守卫:在组件内守卫之前、异步路由组件解析之后执行
router.beforeResolve(async (to) => { /* 例如预取数据并做最后确认 */ })

// 3) 全局后置钩子:导航已确认,无法取消,适合埋点与标题
router.afterEach((to) => {
  document.title = (to.meta.title as string) ?? '我的应用'
})
// 4) 路由独享守卫:只对这条路由生效
{ path: '/admin', component: () => import('@/views/Admin.vue'), beforeEnter: (to) => true }

// 5) 组件内守卫(组合式 API)
onBeforeRouteLeave((to, from) => {
  // 常用于"表单未保存,确认离开吗?"
  if (hasUnsavedChanges.value && !window.confirm('放弃未保存的修改?')) return false
})
onBeforeRouteUpdate((to) => { /* 同一路由参数变化时触发 */ })
守卫类型注册位置能否取消/重定向典型用途
beforeEach全局可以登录与权限拦截、进度条开始
beforeResolve全局可以异步组件解析后的最终确认
afterEach全局不能埋点、设置标题、进度条结束
beforeEnter路由配置可以单条路由的专属校验
onBeforeRouteLeave / onBeforeRouteUpdate组件内可以未保存提醒、参数变化后重新取数

守卫里的常见错误

① beforeEach 里写 next() 又 return(Vue Router 4 支持返回值风格,两种混用容易出错,统一用返回值风格);

② 在守卫里 await 慢接口却没有 loading 反馈,用户以为页面死了;

③ 忘记给登录页设 meta.public,导致无限重定向到 /login。

3.10 Pinia:状态管理

为什么用 Pinia 而不是 Vuex:

对比项PiniaVuex(3/4)
写法组合式风格的 defineStorestate / mutations / actions / getters
修改 state直接在 action 里改,甚至组件里改必须通过 mutations,且必须同步
TypeScript类型推导自然,几乎不用手写类型需要额外的类型体操
模块化天然多 store,各自独立、可互相引用单 store + modules 命名空间嵌套
是否装 Vue 2 插件否(Vue 3 原生)需要 Vuex 4
官方定位Vue 官方推荐的状态管理库维护模式,新项目不推荐
// src/stores/counter.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

// Setup Store 写法(与组件里的组合式 API 完全一致,推荐)
export const useCounterStore = defineStore('counter', () => {
  // state
  const count = ref(0)
  const history = ref<number[]>([])

  // getters
  const double = computed(() => count.value * 2)
  const isPositive = computed(() => count.value > 0)

  // actions:可以是同步也可以是异步
  function increment(step = 1) {
    count.value += step
    history.value.push(count.value)
  }
  async function loadFromServer() {
    const res = await fetch('/api/counter')
    const data = (await res.json()) as { count: number }
    count.value = data.count
  }

  return { count, history, double, isPositive, increment, loadFromServer }
})
<script setup lang="ts">
import { storeToRefs } from 'pinia'
import { useCounterStore } from '@/stores/counter'

const counter = useCounterStore()

// ❌ 直接解构会丢响应式(同 reactive 的道理)
// const { count } = counter

// ✅ 用 storeToRefs 保留响应式;action 直接从 store 上取
const { count, double } = storeToRefs(counter)

function onClick() {
  counter.increment(2)      // 调用 action
  counter.count++           // 也允许直接改 state(Pinia 内部用 reactive)
}
</script>

<template>
  <p>{{ count }} / {{ double }}</p>
  <button @click="onClick">+2</button>
</template>

持久化思路:Pinia 本身不带持久化。三种做法:

// 做法一:手写订阅(无依赖,理解成本最低)
import { useUserStore } from '@/stores/user'

const KEY = 'user-store'
const userStore = useUserStore()

// 恢复:在创建 store 后立刻读一次
const saved = localStorage.getItem(KEY)
if (saved) userStore.$patch(JSON.parse(saved))

// 保存:订阅任何 state 变化($subscribe 对 patch 和直接赋值都生效)
userStore.$subscribe((_mutation, state) => {
  localStorage.setItem(KEY, JSON.stringify(state))
})

// 做法二:插件形式,全局给所有 store 加持久化
// 说明:这里把 context 的类型收敛成"实际用到的三个成员",避免写下随版本变化的内部类型名
interface StoreContext {
  store: {
    $id: string
    $state: Record<string, unknown>
    $patch: (partialState: Record<string, unknown>) => void
    $subscribe: (cb: (mutation: unknown, state: Record<string, unknown>) => void) => void
  }
}
export function persistPlugin({ store }: StoreContext) {
  const key = `pinia:${store.$id}`
  const raw = localStorage.getItem(key)
  if (raw) store.$patch(JSON.parse(raw) as Record<string, unknown>)
  store.$subscribe(() => localStorage.setItem(key, JSON.stringify(store.$state)))
}

// 做法三:使用社区的 pinia-plugin-persistedstate(配置最少,注意其 API 随版本变化,以官方最新文档为准)

3.11 实战:搜索防抖与分页

可组合函数(composable)风格的搜索:把"输入 → 防抖 → 请求 → 竞态处理"封装起来

// src/composables/useSearch.ts
import { ref, watch, onScopeDispose } from 'vue'

export interface PageResult<T> {
  list: T[]
  total: number
}

/**
 * 带防抖与竞态防护的分页搜索。
 * 关键点:
 *  1. 用 AbortController 取消上一次请求,避免慢响应覆盖新结果;
 *  2. 用 onScopeDispose 清理定时器与在途请求,组件卸载后不再 setState;
 *  3. 只有非空关键词才发起请求,避免打开页面就请求一次空数据。
 */
export function useSearch<T>(fetcher: (q: string, page: number, signal: AbortSignal) => Promise<PageResult<T>>, delay = 300) {
  const keyword = ref('')
  const page = ref(1)
  const pageSize = ref(10)
  const list = ref<T[]>([]) as { value: T[] }
  const total = ref(0)
  const loading = ref(false)
  const error = ref<string | null>(null)

  let timer: number | undefined
  let controller: AbortController | null = null

  async function run() {
    const q = keyword.value.trim()
    if (!q) {
      list.value = []
      total.value = 0
      return
    }
    controller?.abort()               // 取消在途请求(竞态防护)
    controller = new AbortController()
    loading.value = true
    error.value = null
    try {
      const res = await fetcher(q, page.value, controller.signal)
      list.value = res.list
      total.value = res.total
    } catch (e) {
      if ((e as Error).name !== 'AbortError') error.value = (e as Error).message
    } finally {
      loading.value = false
    }
  }

  // 关键词变化:重置到第一页 + 防抖
  watch(keyword, () => {
    page.value = 1
    window.clearTimeout(timer)
    timer = window.setTimeout(run, delay)
  })

  // 翻页:立即请求,不再防抖
  watch(page, () => {
    window.clearTimeout(timer)
    void run()
  })

  onScopeDispose(() => {
    window.clearTimeout(timer)
    controller?.abort()
  })

  return { keyword, page, pageSize, list, total, loading, error, refresh: run }
}
<!-- src/views/SearchView.vue:完整使用示例 -->
<script setup lang="ts">
import { computed } from 'vue'
import { useSearch } from '@/composables/useSearch'

interface Article { id: number; title: string }

// 用内存数据模拟后端分页,替换成真实 fetch 即可
async function fetcher(q: string, page: number, signal: AbortSignal) {
  const all: Article[] = Array.from({ length: 42 }, (_, i) => ({ id: i + 1, title: `${q} 的第 ${i + 1} 篇` }))
  await new Promise((r) => setTimeout(r, 300))
  if (signal.aborted) throw new DOMException('aborted', 'AbortError')
  const start = (page - 1) * 10
  return { list: all.slice(start, start + 10), total: all.length }
}

const { keyword, page, pageSize, list, total, loading, error } = useSearch<Article>(fetcher)
const totalPages = computed(() => Math.max(1, Math.ceil(total.value / pageSize.value)))
</script>

<template>
  <div>
    <input v-model.trim="keyword" placeholder="输入关键词搜索" />
    <p v-if="loading">加载中…</p>
    <p v-else-if="error">出错了:{{ error }}</p>
    <ul v-else>
      <li v-for="item in list" :key="item.id">{{ item.title }}</li>
    </ul>
    <div>
      <button :disabled="page <= 1" @click="page--">上一页</button>
      <span>{{ page }} / {{ totalPages }}</span>
      <button :disabled="page >= totalPages" @click="page++">下一页</button>
    </div>
  </div>
</template>

如果不想抽 composable,直接在组件里写防抖(注意 onUnmounted 清理):

<script setup lang="ts">
import { ref, watch, onUnmounted } from 'vue'
const keyword = ref('')
let timer: number | undefined
watch(keyword, (q) => {
  window.clearTimeout(timer)
  timer = window.setTimeout(() => console.log('请求:', q), 300)
})
onUnmounted(() => window.clearTimeout(timer))
</script>

3.12 样式方案

3.12.1 scoped 的原理与 :deep()
<style scoped>
/* 编译后大致变成:.title[data-v-7a7a37b1] { ... } */
.title { color: red; }

/* 子组件的根元素会同时带上父组件的 data-v-*,所以能这样选到 */
:deep(.child-inner) { color: blue; }

/* 想作用于插槽内容(插槽内容的"主人"是父组件)时用 :slotted */
:slotted(p) { margin: 0; }

/* 作用于全局(如 body、第三方弹窗挂载到 body 的节点) */
:global(.el-overlay) { z-index: 3000; }
</style>
写法作用范围何时使用
普通选择器仅当前组件的元素(带 data-v-*)默认
:deep(选择器)穿透到子组件内部元素改第三方组件库的内部样式
:slotted(选择器)父组件传入的插槽内容统一插槽内容的样式
:global(选择器)全局,无作用域属性body、挂到 body 的弹窗

为什么 :deep() 有时不生效

① 目标元素被 teleport 到了 body 外(用 :global 或 teleport 的 to 指定容器);

② 目标在子组件的子组件里,而中间那层没有把父组件的 data-v-* 传下去;

③ 优先级被样式库里的选择器压过(用 DevTools 看实际命中规则,而不是猜)。

3.12.2 CSS Modules 与 Tailwind
<!-- CSS Modules:类名在编译期被哈希化,天然隔离,适合从 React 迁移的团队 -->
<script setup lang="ts">
import styles from './UserCard.module.css'
console.log(styles.card)   // 例如 "_card_1a2b3"
</script>

<template>
  <div :class="styles.card">内容</div>
</template>
<!-- Tailwind:原子类写在模板里,无需给类命名,适合快速迭代 -->
<template>
  <div class="rounded-lg bg-white p-4 shadow hover:shadow-md">
    <h3 class="text-lg font-semibold text-gray-800">标题</h3>
    <p class="mt-1 text-sm text-gray-500">说明文字</p>
  </div>
</template>
方案隔离方式优点代价
<style scoped>编译期加 data-v-* 属性零依赖、写法接近普通 CSS深度选择器有学习成本;不影响子组件内部
CSS Modules类名哈希严格隔离、可组合、JS 里能拿到类名需要 .module.css,全局样式与第三方覆盖较绕
Tailwind原子类,天然不与选择器冲突迭代快、体积可控(按需生成)、设计约束统一模板变长、需要记类名、复杂选择器(如伪元素组合)要写配置
CSS-in-JS运行时或构建期生成逻辑与样式同源运行时开销与 SSR 复杂度,Vue 生态较小众

在 Vue 里用 Tailwind

Tailwind 4.x 起官方推荐用 @tailwindcss/vite 插件,在 vite.config.ts 中 plugins: [vue(), tailwindcss()],CSS 里 @import "tailwindcss"; 即可,不再需要 tailwind.config.js 与 postcss.config.js(具体配置方式以官方最新文档为准)。

3.13 性能优化

手段作用适用场景
v-once子树只渲染一次完全静态的内容(页脚、说明文字)
v-memo="[a, b]"数组内依赖不变则跳过该子树更新v-for 长列表中的行
v-pre跳过编译展示模板源码
shallowRef只追踪 .value 整体替换,不深度递归第三方实例(ECharts、地图)、大而不变的对象
shallowReactive只追踪第一层属性顶层字段少、深层数据只读的大对象
markRaw标记对象永不被转为响应式类实例、常量配置
computed 代替重复计算复用计算结果所有派生值
虚拟列表只渲染可视区域内的项上万条数据的列表
路由懒加载按路由分包多页面应用的首屏优化
defineAsyncComponent按需加载组件弹窗、富文本编辑器等重组件
<script setup lang="ts">
import { shallowRef, triggerRef, onMounted } from 'vue'
import * as echarts from 'echarts'

// 图表实例是一个庞大的对象,深度响应式化毫无意义还拖慢性能
const chartRef = shallowRef<echarts.ECharts>()
const container = shallowRef<HTMLDivElement>()

onMounted(() => {
  chartRef.value = echarts.init(container.value!)
  chartRef.value.setOption({ xAxis: {}, yAxis: {}, series: [] })
  // 若确实需要"整体替换"以外的更新,明确调用 triggerRef 手动触发
  triggerRef(chartRef)
})
</script>

<template>
  <div ref="container" style="height: 320px"></div>
</template>
<!-- v-memo:只有当 item.id 或 item.done 变化时才更新这一行 -->
<template>
  <div v-for="item in list" :key="item.id" v-memo="[item.id, item.done]">
    <span>{{ item.title }}</span>
    <b>{{ item.done ? '已完成' : '待办' }}</b>
  </div>
</template>

虚拟列表思路(不引库的最小实现):

<script setup lang="ts">
import { ref, computed } from 'vue'

const props = withDefaults(defineProps<{ items: unknown[]; itemHeight?: number; height?: number }>(), {
  itemHeight: 40,
  height: 400,
})
const scrollTop = ref(0)

// 可见项索引区间:向上多渲染 3 项缓冲,避免快速滚动时露白
const start = computed(() => Math.max(0, Math.floor(scrollTop.value / props.itemHeight) - 3))
const visibleCount = computed(() => Math.ceil(props.height / props.itemHeight))
const end = computed(() => Math.min(props.items.length, start.value + visibleCount.value + 6))
const visible = computed(() => props.items.slice(start.value, end.value))
const offsetY = computed(() => start.value * props.itemHeight)
</script>

<template>
  <div :style="{ height: `${height}px`, overflowY: 'auto' }" @scroll.passive="scrollTop = ($event.target as HTMLElement).scrollTop">
    <!-- 占位撑起总高度,让滚动条反映真实数据量 -->
    <div :style="{ height: `${items.length * itemHeight}px`, position: 'relative' }">
      <div :style="{ transform: `translateY(${offsetY}px)` }">
        <div v-for="(item, i) in visible" :key="start + i" :style="{ height: `${itemHeight}px` }">
          <slot :item="item" :index="start + i" />
        </div>
      </div>
    </div>
  </div>
</template>

不要过早优化

Vue 的编译器已做静态提升、补丁标记等优化,绝大多数页面不需要手写 v-memo、shallowRef。先用 DevTools 的 Performance 面板找到真正的瓶颈(通常是长列表或昂贵的子组件重渲染),再对症优化。

3.14 完整示例:TodoList(增删改查 + 过滤 + 本地存储)

这个组件把本篇的响应式、computed、watch、事件、列表渲染、生命周期、持久化串起来,可以直接放进 npm create vue@latest 生成的项目里跑。

<!-- src/components/TodoList.vue -->
<script setup lang="ts">
import { ref, computed, watch, onMounted } from 'vue'

interface Todo {
  id: number
  title: string
  done: boolean
}

type Filter = 'all' | 'active' | 'done'

const STORAGE_KEY = 'vue-todolist'

// ---------- 状态 ----------
const todos = ref<Todo[]>([])
const draft = ref('')            // 新增输入
const filter = ref<Filter>('all')
const editingId = ref<number | null>(null)  // 正在编辑哪一项
const editingText = ref('')

// ---------- 派生数据(computed 而不是 watch + 手动维护) ----------
const remaining = computed(() => todos.value.filter((t) => !t.done).length)
const visibleTodos = computed(() => {
  switch (filter.value) {
    case 'active':
      return todos.value.filter((t) => !t.done)
    case 'done':
      return todos.value.filter((t) => t.done)
    default:
      return todos.value
  }
})
const allDone = computed({
  get: () => todos.value.length > 0 && todos.value.every((t) => t.done),
  // 可写 computed:把"全选/取消全选"这个动作也表达成一个可赋值的值
  set: (v: boolean) => todos.value.forEach((t) => (t.done = v)),
})

// ---------- 增删改查 ----------
function addTodo() {
  const title = draft.value.trim()
  if (!title) return                 // 空标题不入库
  todos.value.unshift({ id: Date.now(), title, done: false })
  draft.value = ''
}
function removeTodo(id: number) {
  todos.value = todos.value.filter((t) => t.id !== id)
}
function startEdit(todo: Todo) {
  editingId.value = todo.id
  editingText.value = todo.title
}
function commitEdit(todo: Todo) {
  const title = editingText.value.trim()
  if (title) todo.title = title       // 数组内对象的属性可直接改,ref 会追踪
  editingId.value = null
}
function clearDone() {
  todos.value = todos.value.filter((t) => !t.done)
}

// ---------- 持久化 ----------
onMounted(() => {
  const raw = localStorage.getItem(STORAGE_KEY)
  if (!raw) return
  try {
    const parsed = JSON.parse(raw) as unknown
    // 数据来自外部,必须校验形状,避免脏数据把页面搞崩
    if (Array.isArray(parsed)) todos.value = parsed as Todo[]
  } catch {
    localStorage.removeItem(STORAGE_KEY)   // 损坏的缓存直接丢弃
  }
})

watch(
  todos,
  (val) => localStorage.setItem(STORAGE_KEY, JSON.stringify(val)),
  { deep: true },   // 元素属性变化(改标题、勾选)也要落盘
)
</script>

<template>
  <div class="todo">
    <h2>待办清单(剩余 {{ remaining }} 项)</h2>

    <form class="add" @submit.prevent="addTodo">
      <input v-model.trim="draft" placeholder="输入后回车添加" />
      <button type="submit" :disabled="!draft.trim()">添加</button>
    </form>

    <label class="all">
      <input type="checkbox" v-model="allDone" />
      全选
    </label>

    <ul class="list">
      <!-- 用 todo.id 作 key:删除中间项时不会串位 -->
      <li v-for="todo in visibleTodos" :key="todo.id" :class="{ done: todo.done }">
        <input type="checkbox" v-model="todo.done" />

        <!-- 编辑态与展示态互斥 -->
        <template v-if="editingId === todo.id">
          <input
            v-model.trim="editingText"
            @keyup.enter="commitEdit(todo)"
            @keyup.esc="editingId = null"
            v-focus
          />
          <button @click="commitEdit(todo)">保存</button>
        </template>
        <template v-else>
          <span @dblclick="startEdit(todo)">{{ todo.title }}</span>
          <button @click="startEdit(todo)">编辑</button>
        </template>

        <button class="del" @click="removeTodo(todo.id)">删除</button>
      </li>
    </ul>

    <p v-if="visibleTodos.length === 0" class="empty">这里还没有内容</p>

    <div class="footer">
      <button :class="{ active: filter === 'all' }" @click="filter = 'all'">全部</button>
      <button :class="{ active: filter === 'active' }" @click="filter = 'active'">未完成</button>
      <button :class="{ active: filter === 'done' }" @click="filter = 'done'">已完成</button>
      <button @click="clearDone">清除已完成</button>
    </div>
  </div>
</template>

<style scoped>
.todo { max-width: 520px; margin: 24px auto; font-family: system-ui, sans-serif; }
.add { display: flex; gap: 8px; margin-bottom: 8px; }
.add input { flex: 1; padding: 6px 8px; }
.list { list-style: none; padding: 0; }
.list li { display: flex; align-items: center; gap: 8px; padding: 6px 0; border-bottom: 1px solid #eee; }
.list li.done span { text-decoration: line-through; color: #999; }
.list li span { flex: 1; cursor: pointer; }
.del { color: #d33; }
.empty { color: #999; text-align: center; }
.footer { display: flex; gap: 8px; margin-top: 12px; }
.footer button.active { font-weight: 700; border-color: #42b883; color: #42b883; }
</style>

v-focus 是一个自定义指令(进入编辑时自动聚焦),放在 src/directives/focus.ts:

// src/directives/focus.ts
import type { Directive } from 'vue'

// 自定义指令的生命周期:created / beforeMount / mounted / beforeUpdate / updated / beforeUnmount / unmounted
export const vFocus: Directive<HTMLInputElement> = {
  mounted(el) {
    el.focus()
  },
}
// src/main.ts 注册
import { createApp } from 'vue'
import App from './App.vue'
import { vFocus } from './directives/focus'

createApp(App).directive('focus', vFocus).mount('#app')

这个示例里值得回看的五个设计点:

  1. visibleTodos / remaining 都是 computed,没有用 watch 手动维护一份"过滤后的数组"——少一份状态就少一类 bug。
  2. allDone 用可写 computed 表达"全选的当前值 + 全选动作",模板里直接 v-model="allDone"。
  3. key 用 todo.id,removeTodo 删中间项时输入框与勾选状态不会串位。
  4. 从 localStorage 反序列化后先做形状校验,脏数据不会让页面崩。
  5. watch(todos, ..., { deep: true }) 保证"改标题"这种深层变更也会落盘;如果只监听整体替换,编辑标题就不会被保存。

想加"撤销删除"

把 removeTodo 改成先记录被删项与其索引,提供 3 秒内的撤销按钮(配合 setTimeout 与 onUnmounted 清理),这就是练习 5。


四、常见坑

十个高频错误

1. 忘记 .value:count++ 写成 count.value++ 才对;ref 数组要用 list.value.push(x)。

2. 解构 reactive:const { name } = state 后改名不生效,要 toRefs 或直接用 ref。

3. 给 reactive 重新赋值:state = { ...state, a: 1 } 会切断响应式;应逐字段赋值或改用 ref。

4. key 用索引:列表中间增删时输入框内容错位,用业务 id。

5. v-if 与 v-for 同用在一个元素上:v-if 会逐项求值,想过滤应先用 computed 得到新数组。

6. 在 computed 里发请求或改状态:求值时机不可预测,副作用要放 watch。

7. watch 侦听 ref 对象的深层变化忘记 deep: true:watch(user, ...) 里 user 若是 ref({}),改属性不会触发。

8. 不清理副作用:定时器、addEventListener、WebSocket 没在 onUnmounted 里清理,导致内存泄漏与重复请求。

9. 直接改 props:props.title = 'x' 报错;应 emit 或建本地副本配合 watch。

10. v-html 渲染用户输入:XSS 风险;必须用白名单净化。

调试建议

① 装 Vue DevTools,能直接看到组件树里每个 ref 的实时值,比 console.log 快得多;

② 响应式"没生效"时先确认三点——数据是不是响应式的、改的是不是同一个对象、读的地方有没有在依赖链上;

③ 模板报错信息里有组件名与行号,先看控制台第一条错误,它往往才是根因。


五、练习题

  1. 基础题:写一个 TemperatureConverter.vue,包含摄氏与华氏两个输入框,v-model.number 双向同步,用 computed 的 get/set 实现"改任意一个,另一个立刻跟着变",并在任一方输入非数字时显示提示。
  2. 组件通信题:实现 Pagination.vue,接收 total、pageSize、current 三个 props,内部不许改 props;通过 emit('update:current', n) 让父组件用 v-model:current 绑定;再补一个 pageSize 选择器(10/20/50),同样用 v-model:pageSize 上报。
  3. 响应式辨析题:解释下列四段代码各自会不会触发视图更新,并说明原因;不会的请给出两种修法。

```ts

const s = reactive({ a: { b: 1 } })

s = { a: { b: 2 } } // ①

const { a } = s; a.b = 3 // ②

const r = ref({ n: 1 }); r.value.n = 2 // ③

const l = ref([1, 2]); l.value = [...l.value, 3] // ④

```

  1. 性能题:用 useSearch composable 的思路,写一个不依赖第三方库的 useDebouncedRef<T>(source, delay),返回防抖后的值;再写一个 useThrottle,说明两者在"输入框搜索"与"滚动监听"场景下分别为什么更合适。
  2. 综合题:给 3.14 的 TodoList 增加"撤销删除":删除后 3 秒内可撤销;如果 3 秒内组件被卸载,定时器必须清理;localStorage 里不能留下"待撤销"的中间状态。写完后回答:撤销状态应该放在 ref 还是 computed?它需要持久化吗?

六、常见问题(FAQ)

Q1:学了 Vue 3 的组合式 API,还需要看 Vue 2 的 Options API 吗?

A:做新项目不需要。但国内仍有大量存量项目在 Vue 2 上,接手时你会看到 data()、methods、this.$emit`、`this.$refs。建议只掌握"能读懂"的程度:知道 this 上的东西在组合式里分别对应 ref、函数、defineEmits、模板 ref 即可,不要混着写。Vue 2 已于 2023-12-31 停止维护,新项目请直接用 Vue 3。

Q2:ref 和 reactive 到底选哪个?

A:默认 ref。理由:能包装所有类型、支持整体替换(user.value = newUser 很常见)、可以安全地解构与传递、团队风格统一。reactive 只在"字段固定的表单对象、不做整体替换、不解构"时才更省事。注意 Vue 3.5 对 reactive 做了一些改进,但解构丢响应式这一点没有变,仍需要 toRefs(以官方最新文档为准)。

Q3:有了 provide/inject 和 pinia,什么时候才需要状态管理库?

A:判断顺序是:① 只在父子间用 → props/emit;② 只在某个子树内共享(主题、表单上下文)→ provide/inject;③ 跨路由、跨页面长期存在、多个不相关组件都要读写、需要被 DevTools 追踪与调试 → Pinia。典型信号是"同一个数据你已经在三个地方各自维护了一份副本"。不要一上来就全局 store:状态越集中,组件越难复用。

Q4:为什么我的 watch 没触发?

A:按顺序检查四件事:① 侦听的是 ref 还是 reactive(侦听 reactive 对象默认深层,侦听 ref 包的对象需要 deep: true);② 是否侦听了一个非响应式的普通变量或解构出来的值;③ 是否给 watch 传了 () => obj.prop 这样的 getter(正确)而不是 obj.prop 的值(错误,等于传了个常量);④ 变化是否发生在 flush 时机之后——需要"DOM 更新后再执行"时要写 { flush: 'post' }。

Q5:开发时数据变了视图没变,怎么快速定位?

A:在 Vue DevTools 里看该数据的值是否真的变了。若值变了但视图没变,通常是"你改的不是响应式源头"(比如改的是解构出来的副本、或数组用 arr[i] = x 之外的赋值方式改了长度以外的东西)。一个实用检查法:把要显示的值换成 <pre>{{ JSON.stringify(state) }}</pre> 直接观察。若值没变,问题在赋值处,而不是在响应式系统。


相关笔记

  • 前端-07-React:同一批问题的另一套答案,对照读能看清"响应式可变"与"不可变 + 重渲染"的取舍
  • 前端-08-构建工具-Vite与Webpack:@vitejs/plugin-vue、热更新(HMR)与生产构建的原理
  • 前端-05-TypeScript:defineProps<Props>()、InjectionKey、storeToRefs 的类型推导基础
  • JavaScript-07-ES6新特性:Proxy 与 Reflect 是 Vue 3 响应式系统的底层机制

参考来源

以下链接核实于 2026-10-11,均为官方文档(Vue 官方中文文档在 cn.vuejs.org 提供与英文版同步的内容):

  • Vue 官方中文文档 · 简介(渐进式框架、声明式渲染):<https://cn.vuejs.org/guide/introduction>
  • Vue 官方中文文档 · 响应式基础(ref / reactive / toRefs):<https://cn.vuejs.org/guide/essentials/reactivity-fundamentals>
  • Vue 官方中文文档 · 模板语法(插值、指令、修饰符):<https://cn.vuejs.org/guide/essentials/template-syntax>
  • Vue 官方中文文档 · 组件 Props(声明、校验、单向数据流):<https://cn.vuejs.org/guide/components/props>
  • Vue 官方中文文档 · 组合式函数(composable 的写法与清理):<https://cn.vuejs.org/guide/reusability/composables>
  • Vue 官方中文文档 · 路由(官方 SPA 路由方案与守卫):<https://cn.vuejs.org/guide/scaling-up/routing>
  • Pinia 官方文档(中文):<https://pinia.vuejs.org/zh/>
  • Vite 官方文档(脚手架与 @vitejs/plugin-vue):<https://vite.dev/guide/>

版本说明

本篇对应 Vue 3.5.x(本库核实时 npm latest 为 3.5.43,3.6 处于 RC 阶段)与 Pinia 3.x、Vue Router 4.x。

其中 defineModel(3.4+ 稳定)、defineOptions(3.3+)、useTemplateRef(3.5+)等 API 存在的版本下限,以及 Vue 3.6 的正式发布状态,均以官方最新文档与发布说明为准。

Vue 2 已于 2023-12-31 结束维护,本库不再覆盖其写法。