Funcionalidad y Propósito de las Directivas Personalizadas en Vue.js

Vue.js ofrece un mecanismo potente para interactuar directamente con el DOM y encapsular lógica de bajo nivel mediante las directivas personalizadas. Mientras que las instancias o componentes de Vue se centran en el enlace de datos reactivo y la gestión del estado, las directivas son la herramienta óptima para ejecutar operaciones DOM directas y reutilizables.

¿Por qué emplear Directivas Personalizadas?

• Manipulación Directa del DOM: Son esenciales cuando se requiere una interacción específica con el DOM que no es cubierta por las directivas integradas de Vue o por su sistema de reactividad estándar. Esto abarca, por ejemplo, la integración de librerías de terceros que modifican el DOM, animaciones complejas o el manejo del enfoque de elementos.
• Reutilización de Lógica Específica: Cuando una operación DOM particular se repite con frecuencia o es intrincada, encapsularla dentro de una directiva personalizada permite su fácil reutilización en cualquier sección de la aplicación, lo que mejora la modularidad y la legibilidad del código.

Tipos de Declaración de Directivas

Dierctivas de Ámbito Global

Las directivas globales están disponibles en toda la aplicación Vue. Se registran en la instancia principal de Vue, habitualmente en el archivo main.js.

// Archivo: main.js
import Vue from 'vue'; // Importa la librería Vue
import App from './App.vue';

// Registro global de la directiva 'resaltar-fondo'
Vue.directive('resaltar-fondo', {
  /**
   * Se invoca una única vez, cuando la directiva se vincula al elemento.
   * Es el lugar idóneo para configurar listeners de eventos o realizar
   * preparativos iniciales que no requieran que el elemento esté en el DOM.
   * @param {HTMLElement} el Elemento DOM al que está enlazada la directiva.
   * @param {Object} binding Objeto con información del enlace (valor, modificadores, etc.).
   */
  bind(el, binding) {
    console.log('Directiva resaltar-fondo: bind - Elemento inicializado');
    // el.style.backgroundColor = binding.value || '#f0f0f0'; // Ejemplo: color de fondo por defecto
  },

  /**
   * Se ejecuta cuando el elemento enlazado ha sido insertado en el DOM padre.
   * Permite iniciar lógica que requiere que el elemento esté ya en el árbol de nodos.
   * @param {HTMLElement} el Elemento DOM.
   * @param {Object} binding Información del enlace.
   */
  inserted(el, binding) {
    console.log('Directiva resaltar-fondo: inserted - Elemento en el DOM');
    // Aplicar el color solo una vez al insertar
    if (binding.value) {
      el.style.backgroundColor = binding.value;
    }
  },

  /**
   * Se invoca antes de que el componente que contiene el elemento se actualice,
   * pero después de que los VNodes de la directiva se hayan actualizado.
   * Útil para reaccionar a cambios en el valor de la directiva.
   * @param {HTMLElement} el Elemento DOM.
   * @param {Object} binding Información del enlace (incluye oldValue).
   */
  update(el, binding) {
    console.log('Directiva resaltar-fondo: update - Valor de la directiva actualizado');
    if (binding.value !== binding.oldValue) {
      el.style.backgroundColor = binding.value;
    }
  },

  /**
   * Se invoca después de que el componente que contiene el elemento
   * y sus VNodes hijos se hayan actualizado completamente.
   * @param {HTMLElement} el Elemento DOM.
   * @param {Object} binding Información del enlace.
   */
  componentUpdated(el, binding) {
    console.log('Directiva resaltar-fondo: componentUpdated - Componente y VNodes hijos actualizados');
  },

  /**
   * Se invoca una única vez, cuando la directiva se desenlaza del elemento.
   * Es crucial para liberar recursos (como listeners de eventos) y prevenir fugas de memoria.
   * @param {HTMLElement} el Elemento DOM.
   */
  unbind(el) {
    console.log('Directiva resaltar-fondo: unbind - Limpieza de recursos');
    el.style.backgroundColor = ''; // Limpiar estilo
  }
});

// Inicializa la instancia de Vue
new Vue({
  el: '#app',
  render: h => h(App)
});

Directivas de Ámbito Local

Las directivas locales se definen dentro de las opciones de un componente específico, lo que restringe su disponibilidad únicamente a ese componente.

<template>
  <div>
    <h2>Ejemplo de Directiva Local: Estilizar Elementos</h2>
    <input type="text" v-estilizar:borde.grueso="'#FFD700'" placeholder="Borde dorado y grueso" />
    <p v-estilizar:texto.negrita="'#007bff'">Este párrafo tendrá texto azul y negrita.</p>
    <div v-estilizar="colorDinamico">Fondo con color dinámico: {{ colorDinamico }}</div>
    <button @click="cambiarColor">Alternar Color</button>
  </div>
</template>

