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

CKTIS / JavaScript

Os eventos DOMContentLoaded, hashchange, mouseover e focusin

Escolhe onde escutar a disponibilidade do DOM, a mudança de fragmento do URL, a entrada do ponteiro e o foco. Delega os eventos dos descendentes num contentor comum.

Versão: Current web platform; runtime support varies

Sintaxe

document.addEventListener("DOMContentLoaded", onReady, { once: true });
window.addEventListener("hashchange", onHashChange);
container.addEventListener("mouseover", onMouseOver);
container.addEventListener("focusin", onFocusIn);

Estes quatro eventos assinalam situações diferentes: disponibilidade do documento, navegação por fragmentos, movimento do ponteiro e mudança de foco. São API da plataforma Web. No campo de versão, ECMAScript 2024 refere-se apenas à linguagem JavaScript e não indica se estes eventos são suportados. Verifica o suporte nos navegadores de destino: um ambiente JavaScript, por si só, não garante a existência de um DOM.

Escuta DOMContentLoaded em document. O navegador dispara este Event não cancelável depois de analisar o HTML e executar os scripts clássicos com defer e os módulos sem async. Não espera por imagens nem por scripts async; as folhas de estilo podem atrasá-lo indiretamente se bloquearem um script. Se a inicialização só precisar do DOM já construído pelo analisador, regista um listener com { once: true } quando document.readyState === "loading"; caso contrário, inicializa de imediato. O estado "interactive" não prova que o evento já tenha ocorrido.

Escuta hashchange em window quando uma navegação alterar o fragmento do URL no mesmo documento, por exemplo ao atribuir um valor a location.hash. O HashChangeEvent contém os URL completos em oldURL e newURL. Chamar history.pushState() ou history.replaceState() não dispara, por si só, hashchange, mesmo que o fragmento mude.

mouseover é um MouseEvent disparado no elemento em que o ponteiro entra. Propaga-se para os antepassados, pelo que mover o ponteiro entre descendentes também pode ativar o listener do contentor. relatedTarget indica o elemento que o ponteiro deixou, ou vale null se não houver um alvo secundário. Para detetar apenas entradas a partir do exterior do contentor, escuta diretamente mouseenter, que não se propaga para os antepassados.

focusin é um FocusEvent não cancelável disparado quando um elemento recebe o foco, por exemplo ao premir Tab. Ao contrário de focus, focusin propaga-se para os antepassados. Ao delegar focusin ou mouseover numa árvore DOM normal, usa event.target para identificar o elemento afetado e event.currentTarget para identificar o contentor cujo listener está a ser executado.

Exemplos

(() => {
  const { document, window, HashChangeEvent, MouseEvent, FocusEvent } =
    typeof globalThis.document === "undefined" ? createNodeDemo() : globalThis;

  const container = document.createElement("div");
  const button = document.createElement("button");
  container.append(button);

  document.addEventListener("DOMContentLoaded", (event) => {
    console.log(`${event.type}: document=${event.target === document}`);
  }, { once: true });

  window.addEventListener("hashchange", (event) => {
    console.log(`${event.type}: ${new URL(event.oldURL).hash} -> ${new URL(event.newURL).hash}`);
  }, { once: true });

  for (const type of ["mouseover", "focusin"]) {
    container.addEventListener(type, (event) => {
      console.log(`${event.type}: button=${event.target === button}, container=${event.currentTarget === container}`);
    });
  }

  document.dispatchEvent(new Event("DOMContentLoaded", { bubbles: true }));
  window.dispatchEvent(new HashChangeEvent("hashchange", {
    oldURL: "https://example.com/#before",
    newURL: "https://example.com/#after",
  }));
  button.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
  button.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));

  // Node.js fallback: model only the detached tree and event data used here.
  function createNodeDemo() {
    class DemoElement extends EventTarget {
      parentNode = null;

      append(child) {
        child.parentNode = this;
      }

      dispatchEvent(event) {
        let current = this;
        Object.defineProperties(event, {
          target: { configurable: true, value: this },
          currentTarget: { configurable: true, get: () => current },
        });

        try {
          for (; current; current = current.parentNode) {
            EventTarget.prototype.dispatchEvent.call(current, event);
            if (!event.bubbles || event.cancelBubble) break;
          }
        } finally {
          current = null;
        }
        return !event.defaultPrevented;
      }
    }

    class DemoHashChangeEvent extends Event {
      constructor(type, { oldURL, newURL }) {
        super(type);
        this.oldURL = oldURL;
        this.newURL = newURL;
      }
    }

    return {
      document: Object.assign(new EventTarget(), {
        createElement: () => new DemoElement(),
      }),
      window: new EventTarget(),
      HashChangeEvent: DemoHashChangeEvent,
      MouseEvent: Event,
      FocusEvent: Event,
    };
  }
})();

Resultado

DOMContentLoaded: document=true
hashchange: #before -> #after
mouseover: button=true, container=true
focusin: button=true, container=true

Executa o código na consola do navegador em `about:blank` ou guarda-o como `main.js` e executa `node main.js`. O navegador usa o seu DOM nativo; em Node.js, o código usa um modelo simplificado da árvore e dos eventos, não um DOM. `dispatchEvent()` dispara eventos sintéticos de forma síncrona: não recarrega o documento, não altera o URL e não desloca o ponteiro nem o foco. As últimas duas linhas mostram a propagação do botão para um contentor que não está ligado ao documento.

Lições relacionadas

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

Fontes