CKTIS / JavaScript
Element.querySelector() y Element.querySelectorAll()
Busca descendientes de un elemento con selectores CSS y elige entre la primera coincidencia y una lista estática con todas las coincidencias.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
element.querySelector(selectors) // Element | null
element.querySelectorAll(selectors) // static NodeList of Element objectsquerySelector() y querySelectorAll() son métodos de instancia de Element. Cada uno recibe una cadena con un selector CSS o una lista de selectores CSS separados por comas. querySelector() devuelve el primer elemento coincidente en el orden del documento, o null. querySelectorAll() devuelve una NodeList estática con todos los elementos coincidentes en ese mismo orden: los padres antes que sus descendientes y los hermanos anteriores antes que los posteriores. El orden de los selectores no da prioridad a ninguno y cada elemento aparece como máximo una vez. Si no hay coincidencias, la lista está vacía (length === 0).
Solo pueden devolverse descendientes del elemento sobre el que se llama al método, nunca el propio elemento. Aun así, la coincidencia puede depender de antepasados externos a ese subárbol. :scope se refiere al elemento sobre el que se llama al método, por lo que :scope > .item solo selecciona sus hijos directos con la clase item. Las consultas no atraviesan los límites del DOM en la sombra. Para buscar dentro, llama al método sobre un ShadowRoot accesible.
Una lista estática conserva sus entradas y el orden que tenían al hacer la consulta. Cambiar una clase o añadir, eliminar o mover un elemento no actualiza la lista. Sus entradas siguen apuntando a los objetos Element originales, no a copias. Repite la consulta para obtener un resultado actualizado y usa Array.from(list) si necesitas métodos de array.
Si la cadena del selector no es válida, ambos métodos lanzan una DOMException llamada SyntaxError; eso no equivale a no encontrar coincidencias. Los pseudoelementos de CSS como ::before no se devuelven como elementos del DOM. Para insertar un ID dinámico en un selector, usa "#" + CSS.escape(id) y escapa así el identificador CSS, no el selector entero ni HTML. Estos métodos son del DOM de la plataforma web, no de ECMAScript 2024. Comprueba la compatibilidad con el DOM y con los selectores en el entorno de destino.
Ejemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Element selector queries</title>
</head>
<body>
<script>
const frame = document.createElement("div");
frame.className = "frame";
const root = frame.appendChild(document.createElement("section"));
const direct = root.appendChild(document.createElement("p"));
const wrapper = root.appendChild(document.createElement("div"));
const nested = wrapper.appendChild(document.createElement("p"));
direct.className = nested.className = "item";
direct.textContent = "A";
nested.textContent = "B";
const snapshot = root.querySelectorAll(".frame .item");
console.log(root.querySelector(":scope > .item").textContent);
console.log(snapshot.length);
console.log(root.querySelectorAll(":scope > .item").length);
nested.remove();
console.log(`${snapshot.length} ${root.querySelectorAll(".frame .item").length}`);
</script>
</body>
</html>Resultado
A 2 1 2 1
Guarda el ejemplo como archivo HTML, ábrelo en un navegador y comprueba el resultado en la consola del navegador. `:scope > .item` solo encuentra `A`, mientras que `.frame .item` encuentra ambos párrafos gracias a un antepasado situado fuera de `root`. Tras eliminar `B`, la lista guardada sigue teniendo dos entradas, pero la nueva consulta devuelve una.
Lecciones relacionadas
- JavaScript · Lección 30 · Avanzado · Versión: 4