Переход с AngularJS на Angular: цели, планы и правила переноса элементов (1/3)06.02.2018 14:33

Если в модуле, в котором что-то начинаем апгрейдить, нет модуля ангуляра, то создаём его и цепляем в основной модуль приложения:

import {NgModule} from "@angular/core";

@NgModule({
  //
});
export class SmthModule {}

@NgModule({
  imports: [
    ...
    SmthModule,
  ],
});
export class AppModule {}

Если ангуляржс модуль ещё остаётся живым, то новый именуем с постфиксом .new. Выпиливаем постфикс вместе со старым модулем ангуляржса.

В хорошем случае добавляем декоратор, убираем default из экспорта, правим импорты (т.к. убрали дефолт), импортируем в ангуляр модуле, даунгрейдим в ангуряржс модуле:

import {Injectable} from "@angular/core";

@Injectable()
export class SmthService {
  ...
}

// angular module
@NgModule({
  providers: [
    ...
    SmthService,
  ],
});

// angularjs module
import {downgradeInjectable} from "@angular/upgrade/static";

...
  .factory("vim.smth", downgradeInjectable(SmthService))

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

Хороший вариант подразумевает: все инжектуные сервисы уже переехали на ангуляр, не используются какие-то специфические вещи по типу templateCache или compiler.

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

Докидываем к контроллеру декоратор с мета-данными, проставляем декораторы инпутам/аутпутам и переносим их в начало класса:

import {Component, Input, Output, EventEmitter} from "@angular/core";

@Component({
  // селектор через `-` как будет использоваться в шаблоне, а не camelCase
  selector: "vim-smth",
  // при сборке специальный лоадер заменит на require("./smth.html")
  templateUrl: "smth.html",
})
export class SmthComponent {
  @Input() smth1: string;

  @Output() smthAction = new EventEmitter();

  ...
}

// angular module
@NgModule({
  declarations: [
    ...
    SmthComponent,
  ],
  // дублируем сюда если компонент используется в компонентах других модулей, иначе он будет доступен только компонентам этого модуля
  exports: [
    ...
    SmthComponent,
  ],
});

// angularjs module
import {downgradeInjectable} from "@angular/upgrade/static";

...
  .directive("vimSmth", downgradeComponent({ component: SmthComponent }) as ng.IDirectiveFactory)

Все инжекнутые сервисы, все require компоненты (как их цеплять — ниже во Всякое) и все компоненты/директивы/фильтры, используемые внутри шаблона, должны быть на ангуляре.

Все используемые в шаблоне переменные компонента должны быть объявлены как public, иначе упадёт на AoT сборке.

Если компонент получает все данные для вывода из компонента выше (через инпуты), то смело пишем ему в мета-данные changeDetection: ChangeDetectionStrategy.OnPush. Это говорит ангуляру, что синкать шаблон с данными (пускать change detection для этого компонента) он будет, только если изменится любой из инпутов компонента. В идеале бОльшая часть компонентов должна быть в таком режиме (но у нас вряд ли, т.к. очень крупные компоненты, получающие данные для вывода через сервисы).

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

Селектор в camelCase, так же используется в шаблонах компонентов.

Теперь он @Pipe и должен имплементить PipeTransform интерфейс. В модуль закидывается туда же, куда и компоненты/директивы, и так же надо экспортировать, если используется в других модулях.

Селектор в camelCase, так же используется в шаблонах компонентов.

Директивы и фильтры ангуляра нельзя использовать в шаблонах ангуляржс компонентов и наоборот. Между фреймворками пробрасываются только сервисы и компоненты.

Во-первых, избавляемся от export default, т.к. AoT компилятор в него не может.

Во-вторых, из-за текущей структуры модулей (очень крупные) и использования интерфейсов (кладём кучей в тот же файл, где классы) мы словили весёлый баг с импортом таких интерфейсов и их использованием с декораторами: если интерфейс импортируется из файла, содержащего экспорты не только интерфейсов, но и, например, классов/констант, и такой интерфейс используется для типизации рядом с декоратором (например, @Input() smth: ISmth), то компилятор выдаст ошибку импорта export 'ISmth' was not found. Это может фикситься или выносом всех интерфейсов в отдельный файл (что плохо из-за крупных модулей, такой файл будет в десяток экранов), или заменой интерфейсов на классы. Замена на классы не прокатит, т.к. нельзя наследовать от нескольких родителей.

Выбранное решение: создать в каждом модуле каталог interface, в котором будут лежать файлы с именованием по сущности, содержащие соответствующие интерфейсы (например room, step, content, workbook, homework). Соответственно, все интерфейсы, используемые не локально, кладутся туда и импортируются из таких каталогов-файлов.

