Разработка Schematics

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

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

Концепции Schematics

Публичный API для Schematics определяет классы, представляющие основные концепции.

• Виртуальная файловая система представлена классом Tree. Структура данных Tree содержит базу (набор уже существующих файлов) и область подготовки (staging area — список изменений, которые нужно применить к базе). При внесении изменений вы фактически не меняете базу, а добавляете эти модификации в область подготовки.

• Объект Rule определяет функцию, которая принимает Tree, применяет преобразования и возвращает новое Tree. Главный файл Schematic-а, index.ts, определяет набор правил, реализующих логику Schematic-а.

• Преобразование представлено объектом Action. Существует четыре типа действий: Create (создать), Rename (переименовать), Overwrite (перезаписать) и Delete ( удалить).

• Каждый Schematic запускается в контексте, представленном объектом SchematicContext.

Объект контекста, передаваемый в правило, предоставляет доступ к служебным функциям и метаданным, которые могут понадобиться Schematic-у для работы, включая API логирования для помощи в отладке. Контекст также определяет стратегию слияния (merge strategy), которая определяет, как изменения из подготовленного дерева сливаются с базовым деревом. Изменение может быть принято, проигнорировано или вызвать исключение.

Определение правил и действий

Когда вы создаете новый пустой Schematic с помощью Schematics CLI, сгенерированная входная функция является фабрикой правил (rule factory). Объект RuleFactory определяет функцию высшего порядка, которая создает Rule.

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 helloWorld(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    return tree;
  };
}

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

Правила могут использовать утилиты, предоставляемые пакетом @schematics/angular. Ищите вспомогательные функции для работы с модулями, зависимостями, TypeScript, AST, JSON, рабочими пространствами и проектами Angular CLI и многим другим.

import {
JsonAstObject,
JsonObject,
JsonValue,
Path,
normalize,
parseJsonAst,
strings,
} from '@angular-devkit/core';

Определение входных опций с помощью схемы и интерфейсов

Правила могут собирать значения опций от вызывающей стороны и внедрять их в шаблоны. Опции, доступные вашим правилам, с их допустимыми значениями и значениями по умолчанию, определяются в файле JSON-схемы Schematic-а, <schematic>/schema.json. Определяйте переменные или перечисляемые типы данных для схемы, используя интерфейсы TypeScript.

Схема определяет типы и значения по умолчанию переменных, используемых в Schematic. Например, гипотетический Schematic "Hello World" может иметь следующую схему.

{
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "default": "world"
    },
    "useColor": {
      "type": "boolean"
    }
  }
}

См. примеры файлов схем для команд Angular CLI в @schematics/angular.

Подсказки (Prompts) в Schematics

Подсказки (prompts) Schematics вводят взаимодействие с пользователем при выполнении. Настройте опции Schematic-а, чтобы отображать пользователю настраиваемый вопрос. Подсказки отображаются перед выполнением Schematic-а, который затем использует ответ в качестве значения опции. Это позволяет пользователям управлять работой Schematic-а без необходимости глубокого знания всего спектра доступных опций.

Schematic "Hello World" может, например, спросить имя пользователя и отобразить это имя вместо имени по умолчанию " world". Чтобы определить такую подсказку, добавьте свойство x-prompt в схему для переменной name.

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

{
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "default": "world",
      "x-prompt": "What is your name?"
    },
    "useColor": {
      "type": "boolean",
      "x-prompt": "Would you like the response in color?"
    }
  }
}

Сокращенный синтаксис подсказок

В этих примерах используется сокращенная форма синтаксиса подсказок, предоставляющая только текст вопроса. В большинстве случаев этого достаточно. Обратите внимание, однако, что две подсказки ожидают разные типы ввода. При использовании сокращенной формы наиболее подходящий тип выбирается автоматически на основе схемы свойства. В примере подсказка name использует тип input, так как это строковое свойство. Подсказка useColor использует тип confirmation, так как это логическое (Boolean) свойство. В данном случае "yes" соответствует true, а "no" — false.

Поддерживаются три типа ввода.

В краткой форме тип выводится из типа и ограничений свойства.

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

{
  "style": {
    "description": "The file extension or preprocessor to use for style files.",
    "type": "string",
    "default": "css",
    "enum": [
      "css",
      "scss",
      "sass",
      "less",
      "styl"
    ],
    "x-prompt": "Which stylesheet format would you like to use?"
  }
}

Среда выполнения подсказок автоматически проверяет предоставленный ответ на соответствие ограничениям, указанным в JSON-схеме. Если значение неприемлемо, пользователю предлагается ввести новое значение. Это гарантирует, что любые значения, переданные в Schematic, соответствуют ожиданиям реализации Schematic-а, поэтому вам не нужно добавлять дополнительные проверки в коде Schematic-а.

Полный синтаксис подсказок

Синтаксис поля x-prompt поддерживает полную форму для случаев, когда требуется дополнительная настройка и контроль над подсказкой. В этой форме значение поля x-prompt представляет собой JSON-объект с подполями, которые настраивают поведение подсказки.

Следующий пример полной формы взят из JSON-схемы для Schematic-а, который CLI использует для генерации приложений. Он определяет подсказку, позволяющую пользователям выбрать препроцессор стилей, который они хотят использовать для создаваемого приложения. Используя полную форму, Schematic может обеспечить более явное форматирование вариантов меню.

