DiequerySelector()-Methode derElement-Schnittstelle gibt das erste Element zurück, das ein Nachkomme des Elements ist, auf dem sie aufgerufen wurde und das mit der angegebenen Gruppe von Selektoren übereinstimmt.

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 eineSyntaxError-Ausnahme ausgelöst.

Beachten Sie, dass die HTML-Spezifikation nicht verlangt, dass Attributwerte gültige CSS-Bezeichner sind. Wenn einclass- oderid-Attributwert kein gültiger CSS-Bezeichner ist, müssen Sie ihn vor der Verwendung in einem Selektor escapen, entweder indem SieCSS.escape() auf den Wert anwenden oder eine der inZeichen escapen beschriebenen Techniken verwenden. SieheAttributwerte escapen für ein Beispiel.

Rückgabewert

Das erste Nachkommelement vonbaseElement, das mit der angegebenen Gruppe vonselectors übereinstimmt. Die gesamte Hierarchie der Elemente wird bei der Übereinstimmung berücksichtigt, einschließlich derer außerhalb der Menge an Elementen, diebaseElement und seine Nachkommen umfasst; mit anderen Worten,selectors wird zuerst auf das gesamte Dokument angewendet, nicht aufbaseElement, um eine anfängliche Liste möglicher Elemente zu generieren. Die resultierenden Elemente werden dann überprüft, ob sie Nachkommen vonbaseElement sind. Das erste übereinstimmende dieser verbleibenden Elemente wird von derquerySelector()-Methode zurückgegeben.

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

Ausnahmen

SyntaxErrorDOMException

Wird ausgelöst, wenn die angegebenenselectors 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 desparentElement-Elements abzurufen.

HTML

<div>  <h6>Page Title</h6>  <div>    <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, wennselectors angewendet werden, sodass Ebenen außerhalb des angegebenenbaseElement 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></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 vonbaseElement das<div>-Element nicht enthalten (es ist immer noch Teil des angegebenen Selektors).

Attributwerte escapen

Dieses Beispiel zeigt, dass, wenn ein HTML-Dokument eineid enthält, die kein gültigerCSS-Bezeichner ist, wir den Attributwert escapen müssen, bevor wir ihn inquerySelector() verwenden.

HTML

Im folgenden Code hat ein<div>-Element eineid 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>  <div></div></div><button>No escape</button><button>CSS.escape()</button><button>Manual escape</button><pre></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 mitCSS.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

SieheDocument.querySelector() für zusätzliche Beispiele des korrekten Formats für dieselectors.

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() undDocument.querySelectorAll()
• DocumentFragment.querySelector() undDocumentFragment.querySelectorAll()
• Andere Methoden, die Selektoren verwenden:element.closest() undelement.matches().