Element: querySelectorAll() Methode

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 durch den Aufruf von CSS.escape() für den Wert oder durch eine der in Escaping characters beschriebenen Techniken. Siehe Escaping attribute values für ein Beispiel.

Die Selektoren werden auf das gesamte Dokument angewendet, nicht nur auf das spezielle Element, auf dem querySelectorAll() aufgerufen wird. Um den Selektor auf das Element zu beschränken, auf dem querySelectorAll() aufgerufen wird, fügen Sie die :scope Pseudo-Klasse am Anfang des Selektors hinzu. Siehe das Beispiel für den Selektorbereich.

Eine nicht-live NodeList, die ein Element-Objekt für jeden Nachkommensknoten enthält, der mit mindestens einem der angegebenen Selektoren übereinstimmt. Die Elemente sind in Dokumentreihenfolge – das heißt, Eltern vor Kindern, frühere Geschwister vor späteren Geschwistern.

SyntaxError DOMException

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

Dieses Beispiel verwendet den Attributselektor, um mehrere Elemente mit einem data-name Datenattribut auszuwählen, das "funnel-chart-percent" enthält.

<section class="box" id="sect1">
  <div data-name="funnel-chart-percent1">10.900%</div>
  <div data-name="funnel-chart-percent2">3700.00%</div>
  <div data-name="funnel-chart-percent3">0.00%</div>
</section>

const refs = [
  ...document.querySelectorAll(`[data-name*="funnel-chart-percent"]`),
];

Um eine NodeList aller <p>-Elemente zu erhalten, die im Element myBox enthalten sind:

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

Dieses Beispiel gibt eine Liste aller <div>-Elemente innerhalb myBox mit einer Klasse entweder note oder alert zurück:

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

Hier erhalten wir eine Liste der <p>-Elemente des Dokuments, deren unmittelbares Elternelement ein <div> mit der Klasse "highlighted" und das sich in einem Container mit der ID "test" befindet.

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 innerhalb 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']");

Sobald die NodeList der passenden Elemente zurückgegeben wird, können Sie sie wie ein Array untersuchen. Wenn das Array leer ist (d.h. 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 gängige Schleifenanweisung verwenden, wie zum Beispiel:

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

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

Die Methode querySelectorAll() wendet ihre Selektoren auf das gesamte Dokument an: sie sind nicht auf das Element beschränkt, auf dem die Methode aufgerufen wird. Um die Selektoren zu beschränken, fügen Sie die :scope Pseudo-Klasse am Anfang des Selektor-Strings hinzu.

HTML

In diesem Beispiel enthält das HTML:

• zwei Buttons: #select und #select-scope
• drei verschachtelte <div>-Elemente: #outer, #subject und #inner
• ein <pre>-Element, das das Beispiel für die Ausgabe verwendet.

<button id="select">Select</button>
<button id="select-scope">Select with :scope</button>

<div id="outer">
  #outer
  <div id="subject">
    #subject
    <div id="inner">#inner</div>
  </div>
</div>

<pre id="output"></pre>

div {
  margin: 0.5rem;
  padding: 0.5rem;
  border: 3px #20b2aa solid;
  border-radius: 5px;
  font-family: monospace;
}

pre,
button {
  margin: 0.5rem;
  padding: 0.5rem;
}

JavaScript

Im JavaScript wählen wir zuerst das #subject-Element aus.

Wenn die #select-Taste gedrückt wird, rufen wir querySelectorAll() auf #subject auf und übergeben "#outer #inner" als Selektor-String.

Wenn die #select-scope-Taste gedrückt wird, rufen wir erneut querySelectorAll() auf #subject auf, übergeben jedoch diesmal ":scope #outer #inner" als Selektor-String.

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

const select = document.querySelector("#select");
select.addEventListener("click", () => {
  const selected = subject.querySelectorAll("#outer #inner");
  output.textContent = `Selection count: ${selected.length}`;
});

const selectScope = document.querySelector("#select-scope");
selectScope.addEventListener("click", () => {
  const selected = subject.querySelectorAll(":scope #outer #inner");
  output.textContent = `Selection count: ${selected.length}`;
});

Ergebnis

Wenn wir auf "Select" drücken, wählt der Selektor alle Elemente mit einer ID von inner aus, die auch einen Vorfahren mit einer ID von outer haben. Beachten Sie, dass obwohl #outer außerhalb des #subject-Elements liegt, es dennoch in die Auswahl einbezogen wird, sodass unser #inner-Element gefunden wird.

Wenn wir auf "Select with :scope" drücken, beschränkt die :scope Pseudo-Klasse den Selektorbereich auf #subject, sodass #outer nicht in der Selektorabstimmung verwendet wird und das #inner-Element nicht gefunden wird.

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="container">
  <div id="this?element"></div>
</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 beim Klicken, das <div>-Element auszuwählen und dann seine Hintergrundfarbe auf einen zufälligen Wert zu setzen.

• Die erste Schaltfläche verwendet den "this?element"-Wert direkt.
• Die zweite Schaltfläche escapet den Wert mit CSS.escape().
• Die dritte Schaltfläche escapet explizit das "?'"-Zeichen mit einem Backslash. Beachten Sie, dass wir auch den Backslash selbst escapen müssen, indem wir einen weiteren Backslash verwenden, wie: "\\?".

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

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

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

  try {
    const elements = container.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 führt zu einem Fehler, während die zweite und dritte Schaltflächen ordnungsgemäß funktionieren.

• Auffinden von DOM-Elementen mit Selektoren
• Attributselektoren im CSS-Leitfaden
• Attributselektoren im MDN-Lernbereich
• Element.querySelector()
• Document.querySelector() und Document.querySelectorAll()
• DocumentFragment.querySelector() und DocumentFragment.querySelectorAll()