{
  "style": {
    "description": "The file extension or preprocessor to use for style files.",
    "type": "string",
    "default": "css",
    "enum": [
      "css",
      "scss",
      "sass",
      "less"
    ],
    "x-prompt": {
      "message": "Which stylesheet format would you like to use?",
      "type": "list",
      "items": [
        { "value": "css", "label": "CSS" },
        { "value": "scss", "label": "SCSS [ https://sass-lang.com/documentation/syntax#scss ]" },
        { "value": "sass", "label": "Sass [ https://sass-lang.com/documentation/syntax#the-indented-syntax ]" },
        { "value": "less", "label": "Less [ https://lesscss.org/ ]" }
      ]
    }
  }
}

Схема x-prompt

JSON-схема, определяющая опции Schematic-а, поддерживает расширения, позволяющие декларативно определять подсказки и их поведение. Никакой дополнительной логики или изменений в коде Schematic-а для поддержки подсказок не требуется. Следующая JSON-схема является полным описанием синтаксиса полной формы для поля x-prompt.

{
  "oneOf": [
    {
      "type": "string"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "items": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string"
                  },
                  "value": {}
                },
                "required": [
                  "value"
                ]
              }
            ]
          }
        }
      },
      "required": [
        "message"
      ]
    }
  ]
}

Schematics CLI

Schematics поставляются со своим собственным инструментом командной строки. Используя Node 6.9 или новее, установите инструмент командной строки Schematics глобально:

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

Это установит исполняемый файл schematics, который вы можете использовать для создания новой коллекции Schematics в отдельной папке проекта, добавления нового Schematic-а в существующую коллекцию или расширения существующего Schematic-а.

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

Однако наиболее распространенным вариантом использования Schematics является интеграция библиотеки Angular с Angular CLI. Делайте это, создавая файлы Schematic-а непосредственно в проекте библиотеки в рабочем пространстве Angular, не используя Schematics CLI. См. Schematics для библиотек.

Создание коллекции Schematics

Следующая команда создает новый Schematic с именем hello-world в новой папке проекта с тем же именем.

schematics blank --name=hello-world

Schematic blank предоставляется Schematics CLI. Команда создает новую папку проекта (корневую папку для коллекции) и начальный именованный Schematic в коллекции.

Перейдите в папку коллекции, установите npm-зависимости и откройте новую коллекцию в любимом редакторе, чтобы увидеть сгенерированные файлы. Например, если вы используете VS Code:

cd hello-world
npm install
npm run build
code .

Начальный Schematic получает то же имя, что и папка проекта, и генерируется в src/hello-world. Добавляйте связанные Schematics в эту коллекцию и модифицируйте сгенерированный скелет кода, чтобы определить функциональность вашего Schematic-а. Имя каждого Schematic-а должно быть уникальным в пределах коллекции.

Запуск Schematic-а

Используйте команду schematics для запуска именованного Schematic-а. Укажите путь к папке проекта, имя Schematic-а и любые обязательные опции в следующем формате.

schematics <path-to-schematics-project>:<schematics-name> --<required-option>=<value>

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

schematics .:hello-world

Добавление Schematic-а в коллекцию

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

cd hello-world
schematics blank --name=goodbye-world

Команда генерирует новый именованный Schematic внутри вашей коллекции, с главным файлом index.ts и связанным с ним тестом. Она также добавляет имя, описание и фабричную функцию для нового Schematic-а в схему коллекции в файле collection.json.

Содержимое коллекции

Верхний уровень корневой папки проекта коллекции содержит конфигурационные файлы, папку node_modules и папку src/. Папка src/ содержит подпапки для именованных Schematics в коллекции и схему collection.json, которая описывает собранные Schematics. Каждый Schematic создается с именем, описанием и фабричной функцией.

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

• Свойство $schema указывает схему, которую CLI использует для валидации.

• Свойство schematics перечисляет именованные Schematics, принадлежащие этой коллекции. Каждый Schematic имеет текстовое описание и указывает на сгенерированную входную функцию в главном файле.

• Свойство factory указывает на сгенерированную входную функцию. В этом примере вы вызываете Schematic hello-world, вызывая фабричную функцию helloWorld().

• Необязательное свойство schema указывает на файл JSON-схемы, который определяет опции командной строки, доступные для Schematic-а.

• Необязательный массив aliases задает одну или несколько строк, которые можно использовать для вызова Schematic-а. Например, Schematic для команды Angular CLI "generate" имеет псевдоним "g", что позволяет использовать команду ng g.

Именованные Schematics

Когда вы используете Schematics CLI для создания пустого проекта Schematics, новый пустой Schematic является первым членом коллекции и имеет то же имя, что и коллекция. Когда вы добавляете новый именованный Schematic в эту коллекцию, он автоматически добавляется в схему collection.json.

Помимо имени и описания, каждый Schematic имеет свойство factory, которое идентифицирует точку входа Schematic-а. В примере вы вызываете определенную функциональность Schematic-а, вызывая функцию helloWorld() в главном файле hello-world/index.ts.

Каждый именованный Schematic в коллекции состоит из следующих основных частей.

Schematic может предоставлять всю свою логику в файле index.ts без дополнительных шаблонов. Однако вы можете создавать динамические Schematics для Angular, предоставляя компоненты и шаблоны в папке files, подобно тому, как это делается в standalone-проектах Angular. Логика в индексном файле настраивает эти шаблоны, определяя правила, которые внедряют данные и модифицируют переменные.