jQuery.find()

Описание: Движок селекторов jQuery, ранее известный как Sizzle, доступен через jQuery.find. На этой странице описаны все API в jQuery.find.

Примечание

Движок селекторов jQuery сначала пытается выполнить переданный селектор — с некоторыми изменениями — с помощью нативного querySelectorAll, поэтому селекторы, изначально поддерживаемые текущими браузерами, обычно работают без дополнительной настройки. Однако если браузер не распознаёт селектор, jQuery выполняет весь поиск самостоятельно. Некоторые более новые селекторы могут не работать при таком поиске с помощью jQuery.

Селекторы

CSS 3

jQuery поддерживает практически все селекторы CSS 3, в том числе экранированные селекторы (.foo\+bar), селекторы Unicode и результаты, возвращаемые в порядке следования элементов в документе. Единственные исключения — селекторы, для работы которых потребовались бы дополнительные обработчики событий DOM, отслеживающие состояние элементов.

Поэтому следующие псевдоселекторы не поддерживаются:

:hover
:active
:visited, :link

Примечание: До версии 1.9 эти псевдоселекторы CSS3 не поддерживались:

:target
:root
:nth-last-child
:nth-of-type, :nth-last-of-type, :first-of-type, :last-of-type, :only-of-type
:lang()

Другие селекторы и соглашения

Изменения

Полные списки селекторов в :not(); например, :not(a.b), :not(div > p), :not(div, p)
Вложенные псевдоселекторы; например, :not(:has(div:first-child))

Добавления

[NAME!=VALUE]: Элементы, атрибут NAME которых не соответствует указанному значению. Эквивалент :not([NAME=VALUE]).
:contains(TEXT): Элементы, textContent которых содержит слово 'TEXT'. С учётом регистра.
:header: Элементы заголовков (h1, h2, h3, h4, h5, h6).
:parent: Элементы, у которых есть хотя бы один дочерний узел (текст или элемент).
:selected: элементы (option), выбранные в данный момент

Дополнительные селекторы форм

Примечание: В этом контексте input, button, select и textarea считаются элементами input.

:input: Элементы input
:button: Элементы input, являющиеся buttonами или имеющие тип "button"
:checkbox, :file, :image, :password, :radio, :reset, :submit, :text: Элементы input с указанным типом

Дополнительные позиционные селекторы

В этом контексте «позиционный» означает положение элемента в коллекции после выбора, определяемое порядком элементов в документе. Например, div:first вернёт массив, содержащий первый div на странице, а div:first em выберет первый div на странице и все элементы em внутри него.

Примечание: Отсчёт позиционных индексов начинается с нуля.

:first/:last: Первый/последний совпавший элемент
:even/:odd: Элементы с чётными/нечётными номерами
:eq/:nth: Элемент с номером n; например, :eq(5) находит 6-й элемент
:lt/:gt: Элементы, расположенные выше/ниже указанной позиции

API

API выборки jQuery состоит из 3 частей:

Публичный API, с которым взаимодействуют пользователи.
API расширений, предназначенный для изменения движка селекторов.
Внутренний API, используемый внутри jQuery.

Публичный API

`jQuery.find( String selector[, DOMNode context[, Array results]] )`

Основная функция для поиска элементов. Использует querySelectorAll, если он доступен.

возвращает (Array): Все элементы, соответствующие селектору

Параметры

selector: Селектор CSS

context: Элемент, документ или фрагмент документа, используемый в качестве контекста для поиска элементов. По умолчанию — document. Примечание: До версии 2.1 фрагменты документа здесь не допускались.

results: Массив или объект, подобный массиву, в который jQuery добавит результаты. Например, jQuery передаёт коллекцию jQuery. «Объект, подобный массиву» — это объект с неотрицательным числовым свойством length и методом push.

`jQuery.find.matchesSelector( DOMElement element, String selector )`

Использует нативный matchesSelector, если он доступен

возвращает(Boolean): Соответствует ли указанный элемент селектору

Параметры

element: Объект DOMElement, относительно которого jQuery проверяет селектор

selector: Селектор CSS

`jQuery.find.matches( String selector, Array<DOMElement> elements )`

возвращает(Array): Элементы массива, соответствующие указанному селектору

Параметры

selector: Селектор CSS

elements: Массив объектов DOMElements для фильтрации по указанному селектору

API расширений

`jQuery.expr.match.NAME = RegExp`

Здесь содержатся регулярные выражения, используемые для разбора селектора на отдельные части, необходимые для поиска и фильтрации. Название каждого регулярного выражения должно соответствовать названиям, указанным в объектах jQuery.expr.find и jQuery.expr.filter.

Поиск

Чтобы добавить новую функцию поиска:

В объект match необходимо добавить регулярное выражение.
Необходимо определить функцию для find.
"|" + NAME необходимо добавить в регулярное выражение jQuery.expr.order.

`jQuery.expr.find.NAME = function( match, context, isXML ) {}`

Метод для поиска элементов на странице. Указанная функция будет вызвана не более одного раза для каждого селектора.

