Всем привет! Я Александр Бухтатый, frontend-разработчик в Тинькофф, специализируюсь на Angular. Наша команда работает в монорепозитории с четырьмя проектами. В каждом проекте много форм, нужно сопровождать их и создавать новые.
В статье покажу один из способов работы с формами в Angular-проектах, который упрощает создание новых форм и изолирует зависимость от внешней UI-библиотеки. Будет мало текста и много кода, пристегните ремни, мы начинаем.
Определили проблемы
Мы используем Taiga UI, но можно делать обертки и под другие UI-библиотеки, принцип оберток никак не зависит от той, что вы используете. Taiga UI — хороший и гибкий инструмент для разработки, но при использовании любой UI-библиотеки есть своя цена.
Зависимость. Большая зависимость от UI-библиотеки при обновлении мажорной версии приведет к куче рефакторинга во всех формах всех проектов монорепозитория. При создании поля в форме нужно применить множество разных компонентов, каждый из которых служит поводом вернутся и внести правки в код с полем формы.
Например, если изменятся контракты tui-error, придется вносить правки во все поля всех форм на проекте. Обертки делают инверсию зависимостей, и наши формы зависят от оберток, а те, в свою очередь, зависят от внешней UI-библиотеки.
Такой подход защищает от обратно несовместимых правок в UI-библиотеке и уменьшает количество работы по переходу на ее новую версию.
Много бойлерплейта, который нужно писать для реализации форм при помощи унифицированной UI-библиотеки.
Дублирование кода. К каждому полю нужно дописывать tui-error и вспомогательные вещи типа шаблонов или компонентов для работы со списком. Видно в примерах предыдущей проблемы.
Сложно добавлять новое поле в форму — много усилий и постоянное обращение к справке UI-библиотеки.
Чтобы применить тот же комбобокс, нужно скопировать пример, донастроить, обратиться к документации и так далее. С обертками достаточно будет скопировать нужный вариант и реализовать метод получения отфильтрованного списка. Появится отдельный модуль со всем, что нужно для работы с формами, который позволяет посмотреть доступные поля, варианты, валидаторы, маски и директивы сразу в IDE.
Нашли решение
Думая над обозначенными проблемами, мы осознали, что решение все это время было рядом — и это инкапсуляция.
Мы составили список работ:
Завернуть все связанное с формами в один модуль.
Реализовать обертки полей форм так, чтобы с ними было удобно работать, и с возможностью создавать для них варианты. Вариант — конфигурация поля формы через директиву. Он нужен для удобства переиспользования одного и того же поля с разными настройками.
Реализовать вспомогательные инструменты для работы с обертками полей формы, чтобы упростить работу с полями.
Приступили к реализации
Модуль нужен для того, чтобы хранить все связанное с формами в одном месте, это помогает снизить количество дублей, служит хорошей документацией по тому, что нам доступно для работы с формами.
Компоненты модуля содержат:
Core — все вспомогательные классы.
Controls — пользовательские компоненты с реализацией ControlValueAccessor.
Fields — обертки полей формы и их варианты.
Masks — каталог доступных масок для полей формы.
Validators — различные валидаторы для полей формы.
Обертка поля формы — это компонент с удобным интерфейсом, инкапсулирующий в себя весь бойлерплейт из UI-библиотек. С оберткой можно работать как с компонентом, реализующим ControlValueAccessor, то есть используя Angular-директивы ngModel, FormControl, FormControlName.
Преимущества использования обертки:
Улучшаем читаемость кода.
Снижаем количество бойлерплейта.
Ускоряем разработку за счет переиспользования готовых оберток и их вариантов.
Изолируем зависимость от внешней UI-библиотеки.
Сначала создаем вспомогательный класс, который упростит разработку новых оберток для полей. Базовый класс обертки:
@Directive()
export class FormFieldBase implements OnInit, OnDestroy, ControlValueAccessor {
control!: FormControl;
private subscription!: Subscription;
constructor(
@Optional() @Self() public ngControl: NgControl
) {
if (this.ngControl != null) {
this.ngControl.valueAccessor = this;
}
}
writeValue(obj: any): void {}
registerOnChange(fn: (_: any) => void): void {}
registerOnTouched(fn: any): void {}
ngOnInit() {
if (!this.ngControl) throw new Error('ngControl is undefined');
if (this.ngControl instanceof FormControlName) {
this.control = this.ngControl.control;
} else if (this.ngControl instanceof FormControlDirective) {
this.control = this.ngControl.control;
} else if (this.ngControl instanceof NgModel) {
this.control = this.ngControl.control;
this.subscription = this.control.valueChanges.subscribe((x) =>
this.ngControl.viewToModelUpdate(this.control.value)
);
} else if (!this.ngControl) {
this.control = new FormControl();
}
}
ngOnDestroy() {
this.subscription?.unsubscribe();
}
}
После реализации базового класса можно создавать обертки. Пример обертки combobox.component.ts:
@Component({
selector: 'ngnx-form-field-combobox',
templateUrl: './form-field-combobox.component.html',
styleUrls: ['./form-field-combobox.component.scss'],
standalone: true,
imports: [
TuiComboBoxModule,
ReactiveFormsModule,
TuiDataListWrapperModule,
TuiErrorModule,
TuiFieldErrorPipeModule,
AsyncPipe,
JsonPipe
]
})
export class FormFieldComboboxComponent<T> extends FormFieldBase {
private readonly itemsHandlers: TuiItemsHandlers<T> = inject(TUI_ITEMS_HANDLERS);
@Input()
items: any[] | null = null;
@Input()
identityMatcher: TuiItemsHandlers<T>['identityMatcher'] = this.itemsHandlers.identityMatcher;
@Input()
stringify: TuiItemsHandlers<T>['stringify'] = this.itemsHandlers.stringify;
@Input()
placeholder?: string = '';
@Input()
valueContent: PolymorpheusContent<TuiValueContentContext<T>> = new PolymorpheusComponent(DefaultOptionTemplateComponent);
@Input()
itemContent: PolymorpheusContent<TuiValueContentContext<T>> = new PolymorpheusComponent(DefaultOptionTemplateComponent);
@Output()
search$ = new ReplaySubject<string | null>();
}
Пример обертки combobox.component.html:
<tui-combo-box
[formControl]="control"
[identityMatcher]="identityMatcher"
[valueContent]="valueContent"
[stringify]="stringify"
(searchChange)="search$.next($event)"
>
<ng-content></ng-content>
<input
tuiTextfield
[placeholder]="placeholder"
/>
<tui-data-list-wrapper
*tuiDataList
[items]="items"
[itemContent]="itemContent"
></tui-data-list-wrapper>
</tui-combo-box>
<tui-error
[formControl]="control"
[error]="[] | tuiFieldError | async"
></tui-error>
Пример использования обертки Combobox — delivery-form.component.html:
<div [formGroup]="formGroup">
<div class="tui-form__row tui-form__row_multi-fields">
<div class="tui-form__multi-field">
<aff-combobox
formControlName="address"
[affComboboxDataProvider]="comboboxDataProvider"
[stringify]="comboboxStringify"
>
address
</aff-combobox>
</div>
...
</div>
Пример использования обертки Combobox — delivery-form.component.ts:
@Component({
selector: 'aff-delivery-form',
templateUrl: './delivery-form.component.html',
styleUrls: ['./delivery-form.component.less'],
})
export class DeliveryFormComponent extends FormGroupBase {
selectItemsWithHints = [
{id: '1', label: 'Label 1'},
{id: '2', label: 'Label 2'},
{id: '3', label: 'Label 3'},
{id: '4', label: 'Label 4'},
];
comboboxStringify(item: {label: string}): string {
return item.label;
}
comboboxDataProvider: ComboboxDataProvider<any> = (term: string) => {
const foundedItems = this.selectItemsWithHints.filter((item) => term == '' || item.label.toLowerCase() == term.toLowerCase() || item.label.toLowerCase().includes(term.toLowerCase()));
return foundedItems && foundedItems.length ? of(foundedItems) : of(null);
}
}
Некоторые поля формы имеют вариативность: например, выбор пользователя может быть просто по логину или по карточке пользователя с фото. Для таких случаев мы будем использовать варианты и шаблоны.
Шаблон — компоненты, которые отображаются в качестве частей оборачиваемого компонента. Реализация шаблона option-with-hint-content-template.component.ts:
export type OptionWithHint<T> = T & {
label: string;
hint: string;
};
@Component({
selector: 'aff-option-with-hint-content-template',
standalone: true,
imports: [CommonModule],
templateUrl: './option-with-hint-content-template.component.html',
styleUrls: ['./option-with-hint-content-template.component.scss'],
})
export class OptionWithHintContentTemplateComponent {
@Input('label') inputLabel?: string;
@Input('hint') inputHint?: string;
get label(): string {
return this.optionWithHintMapperDirectiveRef?.mapper?.label(this.context?.$implicit) || this.context?.$implicit?.label || this.inputLabel || '-';
}
get hint(): string {
return this.optionWithHintMapperDirectiveRef?.mapper?.hint(this.context?.$implicit) || this.context?.$implicit?.hint || this.inputHint || '-';
}
constructor(
@Optional() private optionWithHintMapperDirectiveRef: OptionWithHintMapperDirective,
@Optional() @Inject(POLYMORPHEUS_CONTEXT) readonly context: { $implicit: OptionWithHint<any>, active: boolean }
) {
}
}
Реализация шаблона option-with-hint-content-template.component.html:
<div><b>{{label}}</b></div>
<div>{{hint}}</div>Вариант — директивы, агрегирующие другие директивы и переопределяющие поля компонента так, чтобы тот изменил свой внешний вид или даже поведение. Один вариант равен одному виду поля в макетах Figma.
Реализация варианта combobox-with-hint-variant.directive.ts:
@Directive({
selector: 'aff-combobox[withHint]',
standalone: true,
})
export class ComboboxWithHintVariantDirective<T> {
comboboxComponenRef = inject(ComboboxComponent<T>);
constructor() {
this.comboboxComponenRef.itemContent = new PolymorpheusComponent(
WithHintOptionTemplateComponent
);
this.comboboxComponenRef.valueContent = new PolymorpheusComponent(
WithHintValueTemplateComponent
);
}
}
Пример использования варианта для Combobox delivery-form.component.html:
<div [formGroup]="formGroup">
<div class="tui-form__row tui-form__row_multi-fields">
<div class="tui-form__multi-field">
<aff-combobox
formControlName="address"
withHint
[affComboboxDataProvider]="comboboxDataProvider"
[stringify]="comboboxStringify"
>
address
</aff-combobox>
</div>
...
</div>
Пример использования шаблона без директивы-варианта:
<div [formGroup]="formGroup">
<div class="tui-form__row tui-form__row_multi-fields">
<div class="tui-form__multi-field">
<aff-combobox
formControlName="address"
[affComboboxDataProvider]="comboboxDataProvider"
[stringify]="comboboxStringify"
[valueContent]="content"
[itemContent]="content"
>
address
</aff-combobox>
<ng-template #content let-data>
<aff-with-hint-option-template [label]="data.label" [hint]="data.hint"></aff-with-hint-option-template>
</ng-template>
</div>
...
</div>
Для удобной работы с разными обертками можно создавать директивы-помощники. Например, сделать директиву, в которую через Input передадим метод, возвращающий список доступных значений каждый раз при обновлении поисковой строки Combobox. Это нужно, чтобы не писать каждый раз логику с подпиской и прокидыванием результата в компонент через шаблон.
Реализация вспомогательной директивы будет такой:
export type ComboboxDataProvider<T> = (term: string) => Observable<Array<T> | null>;
@Directive({
selector: '[affComboboxDataProvider]',
standalone: true
})
export class ComboboxDataProviderDirective<T> implements OnInit, OnDestroy {
@Input('affComboboxDataProvider') dataFetchFn!: ComboboxDataProvider<T>;
comboboxComponenRef = inject(ComboboxComponent<T>);
private subscription!: Subscription;
ngOnInit() {
this.comboboxComponenRef.search$.pipe(
startWith(''),
filter((term: string | null) => term !== null),
switchMap((term: string | null) => this.dataFetchFn(term))
).subscribe({
next: (response) => this.comboboxComponenRef.items = response,
error: (error) => this.comboboxComponenRef.items = [],
})
}
ngOnDestroy() {
this.subscription?.unsubscribe();
}
}
Пример использования мы уже видели ранее в delivery-form.component.html и delivery-form.component.ts.
Мы можем сделать директивы, которые агрегируют в себе другие директивы, и обозвать их вариантом, чтобы не навешивать на наши обертки кучу директив. Можно по аналогии с директивами-контроллерами сделать директивы для схожих инпутов из разных компонентов.
Оборачиваются не только поля формы, но и части форм для переиспользования. Например, мы можем переиспользовать форму для обратной связи, форму с адресом, форму с реквизитами клиента и так далее.
Реализация вспомогательного класса form-group-base.class.ts:
@Directive()
export class FormGroupBase {
get formGroup(): FormGroup {
return this.controlContainer.control as FormGroup;
}
constructor(private controlContainer: ControlContainer) {}
}
Пример реализации переиспользуемой формы contacts-short-form.component.ts:
@Component({
selector: 'aff-contacts-short-form',
templateUrl: './contacts-short-form.component.html',
styleUrls: ['./contacts-short-form.component.less'],
})
export class ContactsShortFormComponent extends FormGroupBase {}
Пример реализации переиспользуемой формы contacts-short-form.component.html:
<div class="tui-form__row tui-form__row_multi-fields" [formGroup]="formGroup">
<div class="tui-form__multi-field">
<aff-input formControlName="name">Name</aff-input>
</div>
<div class="tui-form__multi-field">
<aff-phone formControlName="phone">Phone</aff-phone>
</div>
</div>Пример использования order-form.component.html:
<div class="tui-container tui-container_adaptive tui-space_top-8">
<h1>Pizza order form</h1>
<form [formGroup]="formGroup">
...
<h2 class="tui-space_top-8">Contacts</h2>
<aff-contacts-short-form formGroupName="contacts"></aff-contacts-short-form>
...
</form>
</div>Результаты и полезные ссылки
Создание оберток для всех компонентов Taiga UI заняло один рабочий день, потом пару недель мы обкатывали обертки на формах, с которыми работаем. После успешной обкатки решили целиком перейти на обертки — и не жалеем об этом.
У нас получилось:
Сократить время разработки.
Улучшить читаемость кода.
Сократить количество бойлерплейта — в среднем html-код сократился на 50%.
Создать единое место для всего связанного с формами, что снижает вероятность создания дублей.
Изолировать зависимость от внешней UI-библиотеки. Если произойдут критичные изменения в UI-библиотеке, мы будем править только обертки, а не все поля у форм во всех проектах монорепозитория.
Полезные ссылки:
github-репозиторий
Концепция директив-контроллеров для компонента в Angular (часть 1, часть 2)
Использование директив для расширения компонентов, которыми вы не владеете
Real world angular reactive form
Building-Up A Complex Objects Using A Multi-Step Form Workflow In ColdFusion
Split an Angular Reactive Form model into child components
A new way to validate Angular Forms
Если есть вопросы - буду рад обсудить в комментариях!
