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

CKTIS / JavaScript

IdleDeadline: motivo da chamada e tempo de inatividade restante

`didTimeout` indica o motivo da chamada da função; `timeRemaining()` estima quantos milissegundos restam no período de inatividade atual.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

window.requestIdleCallback(callback);
window.requestIdleCallback(callback, { timeout: milliseconds });

// Inside callback(deadline), where deadline is an IdleDeadline:
deadline.didTimeout;        // read-only boolean property
deadline.timeRemaining();  // number of milliseconds, no arguments

O navegador passa um objeto IdleDeadline à função de retorno registada com window.requestIdleCallback(). Trata-se de uma API web de Window, não de uma funcionalidade do ECMAScript 2024. Não está disponível em Web Workers e o suporte varia consoante o navegador. Verifica se a API está disponível antes de a chamar.

deadline.didTimeout é uma propriedade booleana só de leitura. true indica que a função foi chamada porque terminou o prazo opcional timeout; false indica uma chamada durante um período de inatividade. Se o prazo terminar antes de a função ser executada, o navegador coloca na fila uma tarefa para a chamar. Isto não interrompe o código em execução nem garante um momento de início exato. Sem um prazo, a espera pode ser longa.

deadline.timeRemaining() não recebe argumentos e devolve uma estimativa não negativa do tempo de inatividade restante, em milissegundos que podem ser fracionários. Devolve 0 quando didTimeout === true, mas também pode devolver 0 quando didTimeout === false e o tempo disponível já se esgotou. A estimativa não é tempo de execução reservado nem uma contagem decrescente até ao timeout. Consulta-a durante a chamada atual, em vez de depender dela depois de um await.

Divide o trabalho em pequenas partes e verifica timeRemaining() > 0 antes de cada uma. Se a chamada se dever ao fim do prazo, executa no máximo uma pequena parte indispensável e agenda outra chamada para o restante trabalho. Uma condição de ciclo com || deadline.didTimeout pode esvaziar toda a fila mesmo sem tempo de inatividade disponível.

Exemplos

(() => {
  function logIdleStatus(host) {
    if (typeof host.requestIdleCallback !== 'function') {
      console.log('requestIdleCallback unavailable');
      return;
    }

    host.requestIdleCallback((deadline) => {
      const reason = deadline.didTimeout ? 'timeout' : 'idle';
      const budget = deadline.timeRemaining() > 0
        ? 'budget available'
        : 'no idle budget';
      console.log(`${reason}: ${budget}`);
    }, { timeout: 100 });
  }

  if (typeof window !== 'undefined') {
    logIdleStatus(window);
    return;
  }

  // Test doubles exercise the callback without browser scheduling.
  for (const [didTimeout, remaining] of [[false, 5], [false, 0], [true, 0]]) {
    logIdleStatus({
      requestIdleCallback(callback) {
        callback({ didTimeout, timeRemaining: () => remaining });
      },
    });
  }
  logIdleStatus({});
})();

Resultado

idle: budget available
idle: no idle budget
timeout: no idle budget
requestIdleCallback unavailable

Em Node.js, o exemplo apresenta as quatro linhas pela ordem indicada. Usa objetos de teste em vez de objetos `IdleDeadline` para os três primeiros casos e um objeto sem a API para o último. Isto não testa a forma como o navegador agenda as tarefas. Se colares o código na consola de programador de uma página do navegador, o programa apresenta apenas uma linha: uma das três primeiras de forma assíncrona se a API estiver disponível, ou logo a quarta se não estiver. Definir 100 ms não obriga a seguir o ramo de fim do prazo.

Lições relacionadas

  • JavaScript · Lição 6 · Avançado · Versão: 4

Fontes