Component — Angular | Spec-Zone.ru

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

API

@ Component({
  changeDetection?: ChangeDetectionStrategy | undefined;
  viewProviders?: Provider[] | undefined;
  templateUrl?: string | undefined;
  template?: string | undefined;
  styleUrl?: string | undefined;
  styleUrls?: string[] | undefined;
  styles?: string | string[] | undefined;
  animations?: any[] | undefined;
  encapsulation?: ViewEncapsulation | undefined;
  preserveWhitespaces?: boolean | undefined;
  standalone?: boolean | undefined;
  imports?: (readonly any[] | Type<any>)[] | undefined;
  schemas?: SchemaMetadata[] | undefined;
  override selector?: string | undefined;
  override inputs?:
    | (
        | string
        | {
            name: string;
            alias?: string | undefined;
            required?: boolean | undefined;
            transform?: ((value: any) => any) | undefined;
          }
      )[]
    | undefined;
  override outputs?: string[] | undefined;
  override providers?: Provider[] | undefined;
  override exportAs?: string | undefined;
  override queries?: { [key: string]: any } | undefined;
  override host?: { [key: string]: string } | undefined;
  override jit?: true | undefined;
  override hostDirectives?:
    | (
        | Type<unknown>
        | {
            directive: Type<unknown>;
            inputs?: string[] | undefined;
            outputs?: string[] | undefined;
          }
      )[]
    | undefined;
})

changeDetection

ChangeDetectionStrategy | undefined

Стратегия обнаружения изменений, используемая для этого компонента.

При создании экземпляра компонента Angular создаёт детектор изменений, отвечающий за передачу привязок компонента. Возможны следующие стратегии:

ChangeDetectionStrategy#OnPush задаёт стратегию CheckOnce (по запросу).
ChangeDetectionStrategy#Eager задаёт стратегию CheckAlways.

ПРИМЕЧАНИЕ: По умолчанию включён режим OnPush.

viewProviders

Provider[] | undefined

Определяет набор внедряемых объектов, доступных дочерним элементам DOM-представления. См. пример.

templateUrl

string | undefined

Относительный путь или абсолютный URL файла шаблона компонента Angular. Если это свойство задано, не указывайте встроенный шаблон с помощью template.

template

string | undefined

Встроенный шаблон компонента Angular. Если это свойство задано, не указывайте файл шаблона с помощью templateUrl.

styleUrl

string | undefined

Относительный путь или абсолютный URL файла с таблицей стилей CSS для этого компонента.

styleUrls

string[] | undefined

Относительные пути или абсолютные URL файлов с таблицами стилей CSS для этого компонента.

styles

string | string[] | undefined

Одна или несколько встроенных таблиц стилей CSS для этого компонента.

animations

any[] | undefined

Один или несколько вызовов trigger() анимации, содержащих определения state() и transition(). См. руководство по анимации и документацию API анимации.

encapsulation

ViewEncapsulation | undefined

Политика инкапсуляции стилей компонента. Возможные значения:

ViewEncapsulation.Emulated: применяет изменённые стили компонента, чтобы эмулировать поведение инкапсуляции CSS в нативном Shadow DOM.
ViewEncapsulation.None: применяет стили компонента глобально, без какой-либо инкапсуляции.
ViewEncapsulation.ShadowDom: использует нативный API Shadow DOM браузера для инкапсуляции стилей.

Если значение не указано, оно берётся из CompilerOptions, для которого по умолчанию задано ViewEncapsulation.Emulated.

Если задана политика ViewEncapsulation.Emulated, а у компонента нет ни styles, ни styleUrls, политика автоматически переключается на ViewEncapsulation.None.

preserveWhitespaces

boolean | undefined

Значение true сохраняет, а false удаляет потенциально избыточные пробельные символы из скомпилированного шаблона. Пробельными считаются символы, соответствующие классу символов \s в регулярных выражениях JavaScript. По умолчанию задано значение false, если оно не переопределено в параметрах компилятора.

standalone

boolean | undefined

Установите standalone в значение false, если хотите импортировать директиву в NgModule.

imports

(readonly any[] | Type<any>)[] | undefined

Свойство imports задаёт зависимости шаблона автономного компонента — директивы, компоненты и каналы, которые можно использовать в его шаблоне. Автономные компоненты могут импортировать другие автономные компоненты, директивы и каналы, а также существующие NgModule.

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

schemas

SchemaMetadata[] | undefined

