Files
cc-1c-skills/docs/form-dsl-spec.md
T
Nick Shirokov 4c2c72abce feat(form-decompile,form-compile): унификация событий элементов на events-мапу (кластер Events DSL)
Несогласованность DSL: события ФОРМЫ описывались интуитивной мапой
events:{Событие:Обработчик}, а события ЭЛЕМЕНТА — двумя сущностями
on:[...] + handlers:{...}. Два способа для одного понятия путали модель.

Унифицировано на единую мапу events:{Событие:ИмяОбработчика} на форме И
элементах (как form-level). Декомпилятор эмитит только её, с явными именами
обработчиков (прозрачно, консистентно с form-level).

Компилятор (ps1+py):
- Emit-Events читает events-мапу (основной формат); значение null/"" →
  имя по конвенции ИмяЭлемента+суффикс (прощающий fallback).
- legacy on/handlers по-прежнему принимаются ради совместимости (не эмитятся).
- choiceButton: проверка StartChoice через оба формата (Test-ElementEvent).
- events добавлен в whitelist ключей элемента.

Декомпилятор: Get-Events → упорядоченная мапа {Событие:Обработчик} в порядке
документа; убраны on/handlers и инверсия авто-имён.

spec/SKILL.md: events как единственный рекомендованный формат, on/handlers
помечены legacy. В SKILL.md только явные имена (null-сахар — деталь spec,
инструкцию не раздуваем).

Корпус acc_8.3.24: 190 элементов в 114/400 форм теряли Events до фикса (баг
on/handlers разобран отдельным коммитом). Раундтрип 2.17: Events ушли из топа
LOST, match 4→6, 0 compile-fail. Регресс ps+py 32/32, снэпшот events (добавлен
блок Events у поля с переименованным обработчиком) сертифицирован в 1С 8.3.24.

Follow-up: form-edit использует расширенный on с {event,callType} —
унификация отдельным решением (см. BACKLOG).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-05 12:46:56 +03:00

29 KiB
Raw Blame History

Form DSL Specification

Спецификация JSON-формата для /form-compile — компактного описания управляемых форм 1С:Предприятия 8.3.


1. Корневой объект

{
  "title": "Заголовок формы",
  "properties": { ... },
  "excludedCommands": [ ... ],
  "events": { ... },
  "elements": [ ... ],
  "attributes": [ ... ],
  "parameters": [ ... ],
  "commands": [ ... ]
}
Поле Тип Описание
title string Заголовок формы (необязательный)
properties object Свойства формы (необязательный)
excludedCommands string[] Исключённые стандартные команды (необязательный)
events object Обработчики событий формы (необязательный)
elements array Дерево UI-элементов (необязательный)
attributes array Реквизиты формы (необязательный)
parameters array Параметры формы (необязательный)
commands array Команды формы (необязательный)

2. Properties — свойства формы

Объект со свойствами в camelCase. Компилятор преобразует в PascalCase для XML.

"properties": {
  "autoTitle": false,
  "windowOpeningMode": "LockOwnerWindow",
  "commandBarLocation": "Bottom"
}

Поддерживаемые свойства

DSL ключ XML элемент Значения
autoTitle <AutoTitle> true / false
windowOpeningMode <WindowOpeningMode> LockOwnerWindow, Modeless
commandBarLocation <CommandBarLocation> Top, Bottom, None
saveDataInSettings <SaveDataInSettings> UseList, Use, DontUse
autoSaveDataInSettings <AutoSaveDataInSettings> Use, DontUse
autoTime <AutoTime> CurrentOrLast, Current, Last
usePostingMode <UsePostingMode> Auto, Postings, Movements
repostOnWrite <RepostOnWrite> true / false
autoURL <AutoURL> true / false
autoFillCheck <AutoFillCheck> true / false
customizable <Customizable> true / false
enterKeyBehavior <EnterKeyBehavior> DefaultButton, NewLine
verticalScroll <VerticalScroll> useIfNecessary, Auto, AlwaysShow, Never
width <Width> число
height <Height> число
group <Group> Vertical, Horizontal, AlwaysHorizontal, AlwaysVertical
useForFoldersAndItems <UseForFoldersAndItems> Folders, Items, FoldersAndItems

Нераспознанные ключи преобразуются с автоматическим PascalCase (первая буква в верхний регистр).


3. Events — обработчики событий формы

"events": {
  "OnCreateAtServer": "ПриСозданииНаСервере",
  "OnOpen": "ПриОткрытии"
}

Ключ — имя события, значение — имя процедуры-обработчика. Тот же формат events используется и на элементах (§4.1) — единый способ описания событий во всём DSL.

Доступные события

Событие Описание
OnCreateAtServer Создание формы на сервере
OnOpen Открытие формы
BeforeClose Перед закрытием
OnClose При закрытии
BeforeWrite Перед записью
BeforeWriteAtServer Перед записью на сервере
OnWriteAtServer При записи на сервере
AfterWriteAtServer После записи на сервере
AfterWrite После записи
OnReadAtServer При чтении объекта
NotificationProcessing Обработка оповещений
ChoiceProcessing Обработка выбора
FillCheckProcessingAtServer Проверка заполнения

4. Elements — дерево UI-элементов

Массив объектов. Тип элемента определяется ключом-идентификатором.

4.1. Общие свойства всех элементов

Свойство Тип Описание
name string Имя элемента (по умолчанию — из значения ключа типа)
title string/object Заголовок. Нет ключа → авто-вывод из имени (для page/popup/label и непривязанных полей/кнопок). "" → подавить (заголовок не выводится). Строка → ru. Объект { "ru": "…", "en": "…" } → мультиязычный (по <v8:item> на язык). Так же tooltip/inputHint/title команд/реквизитов/колонок
hidden bool true<Visible>false</Visible>
disabled bool true<Enabled>false</Enabled>
readOnly bool true<ReadOnly>true</ReadOnly>
events object Обработчики событий: { "ИмяСобытия": "ИмяОбработчика" } — тот же формат, что у событий формы (§3). Значение null → имя по конвенции (§4.2). См. §4.2

4.1a. Общие layout-свойства

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

Свойство XML Значения
width <Width> число
height <Height> число (у table<HeightInTableRows>, высота в строках)
horizontalStretch <HorizontalStretch> true
verticalStretch <VerticalStretch> true
autoMaxWidth <AutoMaxWidth> false (у input при multiLine подставляется автоматически)
autoMaxHeight <AutoMaxHeight> false
maxWidth <MaxWidth> число
maxHeight <MaxHeight> число
groupHorizontalAlign <GroupHorizontalAlign> Left, Center, Right
groupVerticalAlign <GroupVerticalAlign> Top, Center, Bottom
horizontalAlign <HorizontalAlign> Left, Center, Right
skipOnInput <SkipOnInput> true

4.2. События элемента и автоименование обработчиков

События элемента описываются мапой events (как у формы):

{ "input": "Контрагент", "path": "Объект.Контрагент",
  "events": { "OnChange": "КонтрагентПриИзменении" } }

Значение — имя процедуры-обработчика. Если вместо имени указать null, имя генерируется автоматически по конвенции 1С <ИмяЭлемента><РусскийСуффикс>:

{ "input": "Контрагент", "path": "Объект.Контрагент",
  "events": { "OnChange": null } }   // → обработчик КонтрагентПриИзменении

Суффиксы для авто-имени:

Событие Суффикс
OnChange ПриИзменении
StartChoice НачалоВыбора
ChoiceProcessing ОбработкаВыбора
AutoComplete АвтоПодбор
Clearing Очистка
Opening Открытие
Click Нажатие
OnActivateRow ПриАктивизацииСтроки
BeforeAddRow ПередНачаломДобавления
BeforeDeleteRow ПередУдалением
BeforeRowChange ПередНачаломИзменения
OnStartEdit ПриНачалеРедактирования
OnEndEdit ПриОкончанииРедактирования
Selection ВыборСтроки
OnCurrentPageChange ПриСменеСтраницы
TextEditEnd ОкончаниеВводаТекста

Legacy-формат (принимается, но устарел). Ранее события элемента задавались парой on (массив имён событий) + handlers (переопределение имён): { "on": ["OnChange"], "handlers": { … } }. Компилятор по-прежнему его принимает ради совместимости, но рекомендуемый и единственный эмитируемый формат — мапа events. Новые формы пишите через events.

4.3. Типы элементов

group — UsualGroup

{ "group": "horizontal", "name": "ГруппаШапка", "children": [ ... ] }
Свойство Тип Описание
group string Ориентация: horizontal, vertical, alwaysHorizontal, alwaysVertical, collapsible
children array Вложенные элементы
showTitle bool Показывать заголовок группы
representation string none, normal, weak, strong
united bool Объединение

input — InputField

{ "input": "Организация", "path": "Объект.Организация", "events": { "OnChange": "ОрганизацияПриИзменении" } }
Свойство Тип Описание
path string DataPath
multiLine bool Многострочный режим
passwordMode bool Режим пароля
titleLocation string none, left, right, top, bottom
choiceButton bool Показывать кнопку выбора
clearButton bool Показывать кнопку очистки
spinButton bool Показывать кнопку прокрутки
dropListButton bool Показывать кнопку раскрытия
markIncomplete bool Автопометка незаполненных
editMode string Режим редактирования: EnterOnInput, Directly
skipOnInput bool Пропускать при вводе
inputHint string Подсказка ввода (placeholder)
width int Ширина
height int Высота
horizontalStretch bool Растягивание по горизонтали
verticalStretch bool Растягивание по вертикали
autoMaxWidth bool Автомаксимальная ширина
autoMaxHeight bool Автомаксимальная высота

check — CheckBoxField

{ "check": "ФлагАктивности", "path": "Активен", "events": { "OnChange": "ФлагАктивностиПриИзменении" } }
Свойство Тип Описание
path string DataPath
checkBoxType string Вид флажка. Нет ключа → умный дефолт Auto. "" → не выводить тег (платформа применит своё умолчание). Значения: auto, checkBox, switcher, tumbler
editMode string Режим редактирования: EnterOnInput, Directly
titleLocation string Расположение заголовка. Нет ключа → умный дефолт Right (флажки почти всегда справа). "" → не выводить тег (платформа применит своё умолчание, Left). Значение (none/left/top/…) → как указано

radio — RadioButtonField

{
  "radio": "СпособКурса",
  "path": "Объект.СпособУстановкиКурса",
  "radioButtonType": "Auto",
  "choiceList": [
    { "value": "Enum.СпособыКурса.EnumValue.Авто",   "presentation": "автоматически" },
    { "value": "Enum.СпособыКурса.EnumValue.Ручной", "presentation": { "ru": "вручную", "en": "manual" } }
  ]
}
Свойство Тип Описание
path string DataPath
radioButtonType string Auto (по умолчанию), RadioButtons, Tumbler
columnsCount int Число колонок раскладки
titleLocation string Расположение заголовка. Нет ключа → умный дефолт None. "" → не выводить тег (платформа применит своё умолчание). Значение → как указано
choiceList array Варианты выбора: массив { value, presentation }

choiceList[*]:

Свойство Тип Описание
value string/number/bool Значение варианта. Для перечисления — "Enum.ИмяТипа.EnumValue.ИмяЗначения" (xsi:type автоматически: xr:DesignTimeRef / xs:string / xs:decimal / xs:boolean)
presentation string или object Текст рядом с переключателем. Строка → ru; объект {ru, en, ...} → мультиязык. Если не задано — выводится из имени значения

label — LabelDecoration

{ "label": "Подсказка", "title": "Выберите параметры", "hyperlink": true }
Свойство Тип Описание
title string Текст надписи
hyperlink bool Режим гиперссылки
width int Ширина
height int Высота
autoMaxWidth bool Автомаксимальная ширина
autoMaxHeight bool Автомаксимальная высота

labelField — LabelField

{ "labelField": "СтатусОбработки", "path": "Статус" }
Свойство Тип Описание
path string DataPath
hyperlink bool Режим гиперссылки (у LabelField платформенный тег <Hiperlink> — опечатка 1С, компилятор учитывает)
editMode string Режим редактирования: EnterOnInput, Directly

table — Table

{
  "table": "Товары", "path": "Объект.Товары",
  "columns": [
    { "input": "Номенклатура", "path": "Объект.Товары.Номенклатура" }
  ]
}
Свойство Тип Описание
path string DataPath
columns array Колонки (элементы input/check/labelField/picField, либо columnGroup для группировки)
representation string List, Tree, HierarchicalList
changeRowSet bool Разрешить добавление/удаление строк
changeRowOrder bool Разрешить перемещение строк
height int Высота в строках таблицы
header bool Показывать шапку
footer bool Показывать подвал
commandBarLocation string None, Top, Bottom, Auto
searchStringLocation string None, Top, Bottom, CommandBar, Auto
viewStatusLocation string None, Top, Bottom, Auto
searchControlLocation string None, Top, Bottom, Auto
excludedCommands string[] Исключённые стандартные команды таблицы (Add, Delete, MoveUp, SortListAsc, …) → <CommandSet>

columnGroup — ColumnGroup