match — это массив результатов, полученных при сопоставлении указанного регулярного выражения с селектором.
context — это DOMElement или DOMDocument, в пределах которого будет выполняться поиск.
isXML — это логическое значение, указывающее, выполняется ли функция в данный момент в XML-документе.

Фильтрация

Чтобы добавить новое условие фильтрации:

В объект match необходимо добавить регулярное выражение.
В объект filter необходимо добавить функцию.
При необходимости в объект preFilter можно добавить функцию.

`jQuery.expr.preFilter.NAME = function( match ) {}`

Необязательная функция предварительной фильтрации, которая позволяет отфильтровать сопоставленный массив по соответствующему регулярному выражению и возвращает новый сопоставленный массив. Этот массив впоследствии передаётся в виде аргументов соответствующей функции фильтрации и преобразуется в плоский список. Это позволяет избежать повторяющейся обработки, выполняемой в функции фильтрации.

`jQuery.expr.filter.NAME: function( element, match[1][, match[2], match[3], ...] ) {}`

Примечание: match[0] будет удалено перед передачей фильтру, поэтому использовать его нельзя.

Аргументы метода фильтрации — это элемент и захваченные группы регулярного выражения, соответствующего данному фильтру (указанные выше содержимым совпадения, начиная с индекса 1). Результат должен иметь логический тип: true, если элемент соответствует селектору, и false в противном случае.

Атрибуты

`jQuery.expr.attrHandle.LOWERCASE_NAME = function( elem, casePreservedName, isXML ) {}`

Обработка атрибута, требующего специальной обработки (например, href, для которого существуют межбраузерные проблемы). Результатом должна быть фактическая строка значения этого атрибута.

Псевдоселекторы (псевдо)

`jQuery.expr.pseudos.NAME = function( elem ) {}`

Самое распространённое расширение движка селекторов: добавление нового псевдоселектора. Результат этой функции должен иметь логический тип: true, если элемент соответствует селектору, и false в противном случае.

Например, так определяется простой псевдоселектор :fixed:

var $test = jQuery( document );
jQuery.expr.pseudos.fixed = function( elem ) {
  $test[ 0 ] = elem;
  return $test.css( "position" ) === "fixed";
};

`jQuery.expr.createPseudo( function )`

createPseudo требуется только в том случае, если пользовательский псевдоселектор принимает аргумент.

Примечание: В jQuery 1.8 и более ранних версиях API создания пользовательских псевдоселекторов с аргументами работал некорректно. В jQuery 1.8.1+ API обеспечивает обратную совместимость. В любом случае настоятельно рекомендуется использовать createPseudo.

Теперь, когда парсер компилирует одну функцию, содержащую другие функции, пользовательские псевдоселекторы с аргументами стали значительно проще.

Например, реализация псевдоселектора :not( <sub-selector> ) внутри jQuery очень похожа на следующую:

jQuery.expr.pseudos.not =
  jQuery.expr.createPseudo( function( subSelector ) {
    var matcher = jQuery.find.compile( subSelector );
    return function( elem ) {
      return !matcher( elem );
    };
  } );

`jQuery.expr.setFilters.LOWERCASE_NAME = function( elements, argument, not ) {}`

Эти фильтры запускаются после того, как предыдущая часть селектора уже вернула результаты. setFilters находятся путём сопоставления с jQuery.expr.match.POS. Если применимо, ожидается, что argument будет целым числом. Аргумент not — это логическое значение, указывающее, нужно ли инвертировать результат (как в div:not(:first)).

Например, код фильтра набора :first похож на следующий:

var first = function( elements, argument, not ) {
  // No argument for first
  return not ? elements.slice( 1 ) : [ elements[ 0 ] ];
};
jQuery.expr.setFilters.first = first;

Движок выборки jQuery легко расширить — даже его селекторы POS. Например, чтобы переименовать :first в :uno:

jQuery.expr.match.POS = new RegExp( oldPOS.source.replace( "first", "uno" ), "gi" );
jQuery.expr.setFilters.uno = jQuery.expr.setFilters.first;
delete jQuery.expr.setFilters.first;
jQuery.find( "div:uno" ); // ==> [ <div> ]

Внутренний API

Примечание: Доступ к функциональности следует получать через публичный API и API расширений. Хотя внутренний API предназначен специально для внутреннего использования, он открыт для особых случаев.

`jQuery.expr.cacheLength`

Внутри jQuery кэшируются скомпилированные функции селекторов и объекты токенизации. По умолчанию размер этих кэшей равен 50, но его можно задать любым положительным целым числом, присвоив значение этому свойству.

`jQuery.find.compile( selector )`

Этот метод компилирует функцию селектора и кэширует её для последующего использования. Например, вызов jQuery.find.compile( ".myWidget:myPseudo" ) при инициализации плагина ускорит первый поиск соответствующих элементов.

возвращает(Function): Скомпилированная функция, используемая при фильтрации набора потенциально подходящих элементов

Параметры

selector: Селектор CSS