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

CKTIS / JavaScript

Node.contains() e Node.isConnected: subárvore ou documento

Usa `contains()` para verificar se um nó pertence a uma subárvore específica e `isConnected` para saber se está ligado a um documento.

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

Sintaxe

container.contains(otherNode) // boolean; otherNode is a required argument that accepts a Node or null
node.isConnected              // boolean; read-only property

container.contains(otherNode) devolve true se otherNode for o próprio container ou um dos seus descendentes diretos ou indiretos na árvore de nós. Também funciona numa subárvore desligada do documento. O argumento é obrigatório: null dá false, mas omitir o argumento ou passar uma cadeia de caracteres com um seletor provoca um TypeError.

node.isConnected é uma propriedade booleana só de leitura, não um método. Vale true se a raiz do nó, seguindo os eventuais anfitriões de Shadow DOM, for um Document. Não tem de ser o document atual, e o resultado não indica se o nó é visível. Ao desligar uma subárvore de um documento, isConnected passa a false para os seus nós sem alterar as relações dentro da subárvore.

contains() não atravessa a fronteira de Shadow DOM. Um nó numa árvore de sombra pode ter isConnected === true se o anfitrião estiver ligado a um documento, mesmo que host.contains(shadowChild) devolva false. Ambas são API do DOM da Web, não funcionalidades de ECMAScript 2024; a sua disponibilidade depende do ambiente de execução.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>DOM checks</title>
</head>
<body>
<script>
{
  const doc = document.implementation.createHTMLDocument("DOM checks");
  const host = doc.createElement("div");
  const child = doc.createElement("span");
  const shadow = host.attachShadow({ mode: "open" });
  const shadowChild = doc.createElement("span");
  host.appendChild(child);
  shadow.appendChild(shadowChild);

  const report = (label) => {
    console.log(`${label}: ${host.contains(child)} ${child.isConnected}`);
  };

  console.log(`self/null: ${host.contains(host)} ${host.contains(null)}`);
  report("before");
  doc.body.appendChild(host);
  report("attached");
  console.log(`shadow: ${host.contains(shadowChild)} ${shadow.contains(shadowChild)} ${shadowChild.isConnected}`);
  host.remove();
  report("detached");
}
</script>
</body>
</html>

Resultado

self/null: true false
before: true false
attached: true true
shadow: false true true
detached: true false

Guarda o exemplo como ficheiro HTML, abre-o num navegador e verifica a saída na consola de desenvolvimento. O exemplo cria um documento HTML separado e não altera a página aberta. Depois de removeres o anfitrião, `child` continua dentro dele, mas `child.isConnected` volta a ser `false`.

Lições relacionadas

  • JavaScript · Lição 40 · Intermédio · Versão: 3

Fontes