Dokument: querySelectorAll() Methode

Syntax

querySelectorAll(selectors)

Parameter

selectors

Ein String, der einen oder mehrere Selektoren enthält, die übereinstimmen sollen. Dieser String muss ein gültiger CSS-Selektor-String sein; falls 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 vor der Verwendung in einem Selektor escapen, entweder indem Sie CSS.escape() auf den Wert anwenden oder eine der Techniken verwenden, die in Zeichen escapen beschrieben sind. Siehe Attribute-Werte escapen für ein Beispiel.

Rückgabewert

Eine nicht-live NodeList, die für jedes Element, das mindestens einem der angegebenen Selektoren entspricht, ein Element-Objekt enthält, oder eine leere NodeList im Falle keiner Übereinstimmungen. Die Elemente sind in Dokumentreihenfolge — 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 ungültig ist.

Beispiele

Eine Liste von Übereinstimmungen erhalten

Um eine NodeList mit 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 eine 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 namens data-src enthalten:

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

Hier wird ein Attributselektor verwendet, um eine Liste der Listenelemente in einer Liste mit der ID user-list zurückzugeben, die ein data-active-Attribut mit dem Wert 1 haben:

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

Auf die Übereinstimmungen zugreifen

Sobald die NodeList der übereinstimmenden Elemente zurückgegeben wird, können Sie sie wie jedes Array untersuchen. Wenn das Array leer ist (d.h. seine length-Eigenschaft ist 0), wurden keine Übereinstimmungen gefunden.

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

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

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

Attributwerte escapen

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

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 Schaltflächen 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 Schaltflächen versuchen, wenn sie angeklickt werden, das <div> zu selektieren und dann seine Hintergrundfarbe auf einen zufälligen Wert zu setzen.

• Die erste Schaltfläche verwendet den Wert "this?element" direkt.
• Die zweite Schaltfläche escapt den Wert mit CSS.escape().
• Die dritte Schaltfläche escapt das "?"-Zeichen explizit mit einem Backslash. Beachten Sie, dass wir auch den Backslash selbst escapen müssen, indem wir einen weiteren Backslash verwenden, 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

Das Klicken auf die erste Schaltfläche ergibt einen Fehler, während die zweite und dritte Schaltfläche 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()