Vue / 知识点
Vue 3 开发速查手册
手册条目
使用 watchEffect 自动收集同步执行期间访问的响应式依赖。
自动追踪副作用
当副作用依赖多个响应式值,或依赖关系会随分支变化时,使用 watchEffect 可在执行回调时自动收集被读取的依赖,并在依赖变化后重新运行。它适合请求刷新、日志联动和轻量同步;需要精确控制监听源时应改用 watch。
基本语法
watchEffect(effect, options?) 会立即执行一次回调。回调同步执行期间读取到的 ref、reactive 属性或计算值会成为依赖;任一依赖变化后,Vue 会安排下一次执行。
<script setup>
import { ref, watchEffect } from 'vue'
const keyword = ref('vue')
const page = ref(1)
watchEffect((onCleanup) => {
const controller = new AbortController()
// 同步读取 keyword 和 page,因此两者都会成为依赖
console.log(`load: keyword=${keyword.value}, page=${page.value}`)
onCleanup(() => {
controller.abort()
console.log('cleanup previous effect')
})
})
setTimeout(() => {
page.value = 2
}, 0)
</script>
<template>
<p>{{ keyword }} / page {{ page }}</p>
</template>预期输出
load: keyword=vue, page=1
cleanup previous effect
load: keyword=vue, page=2开发环境下日志附近可能出现框架调试信息,但读取顺序不变:首次立即执行;page 变化前先清理旧副作用,再运行新副作用。
高频用法
用于自动刷新请求时,把本次请求使用的响应式参数放在回调的同步部分读取,并在 onCleanup 中取消旧请求。用于联动浏览器 API 时,在回调中注册监听器,在清理函数中移除,避免重复绑定。
依赖必须在同步阶段被访问。异步回调执行到第一个 await 后才读取的响应式值不会被自动收集;可在 await 前保存所需值,或改用 watch 显式声明监听源。
常用选项
flush: 'pre' 是默认值,回调通常在组件更新前运行;flush: 'post' 适合读取更新后的 DOM;flush: 'sync' 会同步触发,容易造成重复执行或性能抖动,只应用于简单且低频的状态。
调试依赖时可使用 onTrack 和 onTrigger,它们仅用于开发诊断,不应承载业务逻辑。
风险与边界
回调内若无条件修改自己读取的状态,可能形成持续重跑。触发条件是副作用既读取又反复写入同一依赖;后果是高 CPU、界面卡顿或无限更新。安全替代方案是将状态推导改为 computed,或使用 watch 比较新旧值后再写入。
watchEffect 返回停止函数。组件 setup 同步创建的监听会随组件卸载自动停止;在异步回调中延迟创建的监听可能脱离组件生命周期,应保存并主动调用停止函数。
兼容性
watchEffect 适用于 Vue 3。为兼容较早的 Vue 3 小版本,清理逻辑优先使用回调参数 onCleanup;较新的 onWatcherCleanup 需要按项目锁定的 Vue 版本确认后再使用。
在组件挂载、更新和卸载阶段执行初始化或清理逻辑。
使用生命周期钩子
在组件创建、挂载、更新和卸载的明确阶段执行初始化或清理逻辑时,使用组合式 API 生命周期钩子。常见做法是在 onMounted 访问 DOM,在 onUpdated 观察渲染后的变化,并在 onUnmounted 释放定时器、事件监听和第三方实例。
生命周期位置