Более подробное описание проблемы:
https://github.com/angular/angular-cli/issues/2034#issuecomment-302666897
https://github.com/webpack/webpack/issues/2977#issuecomment-245898520

Если в апгрейженном компоненте используется трансклуд (ng-content), то при использовании компонента из шаблонов ангуляржса:

• не работают multi-slot трансклуды, только возможность пробросить всё одним куском через один ng-content;
• в трансклуд такого компонента нельзя прокидывать ui-view, т.к. оно не будет работать (обломалось при попытке апгрейда viewport компонента);
• если компонент используется подобным образом, то либо откладываем его апгрейд до апгрейда всех мест, где его используют, либо делаем его копию для параллельной работы в уже апгрейженных компонентах.

При использовании ангуляр компонента в ангуляржс компоненте инпуты прописываются как для обычного ангуляр компонента (с использованием [] и ()), но в kebab-case

При переписывании такого шаблона на ангуляр правим kebab-case на camelCase.

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

было:

    ${require('!html-loader!image-webpack-loader?{}!./images/icon.svg')}

стало:

const imageIcon = require("!html-loader!image-webpack-loader?{}!./images/icon.svg");

public imageIcon = imageIcon;

Или для использования через img

было:

стало:

const imageIcon = require("./images/icon.svg");

public imageIcon = imageIcon;

$compile больше нет, как нет и компиляции из строки (на самом деле есть небольшим хаком, но тут о том, как жить в 95% случаев без $compile).

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

@Component({...})
class DynamicComponent {}

@NgModule({
  declarations: [
    ...
    DynamicComponent,
  ],
  entryComponents: [
    DynamicComponent,
  ],
})
class SomeModule {}

// использование
@Component({
  ...
  template: `
    
  `
})
class SomeComponent {
  public dynamicComponent = DynamicComponent;
}

Класс вставляемого компонента может прокидываться через сервис, инпуты или ещё как-либо.

vim-base-dynamic-component — это уже написанный компонент для динамической вставки других компонентов с поддержкой инпутов/аутпутов (в будущем, если понадобится).

Если нужно выводить разные шаблоны по условию, и для этого использовался динамический templateUrl, заменяем это на структурную директиву и разбиваем компонент на три. Пример для разделения вывода мобилка/не мобилка:

запрос/обработка данных
отображение для мобилки
отображение для десктопов

Первый компонент имеет минимальный шаблон и занимается работой с данными, обработкой действий юзера и тому подобное (такой шаблон, из-за его краткости, есть смысл класть тут же в template св-во компонента через `` вместо отдельного html файла и templateUrl). Например:

@Component({
  selector: "...",
  template: `
    
    
    
    
  `,
})

vimBaseIfMobile — структурная директива (в данном случае прямой аналог ngIf), отображающая соответствующий компонент по внутреннему условию и переданному параметру.

Компоненты для мобилки и десктопа получают данные через инпуты, шлют какие-то события через output и занимаются только выводом необходимого. Вся сложная логика, обработки, изменение данных — в основном компоненте который их выводит. В таких компонентах (декстоп/мобайл) можно смело прописывать changeDetection: ChangeDetectionStrategy.OnPush.

Открываем app/entries/angularjs-services-upgrade.ts и по примеру уже имеющегося копипастим (всё в рамках этого файла):

// EXAMPLE: copy-paste, fix naming/params, add to module providers at the bottom, use
// -----
import LoaderService from "../service/loader";
// NOTE: this function MUST be provided and exported for AoT compilation
export function loaderServiceFactory(i: any) {
  return i.get(LoaderService.ID);
}
const loaderServiceProvider = {
  provide: LoaderService,
  useFactory: loaderServiceFactory,
  deps: [ "$injector" ]
};
// -----

@NgModule({
  providers: [
    loaderServiceProvider,
  ]
})
export class AngularJSServicesUpgrade {}

Т.е. копируем имеющийся блок, импортируем нужный сервис, правим под него названия константы/функции, правим в них используемый сервис и его название (чаще всего вместо SmthService.ID надо будет вставить просто строкой имя, под которым сервис доступен (инжектится) в ангуляржсе), добавляем новую константу smthServiceProvider в список провайдеров в конце файла.

Такой сервис используется как нативный ангуляровский: просто инжектим в конструкторе по классу.

Кладём в файл с оригинальным компонентом (в начало) следующую заглушку, которая позволит прокинуть компонент в ангуляр окружение:

import {Directive, ElementRef, Injector, Input, Output, EventEmitter} from "@angular/core";
import {UpgradeComponent} from "@angular/upgrade/static";

