LOGO JQuery
jQuery API: Traversing - обход DOM
Очередная статья по документации jQuery. Мы разберем как библиотека jQuery позволяет работать с объектной моделью документа.

Узнаем как изменять набор элементов DOM с помощью фильтров или поиска, а также научимся формировать и изменять цепочки вызовов для перемещения по объектной модели документа не только вперед, но и назад.

Перемещения по дереву DOM

.children([selector])

Возвращает все дочерние элементы выбранных элементов.
При необходимости, можно указать селектор selector для фильтрации результата.
// вернет элементы, которые лежат непосредственно внутри div-элементов.
$("div").children();
//  элементы класса bigBlock, которые лежат непосредственно внутри div-элементов.
$("div").children(".bigBlock");
// вернет элементы класса lBlock, 
которые лежат непосредственно внутри элемента с идентификатором lArea.	
$("#lArea").children(".lBlock");
Выделим элементы, содержащиеся внутри элементов списка
(и заодно узнаем, что нужно для приготовления суши):
$("li").children().css("border", "1px solid red");
Откройте пример в новом окне и посмотрите исходный код

.find(selector)

Ищет элементы, соответствующие заданному селектору, внутри выбранных элементов.

.find() удобно использовать, когда некоторые элементы уже найдены, и вам необходимо осуществить поиск элементов внутри них:
// найдем все ul-элементы на странице
var ulElements = $('ul');

// найдем li-элементы с классом userBox, внутри $ulElements
ulElements.find('li.userBox');
Так же, .find() удобен для использования в цепочках методов:
$('ul') // найдем все ul-элементы на странице
  .addClass('listElements') // добавим ul класс listElements
  .find('li.userBox') // найдем li-элементы с классом userBox, внутри ul
  .remove(); // и удалим их
Работа метода .find() схожа с .children(), который осуществляет поиск подходящих дочерних элементов.

Отличие заключается в том, что .find() проводит поиск не только среди дочерних элементов, но и внутри них тоже.

Поиск проходит на всех вложенных уровнях иерархии DOM, в то время как .children() ищет только на одном уровне.

В этом примере поиск элементов span производится в наборе всех элементов p. По другому это можно записать как $("p span")
$("p").find("span").css('color','red');
Откройте пример в новом окне и посмотрите исходный код

.next([selector])

Возвращает элементы, которые находятся непосредственно после каждого из выбранных элементов.
При необходимости, можно задать селектор selector для фильтрации результата.
// вернет элементы, которые находятся непосредственно после div-элементов на странице.
$("div").next();	
// вернет элементы класса bigBlock, которые находятся непосредственно после div-элементов.
$("div").next(".bigBlock");
В этом примере мы отыскиваем сестринские элементы, следующие непосредственно за элементами button, которые имеют значение атрибута disabled = disabled и изменяем текст этих (следующих за кнопками) элементов на "this button is disabled".
$("button[disabled]").next()
  .text("this button is disabled");
Откройте пример в новом окне и посмотрите исходный код

.nextAll([selector])

Возвращает все элементы, которые находятся после каждого из выбранных элементов. При необходимости, можно указать селектор selector для фильтрации результата.

nextAll ищет нужные элементы, только на общих уровнях дерева DOM с выбранными элементами. То есть, только внутри непосредственных родителей выбранных элементов.
// вернет элементы, которые находятся после div-элементов на странице.
$("div").nextAll();	
// вернет элементы класса bigBlock, которые находятся после div-элементов.
$("div").nextAll(".bigBlock");	
// вернет элементы класса lBlock, которые находятся после элемента с идентификатором lArea.
$("#lArea").nextAll(".lBlock");
В этом примере мы определяем все элементы div после первого и назначаем им класс с именем after.
$("div:first").nextAll().addClass("after");
Откройте пример в новом окне и посмотрите исходный код

.nextUntil([selector])

jQuery 1.4+

Возвращает все элементы, которые лежат после каждого из выбранных, но не дальше первого элемента, удовлетворяющего заданному селектору selector.
Если селектор не задан, результат будет аналогичен использованию nextAll()
// вернет элементы, которые находятся после каждого div-элемента на странице, 
// но не дальше первого элемента с классом lBlock.
$("div").nextUntil(".lBlock")
Выясним, какие элементы в списках идут после элементов с классом start и до элементов с классом stop:
$(".start")
	.nextUntil(".stop")
	.css("background-color", "red");