组合式 API 的钩子必须在 setup() 或 <script setup> 的同步执行期间注册。onMounted 只表示当前组件的同步子组件已挂载,不代表异步组件、远程数据或图片资源已经完成。
主示例
下面的组件在挂载后启动计时器,更新后记录 DOM 文本,并在卸载时释放资源。父组件通过条件渲染移除它时,清理逻辑会执行。
<script setup>
import { onMounted, onUpdated, onUnmounted, ref } from 'vue'
const count = ref(0)
let timerId
onMounted(() => {
console.log('mounted')
timerId = window.setInterval(() => {
count.value += 1
}, 1000)
})
onUpdated(() => {
console.log(`updated: count=${count.value}`)
})
onUnmounted(() => {
window.clearInterval(timerId)
console.log('unmounted and timer cleared')
})
</script>
<template>
<p>count: {{ count }}</p>
</template>预期输出
mounted
updated: count=1
updated: count=2
...
unmounted and timer cleared最后一行只会在组件被卸载时出现;计数次数取决于组件保留时间,因此中间值可能不同。
常用钩子
onBeforeMount 用于首次 DOM 提交前的少量准备,但此时不能访问已挂载元素。onMounted 适合读取模板引用、初始化图表或绑定仅浏览器可用的 API。onBeforeUpdate 可在 DOM 更新前读取旧状态,onUpdated 可读取新 DOM,但不应在其中无条件修改响应式状态。
onBeforeUnmount 适合在组件仍完整可用时通知第三方实例停止工作;onUnmounted 适合清除定时器、事件监听、观察器和订阅。若清理依赖实例仍挂载,应放在 onBeforeUnmount,否则通常放在 onUnmounted。
风险与边界
在 onUpdated 中直接修改其依赖的响应式状态会再次触发更新,可能形成无限循环。触发条件是每次更新都无条件写状态;后果是 Maximum recursive updates exceeded、页面卡顿或 CPU 升高。安全替代方案是使用 watch 监听特定值,或增加严格条件避免重复写入。
服务端渲染期间不会执行 onMounted 和 onUnmounted。访问 window、document 或浏览器插件的代码应放入 onMounted,并在卸载时成对清理,避免 SSR 报错和客户端内存泄漏。
排障清单
钩子未执行时,先确认它是否在 <script setup> 顶层同步注册,并确认组件确实完成挂载或卸载。清理未发生时,检查父组件是否只是通过 CSS 隐藏,而不是使用 v-if 移除;v-show 不会卸载组件。开发环境使用 KeepAlive 时,还需根据缓存行为改用 onActivated 和 onDeactivated。
兼容性
这些钩子适用于 Vue 3 组合式 API。使用 KeepAlive、Suspense、异步组件或 SSR 时,挂载与激活语义会不同,应按实际渲染方式选择 onActivated、onDeactivated 或服务端专用钩子。
使用模板引用获取 DOM 元素或子组件公开的实例能力。
访问模板元素
当逻辑必须直接调用 DOM 方法,或父组件需要调用子组件主动公开的方法时,使用模板引用。引用只在组件挂载后可用;普通渲染逻辑仍应优先通过 props、事件和响应式状态完成。
基本语法
在模板上声明 ref="名称",在 <script setup> 中创建同名的 ref(null)。挂载前值为 null;DOM 元素挂载后得到原生元素,子组件挂载后得到组件公开实例。
下面示例同时演示聚焦输入框,以及父组件调用子组件通过 defineExpose 暴露的 open 方法。ChildPanel.vue:
<script setup>
import { ref } from 'vue'
const status = ref('closed')
function open() {
status.value = 'opened from parent'
}
// <script setup> 组件默认是封闭的,只公开父组件确实需要的能力。
defineExpose({ open })
</script>
<template>
<p data-testid="panel-status">{{ status }}</p>
</template>App.vue:
<script setup>
import { onMounted, ref } from 'vue'
import ChildPanel from './ChildPanel.vue'
const searchInput = ref(null)
const childPanel = ref(null)
onMounted(() => {
// 此时元素和子组件都已挂载,可以安全访问引用。
searchInput.value?.focus()
childPanel.value?.open()
})
</script>
<template>
<input ref="searchInput" aria-label="Search" value="Vue 3">
<ChildPanel ref="childPanel" />
</template>预期结果:
页面加载后,输入框自动获得焦点。
子组件显示:opened from parent读取方法:浏览器中可直接观察焦点和文本;调试时打印 searchInput.value 会得到 HTMLInputElement,打印 childPanel.value 只能看到子组件通过 defineExpose 公开的成员。
高频用法
需要读取尺寸或滚动位置时,在 onMounted、事件处理器或 DOM 更新后的 nextTick 中访问 el.value.getBoundingClientRect()、scrollIntoView() 等原生 API。
需要控制第三方组件时,先确认组件文档是否提供实例方法。优先保存最小公开接口,不要依赖子组件内部响应式变量或未公开方法。
对动态元素使用 v-if 时,元素被移除后引用会重新变为 null。访问前使用可选链,或在相关状态更新后等待 nextTick。
风险与边界
模板引用会增加父子组件耦合。父组件直接操纵子组件内部状态,可能导致重构时静默失效;安全替代方案是优先使用 props 传入状态、通过 emit 上报事件,只把聚焦、打开、校验等命令式能力放入 defineExpose。
不要在 setup 顶层立即读取 .value,触发条件是组件尚未挂载,结果通常为 null。安全做法是在 onMounted 中读取;元素受条件渲染影响时,还要在状态切换后等待 DOM 刷新。
排障清单
- 引用始终为
null:核对模板中的ref名称、脚本变量名以及元素是否被v-if移除。 - 子组件方法为
undefined:确认子组件使用defineExpose({ methodName }),且父组件调用名称完全一致。 - 引用指向旧元素:检查是否在列表中复用了不稳定的
key,或是否在更新完成前读取 DOM。 - 服务端渲染报错:DOM API 只能在客户端挂载后执行,不要在模块顶层访问
window、document或元素引用。
兼容性
ref(null) 方式适用于 Vue 3 各常用版本。Vue 3.5 及以上还可使用 useTemplateRef() 获得更明确的模板引用表达,但项目需要兼容较早版本时继续使用本条目的写法。
使用 nextTick 在响应式变更完成 DOM 刷新后执行代码。
等待 DOM 更新
响应式状态修改后,Vue 会把同一轮中的多次变更合并,并在后续刷新周期更新 DOM。需要读取更新后的文本、尺寸、焦点目标或调用依赖新节点的插件时,使用 await nextTick()。
基本语法
nextTick 从 vue 导入。先修改响应式状态,再等待 DOM 刷新;等待完成后,当前组件及相关子组件的待处理 DOM 更新通常已经提交。
<script setup>
import { nextTick, ref } from 'vue'
const count = ref(0)
const countEl = ref(null)
const logs = ref([])
async function incrementAndRead() {
count.value += 1
const before = countEl.value.textContent
await nextTick()
const after = countEl.value.textContent
logs.value.push(`before=${before}, after=${after}`)
}
</script>
<template>
<button type="button" @click="incrementAndRead">Increment</button>
<p ref="countEl">{{ count }}</p>
<pre>{{ logs.join('\n') }}</pre>
</template>首次点击后的预期结果:
页面计数显示:1
日志显示:before=0, after=1读取方法:count.value 在赋值后立即变为 1,但同一调用栈内的 DOM 仍可能显示旧值 0;await nextTick() 返回后再读取,得到新文本 1。
高频用法
状态切换后需要聚焦新出现的输入框时,先令 showInput.value = true,再等待 nextTick,最后调用模板引用的 focus()。否则触发条件是节点尚未创建,可能得到 null。
列表追加数据后需要滚动到底部时,先更新数组,再等待 DOM 生成新增行,然后读取容器的 scrollHeight 并设置 scrollTop。这样读取到的是更新后的布局高度。
连续修改多个状态时通常只需在最后等待一次。Vue 会批量处理本轮更新,多次无条件调用 nextTick 不会让业务状态更可靠,只会让执行顺序更难追踪。
风险与边界
nextTick 只等待 Vue 当前待处理的 DOM 刷新,不等待网络请求、图片加载、CSS 动画、浏览器下一帧绘制或第三方库内部异步任务。若目标依赖图片尺寸,应监听 load;若依赖下一帧布局或动画,可在 nextTick 后再使用 requestAnimationFrame。
不要用 setTimeout(..., 0) 代替。定时器只能推迟执行,无法表达“等待 Vue 完成本轮更新”的意图,在测试环境或复杂更新链中可能出现偶发错误。安全替代方案是 await nextTick(),或对持续性的更新后副作用使用 watch 并设置 flush: 'post'。
排障清单
- 等待后仍找不到元素:检查元素是否真的满足
v-if条件,以及模板引用名称是否一致。 - 读取尺寸仍为
0:确认元素没有被display: none隐藏,并判断是否还需等待字体、图片或下一帧布局。 - 日志顺序混乱:检查异步函数是否被高频重复触发;必要时加互斥状态、取消旧任务或只保留最后一次操作。
- 测试断言偶发失败:触发状态变更后先
await nextTick();若组件还发起 Promise、请求或定时器,还需分别等待对应任务。
兼容性
nextTick 是 Vue 3 的稳定公开 API,可使用 Promise 形式 await nextTick(),也可传入回调。组合式 API 中优先使用 await,错误栈和执行顺序更容易排查。
声明父组件传入的数据,并配置 TypeScript 类型、默认值和校验规则。
声明组件 Props
使用 defineProps() 明确子组件可接收的数据。需要同时获得 TypeScript 推断、默认值和运行时校验时,优先使用对象式声明;只需要类型约束时,可使用泛型声明。
基本语法
在 Vue 3 + Vite 项目中,新建 StatCard.vue。defineProps 是 <script setup> 编译宏,无需导入;复杂对象或数组类型通过 PropType 标注。
<script setup lang="ts">
import type { PropType } from 'vue'
const props = defineProps({
title: {
type: String,
required: true
},
count: {
type: Number,
default: 0,
// 校验失败会在开发环境给出警告,但不会替代业务校验
validator(value: number) {
return Number.isInteger(value) && value >= 0
}
},
tags: {
type: Array as PropType<string[]>,
// 数组和对象默认值使用工厂函数,避免实例间共享引用
default: () => []
}
})
</script>
<template>
<section>
<strong>{{ props.title }}:{{ props.count }}</strong>
<p>标签数:{{ props.tags.length }}</p>
</section>
</template>父组件 App.vue 传入必填值和动态数值;未传 tags 时使用空数组默认值。
<script setup lang="ts">
import StatCard from './StatCard.vue'
</script>
<template>
<StatCard title="待处理" :count="3" />
</template>预期结果
待处理:3
标签数:0读取方法:模板中可直接访问 props.title、props.count 和 props.tags;父组件传入的 :count="3" 保持数字类型,不会变成字符串。
高频用法
必填属性使用 required: true;可选属性通过 default 提供稳定值。字符串字面量、对象、数组等复杂类型使用 PropType<T>。仅做编译期约束时,可写 defineProps<{ title: string; count?: number }>();需要默认值可配合 withDefaults,但不能把泛型声明和对象式运行时声明写在同一次 defineProps() 中。
父组件传静态字符串可写 title="待处理",传数字、布尔值、数组或对象必须使用 v-bind,例如 :count="3"。属性名在脚本中通常使用 camelCase,在模板中推荐使用 kebab-case,例如 userId 对应 user-id。
风险与边界
Props 是单向数据流,子组件不应直接修改 props.count。直接赋值会触发只读警告;若需要本地编辑,先复制到 ref,或通过事件通知父组件更新。对象和数组的嵌套字段仍可能被修改,但会造成父子状态耦合,安全做法仍是发事件或传入不可变数据。
运行时 type 和 validator 主要用于开发期提示,不能当作接口安全校验。外部数据进入应用时应先在请求层或表单层校验,再传给组件;否则生产构建中可能缺少可依赖的警告。
排障清单
- 控制台提示缺少必填 Prop:检查父组件属性名、条件渲染和异步数据初始值。
- 数字收到字符串:把
count="3"改为:count="3"。 - 默认数组被多个实例共享:确认
default写成() => [],对象同理。 - TypeScript 类型正确但仍需业务规则:补充对象式
validator,并在数据入口执行真正的校验。 - 编译提示宏位置错误:
defineProps()必须直接位于<script setup>顶层,不能放进函数或条件分支。
兼容性
对象式 defineProps()、PropType 和 <script setup> 适用于 Vue 3.2 及以上。若项目使用较新的 Vue 3,可使用响应式 Props 解构;为兼容不同 Vue 3 小版本和避免解构丢失响应性,速查场景中直接读取 props.xxx 最稳妥。
声明并触发组件自定义事件,将操作结果通知父组件。
触发组件事件
使用 defineEmits() 声明子组件能够触发的自定义事件,并通过 emit() 把操作结果传给直接父组件。TypeScript 项目应同时声明事件名和载荷类型,避免参数数量或字段类型写错。
基本语法
在 Vue 3 + Vite 项目中,新建 ActionPanel.vue。下面声明 submit 和 cancel 两个事件;submit 携带结果对象,cancel 不携带参数。
<script setup lang="ts">
type SubmitResult = {
id: number
ok: boolean
}
const emit = defineEmits<{
submit: [result: SubmitResult]
cancel: []
}>()
function submit() {
// 先完成子组件内部处理,再把稳定的数据结构交给父组件
emit('submit', { id: 101, ok: true })
}
function cancel() {
emit('cancel')
}
</script>
<template>
<button type="button" @click="submit">提交</button>
<button type="button" @click="cancel">取消</button>
</template>父组件 App.vue 使用 @事件名 监听,监听函数的第一个参数就是子组件传出的载荷。
<script setup lang="ts">
import { ref } from 'vue'
import ActionPanel from './ActionPanel.vue'
type SubmitResult = {
id: number
ok: boolean
}
const status = ref('未操作')
function handleSubmit(result: SubmitResult) {
status.value = result.ok ? `提交完成:${result.id}` : '提交失败'
}
function handleCancel() {
status.value = '已取消'
}
</script>
<template>
<ActionPanel @submit="handleSubmit" @cancel="handleCancel" />
<p>{{ status }}</p>
</template>预期结果
初始显示:未操作
点击“提交”:提交完成:101
点击“取消”:已取消读取方法:父组件只处理事件载荷,不直接调用子组件内部函数;同一事件传出的多个参数会按顺序进入监听函数,但实际项目更推荐传一个结构清晰的对象。
高频用法
无参数事件写成 close: [],单参数事件写成 change: [value: string],多个参数可写成命名元组。表单提交、选择变化、删除确认等一次性通知适合自定义事件;需要双向绑定时优先使用 v-model,其底层约定是属性和 update:属性名 事件。
事件名在脚本中可使用 camelCase,父组件模板监听时推荐 kebab-case,例如子组件触发 emit('itemSelected', item),父组件写 @item-selected="handleItem"。载荷应保持精简稳定,避免把整个组件实例、DOM 节点或可变大对象传给父组件。
运行时校验
泛型写法提供编译期类型检查,但不会表达复杂业务校验。需要开发期运行时检查时,可改用对象式 defineEmits({ submit: (payload) => boolean });校验函数返回 false 时会产生警告。对象式声明与泛型声明不能同时用于同一次 defineEmits(),且运行时警告不能替代提交前的业务校验。
风险与边界
组件事件不会像 DOM 事件那样向祖先冒泡,只能由直接父组件监听。祖孙组件通信需要逐层转发,或改用 provide/inject、Pinia 等状态方案。若声明名为 click 的组件事件,父组件的 @click 将监听组件主动触发的事件,不应再假设它自动对应根元素的原生点击。
defineEmits() 必须位于 <script setup> 顶层,不能在函数、循环或条件分支中创建。事件触发前先固定载荷结构;若字段有时存在、有时缺失,父组件容易出现分支遗漏,安全替代方案是使用带可选字段的明确类型或拆分为不同事件。
排障清单
- 父组件没有收到事件:确认监听的是直接子组件,事件名拼写一致,并且点击路径确实执行了
emit()。 - TypeScript 报参数错误:核对命名元组中的参数顺序、数量和类型。
- 模板监听无响应:检查 camelCase 与 kebab-case 的对应关系,避免大小写混用。
- 事件被触发两次:检查是否同时在模板
$emit和脚本处理函数中重复触发。 - 深层组件无法监听:不要等待事件冒泡,改为逐层转发或使用共享状态。
兼容性
示例中的命名元组 defineEmits<{ event: [arg: Type] }>() 语法适用于 Vue 3.3 及以上。Vue 3.2 可改用调用签名形式 (e: 'submit', result: SubmitResult): void。Vue 3.4 及以上实现组件双向绑定时,通常优先使用 defineModel()。
为自定义组件实现单个或多个双向绑定字段。
实现组件 v-model
用于让父组件通过 v-model 读写自定义组件中的表单值。Vue 3 默认把无参数的 v-model 映射为 modelValue 属性和 update:modelValue 事件;多个字段则使用 v-model:字段名。Vue 3.4 及以上优先使用 defineModel(),代码更短且类型更集中。
基本语法
单字段绑定使用 defineModel<T>() 返回一个可读写 ref;具名绑定把字段名作为第一个参数。父组件修改绑定值会同步到子组件,子组件给模型赋值时会触发对应的 update:* 事件。
<!-- src/components/UserEditor.vue -->
<script setup lang="ts">
const name = defineModel<string>({ required: true })
const email = defineModel<string>("email", { required: true })
</script>
<template>
<label>
姓名
<input v-model.trim="name" />
</label>
<label>
邮箱
<input v-model.trim="email" type="email" />
</label>
</template><!-- src/App.vue -->
<script setup lang="ts">
import { ref } from "vue"
import UserEditor from "./components/UserEditor.vue"
const name = ref("Alice")
const email = ref("alice@example.com")
</script>
<template>
<UserEditor v-model="name" v-model:email="email" />
<p>姓名:{{ name }}</p>
<p>邮箱:{{ email }}</p>
</template>启动现有 Vue 3 + Vite 项目:
npm run dev预期结果:
页面初始显示:
姓名:Alice
邮箱:alice@example.com
在两个输入框中编辑后,下面的姓名和邮箱立即同步更新。读取方法:无参数绑定对应 modelValue,v-model:email 对应 email;子组件对 name.value 或 email.value 的写入会分别通知父组件。
高频用法
- 单字段表单控件:使用无参数
v-model,适合输入框、开关、分页器当前页等单一状态。 - 多字段组件:使用
v-model:email、v-model:visible等具名模型,避免把互不相关的值塞进一个对象。 - 输入归一化:父组件可直接使用
.trim、.number等原生修饰符;自定义修饰符可通过defineModel()返回的 modifiers 和set转换器处理。 - 只读展示不需要
v-model;只传prop,避免制造不存在的双向编辑语义。
风险与边界
子组件为模型设置 default,而父组件绑定值仍为 undefined 时,双方初始值可能不同步。触发条件是父组件未初始化、子组件却使用默认值;后果是页面显示有值但父状态仍为空。安全做法是把模型声明为 required,或在父组件先初始化 ref。
绑定对象时直接修改深层属性不会产生一次清晰的模型替换事件,可能让审计、校验或浅层监听遗漏变化。需要可追踪更新时,创建新对象后整体赋值,或把关键字段拆成多个具名模型。
排障清单
- 父值不更新:检查事件名是否严格为
update:modelValue或update:字段名,大小写和字段名必须一致。 - 子组件收到
undefined:确认父组件的ref已初始化,并检查是否把v-model:email错写成无参数绑定。 - TypeScript 报模型类型不匹配:让父组件
ref类型与defineModel<T>()保持一致,不要依赖隐式字符串与数字转换。 - 输入更新但校验未触发:确认校验监听的是绑定值本身,而不是只监听未被替换的对象引用。
兼容性
defineModel() 从 Vue 3.4 起可用。Vue 3.3 及更早版本使用 defineProps 与 defineEmits 手动实现:
<script setup lang="ts">
const props = defineProps<{ modelValue: string }>()
const emit = defineEmits<{ "update:modelValue": [value: string] }>()
</script>
<template>
<input
:value="props.modelValue"
@input="emit('update:modelValue', ($event.target as HTMLInputElement).value)"
/>
</template>生效结果与无参数 v-model 相同:输入变化后,父组件绑定值收到新的字符串。
使用默认、具名和作用域插槽定制子组件内部内容。
使用组件插槽
插槽用于让父组件把内容放进子组件预留的位置,同时保留子组件的布局和数据控制。默认插槽承载主体内容,具名插槽区分标题、操作区等位置,作用域插槽把子组件数据显式提供给父组件模板。
基本语法
子组件使用 <slot> 声明出口;name 指定具名插槽,标签内部内容是未传入插槽时的后备内容。父组件使用 <template #名称> 填充具名插槽,#default 可显式接收默认插槽的作用域数据。
主示例
下面的卡片同时提供默认、具名和作用域插槽。user 由子组件通过插槽属性传给父组件,父组件决定如何渲染标题、正文和按钮。
<!-- src/components/UserCard.vue -->
<script setup lang="ts">
type User = {
id: number
name: string
role: string
}
defineProps<{ user: User }>()
</script>
<template>
<article class="user-card">
<header>
<slot name="title" :user="user">
<h2>用户信息</h2>
</slot>
</header>
<section>
<slot :user="user">
<p>{{ user.name }} / {{ user.role }}</p>
</slot>
</section>
<footer>
<slot name="actions" :user="user" />
</footer>
</article>
</template><!-- src/App.vue -->
<script setup lang="ts">
import UserCard from "./components/UserCard.vue"
const user = { id: 1, name: "Alice", role: "管理员" }
function viewUser(id: number) {
console.log(`view:${id}`)
}
</script>
<template>
<UserCard :user="user">
<template #title="{ user }">
<h2>{{ user.name }}</h2>
</template>
<template #default="{ user }">
<p>角色:{{ user.role }}</p>
</template>
<template #actions="{ user }">
<button type="button" @click="viewUser(user.id)">查看</button>
</template>
</UserCard>
</template>启动现有 Vue 3 + Vite 项目:
npm run dev预期结果:
页面显示:
Alice
角色:管理员
[查看]
点击“查看”后,浏览器控制台输出:
view:1读取方法:#title 对应 name="title",#actions 对应 name="actions";没有名称的 <slot> 是默认插槽。{ user } 是对插槽属性的解构,不是父组件原有变量。
高频用法
- 默认插槽:适合弹窗正文、卡片主体、布局容器中的主要内容。
- 具名插槽:适合
header、footer、actions等固定区域,名称应表达区域职责而不是视觉位置。 - 作用域插槽:适合表格单元格、列表项或下拉选项,由子组件提供当前行数据,父组件决定展示方式。
- 后备内容:在
<slot>内放置默认文本或结构,让父组件不传内容时组件仍可用。
风险与边界
插槽内容在父组件作用域中编译,不能直接访问子组件内部变量。触发条件是父模板引用了子组件未通过插槽属性暴露的状态;后果是变量未定义或渲染为空。安全做法是使用 :user="user" 等插槽属性显式传递。
不要通过作用域插槽直接修改子组件对象。深层修改可能绕过组件事件约定,导致状态来源不清或响应链难以排查。需要触发操作时,子组件应发出事件,或通过插槽属性传入语义明确的回调函数。
排障清单
- 插槽没有显示:确认父组件使用的名称与子组件
slot name完全一致;未命名内容只会进入默认插槽。 - 作用域变量为
undefined:检查子组件是否传了同名插槽属性,并确认父组件解构名称没有拼写错误。 - 后备内容未出现:只有父组件完全未提供该插槽时才显示;传入空模板也会视为已提供。
v-slot编译报错:把#name写在组件标签或直接子级<template>上,不要放到普通 HTML 元素上。- 列表插槽更新异常:确保列表项
key稳定唯一,不要使用会随排序变化的数组下标。
使用动态组件在多个组件类型之间切换渲染。
切换动态组件
当同一块区域需要在标签页、编辑器或不同视图间切换时,使用 <component :is="..."> 绑定当前组件。传入已导入的组件对象最稳妥;默认切走会卸载实例,需要保留表单或滚动状态时再配合 <KeepAlive>。
基本语法
:is 可以接收组件对象、已注册的组件名字符串,也可以接收原生标签名。业务项目通常维护“业务键到组件对象”的映射,避免直接拼接字符串导致组件未注册或名称写错。
<script setup lang="ts">
import { defineComponent, h, ref } from 'vue'
const OverviewPanel = defineComponent({
name: 'OverviewPanel',
setup() {
const count = ref(0)
return () =>
h('section', [
h('p', `概览计数:${count.value}`),
h('button', { onClick: () => count.value++ }, '增加')
])
}
})
const SettingsPanel = defineComponent({
name: 'SettingsPanel',
setup: () => () => h('p', '设置面板')
})
const panels = {
overview: OverviewPanel,
settings: SettingsPanel
} as const
const current = ref<keyof typeof panels>('overview')
</script>
<template>
<nav>
<button @click="current = 'overview'">概览</button>
<button @click="current = 'settings'">设置</button>
</nav>
<!-- 最多缓存两个实例,避免低频视图无限占用内存 -->
<KeepAlive :max="2">
<component :is="panels[current]" />
</KeepAlive>
</template>预期结果
初始显示:概览计数:0
点击“增加”后:概览计数:1
切到“设置”再切回“概览”:仍显示概览计数:1读取方法:组件由 current 决定;切换按钮只修改业务键。因为动态组件被 <KeepAlive> 包裹,离开的实例进入停用状态而不是立即销毁,所以计数能够保留。
高频用法
不需要保留状态时直接使用 <component :is="panels[current]" />,让切走的组件卸载并释放副作用。需要缓存部分组件时使用 include 或 exclude,匹配依据是组件的 name;需要限制缓存数量时设置 max。
同一组件类型用于不同记录时,可绑定 :key="recordId" 区分实例。键变化会创建新实例并重置局部状态,适合“切换记录必须重新初始化”的场景;不要把频繁变化的随机值作为键,否则会造成反复卸载和重建。
风险与边界
启用 <KeepAlive> 后,组件的定时器、订阅或监听器可能在停用期间继续工作,造成重复请求或后台消耗。应在 onDeactivated() 中暂停,在 onActivated() 中恢复;若无需保留状态,安全替代方案是移除缓存。
缓存大量重型组件会增加内存占用。触发条件是动态视图种类持续增长且没有 max、include 限制;可能后果是页面长时间运行后变慢。优先只缓存高频、恢复成本高的组件,并设置合理上限。
排障清单
出现“Failed to resolve component”时,检查 :is 是否传入了未注册的字符串;优先改为导入后的组件对象。切换后状态意外丢失时,确认 <KeepAlive> 是否直接包裹动态组件,以及 :key 是否被无意改变。include 不生效时,核对组件 name 与匹配值是否一致。
延迟加载低频组件并配置加载、错误和超时状态。
异步加载组件
低频弹窗、复杂报表或管理页面不必进入首屏包,可用 defineAsyncComponent() 包装动态 import(),仅在组件首次渲染时请求对应代码块。生产环境应同时配置加载提示、错误组件和超时,避免慢网或资源发布异常时出现空白区域。
基本语法与配置
loader 必须返回 Promise,Vite 或 webpack 会把动态导入识别为拆包点。delay 控制加载提示延迟出现,减少快速加载时的闪烁;timeout 超过后进入错误状态;onError 可按错误类型和尝试次数决定重试或终止。
| 配置 | 作用 | 常用取值 |
|---|---|---|
loader |
加载目标组件 | () => import('./Panel.vue') |
loadingComponent |
等待期间显示 | 轻量文本或骨架屏 |
errorComponent |
加载失败或超时显示 | 含重试入口的错误提示 |
delay |
延迟显示加载态 | 100~300 毫秒 |
timeout |
最长等待时间 | 按资源大小和网络环境设定 |
onError |
自定义重试策略 | 仅重试临时网络错误 |
主示例
将以下文件放入 Vite 创建的 Vue 3 项目。按钮未点击时不会请求报表组件;点击后才触发独立代码块加载。src/App.vue
<script setup lang="ts">
import { defineAsyncComponent, defineComponent, h, ref } from 'vue'
const showReport = ref(false)
const LoadingPanel = defineComponent({
name: 'LoadingPanel',
setup: () => () => h('p', '报表加载中…')
})
const ErrorPanel = defineComponent({
name: 'ErrorPanel',
setup: () => () => h('p', '报表加载失败,请刷新后重试。')
})
const AsyncReport = defineAsyncComponent({
loader: () => import('./components/ReportPanel.vue'),
loadingComponent: LoadingPanel,
errorComponent: ErrorPanel,
delay: 150,
timeout: 10_000,
onError(error, retry, fail, attempts) {
// 只对常见的临时网络或代码块加载错误进行有限重试
const transient = /fetch|network|loading chunk|dynamically imported module/i.test(
error.message
)
if (transient && attempts <= 3) {
retry()
} else {
fail()
}
}
})
</script>
<template>
<button :disabled="showReport" @click="showReport = true">
加载报表
</button>
<AsyncReport v-if="showReport" />
</template>src/components/ReportPanel.vue
<template>
<section>
<h2>月度报表</h2>
<p>报表组件已按需加载。</p>
</section>
</template>预期结果
初始:只显示“加载报表”按钮,报表代码块尚未请求。
点击后:网络耗时超过 150 ms 时先显示“报表加载中…”。
成功:显示“月度报表”和“报表组件已按需加载。”。
失败或超过 10 s:显示“报表加载失败,请刷新后重试。”。实际代码块文件名和加载耗时由构建结果、浏览器缓存及网络决定,可在浏览器开发者工具的 Network 面板中确认目标 chunk 是否在点击后才请求。
风险与边界
异步加载减少首屏代码,但首次打开低频功能会增加一次网络等待。对用户进入后立即必用的核心组件做异步化,可能导致关键内容延迟;安全替代方案是同步导入,或在空闲时预加载对应模块。
timeout 只负责让组件进入错误状态,不能替代请求取消、版本回滚或 CDN 容灾。发布后若旧页面仍引用已删除的 chunk,用户可能看到加载失败;应保留一段时间的旧静态资源、使用稳定缓存策略,并提供刷新提示。
不要对所有失败无限 retry()。资源 404、语法错误或版本不匹配不会因重试恢复,反而会制造请求风暴。本例仅对常见临时网络错误最多重试三次,其余立即 fail()。
排障清单
组件始终不加载时,确认模板条件确实变为真,并检查动态导入路径的大小写。开发环境正常、生产环境失败时,重点检查静态资源基础路径、CDN 缓存和部署时是否删除旧 chunk。加载态不出现通常是资源在 delay 前完成,可临时把 delay 设为 0 验证。
Vue Router 的路由懒加载应直接在路由配置中使用 component: () => import('./Page.vue'),不要额外包一层 defineAsyncComponent();普通页面内部的低频子组件再使用本条目方案。
使用 provide 和 inject 在祖先与深层后代之间共享依赖。
跨层传递依赖
当配置、服务实例或响应式状态需要从祖先组件传到深层后代时,使用 provide 和 inject,可避免中间组件逐层声明并转发 props。它适合组件树内的依赖共享,不替代跨页面全局状态管理。
基本语法
祖先组件调用 provide(key, value),任意后代调用 inject(key, defaultValue)。为避免字符串键冲突,项目代码优先使用共享的 Symbol;需要让后代响应更新时,提供 ref、reactive 或 computed,不要只提供普通值的快照。
高频用法
下面示例由三个文件组成,可直接放入 Vue 3 + Vite 项目。祖先提供主题和修改函数,深层后代直接读取并更新。
// src/theme.ts
import type { InjectionKey, Ref } from "vue"
export interface ThemeContext {
theme: Ref<"light" | "dark">
toggle: () => void
}
export const themeKey: InjectionKey<ThemeContext> = Symbol("theme")<!-- src/App.vue -->
<script setup lang="ts">
import { provide, ref } from "vue"
import DeepChild from "./components/DeepChild.vue"
import { themeKey } from "./theme"
const theme = ref<"light" | "dark">("light")
provide(themeKey, {
theme,
toggle: () => {
theme.value = theme.value === "light" ? "dark" : "light"
}
})
</script>
<template>
<main>
<p>祖先主题:{{ theme }}</p>
<DeepChild />
</main>
</template><!-- src/components/DeepChild.vue -->
<script setup lang="ts">
import { inject } from "vue"
import { themeKey } from "../theme"
const themeContext = inject(themeKey)
if (!themeContext) {
throw new Error("ThemeContext 未提供")
}
</script>
<template>
<section>
<p>后代主题:{{ themeContext.theme.value }}</p>
<button @click="themeContext.toggle">切换主题</button>
</section>
</template>预期结果:页面初始显示 light;点击按钮后,祖先和后代文本同时变为 dark。
祖先主题:light
后代主题:light
点击“切换主题”后:
祖先主题:dark
后代主题:dark读取时注意:模板会自动解包顶层 ref,但这里的 ref 位于注入对象内部,因此模板中需要写 themeContext.theme.value。
风险与边界
当依赖来自可复用组件库时,字符串键可能与业务代码冲突,后果是注入到错误值;安全替代方案是导出唯一的 InjectionKey。后代直接修改祖先提供的响应式对象会让写入来源难以追踪,建议同时提供明确的修改函数,并在祖先集中更新。
inject 找不到提供者时会返回 undefined。关键依赖应立即抛出可读错误;可选依赖则传入默认值,例如 inject(key, fallback)。默认值是工厂函数时,第三个参数应传 true,避免把函数本身当作结果。
排障清单
- 注入值为
undefined:确认调用者确实位于提供者的后代树中,并检查 key 是否来自同一个模块实例。 - 值更新但视图不刷新:确认提供的是
ref、reactive或computed,而不是provide(key, state.value)这类普通值快照。 - TypeScript 推断为可空:使用运行时守卫,不要仅用非空断言掩盖缺失提供者。
- SSR 中出现请求间数据串用:在组件
setup或每次应用创建流程中提供状态,不要把可变单例放在模块顶层共享。
兼容性
provide、inject 和 InjectionKey 适用于 Vue 3 Composition API;Options API 也可使用 provide 与 inject 选项,但同一项目建议统一风格,减少响应式和类型推断差异。
使用 v-model 处理输入框、复选框、单选框和下拉选择。
绑定表单数据
使用 v-model 将表单控件的当前值与组件状态双向同步。文本框通常绑定字符串,单个复选框绑定布尔值,同名多选复选框绑定数组,单选框和下拉框绑定选中项。
基本语法
v-model 会根据控件类型自动选择属性与事件:文本输入使用 value 和 input,复选框、单选框使用 checked 和 change,下拉框使用 value 和 change。表单状态应先在脚本中初始化,模板里的 value、checked 或 selected 不能替代它。
常用修饰符包括:
.trim:写回状态前去除首尾空白。.number:尽量把输入转换为数字;输入为空时仍可能得到空字符串。.lazy:从每次输入改为在change事件后同步。
高频用法
下面的单文件组件覆盖输入框、单个复选框、复选框数组、单选框和下拉选择,可直接替换 Vite 项目的 src/App.vue。
<script setup lang="ts">
import { computed, ref } from "vue"
const name = ref("")
const age = ref<number | "">("")
const agreed = ref(false)
const skills = ref<string[]>([])
const contact = ref("email")
const city = ref("shanghai")
const snapshot = computed(() =>
JSON.stringify(
{
name: name.value,
age: age.value,
agreed: agreed.value,
skills: skills.value,
contact: contact.value,
city: city.value
},
null,
2
)
)
</script>
<template>
<form @submit.prevent>
<label>
姓名
<input v-model.trim="name" type="text" />
</label>
<label>
年龄
<input v-model.number="age" type="number" min="0" />
</label>
<label>
<input v-model="agreed" type="checkbox" />
同意条款
</label>
<fieldset>
<legend>技能</legend>
<label><input v-model="skills" type="checkbox" value="vue" />Vue</label>
<label><input v-model="skills" type="checkbox" value="ts" />TypeScript</label>
</fieldset>
<fieldset>
<legend>联系方式</legend>
<label><input v-model="contact" type="radio" value="email" />邮箱</label>
<label><input v-model="contact" type="radio" value="phone" />电话</label>
</fieldset>
<label>
城市
<select v-model="city">
<option value="shanghai">上海</option>
<option value="beijing">北京</option>
</select>
</label>
<pre>{{ snapshot }}</pre>
</form>
</template>预期结果:输入姓名 Alice、年龄 20,勾选条款与两项技能,选择电话和北京后,页面中的 <pre> 显示:
{
"name": "Alice",
"age": 20,
"agreed": true,
"skills": [
"vue",
"ts"
],
"contact": "phone",
"city": "beijing"
}读取时注意:单个复选框返回布尔值;多个复选框绑定同一数组时,勾选项的 value 会加入数组;单选框与下拉框返回被选项的 value。
风险与边界
当 .number 遇到空输入或无法转换的内容时,结果不一定始终是数字;若后续用于计算或接口校验,必须在提交时再次检查类型和范围。安全做法是允许状态类型包含空字符串,并在提交阶段显式转换和验证。
动态渲染 <select> 选项时,当前状态若不匹配任何 option,界面可能显示未选择。应给状态设置有效初值,或提供值为空的占位选项。不要同时手写 :value 与 v-model 去控制同一输入框,否则会形成两个数据源。
排障清单
- 输入后状态不变:检查是否把
v-model绑定到只读computed,或绑定表达式是否不可赋值。 - 复选框数组没有加入预期值:确认每个复选框都有明确且唯一的
value。 - 单选框无法互斥:确认它们绑定同一个状态变量;使用
v-model时通常不必额外写相同的name。 - 下拉框初始为空:确认状态初值与某个
option value的类型和值完全一致。 - 组件封装后
v-model失效:Vue 3.4+ 可使用defineModel();较早版本需实现modelValueprop 和update:modelValue事件。
兼容性
原生表单控件的 v-model 适用于 Vue 3。defineModel() 从 Vue 3.4 起提供;使用更早版本时,保持 modelValue 与 update:modelValue 的组件协议即可。
将可复用的响应式状态和业务逻辑提取为 Composable。
封装组合式函数
当多个组件需要复用同一组响应式状态、计算逻辑或副作用管理时,将它们提取为以 use 开头的 Composable。它应返回组件真正需要的状态和操作,不负责渲染界面;需要同时复用结构与样式时,优先封装组件。
基本写法
Composable 是在 setup() 或 <script setup> 中调用的普通函数。响应式变量通常在函数内部创建,并以“普通对象包含多个 ref”的形式返回,这样调用方解构后仍能保持响应性。
以下示例封装窗口尺寸监听。浏览器事件只在组件挂载后注册,并在卸载时清理,因此不会在组件反复进入、离开时累积监听器。
src/composables/useWindowSize.ts:
import { onMounted, onUnmounted, readonly, ref } from 'vue'
export function useWindowSize() {
const width = ref(0)
const height = ref(0)
const updateSize = () => {
width.value = window.innerWidth
height.value = window.innerHeight
}
onMounted(() => {
updateSize()
window.addEventListener('resize', updateSize)
})
onUnmounted(() => {
window.removeEventListener('resize', updateSize)
})
// 对外只读,避免组件绕过 Composable 修改内部状态
return {
width: readonly(width),
height: readonly(height)
}
}src/App.vue:
<script setup lang="ts">
import { useWindowSize } from './composables/useWindowSize'
const { width, height } = useWindowSize()
</script>
<template>
<main>
<h1>窗口尺寸</h1>
<p>{{ width }} × {{ height }}</p>
</main>
</template>运行开发服务器:
npm run dev预期输出:
VITE v<VERSION> ready in <TIME> ms
➜ Local: http://localhost:<PORT>/打开页面后可见:
窗口尺寸
<WIDTH> × <HEIGHT><PORT>、<WIDTH> 和 <HEIGHT> 取决于本机环境。模板会自动解包 ref;在 TypeScript 逻辑中读取原始 ref 时使用 width.value。
高频用法
- 复用请求状态:返回
data、loading、error和execute,并由调用方决定何时请求。 - 复用浏览器副作用:统一注册事件、定时器或观察器,并在
onUnmounted中释放。 - 复用表单业务规则:把校验状态和提交动作放入 Composable,输入通过参数传入,避免直接依赖具体组件。
- 共享状态需要谨慎:状态写在函数内部时,每次调用相互隔离;写在模块顶层时会成为单例。
风险与边界
生命周期钩子应在组件的同步初始化阶段注册。若在普通异步回调中首次调用 Composable,可能失去当前组件上下文,导致钩子不生效;安全做法是在 <script setup> 顶层同步调用,再把异步工作放进返回的方法或钩子内部。
副作用没有清理会造成重复请求、重复事件响应或内存增长。凡是调用 addEventListener、setInterval、watch 或第三方订阅 API,都应保存对应清理方式,并在组件卸载或新任务开始前执行。
服务端渲染环境没有 window、document。浏览器 API 必须放在 onMounted 内,或先判断运行环境;模块顶层共享可变状态还可能在不同请求之间串数据,SSR 项目应改为按请求创建状态。
排障清单
- 页面不更新:确认返回的是 ref,且没有把
reactive()对象直接解构为普通值。 - 监听触发多次:确认组件是否重复挂载,并检查卸载时是否使用同一个回调引用清理。
- 控制台出现
window is not defined:检查浏览器 API 是否在模块加载阶段执行。 - 注入参数变化但结果不变:传入 ref 或 getter,并在 Composable 内通过
watch、watchEffect或计算属性消费它。
使用 app.use 安装路由、状态库或自定义 Vue 插件。
注册应用插件
在应用启动阶段安装路由、状态库或跨组件服务时使用 app.use()。插件必须在 app.mount() 前注册,使根组件及其后代在初始化时就能访问插件提供的组件、指令、注入值或全局能力。
基本语法
插件可以是带 install(app, options) 方法的对象,也可以直接是安装函数。第二个及后续参数会原样传给插件,用于设置前缀、环境开关或服务实例。以下为片段示例,依赖项目中已创建的路由模块并已安装 Pinia。
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import { createPinia } from 'pinia'
const app = createApp(App)
app.use(router)
app.use(createPinia())
app.mount('#app')验证方法是启动项目后确认路由可跳转、Store 可在组件中正常读取。
自定义插件示例
以下示例通过插件向整棵组件树提供日志服务,避免把方法挂到 globalProperties 后产生名称冲突和额外类型声明。src/plugins/logger.ts:
import type { App, InjectionKey } from 'vue'
export interface Logger {
info(message: string): void
}
export interface LoggerOptions {
prefix?: string
}
export const loggerKey: InjectionKey<Logger> = Symbol('logger')
export const loggerPlugin = {
install(app: App, options: LoggerOptions = {}) {
const prefix = options.prefix ?? 'app'
const logger: Logger = {
info(message) {
console.log(`[${prefix}] ${message}`)
}
}
// 后代组件通过同一个 InjectionKey 获取服务
app.provide(loggerKey, logger)
}
}src/main.ts:
import { createApp } from 'vue'
import App from './App.vue'
import { loggerPlugin } from './plugins/logger'
createApp(App)
.use(loggerPlugin, { prefix: 'admin' })
.mount('#app')src/App.vue:
<script setup lang="ts">
import { inject } from 'vue'
import { loggerKey } from './plugins/logger'
const logger = inject(loggerKey)
if (!logger) {
throw new Error('loggerPlugin 未安装')
}
function handleSave() {
logger.info('保存完成')
}
</script>
<template>
<button type="button" @click="handleSave">保存</button>
</template>运行开发服务器并点击“保存”:
npm run dev预期输出:
VITE v<VERSION> ready in <TIME> ms
➜ Local: http://localhost:<PORT>/浏览器控制台随后输出:
[admin] 保存完成<VERSION>、<TIME> 和 <PORT> 会随本机环境变化。若页面能显示按钮且点击后出现日志,说明插件安装和注入链路已生效。
常用注册方式
- 路由:
app.use(router),应在挂载前完成,以便组件首次渲染即可访问路由实例。 - 状态库:先创建实例,再执行
app.use(pinia);不要把createPinia函数本身传入。 - UI 组件库:按库文档传入插件对象及主题、语言等选项,避免同时全量注册和手工重复注册组件。
- 自定义服务:优先用
app.provide()暴露有明确类型的服务,组件通过inject()或二次封装的useXxx()获取。
风险与边界
传错对象时通常会出现“插件必须是函数或包含 install 方法”的警告,后续组件也可能因注入为空而失败。安全做法是确认传给 app.use() 的是已创建的插件实例,例如 router、pinia,而不是工厂函数或配置对象。
插件在 install() 中修改全局属性、注册全局组件或启动订阅,会影响整个应用。名称冲突可能覆盖已有能力,长期订阅还可能无法随单个组件卸载;应使用唯一命名、限制全局注册范围,并把可释放的副作用交给具体 Composable 或组件管理。
测试中单独挂载组件时,应用入口的插件不会自动执行。若组件依赖插件,应在测试挂载配置的 global.plugins 中安装同一插件,或显式提供对应注入值。
排障清单
inject()返回undefined:检查插件是否在mount()前安装,以及提供和注入是否使用同一个InjectionKey。- 路由或 Store 未初始化:确认传入的是实例,并检查导入路径是否指向同一个模块。
- 插件选项未生效:核对
app.use(plugin, options)与install(app, options)的参数位置。 - 组件测试通过、真实应用失败,或反之:对比生产入口和测试环境安装的插件及选项是否一致。
兼容性
以上写法适用于 Vue 3 的应用实例。Vue 2 使用全局 Vue.use(),插件入口和类型声明方式不同,不能直接照搬。第三方插件还应确认其主版本明确支持 Vue 3。
在组合式函数或组件中发送异步请求并更新响应式数据。
发送接口请求
在 Vue 3 组件中使用原生 fetch() 获取数据时,至少要处理加载状态、HTTP 非成功响应、异常和组件卸载。下面的写法会在组件挂载后请求单条待办数据,成功后更新响应式对象,并在重复请求或卸载时取消旧请求。
基本写法
请求结果使用 ref() 保存,模板会自动读取其 .value。fetch() 只有在网络失败或请求被取消时才会抛出异常,服务端返回 404、500 时仍会正常解析响应,因此必须先检查 response.ok。
主示例
<script setup lang='ts'>
import { onBeforeUnmount, onMounted, ref } from 'vue'
interface Todo {
id: number
title: string
completed: boolean
}
const todo = ref<Todo | null>(null)
const loading = ref(false)
const error = ref('')
let activeController: AbortController | null = null
async function loadTodo() {
activeController?.abort()
const current = new AbortController()
activeController = current
loading.value = true
error.value = ''
try {
const response = await fetch(
'https://jsonplaceholder.typicode.com/todos/1',
{ signal: current.signal }
)
if (!response.ok) {
throw new Error(`HTTP ${response.status}`)
}
todo.value = (await response.json()) as Todo
} catch (cause) {
if (cause instanceof DOMException && cause.name === 'AbortError') return
error.value = cause instanceof Error ? cause.message : '未知请求错误'
} finally {
// 旧请求结束时不能覆盖新请求的加载状态
if (activeController === current) loading.value = false
}
}
onMounted(loadTodo)
onBeforeUnmount(() => activeController?.abort())
</script>
<template>
<button :disabled='loading' @click='loadTodo'>重新请求</button>
<p v-if='loading'>加载中...</p>
<p v-else-if='error'>请求失败:{{ error }}</p>
<section v-else-if='todo'>
<p>{{ todo.title }}</p>
<p>状态:{{ todo.completed ? '已完成' : '未完成' }}</p>
</section>
</template>预期结果
delectus aut autem
状态:未完成页面先短暂显示“加载中...”,随后显示标题和完成状态。浏览器开发者工具的 Network 面板中应看到 GET /todos/1 返回 200;实际耗时和响应头可能不同。
风险与边界
- 未检查
response.ok时,404或500会被误当作成功结果,后续读取字段可能报错。安全做法是先校验状态码,再解析响应体。 - 用户快速重复点击时,较早请求可能晚于新请求返回并覆盖新数据。示例会取消旧请求,并用控制器身份判断只允许当前请求结束加载状态。
- 浏览器跨域策略可能阻止请求;出现 CORS 错误时不能在前端绕过,应由服务端配置允许来源,或通过同源后端代理转发。密钥和长期令牌不得写入前端代码。
排障清单
先看 Network 面板确认请求是否发出、状态码和响应体是否符合预期。若控制台显示 Failed to fetch,重点检查网络、HTTPS 混用、CORS 和代理配置;若出现 JSON 解析异常,确认接口没有返回 HTML 错误页或空响应。
兼容性
fetch 与 AbortController 可用于主流现代浏览器。服务端渲染场景应在 onMounted()、路由数据加载器或服务端专用请求层中发起请求,避免在模块顶层直接访问仅浏览器可用的对象。
统一处理请求中的加载、成功、失败、重试和取消状态。
管理请求状态
把异步请求统一建模为 idle、loading、success、error 和 canceled,可以让按钮禁用、错误提示、重试和取消行为保持一致。下面的组合式函数只保留最新请求,失败或取消后可重试同一任务。
状态模型
execute() 从空闲、失败或已取消状态进入加载;请求完成后进入成功或失败;调用 cancel() 会触发 AbortController 并进入已取消。再次执行请求时会先取消旧请求,避免旧响应覆盖新结果。

