Dokument: 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-Selector-String sein; wenn nicht, 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 Selector entweder durch einen Aufruf von CSS.escape() auf den Wert oder eine der in Escaping characters beschriebenen Techniken escapen. Siehe Escaping attribute values 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 vorhanden sind.

Wenn 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 finden, das einer Klasse entspricht

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

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

Komplexe Selektoren

Selectoren können auch sehr mächtig sein, wie im folgenden Beispiel gezeigt. Hier wird das erste <input>-Element mit dem Namen "login" (<input name="login"/>), das sich in einem <div> befindet, dessen Klasse "user-panel main" (<div class="user-panel main">) ist, im Dokument zurückgegeben:

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

Negation

Da alle CSS-Selector-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.

Escaping von Attributwerten

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", was kein gültiger CSS-Bezeichner ist, da das Zeichen "?" in CSS-Bezeichnern nicht erlaubt ist.

Wir haben auch drei Schaltflächen und ein <pre>-Element zum Protokollieren 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 Schaltflächen versuchen bei Klick, das <div> auszuwählen und dann seine Hintergrundfarbe auf einen zufälligen Wert zu setzen.

• Die erste Schaltfläche verwendet den "this?element"-Wert direkt.
• Die zweite Schaltfläche escapet den Wert mit CSS.escape().
• Die dritte Schaltfläche escapet 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 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

Durch Klicken auf die erste Schaltfläche wird ein Fehler ausgegeben, während die zweite und dritte Schaltfläche ordnungsgemäß funktionieren.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Selektion und Durchlauf im DOM-Baum
• Element.querySelector()
• Document.querySelectorAll()
• Element.querySelectorAll()