XBSL для VS Code

Расширение VS Code для 1С:Элемент: подсветка синтаксиса, линтинг на лету с Quick Fix, визуальный конструктор форм, обозреватель метаданных и навигация по проекту – всё на движке xbsl.

Подсветка синтаксиса и проверка на лету исходников 1С:Элемент (.xbsl) движком xbsl – плюс конструктор форм, дерево метаданных, панель документации платформы, создание метаданных, отладка и кнопка деплоя.

Хотите пощупать всё на игрушечном проекте? Откройте папку demo/ репозитория – крошечное приложение 1С:Элемент с формой и несколькими нарочными находками линтера.

Как это устроено

Расширение – тонкий клиент движка xbsl: в LSP-режиме по умолчанию все возможности – диагностика, навигация, панель документации и создание метаданных – разговаривают с одним долгоживущим сервером xbsl-lsp; без сервера те же проверки и создание метаданных идут через CLI:

В режиме CLI одну коллекцию диагностик наполняют два источника, разделение – по состоянию буфера:

• Пока вы печатаете (несохранённый буфер) расширение запускает xbsl --stdin --filename <имя> --format json по живому тексту – только пофайловые правила, быстро, с задержкой. Результат замещает диагностики только этого буфера.
• По сохранению любого .xbsl/.yaml расширение запускает в фоне xbsl <папка воркспейса> --format json (с задержкой, не более одного прогона за раз; сохранение во время прогона отменяет устаревший и начинает заново). Результат покрывает и пофайловые, и проектные правила, поэтому замещает диагностики всех файлов папки – кроме буферов, к тому моменту снова несохранённых: за ними остаётся их живая --stdin-картина до следующего сохранения.

Так нет ни дублей, ни потерянных правил: чистый файл всегда показывает полную картину прогона по воркспейсу, редактируемый – мгновенную пофайловую, и каждое сохранение сводит их вместе. Оба прогона говорят на одном JSON-контракте {diagnostics, summary}, который отдаёт и MCP-сервер линтера.

Упавший или превысивший xbsl.workspaceLintTimeout фоновый прогон сообщается только в панель вывода XBSL – без всплывающих окон на каждое сохранение.

Возможности

• Подсветка синтаксиса .xbsl: ключевые слова (русские и английские формы), объявления, операторы, @-декораторы, числа, комментарии и строки с интерполяцией %имя / ${...}.
• Живые диагностики при наборе (с задержкой) и по сохранению – баланс скобок и блоков, неиспользуемые переменные, типографика, соглашения по стилю и всё остальное, что видит линтер. Подчёркивания несут идентификатор правила (например, code/brackets) и важность.
• Диагностики по всему проекту – сохранение любого .xbsl/.yaml запускает линтер по всей папке воркспейса в фоне, так что проектные правила (code/unknown-type, yaml/unknown-type, уникальность Ид) видны прямо в редакторе по всем файлам. Управляется xbsl.workspaceLint (включено по умолчанию).
• Проверка всего проекта по требованию – команда XBSL: проверить весь проект.
• Переход к определению, поиск всех ссылок и автодополнение по проекту – отвечает языковой сервер по своему индексу проекта. См. Навигация и автодополнение.
• Quick Fix для механических находок – лампочка на исправимой диагностике (хвостовые пробелы, типографские символы) применяет ровно ту правку, которую сообщил линтер; source-действие исправить все (source.fixAll.xbsl) чинит весь файл и умеет запускаться по сохранению через editor.codeActionsOnSave. Нужен xbsl >= 0.7.1. См. Quick Fix.
• Деплой на стенд – команда XBSL: деплой на стенд (elemctl) (и кнопка-облачко в заголовке дерева метаданных) запускает elemctl deploy терминальной задачей: сборка из исходников → загрузка → применение → перезапуск → проверка фактического применения. См. Деплой на стенд.
• Конструктор формы – панель из трёх областей: дерево структуры слева, данные формы справа, каркас формы под ними. Следует за активным редактором и обновляется при наборе; выделение связано между областями, курсором в yaml и панелью свойств. Палитра компонентов – рядом с деревом метаданных, пока панель открыта. См. Конструктор формы.
• Обозреватель метаданных – дерево объектов проекта в основной боковой панели, по видам, с поддеревьями (реквизиты, измерения, формы, значения перечисления …), редактируемой панелью свойств, созданием объектов/полей/подсистем и отбором по подсистеме. См. Обозреватель метаданных.
• Документация – вид во вторичной боковой панели: справка 1С:Элемент как на сайте – дерево “Содержание” (руководства разработчика и администратора, справочники типов и языка запросов), полнотекстовый поиск и просмотр страницы с картинками и ссылкой на первоисточник. Правый клик на типе или переменной открывает её документацию. См. Документация.

Раскладка панелей. Расширение объявляет два контейнера, и раскладка со снимка выше получается сама: 1С:Элемент • Проект (дерево метаданных и палитра) – в основной боковой панели слева, 1С:Элемент • Инспектор (свойства и документация) – во вторичной справа, рядом с чатом. Ничего не приколочено: значок контейнера перетаскивается между панелями, а команда Вид: сбросить расположение представлений возвращает умолчание. Вторичная панель показывается и скрывается по Ctrl+Alt+B (Вид > Внешний вид > Дополнительная боковая панель).

.yaml-описания элементов сохраняют встроенную подсветку YAML.

Требования

Расширение – тонкий клиент над CLI xbsl, проверку оно не встраивает. Нужны:

1. Python 3.10+ и линтер: pip install xbsl. Если линтер не найден, расширение само предложит установку прямо из сообщения об ошибке.
2. Данные языка Элемента – генерируются один раз из вашего дистрибутива 1С:Элемент, см. шаг 1 README линтера. Без них большинство правил не работает; ошибку линтера расширение показывает один раз.

По умолчанию расширение зовёт xbsl из PATH. Перенаправить можно настройками xbsl.linter.command (исполняемый файл) или xbsl.linter.pythonPath (интерпретатор – линтер тогда запускается как <python> -m xbsl).

Ставятся они по отдельности, поэтому движок может отстать от расширения. Большинству возможностей это безразлично; словарю перевода нужен xbsl 0.72.0 или новее – --suggest, запрос машинного перевода за кнопкой предложений, появился только там. С движком постарше панель не открывается и сообщает, какая версия установлена (pip install -U xbsl).

Новый проект

Команда XBSL: новый проект 1С:Элемент (xbsl.project.new) заводит проект с нуля. Мастер спрашивает четыре вещи – имя проекта, поставщика, вид проекта (приложение или библиотека) и папку, – после чего создаёт заготовку через тот же движок, что и остальные операции с метаданными, и открывает готовый Проект.yaml.

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

Структурный поиск по формам

Команда XBSL: структурный поиск по формам (xbsl.forms.search) ищет не по тексту, а по структуре: задаётся тип компонента и, если нужно, условия по свойствам вида ключ=значение. Расширение собирает формы проекта (включая несохранённые буферы), отдаёт их движку и показывает совпадения списком – выбор перемещает курсор на строку компонента в его yaml.

Поиск нужен, когда вопрос звучит как “где у нас поля ввода с таким-то свойством” – текстовым поиском такое не находится, потому что в yaml свойство и тип компонента лежат на разных строках.

Требует режима LSP: подбор совпадений выполняет движок, а в CLI-режиме он не запущен.

Навигация и автодополнение

Навигацию даёт движок: индекс проекта держит языковой сервер, он же отвечает на переход к определению, поиск ссылок, автодополнение и подсказки. Своей второй реализации у расширения нет – что знает движок (типы возврата проектных методов, члены платформенных типов), то знает и навигация. Без режима LSP навигации нет: в режиме CLI спрашивать некого.

Переход к определению (F12 / Ctrl+клик), в .xbsl и .yaml:

• имя объекта проекта (голое или корень точечной цепочки) → его .yaml;
• Объект.ЛокальныйТип → объявление типа; Объект.ТабличнаяЧасть → секция в yaml объекта; Перечисление.Значение → строка значения;
• Модуль.Метод (включая модули менеджера, названные по объекту) и голое имя метода внутри своего модуля → метод;
• Компоненты.Имя → узел компонента в yaml текущей формы; Компоненты.Имя.Метод → метод модуля этой формы;
• в yaml значение Обработчик: Имя → обработчик в парном .xbsl.

Найти все ссылки (Shift+F12 или Перейти к ссылкам / Найти все ссылки в контекстном меню), для методов, объектов и компонентов интерфейса – все использования по тому же индексу:

• метод → его вызовы внутри модуля, Модуль.Метод и Компоненты.Модуль.Метод, а также обработчики Обработчик: Имя в yaml;
• объект → все места, где он корень точечной цепочки;
• компонент → его обращения Компоненты.Имя в модуле формы.

Поиск ссылок идёт по индексу имён, а не по типам: цепочку он не разбирает – как и переход к определению.

Автодополнение (по . и :):

• после Объект. – семейство типов (Ссылка, Объект, …), табличные части, локальные типы и методы модуля менеджера; для перечисления – его значения;
• после Компоненты. – компоненты текущей формы; после Компоненты.X. – методы модуля X;
• в yaml после Тип: – имена объектов проекта (вид объекта показан в подсказке).

Дополнение по типам – только в LSP-режиме (разбор идёт по токенам, поэтому ключевые слова понимаются в обеих формах – пер/var, новый/new):

