Angular schematics, или как я писал свой шаблон для angular cli

Моя цель - предложение широкого ассортимента товаров и услуг на постоянно высоком качестве обслуживания по самым выгодным ценам.

Прежде чем перейти к статье, хочу вам представить, экономическую онлайн игру Brave Knights, в которой вы можете играть и зарабатывать. Регистируйтесь, играйте и зарабатывайте!

Здравствуйте, меня зовут Максим. Уже несколько лет я занимаюсь front-end разработкой. Мне часто приходится иметь дело с версткой различных html шаблонов. В своей повседневной работе я обычно пользуюсь сборщиком webpack c настроенным шаблонизатором pug, а также использую методологию BEM. Для того чтобы облегчить себе жизнь использую замечательный пакет.


Недавно нужно было сделать небольшой проект на Angular, а так как я привык работать со своими любимыми инструментами, возвращаться на голый html не хотелось. В связи с чем появилась задача как подружить bempug с ангуляром, и не просто подружить, но еще и генерировать компоненты из cli с необходимой мне структурой.


Кому интересно как я все это провернул добро пожаловать под кат.


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


Выполняем в командной строке:


ng g test-project.


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


Проект создался, но шаблоны компонентов по умолчанию у нас в html, сейчас поправим. Первым делом, нужно подружить angular cli с шаблонизатором pug, для этого я использовал пакет ng-cli-pug-loader


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


ng add ng-cli-pug-loader.


Теперь можно использовать pug файлы шаблонов. Далее переписываем декоратор root компонента AppComponent на:


 @Component({
  selector: 'app-root',
  templateUrl: './app.component.pug',
  styleUrls: ['./app.component.scss']
})

Соответственно меняем расширение файла app.component.html на app.component.pug, и содержание прописываем в синтаксисе шаблонизатора. В данном файле я удалил все кроме роутера.


Займемся наконец созданием нашего генератора компонентов!


Для генерации шаблонов нам необходимо создать свою схему. Я использую пакет schematics-cli из @angular-devkit. Устанавливаем пакет глобально командой:


npm install -g @angular-devkit/schematics-cli.


Схему я создал в отдельной дирректории вне проекта командой:


schematics blank --name=bempug-component.


Заходим в созданную схему, нас сейчас интересует файл src/collection.json. Выглядит он так:


  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "bempug-component": {
      "description": "A blank schematic.",
      "factory": "./bempug-component/index#bempugComponent"
    }
  }
}

Это файл описания нашей схемы, где параметр "factory": "./bempug-component/index#bempugComponent": это описание основной функции "фабрики" нашего генератора.


Изначально он выглядит как то так:


import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';

// You don't have to export the function as default. You can also have more than one rule factory
// per file.
export function bempugComponent(options: any): Rule {
    return (tree: Tree, _context: SchematicContext) => {
        return tree;
    };
}

Можно сделать у функции экспорт по умолчанию, тогда параметр "factory" можно переписать как "./bempug-component/index ".


Далее в директории нашей схемы создаем файл schema.json, он будет описывать все параметры нашей схемы.


{
  "$schema": "http://json-schema.org/schema",
  "id": "SchemanticsForMenu",
  "title": "Bempug Schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "$default": {
        "$source": "argv",
        "index": 0
      }
    },
    "path": {
      "type": "string",
      "format": "path",
      "description": "The path to create the component.",
      "visible": false
    },
    "project": {
      "type": "string",
      "description": "The name of the project.",
      "$default": {
        "$source": "projectName"
      }
    }
  }
}

Параметры находятся в properties, a именно:


  • name имя сущности (в нашем случае это будет компонент);
  • Path это путь по которому генератор создаст файлы компонента ;
  • Project это сам проект, в котором будет сгенерирован компонент;

Добавим в файл еще несколько параметров, которые понадобятся в дальнейшем.


"module":  {
  "type": "string",
  "description": "The declaring module.",
  "alias": "m"
},
"componentModule": {
  "type": "boolean",
  "default": true,
  "description": "Patern module per Component",
  "alias": "mc"
},
"export": {
  "type": "boolean",
  "default": false,
  "description": "Export component from module?"
}

  • module тут будет хранится ссылка на модуль в который будет включатся компонент, а точнее модуль компонента ;
  • componentModule тут флаг создавать ли для компонента собственный модуль (дальше я пришел к выводу что он будет создаваться всегда и установил его в true);
  • export: это флаг экспортировать ли из модуля в который мы делам импорт нашего модуля компонента;

