Расширение файлов проекта сниппетами

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

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

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

Данная функциональность доступна пользователям проекта с ролью Разработчик.

Файлы, доступные для расширения

Файлы проекта, которые расширяются через сниппеты, отображаются в дереве проекта только для просмотра. Редактировать их напрямую нельзя — вы работаете с соответствующими сниппет-файлами в папке src/snippets.

Файл проекта	Сниппет-файл	Что расширяется	Платформа
`package.json`	`package_dependencies.txt`	Секция `dependencies`	Angular, React
`package.json`	`package_devDependencies.txt`	Секция `devDependencies`	Angular, React
`angular.json`	`angular_projects.architect.build.options.assets.txt`	Секция `projects.<имя проекта>.architect.build.options.assets`	Angular
`Jenkinsfile`	`jenkinsfile_snippet.txt`	Специальный маркер в пайплайне сборки	Angular, React

Имя сниппет-файла состоит из имени целевого файла без расширения и маркера — пути к секции, в которую будет добавлено содержимое сниппета. Например, в файле angular_projects.architect.build.options.assets.txt часть angular — это целевой файл angular.json, а projects.architect.build.options.assets — секция внутри него.

Папка src/snippets

Все сниппет-файлы находятся в папке src/snippets. Она создаётся автоматически вместе с предсозданными сниппет-файлами для выбранной платформы и является защищённой системной папкой.

В папке src/snippets недоступны действия:

удаление папки
создание новых файлов и папок
загрузка файла или архива
переименование
перемещение

Предсозданные сниппет-файлы внутри папки нельзя удалить, переименовать или переместить — доступно только редактирование их содержимого.

Добавление сниппета

Чтобы добавить сниппет в файл проекта, выполните действия:

Откройте проект интерфейса.
Перейдите в раздел Страницы и нажмите кнопку Код проекта.
Ознакомьтесь со структурой проекта и содержимым сгенерированных файлов package.json, angular.json и Jenkinsfile, чтобы понять, какие значения уже заданы генератором.
Откройте папку src/snippets и выберите файл, соответствующий нужному файлу проекта и его секции.
Добавьте содержимое сниппета, следуя подсказке в начале файла.
Сохраните изменения.
Запустите публикацию проекта.

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

Формат сниппетов

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

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

package_dependencies.txt и package_devDependencies.txt

Зависимости указываются в строгом JSON-формате: ключ — имя npm-пакета, значение — его версия.

{
  "lodash": "^4.17.21",
  "date-fns": "^3.6.0"
}

Содержимое объединяется с секцией dependencies (или devDependencies) файла package.json. Если секция в исходном файле отсутствует, она будет создана.

angular_projects.architect.build.options.assets.txt

Сниппет применяется только для Angular-проекта. Значение указывается в строгом JSON-формате, при этом допустимы три варианта:

Строка:
```
"src/assets/custom-file.json"
```

Объект:

{
  "glob": "**/*",
  "input": "src/assets/custom",
  "output": "assets/custom"
}

Массив строк и/или объектов:

[
  "src/assets/custom-file.json",
  {
    "glob": "**/*",
    "input": "src/assets/custom",
    "output": "assets/custom"
  }
]

Элементы сниппета добавляются в конец массива assets. Если секция assets отсутствует, она будет создана. Если в файле явно определена секция assets для конфигурации production, содержимое сниппета добавляется и в неё.

jenkinsfile_snippet.txt

В сниппете указывается фрагмент Jenkins Pipeline, который будет вставлен в специальный маркер Jenkinsfile при подготовке проекта к публикации.

pipelineParameters.put("custom_param", "value")

Содержимое добавляется в Jenkinsfile перед строкой dsMsaPipeline(pipelineParameters). Если сниппет не заполнен, маркер удаляется из итогового файла.

Правила применения сниппетов

Содержимое сниппета объединяется с содержимым файла проекта.
При совпадении значений приоритет имеет значение из сниппета: например, версия зависимости из package_dependencies.txt переопределит версию, заданную генератором в package.json.
Итоговые package.json и angular.json всегда остаются валидными JSON-файлами.

Проверка корректности сниппета

Содержимое сниппетов для package.json и angular.json проверяется на этапе ввода: система применяет сниппет к файлу проекта и проверяет синтаксис итогового файла.

Если итоговый файл получается невалидным:

кнопка Сохранить блокируется, а рядом с ней отображается иконка с подсказкой «Невалидные файлы: <имя файла>»
в дереве проекта невалидный файл и соответствующий ему сниппет-файл отмечаются иконкой с подсказкой «Проверьте содержание сниппет-файла»

Чтобы снять блокировку, исправьте содержимое сниппет-файла в соответствии с описанным форматом.

Пользовательский код проекта Реестр компонентов