Vue 2参考手册
指南 | Guide
15. Custom Directives(自定义指令)
介绍
除了核心(v-model
和v-show
)中的默认指令集外,Vue 还允许您注册自己的自定义指令。请注意,在 Vue 2.0 中,代码重用和抽象的主要形式是组件 - 但是在某些情况下,您需要对普通元素进行低级别的 DOM 访问,这也是自定义指令仍然有用的地方。一个例子就是关注一个输入元素,就像这样:
当页面加载时,该元素获得焦点(注意:自动对焦在移动 Safari 上不起作用)。事实上,如果您在访问此页面后没有点击其他任何内容,上面的输入应该现在集中。现在我们来构建完成这个的指令:
// Register a global custom directive called v-focus
Vue.directive('focus', {
// When the bound element is inserted into the DOM...
inserted: function (el) {
// Focus the element
el.focus()
}
})
如果您想在本地注册指令,组件也会接受一个 directives
选项:
directives: {
focus: {
// directive definition
inserted: function (el) {
el.focus()
}
}
}
然后在模板中,可以v-focus
在任何元素上使用新属性,如下所示:
<input v-focus>
Hook功能
指令定义对象可以提供多种钩子函数(全部可选):
-
bind
:仅在指令首次绑定到元素时才调用一次。这是您可以进行一次性安装工作的地方。 -
inserted
:在绑定元素已经插入到其父节点时调用(这只能保证父节点的存在,不一定在文档中)。 -
update
:在包含组件的 VNode 更新后调用,但可能在其子组件更新之前调用。该指令的值可能也可能没有改变,但可以通过比较绑定的当前值和旧值来避免不必要的更新(请参阅下面的挂钩参数)。 -
componentUpdated
:在包含组件的 VNode 和子项的 VNodes 更新后调用。 -
unbind
:仅当该指令从元素解除绑定时才调用一次。
我们将探讨传递到这些挂钩(即论点el
,binding
,vnode
,和oldVnode
)在下一节。
指令Hook参数
指令Hook传递了这些参数:
- el:指令所绑定的元素。这可以用来直接操作 DOM。
-
绑定:包含以下属性的对象。
-
名称:指令的名称,不带
v-
前缀。 -
value:传递给指令的值。例如
v-my-directive="1 + 1"
,价值会是2
。 -
oldValue:以前的值,仅在
update
和中可用componentUpdated
。无论值是否已更改,都可用。 -
表达式:作为字符串的绑定表达式。例如
v-my-directive="1 + 1"
,表达式就是"1 + 1"
。 -
arg:传递给指令的参数,如果有的话。例如
v-my-directive:foo
,arg就是"foo"
。 -
修饰符:包含修饰符的对象(如果有的话)。例如在
v-my-directive.foo.bar
,修饰符对象会{ foo: true, bar: true }
。
-
名称:指令的名称,不带
- vnode:由 Vue 编译器生成的虚拟节点。有关完整的详细信息,请参阅 VNode API。
-
oldVnode:前一个虚拟节点,仅在
update
和componentUpdated
钩子中可用。
除此之外el
,您应该将这些参数视为只读,并且不要修改它们。如果您需要通过钩子共享信息,建议通过元素的数据集来实现。
使用其中一些属性的自定义指令的示例:
<div id="hook-arguments-example" v-demo:foo.a.b="message"></div>
Vue.directive('demo', {
bind: function (el, binding, vnode) {
var s = JSON.stringify
el.innerHTML =
'name: ' + s(binding.name) + '<br>' +
'value: ' + s(binding.value) + '<br>' +
'expression: ' + s(binding.expression) + '<br>' +
'argument: ' + s(binding.arg) + '<br>' +
'modifiers: ' + s(binding.modifiers) + '<br>' +
'vnode keys: ' + Object.keys(vnode).join(', ')
}
})
new Vue({
el: '#hook-arguments-example',
data: {
message: 'hello!'
}
})
功能速记
在很多情况下,你可能希望在相同的行为bind
和update
,但不关心其他钩。例如:
Vue.directive('color-swatch', function (el, binding) {
el.style.backgroundColor = binding.value
})
对象文字
如果您的指令需要多个值,则还可以传入 JavaScript 对象文字。请记住,指令可以采用任何有效的 JavaScript 表达式。
<div v-demo="{ color: 'white', text: 'hello!' }"></div>
Vue.directive('demo', function (el, binding) {
console.log(binding.value.color) // => "white"
console.log(binding.value.text) // => "hello!"
})
指南 | Guide相关
Vue.js 是一个构建数据驱动的 web 界面的渐进式框架。Vue.js 的目标是通过尽可能简单的 API 实现响应的数据绑定和组合的视图组件。
主页 | https://vuejs.org/ |
源码 | https://github.com/vuejs/vue |
版本 | 2 |
发布版本 | 2.5.2 |