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

CKTIS / JavaScript

Selecionar um descendente com querySelector() e alterar o seu conteúdo com innerHTML

Encontra o primeiro descendente que corresponde a um seletor CSS, trata a ausência de resultados e lê ou substitui a marcação do elemento selecionado.

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

Sintaxe

const target = root.querySelector(selectors);
if (target !== null) {
  const previousMarkup = target.innerHTML;
  target.innerHTML = markup;
}

Element.querySelector/innerHTML junta duas operações: encontrar um elemento e trabalhar com o seu conteúdo. root.querySelector(selectors) aceita uma cadeia de caracteres com um seletor CSS ou uma lista de seletores separados por vírgulas. Devolve o primeiro elemento descendente correspondente pela ordem da árvore DOM, independentemente da ordem dos seletores na lista. Nunca devolve o próprio root. Se não houver correspondência, devolve null; a sintaxe inválida do seletor lança uma DOMException chamada SyntaxError. Verifica o resultado antes de ler ou atribuir um valor a uma propriedade.

O resultado tem de estar abaixo de root, mas a avaliação do seletor pode ter em conta antepassados fora dessa subárvore. Usa :scope > .message para selecionar apenas filhos diretos de root com a classe message. Não é uma pesquisa em todo o documento como document.querySelector().

Ler target.innerHTML devolve o conteúdo serializado numa cadeia de caracteres, sem as etiquetas do próprio elemento nem as raízes do Shadow DOM. Uma atribuição analisa um fragmento no contexto do elemento e substitui os seus filhos, não o próprio elemento. Num elemento template, substitui antes o conteúdo do modelo. As referências guardadas e os ouvintes de eventos continuam associados aos nós antigos que foram desligados da árvore, não aos novos. Num documento XML, atribuir marcação mal formada lança SyntaxError; a leitura pode lançar InvalidStateError se a serialização XML falhar. Ambas são DOMException.

Não atribuas dados de origem não fidedigna diretamente a innerHTML: por omissão, a propriedade não higieniza a marcação e pode dar origem a XSS. Para texto simples, usa textContent. Se precisares de marcação de uma fonte não fidedigna, higieniza-a primeiro. Trusted Types não faz essa higienização por si só. Se o ambiente suportar Trusted Types e uma CSP os impuser, atribuir uma cadeia de caracteres normal sem uma política predefinida adequada lança TypeError. Passa antes um valor TrustedHTML produzido por uma política que higienize os dados.

Estas API pertencem à plataforma Web, não ao ECMAScript 2024. Confirma que o ambiente de execução disponibiliza um DOM e suporta os mecanismos de segurança necessários.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>querySelector() and innerHTML</title>
</head>
<body>
  <script>
    {
      const panel = document.createElement("div");
      panel.innerHTML = '<p class="message"><em>Before</em></p><p class="message">Unchanged</p>';

      const target = panel.querySelector(".message");
      if (target !== null) {
        const oldChild = target.firstElementChild;
        console.log(target.innerHTML);
        target.innerHTML = "<strong>After</strong>";
        console.log(target.innerHTML);
        console.log(oldChild.parentNode === null);
        console.log(target.nextElementSibling.textContent);
      }
      console.log(panel.querySelector(".missing") === null);
    }
  </script>
</body>
</html>

Resultado

<em>Before</em>
<strong>After</strong>
true
Unchanged
true

Guarda o exemplo num ficheiro `.html` e abre-o num navegador sem uma CSP que imponha Trusted Types. Consulta os resultados na consola do navegador. Só muda o primeiro elemento correspondente. O seu antigo filho já não tem nó pai, o segundo elemento mantém o texto `Unchanged` e a pesquisa sem correspondências devolve `null`.

Lições relacionadas

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

Fontes