Группа колонок таблицы. Используется только внутри columns таблицы. Допускается вложение columnGroup в columnGroup.

{ "table": "Список", "path": "Список", "columns": [
    { "columnGroup": "horizontal", "name": "ГруппаДата", "title": "Срок", "children": [
        { "input": "ДатаНачала", "path": "Список.ДатаНачала" },
        { "input": "ДатаОкончания", "path": "Список.ДатаОкончания" }
    ]},
    { "columnGroup": "inCell", "name": "ГруппаИсполнитель", "showInHeader": true, "children": [
        { "input": "Исполнитель", "path": "Список.Исполнитель" }
    ]}
]}
Свойство Тип Описание
columnGroup string Ориентация: horizontal, vertical, inCell (склейка колонок в одной ячейке шапки)
name string Имя элемента (рекомендуется задавать явно)
title string/object Заголовок группы
showTitle bool Показывать заголовок
showInHeader bool Показывать в шапке таблицы
width int Ширина
horizontalStretch bool Растягивание
children array Колонки внутри группы

pages / page — Pages / Page

{
  "pages": "Страницы", "children": [
    { "page": "Основное", "children": [ ... ] },
    { "page": "Дополнительно", "children": [ ... ] }
  ]
}

Page поддерживает group для задания ориентации содержимого и children для вложенных элементов.

Pages поддерживает pagesRepresentation: None, TabsOnTop, TabsOnBottom, TabsOnLeft, TabsOnRight.

button — Button

{ "button": "Загрузить", "command": "Загрузить", "defaultButton": true }
Свойство Тип Описание
command string Имя команды формы (→ Form.Command.<name>)
stdCommand string Стандартная команда (→ Form.StandardCommand.<name>)
type string usual, hyperlink, commandBar
defaultButton bool Кнопка по умолчанию
picture string Ссылка на картинку (StdPicture.Name)
representation string Auto, Picture, Text, PictureAndText
locationInCommandBar string InCommandBar, InAdditionalSubmenu

picture — PictureDecoration

{ "picture": "Логотип", "src": "CommonPicture.Логотип" }
Свойство Тип Описание
src или picture (как свойство) string Ссылка на картинку
loadTransparent bool true → загружать прозрачной. По умолчанию false
hyperlink bool Режим гиперссылки
width int Ширина
height int Высота

picField — PictureField

{ "picField": "Фото", "path": "Фотография" }

Для поля, привязанного к булеву/числу (иконка-индикатор в колонке), задайте картинку значения через valuesPicture — без неё иконка не отрисуется:

{ "picField": "Картинка", "path": "Таблица.Картинка",
  "valuesPicture": "StdPicture.Favorites", "loadTransparent": true }
Свойство Тип Описание
valuesPicture string Ссылка на картинку значения (StdPicture.*, CommonPicture.*)
loadTransparent bool Скрыть кадр «нет значения». Выводится только при true

calendar — CalendarField

{ "calendar": "Дата", "path": "ДатаОтчета" }

cmdBar — CommandBar

{ "cmdBar": "КоманднаяПанель", "children": [ ... ] }

popup — Popup

{ "popup": "Печать", "picture": "StdPicture.Print", "children": [ ... ] }

buttonGroup — ButtonGroup

Группа кнопок внутри командной панели (autoCmdBar/cmdBar/popup). Значение ключа — имя элемента.

{ "buttonGroup": "ГруппаПереместить", "title": "Переместить", "children": [
    { "button": "ПереместитьВверх", "command": "ПереместитьВверх" },
    { "button": "ПереместитьВниз", "command": "ПереместитьВниз" }
] }
Свойство Тип Описание
buttonGroup string Имя элемента
title string/object Заголовок группы
representation string Auto, Picture, Text, PictureAndText
children array Кнопки (button) внутри группы

autoCmdBar — командная панель формы

Командная панель самой формы (<AutoCommandBar id="-1">). Задаётся как элемент в elements; компилятор автоматически вынимает его из дерева. Нужен только если в панель помещаются явные кнопки/группы или меняется выравнивание/автозаполнение — иначе панель формируется автоматически.

{ "autoCmdBar": "ФормаКоманднаяПанель", "horizontalAlign": "Right", "autofill": false, "children": [
    { "button": "ОК", "command": "ОК", "defaultButton": true },
    { "button": "Отмена", "command": "Отмена" }
] }
Свойство Тип Описание
autoCmdBar string Имя панели (обычно ФормаКоманднаяПанель)
horizontalAlign string Right, Left, Center
autofill bool false — отключить автозаполнение стандартными командами
children array Кнопки/группы кнопок панели

