Form DSL Specification
Спецификация JSON-формата для /form-compile — компактного описания управляемых форм 1С:Предприятия 8.3.
1. Корневой объект
| Поле |
Тип |
Описание |
title |
string |
Заголовок формы (необязательный) |
properties |
object |
Свойства формы (необязательный) |
excludedCommands |
string[] |
Исключённые стандартные команды (необязательный) |
events |
object |
Обработчики событий формы (необязательный) |
elements |
array |
Дерево UI-элементов (необязательный) |
attributes |
array |
Реквизиты формы (необязательный) |
parameters |
array |
Параметры формы (необязательный) |
commands |
array |
Команды формы (необязательный) |
2. Properties — свойства формы
Объект со свойствами в camelCase. Компилятор преобразует в PascalCase для XML.
Поддерживаемые свойства
| 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 используется и на элементах (§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 (как у формы):
Значение — имя процедуры-обработчика. Если вместо имени указать null, имя
генерируется автоматически по конвенции 1С <ИмяЭлемента><РусскийСуффикс>:
Суффиксы для авто-имени:
| Событие |
Суффикс |
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 |
string |
Ориентация: horizontal, vertical, alwaysHorizontal, alwaysVertical, collapsible |
children |
array |
Вложенные элементы |
showTitle |
bool |
Показывать заголовок группы |
representation |
string |
none, normal, weak, strong |
united |
bool |
Объединение |
input — InputField
| Свойство |
Тип |
Описание |
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
| Свойство |
Тип |
Описание |
path |
string |
DataPath |
checkBoxType |
string |
Вид флажка. Нет ключа → умный дефолт Auto. "" → не выводить тег (платформа применит своё умолчание). Значения: auto, checkBox, switcher, tumbler |
editMode |
string |
Режим редактирования: EnterOnInput, Directly |
titleLocation |
string |
Расположение заголовка. Нет ключа → умный дефолт Right (флажки почти всегда справа). "" → не выводить тег (платформа применит своё умолчание, Left). Значение (none/left/top/…) → как указано |
radio — RadioButtonField
| Свойство |
Тип |
Описание |
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
| Свойство |
Тип |
Описание |
title |
string |
Текст надписи |
hyperlink |
bool |
Режим гиперссылки |
width |
int |
Ширина |
height |
int |
Высота |
autoMaxWidth |
bool |
Автомаксимальная ширина |
autoMaxHeight |
bool |
Автомаксимальная высота |
labelField — LabelField
| Свойство |
Тип |
Описание |
path |
string |
DataPath |
hyperlink |
bool |
Режим гиперссылки (у LabelField платформенный тег <Hiperlink> — опечатка 1С, компилятор учитывает) |
editMode |
string |
Режим редактирования: EnterOnInput, Directly |
table — Table
| Свойство |
Тип |
Описание |
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.
| Свойство |
Тип |
Описание |
columnGroup |
string |
Ориентация: horizontal, vertical, inCell (склейка колонок в одной ячейке шапки) |
name |
string |
Имя элемента (рекомендуется задавать явно) |
title |
string/object |
Заголовок группы |
showTitle |
bool |
Показывать заголовок |
showInHeader |
bool |
Показывать в шапке таблицы |
width |
int |
Ширина |
horizontalStretch |
bool |
Растягивание |
children |
array |
Колонки внутри группы |
pages / page — Pages / Page
Page поддерживает group для задания ориентации содержимого и children для вложенных элементов.
Pages поддерживает pagesRepresentation: None, TabsOnTop, TabsOnBottom, TabsOnLeft, TabsOnRight.
button — Button
| Свойство |
Тип |
Описание |
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
| Свойство |
Тип |
Описание |
src или picture (как свойство) |
string |
Ссылка на картинку |
loadTransparent |
bool |
true → загружать прозрачной. По умолчанию false |
hyperlink |
bool |
Режим гиперссылки |
width |
int |
Ширина |
height |
int |
Высота |
picField — PictureField
Для поля, привязанного к булеву/числу (иконка-индикатор в колонке), задайте картинку значения через valuesPicture — без неё иконка не отрисуется:
| Свойство |
Тип |
Описание |
valuesPicture |
string |
Ссылка на картинку значения (StdPicture.*, CommonPicture.*) |
loadTransparent |
bool |
Скрыть кадр «нет значения». Выводится только при true |
calendar — CalendarField
cmdBar — CommandBar
buttonGroup — ButtonGroup
Группа кнопок внутри командной панели (autoCmdBar/cmdBar/popup). Значение ключа — имя элемента.
| Свойство |
Тип |
Описание |
buttonGroup |
string |
Имя элемента |
title |
string/object |
Заголовок группы |
representation |
string |
Auto, Picture, Text, PictureAndText |
children |
array |
Кнопки (button) внутри группы |
autoCmdBar — командная панель формы
Командная панель самой формы (<AutoCommandBar id="-1">). Задаётся как элемент в elements; компилятор автоматически вынимает его из дерева. Нужен только если в панель помещаются явные кнопки/группы или меняется выравнивание/автозаполнение — иначе панель формируется автоматически.
| Свойство |
Тип |
Описание |
autoCmdBar |
string |
Имя панели (обычно ФормаКоманднаяПанель) |
horizontalAlign |
string |
Right, Left, Center |
autofill |
bool |
false — отключить автозаполнение стандартными командами |
children |
array |
Кнопки/группы кнопок панели |
5. Attributes — реквизиты формы
| Свойство |
Тип |
Описание |
name |
string |
Имя реквизита (обязательно) |
type |
string |
Тип (shorthand) |
main |
bool |
Основной реквизит формы |
title |
string |
Заголовок |
savedData |
bool |
Сохраняемые данные |
fillChecking |
string |
Show, DontShow |
columns |
array |
Колонки для ValueTable/ValueTree |
6. Parameters — параметры формы
| Свойство |
Тип |
Описание |
name |
string |
Имя параметра (обязательно) |
type |
string |
Тип (shorthand) |
key |
bool |
Ключевой параметр |
7. Commands — команды формы
| Свойство |
Тип |
Описание |
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 |
Составные типы
Разделитель " | ":
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С).