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

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

Обзор

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

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

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

Создание псевдонимов для этих свойств возможно с помощью 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).

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

Эта директива создаёт новую область видимости.
Эта директива выполняется на уровне приоритета 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.6.9/docs/api/ng/directive/ngRepeat