Как любитель SCSS, структуры и организации, я всегда обнаруживаю, что добавляю полную структуру папок SCSS в свои проекты внешнего интерфейса. Ленивый разработчик во мне (он же эффективный разработчик) хотел одну командную строку, которую я мог бы ввести в свой терминал, которая бы все это для меня подготовила и создала все необходимые файлы за считанные секунды. Войдите в Angular Schematics 🤲… это базовое краткое руководство, которое поможет вам начать работу с Angular Schematic.

Что такое угловые схемы

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

В моей схеме scss-scaffold я хотел изменить проект Angular следующим образом:

  • Добавьте базовые папки SCSS и файлы каталогов
  • Создать новую таблицу стилей
  • Переименуйте существующую таблицу стилей по умолчанию (в случае, если есть существующий код, который вы хотите сохранить)
  • Обновите настройки проекта, чтобы они указывали на новую таблицу стилей.

Вы можете ознакомиться со схемой репо здесь:



sjtrimble / scss-scaffold
Схема углового каркаса SCSS. Участвуйте в разработке sjtrimble / scss-scaffold, создав учетную запись на GitHub. github.com



Пакет NPM находится здесь:



scss-scaffold
Добавить файлы и структуру папок на основе SCSS в приложение Angular CLI www.npmjs.com



Теперь давайте разберемся, как я это настроил!

Предпосылки

Базовые требования

  1. NodeJS
  2. NPM (диспетчер пакетов узлов)
  3. Angular CLI (npm install -g @angular/cli@latest)

Требования к схемам

Установите официальный пакет схем Angular для использования в вашем терминале:

@angular-devkit/schematics-cli

Схема установки

  1. Создать схему. Создайте пустой проект схемы с помощью интерфейса командной строки схемы - передайте ему имя, которое хотите дать, используя «тег имени»:
schematics blank --name=project-name

Вы получите набор файлов по умолчанию, указанный выше, когда создадите пустой проект схемы:

2. Установите зависимости и сборку: установите зависимости и создайте проект схемы, чтобы все заработало:

npm install && npm run build

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

Состав