Дальше создаем интерфейс с параметрами нашего компонента файл schema.d.ts. 


export interface BemPugOptions {
    name: string;
    project?: string;
    path?: string;
    module?: string;
    componentModule?: boolean;
    module?: string;
    export?: boolean;
    bemPugMixinPath?: string;
}

В нем свойства дублируют свойства из schema.json. Далее подготовим нашу фабрику, переходим в файл index.ts. В нем создаем две функции filterTemplates, которая будет отвечать за то создавать ли модуль для компонента в зависимости от значения componentModule, и setupOptions, которая настраивает параметры необходимые для фабрики.


function filterTemplates(options: BemPugOptions): Rule {
  if (!options.componentModule) {
    return filter(path => !path.match(/\.module\.ts$/) && !path.match(/-item\.ts$/) && !path.match(/\.bak$/));
  }
  return filter(path => !path.match(/\.bak$/));
}

function setupOptions(options: BemPugOptions, host: Tree): void {
  const workspace = getWorkspace(host);
  if (!options.project) {
    options.project = Object.keys(workspace.projects)[0];
  }
  const project = workspace.projects[options.project];

  if (options.path === undefined) {
    const projectDirName = project.projectType === 'application' ? 'app' : 'lib';
    options.path = `/${project.root}/src/${projectDirName}`;
  }

  const parsedPath = parseName(options.path, options.name);
  options.name = parsedPath.name;
  options.path = parsedPath.path;

}

Далее в основную функцию прописываем:


export function bempugComponent(options: BemPugOptions): Rule {
  return (host: Tree, context: SchematicContext) => {

    setupOptions(options, host);

    const templateSource = apply(url('./files'), [
      filterTemplates(options),
      template({
        ...strings,
        ...options
      }),
      move(options.path || '')
    ]);

    const rule = chain([
      branchAndMerge(chain([
        mergeWith(templateSource),
      ]))
    ]);

    return rule(host, context);
  }
}

Фабрика готова и она уже может генерировать файлы компонентов обрабатывая шаблоны из папки files, которой пока нет. Это не беда, создаем в папке нашей схемы в моем случае это bempug-component папку files. В папке files создаем папку __name@dasherize__, при генерации фабрика заменит __name@dasherize__ на имя компонента.


Далее внутри папки __name@dasherize__ создаем файлы


  • __name@dasherize__.component.pug pug шаблон компонента
  • __name@dasherize__.component.spec.ts файл юнит теста для компонента
  • __name@dasherize__.component.ts файл самого компонента
  • __name@dasherize__-component.module.ts модуль компонента
  • __name@dasherize__-component.scss файл стилей компонента

Теперь добавим в нашу фабрику поддержку обновления модулей, для этого создадим файл add-to-module-context.ts, для хранения параметров, которые понадобятся фабрике для работы с модулем.


import * as ts from 'typescript';

export class AddToModuleContext {
    // source of the module file
    source: ts.SourceFile;

    // the relative path that points from
    // the module file to the component file
    relativePath: string;

    // name of the component class
    classifiedName: string;
}

Добавляем поддержку модулей в фабрику.


const stringUtils = { dasherize, classify };

// You don't have to export the function as default. You can also have more than one rule factory
// per file.

function filterTemplates(options: BemPugOptions): Rule {
  if (!options.componentModule) {
    return filter(path => !path.match(/\.module\.ts$/) && !path.match(/-item\.ts$/) && !path.match(/\.bak$/));
  }
  return filter(path => !path.match(/\.bak$/));
}

function setupOptions(options: BemPugOptions, host: Tree): void {
  const workspace = getWorkspace(host);
  if (!options.project) {
    options.project = Object.keys(workspace.projects)[0];
  }
  const project = workspace.projects[options.project];

  if (options.path === undefined) {
    const projectDirName = project.projectType === 'application' ? 'app' : 'lib';
    options.path = `/${project.root}/src/${projectDirName}`;
  }

  const parsedPath = parseName(options.path, options.name);
  options.name = parsedPath.name;
  options.path = parsedPath.path;
    options.module = options.module || findModuleFromOptions(host, options) || '';
}

