Метод .pushStack()

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

Метод .pushStack() создаёт новую коллекцию jQuery и связывает её с предыдущей. Он полезен авторам плагинов обхода DOM: пользователь сможет продолжить цепочку и вернуться к исходному набору через .end().

Синтаксис

JavaScript

const next = collection.pushStack(elements);
const previous = next.end();

Параметры и возвращаемое значение

elements — массив DOM-элементов. Результат — новая коллекция jQuery; исходный набор остаётся прежним. Метод не вставляет узлы на страницу, не удаляет дубликаты и не сортирует переданный массив.

Для обычного поиска применяйте .find(), .filter() или .eq(): они уже поддерживают возврат по стеку. .pushStack() нужен, когда набор для собственного метода вычисляется иначе.

Особенности и совместимость

Не путайте его с Array.prototype.push(): он не дописывает элементы в исходный объект и не возвращает длину. В старых описаниях встречаются дополнительные служебные аргументы; в современном коде используйте форму с одним массивом.

В примере создаётся набор только из последнего элемента. Его .end() возвращает прежние три элемента, а порядок документа остаётся неизменным.

Документация

pushStack — jQuery API

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

Возврат к исходному набору: попробуйте сами

Новая коллекция содержит В, после .end() снова доступны А, Б и В. Используется jQuery 4.0.0.

index.html

HTML

<ul>
  <li>А</li>
  <li>Б</li>
  <li>В</li>
</ul>
<pre id="result"></pre>

main.js

JavaScript

const original = $('li')
const last = original.pushStack([original.get(-1)])
$('#result').text(last.text() + ' | ' + last.end().text() + ' | ' + original.length)