Откройте пример в новом окне и посмотрите исходный код

.offsetParent()

Возвращает ближайшего предка (т.е. из числа: родитель, прародитель, и так далее, до начало дерева DOM), у которого задан тип позиционирования.

Элементы с заданным позиционированием играют особую роль, поскольку именно относительно них происходит позиционирование всех элементов внутри.

Для элемента с классом inner найдем и выделим желтым цветом ближайший родительский элемент, у которого задан тип позиционирования.
$(".inner").offsetParent().css('background-color', 'yellow');
Откройте пример в новом окне и посмотрите исходный код

.parent([selector])

Возвращает родительские элементы всех выбранных элементов.
При необходимости, можно указать селектор selector для фильтрации результата.
// вернет родителя элемента с идентификатором block.
$("#block").parent();	
// вернет родительские элементы всех div-ов.
$("div").parent();	
// вернет элементы класса lBlock, которые являются родительскими для div-элементов на странице.
$("div").parent(".lBlock");
Найдем бомбы в коробках (элементы класса bomb, лежащие непосредственно внутри элементов класса box):
$(".bomb")
	.parent(".box")
	.css("border","3px solid red")
	.html("Бомба, епт!");
Откройте пример в новом окне и посмотрите исходный код

.parents([selector])

Осуществляет поиск всех предков выбранных элементов.
Не только прямых родителей, но и прародителей, прапрародителей и так далее, до начало дерева DOM.
// вернет всех предков элемента, имеющего идентификатор block.
$("#block").parents();	
// вернет всех предков для div-элементов на странице.
$("div").parents();	
// вернет всех предков класса lBlock, для div-элементов на странице.
$("div").parents(".lBlock");
Зальем элемент с классом item-b зеленым цветом, а всем его предкам добавим красную рамку:
$(".item-b")
	.css("background-color", "green")
	.parents().css("border", "1px solid red");
Откройте пример в новом окне и посмотрите исходный код

.parentsUntil([selector])

Ищет всех предков у выбранных элементов.
Прекращая поиск перед элементами, соответствующими заданному селектору selector.

Зальем элемент с классом item-b зеленым цветом, а всем его предкам, до элемента с классом level-1, добавим красную рамку:
$(".item-b")
	.css("background-color", "green")
	.parentsUntil(".level-1")
	.css("border", "1px solid red");
Откройте пример в новом окне и посмотрите исходный код

.prev([selector])

Возвращает элементы, которые находятся непосредственно перед каждым из выбранных элементов.
При необходимости, можно задать селектор selector для фильтрации результата.

В этом примере мы каждый раз по клику на кнопке находим непосредственно предыдущий сестринский элемент для каждого элемента div.
var $curr = $("#start");
$curr.css("background", "#f99");
$("button").click(function () {
  $curr = $curr.prev();
  $("div").css("background", "");
  $curr.css("background", "#f99");
});
Откройте пример в новом окне и посмотрите исходный код

.prevAll(selector)

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

В этом примере мы определяем все элементы div перед последним и назначаем им класс с именем before.
$("div:last").prevAll().addClass("before");
Откройте пример в новом окне и посмотрите исходный код

.prevUntil([selector])

Возвращает элементы, которые лежат перед каждым из выбранных, но не дальше первого элемента, соответствующего заданному селектору.
Если селектор не задан, результат будет аналогичен использованию prevAll()

Выясним, какие элементы в списках идут перед элементами с классом start, но находятся от них не дальше элемента с классом stop:
$(".start").prevUntil(".stop")
      .css("background-color", "red");
Откройте пример в новом окне и посмотрите исходный код

.siblings([selector])

Осуществляет поиск элементов, являющихся соседними для выбранных элементов
(под соседними понимаются элементы, которые имеют общего родителя).
При этом, сами выбранные элементы в результат не включаются.
// найдет элементы, которые имеют общего родителя, 
// с элементом, обладающим идентификатором block.
$("#block").siblings();
// найдет элементы, которые имеют общих родителей, 
// с элементами класса lBlock	
$(".lBlock").siblings();	
// найдет элементы класса cont, 
// которые имеют общих родителей, с элементами класса lBlock
$(".lBlock").siblings(".cont");
Найдем соседние элементы для элементов с классами item-2 и item-ii:
$(".item-2").siblings().css("background-color", "green");
  $(".item-ii").siblings().css("background-color", "red");