export function createAddToModuleContext(host: Tree, options: ModuleOptions, componentPath: string): AddToModuleContext {
  const result = new AddToModuleContext();

  if (!options.module) {
    throw new SchematicsException(`Module not found.`);
  }

  // Reading the module file
  const text = host.read(options.module);

  if (text === null) {
    throw new SchematicsException(`File ${options.module} does not exist.`);
  }

  const sourceText = text.toString('utf-8');
  result.source = ts.createSourceFile(options.module, sourceText, ts.ScriptTarget.Latest, true);

  result.relativePath = buildRelativePath(options.module, componentPath);

  result.classifiedName = stringUtils.classify(`${options.name}ComponentModule`);

  return result;
}

function addDeclaration(host: Tree, options: ModuleOptions, componentPath: string) {

  const context = createAddToModuleContext(host, options, componentPath);
  const modulePath = options.module || '';
  const declarationChanges = addImportToModule(
      context.source,
      modulePath,
      context.classifiedName,
      context.relativePath);

  const declarationRecorder = host.beginUpdate(modulePath);
  for (const change of declarationChanges) {
    if (change instanceof InsertChange) {
      declarationRecorder.insertLeft(change.pos, change.toAdd);
    }
  }
  host.commitUpdate(declarationRecorder);
};

function addExport(host: Tree, options: ModuleOptions, componentPath: string) {
  const context = createAddToModuleContext(host, options, componentPath);
  const modulePath = options.module || '';

  const exportChanges = addExportToModule(
      context.source,
      modulePath,
      context.classifiedName,
      context.relativePath);

  const exportRecorder = host.beginUpdate(modulePath);

  for (const change of exportChanges) {
    if (change instanceof InsertChange) {
      exportRecorder.insertLeft(change.pos, change.toAdd);
    }
  }
  host.commitUpdate(exportRecorder);
};

export function addDeclarationToNgModule(options: ModuleOptions, exports: boolean, componentPath: string): Rule {
  return (host: Tree) => {
    addDeclaration(host, options, componentPath);
    if (exports) {
      addExport(host, options, componentPath);
    }
    return host;
  };
}

export function bempugComponent(options: BemPugOptions): Rule {
  return (host: Tree, context: SchematicContext) => {

    setupOptions(options, host);

    deleteCommon(host);
    const templateSource = apply(url('./files'), [
      filterTemplates(options),
      template({
        ...strings,
        ...options
      }),
      move(options.path || '')
    ]);

    const rule = chain([
      branchAndMerge(chain([
        mergeWith(templateSource),
        addDeclarationToNgModule(options, !!options.export, `${options.path}/${options.name}/${options.name}-component.module` || '')
      ]))
    ]);

    return rule(host, context);
  }
}

Теперь при добавлении параметра -m <ссылка на модуль> к сli команде, наш модуль компонента будет добавлять импорт в указанный модуль а при добавлении флага –export добавлять экспорт из него. Дальше добавим поддержку BEM. Для этого я взял исходники npm пакета bempug и сделал код в одном файле bempugMixin.pug, который поместил в папку common и внутри в еще одну папку common, чтобы миксин копировался в папку common в проекте на ангуляр.


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


import {
  Rule,
  SchematicContext,
  Tree,
  filter,
  apply,
  template,
  move,
  chain,
  branchAndMerge, mergeWith, url, SchematicsException
} from '@angular-devkit/schematics';
import {BemPugOptions} from "./schema";
import {getWorkspace} from "@schematics/angular/utility/config";
import {parseName} from "@schematics/angular/utility/parse-name";
import {normalize, strings} from "@angular-devkit/core";
import { AddToModuleContext } from './add-to-module-context';
import * as ts from 'typescript';

import {classify, dasherize} from "@angular-devkit/core/src/utils/strings";
import {buildRelativePath, findModuleFromOptions, ModuleOptions} from "@schematics/angular/utility/find-module";
import {addExportToModule, addImportToModule} from "@schematics/angular/utility/ast-utils";
import {InsertChange} from "@schematics/angular/utility/change";

const stringUtils = { dasherize, classify };

// You don't have to export the function as default. You can also have more than one rule factory
// per file.

function filterTemplates(options: BemPugOptions): Rule {
  if (!options.componentModule) {
    return filter(path => !path.match(/\.module\.ts$/) && !path.match(/-item\.ts$/) && !path.match(/\.bak$/));
  }
  return filter(path => !path.match(/\.bak$/));
}

