Создание метаданных

Создание объектов, реквизитов, маршрутов и форм движком вместо ручного yaml – и шаблоны кода.

Писать yaml руками – значит помнить про UUID, имена свойств вида и место, где регистрируется форма. Эту часть берёт на себя движок; те же операции доступны из CLI, редактора и агента.

Создание метаданных

Механику создания метаданных инструмент берёт на себя: UUID, отступы, точечные вставки в yaml, проверки дублей и совместимости секции с видом объекта. Одни и те же операции доступны из CLI (подкоманды, вывод – JSON), из MCP (инструменты meta_* для агентов) и из LSP (кастомные запросы xbsl/meta* – на них работает дерево метаданных расширения VS Code).

Создаётся 33 вида элементов проекта – от Справочника и Документа до ВиртуальнойТаблицы (вместе с обязательным парным запросом .xbql), ЗапланированногоЗадания, контрактов, прав и команд. Каждый вид несёт то, что документация делает обязательным: платформенное умолчание видимости (ВПодсистеме – расширять осознанно ключом --scope), заготовку обработчика, без которого вид бесполезен, и заметку о том, что генератор не станет выдумывать за разработчика. Виды, чьё содержимое рисуется в дизайнере (ПанельОтчетов, ПроцессИнтеграции), намеренно отсутствуют.

xbsl new-project . vendor Приложение                      # описание проекта + модуль + подсистема
xbsl new-object <каталог-подсистемы> <вид> <имя>          # вид: Справочник, Документ, Перечисление, ...
xbsl add-field <объект>.yaml <секция> <поле> --type <тип>
xbsl add-form . --name <объект>                           # формы объекта и списка + регистрация
xbsl add-form . --name <объект> --forms list-cards        # форма списка карточками
xbsl new-object <каталог-подсистемы> <вид-http-сервиса> <имя> --routes "GET /, POST /, GET /{id}"
xbsl add-route  <сервис>.yaml "DELETE /{id}"              # шаблон URL + заготовка обработчика
xbsl add-method <модуль>.xbsl <метод> --annotations <аннотация> --after <существующий-метод>
xbsl add-subsystem vendor/Приложение <имя>
xbsl add-dependency . acme CurrencyConverter 2.0          # подключить библиотеку к проекту
xbsl rename-object . <старое-имя> <новое-имя>             # файлы + ссылки по всему проекту
xbsl delete-object . --name <объект>                      # план; --apply удаляет и называет хвосты
xbsl set-access . --name <объект> --default <способ-доступа>
xbsl object-info . --name <объект>                        # реквизиты, ТЧ, формы, namespace
xbsl project-info .                                       # проекты, подсистемы, объекты по видам

Вид, секция, аннотации, способы доступа и все идентификаторы пишутся на языке разработки проекта – платформа так документирует свой словарь метаданных, и инструмент принимает ровно эти написания, поэтому в примерах выше стоят плейсхолдеры. Какие виды бывают в проекте, покажет xbsl new-object --help.

Сами исходники бывают написаны и по-английски, и создание метаданных читает оба написания: объект с ElementKind: Catalog и секцией Attributes: находится, описывается и правится ровно так же, как объект с ВидЭлемента: Справочник и Реквизиты:. Пишет инструмент на языке того файла, куда пишет: новый реквизит английского объекта получает Name: и Type:, недостающая секция создаётся как Attributes:, подсистема и запись библиотеки оформляются как проект вокруг них. Пары написаний берутся из данных платформы (английское имя свойства из метамодели), поэтому имя, которое платформа в разных классах пишет по-разному – Элементы это Items у перечисления и Elements в остальных местах, – остаётся русским и при чтении, и при записи: догадка тут хуже молчания. Значения (типы, способы доступа) – ваши, они пишутся как переданы.

add-field ставит новый элемент в конец секции своего вида, а секцию заводит только когда её в файле нет. Данные регистра лежат в Измерения и Ресурсы, поэтому реквизит, запрошенный у регистра, где есть ресурсы и нет реквизитов, попадает в новую секцию Реквизиты в конце файла – notes говорят об этом и называют вид, который положил бы поле рядом с существующими (здесь ресурс; для ресурса там, где есть только реквизиты, – наоборот).

Формы генерируются с наполнением: поля ввода по реквизитам объекта (включая стандартные Наименование / Номер / Дата и иерархию), колонки динамического списка, таблицы табличных частей, форма отчёта с параметрами; готовая форма регистрируется в секции Интерфейс владельца. Ключ --dry-run печатает изменения (с полными текстами файлов), ничего не записывая – так расширение применяет правки через свой механизм undo.

--forms list-cards собирает форму списка не таблицей, а сеткой карточек: ПроизвольныйСписок с матричной группой в КонтейнерСтрок плюс компонент строки СтрокаСписка<Имя>. На карточку идут заголовок, фото (реквизит ДвоичныйОбъект.Ссылка переключает её на ПроизвольнаяКарточка с изображением над подписью) и ещё до трёх полей, даты – с форматированием; что попало на карточку, а что нет, перечисляют notes. Ширину колонки сетки задаёт --card-min-width (по умолчанию 400, с фото – 250), картинку-заглушку пустого фото – --card-placeholder.