Набор схем, определяющих элементы, допустимые в автономном компоненте. Элементы и свойства, которые не являются компонентами или директивами Angular, необходимо объявить в схеме.

selector

string | undefined

Селектор CSS, который идентифицирует эту директиву в шаблоне и инициирует её создание.

Задайте один из следующих вариантов:

element-name: выбор по имени элемента.
.class: выбор по имени класса.
[attribute]: выбор по имени атрибута.
[attribute=value]: выбор по имени и значению атрибута.
:not(sub_selector): выбор, только если элемент не соответствует sub_selector.
selector1, selector2: выбор, если соответствует selector1 или selector2.

Angular разрешает директивам применяться только к селекторам CSS, не пересекающим границы элементов.

В следующем HTML шаблона директива с селектором input[type=text] будет создана только для элемента <input type="text">.

<form>
  <input type="text">
  <input type="radio">
<form>

inputs

(string | { name: string; alias?: string | undefined; required?: boolean | undefined; transform?: ((value: any) => any) | undefined; })[] | undefined

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

Angular автоматически обновляет входные свойства во время обнаружения изменений. Свойство inputs принимает строки или литералы объектов, задающие свойства директивы, доступные в качестве входных.

Если передан литерал объекта, свойство name указывает, в какое свойство класса должны записываться входные данные, а alias определяет имя, под которым входные данные будут доступны в привязках шаблона. Свойство required указывает, что входные данные обязательны; если при использовании директивы они не переданы, во время компиляции возникнет ошибка.

Если в массив inputs передана строка, она может иметь формат 'name' или 'name: alias', где name — свойство класса, в которое директива должна записывать данные, а alias определяет имя, под которым входные данные будут доступны в привязках шаблона. Строковые определения входных данных считаются необязательными.

outputs

string[] | undefined

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

Когда выходное свойство генерирует событие, вызывается обработчик этого события, указанный в шаблоне.

Свойство outputs задаёт набор directiveProperty для конфигурации alias:

directiveProperty указывает свойство компонента, генерирующее события.
alias указывает свойство DOM, к которому привязан обработчик события.

providers

Provider[] | undefined

Настраивает инжектор этой директивы или компонента с помощью токена, связанного с поставщиком зависимости.

exportAs

string | undefined

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

queries

{ [key: string]: any; } | undefined

Настраивает запросы, которые будут внедрены в директиву.

Запросы содержимого устанавливаются до вызова обратного вызова ngAfterContentInit. Запросы представления устанавливаются до вызова обратного вызова ngAfterViewInit.

host

{ [key: string]: string; } | undefined

Связывает свойства класса со свойствами, атрибутами и событиями элемента-хоста с помощью набора пар «ключ-значение».

Angular автоматически проверяет привязки свойств хоста во время обнаружения изменений. Если привязка изменяется, Angular обновляет элемент-хост директивы.

Если ключ является свойством элемента-хоста, его значение передаётся указанному свойству DOM.

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

Для обработки событий:

Ключ — это событие DOM, которое отслеживает директива. Для добавления префикса к имени события можно использовать глобальные цели document:, window: и body:.
Значение — это инструкция, выполняемая при возникновении события. Если результатом инструкции является false, к событию DOM применяется preventDefault. В методе-обработчике можно использовать локальную переменную $event.

jit

true | undefined

Если этот параметр указан, AOT-компилятор игнорирует данную директиву или компонент. Элемент остаётся в распространяемом коде, а JIT-компилятор пытается скомпилировать его во время выполнения в браузере. Для правильной работы приложение должно импортировать @angular/compiler.

hostDirectives

(Type<unknown> | { directive: Type<unknown>; inputs?: string[] | undefined; outputs?: string[] | undefined; })[] | undefined

Автономные директивы, которые должны применяться к хосту при каждом совпадении с директивой. По умолчанию входные и выходные данные директив-хостов недоступны на хосте, если они не указаны в свойствах inputs или outputs.

Кроме того, входные и выходные данные можно переименовать, добавив двоеточие и псевдоним после исходного имени. Например, если директива, применённая через hostDirectives, определяет входное свойство с именем menuDisabled, его можно переименовать в disabled, добавив 'menuDisabled: disabled' в качестве элемента в inputs.

Описание

Компоненты — это основные строительные блоки пользовательского интерфейса приложения Angular. Приложение Angular состоит из дерева компонентов Angular.

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

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