function setupOptions(options: BemPugOptions, host: Tree): void {
  const workspace = getWorkspace(host);
  if (!options.project) {
    options.project = Object.keys(workspace.projects)[0];
  }
  const project = workspace.projects[options.project];

  if (options.path === undefined) {
    const projectDirName = project.projectType === 'application' ? 'app' : 'lib';
    options.path = `/${project.root}/src/${projectDirName}`;
  }

  const parsedPath = parseName(options.path, options.name);
  options.name = parsedPath.name;
  options.path = parsedPath.path;
  options.module = options.module || findModuleFromOptions(host, options) || '';
  options.bemPugMixinPath = buildRelativePath(`${options.path}/${options.name}/${options.name}.component.ts`, `/src/app/common/bempugMixin.pug`);

}

export function createAddToModuleContext(host: Tree, options: ModuleOptions, componentPath: string): AddToModuleContext {
  const result = new AddToModuleContext();

  if (!options.module) {
    throw new SchematicsException(`Module not found.`);
  }

  // Reading the module file
  const text = host.read(options.module);

  if (text === null) {
    throw new SchematicsException(`File ${options.module} does not exist.`);
  }

  const sourceText = text.toString('utf-8');
  result.source = ts.createSourceFile(options.module, sourceText, ts.ScriptTarget.Latest, true);

  result.relativePath = buildRelativePath(options.module, componentPath);

  result.classifiedName = stringUtils.classify(`${options.name}ComponentModule`);

  return result;
}

function addDeclaration(host: Tree, options: ModuleOptions, componentPath: string) {

  const context = createAddToModuleContext(host, options, componentPath);
  const modulePath = options.module || '';

  const declarationChanges = addImportToModule(
      context.source,
      modulePath,
      context.classifiedName,
      context.relativePath);

  const declarationRecorder = host.beginUpdate(modulePath);
  for (const change of declarationChanges) {
    if (change instanceof InsertChange) {
      declarationRecorder.insertLeft(change.pos, change.toAdd);
    }
  }
  host.commitUpdate(declarationRecorder);
};

function addExport(host: Tree, options: ModuleOptions, componentPath: string) {
  const context = createAddToModuleContext(host, options, componentPath);
  const modulePath = options.module || '';

  const exportChanges = addExportToModule(
      context.source,
      modulePath,
      context.classifiedName,
      context.relativePath);

  const exportRecorder = host.beginUpdate(modulePath);

  for (const change of exportChanges) {
    if (change instanceof InsertChange) {
      exportRecorder.insertLeft(change.pos, change.toAdd);
    }
  }
  host.commitUpdate(exportRecorder);
};

export function addDeclarationToNgModule(options: ModuleOptions, exports: boolean, componentPath: string): Rule {
  return (host: Tree) => {
    addDeclaration(host, options, componentPath);
    if (exports) {
      addExport(host, options, componentPath);
    }
    return host;
  };
}

function deleteCommon(host: Tree) {
  const path = `/src/app/common/bempugMixin.pug`;
  if(host.exists(path)) {
    host.delete(`/src/app/common/bempugMixin.pug`);
  }
}

export function bempugComponent(options: BemPugOptions): Rule {
  return (host: Tree, context: SchematicContext) => {

    setupOptions(options, host);

    deleteCommon(host);
    const templateSource = apply(url('./files'), [
      filterTemplates(options),
      template({
        ...strings,
        ...options
      }),
      move(options.path || '')
    ]);
    const mixinSource = apply(url('./common'), [
      template({
        ...strings,
        ...options
      }),
      move('/src/app/' || '')
    ]);

    const rule = chain([
      branchAndMerge(chain([
        mergeWith(templateSource),
        mergeWith(mixinSource),
        addDeclarationToNgModule(options, !!options.export, `${options.path}/${options.name}/${options.name}-component.module` || '')
      ]), 14)
    ]);

    return rule(host, context);
  }
}

Самое время заняться наполнением наших файлов шаблонов.


__name@dasherize__.component.pug:


include <%= bemPugMixinPath %>

+b('<%= name %>')
    +e('item', {m:'test'})
        | <%= name %> works

То что указанно в <% = %> при генерации заменится на имя компонента .


__name@dasherize__.component.spec.ts:


import { async, ComponentFixture, TestBed } from '@angular/core/testing';
import {NO_ERRORS_SCHEMA} from '@angular/core';
import { <%= classify(name) %>ComponentModule } from './<%= name %>-component.module';
import { <%= classify(name) %>Component } from './<%= name %>.component';

