Vue 3 模板语法速查
摘要
- Vue 3 模板(
<template>)语法速查:插值、指令解剖、v-bind/v-on/v-if/v-for/v-model、插槽、ref/key,以及v-once/v-memo等优化指令,配可直接对照的示例 - 本文按 Vue 3.4+(同名简写等按版本标注)。示例默认 Composition API +
<script setup>,与 用 create-vue 创建 Vue 3 项目 脚手架一致 - 官方文档:模板语法、内置指令、Class 与 Style 绑定、条件渲染、列表渲染、事件处理、表单输入绑定、插槽
怎么速查
按场景跳转:
| 我想… | 看 |
|---|---|
| 显示文本 / HTML | 文本插值与 v-html |
| 绑属性、class、style | v-bind |
| 点按钮、键盘 | v-on |
| 显示隐藏 | v-if / v-show |
| 列表 | v-for |
| 表单双向绑定 | v-model |
| 父子内容分发 | 插槽 |
| 拿 DOM / 组件实例 | ref |
| 指令总表 | 内置指令一览 |
SFC 里的 template
单文件组件通常三块:
1 | <script setup lang="ts"> |
要点:
-
<template>是组件的声明式视图;编译后变成渲染函数 -
<script setup>顶层绑定会自动暴露给模板,不必return -
模板必须是合法 HTML 结构;根节点在 Vue 3 可以有多个(片段)
-
模板里写的是表达式,不是任意语句(见下文)
单独的 <template> 标签(不带组件)也可作不可见包装:配合 v-if / v-for / v-slot 包一组节点,本身不渲染成 DOM 元素。
文本插值与 v-html
双大括号
1 | <span>{{ msg }}</span> |
-
按文本插入,会转义 HTML
-
msg变化时自动更新
v-text / v-html
1 | <span v-text="msg"></span> |
v-html 按 HTML 插入,不解析其中的 Vue 模板语法。只用于可信内容;不要把用户输入直接塞进 v-html(XSS)。
scoped CSS 不会作用到 v-html 插入的内容。
表达式规则
模板绑定里可以用完整 JS 表达式,但每处绑定只能是单一表达式(能写在 return 后面的那种):
1 | <!-- 合法 --> |
-
可调用组件里暴露的方法;方法在每次更新时可能被调用,不要有副作用(改数据、发请求)
-
只能访问有限全局(如
Math、Date);自定义全局需挂到app.config.globalProperties
指令解剖
1 | v-指令名:参数.修饰符1.修饰符2="表达式" |
| 形态 | 示例 | 含义 |
|---|---|---|
| 无参数 | v-if="seen" |
表达式为真才渲染 |
| 有参数 | v-bind:href="url" |
把 url 绑到 href |
| 动态参数 | v-bind:[attrName]="val" |
参数名运行时决定 |
| 修饰符 | @submit.prevent |
提交时 preventDefault |
| 简写 | :href / @click / #header |
v-bind / v-on / v-slot |
动态参数的值须是字符串或 null(null 表示移除绑定)。复杂表达式建议放到计算属性。DOM 内嵌模板里属性名会被转成小写,动态参数慎用驼峰;SFC 无此限制。
v-bind:属性与 prop
简写 :。
基础
1 | <img :src="imageSrc" :alt="imageAlt" /> |
同名简写(3.4+)
1 | <!-- 等价于 :id="id" --> |
对象一次性绑定多个
1 | <script setup lang="ts"> |
Vue 3 中 v-bind="obj" 与单独写的绑定按书写顺序合并,后写的覆盖先写的。
class
1 | <!-- 对象:值为真的 class 生效 --> |
组件上的 class / style 默认落到根元素;多根节点时需显式声明继承或绑到目标节点。
style
1 | <div :style="{ color: activeColor, fontSize: fontSize + 'px' }"></div> |
修饰符
| 修饰符 | 作用 |
|---|---|
.prop |
强制设为 DOM property(3.2+);简写可用 .foo="bar" |
.attr |
强制设为 DOM attribute(3.2+) |
.camel |
短横线名转驼峰(DOM 内模板绑 SVG viewBox 等时有用) |
1 | <div :inner-html.prop="html"></div> |
绑到子组件时,对应 prop 须在子组件中声明。
v-on:事件
简写 @。
基础
1 | <script setup lang="ts"> |
-
普通元素:听原生 DOM 事件
-
组件:听子组件
emit的自定义事件(Vue 3 无需.native)
修饰符速查
可链式组合:@click.stop.prevent。
| 修饰符 | 作用 |
|---|---|
.stop |
stopPropagation |
.prevent |
preventDefault |
.capture |
捕获阶段监听 |
.self |
事件从本元素发出才触发(子元素冒泡上来的不触发) |
.once |
最多触发一次 |
.passive |
{ passive: true }(滚动性能) |
.left / .right / .middle |
鼠标按键 |
.enter / .esc / .tab / .space / .up / .down / .left / .right 等 |
按键别名 |
.ctrl / .alt / .shift / .meta |
系统修饰键 |
.exact |
精确组合(有多余修饰键则不触发) |
1 | <form @submit.prevent="onSubmit">...</form> |
系统修饰键也可配在 keyup:@keyup.ctrl="onCtrl"。注意 keyup 时若先松修饰键,可能检测不到组合,按需改用 keydown。
条件渲染
v-if / v-else-if / v-else
1 | <div v-if="type === 'A'">A</div> |
-
条件为假时不渲染(可销毁 / 重建内部状态)
-
懒:初始为假时,内部一开始不会渲染
v-show
1 | <h1 v-show="ok">一直在 DOM 里,用 display 切换</h1> |
v-if |
v-show |
|
|---|---|---|
| 隐藏方式 | 不渲染 / 销毁 | display: none |
| 初始成本 | 假时更低 | 总是渲染 |
| 切换成本 | 更高 | 更低 |
| 适用 | Cond 很少变 | 频繁切换 |
v-else 不能接在 v-show 后面。
同一元素上不要同时写 v-if 与 v-for。Vue 3 中 v-if 优先级更高,往往拿不到 v-for 的作用域变量。需要时先用 computed 过滤列表,或把 v-if 放到内层 / 外层 <template>。
列表渲染
数组
1 | <li v-for="item in items" :key="item.id"> |
对象
1 | <li v-for="(value, key) in object" :key="key"> |
数字 / 字符串 / Iterable
1 | <span v-for="n in 5" :key="n">{{ n }}</span> |
也支持实现了 Iterable 的 Map / Set。
key
1 | <div v-for="item in items" :key="item.id">...</div> |
-
给 Vue 排序 / 复用节点的身份提示
-
用稳定唯一 id;不要用随机数;慎用
index(列表会插入 / 删除 / 重排时容易状态错乱) -
组件上的
v-for同样需要:key
过滤与排序
不要在模板里 v-for="item in items.filter(...)" 写复杂逻辑;用计算属性:
1 | <script setup lang="ts"> |
与 <template> / 组件
1 | <template v-for="item in items" :key="item.id"> |
v-model
在表单控件或组件上做双向绑定。
原生表单
1 | <script setup lang="ts"> |
checkbox 多选绑到数组:
1 | <input type="checkbox" value="js" v-model="langs" /> |
修饰符
| 修饰符 | 作用 |
|---|---|
.lazy |
在 change 时同步,而不是每次 input |
.number |
输入转数字(合法时) |
.trim |
去两端空格 |
1 | <input v-model.lazy.trim="name" /> |
组件上的 v-model
默认等价于:
1 | <Child v-model="foo" /> |
子组件(<script setup>):
1 | <script setup lang="ts"> |
多个 v-model / 具名:
1 | <UserForm v-model:name="name" v-model:age="age" /> |
子组件对应 prop name + 事件 update:name,或 defineModel('name')。
插槽
默认插槽
子组件:
1 | <!-- Child.vue --> |
父组件:
1 | <Child> |
具名插槽
简写 #。
1 | <!-- Layout.vue --> |
1 | <Layout> |
判断是否传入:
1 | <div v-if="$slots.header" class="header"> |
作用域插槽
子 → 父传数据:
1 | <!-- List.vue --> |
1 | <List :items="items"> |
只有默认作用域插槽时,可写在组件标签上:
1 | <Mouse v-slot="{ x, y }"> |
模板 ref
拿 DOM 或子组件实例。
1 | <script setup lang="ts"> |
-
ref="inputRef"对应脚本里的同名ref -
v-for上的 ref 是数组(或按 key 的 Map,视写法而定);在onBeforeUpdate里清空再收集更稳妥 -
子组件若用
<script setup>,内部绑定默认私有;需用defineExpose({ open })暴露给父级
特殊 attribute:key / is
key
除 v-for 外,也可用在 v-if 分支上强制重建:
1 | <UserForm :key="userId" /> |
is(动态组件 / 原生元素)
1 | <script setup lang="ts"> |
在 DOM 内模板里,带 is 的原生标签可能被浏览器限制;SFC 一般无妨。
内置「模板友好」组件(速记)
| 组件 | 用途 |
|---|---|
<KeepAlive> |
缓存动态组件实例,保留状态 |
<Teleport to="body"> |
把子树挂到 DOM 别处(弹层) |
<Transition> / <TransitionGroup> |
进入 / 离开过渡 |
<Suspense> |
异步依赖就绪前的占位(实验性能力随版本演进,查当前文档) |
1 | <Teleport to="body"> |
性能与编译相关指令
v-once
只渲染一次,之后当静态节点跳过更新:
1 | <span v-once>固定文案:{{ msg }}</span> |
v-memo(3.2+)
依赖数组不变则跳过整棵子树更新:
1 | <div v-memo="[valueA, valueB]">...</div> |
v-memo="[]" 约等于 v-once。依赖写错会跳过本该更新的内容;仅在确有性能瓶颈时用。
v-pre
跳过编译,原样显示模板语法:
1 | <span v-pre>{{ 这里不会被编译 }}</span> |
v-cloak
无构建步骤、DOM 内模板时,避免未编译的 {{ }} 闪现:
1 | [v-cloak] { display: none; } |
1 | <div v-cloak>{{ message }}</div> |
Vite + SFC 项目一般用不到。
内置指令一览
| 指令 | 简写 | 一句话 |
|---|---|---|
v-text |
— | 设 textContent |
v-html |
— | 设 innerHTML(慎用) |
v-show |
— | CSS 切换显示 |
v-if |
— | 条件挂载 |
v-else-if |
— | if 链 |
v-else |
— | else 块 |
v-for |
— | 列表 |
v-on |
@ |
事件 |
v-bind |
: / . |
属性 / prop |
v-model |
— | 双向绑定 |
v-slot |
# |
插槽 |
v-pre |
— | 不编译 |
v-once |
— | 只渲染一次 |
v-memo |
— | 按依赖缓存子树 |
v-cloak |
— | 挂载前隐藏未编译模板 |
常见坑速查
| 现象 | 处理 |
|---|---|
attribute 里写了 {{ }} |
改用 :attr="expr" |
v-if + v-for 同元素 |
拆开或先 computed 过滤 |
| 列表状态错乱 | 给稳定 :key,别乱用 index |
子组件 ref 调不到方法 |
defineExpose |
| 按需后语言包不对 | 用 ElConfigProvider,见 Vue 3 全量引入与按需导入 |
| 刷新子路由 404 | History 模式要服务端回退,见 用 create-vue 创建 Vue 3 项目 |
最小可复制示例
1 | <script setup lang="ts"> |
覆盖了插值、v-model、v-on、v-bind(含 class / disabled)、v-for + key、v-if 链——可作本地练习底稿。