Element: querySelectorAll() Methode

selectors

Ein String, der einen oder mehrere Selektoren enthält, die abgeglichen werden sollen. Dieser String muss ein gültiger CSS-Selektorstring sein; ist dies nicht der Fall, wird eine SyntaxError Ausnahme ausgelöst.

Beachten Sie, dass die HTML-Spezifikation nicht vorschreibt, dass Attributwerte gültige CSS-Bezeichner sein müssen. Wenn ein class oder id Attributwert kein gültiger CSS-Identifier ist, müssen Sie diesen vor der Verwendung in einem Selektor escapen, entweder indem Sie CSS.escape() auf den Wert anwenden oder eine der Techniken aus Escaping characters verwenden. Siehe Escaping attribute values für ein Beispiel.

Die Selektoren werden auf das gesamte Dokument angewendet, nicht nur auf das bestimmte 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 Selektor-Scope Beispiel.

Eine nicht-dynamische NodeList, die ein Element Objekt für jeden Nachkommensknoten enthält, der mindestens einem der angegebenen Selektoren entspricht. 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 ungültig ist.

In diesem Beispiel wird der Attributselektor verwendet, 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 in dem Element myBox enthalten sind:

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

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

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

Hier holen wir eine Liste der <p> Elemente des Dokuments, deren unmittelbares Elternelement ein <div> mit der Klasse "highlighted" ist und die sich in einem Container mit der ID "test" befinden.

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 Listeneinträge 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 übereinstimmenden Elemente zurückgegeben ist, 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 die Standard-Array-Notation verwenden, um auf die Inhalte 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 querySelectorAll() Methode 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 einzuschrä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 zunächst das #subject Element aus.

Wenn der #select Button gedrückt wird, rufen wir querySelectorAll() auf #subject auf und übergeben "#outer #inner" als Selektorstring.

Wenn der #select-scope Button gedrückt wird, rufen wir erneut querySelectorAll() auf #subject auf, aber diesmal übergeben wir ":scope #outer #inner" als Selektorstring.

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 "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 ist, es dennoch in der Auswahl verwendet wird, so dass unser #inner Element gefunden wird.

Wenn wir "Select with :scope" drücken, schränkt die :scope Pseudo-Klasse den Selektorenbereich auf #subject ein, sodass #outer nicht in der Selektorauswahl verwendet wird und wir das #inner Element nicht finden.

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, weil das "?" Zeichen nicht in CSS-Bezeichnern erlaubt ist.

Wir haben auch drei Buttons 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 Buttons versuchen bei einem Klick das <div> Element auszuwählen und dann die Hintergrundfarbe auf einen zufälligen Wert zu setzen.

• Der erste Button verwendet den Wert "this?element" direkt.
• Der zweite Button escapt den Wert mit CSS.escape().
• Der dritte Button escapt das "?" Zeichen ausdrücklich mit einem Backslash. Beachten Sie, dass wir auch den Backslash selbst durch einen weiteren Backslash escapen müssen, 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 den ersten Button ergibt einen Fehler, während der zweite und dritte Button korrekt funktionieren.

• DOM-Elemente mit Selektoren finden
• Attributselektoren im CSS Leitfaden
• Attributselektoren im MDN Learning Bereich
• Element.querySelector()
• Document.querySelector() und Document.querySelectorAll()
• DocumentFragment.querySelector() und DocumentFragment.querySelectorAll()