Приём данных с помощью входных параметров

При использовании компонента часто требуется передать ему какие-либо данные. Компонент указывает принимаемые данные, объявляя входные параметры:

import {Component, input} from '@angular/core';

@Component({
  /*...*/
})
export class CustomSlider {
  // Declare an input named 'value' with a default value of zero.
  value = input(0);
}

Это позволяет привязываться к свойству в шаблоне:

<custom-slider [value]="50" />

Если входной параметр имеет значение по умолчанию, TypeScript выводит тип из этого значения:

@Component({
  /*...*/
})
export class CustomSlider {
  // TypeScript infers that this input is a number, returning InputSignal<number>.
  value = input(0);
}

Вы можете явно объявить тип входного параметра, указав обобщённый параметр функции.

Если для входного параметра без значения по умолчанию не задано значение, его значением будет undefined:

@Component({
  /*...*/
})
export class CustomSlider {
  // Produces an InputSignal<number | undefined> because `value` may not be set.
  value = input<number>();
}

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

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

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

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

Чтение входных параметров

Функция input возвращает InputSignal. Вы можете прочитать значение, вызвав сигнал:

import {Component, input, computed} from '@angular/core';

@Component({
  /*...*/
})
export class CustomSlider {
  // Declare an input named 'value' with a default value of zero.
  value = input(0);

  // Create a computed expression that reads the value input
  label = computed(() => `The slider's value is ${this.value()}`);
}

Сигналы, созданные функцией input, доступны только для чтения.

Обязательные входные параметры

Вы можете объявить входной параметр required, вызвав input.required вместо input:

@Component({
  /*...*/
})
export class CustomSlider {
  // Declare a required input named value. Returns an `InputSignal<number>`.
  value = input.required<number>();
}

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

Для обязательных входных параметров undefined автоматически не включается в обобщённый параметр возвращаемого значения InputSignal.

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

Функция input принимает объект конфигурации в качестве второго параметра, позволяющий изменить поведение входного параметра.

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

Вы можете указать функцию transform, чтобы изменять значение входного параметра при его установке Angular.

@Component({
  selector: 'custom-slider',
  /*...*/
})
export class CustomSlider {
  label = input('', {transform: trimString});
}

function trimString(value: string | undefined): string {
  return value?.trim() ?? '';
}

<custom-slider [label]="systemVolume" />

В приведённом выше примере при каждом изменении значения systemVolume Angular запускает trimString и задаёт label результатом её выполнения.

Чаще всего преобразования входных параметров используют, чтобы принимать в шаблонах более широкий диапазон типов значений, в том числе null и undefined.

Функция преобразования входного параметра должна статически анализироваться во время сборки. Нельзя задавать функции преобразования условно или в результате вычисления выражения.

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

Проверка типов

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

@Component({
  /*...*/
})
export class CustomSlider {
  widthPx = input('', {transform: appendPx});
}

function appendPx(value: number): string {
  return `${value}px`;
}

В приведённом выше примере входной параметр widthPx принимает number, а свойство InputSignal возвращает string.

Встроенные преобразования

В Angular есть две встроенные функции преобразования для двух наиболее распространённых случаев: приведения значений к типам boolean и number.

import {Component, input, booleanAttribute, numberAttribute} from '@angular/core';

@Component({
  /*...*/
})
export class CustomSlider {
  disabled = input(false, {transform: booleanAttribute});
  value = input(0, {transform: numberAttribute});
}

booleanAttribute имитирует поведение стандартных HTML-логических атрибутов, где о значении «true» свидетельствует наличие атрибута. Однако booleanAttribute в Angular воспринимает строку "false" как логическое значение false.

numberAttribute пытается преобразовать заданное значение в число и возвращает NaN, если преобразование не удалось.

Псевдонимы входных параметров

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

@Component({
  /*...*/
})
export class CustomSlider {
  value = input(0, {alias: 'sliderValue'});
}

<custom-slider [sliderValue]="50" />

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

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

Модельные входные параметры

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

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

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

@Component({
  /* ... */
})
export class CustomSlider {
  // Define a model input named "value".
  value = model(0);

  increment() {
    // Update the model input with a new value, propagating the value to any bindings.
    this.value.update((oldValue) => oldValue + 10);
  }
}

