Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

setTimeout — agendar uma função uma única vez

setTimeout agenda uma função para ser executada uma única vez, sem bloquear o código atual. O atraso não garante um momento exato de execução, e o identificador devolvido permite cancelar a invocação pendente.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

const id = setTimeout(callback, delayMs, ...args);
clearTimeout(id);

setTimeout é uma API definida pelo HTML Standard para janelas e workers, não uma função do próprio ECMAScript. Agenda a invocação de uma função uma única vez; setInterval agenda repetições. Forneça uma função callback, um atraso delayMs em milissegundos e os args opcionais que serão passados à função. Passe uma função em vez de texto de código que exija compilação.

A chamada regressa sem esperar. Mesmo com um atraso de 0, o callback aguarda uma tarefa posterior do ciclo de eventos; não interrompe o código síncrono atual. O momento indicado não é garantido e a execução pode ocorrer mais tarde. Quando o nível de aninhamento do temporizador é superior a 5, os atrasos inferiores a 4 ms são elevados para 4 ms.

Ao agendar uma função, é devolvido um identificador inteiro positivo id. clearTimeout(id) cancela a invocação pendente no mesmo ambiente global. Não interrompe um callback que já esteja a ser executado.

O exemplo cancela um temporizador e passa "timer" como argumento a outro. O código síncrono acrescenta "end" antes de o callback do temporizador ser executado, pelo que o resultado esperado é start -> end -> timer. Verifique a ordem, não o tempo exato decorrido.

Exemplos

(() => {
  const events = ["start"];
  const id = setTimeout(() => events.push("cancelled"), 0);
  clearTimeout(id);

  setTimeout((message) => {
    events.push(message);
    console.log(events.join(" -> "));
  }, 0, "timer");

  events.push("end");
})();

Resultado

start -> end -> timer

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes