Создание и использование кастомных pipe в Angular

Зачем использовать pipes в Angular

Pipes — это декорированные функции преобразования, которые применяются прямо в шаблонах Angular. Они помогают:

• Разделять логику форматирования от представления.
• Писать декларативные шаблоны: {{ value | myPipe }}.
• Переиспользовать преобразования в разных компонентах.

Краткое определение: pipe — функция, реализующая интерфейс PipeTransform и возвращающая преобразованное значение.

Подготовка проекта

Перед созданием кастомных pipe убедитесь, что у вас установлен Angular CLI и рабочая среда Node.js. Если CLI ещё не установлен, выполните в терминале:

npm install -g @angular/cli

Создайте новый проект Angular (если нужно):

ng new my-app

Перейдите в каталог проекта и откройте его в IDE.

Создание кастомного pipe

Сгенерируйте файл pipe с помощью CLI:

ng generate pipe customPipe

Команда создаст файлы custom-pipe.pipe.ts и custom-pipe.pipe.spec.ts в src/app. В файле custom-pipe.pipe.ts вы увидите заготовку вида:

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

@Pipe({
  name: 'customPipe'
})
export class CustomPipePipe implements PipeTransform {
  transform(value: unknown, ...args: unknown[]): unknown {
    return null;
  }
}

Эта заготовка подключает декоратор Pipe и требует реализовать метод transform. Параметры transform: value — входное значение, args — дополнительные аргументы.

Заменим заготовку реализацией, которая разбивает строку на массив символов:

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

@Pipe({
  name: 'customPipe'
})
export class CustomPipePipe implements PipeTransform {
  transform(value: string): string[] {
    return value.split('');
  }
}

Примечание по типам: здесь transform принимает строку и возвращает string[]. В реальных задачах указывайте точные типы и обрабатывайте null/undefined.

Подключение pipe в модуле

Чтобы pipe был доступен в шаблонах, импортируйте и объявите его в AppModule. Откройте src/app/app.module.ts и добавьте класс pipe в declarations:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';
import { CustomPipePipe } from './custom-pipe.pipe';

@NgModule({
  declarations: [
    AppComponent,
    CustomPipePipe
  ],
  imports: [
    BrowserModule,
    AppRoutingModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Теперь можно использовать pipe в шаблонах.

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

Откройте src/app/app.component.html и добавьте пример использования:

{{ 'apple' | customPipe }}

Обратите внимание: имя pipe в декораторе — ‘customPipe’, и в шаблоне оно указывается в нижнем регистре так, как вы его объявили. Регистр важен.

Тестирование и запуск

Запустите dev-сервер Angular:

ng serve

Откройте в браузере http://localhost:4200 — вы должны увидеть результат работы pipe (в данном примере — массив символов).

Когда кастомный pipe не подходит

• Если преобразование зависит от внешнего состояния или сервера — лучше использовать сервисы или подписки на Observable.
• Для сложной логики с большим количеством условий удобнее написать метод в компоненте.
• Для операций, влияющих на производительность, избегайте вычислений в pipe при каждом цикле обнаружения изменений (см. советы по производительности ниже).

Альтернативные подходы

• Методы компонента: удобны для локальной логики, но портят декларативность шаблона.
• Сервисы, возвращающие Observable: полезно при асинхронных данных.
• pure vs impure pipe: по возможности делайте pipe чистыми (pure), чтобы Angular кэшировал результат.

Ментальные модели и эвристики

• Pipe = чистая функция отображения вход → выход (при чистом pipe).
• Чем проще pipe — тем легче его тестировать и поддерживать.
• Используйте pipe для форматирования/фильтрации, но не для изменений состояния.

Советы по производительности

• По умолчанию pipe — pure. Pure pipe вызывается только при изменении входного аргумента.
• Сделайте pipe impure только если он зависит от внешних данных; impure pipe вызывается на каждом цикле обнаружения изменений и может замедлить приложение.
• Кэшируйте дорогостоящие вычисления внутри pipe или используйте memoization в сервисе.

Критерии приёмки

• Pipe объявлен в модуле и доступен в шаблонах.
• Типы входных/выходных данных указаны и обработаны null/undefined.
• Unit-тесты покрывают базовые случаи и граничные состояния.
• Pipe остаётся чистым, если это возможно (pure: true).

Тест-кейсы и примеры приёмки

1. Вход: ‘apple’ — ожидаемый выход: [‘a’,’p’,’p’,’l’,’e’].
2. Вход: ‘’ — ожидаемый выход: [].
3. Вход: null/undefined — ожидаемая реакция: безопасное поведение (например, [] или null по контракту).
4. Негативный кейс: объект вместо строки — проверка на выброс ошибки или корректную обработку.

Чек-лист по ролям

• Developer:
  • Реализовать pipe с типами и проверками.
  • Добавить unit-тесты и документировать контракт.
• Reviewer:
  • Проверить pure/impure статус.
  • Оценить влияние на производительность.
• QA:
  • Протестировать граничные значения и интеграцию в шаблон.

Мини-методология разработки pipe

1. Определите контракт: вход/выход, что делать с null.
2. Напишите простую реализацию как pure pipe.
3. Добавьте unit-тесты для типичных и граничных кейсов.
4. Измерьте производительность при необходимости.
5. Документируйте использование в README модуля.

Шпаргалка: быстрые подсказки

• Генерация: ng generate pipe myPipe
• Сигнатура: implements PipeTransform { transform(value: T, …args): R }
• Объявление: добавить в declarations AppModule
• Использование: {{ value | myPipe:arg1:arg2 }}

Примеры расширений pipe

• Фильтрация массива: items | filterBy:’name’:query
• Форматирование дат с локалью: value | customDate:’dd.MM.yyyy’
• Комбинация: {{ someValue | customPipe | uppercase }}

Безопасность и приватность

Pipes не должны инжектировать или раскрывать конфиденциальные данные. Если pipe форматирует данные из внешних источников, убедитесь, что данные проверены и экранированы в шаблонах по необходимости.

Факт-бокс: ключевые идеи

• Pipes — декларативный способ преобразования в шаблонах.
• По умолчанию они pure и кешируются Angular.
• Для побочных эффектов используйте сервисы, а не pipe.

1-line glossary

• Pipe: функция преобразования, реализующая PipeTransform и применяемая в шаблоне через знак |.

Заключение

Pipes — безопасный и удобный инструмент для отделения логики форматирования от представления. Создание кастомных pipe в Angular простое: сгенерируйте файл, реализуйте transform, зарегистрируйте в модуле и используйте в шаблонах. Всегда учитывайте производительность и выбирайте pure/impure с умом.

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