前端-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 3 | React 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@latest | Vite 手动搭建 |
|---|---|---|
| 上手速度 | 一条命令得到完整工程 | 需要理解每个配置项 |
| 默认包含 | 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-if | v-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>
| 对比项 | ref | reactive | |
|---|---|---|---|
| 可包装类型 | 任意(含 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>
| 对比项 | computed | watch | watchEffect |
|---|---|---|---|
| 返回值 | 派生出的值 | 无(用于副作用) | 无(用于副作用) |
| 依赖来源 | 自动收集 | 显式指定 | 自动收集 |
| 是否立即执行 | 读取时惰性求值 | 默认否(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 / emit | provide / 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 更新前 | 更新前记录滚动位置 |
onUpdated | DOM 更新完成后 | 依赖新 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 开关 props | showHeader、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:
| 对比项 | Pinia | Vuex(3/4) |
|---|---|---|
| 写法 | 组合式风格的 defineStore | state / 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')
这个示例里值得回看的五个设计点:
visibleTodos/remaining都是computed,没有用watch手动维护一份"过滤后的数组"——少一份状态就少一类 bug。allDone用可写computed表达"全选的当前值 + 全选动作",模板里直接v-model="allDone"。key用todo.id,removeTodo删中间项时输入框与勾选状态不会串位。- 从
localStorage反序列化后先做形状校验,脏数据不会让页面崩。 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快得多;② 响应式"没生效"时先确认三点——数据是不是响应式的、改的是不是同一个对象、读的地方有没有在依赖链上;
③ 模板报错信息里有组件名与行号,先看控制台第一条错误,它往往才是根因。
五、练习题
- 基础题:写一个
TemperatureConverter.vue,包含摄氏与华氏两个输入框,v-model.number双向同步,用computed的get/set实现"改任意一个,另一个立刻跟着变",并在任一方输入非数字时显示提示。 - 组件通信题:实现
Pagination.vue,接收total、pageSize、current三个 props,内部不许改 props;通过emit('update:current', n)让父组件用v-model:current绑定;再补一个pageSize选择器(10/20/50),同样用v-model:pageSize上报。 - 响应式辨析题:解释下列四段代码各自会不会触发视图更新,并说明原因;不会的请给出两种修法。
```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] // ④
```
- 性能题:用
useSearchcomposable 的思路,写一个不依赖第三方库的useDebouncedRef<T>(source, delay),返回防抖后的值;再写一个useThrottle,说明两者在"输入框搜索"与"滚动监听"场景下分别为什么更合适。 - 综合题:给 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 结束维护,本库不再覆盖其写法。