JavaScript метод document.querySelector()

Определение и применение

JavaScript метод document.querySelector() возвращает первый элемент в документе (объект Element), соответствующий указанному селектору, или группе селекторов. Если совпадений не найдено, то возвращается значение null.

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

Метод .querySelector() также определен в объекте Element, по этой причине он может быть вызван на любом элементе, не только на объекте document. Элемент, на котором он вызывается, будет использован в качестве корневого элемента для поиска.

Поддержка браузерами

Спецификация: dom.spec.whatwg

Поддерживается во всех основных браузерах с 2015 года.

Показать браузеры
Совместимостьapi.Document.querySelector
ВозможностьКомпьютерыМобильные
ChromeEdgeFirefoxOperaSafariChrome AndroidFirefox for AndroidOpera AndroidSafari on iOSSamsung BrowserWebView AndroidWebView on iOS
querySelector✓1✓12✓3.5✓10✓3.1✓18✓4✓10.1✓2✓1.0✓4.4✓2

поддерживаетсяс ограниченияминет поддержкинет данных≤31 — не позднее версии 31

JavaScript синтаксис

JavaScript
const element = document.querySelector(selectors);

Спецификация

DOM Standard.

Значения параметров

Параметры document.querySelector()
Параметр Описание
selectors Аргумент должен соответствовать допустимой строке селектора, содержащей один или несколько селекторов. При указании нескольких селекторов необходимо разделять значения запятыми. В этом случае будет возвращён первый в порядке документа элемент, соответствующий любому из заданных селекторов.
Если по какой-то причине вы используете в наименовании селекторов символы, которые не являются частью стандартного синтаксиса CSS, то при поиске такие символы должны быть экранированы с помощью символа обратной косой черты ("\"). Поскольку обратная косая черта также является специальным символом (escape) в JavaScript, то при вводе литеральной строки ее необходимо экранировать дважды. Обязательный параметр.

Исключения

Тип исключения Описание — document.querySelector()
Тип исключения Описание
SyntaxError Возникает в том случае, если синтаксис указанного селектора или селекторов некорректен.

Пример использования

Поиск первого элемента по разным селекторам

Нажмите ▶, затем Нажми меня: первый блок получит чёрный фон и красный текст, второй div — зелёный текст, последний div — синий. Измените селекторы в main.js и сравните, какие элементы находятся.

index.html
HTML
<button data-migration-click-0="">Нажми меня</button>
<div class="block first">Первый блок</div>
<div class="block">Второй блок</div>
<div class="block">Третий блок</div>
main.js
JavaScript
function myFunc() {
    let firstBlock = document.querySelector('.block'),
        first = document.querySelector('.first, .block'),
        second = document.querySelector('div:nth-of-type(2)'),
        third = document.querySelector('div:last-of-type')

    firstBlock.style.background = 'black'
    first.style.color = 'red'
    second.style.color = 'green'
    third.style.color = 'blue'
}

// Обработчики кнопок перенесены из HTML для запуска с CSP без inline-скриптов.
document.querySelector('[data-migration-click-0]').addEventListener('click', function () {
    myFunc()
})

В этом примере мы с использованием метода addEventListener() при нажатии на кнопку (HTML элемент <button>) вызываем функцию myFunc(), которая с использованием JavaScript метода document.querySelector() выбирает следующие элементы:

  • Первый элемент с классом block в документе и устанавливаем черный цвет заднего фона найденному элементу.
  • Первый элемент из заданных селекторов (элемент с классом first, элемент с классом block) и устанавливаем красный цвет текста найденному элементу. В этом случае будет выбран первый в порядке документа элемент, соответствующий любому из селекторов.
  • Элемент <div>, который является вторым дочерним элементом своего родительского элемента и устанавливаем найденному элементу зеленый цвет текста.
  • Элемент <div>, который является последним из элементов своего родительского элемента и устанавливаем найденному элементу синий цвет текста.