add-dependency подключает библиотеку – раздел Библиотеки файла Проект.yaml (Имя, Поставщик, Версия). Версия – это версия релиза библиотеки: релиз выпускается в панели управления, и версия сборки с суффиксом (1.0-42) отклоняется. Разные версии одной библиотеки в проекте не допускаются, поэтому повторное подключение обновляет версию существующей записи. Что подключено сейчас – в project-info (projects[].libraries). Поставщика, имя, версию и полные имена типов библиотеки даёт разбор её архива: elemctl inspect <файл.xlib>.

set-access точечно правит КонтрольДоступа.Разрешения, зная, что допускает вид объекта: --default задаёт право ПоУмолчанию, --permission Чтение=РазрешеноВсем – отдельное право (в том числе пользовательское от ПравоНаЭлемент), --calc-by заполняет РасчетРазрешенийПо – он обязателен для РазрешенияВычисляютсяДляКаждогоОбъекта. Неизвестный способ, право, которого у вида нет, и построчные разрешения у НаборКонстант отклоняются; обработчики вычисления разрешений остаются за разработчиком (какие нужны – скажут notes). object-info показывает текущие разрешения и права вида, project-info – ПоУмолчанию каждого объекта; нет секции – значит, платформа применяет РазрешеноАдминистраторам.

rename-object переименовывает файлы объекта (вместе с формами и компонентом строки СтрокаСписка<Имя>) и обновляет ссылки контекстно по всему проекту: значения ссылочных ключей yaml (Тип/Таблица/ИсточникДанных/Форма/ТипФормы), биндинги =... и код .xbsl. Реквизиты, компоненты и поля динамических списков, лишь совпадающие со старым именем, не трогаются; строковые литералы (UI-текст) – тоже. Ключи --new-presentation / --old-presentation обновляют Заголовок/Представление объекта и его форм. Ид объекта сохраняется – данные на платформе переживают переименование.

delete-object удаляет объект целиком: пару yaml+модуль, его формы и компонент строки списка СтрокаСписка<Имя> – вместе с их парами. Подсистема – это папка, в которой лежат файлы, поэтому вхождение в неё уходит вместе с ними. Каждое ОСТАВШЕЕСЯ упоминание имени по проекту называется файлом и строкой – включая строковые литералы и комментарии: роутер, открывающий форму по имени в строке, или сидинг – ровно те хвосты, которые иначе всплывают ошибкой применения, – и сознательно НЕ правится: какое упоминание мёртвый код, решает автор. Удаление необратимо, поэтому без --apply команда печатает план (инструмент MCP meta_delete_object так же отвечает планом при умолчании dry_run=true).

Переименование, отличающееся только регистром (Товары в товары), инструмент выполняет в два шага через временное имя: регистронезависимая файловая система (Windows, macOS) адресует старое и новое имя как один файл, и одношаговое переименование между ними не гарантировано. Сбой второго шага откатывает первый, временное имя на диске не остаётся; на регистрозависимой файловой системе имя свободно и переименование выполняется одним шагом. Файлы инструмент переименовывает сам, а вот систему контроля версий проверьте: git на регистронезависимой файловой системе сличает имена без учёта регистра только для латиницы, поэтому латинское переименование он не заметит – зафиксируйте его явно (git mv <старое> <новое>), а кириллическое покажет как удаление и добавление, и тогда в остальных клонах на такой же файловой системе git pull остановится с “untracked working tree files would be overwritten by merge” – там перед обновлением надо удалить файл со старым именем.

Шаблоны кода

Шаблон – это аббревиатура и конструкция за ней: набираете есл, жмёте Ctrl+Space, выбираете если – и получаете готовый оператор с точками ввода, между которыми ходит Tab. Механизм повторяет шаблоны 1С:EDT (Параметры – Шаблоны), включая формат файла выгрузки.

Шаблоны предлагаются до остальных подсказок: конструкция, которую вы набираете, нужнее имени, которое просто начинается так же. Данные Элемента им не нужны, нужен только LSP-сервер (xbsl.lsp.enabled, включён по умолчанию) – в режиме CLI-индекса расширение их не предлагает.

Встроенный набор – 51 шаблон (xbsl/templates_builtin.py): управляющие конструкции, объявления (методы с аннотациями, структуры, перечисления, типы исключений), запросы и прикладные идиомы – обход справочника, движения регистра, обработчик HttpСервиса, разрешения доступа по объектам, события объекта, обработчики формы. Каждый шаблон разбирается тем же парсером, что и линтер (tests/test_templates.py), – вставить некомпилируемый код он не может.

В тексте шаблона живут точки ввода и списки выбора. Переменные записываются синтаксисом шаблонов 1С:EDT (${...}) и именуются на языке разработки проекта:

Собственные шаблоны лежат в .xbsl-templates.json в корне воркспейса (--file или настройка xbsl.templates.file): файл дополняет встроенный набор, одноимённый шаблон замещает встроенный. Хранится только то, что отличается от встроенного набора, – поэтому следующий релиз до вас дойдёт.

xbsl templates list                        # весь набор: встроенные и свои (свои помечены *)
xbsl templates export --output мои.json    # выгрузка (например, чтобы перенести на другую машину)
xbsl templates import выгрузка.json        # влить выгрузку в свой файл

В VS Code то же самое – панель XBSL: шаблоны кода, устроенная как диалог EDT: список с контекстом вызова, описание и текст шаблона, кнопки добавления, правки, удаления, импорта, экспорта и восстановления умолчаний. После сохранения работающий сервер перечитывает набор – следующий Ctrl+Space уже предлагает исправленный шаблон.