Debouncing

Abrir en ChatGPT

25.11

Java API

El debouncing es una técnica que retrasa la ejecución de una acción hasta que haya transcurrido un tiempo especificado desde la última llamada. Cada nueva llamada restablece el temporizador. Esto es útil para escenarios como la búsqueda a medida que se escribe, donde se desea esperar hasta que el usuario se detenga antes de ejecutar una consulta de búsqueda.

Mostrar Código

Java

Uso básico

La clase Debouncer proporciona una forma simple de debounciar acciones. Crea un Debouncer con un retraso en segundos, luego llama a run() con la acción que deseas debounciar:

Debouncer debounce = new Debouncer(0.3f);

textField.onModify(e -> {
  debounce.run(() -> search(textField.getText()));
});

En este ejemplo, el método search() se llama solo después de que el usuario deja de escribir durante 300 milisegundos. Cada pulsación de tecla restablece el temporizador a través del evento onModify, por lo que escribir rápidamente no desencadenará múltiples búsquedas.

Cómo funciona

Cuando llamas a run() con una acción:

1. Si no hay ninguna acción pendiente, el Debouncer programa la acción para ejecutarse después del retraso.
2. Si ya hay una acción pendiente, la acción anterior se cancela y el temporizador se reinicia con la nueva acción.
3. Una vez que transcurre el retraso sin otra llamada, la acción se ejecuta.

El Debouncer se ejecuta en el hilo de la interfaz de usuario utilizando el mecanismo de Interval de webforJ, por lo que no necesitas envolver actualizaciones de UI en Environment.runLater().

Unidades de retraso

El parámetro de retraso utiliza segundos como unidad, no milisegundos. Usa 0.3f para 300 ms o 1.5f para 1.5 segundos.

Controlando la ejecución

Los siguientes métodos se pueden usar para manejar de manera más precisa la ejecución y el uso del Debouncer:

Cancelar una acción pendiente

Usa cancel() para detener la ejecución de una acción pendiente:

Debouncer debounce = new Debouncer(1f);

debounce.run(() -> saveDocument());

// El usuario navega antes de que se ejecute el guardado
debounce.cancel();

Cancelar debounces pendientes

Al igual que con los intervalos, es buena práctica cancelar acciones debounced pendientes cuando se destruye un componente. Esto previene fugas de memoria y evita errores por acciones ejecutándose en componentes destruidos:

public class SearchPanel extends Composite<Div> {
  private final Debouncer debounce = new Debouncer(0.3f);

  @Override
  protected void onDidDestroy() {
    debounce.cancel();
  }
}

Forzar la ejecución inmediata

Usa flush() para ejecutar una acción pendiente de inmediato:

Debouncer debounce = new Debouncer(0.5f);

textField.onModify(e -> {
  debounce.run(() -> validateInput(textField.getText()));
});

// Forzar validación antes de la presentación del formulario
submitButton.onClick(e -> {
  debounce.flush();
  if (isValid()) {
    submitForm();
  }
});

Comprobar el estado pendiente

Usa isPending() para verificar si una acción está a la espera de ejecución:

Debouncer debounce = new Debouncer(0.3f);

if (debounce.isPending()) {
  statusLabel.setText("Procesando...");
}

Debouncing a nivel de evento vs Debouncer

webforJ proporciona dos enfoques para el debouncing:

Característica	Debouncer	ElementEventOptions.setDebounce()
Alcance	Cualquier acción	Solo eventos de elementos
Ubicación	Lado del servidor	Lado del cliente
Unidad	Segundos (flotante)	Milisegundos (entero)
Flexibilidad	Control total con cancel/flush	Automático con evento

Usa Debouncer cuando necesites control programático sobre el debouncing, como cancelar o vaciar acciones pendientes. Usa ElementEventOptions cuando desees un debouncing simple del lado del cliente para eventos de elementos sin rondas adicionales al servidor.

// Usando ElementEventOptions para debouncing del lado del cliente
ElementEventOptions options = new ElementEventOptions();
options.setDebounce(300);

element.addEventListener("input", e -> {
  // Este manejador se debounce del lado del cliente
}, options);