Element: querySelector()-Methode

selectors

Ein String, der einen oder mehrere Selektoren enthält, die übereinstimmen sollen. Dieser String muss ein gültiger CSS-Selektor-String sein. Ist er das nicht, wird eine SyntaxError-Ausnahme geworfen.

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, dann müssen Sie ihn escapen, bevor Sie ihn in einem Selektor verwenden. Entweder durch Aufrufen von CSS.escape() auf den Wert oder unter Verwendung einer der Techniken, die in Escaping characters beschrieben sind. Siehe Escaping attribute values für ein Beispiel.

Das erste Nachfahr-Element von baseElement, das mit der angegebenen Gruppe von selectors übereinstimmt. Die gesamte Hierarchie der Elemente wird berücksichtigt, wenn Übereinstimmungen gesucht werden, einschließlich der Elemente außerhalb des Sets von baseElement und seinen Nachfahren. Mit anderen Worten, selectors wird zuerst auf das gesamte Dokument angewendet, nicht auf das baseElement, um eine anfängliche Liste potenzieller Elemente zu generieren. Die resultierenden Elemente werden dann untersucht, um festzustellen, ob sie Nachfahren von baseElement sind. Das erste übereinstimmende dieser verbleibenden Elemente wird von der querySelector()-Methode zurückgegeben.

Wenn keine Übereinstimmungen gefunden werden, ist der zurückgegebene Wert null.

SyntaxError DOMException

Wird geworfen, wenn die angegebenen selectors ungültig sind.

Sehen wir uns ein paar Beispiele an.

In diesem ersten Beispiel wird das erste <style>-Element zurückgegeben, das entweder keinen Typ hat oder den Typ "text/css" im HTML-Dokumentenkörper besitzt:

const el = document.body.querySelector(
  "style[type='text/css'], style:not([type])",
);

Dieses Beispiel verwendet die :scope-Pseudoklasse, um direkte Kinder des parentElement-Elements abzurufen.

HTML

<div>
  <h6>Page Title</h6>
  <div id="parent">
    <span>Love is Kind.</span>
    <span>
      <span>Love is Patient.</span>
    </span>
    <span>
      <span>Love is Selfless.</span>
    </span>
  </div>
</div>

CSS

span {
  display: block;
  margin-bottom: 5px;
}
.red span {
  background-color: red;
  padding: 5px;
}

JavaScript

const parentElement = document.querySelector("#parent");
let allChildren = parentElement.querySelectorAll(":scope > span");
allChildren.forEach((item) => item.classList.add("red"));

Ergebnis

Dieses Beispiel zeigt, dass die Hierarchie des gesamten Dokuments berücksichtigt wird, wenn selectors angewendet werden, sodass Ebenen außerhalb des angegebenen baseElement bei der Suche nach Übereinstimmungen dennoch einbezogen werden.

HTML

<div>
  <h5>Original content</h5>
  <p>
    inside paragraph
    <span>inside span</span>
    inside paragraph
  </p>
</div>
<div>
  <h5>Output</h5>
  <div id="output"></div>
</div>

JavaScript

const baseElement = document.querySelector("p");
document.getElementById("output").textContent =
  baseElement.querySelector("div span").textContent;

Ergebnis

Das Ergebnis sieht folgendermaßen aus:

Beachten Sie, dass der "div span"-Selektor immer noch das <span>-Element erfolgreich findet, auch wenn die Knoten des baseElement keine <div>-Elemente enthalten (es ist dennoch Teil des angegebenen Selektors).

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 querySelector() verwenden.

HTML

In dem folgenden Code hat ein <div>-Element eine id namens "this?element", die 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="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 beim Klicken, 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 escaped den Wert mit CSS.escape().
• Der dritte Button escapt das "?"-Zeichen explizit mit einem Backslash. Beachten Sie, dass wir auch den Backslash selbst mit einem 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 element = container.querySelector(`#${id}`);
    const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`;
    element.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.

Siehe Document.querySelector() für zusätzliche Beispiele des korrekten Formats für die selectors.

• DOM-Elemente mithilfe von Selektoren lokalisieren
• Attribut-Selektoren im CSS-Leitfaden
• Attribut-Selektoren im MDN Learning Area
• Element.querySelectorAll()
• Document.querySelector() und Document.querySelectorAll()
• DocumentFragment.querySelector() und DocumentFragment.querySelectorAll()
• Andere Methoden, die Selektoren verwenden: element.closest() und element.matches().