Element: querySelector() Methode

Syntax

querySelector(selectors)

Parameter

selectors

Ein String, der einen oder mehrere Selektoren zur Übereinstimmung enthält. 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 class- oder id-Attributwert kein gültiger CSS-Bezeichner ist, müssen Sie ihn vor der Verwendung in einem Selektor escapen, entweder indem Sie CSS.escape() auf den Wert anwenden oder eine der in Zeichen escapen beschriebenen Techniken verwenden. Siehe Attributwerte escapen für ein Beispiel.

Rückgabewert

Das erste Nachkommelement von baseElement, das mit der angegebenen Gruppe von selectors übereinstimmt. Die gesamte Hierarchie der Elemente wird bei der Übereinstimmung berücksichtigt, einschließlich derer außerhalb der Menge an Elementen, die baseElement und seine Nachkommen umfasst; mit anderen Worten, selectors wird zuerst auf das gesamte Dokument angewendet, nicht auf baseElement, um eine anfängliche Liste möglicher Elemente zu generieren. Die resultierenden Elemente werden dann überprüft, ob sie Nachkommen 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.

Ausnahmen

SyntaxError DOMException

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

Beispiele

Betrachten wir einige Beispiele.

Ein bestimmtes 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 hat:

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

Direkte Nachkommen mit der :scope Pseudo-Klasse abrufen

Dieses Beispiel verwendet die :scope Pseudo-Klasse, 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 gesamte Dokumentenhierarchie berücksichtigt wird, wenn selectors angewendet werden, sodass Ebenen außerhalb des angegebenen baseElement weiterhin in Betracht gezogen werden, um Übereinstimmungen zu finden.

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 wie folgt aus:

Beachten Sie, wie der "div span"-Selektor immer noch erfolgreich das <span>-Element findet, obwohl die untergeordneten Knoten von baseElement das <div>-Element nicht enthalten (es ist immer noch 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 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>-Element zu selektieren und dann seine 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 explizit mit einem Backslash. Beachten Sie, dass wir auch den Backslash selbst escapen müssen, indem wir einen weiteren Backslash verwenden, 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 der zweite und dritte Button ordnungsgemäß funktionieren.

Weitere Beispiele

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Selektion und Traversierung auf dem DOM-Baum
• Attributselektoren im CSS-Leitfaden
• Attributselektoren im MDN-Lernbereich
• Element.querySelectorAll()
• Document.querySelector() und Document.querySelectorAll()
• DocumentFragment.querySelector() und DocumentFragment.querySelectorAll()
• Andere Methoden, die Selektoren verwenden: element.closest() und element.matches().