Vue 3 模板语法速查

摘要

怎么速查

按场景跳转:

我想… 看
显示文本 / HTML 文本插值与 v-html
绑属性、class、style v-bind
点按钮、键盘 v-on
显示隐藏 v-if / v-show
列表 v-for
表单双向绑定 v-model
父子内容分发 插槽
拿 DOM / 组件实例 ref
指令总表 内置指令一览

SFC 里的 template

单文件组件通常三块:

1
2
3
4
5
6
7
8
9
10
11
12
<script setup lang="ts">
import { ref } from 'vue'
const msg = ref('hello')
</script>

<template>
<p>{{ msg }}</p>
</template>

<style scoped>
p { color: #42b883; }
</style>

要点:

  • <template> 是组件的声明式视图;编译后变成渲染函数

  • <script setup> 顶层绑定会自动暴露给模板,不必 return

  • 模板必须是合法 HTML 结构;根节点在 Vue 3 可以有多个(片段)

  • 模板里写的是表达式,不是任意语句(见下文)

单独的 <template> 标签(不带组件)也可作不可见包装:配合 v-if / v-for / v-slot 包一组节点,本身不渲染成 DOM 元素。

文本插值与 v-html

双大括号

1
2
3
4
<span>{{ msg }}</span>
<span>{{ count + 1 }}</span>
<span>{{ ok ? 'YES' : 'NO' }}</span>
<span>{{ message.split('').reverse().join('') }}</span>
  • 按文本插入,会转义 HTML

  • msg 变化时自动更新

v-text / v-html

1
2
3
4
<span v-text="msg"></span>
<!-- 等同 {{ msg }},但会覆盖元素全部文本内容 -->

<div v-html="rawHtml"></div>

v-html 按 HTML 插入,不解析其中的 Vue 模板语法。只用于可信内容;不要把用户输入直接塞进 v-html(XSS)。

scoped CSS 不会作用到 v-html 插入的内容。

表达式规则

模板绑定里可以用完整 JS 表达式,但每处绑定只能是单一表达式(能写在 return 后面的那种):

1
2
3
4
5
6
7
8
<!-- 合法 -->
{{ number + 1 }}
<div :id="`list-${id}`"></div>
<time>{{ formatDate(date) }}</time>

<!-- 非法:语句 / 流程控制 -->
{{ var a = 1 }}
{{ if (ok) { return message } }}
  • 可调用组件里暴露的方法;方法在每次更新时可能被调用,不要有副作用(改数据、发请求)

  • 只能访问有限全局(如 Math、Date);自定义全局需挂到 app.config.globalProperties

指令解剖

1
2
3
4
5
6
v-指令名:参数.修饰符1.修饰符2="表达式"
│ │ │ │
│ │ │ └─ 多数情况是 JS 表达式
│ │ └─ 点号后缀,改变指令行为
│ └─ 可选,如 href、click、插槽名
└─ 以 v- 开头
形态 示例 含义
无参数 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
2
3
4
5
6
7
8
<img :src="imageSrc" :alt="imageAlt" />
<a :href="url">链接</a>

<!-- 值为 null / undefined 时,该 attribute 会从元素上移除 -->
<div :id="dynamicId"></div>

<!-- 布尔 attribute:真值或 '' 时存在 disabled;其它假值则移除 -->
<button :disabled="isDisabled">保存</button>

同名简写(3.4+)

1
2
<!-- 等价于 :id="id" -->
<div :id></div>

对象一次性绑定多个

1
2
3
4
5
6
7
8
9
10
11
<script setup lang="ts">
const attrs = {
id: 'box',
class: 'card',
'data-x': 1,
}
</script>

<template>
<div v-bind="attrs"></div>
</template>

Vue 3 中 v-bind="obj" 与单独写的绑定按书写顺序合并,后写的覆盖先写的。

class

1
2
3
4
5
6
7
8
9
<!-- 对象:值为真的 class 生效 -->
<div :class="{ active: isActive, 'text-danger': hasError }"></div>

<!-- 数组 -->
<div :class="[classA, classB]"></div>
<div :class="[{ active: isActive }, errorClass]"></div>

<!-- 与普通 class 共存,会合并 -->
<div class="static" :class="{ active: isActive }"></div>

组件上的 class / style 默认落到根元素;多根节点时需显式声明继承或绑到目标节点。

style

1
2
3
4
5
<div :style="{ color: activeColor, fontSize: fontSize + 'px' }"></div>
<div :style="[baseStyles, overridingStyles]"></div>

<!-- 自动加厂商前缀;多值可数组 -->
<div :style="{ display: ['-webkit-box', '-ms-flexbox', 'flex'] }"></div>

修饰符

修饰符 作用
.prop 强制设为 DOM property(3.2+);简写可用 .foo="bar"
.attr 强制设为 DOM attribute(3.2+)
.camel 短横线名转驼峰(DOM 内模板绑 SVG viewBox 等时有用)
1
2
<div :inner-html.prop="html"></div>
<svg :view-box.camel="viewBox"></svg>

绑到子组件时,对应 prop 须在子组件中声明。

v-on:事件

简写 @。

基础

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<script setup lang="ts">
function onSave(e: MouseEvent) {
console.log(e)
}
function greet(name: string, e: Event) {
console.log(name, e)
}
</script>

<template>
<!-- 方法名:自动传入原生事件 -->
<button @click="onSave">保存</button>

<!-- 内联语句;需要原生事件时用 $event -->
<button @click="greet('vue', $event)">打个招呼</button>

<!-- 动态事件名 -->
<button @[eventName]="onSave">动态</button>

<!-- 对象语法:一次绑多个;不支持修饰符 -->
<div v-on="{ mouseenter: onEnter, mouseleave: onLeave }"></div>
</template>
  • 普通元素:听原生 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
2
3
4
5
<form @submit.prevent="onSubmit">...</form>
<input @keyup.enter="onEnter" />
<input @keyup.ctrl.enter="onCtrlEnter" />
<button @click.once="init">只执行一次</button>
<div @click.self="onBackdrop">点遮罩关闭</div>

系统修饰键也可配在 keyup:@keyup.ctrl="onCtrl"。注意 keyup 时若先松修饰键,可能检测不到组合,按需改用 keydown。

条件渲染

v-if / v-else-if / v-else

1
2
3
4
5
6
7
8
9
10
<div v-if="type === 'A'">A</div>
<div v-else-if="type === 'B'">B</div>
<div v-else-if="type === 'C'">C</div>
<div v-else>其它</div>

<!-- 多根用 <template> 包,不产生多余节点 -->
<template v-if="ok">
<h1>标题</h1>
<p>内容</p>
</template>
  • 条件为假时不渲染(可销毁 / 重建内部状态)

  • 懒:初始为假时,内部一开始不会渲染

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
2
3
4
5
6
7
<li v-for="item in items" :key="item.id">
{{ item.text }}
</li>

<li v-for="(item, index) in items" :key="item.id">
{{ index }} - {{ item.text }}
</li>

对象

1
2
3
4
5
6
7
<li v-for="(value, key) in object" :key="key">
{{ key }}: {{ value }}
</li>

<li v-for="(value, key, index) in object" :key="key">
{{ index }}. {{ key }} = {{ value }}
</li>

数字 / 字符串 / Iterable

1
2
3
4
<span v-for="n in 5" :key="n">{{ n }}</span>
<!-- 1 到 5 -->

<span v-for="char in 'vue'" :key="char">{{ char }}</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
2
3
4
5
6
7
8
9
10
11
12
13
14
<script setup lang="ts">
import { computed, ref } from 'vue'

const items = ref([
{ id: 1, text: 'a', done: false },
{ id: 2, text: 'b', done: true },
])

const openItems = computed(() => items.value.filter((i) => !i.done))
</script>

<template>
<li v-for="item in openItems" :key="item.id">{{ item.text }}</li>
</template>

与 <template> / 组件

1
2
3
4
5
6
<template v-for="item in items" :key="item.id">
<li>{{ item.text }}</li>
<li class="divider"></li>
</template>

<MyItem v-for="item in items" :key="item.id" :item="item" />

v-model

在表单控件或组件上做双向绑定。

原生表单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<script setup lang="ts">
import { ref } from 'vue'

const text = ref('')
const checked = ref(false)
const picked = ref('a')
const selected = ref('foo')
const multi = ref<string[]>([])
</script>

<template>
<input v-model="text" placeholder="文本" />
<textarea v-model="text"></textarea>

<input type="checkbox" v-model="checked" />

<input type="radio" value="a" v-model="picked" />
<input type="radio" value="b" v-model="picked" />

<select v-model="selected">
<option disabled value="">请选择</option>
<option>foo</option>
<option>bar</option>
</select>

<select v-model="multi" multiple>
<option>a</option>
<option>b</option>
</select>
</template>

checkbox 多选绑到数组:

1
2
<input type="checkbox" value="js" v-model="langs" />
<input type="checkbox" value="ts" v-model="langs" />

修饰符

修饰符 作用
.lazy 在 change 时同步,而不是每次 input
.number 输入转数字(合法时)
.trim 去两端空格
1
2
<input v-model.lazy.trim="name" />
<input v-model.number="age" type="number" />

组件上的 v-model

默认等价于:

1
2
3
<Child v-model="foo" />
<!-- 约等于 -->
<Child :modelValue="foo" @update:modelValue="foo = $event" />

子组件(<script setup>):

1
2
3
4
5
6
7
8
9
10
<script setup lang="ts">
const model = defineModel<string>() // 3.4+ 更省事
// 或:
// const props = defineProps<{ modelValue: string }>()
// const emit = defineEmits<{ 'update:modelValue': [string] }>()
</script>

<template>
<input :value="model" @input="model = ($event.target as HTMLInputElement).value" />
</template>

多个 v-model / 具名:

1
<UserForm v-model:name="name" v-model:age="age" />

子组件对应 prop name + 事件 update:name,或 defineModel('name')。

插槽

默认插槽

子组件:

1
2
3
4
5
6
<!-- Child.vue -->
<template>
<div class="card">
<slot>默认内容</slot>
</div>
</template>

父组件:

1
2
3
<Child>
<p>被插入到 slot 位置</p>
</Child>

具名插槽

简写 #。

1
2
3
4
5
6
<!-- Layout.vue -->
<template>
<header><slot name="header" /></header>
<main><slot /></main>
<footer><slot name="footer" /></footer>
</template>
1
2
3
4
5
<Layout>
<template #header>标题</template>
<p>默认插槽内容</p>
<template #footer>页脚</template>
</Layout>

判断是否传入:

1
2
3
<div v-if="$slots.header" class="header">
<slot name="header" />
</div>

作用域插槽

子 → 父传数据:

1
2
3
4
5
6
<!-- List.vue -->
<ul>
<li v-for="item in items" :key="item.id">
<slot name="item" :item="item" :index="item.id" />
</li>
</ul>
1
2
3
4
5
<List :items="items">
<template #item="{ item, index }">
<span>{{ index }} - {{ item.text }}</span>
</template>
</List>

只有默认作用域插槽时,可写在组件标签上:

1
2
3
<Mouse v-slot="{ x, y }">
{{ x }}, {{ y }}
</Mouse>

模板 ref

拿 DOM 或子组件实例。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import type Child from './Child.vue'

const inputRef = ref<HTMLInputElement | null>(null)
const childRef = ref<InstanceType<typeof Child> | null>(null)

onMounted(() => {
inputRef.value?.focus()
childRef.value?.open()
})
</script>

<template>
<input ref="inputRef" />
<Child ref="childRef" />
</template>
  • ref="inputRef" 对应脚本里的同名 ref

  • v-for 上的 ref 是数组(或按 key 的 Map,视写法而定);在 onBeforeUpdate 里清空再收集更稳妥

  • 子组件若用 <script setup>,内部绑定默认私有;需用 defineExpose({ open }) 暴露给父级

特殊 attribute:key / is

key

除 v-for 外,也可用在 v-if 分支上强制重建:

1
2
<UserForm :key="userId" />
<!-- userId 变则整表重建,避免旧状态残留 -->

is(动态组件 / 原生元素)

1
2
3
4
5
6
7
8
9
10
11
12
13
<script setup lang="ts">
import { ref, computed } from 'vue'
import Foo from './Foo.vue'
import Bar from './Bar.vue'

const view = ref<'foo' | 'bar'>('foo')
const current = computed(() => (view.value === 'foo' ? Foo : Bar))
</script>

<template>
<component :is="current" />
<!-- 或 :is="'Foo'"(需已注册) / :is="Foo" -->
</template>

在 DOM 内模板里,带 is 的原生标签可能被浏览器限制;SFC 一般无妨。

内置「模板友好」组件(速记)

组件 用途
<KeepAlive> 缓存动态组件实例,保留状态
<Teleport to="body"> 把子树挂到 DOM 别处(弹层)
<Transition> / <TransitionGroup> 进入 / 离开过渡
<Suspense> 异步依赖就绪前的占位(实验性能力随版本演进,查当前文档)
1
2
3
4
5
6
7
<Teleport to="body">
<div class="modal" v-if="open">...</div>
</Teleport>

<KeepAlive>
<component :is="current" />
</KeepAlive>

性能与编译相关指令

v-once

只渲染一次,之后当静态节点跳过更新:

1
<span v-once>固定文案:{{ msg }}</span>

v-memo(3.2+)

依赖数组不变则跳过整棵子树更新:

1
2
3
4
5
6
7
8
9
10
<div v-memo="[valueA, valueB]">...</div>

<!-- 大海量列表时的常见写法 -->
<div
v-for="item in list"
:key="item.id"
v-memo="[item.id === selected]"
>
...
</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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
<script setup lang="ts">
import { computed, ref } from 'vue'

const title = ref('任务')
const draft = ref('')
const items = ref<{ id: number; text: string; done: boolean }[]>([
{ id: 1, text: '学习 template', done: true },
{ id: 2, text: '写速查手册', done: false },
])

const openCount = computed(() => items.value.filter((i) => !i.done).length)

function add() {
const text = draft.value.trim()
if (!text) return
items.value.push({ id: Date.now(), text, done: false })
draft.value = ''
}
</script>

<template>
<h1>{{ title }}(未完成 {{ openCount }})</h1>

<form @submit.prevent="add">
<input v-model.trim="draft" placeholder="新任务" />
<button :disabled="!draft.trim()">添加</button>
</form>

<ul>
<li v-for="item in items" :key="item.id" :class="{ done: item.done }">
<label>
<input type="checkbox" v-model="item.done" />
{{ item.text }}
</label>
</li>
</ul>

<p v-if="items.length === 0">暂无任务</p>
<p v-else-if="openCount === 0">全部完成</p>
</template>

<style scoped>
.done { opacity: 0.5; text-decoration: line-through; }
</style>

覆盖了插值、v-model、v-on、v-bind(含 class / disabled)、v-for + key、v-if 链——可作本地练习底稿。