<script>
export default {
  name: "ComponenteConDirectivaLocal",
  data() {
    return {
      colorDinamico: '#CCE5FF' // Azul claro inicial
    };
  },
  directives: {
    // Definición de la directiva 'estilizar'
    estilizar: { // Nombre de la directiva sin 'v-'
      /**
       * Método auxiliar para aplicar los estilos basado en los parámetros.
       * Se define como parte del objeto de la directiva para encapsular la lógica.
       */
      aplicarEstilos(element, binding) {
        const valor = binding.value || '#F8F9FA'; // Valor por defecto
        let propiedadCSS = 'background-color';
        let valorFuerza = ''; // Para 'important'

        // Evaluar argumento
        if (binding.arg === 'borde') {
          propiedadCSS = 'border';
          element.style.borderStyle = 'solid';
          element.style.borderWidth = '1px';
          element.style.borderColor = valor;
        } else if (binding.arg === 'texto') {
          propiedadCSS = 'color';
          element.style.color = valor;
        } else {
          // Si no hay argumento específico, aplicar al fondo
          element.style.backgroundColor = valor;
        }

        // Evaluar modificadores
        if (binding.modifiers.negrita) {
          element.style.fontWeight = 'bold';
        }
        if (binding.modifiers.subrayado) {
          element.style.textDecoration = 'underline';
        }
        if (binding.modifiers.grueso && binding.arg === 'borde') {
          element.style.borderWidth = '3px';
        }
        if (binding.modifiers.importante) {
          valorFuerza = 'important';
          // Para aplicar 'important' a la propiedad ya sea fondo, borde o texto
          if (binding.arg === 'borde') {
            element.style.setProperty('border-color', valor, valorFuerza);
          } else if (binding.arg === 'texto') {
            element.style.setProperty('color', valor, valorFuerza);
          } else {
            element.style.setProperty('background-color', valor, valorFuerza);
          }
        }
      },

      /**
       * Se ejecuta una vez al enlazar la directiva al elemento.
       * @param {HTMLElement} el El elemento DOM.
       * @param {Object} binding Objeto con información del enlace.
       */
      bind(el, binding) {
        console.log('Directiva estilizar: bind', binding);
        this.aplicarEstilos(el, binding);
      },

      /**
       * Se ejecuta después de que el elemento enlazado es insertado en el DOM.
       */
      inserted(el, binding) {
        console.log('Directiva estilizar: inserted', binding);
      },

      /**
       * Se ejecuta antes de que el VNode del componente contenedor se actualice.
       * Aquí se pueden actualizar los estilos si el valor de la directiva ha cambiado.
       */
      update(el, binding) {
        console.log('Directiva estilizar: update', binding);
        if (binding.value !== binding.oldValue || binding.arg !== binding.oldArg || JSON.stringify(binding.modifiers) !== JSON.stringify(binding.oldModifiers)) {
          this.aplicarEstilos(el, binding);
        }
      },

      /**
       * Se ejecuta después de que el componente contenedor y sus hijos se actualizan completamente.
       */
      componentUpdated(el, binding) {
        console.log('Directiva estilizar: componentUpdated', binding);
      },

      /**
       * Se ejecuta una vez al desenlazar la directiva del elemento.
       * Es el momento adecuado para limpiar los estilos o eventos asociados.
       */
      unbind(el) {
        console.log('Directiva estilizar: unbind');
        el.style.backgroundColor = '';
        el.style.color = '';
        el.style.border = '';
        el.style.fontWeight = '';
        el.style.textDecoration = '';
      }
    }
  },
  methods: {
    cambiarColor() {
      this.colorDinamico = this.colorDinamico === '#CCE5FF' ? '#D4EDDA' : '#CCE5FF'; // Alternar entre azul claro y verde claro
    }
  }
};
</script>

Ciclo de Vida de las Directivas (Hooks)

Una directiva personalizada puede definir una serie de funciones de "hook" que se ejecutan en distintas fases de su ciclo de vida, de manera análoga a los hooks del ciclo de vida de los componentes Vue:

• bind(el, binding, vnode, oldVnode): Invocado una única vez, al momento de que la directiva se vincula por primera vez al elemento. Ideal para la configuración inicial. Su analogía en componentes sería created, pero enfocado en el elemento DOM.
• inserted(el, binding, vnode, oldVnode): Invocado cuando el elemento enlazado ha sido insertado en el DOM padre (no garantiza que los hijos hayan finalizado su renderizado). Similar a mounted.
• update(el, binding, vnode, oldVnode): Invocado antes de que el VNode del componente contenedor se actualice, pero *después* de que los VNodes propios de la directiva se hayan actualizado. Permite actualizar la directiva si el valor asociado ha cambiado. Guarda similitud con updated, aunque con particularidades en el orden de actualización.
• componentUpdated(el, binding, vnode, oldVnode): Invocado después de que el VNode del componente contenedor y sus descendientes se hayan actualizado por completo. Útil para operaciones DOM que dependen de la total actualización del árbol.
• unbind(el, binding, vnode, oldVnode): Invocado una única vez, cuando la directiva se desenlaza del elemento. Es el momento adecuado para liberar cualquier evento o recurso para evitar fugas de memoria. Similar a beforeDestroy/unmounted.

Parámetros de los Hooks de Directivas

Todos los hooks de las directivas reciben los siguientes argumentos:

• el: El elemento DOM al cual la directiva está enlazada. Permite la manipulación directa de este elemento.
• binding: Un objeto que encapsula las siguientes propiedades:
  • name: El nombre de la directiva (sin el prefijo v-).
  • value: El valor actual pasado a la directiva. Por ejemplo, en v-mi-directiva="1 + 1", el valor es 2.
  • oldValue: El valor previo de la directiva. Disponible exclusivaemnte en los hooks update y componentUpdated, siendo útil para detectar cambios.
  • expression: La expresión original de la directiva como una cadena de texto. Por ejemplo, en v-mi-directiva="1 + 1", la expresión es "1 + 1".
  • arg: El argumento proporcionado a la directiva, si existe. Por ejemplo, en v-mi-directiva:foo, el argumento es "foo".
  • modifiers: Un objeto que contiene los modificadores de la directiva. Por ejemplo, en v-mi-directiva.foo.bar, el objeto de modificadores sería { foo: true, bar: true }.
• vnode: El nodo virtual (Virtual Node) generado por el compilador de Vue. (Para más detalles, consultar la API de VNode).
• oldVnode: El nodo virtual previo (solo disponible en los hooks update y componentUpdated).