NgForOf

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

Предупреждение об устаревании

Вместо этого используйте блок @for. Директиву планируется удалить в одном из следующих крупных выпусков

API

class NgForOf<T, U extends NgIterable<T> = NgIterable<T>> implements DoCheck {
  constructor(_viewContainer: ViewContainerRef, _template: TemplateRef<NgForOfContext<T, U>>, _differs: IterableDiffers): NgForOf<T, U>;
  @Input() set ngForOf(value: (U & NgIterable<T>) | null | undefined);
  @Input() get ngForTrackBy(): TrackByFunction<T>;
  @Input() set ngForTemplate(value: TemplateRef<NgForOfContext<T, U>>);
  static ngTemplateContextGuard<T, U extends NgIterable<T>>(dir: NgForOf<T, U>, ctx: any): ctx is NgForOfContext<T, U>;
}

constructor

NgForOf<T, U>

@param_viewContainerViewContainerRef

@param_templateTemplateRef<NgForOfContext<T, U>>

@param_differsIterableDiffers

@returnsNgForOf<T, U>

(U & NgIterable<T>) | null | undefined

@deprecated

Директива ngFor устарела. Вместо неё используйте блок @for.

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

ngForTrackBy

TrackByFunction<T>

@deprecated

Директива ngFor устарела. Вместо неё используйте блок @for.

Задаёт пользовательскую функцию TrackByFunction для вычисления идентификаторов элементов в итерируемой коллекции.

Если пользовательская функция TrackByFunction не задана, NgForOf будет использовать в качестве ключа идентичность объекта.

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

Пользовательская функция TrackByFunction полезна для улучшения взаимодействия с пользователем, если элементы итерируемой коллекции, отображаемые с помощью NgForOf, имеют естественный идентификатор (например, пользовательский ID или первичный ключ), а коллекция может обновиться новыми экземплярами объектов, представляющими те же сущности (например, когда данные повторно загружаются с сервера, итерируемая коллекция создаётся и отображается заново, но большая часть данных остаётся прежней).

ngForTrackBy

TrackByFunction<T>

ngForTemplate

TemplateRef<NgForOfContext<T, U>>

@deprecated

Директива ngFor устарела. Вместо неё используйте блок @for.

Ссылка на шаблон, который создаётся для каждого элемента итерируемой коллекции.

ngTemplateContextGuard

ctx is NgForOfContext<T, U>

Проверяет правильность типа контекста для шаблона, который будет отображён директивой NgForOf.

Наличие этого метода служит сигналом для компилятора проверки типов шаблонов Ivy о том, что структурная директива NgForOf отображает шаблон с определённым типом контекста.

@paramdirNgForOf<T, U>

@paramctxany

@returnsctx is NgForOfContext<T, U>

Описание

Директива ngForOf обычно используется в сокращённой форме *ngFor. В этой форме шаблоном, который отображается на каждой итерации, становится содержимое элемента-якоря с директивой.

В следующем примере показан сокращённый синтаксис с несколькими параметрами внутри элемента <li>.

<li *ngFor="let item of items; index as i; trackBy: trackByFn">...</li>

Сокращённая форма разворачивается в полную форму, в которой селектор ngForOf используется на элементе <ng-template>. Содержимое элемента <ng-template> — это элемент <li>, в котором находилась директива сокращённой формы.

Ниже показан пример сокращённой формы после разворачивания.

<ng-template ngFor let-item [ngForOf]="items" let-i="index" [ngForTrackBy]="trackByFn">
  <li>...</li>
</ng-template>

Angular автоматически разворачивает сокращённый синтаксис при компиляции шаблона. Контекст каждого встроенного представления логически объединяется с контекстом текущего компонента в соответствии с его лексическим положением.

При использовании сокращённого синтаксиса Angular разрешает размещать на элементе только одну структурную директиву. Чтобы, например, выполнить условную итерацию, разместите *ngIf на элементе-контейнере, оборачивающем элемент *ngFor. Подробнее см. в разделе «Структурные директивы».

Экспортируется из

CommonModule

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

Локальные переменные

NgForOf предоставляет экспортируемые значения, которым можно присвоить псевдонимы локальных переменных. Например:

<li *ngFor="let user of users; index as i; first as isFirst">
   {{i}}/{{users.length}}. {{user}} <span *ngIf="isFirst">default</span>
</li>

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

$implicit: T: значение отдельного элемента итерируемой коллекции (ngForOf).
ngForOf: NgIterable<T>: значение итерируемого выражения. Полезно, если выражение сложнее, чем обращение к свойству, например при использовании async pipe (userStreams | async).
index: number: индекс текущего элемента в итерируемой коллекции.
count: number: длина итерируемой коллекции.
first: boolean: значение true, если элемент является первым в итерируемой коллекции.
last: boolean: значение true, если элемент является последним в итерируемой коллекции.
even: boolean: значение true, если индекс элемента в итерируемой коллекции чётный.
odd: boolean: значение true, если индекс элемента в итерируемой коллекции нечётный.

Распространение изменений

Когда содержимое итератора меняется, NgForOf вносит соответствующие изменения в DOM:

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

Angular использует идентичность объектов для отслеживания добавления и удаления элементов в итераторе и отражает эти изменения в DOM. Это важно для анимации и любых элементов управления с состоянием, например элементов <input>, которые принимают пользовательский ввод. Добавленные строки можно анимировать при появлении, удалённые — при исчезновении, а неизменившиеся строки сохраняют несохранённое состояние, например пользовательский ввод. Подробнее об анимации см. в разделе «Переходы и триггеры».

Идентификаторы элементов в итераторе могут измениться, даже если сами данные не меняются. Такое может произойти, например, если итератор формируется на основе RPC-запроса к серверу и этот запрос выполняется повторно. Даже если данные не изменились, во втором ответе будут объекты с другими идентификаторами, и Angular придётся удалить весь DOM и создать его заново (как если бы все старые элементы были удалены, а все новые — добавлены).

Чтобы избежать этой затратной операции, можно настроить алгоритм отслеживания по умолчанию, передав параметр trackBy в NgForOf. trackBy принимает функцию с двумя аргументами: index и item. Если задан trackBy, Angular отслеживает изменения по возвращаемому функцией значению.