Вам нужно знать четыре основных файла:

  • index.ts - Здесь идет ваш логический код
  • schema.json - Переменные схемы (переменные, на которые ссылается ваша логика)
  • schema.d.ts - Определения переменных схемы
  • collection.ts - определяет ваш «проект» и связанные схемы с помощью списка и соответствующих метаданных (вам понадобится это, если вы хотите ng add включить

Дополнительно: вы также можете добавлять подсказки через ваш schema.json файл с помощью «x-prompt».

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

src
 |-- ng add** (originally project name)
        |-- files / styles*
        |-- index.ts
        |-- schema.ts*
        |-- collection.ts
*I added these
** I renamed this to ng add

Файлы шаблонов

В этом случае файлы шаблонов очень полезны, потому что мы хотим полностью скопировать эту структуру в существующий проект. На схеме scss-scaffold я создал базовую папку и файловую структуру для использования SCSS в проекте Angular, включая файлы каталогов (например, _base-dir.scss).

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

Логика

Теперь, когда ваши файлы шаблонов на месте, пора заняться делами! Для схемы scss-scaffold я сохранил всю логику в файле index.ts. Вот разбивка функций и соответствующий код:

  • Настройка: определите проект Angular и убедитесь, что это проект интерфейса командной строки Angular.
  • Добавить содержимое файлов: добавьте папки и файлы из файлов шаблонов и добавьте их в существующий проект.
  • Обработка существующего файла SCSS: если вы настроили проект интерфейса командной строки Angular с SCSS в качестве стилей по умолчанию, интерфейс командной строки Angular автоматически создаст для вас styles.scss файл. Более того, у пользователя может уже быть код, который мы, возможно, захотим сохранить. Текущая стратегия (на данный момент) определяет, существует ли такой файл, и переименовывает его в original-styles.scss.
  • Обновить конфигурацию. Создание новой основной таблицы стилей, в которую перетекает все, означает, что нам также необходимо обновить ссылку на стили в файле Angular configurationangular.json, чтобы она указывала на только что созданный файл styles/styles.scss.
  • Слияние: наконец, нам нужно объединить поэтапное дерево с базовым деревом, чтобы применить все изменения к фактическому проекту.

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

Схема тестирования локально

Могут быть более эффективные способы тестирования вашей схемы, но мне понравилась идея запустить ее локально в «реальном» проекте, поэтому я сделал следующее:

  1. Создание тестового проекта. Создайте простой тестовый проект с помощью Angular CLI с помощью следующих команд и перейдите в папку проекта:
ng new dummy-project
cd dummy-projet

2. Свяжите схему с тестовым проектом: вы захотите перенести свою схему в тестовый проект, чтобы вы могли запускать его изнутри - связывание также построит схему для вас, так что у вас нет чтобы запустить это отдельно, когда вы делаете обновление (оно запускается npm run build как часть последовательности):

// This path will vary depending on where you have your schematic project located relative to your test project
npm link ../scss-scaffold

3. Запустить схему в тестовом проекте. Теперь, когда схема связана, вы можете запустить схему в проекте:

schematics scss-scaffold:ng-add

4. Тада! Следите за тем, как изменения применяются к вашему фиктивному проекту.

Рекомендуется периодически тестировать свою схему, запуская «npm run build” из проекта схемы, чтобы увидеть, не зависнет ли она где-нибудь.

Мне нравится работать поэтапно, чтобы вы могли протестировать одно (например, добавление файла), затем другое (например, поиск существующего файла), затем еще одно (например, изменение указанного файла) и т. Д., Чтобы упростить отладку.

Теперь, когда у вас есть вся логика и рабочая схема, пора сделать ее доступной для других (если вы того пожелаете), добавив ng add поддержку и опубликовав ее в NPM (npmjs.com).

нг добавить поддержку

Самое интересное в Angular Schematics заключается в том, что она позволяет вам упаковать ее для использования в качестве ng add your-awesome-thing команды с Angular CLI. Это упрощает потребление для всех! Все, что нужно запомнить, - это ваше схематическое имя.

Чтобы настроить функциональность ng-add, вам необходимо добавить информацию о ng-add в ваш collection.json файл.

Обратите внимание, что ссылка на хэш factory (в данном случае "./ng-add/index#ngAdd”) является основной функцией в вашем index.ts файле. В этом случае я тоже назвал его ng add.

Вот так! После этого можно использовать ng add.

Совет: флажок «Сохранить» зависимости

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

...
“ng-add”: { 
   “save”: false 
}
..

Добавление этого флага делает так, что когда кто-то использует ng add your-project, он не добавляет ваш проект в зависимость от своего. scss-scaffold только добавляет файлы, поэтому он не требуется в качестве зависимости для будущей функциональности.

А теперь перейдем к публикации!

Развертывание в NPM

Последний шаг - опубликовать ваш пакет в NPM, чтобы он стал общедоступным.

Войти

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

// Create an account if you don't already have an account
npm adduser
npm login
// Verify that you are properly logged in to your account
npm whoam
// Publish your package
npm publish path

Команда npm publish предложит вам ответить на несколько вопросов.

Ключевые слова

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

Внесение обновлений

Убедитесь, что вы либо обновили номер версии в package.jsonфайле, либо запустите npm version patch, чтобы увеличить номер версии и опубликовать автоматически.

npm publish

Вот и все! Теперь у вас есть опубликованная угловая схема, доступная через NPM, которую пользователи могут легко использовать ng add!

Репо

Я решил разместить свое репо на GitHub, но это, очевидно, зависит от вас! Вы можете проверить это ниже:



sjtrimble / scss-scaffold
Схема углового каркаса SCSS. Участвуйте в разработке sjtrimble / scss-scaffold, создав учетную запись на GitHub. github.com



Резюме

Надеюсь, это поможет вам начать работу над своим первым проектом Angular Schematic! Я думаю, что больше людей должны использовать схемы. Схемы чрезвычайно полезны для библиотек, создания шаблонов и основных строительных блоков.

Удачного кодирования!

Мысли

Я не был знаком с некоторыми базовыми функциями JSON JSON.parse и JSON.stringify, поэтому самой сложной частью для меня было изменение существующего файла ( angular.json).

Хотя этот проект неплохо работает с новым блестящим проектом Angular 9 CLI, есть несколько других соображений и будущих функций, которые я хотел бы добавить:

  • Спросите пользователя, хотят ли они сохранить существующий styles.scss файл
  • Учетная запись для других styles.scss местоположений файлов
  • Accont для других существующих *.scss файлов
  • Правильные сообщения об ошибках пользователю
  • Стратегия управления несколькими проектами

Всегда есть место для улучшений и инноваций 😀

Ресурсы

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