Улучшить эту документацию Просмотреть исходный код 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-код (включая тэг, в котором она определена) до и включая закрывающий тэг, где размещено 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).

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

Эта директива создаёт новую область видимости.
Эта директива выполняется на уровне приоритета 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. Обратите внимание, что функция идентификации по умолчанию не поддерживает дублирование примитивных значений (`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 [имя переменной]` не является оператором, а скорее частью микро-синтаксиса 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. Обратите внимание, что функция идентификации по умолчанию не поддерживает дублирование примитивных значений (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 [имя переменной]` не является оператором, а скорее частью микро-синтаксиса ngRepeat, поэтому его можно использовать только после всех фильтров (а не как оператора, внутри выражения).

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

Анимации

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

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

Нажмите здесь для получения дополнительной информации об этапах анимации.

Пример

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

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