Пайпы

Обзор

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

Вот пример использования некоторых встроенных пайпов Angular:

import {Component} from '@angular/core';
import {CurrencyPipe, DatePipe, TitleCasePipe} from '@angular/common';

@Component({
  selector: 'app-root',
  imports: [CurrencyPipe, DatePipe, TitleCasePipe],
  template: `
    <main>
      <!-- Transform the company name to title-case and
       transform the purchasedOn date to a locale-formatted string -->
      <h1>Purchases from {{ company | titlecase }} on {{ purchasedOn | date }}</h1>

      <!-- Transform the amount to a currency-formatted string -->
      <p>Total: {{ amount | currency }}</p>
    </main>
  `,
})
export class ShoppingCart {
  amount = 123.45;
  company = 'acme corporation';
  purchasedOn = '2024-07-08';
}

При отображении компонента Angular использует соответствующий формат даты и валюты, основанный на локали пользователя. Если пользователь находится в США, результат будет таким:

<main>
  <h1>Purchases from Acme Corporation on Jul 8, 2024</h1>
  <p>Total: $123.45</p>
</main>

Подробнее о локализации значений в Angular читайте в подробном руководстве по i18n.

Встроенные пайпы

Angular включает набор встроенных пайпов в пакете @angular/common:

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

В операторе пайпа Angular в выражении шаблона используется символ вертикальной черты (|). Оператор пайпа — бинарный оператор: левый операнд — это значение, передаваемое функции преобразования, а правый операнд — имя пайпа и любые дополнительные аргументы (описаны ниже).

<p>Total: {{ amount | currency }}</p>

В этом примере значение amount передаётся в CurrencyPipe, имя которого — currency. Затем отображается валюта, установленная по умолчанию для локали пользователя.

Использование нескольких пайпов в одном выражении

К значению можно применить несколько преобразований, используя несколько операторов пайпа. Angular выполняет пайпы слева направо.

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

<p>The event will occur on {{ scheduledOn | date | uppercase }}.</p>

Передача параметров пайпам

Некоторые пайпы принимают параметры для настройки преобразования. Чтобы указать параметр, добавьте после имени пайпа двоеточие (:), а затем значение параметра.

Например, DatePipe принимает параметры для форматирования даты заданным способом.

<p>The event will occur at {{ scheduledOn | date: 'hh:mm' }}.</p>

Некоторые пайпы могут принимать несколько параметров. Дополнительные значения параметров можно указать через символ двоеточия (:).

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

<p>The event will occur at {{ scheduledOn | date: 'hh:mm' : 'UTC' }}.</p>

Как работают пайпы

Концептуально пайпы — это функции, которые принимают входное значение и возвращают преобразованное значение.

import {Component} from '@angular/core';
import {CurrencyPipe} from '@angular/common';

@Component({
  selector: 'app-root',
  imports: [CurrencyPipe],
  template: `
    <main>
      <p>Total: {{ amount | currency }}</p>
    </main>
  `,
})
export class AppComponent {
  amount = 123.45;
}

В этом примере:

1. CurrencyPipe импортируется из @angular/common
2. CurrencyPipe добавляется в массив imports
3. Данные amount передаются пайпу currency

Приоритет оператора пайпа

Приоритет оператора пайпа ниже, чем у других бинарных операторов, включая +, -, *, /, %, &&, || и ??.

<!-- firstName and lastName are concatenated before the result is passed to the uppercase pipe -->
{{ firstName + lastName | uppercase }}

Приоритет оператора пайпа выше, чем у условного (тернарного) оператора.

{{ (isAdmin ? 'Access granted' : 'Access denied') | uppercase }}

Если бы то же выражение было записано без скобок:

{{ isAdmin ? 'Access granted' : 'Access denied' | uppercase }}

Оно было бы разобрано следующим образом:

{{ isAdmin ? 'Access granted' : ('Access denied' | uppercase) }}

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

