Element: querySelector() Methode

Syntax

querySelector(selectors)

Parameter

selectors

Ein String, der einen oder mehrere Selektoren enthält, die übereinstimmen sollen. Dieser String muss ein gültiger CSS-Selektor-String sein; andernfalls wird eine SyntaxError-Ausnahme ausgelöst.

Beachten Sie, dass die HTML-Spezifikation nicht verlangt, dass Attributwerte gültige CSS-Bezeichner sind. Wenn ein Wert eines class- oder id-Attributs kein gültiger CSS-Bezeichner ist, müssen Sie ihn entweder durch Aufruf von CSS.escape() auf den Wert escapen oder eine der in Zeichen escapen beschriebenen Techniken verwenden. Siehe Attributwerte escapen für ein Beispiel.

Rückgabewert

Das erste Nachkomme-Element von baseElement, das mit der angegebenen Gruppe von selectors übereinstimmt. Die gesamte Hierarchie der Elemente wird bei der Übereinstimmung berücksichtigt, einschließlich derjenigen außerhalb der Menge der Elemente, die baseElement und seine Nachkommen umfassen; mit anderen Worten, selectors wird zuerst auf das gesamte Dokument angewendet, nicht auf baseElement, um eine initiale Liste potenzieller Elemente zu erstellen. Die resultierenden Elemente werden dann untersucht, um festzustellen, ob sie Nachkommen von baseElement sind. Das erste Übereinstimmungselement dieser verbleibenden Elemente wird von der querySelector()-Methode zurückgegeben.

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

Ausnahmen

SyntaxError DOMException

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

Beispiele

Betrachten wir einige Beispiele.

Ein spezifisches Element mit bestimmten Attributwerten finden

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 besitzt:

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

Direkte Nachkommen mit der :scope-Pseudoklasse abrufen

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

Die gesamte Hierarchie zählt

Dieses Beispiel zeigt, dass die Hierarchie des gesamten Dokuments bei der Anwendung von selectors berücksichtigt wird, sodass Ebenen außerhalb des angegebenen baseElement weiterhin berücksichtigt werden, wenn Übereinstimmungen gesucht 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, wie der "div span"-Selektor dennoch erfolgreich das <span>-Element findet, obwohl die Kindknoten des baseElement nicht das <div>-Element umfassen (es ist trotzdem Teil des angegebenen Selektors).

Attributwerte escapen

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", 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 zur Protokollierung 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 "this?element"-Wert direkt.
• Der zweite Button escapet den Wert mit CSS.escape().
• Der dritte Button escapet das "?"-Zeichen explizit mit einem Backslash. Beachten Sie, dass wir auch den Backslash selbst escapen müssen, indem wir einen weiteren Backslash verwenden, so: "\\?".

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

Beim Klicken auf den ersten Button wird ein Fehler angezeigt, während der zweite und dritte Button ordnungsgemäß funktionieren.

Weitere Beispiele

Siehe Document.querySelector() für zusätzliche Beispiele zur richtigen Formatierung der selectors.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Auswahl und Durchlaufen im DOM-Baum
• Attributselektoren im CSS-Leitfaden
• Attributselektoren 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().