Улучшить эту документацию Просмотреть исходный код ngRepeat

директива в модуле ng

Обзор

Директива ngRepeat создает шаблон один раз для каждого элемента из коллекции. Каждый экземпляр шаблона получает собственный контекст, где переменная цикла принимает текущий элемент коллекции, а $index — индекс или ключ элемента.

Специальные свойства доступны в локальном контексте каждого экземпляра шаблона, включая:

Переменная	Тип	Подробности
`$index`	`number`	смещение итератора для повторяемого элемента (0..длина-1)
`$first`	`boolean`	true, если повторяемый элемент — первый в итерации.
`$middle`	`boolean`	true, если повторяемый элемент находится между первым и последним в итерации.
`$last`	`boolean`	true, если повторяемый элемент — последний в итерации.
`$even`	`boolean`	true, если позиция итератора `$index` чётная (иначе false).
`$odd`	`boolean`	true, если позиция итератора `$index` нечётная (иначе false).

Создание псевдонимов для этих свойств возможно с помощью ngInit. Это может быть полезно, например, при вложенных ngRepeat.

Итерация по свойствам объекта

Возможна итерация по свойствам объекта с помощью следующего синтаксиса:

<div ng-repeat="(key, value) in myObj"> ... </div>

Однако есть несколько ограничений по сравнению с итерацией по массивам:

Спецификация JavaScript не определяет порядок возвращаемых ключей для объекта, поэтому AngularJS полагается на порядок, возвращаемый браузером при выполнении for key in myObj. Браузеры обычно следуют стратегии предоставления ключей в том порядке, в котором они были определены, хотя есть исключения, когда ключи удаляются и восстанавливаются. См. страницу MDN о delete для получения дополнительной информации.
ngRepeat будет молча игнорировать ключи объекта, начинающиеся с $, потому что это префикс, используемый AngularJS для публичных ($) и приватных ($$) свойств.
Встроенные фильтры orderBy и filter не работают с объектами и выдадут ошибку при использовании с ними.

Если вы сталкиваетесь с этими ограничениями, рекомендуется преобразовать свой объект в массив, отсортированный в желаемом порядке, прежде чем передавать его в ngRepeat. Это можно сделать с помощью фильтра, такого как toArrayFilter, или реализовать $watch для объекта самостоятельно.

Отслеживание и дубликаты

ngRepeat использует $watchCollection для обнаружения изменений в коллекции. При изменении ngRepeat вносит соответствующие изменения в DOM:

При добавлении элемента добавляется новый экземпляр шаблона в DOM.
При удалении элемента его экземпляр шаблона удаляется из DOM.
При изменении порядка элементов соответствующие шаблоны изменяют свой порядок в DOM.

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

Все типы функций отслеживания, их синтаксис и поддержка дубликатов в коллекциях можно найти в описании выражения ngRepeat.

Рекомендация: Если вы работаете с объектами, имеющими уникальное свойство идентификатора, вы должны отслеживать по этому идентификатору, а не по экземпляру объекта, например, item in items track by item.id. Если позже вы перезагрузите данные, ngRepeat не придётся перестраивать элементы DOM для уже отрисованных элементов, даже если JavaScript-объекты в коллекции были заменены новыми. Для больших коллекций это значительно улучшает производительность отрисовки.

Последствия повторного использования элементов DOM

При повторном использовании элементов DOM ngRepeat обновляет контекст для элемента, что автоматически обновит любые активные привязки в шаблоне. Однако другая функциональность не будет обновлена, так как элемент не пересоздаётся:

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

Вышесказанное влияет на все виды повторного использования элементов из-за отслеживания, но особенно заметно при отслеживании по $index из-за способа повторного использования элементов ngRepeat.

Следующий пример демонстрирует влияние различных действий с отслеживанием:

Специальные точки начала и конца повторения

Для повторения серии элементов, а не только одного родительского элемента, ngRepeat (как и другие ng-директивы) поддерживает расширение диапазона повторения, определяя явные точки начала и конца с помощью ng-repeat-start и ng-repeat-end соответственно. Директива ng-repeat-start работает так же, как ng-repeat, но будет повторять весь HTML-код (включая тег, в котором она определена) до и включая закрывающий HTML-тег, где находится ng-repeat-end.

Пример ниже использует эту функцию:

<header ng-repeat-start="item in items">
  Header {{ item }}
