Guía

Directivas Personalizadas

Introducción

Además del conjunto predeterminado de directivas incluidas en el núcleo (v-model y v-show), Vue también le permite registrar sus propias directivas personalizadas. Note que en Vue 2.0, la forma primaria de reutilización y abstracción del código son los componentes; sin embargo, puede haber casos en los que necesite un acceso al bajo nivel al DOM en elementos simples, y aquí es donde las directivas personalizadas seguirían siendo útiles. Un ejemplo sería enfocarse en un elemento input, como este:

Cuando se carga la página, este elemento se enfoca (nota: el atributo nativo autofocus no funciona en Safari para dispositivos mobiles). De hecho, si no ha hecho clic en nada más desde que visitó esta página, el input de arriba debería estar enfocada ahora. Ahora vamos a construir la directiva que realiza esto:

// Registra una directiva personalizada global llamada `v-focus`
Vue.directive('focus', {
  // Cuando el elemento enlazado se inserta en el DOM...
  inserted: function (el) {
    // Enfoca el elemento
    el.focus()
  }
})

Si desea registrar una directiva localmente en lugar de lo anterior, los componentes también aceptan una opción directives:

directives: {
  focus: {
    // Definición de directiva
    inserted: function (el) {
      el.focus()
    }
  }
}

Luego, en un template, puede usar el nuevo atributo v-focus en cualquier elemento, como este:

<input v-focus>

Funciones Hook

Un objeto de definición de directiva puede proveer algunas funciones hook, todas opcionales:

Exploraremos los argumentos pasados en estas funciones hook (el, binding, vnode, and oldVnode) en la siguiente sección.

Argumentos en Hooks

Los siguientes argumentos se esperan en las funciones de hook de directivas:

Excepto el, usted debe tratar los otros argumentos como de sólo lectura y nunca modificarlos. Si necesita compartir información entre hooks, es aconsejable utilizar un atributo dataset.

Un ejemplo de una directiva personalizada que usa algunas de estas propiedades:

<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: 'Hola!'
  }
})

Forma Abreviada de Funciones

En muchos casos, es posible que desee el mismo comportamiento en bind y update, pero no se preocupe por los otros hooks. Por ejemplo:

Vue.directive('color-swatch', function (el, binding) {
  el.style.backgroundColor = binding.value
})

Objetos Literales

Si su directiva necesita varios valores, también puede pasar un objeto literal de JavaScript. Recuerde, las directivas pueden tomar cualquier expresión válida de JavaScript.

<div v-demo="{ color: 'white', text: 'Hola!' }"></div>
Vue.directive('demo', function (el, binding) {
  console.log(binding.value.color) // => "white"
  console.log(binding.value.text)  // => "Hola!"
})
← Mixins Funciones de renderizado & JSX →
¿Encontró un error o simplemente quiere contribuir con la documentación? Edite esta página en GitHub! Puesto en marcha en Netlify