describe('<%= classify(name) %>Component', () => {
    let component: <%= classify(name) %>Component;
    let fixture: ComponentFixture<<%= classify(name) %>Component>;

    beforeEach(async(() => {
        TestBed.configureTestingModule({
            imports: [<%= classify(name) %>ComponentModule],
            declarations: [],
            schemas: [ NO_ERRORS_SCHEMA ]
        })
            .compileComponents();
    }));

    beforeEach(() => {
        fixture = TestBed.createComponent(<%= classify(name) %>Component);
        component = fixture.componentInstance;
        fixture.detectChanges();
    });

    it('should create', () => {
        expect(component).toBeTruthy();
    });
});

В данном случае <%= classify(name) %> применяется для приведения имени к CamelCase.


__name@dasherize__.component.ts:


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

@Component({
        selector: 'app-<%=dasherize(name)%>-component',
        templateUrl: '<%=dasherize(name)%>.component.pug',
        styleUrls: ['./<%=dasherize(name)%>-component.scss'],
        encapsulation: ViewEncapsulation.None
})
export class <%= classify(name) %>Component implements OnInit {
        constructor() {}
        ngOnInit(): void {
        }
}

__name@dasherize__-component.module.ts:


import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import {<%= classify(name) %>Component} from './<%= name %>.component';

@NgModule({
    declarations: [
        <%= classify(name) %>Component,
    ],
    imports: [
        CommonModule
    ],
    exports: [
        <%= classify(name) %>Component,
    ]
})
export class <%= classify(name) %>ComponentModule { }

__name@dasherize__-component.scss:


.<%= name %>{

}

Делаем билд нашей схемы командой ``npm run build```.


Все готово для генерации компонентов в проекте!


Для проверки заходим обратно в наш Angular проект создаем модуль.
ng g m test-schema
Далее делаем ``npm link <абсолютный путь к папке проекта с нашей схемой>```, для того чтобы добавить нашу схему в node_modules проекта.


И пробуем схему командой ng g bempug-component:bempug-component test -m /src/app/test-schema/test-schema.module.ts –export.
Наша схема создаст компонент и добавит его в указанный модуль с экспортом.
Схема готова, можно начинать делать приложение на привычных технологиях.


Посмотреть итоговую версию можно вот тут, а также пакет доступен в npm.


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


  • https://blog.angular.io/schematics-an-introduction-dc1dfbc2a2b2;
  • https://medium.com/@tomastrajan/total-guide-to-custom-angular-schematics-5c50cf90cdb4;
  • https://developer.okta.com/blog/2019/02/13/angular-schematics;

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

Источник: https://habr.com/ru/post/469509/

Вернуться к списку

Интересные статьи

Интересные статьи

Я никогда не писал расширения для Хрома, но меня допекли
Я никогда не писал расширения для Хрома, но меня допекли
Если вы узнали стиль заголовка и вам больше не нужны никакие подробности — вот ссылка на репозиторий. Если вы недоумеваете что это такое и почему я отнимаю место в ленте у хороших авт...
Кастомный скроллбар в Angular
Кастомный скроллбар в Angular
После вступления Edge в доблестные ряды Chromium-браузеров кастомизация скроллбаров через CSS отсутствует только в Firefox. Это здорово, но кроме Firefox у CSS-решения есть масса ограничений. Пос...
Поднимаем свой полноценный игровой Minecraft сервер с мини-играми. Часть 2. Устанавливаем карту для лобби сервера
Поднимаем свой полноценный игровой Minecraft сервер с мини-играми. Часть 2. Устанавливаем карту для лобби сервера
После публикации первой части статьи по установке своего Minecraft сервера, ко мне обратился один читатель Хабра. В письме он написал, что по неосторожности показал мою статью своим детям и е...
Повысьте производительность SPA, разбив ваши библиотеки Angular на несколько частей
Привет, Хабр! Представляю Вашему вниманию перевод статьи «Improve SPA performance by splitting your Angular libraries in multiple chunks» автора Kevin Kreuzer. Angular — отличный фреймворк. Мы в...
Обзор AngularConnect 2019. Часть 2
Обзор AngularConnect 2019. Часть 2
В этой статье продолжаем делиться впечатлениями от поездки в Лондон на AngularConnect 2019. Сегодня расскажем, как все происходило, о докладах второго дня и о том, что полезного мы привезли домой...