@Component({
  /* ... */
  // Using the two-way binding syntax means that any changes to the slider's
  // value automatically propagate back to the `volume` signal.
  // Note that this binding uses the signal *instance*, not the signal value.
  template: `<custom-slider [(value)]="volume" />`,
})
export class MediaControls {
  // Create a writable signal for the `volume` local state.
  volume = signal(0);
}

В приведённом выше примере CustomSlider может записывать значения в свой модельный входной параметр value, который передаёт эти значения обратно сигналу volume в MediaControls. Эта привязка синхронизирует значения value и volume. Обратите внимание: привязка передаёт экземпляр сигнала volume, а не его значение.

В остальном модельные входные параметры работают так же, как обычные. Вы можете прочитать значение, вызвав функцию сигнала, в том числе в реактивных контекстах, например в computed и effect.

Дополнительные сведения о двусторонней привязке в шаблонах см. в разделе «Двусторонняя привязка».

Двусторонняя привязка обычных свойств

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

@Component({
  /* ... */
  // `value` is a model input.
  // The parenthesis-inside-square-brackets syntax (aka "banana-in-a-box") creates a two-way binding
  template: '<custom-slider [(value)]="volume" />',
})
export class MediaControls {
  protected volume = 0;
}

В приведённом выше примере CustomSlider может записывать значения в свой модельный входной параметр value, который передаёт эти значения обратно свойству volume в MediaControls. Эта привязка синхронизирует значения value и volume.

Неявные события изменения

Когда вы объявляете модельный входной параметр в компоненте или директиве, Angular автоматически создаёт для этой модели соответствующий выходной параметр. Его имя совпадает с именем модельного входного параметра с суффиксом «Change».

@Directive({
  /* ... */
})
export class CustomCheckbox {
  // This automatically creates an output named "checkedChange".
  // Can be subscribed to using `(checkedChange)="handler()"` in the template.
  checked = model(false);
}

Angular генерирует это событие изменения при каждой записи нового значения в модельный входной параметр с помощью методов set или update.

Дополнительные сведения о выходных параметрах см. в разделе «Пользовательские события с выходными параметрами».

Настройка модельных входных параметров

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

Для модельных входных параметров не поддерживаются преобразования.

Когда использовать модельные входные параметры

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

Выбор имён входных параметров

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

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

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

В качестве альтернативы можно объявить входные параметры компонента, добавив декоратор @Input к свойству:

@Component({
  /*...*/
})
export class CustomSlider {
  @Input() value = 0;
}

Привязка к входному параметру одинакова как для параметров на основе сигналов, так и для параметров на основе декораторов:

<custom-slider [value]="50" />

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

Декоратор @Input принимает объект конфигурации, позволяющий изменить поведение входного параметра.

Обязательные входные параметры

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

@Component({
  /*...*/
})
export class CustomSlider {
  @Input({required: true}) value = 0;
}

Если попытаться использовать компонент, не указав все его обязательные входные параметры, Angular сообщит об ошибке во время сборки.

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

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

@Component({
  selector: 'custom-slider',
  ...
})
export class CustomSlider {
  @Input({transform: trimString}) label = '';
}

function trimString(value: string | undefined) {
  return value?.trim() ?? '';
}

Псевдонимы входных параметров

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

@Component({
  /*...*/
})
export class CustomSlider {
  @Input({alias: 'sliderValue'}) value = 0;
}

<custom-slider [sliderValue]="50" />

Декоратор @Input также принимает псевдоним в качестве первого параметра вместо объекта конфигурации.

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

Входные параметры с геттерами и сеттерами

При использовании входных параметров на основе декораторов входным параметром может быть свойство, реализованное с помощью геттера и сеттера:

export class CustomSlider {
  @Input()
  get value(): number {
    return this.internalValue;
  }

  set value(newValue: number) {
    this.internalValue = newValue;
  }

  private internalValue = 0;
}

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

export class CustomSlider {
  @Input()
  set value(newValue: number) {
    this.internalValue = newValue;
  }

  private internalValue = 0;
}

По возможности предпочитайте преобразования входных параметров геттерам и сеттерам.

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

Указание входных параметров в декораторе @Component

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

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

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

// `CustomSlider` inherits the `disabled` property from `BaseSlider`.
@Component({
  ...,
  inputs: ['disabled: sliderDisabled'],
})
export class CustomSlider extends BaseSlider { }