Обратите внимание: помимо этих параметров настройки директивы, поведение компонента во время выполнения можно контролировать с помощью реализации хуков жизненного цикла. Дополнительную информацию см. в руководстве «Хуки жизненного цикла».

ПОЛЕЗНО: Этот интерфейс нельзя использовать для описания класса-компонента. Декораторы не влияют на типизацию декорируемых классов. Используйте Type<unknown> вместо Type<Component>.

Примечания по использованию

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

В следующем примере создаётся компонент с двумя свойствами, связанными с данными и заданными значением inputs.

@Component({
  selector: 'app-bank-account',
  inputs: ['bankName', 'id: account-id'],
  template: ` Bank Name: {{ bankName }} Account Id: {{ id }} `,
})
export class BankAccountComponent {
  bankName: string | null = null;
  id: string | null = null;

  // this property is not bound, and won't be automatically updated by Angular
  normalizedBankName: string | null = null;
}

@Component({
  selector: 'app-my-input',
  template: ` <app-bank-account bankName="RBC" account-id="4747" /> `,
  imports: [BankAccountComponent],
})
export class MyInputComponent {}

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

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

@Directive({
  selector: 'app-interval-dir',
})
export class IntervalDirComponent {
  everySecond = output<string>();
  everyFiveSeconds = output<string>();

  constructor() {
    setInterval(() => this.everySecond.emit('event'), 1000);
    setInterval(() => this.everyFiveSeconds.emit('event'), 5000);
  }
}

@Component({
  selector: 'app-my-output',
  template: `
    <app-interval-dir (everySecond)="onEverySecond()" (everyFiveSeconds)="onEveryFiveSeconds()" />
  `,
  imports: [IntervalDirComponent],
})
export class MyOutputComponent {
  onEverySecond() {
    console.log('second');
  }
  onEveryFiveSeconds() {
    console.log('five seconds');
  }
}

Внедрение класса с помощью поставщика представления

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

class Greeter {
   greet(name:string) {
     return 'Hello ' + name + '!';
   }
}

@Directive({
  selector: 'needs-greeter'
})
class NeedsGreeter {
  greeter:Greeter;

  constructor(greeter:Greeter) {
    this.greeter = greeter;
  }
}

@Component({
  selector: 'greet',
  viewProviders: [
    Greeter
  ],
  template: `<needs-greeter></needs-greeter>`
})
class HelloWorld {
}

Сохранение пробелов

Удаление пробелов может значительно уменьшить размер кода, сгенерированного AOT-компилятором, и ускорить создание представлений. Начиная с Angular 6 значение preserveWhitespaces по умолчанию равно false (пробелы удаляются). Чтобы изменить значение по умолчанию для всех компонентов приложения, задайте параметр preserveWhitespaces AOT-компилятора.

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

Удаляет все пробелы в начале и в конце шаблона.
Удаляет текстовые узлы, состоящие только из пробелов. Например:

<button>Action 1</button>  <button>Action 2</button>

преобразуется в:

<button>Action 1</button><button>Action 2</button>

Заменяет последовательность пробельных символов в текстовых узлах одним пробелом. Например, <span>\n some text\n</span> преобразуется в <span> some text </span>.
Не изменяет текстовые узлы внутри HTML-тегов, таких как <pre> или <textarea>, где пробельные символы имеют значение.

Обратите внимание: эти преобразования могут повлиять на расположение узлов DOM, хотя влияние должно быть минимальным.

Поведение по умолчанию можно переопределить, чтобы сохранять пробельные символы в отдельных фрагментах шаблона. Например, можно исключить всё поддерево DOM с помощью атрибута ngPreserveWhitespaces:

<div ngPreserveWhitespaces>
    whitespaces are preserved here
    <span>    and here </span>
</div>

Можно сохранить один пробел в текстовом узле с помощью &ngsp;, который компилятор шаблонов Angular заменяет символом пробела:

<a>Spaces</a>&ngsp;<a>between</a>&ngsp;<a>links.</a>
<!-- compiled to be equivalent to:
 <a>Spaces</a> <a>between</a> <a>links.</a>  -->

Обратите внимание: при значении параметра preserveWhitespaces, равном false, последовательности &ngsp; по-прежнему сворачиваются в один пробел.

<a>before</a>&ngsp;&ngsp;&ngsp;<a>after</a>
<!-- compiled to be equivalent to:
 <a>before</a> <a>after</a> -->

Чтобы сохранить последовательности пробельных символов, используйте атрибут ngPreserveWhitespaces.