主示例
<script setup lang='ts'>
import { onBeforeUnmount, ref } from 'vue'
type RequestStatus = 'idle' | 'loading' | 'success' | 'error' | 'canceled'
type RequestTask<T> = (signal: AbortSignal) => Promise<T>
interface Todo {
id: number
title: string
completed: boolean
}
function useRequest<T>() {
const status = ref<RequestStatus>('idle')
const data = ref<T | null>(null)
const error = ref<string | null>(null)
let controller: AbortController | null = null
let lastTask: RequestTask<T> | null = null
async function execute(task: RequestTask<T>) {
controller?.abort()
const current = new AbortController()
controller = current
lastTask = task
status.value = 'loading'
data.value = null
error.value = null
try {
const result = await task(current.signal)
if (controller !== current) return
data.value = result
status.value = 'success'
} catch (cause) {
if (controller !== current) return
if (cause instanceof DOMException && cause.name === 'AbortError') {
status.value = 'canceled'
return
}
error.value = cause instanceof Error ? cause.message : '未知请求错误'
status.value = 'error'
}
}
function retry() {
if (lastTask) void execute(lastTask)
}
function cancel() {
controller?.abort()
}
return { status, data, error, execute, retry, cancel }
}
function abortableDelay(ms: number, signal: AbortSignal) {
return new Promise<void>((resolve, reject) => {
const onAbort = () => {
window.clearTimeout(timer)
reject(new DOMException('请求已取消', 'AbortError'))
}
const timer = window.setTimeout(() => {
signal.removeEventListener('abort', onAbort)
resolve()
}, ms)
if (signal.aborted) return onAbort()
signal.addEventListener('abort', onAbort, { once: true })
})
}
const url = ref('https://jsonplaceholder.typicode.com/todos/1')
const { status, data, error, execute, retry, cancel } = useRequest<Todo>()
function load() {
const currentUrl = url.value
void execute(async (signal) => {
// 固定延迟便于手动验证取消按钮,生产代码可删除
await abortableDelay(1000, signal)
const response = await fetch(currentUrl, { signal })
if (!response.ok) throw new Error(`HTTP ${response.status}`)
return (await response.json()) as Todo
})
}
onBeforeUnmount(cancel)
</script>
<template>
<input v-model='url' aria-label='请求地址'>
<button :disabled="status === 'loading'" @click='load'>发送请求</button>
<button :disabled="status !== 'loading'" @click='cancel'>取消</button>
<button
:disabled="status !== 'error' && status !== 'canceled'"
@click='retry'
>
重试
</button>
<p>状态:{{ status }}</p>
<p v-if='data'>结果:{{ data.title }}</p>
<p v-if='error'>错误:{{ error }}</p>
</template>预期结果
初始:状态:idle
正常请求:状态:loading → success
成功结果:delectus aut autem
取消请求:状态:loading → canceled
错误地址:状态:loading → error,错误:HTTP 404把地址改为 https://jsonplaceholder.typicode.com/not-found 可验证失败状态;请求后 1 秒内点击“取消”可验证取消状态。失败或取消后点击“重试”,会重新执行上一次捕获的请求任务。
风险与边界
- 重试没有上限时,持续故障会造成请求风暴和服务压力。安全做法是限制次数,并为自动重试增加指数退避和随机抖动;用户主动重试仍应禁用连点。
- 取消只表示客户端不再等待结果,不保证服务端事务已经停止。写操作应配合幂等键、服务端取消能力或提交后状态查询,不能把
AbortController当作业务回滚。 - 多个互不相关的并发请求若共用同一个实例,会互相取消。列表分页、并行卡片等场景应为每个请求键创建独立实例,或使用按键管理的请求缓存。
排障清单
状态长期停在 loading 时,检查任务是否存在永不结束的 Promise,以及所有异常路径是否进入 catch。重试参数不正确时,确认 lastTask 捕获的是本次请求的固定参数,而不是后续会变化的响应式值;组件卸载后仍有请求时,确认已调用 cancel()。
兼容性
示例依赖浏览器的 fetch、AbortController 和 DOMException。在 SSR 或 Node 运行时应使用对应环境提供的请求实现,并把 window.setTimeout 改为全局 setTimeout;状态机与重试控制逻辑可以保持不变。
集中配置接口地址、请求头、鉴权信息和错误转换逻辑。
封装 API 客户端
用于把接口地址、公共请求头、鉴权和错误格式集中到一个入口。组件只调用 api.get()、api.post() 等方法,不再重复拼接地址或判断状态码。
请求链路
请求先读取环境变量和令牌,再序列化请求体;响应按内容类型解析,非 2xx 状态统一转换为 ApiError,页面只处理业务提示。

