Eventos

Diferencias entre usar window y document {#differences-window-document}

La diferencia principal entre registrar eventos en window y en document radica en el ámbito de captura del evento.

Sabiendo como se diferencian, tenemos que tener claro lo siguiente de manera resumida sobre la captura de eventos aplicándolo al uso del ratón como ejemplo:

• A nivel global: Movimiento del ratón en cualquier parte de la ventana del navegador, puedes registrarlos en window.
• Dentro del contenido específico de nuestro documento HTML: Se pueden registar en document o en elementos HTML individuales utilizando sus identificadores, clases o selectores.

Es más eficiente y preciso registrar eventos en elementos específicos del documento utilizando document o seleccionando elementos por su ID, clase o selector.

Ventajas de emplear document:

• Mayor control sobre qué elementos van a estar escuchando los eventos y así podremos garantizar que esa lógica asociada al evento se ejecutará en la situación/es que deseamos.
• Reducción de la posibilidad de conflictos o interferencias con otros eventos o funcionalidades en tu aplicación.
• Si solo necesitas capturar eventos en un área específica de tu página web, no es necesario escuchar eventos a nivel global en todo el window.

Por lo tanto, es una buena práctica utilizar document o seleccionar elementos específicos para registrar eventos, ya que te proporciona mayor control y seguridad en cuanto a dónde se ejecutará la lógica relacionada con los eventos.

Casos en los que se podría usar window {#when-use-window}

El objeto window es útil para registrar eventos que deben ser capturados a nivel global en toda la ventana del navegador. A continuación, os proporciono algunos casos en los que podríamos utilizar window para registrar eventos:

1. Eventos de redimensionamiento de ventana (resize): Puedes utilizar window para capturar eventos como resize, que se disparan cuando el usuario cambia el tamaño de la ventana del navegador. Esto puede ser útil si necesitas ajustar dinámicamente el diseño de tu página en función del tamaño de la ventana.

2. Eventos de desplazamiento (scroll): Puedes registrar eventos como scroll en window para detectar cuándo el usuario realiza un desplazamiento vertical u horizontal en la página. Esto puede ser útil si deseas implementar efectos o funcionalidades relacionadas con el desplazamiento.

3. Eventos de carga (load) y descarga (unload): Puedes utilizar window para registrar eventos como load y unload, que se disparan cuando se carga o se cierra la ventana del navegador. Estos eventos pueden ser útiles para realizar tareas específicas al cargar o cerrar una página, como enviar solicitudes de seguimiento o limpiar recursos.

4. Eventos de teclado global: Cuando necesitemos capturar eventos de teclado en toda la ventana, como keydown o keyup, podemos registrarlos en window. Útil para implementar atajos de teclado o funcionalidades de accesibilidad en nuestra aplicación.

En resumen, window es útil cuando queremos registrar eventos a nivel global en toda la ventana del navegador, como eventos de redimensionamiento, eventos de desplazamiento, eventos de carga o descarga, o eventos de teclado globales. En estos casos, no es necesario restringir el ámbito de captura del evento a elementos específicos como podrían ser campos de un formulario por ejemplo.

Introducción

Los eventos en Qwik son los mismos, pero la forma en la que hacemos su llamada es mediante el registro de las funciones de devolución de llamada en la plantilla JSX.

Los manejadores de eventos (Event handlers) se van a registrar utilizando el atributo on{NombreDelEvento}$.

Por ejemplo, se utiliza el atributo onClick$ para escuchar los eventos de click. Formándose de la siguiente forma:

• on: Para especificar que se va a crear una acción.
• Evento que se formará en el tipo de notación PascalCase, por ejemplo si tenemos first name, será FirstName y en el caso de click asignaremos como Click.
• $: Para especificar el final del evento en Qwik. Esto va a indicar tanto el Optimizador de Qwik como al desarrollador de que ocurre una transformación especial en esta ubicación. La presencia del sufijo $ implica un límite cargado de forma diferida aquí. El código asociado con el manejador de click no se cargará en la VM (Máquina virtual) de JavaScript hasta que el usuario active el evento de click; sin embargo, se cargará en la caché del navegador de forma anticipada para no causar retrasos en las primeras interacciones.

Por lo tanto, esto es lo que tenemos que tener en cuenta:

• click: on + Click + $ => onClick$

Junto con otros ejemplos:

• mouseenter: on + MouseEnter + $ => onMouseEnter$
• mouseleave: on + MouseLeave + $ => onMouseLeave$
• copy: on + Copy + $ => onCopy$
• keydown: on + KeyDown + $ => onKeyDown$

Anteriormente, ya hemos visto algún caso como el manejo de la acción del click para forzar cambios de estado y otros ejemplos.

Con esta pequeña introducción vamos a empezar a profundizar con las diferentes formas y variantes que tenemos para trabajar con los eventos en Qwik.

Inline handler - Manejador en línea

El manejador en línea será cuando realicemos el registro del evento mediante un atributo que queramos usar dentro del código JSX, donde ejecutaremos una función para emplear la acción deseada:

Trabajando con el evento click, dentro de un elemento <button> mediante el atributo onClick$ deberemos de implementarlo de la siguiente forma:

import { component$, useSignal } from '@builder.io/qwik';
 
export default component$(() => {
  const count = useSignal(0);

  return (
    <button onClick$={() => count.value++}>Incrementar: {count.value}</button>
  );
});

Y como se puede observar, dentro de onClick$ registrado desde el elemento <button> se debe ejecutar una devolución de llamada () => count.value++ cada vez que se dispara el evento de click en este <button>.

Y el siguiente código, lo podremos visualizar de la siguiente forma:

Haciendo 3 clicks sobre la acción onClick$ debería de sumar 3 unidades, quedando 3 como resultado:

Reutilización de manejadores de eventos

Si deseamos reutilizar el mismo manejador de eventos (por ejemplo la acción de click que hemos visto) para varios elementos o eventos, necesitamos importar $ de @builder.io/qwik y envolver el manejador de eventos en él con una función normal y corriente.

De esta manera, debemos extraer el manejador de eventos en un QRL y pasarlo al escuchador de eventos.

Imaginaros que tenemos una función increment donde vamos a realizar el +1 del elemento contador tendríamos esta función:

  const increment = () => count.value++;

Que si la añadimos de esta forma:

import { component$, useSignal, $ } from '@builder.io/qwik';
 
export default component$(() => {
  const count = useSignal(0);
  const increment = () => count.value++;
  return (
    <>
      <button onClick$={increment}>+1</button>
      <p>Valor actual: {count.value}</p>
    </>
  );
});

Nos va a dar un error como el siguiente, donde básicamente dice que debemos de englobarlo dentro de esa función $ para poder cargarlo de manera diferida (Lazy Loading) cuando sea necesario por nuestra demanda al ejecutar el click del botón:

Por lo tanto, para hacer que funcione bien, debemos de englobarlo dentro de $:

import { ...,  $ } from '@builder.io/qwik';
...
  const increment = $(() => count.value++);
...

Y ahora si arrancará el elemento contador:

El funcionamiento será igual que el punto anterior, solo que ahora hemos conseguido desacoplar esa función del boton y podríamos llamar a ese código mediante otro boton ejecutando el evento onClick$ o cualquier otro como podría ser $onMouseEnter (o el que deseemos).

Ejemplo

Vamos a ver esto, añadiendo un nuevo botón y un elemento como un div, que si ponemos el cursor sobre ese elemento, incrementa el valor del contador.

El código:

import { component$, useSignal, $ } from '@builder.io/qwik';
 
export default component$(() => {
  const count = useSignal(0);
  const increment = $(() => count.value++);
  return (
    <>
      <button onClick$={increment}>+1</button>
      <button onClick$={increment}>+1 (Botón 2)</button>
      <div
        onMouseEnter$={increment}
        style='height: 100px; width: 400px; background-color: blue'
      >
        Poner el cursor del ratón sobre el cuadro azul para hacer + 1
      </div>
      <p>Valor actual: {count.value}</p>
    </>
  );
});

Al cargarlo:

Incrementará +1 siempre que hagamos lo siguiente:

• click en Increment o Increment (Button 2).
• Mover el cursor dentro del rectángulo azul, cuyo evento que se ejecutará será mouseenter

Probad haciendo diferentes variantes clickando, introduciendo el cursor sobre el rectángulo,... y veréis como se va incrementando el valor del contador.

Prevent default

Debido a que el manejo de eventos es asíncrono, no podemos usar event.preventDefault() de esta manera.

¿Y cómo lo podemos hacer? Para resolver esto, Qwik introduce una forma declarativa de prevenir el comportamiento predeterminado a través del atributo preventdefault:{nombreDelEvento} donde nombreDelEvento como bien sabéis puede ser cualquier evento visto anteriormente como click, mousedown, dblclick,...

Si el evento es click debemos de introducir preventdefault:click.

Aplicándolo en el código, con un evento click:

import { component$ } from '@builder.io/qwik';
 
export default component$(() => {
  return (
      <a
      href="/about"
      preventdefault:click // Esto evitará el comportamiento de "click" en este caso, que sería navegar a "/about" después de mostrar la alerta de `onClick$`.
      onClick$={() => {
        alert('Haz algo más para simular la navegación...No podemos hacer nada debido a "preventdefault:click"');
      }}
      >
        Navegar a la página "about"
      </a>
  );
});

Guardamos y esto es lo que tenemos, donde se ve un enlace normal y corriente visualmente, pero no en cuanto a funcionalidad:

Si intentamos realizar la acción de click, lo que hará es mostrar el mensaje de alerta:

Una vez cerrado (con Aceptar), se queda sin realizar ninguna acción más, que lo normal sería que navegase a la ruta /about (con el código especificado no lo hace porque lo bloquea).

Probad a quitar preventdefault:click y ejecutad la acción del click, ya veréis como muestra el mensaje y al cerrar esa alerta nos llevará a la ruta /about.

Objetivo del evento (Event target)

Debido a que el manejo de eventos es asíncrono, no podremos usar event.currentTarget.

¿Cómo solucionamos esto en Qwik? No os preocupéis, Qwik resuelve esto proporcionando como segundo argumento el elemento currentTarget, después del Event Object (Objeto del evento) visto anteriormente.

Se implementa de la siguiente forma aplicando el método onClick$:

...
  onClick$={(event: MouseEvent, currentTarget) => {
    currentElement.value = currentTarget; // este será el valor
    targetElement.value = event.target as HTMLElement;
  }}
...

En este caso, siempre que hagamos click en un elemento HTML que contiene el manejador de eventos (por ejemplo onClick$), siempre devolverá en el currentTarget el valor de su selector.

Por ejemplo, si lo añadiesemos dentro de un elemento <section></section> siempre que hagamos click sobre ese elemento, independientemente de si lo hacemos en un lado, el medio, arriba o donde sea, que si es dentro de ese elemento, el valor currentTarget se corresponderá a <section></section>.

Y aquí un ejemplo donde estamos trabajando con el objetivo del evento, asignándolo en el elemento <section></section> y donde vamos a ir obteniendo la información del elemento que hemos hecho click:

import { component$, useSignal } from '@builder.io/qwik';

export default component$(() => {
  const targetElement = useSignal<HTMLElement>();
  const currentElement = useSignal<HTMLElement>();
  return (
    <section
      onClick$={(event, currentTarget) => {
        currentElement.value = currentTarget;
        targetElement.value = event.target as HTMLElement;
      }}
    >
      Haga clic en cualquier texto <code>target</code> y{' '}
      <code>currentElement</code> del evento por ser donde se realiza el click siempre.
      <hr />
      <p>
        ¡Hola <b>Mundo</b>!
      </p>
      <hr />
      <ul>
        <li>
          Elemento actual (Current Element): {currentElement.value?.tagName}
        </li>
        <li>
          Elemento objetivo (Target Element): {targetElement.value?.tagName}
        </li>
      </ul>
    </section>
  );
});

A tener en cuenta: currentTarget en el DOM apunta al elemento al que se adjuntó el escuchador de eventos (en este caso a onClick$).

En el ejemplo anterior, siempre será el elemento SECTION por lo que prácticamente en todo momento el valor de currentTarget va a estar asignado con SECTION al valor del estado currentElement.

En cambio, el resultado del valor target irá cambiando independientemente de donde hagamos la acción (en este caso click).

La apariencia inicial es la siguiente:

Aquí nos muestra la información del elemento al que se ha hecho click.

Ejemplos:

• Click dentro de section y click en el texto Mundo que está en negrita:

Al hacer click aquí, el resultado del currentTarget será section (reflejado en la pantalla como valor de currentElement) y el target (reflejado como target), el elemento objetivo donde se ha realizado ese click será b.

Esto se refleja teniendo en cuenta esta información añadida en el código anterior:

<p>¡Hola <b>Mundo</b>!</p>

• Click dentro de section y click en el texto Hola:

Al hacer click aquí, el resultado del currentTarget será section también, manteniendo el valor anterior en la pantalla asignado a currentElement.

Esto, como se ha mencionado, es por estar dentro de este elemento donde se registra el manejador de eventos y el target (reflejado en target), el elemento objetivo donde se ha realizado ese click será p.

Esto se refleja teniendo en cuenta esta información añadida:

<p>¡Hola <b>Mundo</b>!</p>

Podéis curiosear haciendo click en diferentes apartados como los que corresponden a los selectores li, hr,... Os invito a que los probéis y veréis que el valor reflejado en currentElement, en este caso, siempre será SECTION y targetElement irá modificándose.

Manejo de eventos síncronos (Synchronous event handling)

En algunos casos, es necesario manejar un evento de manera tradicional porque algunas APIs deben utilizarse de manera síncrona.

Por ejemplo, el evento dragstart debe procesarse de manera síncrona y, por lo tanto, no se puede combinar con la ejecución de código diferida de Qwik.

Para hacer esto, podemos aprovechar el hook useVisibleTask (recordad que tenemos todo al detalle en el capítulo Ciclos de vida) para agregar de manera programática un escuchador de eventos utilizando directamente la API del DOM.

import { component$, useSignal, useVisibleTask$ } from '@builder.io/qwik';
 
export const SynchronousEventHandling = component$(() => {
  // 1.- Aquí tratamos la referencia del elemento HTML para el arrastre
  const draggableRef = useSignal<HTMLElement>();
  // 2.- Almacaremos el valor del estado del arrastre (dragstart / dragend)
  const dragStatus = useSignal(
    'A la espera de arrastrar para cambiar de estado'
  );

  useVisibleTask$(({ cleanup }) => {
    if (draggableRef.value) {
      // 3.- Usamos la API de DOM para añadir el escuchador de eventos (event listener).
      const dragstart = () => (dragStatus.value = 'dragstart (Arrastrando)');
      const dragend = () =>
        (dragStatus.value = 'dragend (Arrastre finalizado)');

      // 4.- Registro de los eventos
      draggableRef.value!.addEventListener('dragstart', dragstart);
      draggableRef.value!.addEventListener('dragend', dragend);

      // 5.- Limpiamos
      cleanup(() => {
        draggableRef.value!.removeEventListener('dragstart', dragstart);
        draggableRef.value!.removeEventListener('dragend', dragend);
      });
    }
  });

  return (
    <div>
      <button draggable ref={draggableRef}>
        {dragStatus.value === 'dragstart (Arrastrando)' ? 'Arrastrando :)' : '¡¡Arrastrame!!'}
      </button>
      <p>{dragStatus.value}</p>
    </div>
  );
});

Y así se visualizará:

Si empezamos a arrastrar haciendo click sobre el botón (y manteniendo para arrastrar):

• dragStatus.value = dragstart (Arrastrando)
• Texto del boton: Arrastrando :)

Y si soltamos, vuelve al estado original:

useOn

El hook useOn escucha eventos en el elemento raíz del componente. El primer parámetro es el nombre del evento que se desea escuchar. El segundo parámetro es una función que se ejecutará cuando se produzca el evento.

• click: Evento click dentro del componente, en su elemento raíz, que en este caso es un elemento p. Mostrará un mensaje alert con el texto Hello World siempre y cuando hagamos click dentro de ese elemento p que visualmente podremos verlo acotado con un borde sólido de color rojo.

import { component$, useOn, $, useStyles$} from '@builder.io/qwik';

export default component$(() => {
  useStyles$(
    `
      .useon {
        border: 2px solid red;
        height: 300px
      }
    `
  );
  useOn(
    'click',
    $(() => alert('Hola Mundo con useOn'))
  );

  return <p class='useon'>App Component. Haz click sobre mí.</p>;
});

Guardamos los cambios y esto es lo que se podemos ver:

Si hacemos clicks de las 3 formas indicadas solo en la 1 mostrará el mensaje del alert ya que la interacción se realiza únicamente en ese caso dentro de ese elemento p (que se delimita con el borde rojo), por lo que en los casos 2 y 3 no realizará esa acción.

useOnDocument

El hook useOnDocument escucha eventos en el documento. El primer parámetro es el nombre del evento que se desea escuchar. El segundo parámetro es una función que se ejecutará cuando se produzca el evento.

Uno de los eventos que podríamos usar dentro del elemento document fuera ya del elemento raíz de un componente podría ser el evento mousemove que se ejecuta cuando movemos el cursor del ratón dentro del elemento document. El siguiente código nos permitirá saber en todo momento mediante el movimiento del cursor del ratón en que posición se encuentra en los ejes x e y y con document.body tenemos las propiedades principales del documento, entre ellas la altura disponible mediante clientHeight siendo lo siguiente:

import { component$, $, useOnDocument, useStore } from '@builder.io/qwik';

export default component$(() => {
  const store = useStore({
    position: {
      x: 0,
      y: 0,
    },
  });

  useOnDocument(
    'mousemove',
    $((event) => {
      // Altura del cliente 
      // (la parte donde se muestran los contenidos)
      console.log('Height: ' + document.body.clientHeight);
      store.position.x = (event as MouseEvent).x;
      store.position.y = (event as MouseEvent).y;
    })
  );

  return (
    <div>
      <p>
        Mi posición actual [x, y]: [{store.position.x}, {store.position.y}]
      </p>
    </div>
  );
});

Al guardar los cambios y no introducir el cursor dentro de la aplicación, nos mostrará con los valores por defecto que sería la posición [x, y] = [0, 0]:

Si introducimos el cursor y apuntamos donde pone Mi posición actual, esto sería lo que visualizaremos:

useOnWindow

El hook useOnWindow escucha eventos en la ventana. El primer parámetro es el nombre del evento que se desea escuchar. El segundo parámetro es una función que se ejecutará cuando se produzca el evento.

Ejemplos básico usando resize donde vamos a tener en todo momento las propiedades de altura (height) y ancho (width) de la pantalla que irá actualizando a medida que hacemos más pequeños o más grande.:

import {
  component$,
  useOnWindow,
  $,
  useSignal,
  useVisibleTask$,
} from '@builder.io/qwik';

export default component$(() => {
  // 1.- Almacenamos el tamaño de la pantalla actual
  const actualScreenSize = useSignal({ x: 0, y: 0 });

  // 2.- Actualizar al estado que se encuentra la pantalla cuando inicia / redimensiona
  const updateScreenSize = $(() => {
    actualScreenSize.value = {
      x: window.innerWidth,
      y: window.innerHeight,
    };
  });

  // 3.- Al cargar, añadimos el tamaño inicial
  useVisibleTask$(() => {
    updateScreenSize();
  });

  // 4.- Redimensionando
  useOnWindow(
    'resize',
    $(() => {
      // Se ejecuta cuando la ventana se redimensiona
      updateScreenSize();
    })
  );

  // 5.- Se muestra
  return (
    <div>
      <h3>Redimensionar navegador para ver como se actualiza</h3>
      <p>
        Tamaño actual: {actualScreenSize.value.x}px (width) /{' '}
        {actualScreenSize.value.y}px (height)
      </p>
    </div>
  );
});

Actividad práctica - 1

Teniendo en cuenta el tamaño de la pantalla que estamos usando

Vamos a catalogar los tamaños siguiendo está tabla:

Sobre las medidas usadas

Estas medidas no son las exactas, son las que usamos para el ejercicio, para prácticar. Podéis usar otras si así lo creéis oportuno.

El resultado es el siguiente, espero que lo hayáis intentado:

import {
  component$,
  useOnWindow,
  $,
  useSignal,
  useVisibleTask$,
} from '@builder.io/qwik';

export default component$(() => {
  // 1.- Almacenamos el tamaño de la pantalla actual y tipo de pantalla
  const actualScreenSize = useSignal({ x: 0, y: 0 });
  const screenName = useSignal("---");

  // 2.- Actualizar al estado que se encuentra la pantalla cuando inicia / redimensiona
  const updateScreenSize = $(() => {
    actualScreenSize.value = {
      x: window.innerWidth,
      y: window.innerHeight,
    };
    
    // Actualizar que tamaño de pantalla tiene

    if ( actualScreenSize.value.x < 600 ) {
      screenName.value = "SMALL";
    } else if (actualScreenSize.value.x >= 600 && actualScreenSize.value.x < 1025 ) {
      screenName.value = "MEDIUM";
    } else {
      screenName.value = "LARGE";
    }
  });

  // 3.- Al cargar, añadimos el tamaño inicial
  (IGUAL)

  // 4.- Redimensionando
 (IGUAL)

  // 5.- Se muestra
  return (
    <div>
      <h3>Redimensionar navegador para ver como se actualiza</h3>
      <p>
        Tamaño actual: {actualScreenSize.value.x}px (width) /{' '}
        {actualScreenSize.value.y}px (height) / Tipo de pantalla: {screenName.value}
      </p>
    </div>
  );
});

Estado inicial con la pantalla al completo (eso puede variar dependiendo de vuestra pantalla):

Si vamos reduciendo el tamaño del navegador y pasamos a menos de 1025px y más de 600px de ancho:

Si ya hemos reducido a menos de 600px de ancho:

Una vez trabajado en esta actividad, esta es mi propuesta:

import {
  component$,
  useOnWindow,
  $,
  useSignal,
  useVisibleTask$,
} from '@builder.io/qwik';

export default component$(() => {
  // 1.- Almacenamos el tamaño de la pantalla actual con tipo de pantalla y número de actualizaciones
  const actualScreenSize = useSignal({ x: 0, y: 0 });
  const screenName = useSignal("---");
  const refreshCount = useSignal(0);

  // 2.- Actualizar al estado que se encuentra la pantalla cuando inicia / redimensiona
  const updateScreenSize = $(() => {
    actualScreenSize.value = {
      x: window.innerWidth,
      y: window.innerHeight,
    };

    // Cada vez que hacemos una actualización +1
    refreshCount.value += 1;

    // Actualizar que tamaño de pantalla tiene

    if ( actualScreenSize.value.x < 600 ) {
      screenName.value = "SMALL";
    } else if (actualScreenSize.value.x >= 600 && actualScreenSize.value.x < 1025 ) {
      screenName.value = "MEDIUM";
    } else {
      screenName.value = "LARGE";
    }
  });

  // 3.- Al cargar, añadimos el tamaño inicial
  useVisibleTask$(() => {
    updateScreenSize();
  });

  // 4.- Redimensionando
  useOnWindow(
    'resize',
    $(() => {
      // Se ejecuta cuando la ventana se redimensiona
      updateScreenSize();
    })
  );

  // 5.- Se muestra
  return (
    <div>
      <h3>Redimensionar navegador para ver como se actualiza</h3>
      <p>
        Tamaño actual: {actualScreenSize.value.x}px (width) /{' '}
        {actualScreenSize.value.y}px (height) / Tipo de pantalla: {screenName.value} / Actualizaciones de tamaño efectuadas: { refreshCount.value}
      </p>
    </div>
  );
});

La diferencia respecto al primero es que hemos añadido un elemento refreshCount con un useSignal para ir almacenando la cantidad de veces que se ejecuta el redimensionado y posteriormente se añade a la pantalla para ir viendo ese resultado: