jQuery / Método / .delay() - Adiar a próxima operação da fila de efeitos

No jQuery, .delay() adia operações posteriores de uma fila, normalmente a de efeitos. Não pausa uma função em execução nem interrompe todo o JavaScript. Um método que não usa essa fila pode executar imediatamente mesmo encadeado depois de .delay().

Identificar quais operações esperam

A documentação de .delay() define .delay(duration, queueName). duration é em milissegundos; sem queueName, a espera entra na fila de efeitos padrão fx. Uma fila guarda operações que serão executadas em sequência para aquele elemento. A espera começa quando o trabalho anterior termina e chega a vez do atraso.

.delay(800) acrescenta uma espera de 800 milissegundos. "fast" e "slow" representam 200 e 600 milissegundos, mas números deixam a comparação mais clara. O tempo anterior é separado: um efeito de 200 milissegundos termina antes de começar a espera adicional de 800 milissegundos.

Exemplo completo de show(0) e show()

Salve todo o código em UTF-8 como delay-demo.html e abra no navegador. É preciso internet para carregar a versão oficial completa do jQuery pela rede de distribuição de conteúdo, CDN; não é preciso instalar pacotes. Não use a versão slim, que exclui efeitos.

O código carrega 4.0.0. Espera na fila, exibição imediata, continuação do JavaScript, restauração durante a espera e cancelamento do temporizador nativo foram executados com 3.7.1 e 4.0.0. As duas caixas começam ocultas e cada botão de exibição controla uma caixa diferente.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Delay a queued effect, not JavaScript</title>
  <style>
    body { font: 16px/1.6 sans-serif; margin: 24px; }
    .box { display: none; padding: 16px; margin: 12px 0; background: #e4f2ef; }
    button, select { padding: 8px; margin: 4px; }
  </style>
  <script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
</head>
<body>
  <h1>Delay a queued effect, not JavaScript</h1>
  <label for="wait">Wait:</label>
  <select id="wait"><option value="800">800 ms</option><option value="200">200 ms</option></select>
  <button type="button" id="run">Queued show(0)</button>
  <button type="button" id="trap">Immediate show()</button>
  <button type="button" id="reset">Reset</button>
  <div class="box" id="queued">A queued display operation</div>
  <div class="box" id="plain">An immediate display operation</div>
  <p>Queue phase: <span id="phase">ready</span></p>
  <p id="continued"></p>
  <p id="result" aria-live="polite"></p>
  <script>
    $(function () {
      const $queued = $("#queued");
      const $plain = $("#plain");
      let busy = false;
      function report() {
        const queued = $queued.is(":visible") ? "visible" : "hidden";
        const plain = $plain.is(":visible") ? "visible" : "hidden";
        $("#result").text(`queued=${queued} | plain=${plain}`);
      }
      $("#run").on("click", function () {
        if (busy) return;
        busy = true;
        $("#phase").text("waiting");
        $queued.stop(true, false).hide()
          .delay(Number($("#wait").val()))
          .show(0, function () {
            busy = false;
            $("#phase").text("done");
            report();
          });
        $("#continued").text("Script continues immediately");
        report();
      });
      $("#trap").on("click", function () {
        $plain.stop(true, false).hide()
          .delay(Number($("#wait").val())).show();
        report();
      });
      $("#reset").on("click", function () {
        $queued.add($plain).stop(true, false).hide();
        busy = false;
        $("#phase").text("ready");
        $("#continued").text("");
        report();
      });
      report();
    });
  </script>
</body>
</html>

Resultado inicial:

queued=hidden | plain=hidden

1. Mantenha Wait em 800 ms e pressione Queued show(0). Queue phase mostra waiting e a primeira caixa continua oculta.
2. Script continues immediately aparece logo: .delay() não bloqueou o JavaScript seguinte.
3. Depois da espera, a primeira caixa aparece, phase muda para done e o resultado para queued=visible | plain=hidden.
4. Pressione Reset e depois Immediate show(). A segunda caixa aparece sem esperar, com queued=hidden | plain=visible. .show() sem argumentos executa fora da fila.
5. Restaure novamente, escolha 200 ms e execute Queued show(0) para uma espera menor.
6. Durante a espera de 800 ms, pressione Reset. Ambas ficam ocultas e phase volta a ready. A primeira não reaparece após o prazo original.

O zero de .show(0) é a duração do efeito de exibição depois que chega sua vez, não cancela a espera anterior. .show() imediato e .show(0) colocado na fila têm comportamentos diferentes.

Gerenciar nomes de filas e restauração

.queue() gerencia a fila de trabalho de um elemento. Com um nome personalizado, use o mesmo para a espera e o trabalho seguinte. Não suponha início automático: inicie a fila explicitamente, por exemplo com .dequeue("work").

Reset usa .stop(true, false) para limpar a fila de efeitos deste exemplo e interromper seu andamento atual. Nas duas versões testadas, restaurar durante a espera impediu a exibição prevista. .delay() não devolve um ID de temporizador nativo nem um identificador independente de cancelamento; não serve para agendar e cancelar qualquer tarefa JavaScript em geral.

.clearQueue() remove entradas ainda pendentes. Remover trabalho futuro e interromper trabalho em andamento são operações diferentes. O exemplo restaura apenas suas duas caixas; busy ignora pedidos adicionais de Queued show(0) durante a execução para não acumular esperas.

Usar temporizadores para funções comuns

Para trabalho sem relação com a fila de animação, agende a função com setTimeout(). Guarde o ID devolvido e passe para clearTimeout() quando precisar cancelar. Execute este trecho completo no Console das ferramentas de desenvolvimento: later, previsto para 800 milissegundos, é cancelado e somente cancelled aparece.

const timer = setTimeout(() => console.log("later"), 800);
clearTimeout(timer);
console.log("cancelled");

cancelled

Tempos de temporizadores e filas de efeitos não garantem um instante exato de execução. Outras tarefas do navegador e o estado da aba podem atrasá-la. Vincule etapas importantes à conclusão real em vez de estimar uma espera fixa.

Se um método parece não esperar, confira se usa fila e se elemento e nome correspondem. Se a caixa não aparecer, verifique seleção e alvo existente, início da fila personalizada, carregamento do jQuery completo em Network e erros no Console.