Элемент: метод querySelector()

Метод querySelector() интерфейса Element возвращает первый элемент, являющийся потомком элемента, на котором он вызван, и соответствующий заданной группе селекторов.

selectors

Строка, содержащая один или несколько селекторов для сопоставления. Эта строка должна быть корректной строкой селектора CSS; в противном случае выбрасывается исключение SyntaxError.

Обратите внимание, что спецификация HTML не требует, чтобы значения атрибутов были корректными идентификаторами CSS. Если значение атрибута class или id не является корректным идентификатором CSS, то необходимо экранировать его перед использованием в селекторе, вызвав CSS.escape() для значения или используя один из методов, описанных в Экранирование символов. Смотрите Экранирование значений атрибутов для примера.

Первый дочерний элемент baseElement, который соответствует указанной группе selectors. В сопоставлении рассматривается вся иерархия элементов, включая элементы за пределами набора элементов, включающих baseElement и его потомков; другими словами, selectors сначала применяется ко всему документу, а не к baseElement, чтобы сгенерировать начальный список потенциальных элементов. Затем проверяются полученные элементы, чтобы определить, являются ли они потомками baseElement. Метод querySelector() возвращает первое совпадение среди оставшихся элементов.

Если совпадений не найдено, возвращаемое значение равно null.

SyntaxError DOMException

Выбрасывается, если указанные selectors некорректны.

Рассмотрим несколько примеров.

В этом первом примере возвращается первый элемент <style>, у которого либо нет типа, либо тип равен "text/css" в теле документа HTML:

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

В этом примере используется псевдокласс :scope для извлечения непосредственных дочерних элементов элемента parentElement.

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"));

Результат

Этот пример демонстрирует, что при применении selectors, учитывается вся иерархия всего документа, поэтому уровни вне указанного baseElement всё ещё рассматриваются при поиске совпадений.

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;

Результат

Результат выглядит так:

Обратите внимание, как селектор "div span" всё ещё успешно находит элемент <span>, даже если дочерние узлы baseElement не включают элемент <div> (он всё ещё входит в заданный селектор).

В этом примере показано, что если в документе HTML есть атрибут id, который не является корректным идентификатором CSS, то значение атрибута необходимо экранировать перед использованием в querySelector().

HTML

В следующем коде элемент <div> имеет атрибут id со значением "this?element", что не является корректным идентификатором CSS, так как символ "?" недопустим в идентификаторах CSS.

У нас также есть три кнопки и элемент <pre> для записи ошибок.

<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

Все три кнопки при нажатии пытаются выбрать <div>, а затем устанавливают его цвет фона случайным значением.

• Первая кнопка использует значение "this?element" напрямую.
• Вторая кнопка экранирует значение с помощью CSS.escape().
• Третья кнопка явно экранирует символ "?" с помощью обратного слэша. Обратите внимание, что мы также должны экранировать сам обратный слэш, используя другой обратный слэш, как: "\\?".

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");
});

Результат

Нажатие на первую кнопку приводит к ошибке, в то время как вторая и третья кнопки работают правильно.

См. Document.querySelector() для дополнительных примеров правильного формата для selectors.

• Поиск элементов DOM с помощью селекторов
• Селекторы атрибутов в руководстве по CSS
• Селекторы атрибутов в учебном центре MDN
• Element.querySelectorAll()
• Document.querySelector() и Document.querySelectorAll()
• DocumentFragment.querySelector() и DocumentFragment.querySelectorAll()
• Другие методы, принимающие селекторы: element.closest() и element.matches().