Откройте пример в новом окне и посмотрите исходный код

Фильтрация набора

.eq(index)

index — номер искомого элемента в наборе. Может быть задан двумя способами: стандартно, как в массиве, то есть нумерация будет начинаться с 0.

Кроме этого, можно задать index отрицательным целым числом, и в таком случае, элементы будут браться с конца:
-1 — последний элемент,
-2 — предпоследний, и.т.д.
$("div").eq(0); // вернет первый div-элемент на странице.
$("div").eq(-1); // вернет последний div-элемент на странице.
$("div.lBlock").eq(5); // вернет шестой по счету div-элемент с классом lBlock.

.slice(start,[end])

Возвращает элементы с индексами от start до end, если последний задан или до конца, если параметр end опущен.

Элементы с индексом start включаются в результат, а end нет

.slice(3,5) вернет элементы, идущие под номером 3 и 4, элемент с номером 5 включен не будет.
// вернет все div-элементы, начиная с четвертого (с индексами 3, 4, ...).
$("div").slice(3);
// вернет div-элементы с индексами 3 и 4.
$("div").slice(3, 5);
В этом примере часть элементов div окрашивается в желтый цвет случайным образом.
function colorEm() {
var $div = $("div");
var start = Math.floor(Math.random() * $div.length);
var end = Math.floor(Math.random() * ($div.length - start)) + start + 1;
if (end == $div.length) end = undefined;
$div.css("background", "");
if (end) {
    $div.slice(start, end).css("background", "yellow");
} else {
    $div.slice(start).css("background", "yellow");
}
$("span").text('$("div").slice(' + start + (end ? ', ' + end : '') + ').css("background", "yellow");');
}
$("button").click(colorEm);
Откройте пример в новом окне и посмотрите исходный код

.filter(selector)

Фильтрует набор элементов, оставляя только те, которые удовлетворяют селектору selector.

.filter(function(index))

Фильтрует набор элементов c помощью заданной функции.

Эта функция вызывается отдельно, для каждого из выбранных элементов.

Если она возвращает true, то текущий элемент будет включен в конечный результат.
Сами элементы доступны в функции, в переменной $(this), а их порядковые номера в наборе — в переменной index.

В этом примере мы выбираем все элементы div и устанавливаем им одинаковый фоновый цвет. Но только для элементов div, которые имеют класс с именем "middle" мы устанавливаем еще и рамку красного цвета.
$("div").css("background", "#c8ebcc")
  .filter(".middle")
  .css("border-color", "red");
Откройте пример в новом окне и посмотрите исходный код


В этом примере мы изменяем цвет всех элементов div и затем добавляем двойную рамку красного цвета только тем из них, кто удовлетворяет требованиям.
Т.е. элементу с индексом равным 1 и элементу, который имеет атрибут id="fourth".
$("div").css("background", "#b4b0da")
  .filter(function (index) {
    return index == 1 || $(this).attr("id") == "fourth";
  })
  .css("border", "3px double red");
Откройте пример в новом окне и посмотрите исходный код

.first()

Возвращает первый элемент из всех выбранных. Эквивалентно .eq(0)
$("div").first(); //вернет первый div-элемент на странице.
$("div.bigBlock").first(); //вернет первый div-элемент с классом bigBlock.

.last()

Возвращает последний элемент из всех выбранных. Эквивалентно .eq(-1)
$("div").last(); //вернет последний div-элемент на странице.
$("div.bigBlock").last(); //вернет последний div-элемент с классом bigBlock.

.has(selector | DOM element)

Фильтрует набор выбранных элементов, оставляя только те, которые имеют потомков, соответствующих заданному selector.
// вернет div-элементы, внутри которых есть элементы p (параграфы).
$("div").has("p");
// вернет div-элементы, внутри которых есть элементы с классом lBlock.	
$("div").has(".lBlock");	
// вернет с классом lBlock, внутри которых есть div-элементы.
$(.lBlock).has("div");
Выделим списки, которые содержат в себе элементы с классом stop:
$("ul").has(".stop").css("background-color", "yellow");
Откройте пример в новом окне и посмотрите исходный код

.is(selector)

Проверяет, удовлетворяет ли заданному селектору хотя бы один из выбранных элементов.

