APIs de HTML

Cada elemento na página é um objeto no DOM (Document Object Model). Interfaces HTML expõem propriedades e métodos que o JavaScript consulta ou altera — sem reinventar o parser.

O exemplo deste capítulo é 16-apis-de-html, no pacote que acompanha o volume. Leia → mude uma coisa → preveja → recarregue → confira.

O que você vai aprender

• Relacionar markup, DOM e árvore de acessibilidade (visão geral).
• Usar querySelector / querySelectorAll para achar nós.
• Ler propriedades tipadas (HTMLImageElement.alt, mídia, etc.).
• Distinguir atributo no HTML e propriedade no objeto.
• Fazer uma inspeção mínima no console ou no script do exemplo.

DOM em uma frase

O DOM é a árvore de nós do documento: elementos, atributos, texto. O navegador monta essa árvore a partir do HTML. Scripts leem e mudam nós; a tela atualiza.

A árvore de acessibilidade (AOM) deriva do DOM: é o que tecnologias assistivas usam para anunciar papéis, nomes e estados. Markup semântico bom alimenta as duas.

Selecionar e ler

const imagens = document.querySelectorAll("img");
imagens.forEach((img) => {
  console.log(img.alt);
});

img.alt vem da interface HTMLImageElement. Quase todo elemento tem interface própria herdando de HTMLElement / Element: âncoras, formulários, mídia, canvas, e assim por diante.

Estado ao vivo

Algumas propriedades refletem o layout ou o player agora, não só o atributo inicial. Exemplo com mídia: duração, tempo atual, se terminou. Exemplo de layout: offsetHeight de uma seção muda se a janela redimensionar.

const video = document.querySelector("video");
if (video) {
  console.log(video.duration, video.currentTime, video.ended);
}

Atributo versus propriedade

No HTML você escreve atributos. No DOM, muitas vezes há propriedade espelhada (id, href, value em campos). Nem sempre o nome é idêntico; e mudar a propriedade nem sempre atualiza o atributo da mesma forma. Para este volume: leia o que o objeto expõe e confira no inspetor.

Erro comum: achar que querySelector “copia” o HTML estático para sempre. Se o script alterar o DOM depois, a página muda — e seletores seguintes veem o novo estado.

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>APIs de HTML — Belavista</title>
  </head>
  <body>
    <main>
      <h1>Inspeção do cartaz</h1>
      <p id="status">Abrindo leitura das imagens…</p>
      <figure>
        <img id="cartaz" src="cartaz-aurora.jpg" alt="Cartaz Aurora vermelha" width="240" height="320">
        <figcaption>Exemplo para ler <code>alt</code> e dimensões via API.</figcaption>
      </figure>
      <button type="button" id="ler">Ler propriedades</button>
    </main>
    <script>
      const status = document.getElementById("status");
      const cartaz = document.getElementById("cartaz");
      document.getElementById("ler").addEventListener("click", () => {
        status.textContent =
          "alt=\"" + cartaz.alt + "\" · naturalWidth=" + cartaz.naturalWidth +
          " · complete=" + cartaz.complete;
      });
    </script>
  </body>
</html>

Clique no botão e confira o parágrafo. Mude o alt no HTML, recarregue e leia de novo.

Para onde isso vai

Formulários têm APIs de validação; dialog tem showModal/close (capítulo 20); elementos customizados usam o ciclo de vida que você viu no 15. O padrão é o mesmo: elemento → interface → métodos/propriedades.

Confira o exemplo completo

A captura mostra o exemplo desta etapa. Abra a pasta completa, mude uma coisa e confira no navegador antes de seguir.

Atividades

1. O que é o DOM em relação ao arquivo HTML?
2. Por que querySelectorAll("img") devolve uma lista e não um único nó?
3. Cite um exemplo de propriedade que muda com o estado da página, não só com o atributo inicial.

Respostas comentadas

1. É a representação em árvore de objetos que o navegador monta a partir do markup (e que scripts podem alterar).
2. Porque pode haver várias imagens; a API devolve uma coleção para percorrer.
3. Exemplos: currentTime de um vídeo, offsetHeight de uma seção, complete de uma imagem após o carregamento.

O arquivo completo

Referência do exemplo 16-apis-de-html, reproduzida aqui para que você possa conferir sem sair da página.

simulacao.js

const form=document.querySelector('form');
if(form){form.querySelector('[type=submit]').disabled=false;form.addEventListener('submit',e=>{e.preventDefault();const r=document.querySelector('#retorno');r.textContent='Simulação concluída. Nada foi enviado ou guardado. Use dados fictícios.';r.focus();});}