• внутри Запрос{ ... } после таблицы – её поля: стандартные поля вида, реквизиты и табличные части. Таблицу узнаём и по алиасу: ИЗ Акция КАК А → после А. те же поля;
• после переменной цикла по результату запроса (для С из Результат → С.) – колонки выборки (алиасы ВЫБРАТЬ ... КАК; у поля без алиаса именем становится последний сегмент);
• после переменной известного типа (пер Список = новый Массив<Строка>() → Список.) – члены этого типа. Тип берётся из аннотации, из новый, из литерала (знч Ключ = "" – это Строка), из вызова: и через модуль (Модуль.Метод()), и без квалификатора – вызов метода СВОЕГО модуля. Годятся и параметры метода;
• после значения проектного типа – его поля и методы: структура модуля, тип, описанный в метаданных, компонент интерфейса (у формы – её Свойства, методы её модуля и члены платформенного типа из Наследует);
• внутри новый Тип( – имена того, что тип несёт: подстановка сразу пишет Имя = ;
• после типа или глобали stdlib (КонтекстДоступа.) – её члены. Свойства и методы показаны раздельно: у метода свой значок, и вставляется он со скобками.

Цепочка проходится до конца, а не на один уровень: Разбор.Файл!.Прочитать(). отвечает членами результата – настойчивая операция цепочку не обрывает. Переменная цикла берёт элемент из записанного типа коллекции (Массив<Каталог.Карточка> → Каталог.Карточка), в том числе когда коллекция пришла из вызова.

Члены типов stdlib берутся из данных Элемента (каталог --data-dir), остальное – из индекса проекта. Имя в области видимости сильнее одноимённого типа: если объявлена переменная Список, то Список. – это про её тип, а не про компонент Список. Нужен линтер xbsl >= 0.10.0.

Известные пределы: вне LSP-режима индекс знает объявления, а не типы (нет дополнения после переменных). Тип не выводится там, где его неоткуда взять: у обобщённого метода платформы, где результат задаётся аргументом-типом; у выражения с операциями ("а" + Х – это операция, а не литерал); у имени, которого нет в каталоге платформы. Члены платформенных типов подсказываются русскими написаниями и в проекте на английском – в каталоге у них нет английской пары. Переименования нет. В неоднозначном контексте провайдеры молчат, а не гадают.

Quick Fix

Находки, которые линтер чинит механически, несут правку; расширение превращает её в Quick Fix:

• Лампочка на диагностике (Ctrl+.) – Исправить: <правило> – применяет точную правку: снятые хвостовые пробелы, длинное тире → среднее, … → ..., кудрявые кавычки → прямые.

• Source-действие “исправить все” – Исправить все (xbsl) – чинит все исправимые находки файла одной правкой. Запуск по сохранению – добавьте в настройки:

  "editor.codeActionsOnSave": { "source.fixAll.xbsl": "explicit" }

Правки нужны от линтера, который отдаёт их в JSON (xbsl >= 0.7.1). Предлагаются только однозначные правки и только к тому тексту, на котором они были вычислены, – снимок с версией защищает от применения смещения к изменившемуся тексту. Правки всего файла (смешанные переводы строк) остаются за xbsl --fix в командной строке.

У находки, чинить которую надо в другом файле, своя лампочка: conventions/missing-translation предлагает записать слово в словарь проекта – см. Словарь перевода.

Настройки

Правила: уровни и отключение

Старые настройки (xbsl.groups.*, linter.select / .enable / .ignore) код читает по-прежнему, но в формах их больше нет: перенести их в таблицу разом – команда XBSL: перенести настройки правил в одну таблицу.

Таблицу не обязательно править руками: команда XBSL: правила открывает панель – все правила движка списком по группам, у каждого свой уровень или “по умолчанию”, поиск по имени, фильтр “только изменённые” и кнопка сброса. Область записи выбирается явно (настройки пользователя или рабочей области), а пишет панель ровно в xbsl.rules – второй модели настроек нет.

По группам – в UI настроек. Секция “Группы правил” (наберите xbsl.groups в поиске настроек или пройдите Расширения → XBSL) даёт выпадающий список на каждый тип находок – код, описания yaml, стиль, типографика, пробелы, кодировка, структура, формы, запросы, именование, проект, безопасность: оставить собственные уровни правил группы, показывать все её находки одним уровнем (error / warning / info / hint) либо выключить группу целиком – off не просто прячет находки, а исключает правила из прогона.

По отдельным правилам – с находки. У каждой находки в лампочке (Ctrl+.) есть действие “Настроить правило…”: отключить правило или переопределить его уровень, не уходя со строки; проверка тут же перезапускается. Выбор сохраняется в настройку xbsl.rules – словарь из идентификатора правила (whitespace/trailing) или целой группы (style) в уровень или off. Точный идентификатор сильнее группы, а любой ключ xbsl.rules сильнее выпадающих списков групп. Работает и в CLI-, и в LSP-режиме.

У группы правил, добавленной плагином движка, своего выпадающего списка нет – списки перечисляют встроенные группы движка. Такая группа настраивается через xbsl.rules по своему имени ({"conventions": "off"}) либо действием “Настроить правило…” на любой её находке – оба пути работают с плагинной группой точно как со встроенной.

Исключение находки (базлайн)

Отключение правила глушит его везде; иногда же не надо исправлять одну конкретную находку – код правильный намеренно. Для этого у каждой находки в лампочке (Ctrl+.) есть действие “Исключить эту находку (в базлайн): <правило>”: введите причину, и идентичность находки (файл + правило + сообщение) запишется в файл базлайна вместе с ней. Исключается только эта одна находка – правило продолжает проверять остальные файлы и имена (выключить правило целиком – действие “Настроить правило…”). Находка исчезает из редактора, а гейт CI по тому же файлу (xbsl ... --baseline) перестаёт её показывать.

Файл – .xbsllint-baseline в папке воркспейса (создаётся при первом исключении) либо тот, на который указывает xbsl.baseline. Причина хранится рядом с замороженной находкой, и xbsl --write-baseline сохраняет её при перезаписи:

"acme/site/Основное/Заметки.yaml": {
 "naming/number": {
  "Имя 'Заметки' в единственном числе – ...": { "count": 1, "reason": "историческое имя" }
 }
}

В LSP-режиме гашение выполняет сервер – нужен движок 0.15.0 или новее; CLI-режим работает с любым движком, знающим --baseline. В идентичность входит текст сообщения, поэтому базлайн привязан к языку вывода – записывайте и проверяйте под одним xbsl.linter.lang.

LSP-режим (по умолчанию)

Расширение работает через долгоживущий сервер xbsl-lsp, а не запускает CLI на каждое событие: данные языка Элемента и индекс проекта живут в памяти, поэтому диагностика при наборе отвечает за миллисекунды, появляется hover (карточка объекта проекта, метода или компонента формы при наведении) и дополнение по типам. Переход к определению, проектная диагностика по сохранению и quick fix работают как раньше, только быстрее. Нужен линтер с extra [lsp] (pip install "xbsl[lsp]"); сервер ищется как xbsl-lsp в PATH, через xbsl.linter.pythonPath (запуск модулем) или явной командой xbsl.lsp.command.

Если сервера нет, расширение молча продолжает в прежнем CLI-режиме (подробности – в панели вывода XBSL, а фактический режим виден в статус-баре). Выключить сервер совсем – "xbsl.lsp.enabled": false; смена настройки требует перезагрузки окна.

Шаблоны кода

Команда XBSL: шаблоны кода (xbsl.templates.manage) открывает панель управления набором – это аналог диалога Параметры – Шаблоны в 1С:EDT: слева список, справа редактор, кнопки добавить, изменить, удалить, импортировать и выгрузить.

Набор состоит из двух частей. Встроенные шаблоны идут с инструментом, пользовательские лежат в файле .xbsl-templates.json в корне воркспейса – путь меняется настройкой xbsl.templates.file. Пользовательский набор дополняет встроенный, а шаблон с тем же именем замещает встроенный: так правится поведение по умолчанию, ничего не ломая.

Формат файла – тот же, что у выгрузки шаблонов 1С:EDT, поэтому набор переносится между средой и редактором в обе стороны:

• XBSL: импорт шаблонов кода (xbsl.templates.import) – влить выгрузку EDT в свой файл;
• XBSL: экспорт шаблонов кода (xbsl.templates.export) – выгрузить набор в файл того же формата.

Панель ничего не пишет сама: и чтение, и запись идут через xbsl templates – тот же механизм, что у консольной команды. Поэтому набор одинаков в обоих режимах расширения, а из шелла с ним можно работать теми же средствами (xbsl templates list / export / import).

Подстановка шаблонов при наборе работает в режиме LSP. В режиме CLI панель и обмен файлами доступны, а автодополнения по шаблонам нет.

Словарь перевода

Проект, который переводит исходники на английские написания (xbsl translate), держит свои имена, строки комментариев и строковые литералы в словаре – каталоге xbsl-translation рядом с проектом или выше: несколько файлов yaml, тысячи записей. Команда XBSL: словарь перевода (xbsl.translate.dictionary) открывает его таблицей из пяти колонок – Вид, Ключ / Перевод, Вхождений, Где встречается, Файл словаря – а каждая запись растянута на две строки: сверху ключ и остальное содержимое строки, под ним во всю ширину строки – само поле перевода, ради места, которого требует настоящее имя или целая строка комментария. Названия колонок сами служат ручками сортировки (кроме “Вида” – это просто подпись, хотя ширину и у него можно тянуть); граница между колонками тянется мышью, ширины запоминаются между открытиями панели, а двойной клик по границе сбрасывает одну эту колонку к умолчанию.

• Поле перевода редактируется. Введённое пишет движок (xbsl translate --set) – в нужный файл и с нужной областью; очищенное поле удаляет запись. Отказ показывает сообщение движка и оставляет таблицу как была.
• Литерал пишется так, как он стоит в исходнике – текст между кавычками, кавычка внутри как \", обратный слеш как \\. Значение возвращается между двумя кавычками модуля, поэтому движок проверяет, что оно вообще может там стоять, и отвергает всё, что закрыло бы литерал раньше времени; отказ показывается вместе с причиной, а поле остаётся с прежним значением.
• Два отбора: строка поиска по ключам и переводам и только незаполненные – то, что словарь ещё не покрывает. Переключатель рядом сужает таблицу до имён, до строк комментариев или до литералов.
• Предложение стоит серым прямо внутри пустого поля, как его собственная подсказка – платформенное написание, если движок его предлагает, иначе догадка сервиса машинного перевода (см. ниже). Галочка справа принимает его – щелчком или клавишей Enter, пока поле ещё пустое; стоит начать печатать – подсказка пропадает сама, как и положено подсказке поля. У литерала такая подсказка бывает, только когда его текст заполнился локально из уже принятого имени (см. ниже) – таблицы платформы называют имена, а не целое сообщение между кавычками.
• Место – ссылка: открывает файл исходника на этой строке. Файл словаря рядом – нет: короткое имя, полный путь – во всплывающей подсказке, щёлкать не по чему.
• Строка над таблицей считает строки, незаполненные среди них и покрытие проекта – то самое число, которое отдаёт xbsl translate и по которому CI останавливает сборку. Литералы посчитаны рядом, как их считает движок: в покрытие они не входят, иначе проект читал бы 100% с кириллическими сообщениями внутри.
• Длинный литерал не рвёт строку таблицы. В настоящем проекте литерал бывает в сотни символов; ячейка ключа обрезается до четырёх строк, а целиком текст показывает всплывающая подсказка.

Панель ничего не пишет сама: чтение – это xbsl translate --entries и --gaps, запись – --set. Устройство словаря – в какой файл попадёт новая запись, области, ключи ресурсов – остаётся делом движка, поэтому панель и консольная команда не могут разойтись.

Перевод прямо на находке

Правило conventions/missing-translation (по умолчанию выключено – включается в таблице правил) показывает каждое непокрытое имя, каждую строку комментария и каждый строковый литерал там, где они стоят. Его лампочка (Ctrl+.) предлагает:

• Перевести как “<написание>” – платформенная подсказка, запись в один щелчок (только когда подсказка есть, поэтому у литерала её не бывает);
• Перевести “<ключ>”… – спрашивает слово, подставив в поле ту же подсказку; у литерала подсказка поля объясняет, как текст пишется между кавычками;
• Открыть словарь переводов – панель выше, отобранная по этому ключу.

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

Предложения машинного перевода

Рядом с именем или строкой комментария, которых словарь ещё не покрывает, кнопка “Запросить машинный перевод” просит внешний сервис (Yandex Translate или Google Translate) заполнить, что получится. Догадка появляется там же, где всегда стояло платформенное написание, – серым внутри пустого поля перевода, и щелчок по галочке или Enter записывает её, ровно так же, как ручная правка поля; до этого ничего не меняется. Литерал сервису не отправляется никогда: он заполняется локально и только тогда, когда его текст целиком совпадает с уже принятым именем. Одно нажатие обходит весь проект: ограничить прогон нечем и остановить на полпути нельзя, а каждая отправленная порция это платный запрос к сервису.

Отчёт о прогоне остаётся на экране. Сколько ответов пришло из кэша, сколько запрошено, сколько сервис отклонил – те же три числа, что на пять секунд появляются строкой состояния, – стоят и в сводке самой панели, и держатся там до следующего прогона, а не только до исчезновения сообщения; наведение на эту строку называет причину каждого отказа. Когда спрашивать было решительно не о чем, строка говорит об этом словами, а не тремя нулями; когда все предложения дали локальные совпадения литералов и сервис не спрашивали вовсе, сказано и это.

Ключ задаётся командой “XBSL: Задать ключ машинного перевода” (xbsl.translate.setKey) – она спрашивает, какой из трёх завести (ключ Yandex, каталог Yandex или ключ Google), и кладёт значение в SecretStorage, никогда в настройку и никогда в командную строку движка. Если настроено больше одного сервиса, какой из них использует --suggest, решает настройка xbsl.translation.provider.

Палитра кода

Команда XBSL: палитра кода (xbsl.choosePalette) перекрашивает синтаксис XBSL одной из популярных палитр: стиль веб-среды 1С:Элемент (красные ключевые слова, синие строки), One Dark, Monokai, Dracula, GitHub Dark – либо возвращает цвета активной темы редактора. Выбор применяется правилами editor.tokenColorCustomizations, адресованными только скоупам *.xbsl, поэтому глобальная тема и другие языки не затрагиваются; расширение управляет только своими правилами (префикс xbsl-palette) и сохраняет ваши собственные настройки.

Конструктор формы

Команда XBSL: конструктор формы (xbsl.previewForm, она же кнопка в заголовке редактора у yaml форм – файлов с КомпонентИнтерфейса) открывает панель формы. Форма зависит от собственных свойств, поэтому её структура и данные правятся там же, где она показана: слева дерево структуры, справа данные, под ними каркас формы; между областями – перетаскиваемые разделители, их положение запоминается.

Панель – на каждую форму. Вторая форма открывается своей вкладкой рядом с первой; у каждой панели своё дерево, выделение и память раскрытия. Панель и её yaml ходят парой: выбор вкладки с одной стороны выводит вперёд другую, а закрытие панели закрывает yaml формы (несохранённый – остаётся). Клавиши работают в самой панели: стрелки по дереву, Alt+Вверх/Alt+Вниз, F2, Delete, Ctrl+C/Ctrl+V и Ctrl+Z/Ctrl+Y.

Структура – дерево слотов и компонентов с иконкой по виду и бейджами линтера. Контекстное меню и клавиши: Alt+Вверх/Alt+Вниз двигают компонент, F2 переименовывает, Delete удаляет, Ctrl+C/Ctrl+V переносят фрагмент yaml, есть оборачивание в контейнер, дублирование, фокус на поддереве и фильтр именованных. Узел перетаскивается на другой узел: контейнер принимает вложением, лист – следом за собой.

Данные – собственные Свойства: компонента и реквизиты объекта-владельца. Двойной клик или перетаскивание записи на узел структуры создаёт компонент ввода с готовым биндингом (Булево –> флажок, иначе поле ввода с Значение: =...).

Каркас формы рисует по yaml вложенные вертикальные/горизонтальные группы, надписи, поля ввода с подписями и =биндингами, кнопки (основная – залита), флажки, таблицы с настоящими колонками, переключаемые вкладки (Страницы), карточки, заглушки картинок и HTML-контейнеров, панель команд формы. Неизвестные и собственные типы компонентов рисуются рамкой с подписью типа и содержимым внутри – ничего не пропадает. В шапке области – масштаб (−/+, колесо над регулятором и Ctrl+колесо над каркасом) и переключатель темы: светлая (вид веб-клиента платформы, по умолчанию), тёмная или тема редактора; выбор запоминается.

Выделение общее для трёх областей. Клик по блоку каркаса и движение курсора в yaml раскрывают свёрнутые группы по пути к узлу, встают на него в структуре и наполняют панель “Свойства”; выбранный узел светится полным цветом выделения независимо от того, где сейчас фокус. Обратный ход следует только за УЖЕ открытым yaml и сам по себе закрытый не открывает: клик по узлу структуры или по блоку каркаса переводит туда курсор, не забирая фокус. Открывает закрытый yaml только явная просьба – двойной клик по узлу структуры или Ctrl+клик по блоку каркаса – и тогда он встаёт рядом с панелью, никогда в её собственной колонке, поэтому не может оказаться позади формы, которой принадлежит.

Палитра компонентов живёт рядом с деревом метаданных и появляется, пока панель формы открыта. Двойной клик по компоненту палитры вставляет его в выделенный узел структуры. Перетащить из палитры в панель нельзя – платформа не переносит перетаскивание из своего дерева в webview, поэтому вставка сделана кликом.

Панель свойств. Клик по элементу выделяет его и открывает отдельную панель “Свойства” (самостоятельная вкладка – перетащите вниз или в сторону, как удобно) – как в веб-редакторе платформы: перечисления выпадающими списками (Компоновка, выравнивания, интервалы, ширина, вид кнопки), Растягивать* – переключателем Авто / Истина / Ложь, остальное текстом; показывается стандартный набор компонента плюс все свойства из yaml (значения-объекты – только для чтения). Правки применяются к yaml-документу точечными заменами – обычный undo работает; пустое значение / (авто) снимает свойство. Выбор элемента и каждая правка позиционируют yaml-редактор на затронутой строке (не забирая фокус); Ctrl+клик или кнопка Показать в yaml переводят в редактор – удобно ориентироваться в больших формах.

Типизированные редакторы значений. Свойство-цвет открывает нативный пикер и образцы цветов, уже использованных в форме, плюс недавние – клик переиспользует оттенок. У любого однострочного значения есть тумблер литерал/биндинг: нажмите =, чтобы привязать свойство к данным, – в режиме биндинга автокомплит предлагает биндинги, уже встречающиеся в форме, и реквизиты объекта-владельца формы (=Объект.Наименование); кнопка abc возвращает к литералу.

Это каркас, а не рендер платформы: компоновка, вложенность и подписи передаются точно, размеры и стили – приблизительно (явные цвет и размер шрифта надписей применяются).

Пресеты блоков. В области структуры команда Сохранить как пресет блока на компоненте сохраняет всё его поддерево под именем (хранится между формами и сеансами); Вставить пресет блока (в шапке палитры или в меню узла) вставляет сохранённый пресет в текущее выделение – именованный постоянный вариант копипаста для часто пересобираемых компоновок. Управление пресетами блоков чистит список.

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

Обозреватель метаданных

Кнопка сворачивания в заголовке дерева (Свернуть до видов метаданных) останавливается на первом уровне: список видов остаётся виден, а раскрытые классы схлопываются. Остальные команды – создание проекта, группировка, обновление, скрытие пустых классов – лежат в меню ... того же заголовка.

Отдельная иконка 1С:Элемент на панели действий (Activity Bar) открывает дерево метаданных проекта – по образу конфигуратора платформы, но внутри VS Code.

Экспериментально. Обозреватель метаданных – экспериментальная функция, возможны ошибки и неудобства.

Дерево. Корень – проект (Проект.yaml), серым рядом Поставщик\Имя; правый клик открывает модуль приложения (Проект.xbsl). Ниже – ветка Подсистемы и категории по виду (ВидЭлемента): справочники, документы, регистры сведений/накопления, перечисления, общие модули, HTTP-сервисы, структуры, клиентские события и т.д. – каждая со своей иконкой. Пара Имя.yaml + Имя.xbsl показана одной строкой; форма объекта/списка вложена под свой объект-владелец, формы без владельца – в раздел Общие формы.

Поддеревья объектов. Справочник и документ раскрываются в Реквизиты, Табличные части, Формы; регистр – в Измерения, Ресурсы, Реквизиты; перечисление – в Значения; структура – в Поля; параметры работы клиента – в Параметры; HTTP-сервис – в Шаблоны URL с их методами; локализованные строки – в Локализацию: узел на каждый язык раздела (Локализация/<язык>/<Имя>.yaml), клик открывает переведённый текст.

Клики. Объект или поле открывает панель свойств справа (тип поля – комбобокс из примитивов, ссылок <Объект>.Ссылка? и перечислений проекта, значение можно и ввести вручную); общий модуль – свой .xbsl; форма – конструктор. Правый клик добавляет Свойства, открыть описание / модуль / модуль объекта.

Панель свойств (та же, что у конструктора формы). Скалярные свойства правятся на месте: выпадающие списки для ОбластьВидимости / Окружение, переключатель Истина / Ложь, остальное текстом. Ид и ВидЭлемента – только для чтения; коллекции (реквизиты и т.п.) правятся в дереве. Правки точечные (обычный undo работает); сохраните файл (Ctrl+S), чтобы дерево обновилось.

Секция “Все свойства” показывает и то, чего в файле ещё нет, – не только у самого объекта, но и у элемента любой его коллекции: реквизита, измерения, ресурса, поля структуры, реквизита табличной части, значения перечисления, параметра. Класс элемента называет сама метамодель, а где элементы разнотипные – выбирает его по имени: встроенные Код, Наименование и Владелец справочника имеют собственные классы, поэтому и наборы свойств у них свои.

Составные (вложенные) свойства – например ВыравниваниеСодержимогоПоГоризонтали { ... } – показаны, но не редактируются: правьте их прямо в yaml.

Создание объектов. В корне категории – действие “Добавить <класс>”: спрашивает имя и подсистему-папку, пишет минимальный валидный yaml (свежий Ид; парный .xbsl у модульных видов) и открывает его. Классы показаны, даже когда их в проекте ещё нет. Доступны все классы, которые умеет создавать движок:

В группах поддерева кнопка “+” добавляет реквизит / измерение / ресурс / значение / параметр / поле / табличную часть (и реквизит табличной части); у справочника и документа – “Добавить форму объекта”: движок генерирует форму с наполнением по реквизитам (по выбору – сразу и форму списка с колонками) и регистрирует её в Интерфейс.

Шаблоны и правки yaml считает движок (xbsl 0.16+): те же операции доступны агентам через его MCP-инструменты meta_* и любому редактору через LSP-запросы xbsl/meta* или подкоманды CLI – дерево лишь собирает параметры и применяет присланные изменения (обычный undo работает).

Подсистемы. Ветка Подсистемы перечисляет папки-подсистемы (клик открывает Подсистема.yaml); “Добавить подсистему” создаёт папку с Подсистема.yaml. На корне проекта – “Отбор по подсистеме” (мультивыбор) и “Снять отбор”; активный отбор виден серым рядом с проектом.

Статус git. Строки объектов, форм, подсистем и проекта несут SCM-декорацию файла (цвет и бейдж) как в Проводнике, сохраняя иконку вида.

Удаление. Правый клик по объекту – “Удалить объект” (с подтверждением; удаляет файлы объекта, обратимо через Undo; ссылки не обновляются – оборванные покажет линтер).

Созданный объект – это заготовка в файлах, он не деплоится сам; невалидный всплывёт только при следующем деплое (откат ловит elemctl), рабочие файлы не портит.

Пример: демо-приложение деревом и деплой на 1cmycloud.com

Дерево умеет собрать рабочее приложение с нуля (yaml генерируют те же шаблоны, что и дерево):

1. Открыть папку с файлом проекта – в дереве появится корень-проект.
2. Подсистемы → “+” → Добавить подсистему → Основное.
3. Справочники → “+” → Добавить справочник → Товары (подсистема Основное); так же Категории.
4. Под Товары → Реквизиты → “+” → Добавить реквизит → Цена, Артикул.
5. Перечисления → Добавить перечисление → СтатусТовара; в Значения → ВНаличии, ПодЗаказ.
6. Задеплоить: elemctl deploy --app-id <app> --project-dir <папка проекта> --output <tmp> (создать приложение заранее: elemctl apps ensure <app> --latest-build --wait).

Отчёт деплоя на 1cmycloud.com (ok: true только при ФАКТИЧЕСКОМ применении):

собран архив <проект> 1.0-N.xasm (версия 1.0-N)
сборка загружена, применение запущено, ждём стабилизации приложения...
приложение в статусе Running, проверяем фактическое применение...
проверка пройдена: сборка применена
{
  "uri": "https://<хост>.1cmycloud.com/applications/<app>",
  "status": "Running",
  "applied-version": "1.0-N",
  "applied": true,
  "uri-status": 200,
  "problems": [],
  "ok": true
}

applied: true и ok: true означают, что сборка реально применилась – справочники Товары / Категории и перечисление СтатусТовара, собранные деревом, открываются в стандартном интерфейсе (демо не требует OIDC/входа).

Документация

Отдельный контейнер Документация (1С:Элемент) на панели действий – справка платформы так, как её показывает сайт документации, но собранная из вашего дистрибутива: она совпадает с вашей версией платформы и работает без сети.

Дерево. Курируемое “Содержание”, совпадающее с сайтом: руководства разработчика и администратора, справочник типов (Стд::Коллекции → Массив → …) и язык запросов. Строится из данных сайдбара самого дистрибутива, поэтому структура как на сайте. Клик по узлу открывает страницу.

Поиск. Кнопка поиска в заголовке вида (команда XBSL: поиск по документации) ищет полнотекстово по всему справочнику и руководству; выбор из списка открывает страницу.

Страница. Открывается вкладкой редактора сбоку и не забирает фокус: очищенная статья с кодом (у примеров – кнопка Копировать), таблицами и картинками и ссылкой Первоисточник на ту же страницу на сайте. Разделы страницы вложены в её узел дерева, внутренние ссылки ведут к другим страницам в этой же вкладке, а при открытии страницы дерево “Содержание” на неё позиционируется.

Документация по символу. Правый клик на типе или переменной в .xbsl – XBSL: документация по символу – открывает её страницу. Для типа сразу открывается страница справочника; для метода или неоднозначного имени показывается список кандидатов, ранжированный по приёмнику перед точкой (Задание.Настроить отдаёт предпочтение страницам запланированного задания, а не топику руководства).

Куда ведут остальные входы. Подсказка при наведении на имя в .xbsl показывает описание типа и ссылку Документация; в конструкторе форм у элемента палитры есть действие Открыть документацию (краткое описание видно и в подсказке). Оба открывают страницу в этой же панели – читать про незнакомый компонент не нужно уходить из редактора.

F12 отступает на страницу. Переход к определению отвечает по индексу проекта, поэтому у члена платформы прыгать некуда – там клавиша открывает страницу документации вместо сообщения о промахе. Настоящее определение всегда выигрывает, а когда нет ни того ни другого, о промахе сообщает VS Code, как обычно.

Данные даёт LSP-сервер линтера, поэтому нужен LSP-режим и база документации, собранная из вашего дистрибутива (xbsl >= 0.12.0, см. README линтера). В обычном режиме (CLI) вид сообщает, что документация доступна в LSP-режиме.

Деплой на стенд

Команда XBSL: деплой на стенд (elemctl) (xbsl.deploy, она же кнопка-облачко в заголовке дерева метаданных – деплоится проект целиком, а не открытый файл) запускает elemctl deploy – сборка, загрузка, применение и проверка фактического применения – терминальной задачей, после диалога подтверждения с точной командной строкой. При сбое применения платформа молча откатывает приложение на прежнюю сборку, продолжая отвечать Running; elemctl этому статусу не верит и завершается ненулевым кодом.

Рабочий каталог – папка воркспейса: подключение и цель elemctl читает из своего .env (ELEMENT_BASE_URL, ELEMENT_CLIENT_ID/SECRET, ELEMENT_APP_ID, ELEMENT_PROJECT_ID). Заданный xbsl.projectRoot передаётся как --project-dir; отсутствующий elemctl предлагается установить прямо из сообщения об ошибке.

Отладка

Отладка приложений 1С:Элемент в обычном VS Code: точки останова, стек вызовов, сцепляющий клиентские и серверные кадры, значения переменных, пошаговое выполнение – без веб-среды на Theia. Расширение и здесь тонкое: оно запускает штатный debug-адаптер платформы (Java, протокол DAP) и получает координаты сессии через elemctl (Console API /actions/debug). Идентификатор сессии, сгенерированный на клиенте, сшивает адаптер и отлаживаемое приложение через сервер отладки платформы.

До версии 0.57 это было отдельное расширение XBSL Debug (keyfire.xbsl-debug). Теперь оно часть этого: деплой и отладка адресуют одно и то же приложение одним и тем же elemctl, а разделение приводило лишь к тому, что реквизиты спрашивались дважды. Настройки старого расширения (xbslDebug.*) по-прежнему читаются – прежняя конфигурация продолжает работать.

С чего начать. Выполните XBSL: настроить отладку 1С:Элемент (xbsl.debug.setup) из палитры команд – мастер проверит Java, каталог адаптера и elemctl, что сможет – починит на месте и предложит создать launch.json. Дальше откройте папку с исходниками, поставьте точку останова в .xbsl и нажмите F5: приложение откроется в браузере с параметрами отладки, а выполнение остановится на вашей точке.

Что нужно:

1. JDK 17+ (21 тоже подходит) – java -version.
2. elemctl >= 0.5 (команды apps debug и debug-adapter) с настроенным .env в корне исходников. Отсутствующий elemctl предлагается установить из сообщения об ошибке и из мастера.
3. Debug-адаптер платформы. Возьмите его из своего дистрибутива 1С:Элемент (.../@1c-appengine-plugin/bin/debugger – каталог с подпапкой repo, где лежат jar-файлы) и задайте xbsl.debug.adapterPath. Адаптер – проприетарный код 1С, в расширение он не входит.
4. Отладка, включённая на сервере приложения – на облачных стендах обычно уже включена.

Исполняемый файл elemctl и идентификатор приложения общие с деплоем (xbsl.deploy.elemctlPath, xbsl.deploy.appId), а реквизиты Console API живут в .env корня исходников, а не в настройке – elemctl читает их сам. launch.json необязателен; его атрибуты – appId, envFile, authMode и workspace.

Как привязываются точки останова. Сервер отладки опознаёт модуль по пути относительно корня исходников в форме <Поставщик>/<Имя>/<путь в проекте>.xbsl с прямыми разделителями. Поэтому исходники должны лежать в каталоге <Поставщик>/<Имя>/, совпадающем с Проект.yaml, а воркспейс – указывать на каталог, который его содержит; этот корень расширение определяет от открытой папки само, так что годится и корень репозитория, и подпапка.

Обойдённая ошибка платформы. Раскрытие структуры в панели переменных на клиентском кадре вешало отлаживаемое приложение и рвало сессию: DAP-запрос variables БЕЗ поля filter – ровно такой панель переменных VS Code шлёт для небольших значений – роняет JS-рантайм приложения, тогда как запрос с фильтром работает штатно. Расширение переписывает каждый запрос без фильтра в запросы с фильтром (named + indexed, счётчики берутся из ответа родителя) и склеивает результаты, так что дерево значений раскрывается нормально и на клиентских, и на серверных кадрах. Обход безусловный, настройки у него нет: выключение не даёт ничего, кроме оборванной сессии.

Команды

• XBSL: новый проект 1С:Элемент (xbsl.project.new) – мастер создания проекта (см. выше).
• XBSL: проверить весь проект (xbsl.lintProject) – проверить весь воркспейс.
• XBSL: структурный поиск по формам (xbsl.forms.search) – поиск компонентов по типу и свойствам (см. выше).
• XBSL: перезапустить линтер (xbsl.restartLinter) – сбросить и перепроверить открытые файлы.
• XBSL: палитра кода (xbsl.choosePalette) – выбрать палитру подсветки XBSL (см. выше).
• XBSL: шаблоны кода (xbsl.templates.manage), импорт (xbsl.templates.import) и экспорт (xbsl.templates.export) – набор шаблонов и обмен выгрузкой EDT (см. выше).
• XBSL: деплой на стенд (elemctl) (xbsl.deploy) – развернуть проект на стенде (см. выше).
• XBSL: конструктор формы (xbsl.previewForm) – панель активной yaml-формы (см. выше).
• XBSL: поиск по документации (xbsl.docs.search) и документация по символу (xbsl.docs.showForSymbol) – вид Документация (см. выше).
• Команды обозревателя метаданных (xbsl.metadata.*) вызываются из самого дерева и его контекстных меню: свойства, добавить объект / поле / подсистему, форму объекта, отбор по подсистеме, удалить объект, обновить. См. Обозреватель метаданных.

Обратная связь и ошибки

Расширение активно развивается, поэтому возможны ошибки и шероховатости – особенно в обозревателе метаданных и конструкторе форм. Если что-то работает не так, пожалуйста, сообщите об этом (по возможности с шагами воспроизведения и версиями расширения/движка из строки состояния) в issues проекта на GitHub:

https://github.com/keyfire/xbsl/issues

VS Code также предлагает Report Issue на странице расширения (по ссылке bugs из манифеста).

Разработка

npm install
npm run compile          # esbuild-бандл -> dist/extension.js
npm run check            # проверка типов tsc
npm test                 # юнит-тесты чистых ядер (чистый Node, без раннера)
npm run package          # сборка .vsix (через @vscode/vsce)

F5 в VS Code запускает Extension Development Host с загруженным расширением.

Лицензия

MIT – см. репозиторий.