useCountDown

Gestiona una cuenta regresiva con opciones para iniciar, detener y restablecer.

Carácteristicas

Ejecuta una función cuando el temporizador a finalizado.
Inicia la cuenta regresiva inmediatamente o manualmente.

Instalación

Instala el custom hook desde tu línea de comandos.

npm i @raddix/use-count-down

Uso

Ejemplo básico

Este ejemplo muestra cómo podrías configurar un temporizador para tu aplicación.

import { useCountDown } from '@raddix/use-count-down';

export function Timer() {
  const initialTime = 30 * 1000; // thirty seconds expressed in miliseconds
  const [count, actions] = useCountDown(initialTime, { autoStart: false });

  return (
    <section>
      <h1>Pomodoro Timer</h1>
      <div>
        <sub>Time left</sub>
        <p>{count}</p>
      </div>
      {count > 0 ? (
        <div>
          <button onClick={() => actions.start()}>Start</button>
          <button onClick={actions.stop}>Pause</button>
        </div>
      ) : (
        <div>
          <p>Time is over!</p>
          <button onClick={actions.reset}>Reset timer</button>
        </div>
      )}
    </section>
  );
}

Callbacks basados en el estado de la cuenta regresiva

Podrías configurar dos callbacks para ser llamados en ciertos estados de cuenta regresiva.

onFinished: Se llama cuando la cuenta regresiva llega a cero.
onTick: Se llama en cada intervalo de la cuenta regresiva.

import { useCountDown } from '@raddix/use-count-down';

export function Modal() {
  const initialTime = 10 * 1000; // ten seconds expressed in miliseconds

  const exitPage = () => {
    /* ... */
  };

  const closeModal = () => {
    /* ... */
  };

  const [count] = useCountDown(initialTime, { onFinished: exitPage });

  return (
    <div>
      <p>Are you sure you want to exit?</p>
      <div>
        <button onClick={exitPage}>Yes, exit</button>
        <button onClick={closeModal}>No, stay here</button>
      </div>
      <sub>Exiting in {count}...</sub>
    </div>
  );
}

API

Valor de retorno

Devuelve un arreglo que puede ser desestructurado en dos variables: count y actions. Estos son nombres de referencia, ya que puedes nombrarlos a tu preferencia.

Índice	Descripción	Tipo
0 (count)	Valor actual del temporizador de cuenta regresiva. Se detiene cuando llega a 0.	number
1 (actions)	Objeto que contiene métodos de manipulación del temporizador.	Object

Funciones dentro de Actions

Nombre	Descripción	Tipo
start	Inicia el temporizador si está detenido o configurado con `autoStart: false`. Opcionalmente se puede definir un nuevo tiempo inicial pasándolo como prop. Esto es útil si necesitas agregar otro segundo al temporizador.	function
stop	Detiene el temporizador.	function
reset	Reinicia el valor del temporizador a su estado inicial. Si el temporizador estaba configurado con `autoStart: true`, se activará inmediatamente.	function

Parámetros

El hook useCountDown acepta dos valores de inicialización.

Nombre	Descripción	Requerido	Tipo
initialTime	Valor inicial de la cuenta regresiva. Se expresa en milisegundos.	Sí	number
options	Objeto de configuración de la cuenta regresiva.	No	Object

Opciones de configuración

Nombre	Descripción	Requerido	Valor por defecto	Tipo
interval	Intervalo de tiempo para refrescar el valor de la cuenta regresiva. IMPORTANTE: Este intervalo no afecta la velocidad de la cuenta. Esto es útil si necesitas refrescar a una velocidad lenta (como 1 segundo) o rápida (como 10 ms).	No	1000	number
autoStart	Especifica si el temporizador se iniciará automáticamente después de configurarlo.	No	true	boolean
onFinished	Callback que se ejecuta cuando el valor de la cuenta llega a 0.	No	undefined	function
onTick	Callback que se ejecuta en cada actualización del valor de la cuenta.	No	undefined	function