非常教程

Vue 2参考手册

指南 | Guide

15. Custom Directives(自定义指令)

介绍

除了核心(v-modelv-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:仅当该指令从元素解除绑定时才调用一次。

我们将探讨传递到这些挂钩(即论点elbindingvnode,和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:前一个虚拟节点,仅在updatecomponentUpdated钩子中可用。

除此之外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!'
  }
})

功能速记

在很多情况下,你可能希望在相同的行为bindupdate,但不关心其他钩。例如:

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!"
})
Vue 2

Vue.js 是一个构建数据驱动的 web 界面的渐进式框架。Vue.js 的目标是通过尽可能简单的 API 实现响应的数据绑定和组合的视图组件。

主页 https://vuejs.org/
源码 https://github.com/vuejs/vue
版本 2
发布版本 2.5.2

Vue 2目录