</header>
<div class="body">
  Body {{ item }}
</div>
<footer ng-repeat-end>
  Footer {{ item }}
</footer>

И с входными данными ['A','B'] для переменной items в примере выше, вывод будет:

<header>
  Header A
</header>
<div class="body">
  Body A
</div>
<footer>
  Footer A
</footer>
<header>
  Header B
</header>
<div class="body">
  Body B
</div>
<footer>
  Footer B
</footer>

Пользовательские точки начала и конца для ngRepeat также поддерживают все другие варианты синтаксиса HTML-директивы, предоставляемые AngularJS (такие как data-ng-repeat-start, x-ng-repeat-start и ng:repeat-start).

END_OF_DOCUMENT_MARKER

Информация о директиве

Данная директива создает новый контекст.
Данная директива выполняется на приоритетном уровне 1000.
Данная директива может использоваться как multiElement

Использование

в качестве атрибута:

<ANY
  ng-repeat="repeat_expression">
...
</ANY>

Аргументы

Параметр Тип Подробности

ngRepeat

Параметр	Тип	Подробности
ngRepeat	`repeat_expression`	Выражение, указывающее, как перечислить коллекцию. В настоящее время поддерживаются следующие форматы: `variable in expression` – где переменная — это определяемая пользователем переменная цикла, а `expression` — выражение контекста, предоставляющее коллекцию для перечисления. Например: `album in artist.albums`. `(key, value) in expression` – где `key` и `value` могут быть любыми определяемыми пользователем идентификаторами, а `expression` — выражение контекста, предоставляющее коллекцию для перечисления. Например: `(name, age) in {'adam':10, 'amalie':12}`. `variable in expression track by tracking_expression` – Вы также можете указать необязательное выражение отслеживания, которое можно использовать для сопоставления объектов в коллекции с элементами DOM. Если выражение отслеживания не указано, ng-repeat сопоставляет элементы по идентичности. Ошибка возникает, если более чем одно значение выражения отслеживания разрешается на один и тот же ключ. (Это означало бы, что два различных объекта сопоставляются с одним и тем же элементом DOM, что невозможно.) По умолчанию отслеживание: $id(): `item in items` эквивалентно `item in items track by $id(item)`. Это означает, что элементы DOM будут сопоставляться по идентичности элементов в коллекции. Встроенная функция `$id()` может использоваться для назначения уникального свойства `$$hashKey` каждому элементу в коллекции. Это свойство затем используется в качестве ключа для сопоставления элементов DOM с соответствующим элементом в коллекции по идентичности. Перемещение одного и того же объекта переместит элемент DOM таким же образом в DOM. Обратите внимание, что функция id по умолчанию не поддерживает дубликаты примитивных значений (`number`, `string`), но поддерживает дубликаты не примитивных значений (`object`), которые равны по форме. Пользовательское выражение: можно использовать любое выражение AngularJS для вычисления идентификатора отслеживания, например, с функцией или используя свойство элементов коллекции. `item in items track by item.id` — типичная схема, когда элементы имеют уникальный идентификатор, например, идентификатор базы данных. В этом случае идентичность объекта не имеет значения. Два объекта считаются эквивалентными, если их свойство `id` одинаково. Отслеживание по уникальному идентификатору — самый производительный метод и должно использоваться всякий раз, когда это возможно. $index: Это специальное свойство отслеживает элементы коллекции по их индексу и повторно использует элементы DOM, которые соответствуют этому индексу, например, `item in items track by $index`. Это может быть использовано для повышения производительности, если уникальный идентификатор недоступен и идентичность элементов коллекции нельзя легко вычислить. Это также позволяет дубликаты. Примечание: повторное использование элементов DOM может иметь непредвиденные последствия. Прочитайте раздел об отслеживании и дубликатах для получения дополнительной информации. Примечание: выражение `track by` должно быть последним — после всех фильтров и выражения псевдонима: `item in items \| filter:searchText as results track by item.id` `variable in expression as alias_expression` – Вы также можете указать необязательное выражение псевдонима, которое будет хранить промежуточные результаты повторяющегося блока после применения фильтров. Обычно это используется для отображения специального сообщения, когда на повторяющемся блоке активен фильтр, но отфильтрованный результат пуст. Например: `item in items \| filter:x as results` будет хранить фрагмент повторяющихся элементов как `results`, но только после обработки элементов через фильтр. Обратите внимание, что `as [variable name]` не является оператором, а скорее частью микро-синтаксиса ngRepeat, поэтому он может использоваться только после всех фильтров (а не как оператор внутри выражения). Например: `item in items \| filter : x \| orderBy : order \| limitTo : limit as results track by item.id` .