В примере показано несколько возможных вариантов использования is() внутри обработчика события.
$("section div").click(function() {
  if ($(this).is(":first-child")) {
	$("p").text("Это первый элемент div.");
  } else if ($(this).is(".blue,.red")) {
	$("p").text("Это синий или красный элемент div.");
  } else if ($(this).is(":contains('Петя')")) {
	$("p").text("Это Петя!");
  } else {
	$("p").html("А это ничего <em>особенного</em>.");
  }
  $("p").hide().slideDown("slow");
  $(this).css({"border-style": "inset", cursor:"default"});
});
Откройте пример в новом окне и посмотрите исходный код

.is(jQuery object):boolean

Проверяет, есть ли среди выбранных элементов, хотя бы один из элементов заданного объекта jQuery.

.is(elem):boolean

Проверяет, есть ли среди выбранных элементов, элемент elem (задается объектом DOM-элемента).

.is(function(index)):boolean

Для каждого из выбранных элементов, будет вызываться заданная функция.

В качестве параметра, она будет получать номер позиции элемента в в наборе, сам элемент будет доступен в переменной $(this).

Функция должна возвращать true или false.
Если хотя бы на одном из выбранных элементов будет возвращено значение true, то .is() тоже вернет true.
Иначе, метод .is() возвратит false

.not(selector)

Исключает из набора те элементы, которые соответствуют селектору selector.

.not(DOM elements)

Исключает из набора элемент(ы), заданные объектом DOM или массивом DOM-объектов.

.not(function(index))

Фильтрует набор элементов c помощью заданной функции.
Эта функция вызывается отдельно, для каждого из выбранных элементов.
Если она возвращает true, то текущий элемент будет исключен из конечного результата.
Сами элементы доступны в функции, в переменной $(this), а их порядковые номера в наборе — в переменной index.
//вернет div-элементы не имеющие класса bigBlock.
$("div").not(".bigBlock"); 
//вернет div-элементы класса bigBlock, без идентификатора area.
$("div.bigBlock").not("#area"); 
В примере добавляем красную рамку всем элементам div, кроме div зеленого или синего цвета.
$("div").not(".green, #blueone")
  .css("border-color", "red");
Откройте пример в новом окне и посмотрите исходный код

Обход набора

.each(callback(index, domElement))

Выполняет заданную функцию для каждого из выбранных элементов в отдельности.
Это дает возможность обрабатывать выбранные элементы отдельно друг от друга.

Узнаем высоту всех div-элементов на странице:
var heights = [];  // переменная, которая будет хранить высоты элементов
 
$("div").each(function(indx, element){
  heights.push($(element).height());
});
 
// в итоге, в переменную heights будут помещены 
// значения высот всех div-элементов
Нужно отметить, что переменная this, внутри функции callback, будет хранить то же самое значение, что и второй параметр domElement, который в нее передается.

Таким образом, предыдущий пример мог выглядеть следующим образом:
var heights = [];  // переменная, которая будет хранить высоты элементов
 
$("div").each(function(indx){
  heights.push($(this).height());
});
 
// в итоге, в переменную heights будут помещены значения высот всех div-элементов

.map(callback(index, domElement))

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

Значения, полученные в результате выполнения этой функции образуют новый набор в виде объекта jQuery, именно его и возвращает метод map.

Обычно, объект jQuery представляет группу элементов страницы, однако, метод map возвращает объект jQuery, включающий в себя величины любых типов javascript: объектов, строк, чисел, функций и.т.д.

Применение стандартных методов к такому нестандартно укомплектованному объекту может вызвать ошибки выполнения, поэтому надежнее будет конвертировать его в массив, например с помощью метода .get()

Найдем классы всех div-элементов на странице:
var classes = $("div").map(function(indx, element){
  return $(element).attr("class");
});
в результате, переменной classes будет присвоен объект jQuery, содержащий список всех классов у div-элементов.

Правильнее будет конвертировать его в массив:
var arr = classes.get();
В следующем примере, найдем предков второго уровня у всех элементов с классом box (т.е. родителей их родителей):
var nonno = $(".box").map(function(indx, element){
  return $(element).parent().parent();
});
Поскольку результатом работы функции будет список элементов страницы, конвертировать его в массив не нужно.

В этом примере мы строим список всех значений формы и добавляем его в элемент p.
$("p").append( $("input").map(function(){
  return $(this).val();
}).get().join(", ") );
Откройте пример в новом окне и посмотрите исходный код