Dokument: querySelector() Methode

Die Document Methode querySelector() gibt das erste Element im Dokument zurück, das dem angegebenen CSS-Selektor oder einer Gruppe von CSS-Selektoren entspricht. Wenn keine Übereinstimmungen gefunden werden, wird null zurückgegeben.

Die Übereinstimmung erfolgt mittels eines tiefen Prioritätsdurchgangs in Vorordnung durch die Knoten des Dokuments, beginnend mit dem ersten Element im Markup des Dokuments und iterierend durch fortlaufende Knoten in der Reihenfolge der Anzahl der Kindknoten.

Wenn der angegebene Selektor einer ID entspricht, die fälschlicherweise mehr als einmal im Dokument verwendet wird, wird das erste Element mit dieser ID zurückgegeben.

CSS-Pseudoelemente werden niemals Elemente zurückgeben.

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; falls nicht, wird eine SyntaxError-Ausnahme ausgelöst.

Beachten Sie, dass die HTML-Spezifikation nicht erfordert, dass Attributwerte gültige CSS-Bezeichner sind. Falls 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 aufrufen oder eine der in Zeichen escapen beschriebenen Techniken anwenden. Siehe Attributwerte escapen für ein Beispiel.

Rückgabewert

Ein Element Objekt, das das erste Element im Dokument darstellt, das dem angegebenen Satz von CSS-Selektoren entspricht, oder null wird zurückgegeben, wenn keine Übereinstimmungen vorliegen.

Falls Sie eine Liste aller Elemente benötigen, die den angegebenen Selektoren entsprechen, sollten Sie stattdessen querySelectorAll() verwenden.

Ausnahmen

SyntaxError DOMException

Wird ausgelöst, wenn die Syntax der angegebenen selectors ungültig ist.

Beispiele

Das erste Element mit einer Klasse finden

In diesem Beispiel wird das erste Element im Dokument mit der Klasse myclass zurückgegeben:

const el = document.querySelector(".myclass");

Komplexe Selektoren

Selektoren können auch sehr leistungsfähig sein, wie im folgenden Beispiel demonstriert. Hier wird das erste <input> Element mit dem Namen "login" (<input name="login"/>) innerhalb eines <div>, dessen Klasse "user-panel main" (<div class="user-panel main">) im Dokument ist, zurückgegeben:

const el = document.querySelector("div.user-panel.main input[name='login']");

Negation

Da alle CSS-Selektor-Strings gültig sind, können Sie auch Selektoren negieren:

const el = document.querySelector(
 "div.user-panel:not(.main) input[name='login']",
);

Dies wird ein Input mit einem übergeordneten div mit der user-panel Klasse, aber nicht der main Klasse auswählen.

Attributwerte escapen

Dieses Beispiel zeigt, dass falls 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", was 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 Ausgabe von Fehlern.

<div id="this?element"></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, wenn sie geklickt werden, 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 escapet den Wert mit CSS.escape().
• Der dritte Button escapet das "?" Zeichen explizit durch einen Backslash. Beachten Sie, dass wir auch den Backslash selbst escapen müssen, indem wir einen weiteren Backslash verwenden, wie: "\\?".

const log = document.querySelector("#log");
function random(number) {
 return Math.floor(Math.random() * number);
}
function setBackgroundColor(id) {
 log.textContent = "";
 try {
 const element = document.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 des ersten Buttons führt zu einem Fehler, während die zweiten und dritten Buttons ordnungsgemäß funktionieren.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Auswahl und Traversierung auf dem DOM-Baum
• Element.querySelector()
• Document.querySelectorAll()
• Element.querySelectorAll()