Element: 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 er es nicht ist, wird eine SyntaxError-Ausnahme ausgelöst.

Beachten Sie, dass die HTML-Spezifikation nicht verlangt, dass Attributwerte gültige CSS-Identifikatoren sind. Wenn ein class oder id Attributwert kein gültiger CSS-Identifikator ist, müssen Sie ihn entweder durch Aufrufen von CSS.escape() auf den Wert oder durch eine der in Escaping characters beschriebenen Techniken escapen, bevor Sie ihn in einem Selektor verwenden. 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, auf dem querySelectorAll() aufgerufen wird, zu beschränken, fügen Sie die :scope Pseudoklasse am Anfang des Selektors hinzu. Siehe das Beispiel Selektorbereich.

Rückgabewert

Eine nicht-live NodeList, die ein Element-Objekt für jeden Nachfahrenknoten enthält, der mindestens einem der angegebenen Selektoren entspricht. Die Elemente befinden sich 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

Alle Elemente mit einem benutzerdefinierten Datenwert abrufen

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"]`),
];

Eine Liste von Übereinstimmungen erhalten

Um eine NodeList von allen <p>-Elementen innerhalb des Elements myBox zu erhalten:

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

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

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" 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 Listenelemente in einer Liste zurückzugeben, deren ID "user-list" ist und die 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 ist, können Sie sie wie ein Array untersuchen. Wenn das Array leer ist (das heißt, 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 übliche Schleifenanweisung verwenden, wie z.B.:

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

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

Selektorbereich

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 zu beschränken, fügen Sie die :scope Pseudoklasse am Anfang des Selektor-Strings hinzu.

HTML

In diesem Beispiel enthält das HTML:

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

<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 lightseagreen 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 der #select Button gedrückt wird, rufen wir querySelectorAll() auf #subject auf und übergeben "#outer #inner" als Selektor-String.

Wenn der #select-scope Button gedrückt wird, rufen wir erneut querySelectorAll() auf #subject auf, diesmal übergeben wir jedoch ":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 "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 auch wenn #outer außerhalb des #subject Elements liegt, es trotzdem bei der Auswahl verwendet wird, sodass unser #inner Element gefunden wird.

Wenn wir "Select with :scope" drücken, beschränkt die :scope Pseudoklasse den Selektorenbereich auf #subject, sodass #outer bei der Selektorauswahl nicht verwendet wird und wir das #inner Element nicht finden.

Ärstellen von Attributwerten

Dieses Beispiel zeigt, dass wenn ein HTML-Dokument eine id enthält, die kein gültiger CSS-Identifikator 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", die kein gültiger CSS-Identifikator ist, weil das Zeichen "?" in CSS-Identifikatoren nicht 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, wenn geklickt, das <div> auszuwählen und dann seine Hintergrundfarbe auf einen zufälligen Wert zu setzen.

• Der erste Button verwendet den Wert "this?element" direkt.
• Der zweite Button escapet den Wert mithilfe von CSS.escape().
• Der dritte Button escapet das Zeichen "?" direkt mit einem Backslash. Beachten Sie, dass wir den Backslash selbst auch mittels eines weiteren Backslashes 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 führt zu einem Fehler, während die zweiten und dritten Buttons ordnungsgemäß funktionieren.

Spezifikationen

Browser-Kompatibilität

Siehe auch

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