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; wenn dies nicht der Fall ist, wird eine SyntaxError Ausnahme ausgelöst.

Beachten Sie, dass die HTML-Spezifikation nicht erfordert, dass Attributwerte gültige CSS-Bezeichner sind. Wenn ein Wert für das class oder id Attribut kein gültiger CSS-Bezeichner ist, müssen Sie ihn escapen, bevor Sie ihn in einem Selektor verwenden, entweder durch Aufrufen von CSS.escape() für den Wert oder durch eine der in Escaping characters beschriebenen Techniken. Siehe Escaping attribute values für ein Beispiel.

Das erste Nachkommelement des baseElement, das mit der angegebenen Gruppe von selectors übereinstimmt. Die gesamte Hierarchie der Elemente wird beim Matchen berücksichtigt, einschließlich solcher außerhalb der Menge von Elementen, zu der baseElement und seine Nachkommen gehören; mit anderen Worten, selectors wird zunächst auf das ganze Dokument angewendet, nicht auf das baseElement, um eine anfängliche Liste von potenziellen Elementen zu generieren. Die resultierenden Elemente werden dann darauf untersucht, ob sie Nachkommen von baseElement sind. Das erste übereinstimmende Element dieser verbleibenden Elemente wird von der querySelector() Methode zurückgegeben.

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

SyntaxError DOMException

Wird ausgelöst, wenn die angegebenen selectors ungültig sind.

Lassen Sie uns einige Beispiele betrachten.

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

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 immer noch bei der Suche nach Übereinstimmungen berücksichtigt 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 so aus:

Beachten Sie, wie der "div span" Selektor das <span> Element weiterhin erfolgreich findet, auch wenn die Kindknoten des baseElement Elements nicht das <div> Element enthalten (es ist trotzdem Teil des angegebenen Selectors).

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

Im folgenden Code hat ein <div> Element eine id von "this?element", welche 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 Klick, 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 escaped das "?" Zeichen explizit mit einem Backslash. Beachten Sie, dass wir auch den Backslash selbst escapen müssen, mit einem weiteren Backslash, 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 erzeugt einen Fehler, während die zweiten und dritten Buttons richtig funktionieren.

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

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