Обнаружение изменений при использовании пайпов

По умолчанию все пайпы считаются pure, то есть выполняются только при изменении примитивного входного значения (например, String, Number, Boolean или Symbol) или ссылки на объект (например, Array, Object, Function или Date). Чистые пайпы повышают производительность, поскольку Angular может не вызывать функцию преобразования, если переданное значение не изменилось.

В результате изменения свойств объектов или элементов массивов не обнаруживаются, если только ссылка на весь объект или массив не заменена ссылкой на другой экземпляр. Если вам требуется такое обнаружение изменений, см. раздел обнаружение изменений в массивах или объектах.

Создание пользовательских пайпов

Чтобы определить пользовательский пайп, реализуйте класс TypeScript с декоратором @Pipe. У пайпа должны быть две характеристики:

• Имя, указанное в декораторе пайпа
• Метод с именем transform, выполняющий преобразование значения.

Кроме того, класс TypeScript должен реализовывать интерфейс PipeTransform, чтобы соответствовать сигнатуре типа пайпа.

Вот пример пользовательского пайпа, который преобразует строки в kebab case:

// kebab-case.pipe.ts
import {Pipe, PipeTransform} from '@angular/core';

@Pipe({
  name: 'kebabCase',
})
export class KebabCasePipe implements PipeTransform {
  transform(value: string): string {
    return value.toLowerCase().replace(/ /g, '-');
  }
}

Использование декоратора @Pipe

При создании пользовательского пайпа импортируйте Pipe из пакета @angular/core и используйте его как декоратор класса TypeScript.

import {Pipe} from '@angular/core';

@Pipe({
  name: 'myCustomTransformation',
})
export class MyCustomTransformationPipe {}

Декоратору @Pipe требуется name, определяющий, как пайп используется в шаблоне.

Соглашение об именовании пользовательских пайпов

Соглашение об именовании пользовательских пайпов включает два правила:

• name — рекомендуется использовать camelCase. Не используйте дефисы.
• class name — версия name в PascalCase с добавлением Pipe в конце

Реализация интерфейса PipeTransform

Помимо декоратора @Pipe, пользовательские пайпы всегда должны реализовывать интерфейс PipeTransform из @angular/core.

import {Pipe, PipeTransform} from '@angular/core';

@Pipe({
  name: 'myCustomTransformation',
})
export class MyCustomTransformationPipe implements PipeTransform {}

Реализация этого интерфейса гарантирует, что класс пайпа имеет правильную структуру.

Преобразование значения в пайпе

Каждое преобразование выполняется методом transform: первый параметр — переданное значение, а возвращаемое значение — результат преобразования.

import {Pipe, PipeTransform} from '@angular/core';

@Pipe({
  name: 'myCustomTransformation',
})
export class MyCustomTransformationPipe implements PipeTransform {
  transform(value: string): string {
    return `My custom transformation of ${value}.`;
  }
}

Добавление параметров в пользовательский пайп

Чтобы добавить параметры для преобразования, добавьте дополнительные параметры в метод transform:

import {Pipe, PipeTransform} from '@angular/core';

@Pipe({
  name: 'myCustomTransformation',
})
export class MyCustomTransformationPipe implements PipeTransform {
  transform(value: string, format: string): string {
    let msg = `My custom transformation of ${value}.`;

    if (format === 'uppercase') {
      return msg.toUpperCase();
    } else {
      return msg;
    }
  }
}

Обнаружение изменений в массивах или объектах

Чтобы пайп обнаруживал изменения внутри массивов или объектов, его нужно пометить как нечистую функцию, передав флаг pure со значением false.

import {Pipe, PipeTransform} from '@angular/core';

@Pipe({
  name: 'joinNamesImpure',
  pure: false,
})
export class JoinNamesImpurePipe implements PipeTransform {
  transform(names: string[]): string {
    return names.join();
  }
}

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