form_write — Документация Кванты

Когда использовать

Вывести реквизит объекта на форму — элемент kind: field с путём к данным Объект.<Реквизит>.
Добавить группу, кнопку с командой, таблицу, надпись; переместить элемент — update с parent и position.
Реквизит формы, колонка реквизита-таблицы, команда, параметр формы.
Обработчики событий формы и элементов — events в update.
Саму форму создаёт metadata_write с адресом <Тип>.X.Form.Y.

Соседние инструменты домена «Формы»

form_readRдерево формы, свойства, #help — контракт записи, #screenshot

Операции

Операции form_write
operation	Что делает	Нужно передать
`create`	Создаёт компонент по адресу. Элемент создаётся так же, как «Добавить элемент» в редакторе формы EDT: с привязкой к данным и обязательными свойствами. С коллекционным адресом и массивом — пачка; поздние элементы видят ранние (группа и поля в ней — одним вызовом).	`project`, `fqn`, `definition`
`update`	Меняет переданные свойства. `name` — переименование (ссылки на старое имя внутри формы не обновляются — ответ предупреждает). У элемента — `parent` и `position` для перемещения и `events`. Голый адрес формы — только события уровня формы.	`project`, `fqn`, `definition`
`delete`	Удаляет компонент.	`project`, `fqn`

Параметры

Параметры form_write
Параметр и тип	Обязательный	Описание	По умолчанию
`project`строка	да	Идентификатор проекта рабочей области EDT — имя из ответа project_read (например, УТ2020). Для расширения — проект расширения.	—
`operation`строка	да	Операция инструмента — значения и их смысл в таблице «Операции».значения: create · update · delete	—
`fqn`строка	да	Адрес компонента: `<форма>.Item.X`, `.Attribute.X`, `.Attribute.X.Column.Y`, `.Command.X`, `.Parameter.X`; голый адрес формы — для событий формы. Маркер без имени — коллекционный адрес для пачки. Русские маркеры тоже принимаются.	—
`definition`объект \| массив	нет	Свойства одного компонента, набор зависит от маркера. Элемент: `kind` (`field`, `group`, `button`, `table`, `decoration`), `data_path`, `command`, `title`, `parent`, `position`, `events`. Реквизит: `type`, `title`, `main`; для динамического списка — `main_table`, `custom_query`, `query_text`. Команда: `action`, `title`, `tooltip`, `shortcut`. Параметр: `type`, `use_always`. Массив — пачка, у каждого элемента `name`, до 100. Полный контракт — `form_read` с гранью `#help`.	—
`dry_run`булево	нет	true — выполнить в транзакции и гарантированно откатить: ответ показывает изменения, форма не меняется.	`false`
`title`строка	нет	Необязательная подпись вызова до 40 символов: клиент показывает её в шапке карточки вызова. На результат не влияет.	—

Таблица собрана из схемы инструмента, которую получает агент при подключении.

Адреса

Адреса form_write
Адрес	Что адресует
`Catalog.Контрагенты.Form.ФормаЭлемента.Item.<Поле>`	элемент формы
`Catalog.Контрагенты.Form.ФормаЭлемента.Attribute.<Реквизит>`	реквизит формы
`Catalog.Контрагенты.Form.ФормаЭлемента.Attribute.<Таблица>.Column.<Колонка>`	колонка реквизита-таблицы
`Catalog.Контрагенты.Form.ФормаЭлемента.Command.<Команда>`	команда формы
`Catalog.Контрагенты.Form.ФормаЭлемента`	только `update`: события формы
`Catalog.Контрагенты.Form.ФормаЭлемента.Item`	коллекционный адрес: пачка элементов

Пример вызова и ответа

parent — путь группы от корня формы через точку (ГруппаВерх.ГруппаЛево), @root или @autoCommandBar; position — first, last, before:X, after:X. Команда кнопки: "ИмяКоманды" — команда формы или объекта-владельца, "CommonCommand.X" — общая, "@Close" — стандартная формы, "@<Таблица>.Add" — стандартная таблицы.

аргументы form_write

{
  "project": "УТ2020",
  "operation": "create",
  "fqn": "Catalog.Контрагенты.Form.ФормаЭлемента.Item.<Поле>",
  "definition": {
    "kind": "field",
    "data_path": "Объект.<Реквизит>",
    "parent": "<путь группы от корня>",
    "position": "after:<соседнее поле>"
  }
}

Пример ответа в подготовке Устройство ответа — на странице Формат ответов.

Отказы и ошибки

rolled_back · лишний ключ definition

Компонент не принимает ключ — ответ перечисляет принимаемые. Контракт — form_read с гранью #help на том же адресе.

rolled_back · тип не поддерживается

Тип реквизита формы проверяется по списку, который EDT допускает для этого узла; неподдерживаемый тип — отказ, а не «неизвестный тип» в форме.

rolled_back · команда не найдена

Для кнопки нет такой команды ни у формы, ни у объекта-владельца — ответ предлагает ближайшие, включая стандартные @….

failed · Unknown operation

Неизвестное значение operation. В ответе — fix_hint: supported: … со списком допустимых операций и секция Did you mean. Допустимо: create, update, delete.

failed · лицензия

Без действующего ключа инструмент отвечает карточкой failed с сообщением лицензия: … и подсказкой, где ввести ключ; в секции Context — список инструментов, доступных без ключа. Подробнее — Лицензия и бесплатный доступ.

Ограничения

Пачка — до 100 компонентов одной коллекции, атомарно.
Переименование реквизита или команды не обновляет ссылки на старое имя в элементах формы — ответ предупреждает.
Цвета и шрифты задаются ключами back_color, text_color, font и подобными; значения — стиль (Style.<Имя>), #RRGGBB или описание шрифта.