5. Attributes — реквизиты формы

"attributes": [
  { "name": "Объект", "type": "DocumentObject.Реализация", "main": true },
  { "name": "Итого", "type": "decimal(15,2)" },
  { "name": "Таблица", "type": "ValueTable", "columns": [
    { "name": "Номенклатура", "type": "CatalogRef.Номенклатура" },
    { "name": "Количество", "type": "decimal(10,3)" }
  ]}
]
Свойство Тип Описание
name string Имя реквизита (обязательно)
type string Тип (shorthand)
main bool Основной реквизит формы
title string Заголовок
savedData bool Сохраняемые данные
fillChecking string Show, DontShow
columns array Колонки для ValueTable/ValueTree

6. Parameters — параметры формы

"parameters": [
  { "name": "Ключ", "type": "DocumentRef.Реализация", "key": true },
  { "name": "Основание", "type": "DocumentRef.Реализация" }
]
Свойство Тип Описание
name string Имя параметра (обязательно)
type string Тип (shorthand)
key bool Ключевой параметр

7. Commands — команды формы

"commands": [
  { "name": "Печать", "action": "ПечатьОбработка", "shortcut": "Ctrl+P" },
  { "name": "Обновить", "action": "ОбновитьОбработка", "picture": "StdPicture.Refresh" }
]
Свойство Тип Описание
name string Имя команды (обязательно)
action string Имя процедуры-обработчика
title string Заголовок
tooltip string/object Всплывающая подсказка команды (<ToolTip>)
currentRowUse string Использование текущей строки: Auto, DontUse, Use
shortcut string Клавиатурное сочетание
picture string Ссылка на картинку
representation string Auto, Picture, Text, PictureAndText

8. Система типов (shorthand)

Примитивные типы

DSL XML
"string" xs:string (неограниченная)
"string(100)" xs:string + Length=100
"decimal(15,2)" xs:decimal + Digits=15, FractionDigits=2, AllowedSign=Any
"decimal(10,0,nonneg)" xs:decimal + AllowedSign=Nonnegative
"boolean" xs:boolean
"date" xs:dateTime + DateFractions=Date
"dateTime" xs:dateTime + DateFractions=DateTime
"time" xs:dateTime + DateFractions=Time

Ссылочные типы

DSL XML
"CatalogRef.Организации" cfg:CatalogRef.Организации
"DocumentObject.Реализация" cfg:DocumentObject.Реализация
"EnumRef.СтавкиНДС" cfg:EnumRef.СтавкиНДС
"DataProcessorObject.ЗагрузкаДанных" cfg:DataProcessorObject.ЗагрузкаДанных

Платформенные типы

DSL XML
"ValueTable" v8:ValueTable
"ValueTree" v8:ValueTree
"ValueList" v8:ValueListType
"FormattedString" v8ui:FormattedString
"Picture" v8ui:Picture
"DynamicList" cfg:DynamicList

Составные типы

Разделитель " | ":

"type": "CatalogRef.Организации | CatalogRef.ИндивидуальныеПредприниматели"

9. Автогенерация

Companion-элементы

Для каждого элемента автоматически создаются служебные вложенные элементы:

Тип элемента Companions
UsualGroup ExtendedTooltip
InputField ContextMenu, ExtendedTooltip
CheckBoxField ContextMenu, ExtendedTooltip
RadioButtonField ContextMenu, ExtendedTooltip
LabelDecoration ContextMenu, ExtendedTooltip
LabelField ContextMenu, ExtendedTooltip
PictureDecoration ContextMenu, ExtendedTooltip
PictureField ContextMenu, ExtendedTooltip
CalendarField ContextMenu, ExtendedTooltip
Table ContextMenu, AutoCommandBar, SearchStringAddition, ViewStatusAddition, SearchControlAddition
Pages ExtendedTooltip
Page ExtendedTooltip
Button ExtendedTooltip

Именование: <name>КонтекстноеМеню, <name>РасширеннаяПодсказка, <name>КоманднаяПанель, <name>СтрокаПоиска, <name>СостояниеПросмотра, <name>УправлениеПоиском.

ID

Последовательная нумерация начиная с 1. AutoCommandBar формы всегда имеет id="-1".

Namespace

Все 17 namespace-деклараций добавляются автоматически (version="2.17").

Кодировка

UTF-8 с BOM (как в файлах конфигурации 1С).