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

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

selectors

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

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

Селекторы применяются ко всему документу, а не только к конкретному элементу, к которому был вызван querySelectorAll(). Чтобы ограничить селектор элементом, к которому вызван querySelectorAll(), добавьте псевдокласс :scope в начале селектора. См. пример области селектора.

Нединамический NodeList, содержащий один объект Element для каждого дочернего узла, который соответствует хотя бы одному из указанных селекторов. Элементы упорядочены по порядку в документе — то есть, родители перед детьми, предыдущие братья перед последующими.

SyntaxError DOMException

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

В этом примере используется селектор атрибута для выбора нескольких элементов с атрибутом данных data-name , содержащим "funnel-chart-percent".

<section class="box" id="sect1">
  <div data-name="funnel-chart-percent1">10.900%</div>
  <div data-name="funnel-chart-percent2">3700.00%</div>
  <div data-name="funnel-chart-percent3">0.00%</div>
</section>

const refs = [
  ...document.querySelectorAll(`[data-name*="funnel-chart-percent"]`),
];

Чтобы получить NodeList всех элементов <p>, содержащихся в элементе myBox:

const matches = myBox.querySelectorAll("p");

Этот пример возвращает список всех элементов <div> внутри myBox с классом либо note , либо alert:

const matches = myBox.querySelectorAll("div.note, div.alert");

Здесь мы получаем список элементов <p> в документе, у которых непосредственным родительским элементом является <div> с классом "highlighted" и которые находятся внутри контейнера с идентификатором "test".

const container = document.querySelector("#test");
const matches = container.querySelectorAll("div.highlighted > p");

Этот пример использует селектор атрибута для возврата списка элементов <iframe> в документе, содержащих атрибут с именем "data-src":

const matches = document.querySelectorAll("iframe[data-src]");

Здесь используется селектор атрибута для возврата списка элементов списка, содержащихся в списке с идентификатором "user-list" и имеющих атрибут "data-active" со значением "1":

const container = document.querySelector("#user-list");
const matches = container.querySelectorAll("li[data-active='1']");

После получения NodeList совпадающих элементов, вы можете обращаться к нему как к любому массиву. Если массив пустой (т.е., его свойство length равно 0), то совпадений не найдено.

В противном случае, вы можете использовать стандартную нотацию массивов для доступа к содержимому списка. Вы можете использовать любые стандартные циклы, такие как:

const highlightedItems = userList.querySelectorAll(".highlighted");

highlightedItems.forEach((userItem) => {
  deleteUser(userItem);
});

Метод querySelectorAll() применяет свои селекторы ко всему документу: они не ограничены элементом, к которому был вызван метод. Чтобы ограничить область действия селекторов, добавьте псевдокласс :scope в начале строки селектора.

HTML

В этом примере HTML содержит:

• две кнопки: #select и #select-scope
• три вложенных элемента <div>: #outer, #subject, и #inner
• элемент <pre> , который используется в примере для вывода.

<button id="select">Select</button>
<button id="select-scope">Select with :scope</button>

<div id="outer">
  #outer
  <div id="subject">
    #subject
    <div id="inner">#inner</div>
  </div>
</div>

<pre id="output"></pre>

JavaScript

В JavaScript мы сначала выбираем элемент #subject.

При нажатии кнопки #select мы вызываем querySelectorAll() на #subject, передавая строку селектора "#outer #inner".

При нажатии кнопки #select-scope мы снова вызываем querySelectorAll() на #subject, но на этот раз передаём строку селектора ":scope #outer #inner".

const subject = document.querySelector("#subject");

const select = document.querySelector("#select");
select.addEventListener("click", () => {
  const selected = subject.querySelectorAll("#outer #inner");
  output.textContent = `Selection count: ${selected.length}`;
});

const selectScope = document.querySelector("#select-scope");
selectScope.addEventListener("click", () => {
  const selected = subject.querySelectorAll(":scope #outer #inner");
  output.textContent = `Selection count: ${selected.length}`;
});

Результат

При нажатии на "Выбрать", селектор выбирает все элементы с id inner , у которых также есть предковый элемент с id outer. Обратите внимание, что даже если #outer находится вне элемента #subject , он всё равно используется в процессе выбора, поэтому наш элемент #inner будет найден.

При нажатии на "Выбрать с :scope", псевдокласс :scope ограничивает область действия селектора элементом #subject, поэтому #outer не используется в процессе сопоставления селектора, и мы не найдём элемент #inner.

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

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 elements = container.querySelectorAll(`#${id}`);
    const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`;
    elements[0].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");
});

Результат

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

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