Пользовательские события с выходными событиями

Компоненты Angular могут определять пользовательские события, присваивая свойству функцию output:

@Component({
  /*...*/
})
export class ExpandablePanel {
  panelClosed = output<void>();
}

<expandable-panel (panelClosed)="savePanelState()" />

Функция output возвращает OutputEmitterRef. Чтобы отправить событие, вызовите метод emit у OutputEmitterRef:

this.panelClosed.emit();

Angular называет свойства, инициализированные функцией output, выходными событиями. С помощью выходных событий можно создавать пользовательские события, похожие на встроенные события браузера, например click.

Пользовательские события Angular не всплывают по DOM.

Имена выходных событий чувствительны к регистру.

При наследовании от класса компонента выходные события наследуются дочерним классом.

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

Передача данных события

При вызове emit можно передать данные события:

// You can emit primitive values.
this.valueChanged.emit(7);

// You can emit custom event objects
this.thumbDropped.emit({
  pointerX: 123,
  pointerY: 456,
});

При определении обработчика события в шаблоне можно получить данные события из переменной $event:

<custom-slider (valueChanged)="logValue($event)" />

Получите данные события в родительском компоненте:

@Component({
 /*...*/
})
export class App {
  logValue(value: number) {
    ...
  }
}

Настройка имен выходных событий

Функция output принимает параметр, позволяющий указать другое имя события в шаблоне:

@Component({
  /*...*/
})
export class CustomSlider {
  changed = output({alias: 'valueChanged'});
}

<custom-slider (valueChanged)="saveVolume()" />

Этот псевдоним не влияет на использование свойства в коде TypeScript.

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

Программная подписка на выходные события

При динамическом создании компонента можно программно подписаться на события выходных событий экземпляра компонента. Тип OutputRef включает метод subscribe:

const someComponentRef: ComponentRef<SomeComponent> = viewContainerRef.createComponent(/*...*/);

someComponentRef.instance.someEventProperty.subscribe((eventData) => {
  console.log(eventData);
});

Angular автоматически удаляет подписки на события при уничтожении компонентов с подписчиками. Также можно отписаться от события вручную. Функция subscribe возвращает OutputRefSubscription с методом unsubscribe:

const eventSubscription = someComponent.someEventProperty.subscribe((eventData) => {
  console.log(eventData);
});

// ...

eventSubscription.unsubscribe();

Выбор имен событий

Не выбирайте для выходных событий имена, совпадающие с именами событий DOM-элементов, например HTMLElement. Совпадение имен затрудняет понимание того, относится ли привязанное свойство к компоненту или к DOM-элементу.

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

Всегда используйте для имен выходных событий camelCase. Не добавляйте к именам выходных событий префикс «on».

Использование выходных событий с RxJS

Подробнее о взаимодействии выходных событий с RxJS см. в разделе Взаимодействие RxJS с выходными событиями компонентов и директив.

Объявление выходных событий с помощью декоратора @Output

Также можно определять пользовательские события, присвоив свойству новый экземпляр EventEmitter и добавив декоратор @Output:

@Component({
  /*...*/
})
export class ExpandablePanel {
  @Output() panelClosed = new EventEmitter<void>();
}

Чтобы отправить событие, вызовите метод emit у EventEmitter.

Псевдонимы с декоратором @Output

Декоратор @Output принимает параметр, позволяющий указать другое имя события в шаблоне:

@Component({
  /*...*/
})
export class CustomSlider {
  @Output('valueChanged') changed = new EventEmitter<number>();
}

<custom-slider (valueChanged)="saveVolume()" />

Этот псевдоним не влияет на использование свойства в коде TypeScript.

Указание выходных событий в декораторе @Component

Помимо декоратора @Output, выходные события компонента можно указать с помощью свойства outputs декоратора @Component. Это может быть полезно, если компонент наследует свойство от базового класса:

// `CustomSlider` inherits the `valueChanged` property from `BaseSlider`.
@Component({
  /*...*/
  outputs: ['valueChanged'],
})
export class CustomSlider extends BaseSlider {}

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

// `CustomSlider` inherits the `valueChanged` property from `BaseSlider`.
@Component({
  /*...*/
  outputs: ['valueChanged: volumeChanged'],
})
export class CustomSlider extends BaseSlider {}