该页面假设你已经阅读过了组件基础。如果你还对组件不太了解，推荐你先阅读它。
不同于组件和 prop，事件名不存在任何自动化的大小写转换。而是触发的事件名需要完全匹配监听这个事件所用的名称。举个例子，如果触发一个 camelCase 名字的事件：
则监听这个名字的 kebab-case 版本是不会有任何效果的：
1
2
|
<my-component v-on:my-event="doSomething"></my-component>
|
不同于组件和 prop，事件名不会被用作一个 JavaScript 变量名或 property 名，所以就没有理由使用 camelCase 或 PascalCase 了。并且 v-on 事件监听器在 DOM 模板中会被自动转换为全小写 (因为 HTML 是大小写不敏感的)，所以 v-on:myEvent 将会变成 v-on:myevent——导致 myEvent 不可能被监听到。
因此，我们推荐你始终使用 kebab-case 的事件名。
2.2.0+ 新增
一个组件上的 v-model 默认会利用名为 value 的 prop 和名为 input 的事件，但是像单选框、复选框等类型的输入控件可能会将 value attribute 用于不同的目的。model 选项可以用来避免这样的冲突：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| Vue.component('base-checkbox', {
model: {
prop: 'checked',
event: 'change'
},
props: {
checked: Boolean
},
template: `
<input
type="checkbox"
v-bind:checked="checked"
v-on:change="$emit('change', $event.target.checked)"
>
`
})
|
现在在这个组件上使用 v-model 的时候：
1
| <base-checkbox v-model="lovingVue"></base-checkbox>
|
这里的 lovingVue 的值将会传入这个名为 checked 的 prop。同时当 <base-checkbox> 触发一个 change 事件并附带一个新的值的时候，这个 lovingVue 的 property 将会被更新。
注意你仍然需要在组件的 props 选项里声明 checked 这个 prop。
你可能有很多次想要在一个组件的根元素上直接监听一个原生事件。这时，你可以使用 v-on 的 .native 修饰符：
1
| <base-input v-on:focus.native="onFocus"></base-input>
|
在有的时候这是很有用的，不过在你尝试监听一个类似 <input> 的非常特定的元素时，这并不是个好主意。比如上述 <base-input> 组件可能做了如下重构，所以根元素实际上是一个 <label> 元素：
1
2
3
4
5
6
7
8
| <label>
{{ label }}
<input
v-bind="$attrs"
v-bind:value="value"
v-on:input="$emit('input', $event.target.value)"
>
</label>
|
这时，父级的 .native 监听器将静默失败。它不会产生任何报错，但是 onFocus 处理函数不会如你预期地被调用。
为了解决这个问题，Vue 提供了一个 $listeners property，它是一个对象，里面包含了作用在这个组件上的所有监听器。例如：
1
2
3
4
| {
focus: function (event) { }
input: function (value) { },
}
|
有了这个 $listeners property，你就可以配合 v-on="$listeners" 将所有的事件监听器指向这个组件的某个特定的子元素。对于类似 <input> 的你希望它也可以配合 v-model 工作的组件来说，为这些监听器创建一个类似下述 inputListeners 的计算属性通常是非常有用的：
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
| Vue.component('base-input', {
inheritAttrs: false,
props: ['label', 'value'],
computed: {
inputListeners: function () {
var vm = this
return Object.assign({},
this.$listeners,
{
input: function (event) {
vm.$emit('input', event.target.value)
}
}
)
}
},
template: `
<label>
{{ label }}
<input
v-bind="$attrs"
v-bind:value="value"
v-on="inputListeners"
>
</label>
`
})
|
现在 <base-input> 组件是一个完全透明的包裹器了，也就是说它可以完全像一个普通的 <input> 元素一样使用了：所有跟它相同的 attribute 和监听器都可以工作，不必再使用 .native 监听器。
2.3.0+ 新增
在有些情况下，我们可能需要对一个 prop 进行“双向绑定”。不幸的是，真正的双向绑定会带来维护上的问题，因为子组件可以变更父组件，且在父组件和子组件两侧都没有明显的变更来源。
这也是为什么我们推荐以 update:myPropName 的模式触发事件取而代之。举个例子，在一个包含 title prop 的假设的组件中，我们可以用以下方法表达对其赋新值的意图：
1
| this.$emit('update:title', newTitle)
|
然后父组件可以监听那个事件并根据需要更新一个本地的数据 property。例如：
1
2
3
4
| <text-document
v-bind:title="doc.title"
v-on:update:title="doc.title = $event"
></text-document>
|
为了方便起见，我们为这种模式提供一个缩写，即 .sync 修饰符：
1
| <text-document v-bind:title.sync="doc.title"></text-document>
|
注意带有 .sync 修饰符的 v-bind 不能和表达式一起使用 (例如 v-bind:title.sync=”doc.title + ‘!’” 是无效的)。取而代之的是，你只能提供你想要绑定的 property 名，类似 v-model。
当我们用一个对象同时设置多个 prop 的时候，也可以将这个 .sync 修饰符和 v-bind 配合使用：
1
| <text-document v-bind.sync="doc"></text-document>
|
这样会把 doc 对象中的每一个 property (如 title) 都作为一个独立的 prop 传进去，然后各自添加用于更新的 v-on 监听器。
将 v-bind.sync 用在一个字面量的对象上，例如 v-bind.sync=”{ title: doc.title }”，是无法正常工作的，因为在解析一个像这样的复杂表达式的时候，有很多边缘情况需要考虑。
🧪 动手 Demo
将原生事件绑定到组件的 Demo
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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
| <!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>彻底搞懂 Vue 2 $listeners 和 .native</title>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/vue.js"></script>
<style>
body { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; padding: 20px; background: #f8f9fa; }
.demo-box {
background: white; padding: 15px 20px; margin-bottom: 30px;
border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1);
border-left: 5px solid #ccc;
}
.demo-box h3 { margin-top: 0; }
.bad { border-left-color: #ff6b6b; }
.good { border-left-color: #51cf66; }
input { padding: 8px 12px; width: 250px; border: 1px solid #ced4da; border-radius: 4px; }
.log { background: #f1f3f5; padding: 5px 12px; border-radius: 20px; display: inline-block; font-size: 14px; }
.highlight { color: #e67700; font-weight: bold; }
</style>
</head>
<body>
<div id="app">
<h2>📖 Vue 2 官方文档案例拆解</h2>
<p>父组件数据：<strong>输入值</strong> = "{{ parentText }}" ｜ <strong>焦点触发次数</strong> = {{ focusCount }}</p>
<hr>
<div class="demo-box bad">
<h3>❌ 场景 1：根元素是 label，父级使用 <code>@focus.native</code></h3>
<p><span class="log">⚡ 点击下方输入框，焦点计数不会增加（静默失败）</span></p>
<base-input-bad
v-model="parentText"
@focus.native="onFocus"
/>
<p style="color: #868e96; font-size: 14px;">💡 原因：.native 绑在了外层 <label> 上，而 focus 事件不冒泡，所以永远收不到。</p>
</div>
<div class="demo-box good">
<h3>✅ 场景 2：根元素是 label，使用 <code>$listeners</code> 透传（官方推荐）</h3>
<p><span class="log">⚡ 点击下方输入框，焦点计数会增加，且 v-model 正常工作</span></p>
<base-input-good
v-model="parentText"
@focus="onFocus"
/>
<p style="color: #2b8a3e; font-size: 14px;">💡 原理：父组件的 @focus 被放进了 $listeners，子组件通过 v-on 精准绑定到了内部的 <input> 上。</p>
</div>
</div>
<script>
// ============================================
// 1. 错误子组件：根元素是 <label>，父级用 .native 会失效
// ============================================
Vue.component('base-input-bad', {
props: ['value'],
template: `
<label style="background:#fff5f5; padding:8px; display:block; border-radius:4px;">
<span style="color:#c92a2a;">❌ 坏组件（外层 label）</span>
<br>
<input
:value="value"
@input="$emit('input', $event.target.value)"
placeholder="点我，计数不会变"
>
</label>
`
});
// ============================================
// 2. 正确子组件：根元素是 <label>，但使用 $listeners 精准透传（官方文档原样复刻）
// ============================================
Vue.component('base-input-good', {
// 允许透传非 prop 的 attribute（如 placeholder, id 等）
inheritAttrs: false,
props: ['value'],
computed: {
inputListeners: function () {
var vm = this;
// 关键点：合并父级的所有监听器（如 @focus）和自定义的 input 处理逻辑
return Object.assign({},
// 1. 父级传过来的所有监听器（这里包含了 @focus）
this.$listeners,
// 2. 我们手动覆盖或添加监听器（这里覆盖了 input 事件）
{
// 当内部 input 触发原生 input 事件时，我们手动抛出一个带值的自定义事件
// 这样父级的 v-model 就能正确收到值了
input: function (event) {
vm.$emit('input', event.target.value);
}
}
);
}
},
template: `
<label style="background:#ebfbee; padding:8px; display:block; border-radius:4px;">
<span style="color:#2b8a3e;">✅ 好组件（外层 label）</span>
<br>
<input
v-bind="$attrs"
:value="value"
v-on="inputListeners"
placeholder="点我，计数会变且 v-model 有效"
>
</label>
`
});
// ============================================
// 3. 父组件
// ============================================
new Vue({
el: '#app',
data: {
parentText: 'Hello Vue',
focusCount: 0
},
methods: {
onFocus: function() {
this.focusCount++;
}
}
});
</script>
</body>
</html>
|
🎯 一句话终极总结
| 写法 |
效果 |
适用场景 |
@focus.native |
绑在根 DOM 元素上，根元素变了就失效 |
仅限根元素就是目标标签的简单情况 |
v-on="$listeners"（不加覆盖） |
父级监听器全透传，但 v-model 可能坏掉 |
不需要 v-model 时可以用 |
Object.assign 覆盖 input（官方写法） |
父级所有事件（如 focus）+ v-model 同时完美工作 |
封装表单输入组件（如带 label 的输入框）的标准写法 |
sync 的 Demo
这是一个 “父子协同修改标题” 的完整例子。点击子组件的按钮，父组件的标题会同步变化。
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
45
46
47
48
49
50
51
52
| <!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>彻底搞懂 Vue .sync 修饰符</title>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/vue.js"></script>
</head>
<body>
<div id="app">
<h2>📺 父组件数据</h2>
<p>当前文章标题：<strong style="color:blue;">{{ doc.title }}</strong></p>
<hr>
<text-document :title.sync="doc.title" />
</div>
<script>
// 子组件：文本编辑器
Vue.component('text-document', {
props: ['title'], // 接收父组件传进来的标题
template: `
<div style="border:1px solid #ccc; padding:15px; border-radius:8px; background:#f8f9fa;">
<h3>📝 子组件编辑器</h3>
<p>当前标题（来自父组件）：<strong>{{ title }}</strong></p>
<button @click="changeTitle">点击修改标题（通知父组件）</button>
<p style="color:#868e96; font-size:14px;">点击按钮 -> 子组件发射 update:title 事件 -> 父组件收到后自动更新 doc.title</p>
</div>
`,
methods: {
changeTitle() {
// 核心：子组件不直接修改 props，而是“喊话”让父组件改
const newTitle = '标题被修改为：' + new Date().toLocaleTimeString();
this.$emit('update:title', newTitle);
}
}
});
new Vue({
el: '#app',
data: {
doc: {
title: 'Vue 官方教程学习笔记'
}
}
});
</script>
</body>
</html>
|
🤔 关于文档最后“对象用法”的解释
文档提到：<text-document v-bind.sync="doc"></text-document>
这是批量操作。如果你的 doc 对象里有 title、author、date 等多个属性，加上 .sync 后，Vue 会自动遍历 doc 对象的每一个属性，分别创建独立的 v-bind:属性名.sync="doc.属性名"。
等价于：
1
2
3
4
5
| <text-document
:title.sync="doc.title"
:author.sync="doc.author"
:date.sync="doc.date"
></text-document>
|
这样，子组件可以分别修改 title、author、date，父组件的数据都会同步更新。
参考
介绍 — Vue.js