主示例
片段示例:保存为 src/api/client.ts,用于 Vite + Vue 3。调用方可以传入 signal 取消请求;上传 FormData 时不会手动设置 Content-Type,由浏览器生成 boundary。
export class ApiError extends Error {
constructor(
public readonly status: number,
message: string,
public readonly details: unknown,
) {
super(message)
this.name = 'ApiError'
}
}
type JsonBody = Record<string, unknown> | unknown[]
type ApiRequestInit = Omit<RequestInit, 'body'> & {
body?: JsonBody | FormData | string | null
}
const baseUrl = (import.meta.env.VITE_API_BASE_URL ?? '/api').replace(/\/$/, '')
function buildBody(body: ApiRequestInit['body'], headers: Headers): BodyInit | null | undefined {
if (body === undefined || body === null || typeof body === 'string' || body instanceof FormData) {
return body
}
headers.set('Content-Type', 'application/json')
return JSON.stringify(body)
}
async function parseResponse(response: Response): Promise<unknown> {
if (response.status === 204) return undefined
const contentType = response.headers.get('content-type') ?? ''
return contentType.includes('application/json')
? response.json()
: response.text()
}
async function request<T>(path: string, init: ApiRequestInit = {}): Promise<T> {
const headers = new Headers(init.headers)
headers.set('Accept', 'application/json')
const token = sessionStorage.getItem('access_token')
if (token) headers.set('Authorization', `Bearer ${token}`)
const { body, ...requestInit } = init
const response = await fetch(`${baseUrl}/${path.replace(/^\//, '')}`, {
...requestInit,
headers,
body: buildBody(body, headers),
})
const payload = await parseResponse(response)
if (!response.ok) {
const serverMessage =
typeof payload === 'object' &&
payload !== null &&
'message' in payload &&
typeof payload.message === 'string'
? payload.message
: `HTTP ${response.status}`
throw new ApiError(response.status, serverMessage, payload)
}
return payload as T
}
export const api = {
get<T>(path: string, init: Omit<ApiRequestInit, 'method' | 'body'> = {}) {
return request<T>(path, { ...init, method: 'GET' })
},
post<T>(
path: string,
body: ApiRequestInit['body'],
init: Omit<ApiRequestInit, 'method' | 'body'> = {},
) {
return request<T>(path, { ...init, method: 'POST', body })
},
}在 .env.development 中配置开发接口地址,修改后需要重启 Vite 开发服务器。
VITE_API_BASE_URL=http://localhost:8080/api假设后端 GET /api/users 返回 [{"id":1,"name":"Ada"},{"id":2,"name":"Linus"}],组件可这样读取:
<script setup lang="ts">
import { onMounted, ref } from 'vue'
import { api, ApiError } from '@/api/client'
interface User {
id: number
name: string
}
const users = ref<User[]>([])
const errorMessage = ref('')
onMounted(async () => {
try {
users.value = await api.get<User[]>('/users')
} catch (error) {
errorMessage.value =
error instanceof ApiError ? `${error.status}: ${error.message}` : '请求失败'
}
})
</script>
<template>
<p v-if="errorMessage">{{ errorMessage }}</p>
<ul v-else>
<li v-for="user in users" :key="user.id">{{ user.name }}</li>
</ul>
</template>预期页面结果:
Ada
Linus读取方式:成功时直接使用泛型返回值;失败时通过 status 判断 401、403、404 或 5xx,通过 message 展示可读提示,details 仅用于日志或字段级错误。
风险与边界
VITE_ 环境变量会被打进前端产物,不能存放私钥、数据库密码或服务端令牌。令牌保存在 Web Storage 时会受 XSS 影响;高敏场景优先使用后端签发的 HttpOnly、Secure Cookie,并配套 CSRF 防护。
不要在响应错误处理里对每个 401 无限刷新令牌,否则并发请求可能形成刷新风暴或重试死循环。安全做法是只允许一次刷新、共享同一个刷新 Promise,刷新失败后清理会话并跳转登录页。
排障清单
- 请求地址错误:在 Network 中核对最终 URL,确认
VITE_API_BASE_URL已重启生效且没有重复/api。 - 浏览器报 CORS:这是服务端响应头或开发代理问题,不能靠前端关闭安全策略解决。
- 上传文件失败:确认传入的是
FormData,不要自行写multipart/form-data。 - 页面切换后仍回写旧数据:创建
AbortController,把signal传给api.get(),卸载时调用abort()。
速查:组件只处理业务状态;地址、鉴权、解析和错误转换留在客户端层。
创建路由实例、声明页面路由并挂载到 Vue 应用。
配置 Vue Router
用于在 Vue 3 单页应用中声明 URL 与页面组件的映射,并把路由实例挂载到应用。完成后可通过 <RouterLink> 导航,通过 <RouterView> 渲染当前页面。
安装与路由表
安装 Vue Router,并用 npm ls 验证依赖已进入当前项目。
npm install vue-router
npm ls vue-router --depth=0预期输出:
<PROJECT>@<VERSION> <PATH>
└── vue-router@<VERSION>保存为 src/router/index.ts。createWebHistory(import.meta.env.BASE_URL) 会同时适配根路径部署和 Vite 配置的子路径部署;兜底路由放在末尾便于快速识别。
import {
createRouter,
createWebHistory,
type RouteRecordRaw,
} from 'vue-router'
const routes: RouteRecordRaw[] = [
{
path: '/',
name: 'home',
component: () => import('@/views/HomeView.vue'),
},
{
path: '/login',
name: 'login',
component: () => import('@/views/LoginView.vue'),
},
{
path: '/users/:id',
name: 'user-detail',
component: () => import('@/views/UserDetailView.vue'),
props: true,
meta: { requiresAuth: true },
},
{
path: '/:pathMatch(.*)*',
name: 'not-found',
component: () => import('@/views/NotFoundView.vue'),
},
]
export const router = createRouter({
history: createWebHistory(import.meta.env.BASE_URL),
routes,
scrollBehavior() {
return { top: 0 }
},
})挂载到应用
路由必须在 mount() 前通过 use() 注册,否则 <RouterLink> 和 <RouterView> 不可用。
import { createApp } from 'vue'
import App from './App.vue'
import { router } from './router'
createApp(App)
.use(router)
.mount('#app')根组件保留导航出口和页面出口:
<script setup lang="ts">
import { RouterLink, RouterView } from 'vue-router'
</script>
<template>
<nav>
<RouterLink to="/">首页</RouterLink>
<RouterLink :to="{ name: 'user-detail', params: { id: 42 } }">
用户 42
</RouterLink>
</nav>
<RouterView />
</template>启动并验证:
npm run dev预期输出:
VITE v<VERSION> ready in <TIME> ms
Local: http://localhost:<PORT>/打开 / 应渲染 HomeView.vue;点击“用户 42”后 URL 变为 /users/42,并渲染 UserDetailView.vue;未知路径进入 NotFoundView.vue。<TIME>、<PORT> 和版本号以本机输出为准。
高频用法
命名路由比硬编码路径更适合业务跳转,参数变化时只需调整路由表。
import { useRouter } from 'vue-router'
const router = useRouter()
await router.push({
name: 'user-detail',
params: { id: 42 },
query: { tab: 'orders' },
})预期结果:
浏览器地址变为 /users/42?tab=orders需要登录校验时使用全局守卫,并通过 return 决定放行或重定向。把守卫放在 src/router/index.ts 创建实例之后。
router.beforeEach((to) => {
const signedIn = Boolean(sessionStorage.getItem('access_token'))
if (to.meta.requiresAuth && !signedIn) {
return {
name: 'login',
query: { redirect: to.fullPath },
}
}
})预期结果:
未登录访问 /users/42 时跳转到 /login?redirect=/users/42风险与边界
使用 createWebHistory() 时,用户直接刷新 /users/42 会向服务器请求该路径。服务器若没有把未知前端路由回退到 index.html,会返回 404;安全替代方案是配置 Nginx、CDN 或静态托管平台的 SPA fallback,无法改服务器时改用 createWebHashHistory()。
守卫中不要同时混用 next() 和返回值,也不要在重定向后继续执行异步逻辑,否则可能出现重复导航或循环跳转。鉴权守卫应明确放行公开路由,并限制重定向次数。
排障清单
- 页面空白:确认
App.vue存在<RouterView />,并且app.use(router)位于mount()前。 - 控制台提示无法匹配路由:核对
path、路由参数名、部署base和链接大小写。 - 开发环境正常、生产刷新 404:补充服务器 fallback,而不是新增更多前端路由。
- 动态参数变化但页面数据不刷新:同一组件实例可能被复用,应监听
route.params.id或使用onBeforeRouteUpdate()。 - Linux 构建失败:检查
views文件名与导入路径大小写是否完全一致。
速查:先声明路由表,再创建实例,最后在 mount() 前注册;生产环境同时配置历史模式回退。
使用路由链接或编程式 API 跳转、替换和返回页面。
执行路由跳转
在 Vue 3 组件中,固定导航优先使用 RouterLink,需要根据事件、权限校验或接口结果决定目标时使用 useRouter()。push 会新增历史记录,replace 会替换当前记录,back 与 go 用于沿浏览器历史移动。
基本语法
RouterLink 的 to 与 router.push() 接受相同的目标格式,可以传路径字符串,也可以传包含 name、params、query 和 hash 的对象。业务代码优先使用命名路由,避免路径调整后到处修改字符串。
| 写法 | 作用 | 历史记录 |
|---|---|---|
<RouterLink to="/about"> |
声明式跳转 | 新增一条 |
router.push(location) |
编程式跳转 | 新增一条 |
router.replace(location) |
编程式替换 | 替换当前条 |
router.back() |
返回上一条记录 | 向后移动 |
router.go(n) |
前进或后退指定步数 | 按 n 移动 |
主示例
片段示例:将以下组件放入已通过 app.use(router) 注册 Vue Router 4 的项目,并确保路由表存在 user-detail 与 login 两个命名路由。
<script setup lang="ts">
import { RouterLink, RouterView, useRouter } from 'vue-router'
const router = useRouter()
async function openUser(): Promise<void> {
// 使用命名路由传 params,路由表应包含 /users/:id。
await router.push({
name: 'user-detail',
params: { id: 42 },
query: { tab: 'profile' }
})
}
async function replaceWithLogin(): Promise<void> {
// 登录页替换当前记录,避免返回按钮再次进入受限页面。
await router.replace({
name: 'login',
query: { redirect: '/users/42' }
})
}
function returnPrevious(): void {
router.back()
}
</script>
<template>
<nav>
<RouterLink to="/about">关于页面</RouterLink>
<button type="button" @click="openUser">打开用户 42</button>
<button type="button" @click="replaceWithLogin">替换为登录页</button>
<button type="button" @click="returnPrevious">返回</button>
</nav>
<RouterView />
</template>预期结果
点击“打开用户 42”:地址变为 /users/42?tab=profile,并可通过返回按钮回到原页面。
点击“替换为登录页”:地址变为 /login?redirect=/users/42,当前历史记录被替换。
点击“返回”:浏览器存在上一条历史记录时返回,否则页面保持不变。选择跳转方式
普通菜单、面包屑和可访问性要求较高的导航使用 RouterLink;提交成功后进入详情页使用 push;登录重定向、旧地址迁移或不希望用户返回中间页时使用 replace。业务上要求“返回列表”时应显式跳转到列表路由,不要假设 back() 一定返回应用内页面。
风险与边界
使用 { path: '/users', params: { id: 42 } } 时,params 不会替你拼接到 path,可能跳到错误地址;改用 { name: 'user-detail', params: { id: 42 } },或直接构造完整路径。调用 replace 后当前记录无法通过返回按钮恢复,涉及编辑草稿或支付流程时应先确认用户不会丢失上下文。
back() 依赖真实浏览器历史:用户直接打开页面、新标签页进入或上一页属于外部站点时,结果可能为空或离开应用。需要确定落点时使用命名路由作为安全替代。不要直接信任查询参数中的 redirect 并交给 window.location,应限制为允许的站内路由,避免开放重定向。
排障清单
跳转无反应时,先确认路由实例在 mount 前执行了 app.use(router),根组件存在 RouterView,目标路由名称拼写一致。地址已变化但刷新后出现服务器 404,通常是 createWebHistory 缺少服务端回退配置;这不是 push 失效,应让服务器把未知前端路径回退到入口 HTML。
导航被取消或重定向时检查全局守卫、路由独享守卫和组件内守卫。组合式 API 中只能在组件 setup 上下文调用 useRouter();Options API 对应使用 this.$router。
读取动态路径参数、查询参数和当前路由信息。
读取路由参数
在 Vue 3 组件中使用 useRoute() 读取动态路径参数、查询参数和当前路由元信息。路由对象是响应式的;同一组件从 /users/41 切换到 /users/42 时,应监听具体字段,而不是只在组件挂载时读取一次。
读取入口
路径 /users/:id 匹配 /users/42?q=vue&tag=router&tag=vue3#profile 后,id 位于 route.params,q 和重复的 tag 位于 route.query,锚点位于 route.hash。route.fullPath 保留查询串和锚点,适合日志、分享地址和缓存键检查。
| 字段 | 读取内容 | 常见类型 |
|---|---|---|
route.params |
动态路径参数 | 字符串或字符串数组 |
route.query |
? 后的查询参数 |
字符串、null 或数组 |
route.hash |
# 开头的锚点 |
字符串 |
route.path |
不含查询和锚点的路径 | 字符串 |
route.fullPath |
完整路由地址 | 字符串 |
route.name |
当前命名路由 | 字符串、Symbol 或未定义 |
route.meta |
匹配路由合并后的元信息 | 对象 |
route.matched |
命中的父子路由记录 | 数组 |
主示例
片段示例:路由表需包含 { path: '/users/:id', name: 'user-detail', component: UserDetail },然后把以下内容作为 UserDetail.vue。
<script setup lang="ts">
import { computed, watch } from 'vue'
import { useRoute } from 'vue-router'
const route = useRoute()
const userId = computed(() => {
const value = route.params.id
return Array.isArray(value) ? value[0] ?? '' : value ?? ''
})
const keyword = computed(() => {
const value = route.query.q
return Array.isArray(value) ? value[0] ?? '' : value ?? ''
})
const tags = computed(() => {
const value = route.query.tag
if (Array.isArray(value)) {
return value.filter((item): item is string => item !== null)
}
return value ? [value] : []
})
watch(
() => route.params.id,
(current, previous) => {
// 同一组件实例复用时,在这里重新请求当前用户数据。
console.log('user changed:', previous, '=>', current)
},
{ immediate: true }
)
</script>
<template>
<p>用户 ID:{{ userId }}</p>
<p>关键词:{{ keyword }}</p>
<p>标签:{{ tags.join('、') }}</p>
<p>当前地址:{{ route.fullPath }}</p>
</template>访问 /users/42?q=vue&tag=router&tag=vue3#profile 时,预期结果
页面显示:
用户 ID:42
关键词:vue
标签:router、vue3
当前地址:/users/42?q=vue&tag=router&tag=vue3#profile
控制台首次进入时显示:
user changed: undefined => 42响应式更新
不要写 const { params, query } = useRoute() 后长期依赖解构结果,因为导航时对应对象可能被替换,容易读到旧值。模板中直接使用 route.params.id,派生值使用 computed,请求数据或执行副作用时使用 watch(() => route.params.id, ...)。需要在导航确认前处理变更时,可使用 onBeforeRouteUpdate。
风险与边界
路由参数和查询参数来自 URL,不能直接视为可信数字、权限标识或数据库主键。转换为数字后还要检查 Number.isInteger、范围和业务权限;验证失败时跳转到安全页面或显示 400 类错误。可选参数可能为 undefined,无值查询参数可能为 null,重复查询参数可能为数组,读取前必须覆盖这些分支。
动态参数默认是字符串,不会因内容为 42 自动变成数字。使用重复参数或重复查询键时,不要强制断言为单个字符串;先按数组处理,再决定取第一项、全部保留或判定为非法输入。
排障清单
route.params.id 为 undefined 时,检查路由路径是否真的声明了 :id、代码中的键名是否一致,以及当前 URL 是否匹配目标路由。参数变化但页面数据不刷新时,通常是组件被复用且请求只写在 onMounted 中,应改为监听具体参数。
查询参数读取异常时,先打印 route.fullPath 与 route.query,确认参数是否被编码、是否重复出现以及是否只有键没有值。组合式 API 使用 useRoute();Options API 使用 this.$route,不要把用于读取信息的 $route 与用于执行跳转的 $router 混淆。