repeat_expression

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

variable in expression – где переменная — это определяемая пользователем переменная цикла, а expression — выражение контекста, предоставляющее коллекцию для перечисления.

Например: album in artist.albums.
(key, value) in expression – где key и value могут быть любыми определяемыми пользователем идентификаторами, а expression — выражение контекста, предоставляющее коллекцию для перечисления.

Например: (name, age) in {'adam':10, 'amalie':12}.
variable in expression track by tracking_expression – Вы также можете указать необязательное выражение отслеживания, которое можно использовать для сопоставления объектов в коллекции с элементами DOM. Если выражение отслеживания не указано, ng-repeat сопоставляет элементы по идентичности. Ошибка возникает, если более чем одно значение выражения отслеживания разрешается на один и тот же ключ. (Это означало бы, что два различных объекта сопоставляются с одним и тем же элементом DOM, что невозможно.)

По умолчанию отслеживание: $id(): item in items эквивалентно item in items track by $id(item). Это означает, что элементы DOM будут сопоставляться по идентичности элементов в коллекции.

Встроенная функция $id() может использоваться для назначения уникального свойства $$hashKey каждому элементу в коллекции. Это свойство затем используется в качестве ключа для сопоставления элементов DOM с соответствующим элементом в коллекции по идентичности. Перемещение одного и того же объекта переместит элемент DOM таким же образом в DOM. Обратите внимание, что функция id по умолчанию не поддерживает дубликаты примитивных значений (number, string), но поддерживает дубликаты не примитивных значений (object), которые равны по форме.

Пользовательское выражение: можно использовать любое выражение AngularJS для вычисления идентификатора отслеживания, например, с функцией или используя свойство элементов коллекции. item in items track by item.id — типичная схема, когда элементы имеют уникальный идентификатор, например, идентификатор базы данных. В этом случае идентичность объекта не имеет значения. Два объекта считаются эквивалентными, если их свойство id одинаково. Отслеживание по уникальному идентификатору — самый производительный метод и должно использоваться всякий раз, когда это возможно.

$index: Это специальное свойство отслеживает элементы коллекции по их индексу и повторно использует элементы DOM, которые соответствуют этому индексу, например, item in items track by $index. Это может быть использовано для повышения производительности, если уникальный идентификатор недоступен и идентичность элементов коллекции нельзя легко вычислить. Это также позволяет дубликаты.

Примечание: повторное использование элементов DOM может иметь непредвиденные последствия. Прочитайте раздел об отслеживании и дубликатах для получения дополнительной информации.

Примечание: выражение track by должно быть последним — после всех фильтров и выражения псевдонима: item in items | filter:searchText as results track by item.id
variable in expression as alias_expression – Вы также можете указать необязательное выражение псевдонима, которое будет хранить промежуточные результаты повторяющегося блока после применения фильтров. Обычно это используется для отображения специального сообщения, когда на повторяющемся блоке активен фильтр, но отфильтрованный результат пуст.

Например: item in items | filter:x as results будет хранить фрагмент повторяющихся элементов как results, но только после обработки элементов через фильтр.

Обратите внимание, что as [variable name] не является оператором, а скорее частью микро-синтаксиса ngRepeat, поэтому он может использоваться только после всех фильтров (а не как оператор внутри выражения).

Например: item in items | filter : x | orderBy : order | limitTo : limit as results track by item.id .

Анимации

Анимация	Происходит
enter	при добавлении нового элемента в список или при раскрытии элемента после фильтрации
leave	при удалении элемента из списка или при исключении элемента из фильтра
move	при исключении смежного элемента, вызывающего перестановку, или при перестановке содержимого элемента

См. пример ниже для определения CSS-анимаций с помощью ngRepeat.

Нажмите здесь для получения дополнительной информации о шагах, участвующих в анимации.

Пример

В этом примере используется ngRepeat для отображения списка людей. Фильтр используется для ограничения отображаемых результатов по имени или возрасту. Новые (входящие) и удаленные (выходящие) элементы анимируются.

© 2010–2020 Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
https://code.angularjs.org/1.8.2/docs/api/ng/directive/ngRepeat