Dokument: querySelectorAll() Methode

Syntax

querySelectorAll(selectors)

Parameter

selectors

Ein String, der einen oder mehrere Selektoren zum Abgleichen enthält. Dieser String muss ein gültiger CSS-Selektor-String sein; wenn nicht, wird eine SyntaxError Ausnahme ausgelöst.

Beachten Sie, dass die HTML-Spezifikation nicht verlangt, dass Attributwerte gültige CSS-Bezeichner sind. Wenn ein class- oder id-Attributwert kein gültiger CSS-Bezeichner ist, müssen Sie ihn entweder durch Aufrufen von CSS.escape() auf den Wert oder durch eine der in Escaping characters beschriebenen Techniken im Selektor maskieren. Siehe Escaping attribute values für ein Beispiel.

Rückgabewert

Eine nicht-dynamische NodeList, die ein Element-Objekt für jedes Element enthält, das mit mindestens einem der angegebenen Selektoren übereinstimmt oder eine leere NodeList bei keinen Übereinstimmungen. Die Elemente sind in Dokumentenreihenfolge — das heißt, Eltern vor Kindern, frühere Geschwister vor späteren Geschwistern.

Ausnahmen

SyntaxError DOMException

Wird ausgelöst, wenn die Syntax des angegebenen selectors-Strings nicht gültig ist.

Beispiele

Erhalten einer Liste von Übereinstimmungen

Um eine NodeList von allen <p> Elementen im Dokument zu erhalten:

const matches = document.querySelectorAll("p");

Dieses Beispiel gibt eine Liste aller <div> Elemente im Dokument zurück, die die Klasse entweder note oder alert haben:

const matches = document.querySelectorAll("div.note, div.alert");

Hier erhalten wir eine Liste von <p> Elementen, deren unmittelbares Elternelement ein <div> mit der Klasse highlighted ist und die sich in einem Container befinden, dessen ID test ist.

const container = document.querySelector("#test");
const matches = container.querySelectorAll("div.highlighted > p");

Dieses Beispiel verwendet einen Attributselektor, um eine Liste der <iframe> Elemente im Dokument zurückzugeben, die ein Attribut mit dem Namen data-src enthalten:

const matches = document.querySelectorAll("iframe[data-src]");

Hier wird ein Attributselektor verwendet, um eine Liste der Listeneinträge zurückzugeben, die in einer Liste mit der ID user-list enthalten sind und ein data-active Attribut haben, dessen Wert 1 ist:

const container = document.querySelector("#user-list");
const matches = container.querySelectorAll("li[data-active='1']");

Zugriff auf die Übereinstimmungen

Sobald die NodeList der übereinstimmenden Elemente zurückgegeben wird, können Sie sie wie ein beliebiges Array untersuchen. Ist das Array leer (das heißt, seine length Eigenschaft ist 0), wurden keine Übereinstimmungen gefunden.

Andernfalls können Sie die Standard-Array-Notation verwenden, um auf den Inhalt der Liste zuzugreifen. Sie können jede übliche Schleifenanweisung verwenden, wie zum Beispiel:

const highlightedItems = userList.querySelectorAll(".highlighted");

highlightedItems.forEach((userItem) => {
  deleteUser(userItem);
});

Attributwerte maskieren

Dieses Beispiel zeigt, dass wir, wenn ein HTML-Dokument eine id enthält, die kein gültiger CSS-Bezeichner ist, den Attributwert maskieren müssen, bevor er in querySelectorAll() verwendet wird.

HTML

Im folgenden Code hat ein <div> Element eine id von "this?element", was kein gültiger CSS-Bezeichner ist, da das "?"-Zeichen in CSS-Bezeichnern nicht erlaubt ist.

Wir haben auch drei Buttons und ein <pre> Element zum Protokollieren von Fehlern.

<div id="this?element"></div>

<button id="no-escape">No escape</button>
<button id="css-escape">CSS.escape()</button>
<button id="manual-escape">Manual escape</button>

<pre id="log"></pre>

CSS

div {
  background-color: blue;
  margin: 1rem 0;
  height: 100px;
  width: 200px;
}

JavaScript

Alle drei Buttons versuchen, wenn sie geklickt werden, das <div> auszuwählen und dann seine Hintergrundfarbe auf einen zufälligen Wert zu setzen.

• Der erste Button verwendet den "this?element" Wert direkt.
• Der zweite Button maskiert den Wert mit CSS.escape().
• Der dritte Button maskiert das "?" Zeichen explizit mit einem Backslash. Beachten Sie, dass wir auch den Backslash selbst mit einem weiteren Backslash maskieren müssen, wie: "\\?".

const log = document.querySelector("#log");

function random(number) {
  return Math.floor(Math.random() * number);
}

function setBackgroundColor(id) {
  log.textContent = "";

  try {
    const elements = document.querySelectorAll(`#${id}`);
    const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`;
    elements[0].style.backgroundColor = randomColor;
  } catch (e) {
    log.textContent = e;
  }
}

document.querySelector("#no-escape").addEventListener("click", () => {
  setBackgroundColor("this?element");
});

document.querySelector("#css-escape").addEventListener("click", () => {
  setBackgroundColor(CSS.escape("this?element"));
});

document.querySelector("#manual-escape").addEventListener("click", () => {
  setBackgroundColor("this\\?element");
});

Ergebnis

Ein Klick auf den ersten Button erzeugt einen Fehler, während der zweite und dritte Button ordnungsgemäß funktionieren.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Selektion und Traversierung im DOM-Baum
• Attributselektoren im CSS-Leitfaden
• Attributselektoren im MDN Learning-Bereich
• Element.querySelector() und Element.querySelectorAll()
• Document.querySelector()
• DocumentFragment.querySelector() und DocumentFragment.querySelectorAll()