@Directive({
  /* tslint:disable:directive-selector */
  selector: "vim-smth"
})
/* tslint:disable:directive-class-suffix */
export class SmthComponent extends UpgradeComponent {
  @Input() smth: boolean;

  @Output() someAction: EventEmitter;

  constructor(elementRef: ElementRef, injector: Injector) {
    super("vimSmth", elementRef, injector);
  }
}

@NgModule({
  declarations: [
    ...
    SmthComponent,
  ]
})
export class SmthModule {

Обращаем внимание, что в данном случае используется декоратор Directive вместо Component, это особенность того, как ангуляр будет это обрабатывать.

Не забываем прописать все Input/Output (биндинги из оригинального компонента) и прописать компонент в declarations соответствующего модуля.

В дальнейшем, при апгрейде этого компонента, такая заглушка станет реальным компонентом ангуляра.

Если компонент (а точнее, старая директива-компонент) инжектит $attrs в контроллер/link функцию, то такой компонент нельзя прокинуть в ангуляр из ангуляржса, и его нужно апгрейдить или класть рядом апгрейженную копию для ангуляра.

Отключение ошибок tslint’a нужно, чтобы не ругался на несоответствие имени селектора и класса декоратору директивы. Эти строчки (комментарии) надо убрать после апгрейда компонента.

• использование сервиса с промисами $q заменяется на нативные Promise. У них нет finally, но это пофиксилось полифилом core.js/es7.promise.finally и теперь он есть. У него также нет deferred, добавлен ts-deferred, чтобы не писать велосипед каждый раз;
• вместо $timeout и $interval используем нативные window.setTimeout и window.setInterval;
• вместо ng-show="visible" биндимся на аттрибут [hidden]="!visible";
• track by теперь всегда должен быть методом, указывается как (не забываем про постфикс Track у метода):

*ngFor="let item of items; trackBy: itemTrack"

public itemTrack(_index: number, item: IItem): number {
  return item.id;
}

• в 99% случаев $digest, $apply, $evalAsync и подобное выпиливаются без замены;
• для инжекта сервиса просто прописываем его в конструкторе constructor(private someService: SomeService), ангуляр сам поймёт, откуда его взять;
• внутри дериктивы элемент, на котором она висит, доступен через инжект constructor(private element: ElementRef) и инициализирован в хуке AfterViewInit (ElementRef это не сам DOM объект, он доступен по this.element.nativeElement);
• ng-include нет без замены, используем динамическое создание компонентов;
• angular.extend, angular.merge, angular.forEach и подобное отсутствует, используем нативный js и lodash;
• angular.element и все его методы отсутствуют. Пользуемся @ViewChild/@ContentChild и работаем через нативный js;
• если надо дёрнуть чендж детекшен в компоненте с OnPush — инжектим private changeDetectorRef: ChangeDetectorRef и дёргаем this.changeDetectorRef.markForCheck();
• из шаблонов выпиливаем $ctrl. — доступ к св-вам и методам напрямую по именам;
• ng-bind-html="smth" → [innerHTML]="smth"
• $sce → import {DomSanitizer} from "@angular/platform-browser";
• ng-pural → [ngPlural] https://angular.io/api/common/NgPlural
• ngClass не может так

[ngClass]="{
  [ styles.active ]: visible,
  [ styles.smth ]: smth
}"

поэтому заменяем на массив

[ngClass]="[
  visible ? styles.active : '',
  smth ? styles.smth : ''
]"

• классы для ui-router сервисов импортируются из @uirouter/core и инжектятся без старого префикса $

import {StateService, TransitionService} from "@uirouter/core";

constructor(stateService: StateService,
            transitionService: TransitionService) {

• data атрибуты на компонентах прописываются как attr.data-smth="" или [attr.data-smth]="";
• require в компонентах/директивах заменяется на инжект класса компонента прямо в конструкторе текущего компонента contructor(private parentComponent: ParentComponent). Ангуляр сам увидит, что это компонент, и зацепит его. Для тонкой подстройки есть декораторы @Host (ищет среди родителей), @Self (ищет прямо на компоненте), @Optional (может присутствовать, а может нет, если нет, то переменная будет undefined). Накидывать можно сразу несколько @Host() @Optional() parentComponent: ParentComponent. Рекварить можно компоненты/директивы в компоненты/директивы;
• two-way биндинг в своих компонентах стал более явным и требует указания Output с тем же именем и постфиксом Change.

export class SmthComponent {
  @Input() variable: string;

  @Output() variableChange = new EventEmitter();

• возможен трансклуд ангуляржс компонентов в ангуляр компоненте. Именованный трансклуд надо проверять: работает или нет (в ангуляре он сделан через селекторы)

  transcluded data