cc-1c-skills/docs/form-guide.md

Управляемые формы (Form)

Навыки группы /form-* позволяют анализировать, генерировать и валидировать управляемые формы 1С:Предприятия 8.3 из XML-исходников, не читая тысячи строк XML.

Навыки

Навык	Параметры	Описание
/form-info	<FormPath>	Компактная сводка: дерево элементов, реквизиты, команды, события
/form-compile	<JsonPath> <OutputPath>	Генерация Form.xml из компактного JSON-определения
/form-validate	<FormPath>	Валидация: уникальность ID, companions, DataPath, команды
/form-add	<FormPath> <JsonPath>	Добавление элементов, реквизитов, команд в существующую форму
/form-patterns	(без параметров)	Справочник паттернов: архетипы, конвенции именования, продвинутые приёмы

Сценарии использования

Анализ формы перед модификацией

Файлы Form.xml содержат от сотен до десятков тысяч строк XML. 80% объёма — визуальный шум (цвета, шрифты, размеры, автогенерированные подсказки). /form-info извлекает суть.

> Покажи структуру формы документа РеализацияТоваровУслуг

Claude найдёт Form.xml и вызовет /form-info. Результат — компактная сводка (40–100 строк вместо тысяч):

=== Form: ФормаДокумента — "Реализация товаров и услуг" (Documents.РеализацияТоваровУслуг) ===

Properties: AutoTitle=false, CommandBarLocation=None

Events:
  OnCreateAtServer -> ПриСозданииНаСервере
  OnOpen -> ПриОткрытии

Elements:
  ├─ [Group:AH] ГруппаШапка
  │ ├─ [Input] Организация -> Объект.Организация {OnChange}
  │ └─ [Input] Контрагент -> Объект.Контрагент {OnChange, StartChoice}
  ├─ [Table] Товары -> Объект.Товары
  │ ├─ [Input] Номенклатура -> Объект.Товары.Номенклатура {OnChange}
  │ └─ [Input] Сумма -> Объект.Товары.Сумма [ro]
  └─ [Pages] Страницы
     ├─ [Page] Основное (5 items)
     └─ [Page] Печать (2 items)

Attributes:
  *Объект: DocumentObject.РеализацияТоваровУслуг (main)
  Валюта: CatalogRef.Валюты
  ...

Commands:
  Печать -> ПечатьДокумента [Ctrl+P]

Добавление элементов в существующую форму

/form-add добавляет элементы, реквизиты и команды в существующий Form.xml. Автоматически назначает ID, генерирует companion-элементы и обработчики событий.

> Добавь поле "Склад" в шапку формы после "Контрагент"

Claude вызовет /form-info для анализа структуры, создаст JSON и вызовет /form-add:

{
  "into": "ГруппаШапка",
  "after": "Контрагент",
  "elements": [
    { "input": "Склад", "path": "Объект.Склад", "on": ["OnChange"] }
  ],
  "attributes": [
    { "name": "Склад", "type": "CatalogRef.Склады" }
  ]
}

Позиционирование: into указывает группу-контейнер, after — элемент, после которого вставлять. Оба опциональны (по умолчанию — в конец корневого ChildItems).

Один вызов может содержать элементы, реквизиты и команды одновременно. Группы поддерживают children для вложенных элементов.

Поиск обработчиков и привязок

Из сводки видно, какие события подключены к каким элементам:

> Какие обработчики срабатывают при изменении контрагента?

Claude вызовет /form-info и найдёт: [Input] Контрагент -> Объект.Контрагент {OnChange, StartChoice} — далее откроет модуль формы и найдёт процедуры по именам событий.

Точечное погружение в детали

Сводка — это карта. Для деталей по конкретному элементу достаточно grep по имени из сводки:

> Покажи все свойства элемента ДоговорКонтрагента

Claude сделает grep по Form.xml и найдёт полный XML-блок с ChoiceParameters, ChoiceFoldersAndItems, стилями и прочими свойствами.

Чтение вывода

Дерево элементов

Обозначение	Элемент
[Group:V] [Group:H] [Group:AH] [Group:AV]	Группа (Vertical / Horizontal / AlwaysHorizontal / AlwaysVertical)
[Input]	Поле ввода
[Check]	Флажок
[Label]	Декоративная надпись
[LabelField]	Поле надписи (привязанное к данным)
[Table]	Таблица
[Pages] / [Page]	Вкладки (страницы показывают количество элементов)
[Button]	Кнопка
[CmdBar]	Командная панель
[Popup]	Выпадающее меню
[Picture]	Декоративная картинка
[PicField]	Поле картинки
[Calendar]	Календарь

Флаги

Показываются только при отклонении от умолчания:

• [visible:false] — элемент скрыт (Visible=false)
• [enabled:false] — элемент недоступен (Enabled=false)
• [ro] — только чтение (ReadOnly=true)
• ,collapse — сворачиваемая группа (Behavior=Collapsible)

Привязки и события

• -> Объект.Поле — DataPath (привязка к данным)
• -> Имя [cmd] — привязка к команде формы
• -> Close [std] — привязка к стандартной команде
• {OnChange, StartChoice} — имена подключённых событий
• [title:Текст] — заголовок, если отличается от имени элемента

Реквизиты

• *Объект: DocumentObject.Реализация (main) — основной реквизит формы
• Таблица: ValueTable [Кол1: тип, Кол2: тип] — таблица значений с колонками
• Список: DynamicList -> Catalog.Пользователи — динамический список с основной таблицей

Генерация формы с нуля

/form-compile принимает компактное JSON-определение (20–50 строк) и генерирует полный Form.xml (100–500+ строк) с namespace-декларациями, companion-элементами и последовательными ID.

> Создай форму загрузки данных с полями Организация, Контрагент, таблицей Товары и кнопкой Загрузить

Claude создаст JSON-определение и вызовет /form-compile. Пример JSON:

{
  "properties": { "autoTitle": false },
  "events": { "OnCreateAtServer": "ПриСозданииНаСервере" },
  "elements": [
    { "group": "horizontal", "name": "Шапка", "children": [
      { "input": "Организация", "path": "Объект.Организация", "on": ["OnChange"] },
      { "input": "Контрагент", "path": "Объект.Контрагент" }
    ]},
    { "table": "Товары", "path": "Объект.Товары", "columns": [
      { "input": "Номенклатура", "path": "Объект.Товары.Номенклатура" },
      { "input": "Сумма", "path": "Объект.Товары.Сумма", "readOnly": true }
    ]},
    { "button": "Загрузить", "command": "Загрузить" }
  ],
  "attributes": [
    { "name": "Объект", "type": "DataProcessorObject.ЗагрузкаДанных", "main": true }
  ],
  "commands": [
    { "name": "Загрузить", "action": "ЗагрузитьОбработка" }
  ]
}

Верификация результата

После компиляции используйте /form-validate и /form-info для проверки:

> /form-validate src/МояОбработка/Forms/Форма/Ext/Form.xml
> /form-info src/МояОбработка/Forms/Форма/Ext/Form.xml

/form-validate проверит структурную корректность (ID, companions, ссылки), /form-info покажет результат в виде компактной сводки.

Примеры слеш-команд

> /form-info upload/acc_8.3.24/Documents/РеализацияТоваровУслуг/Forms/ФормаДокумента/Ext/Form.xml
> /form-info src/МояОбработка/Forms/Форма/Ext/Form.xml
> /form-compile src/form.json src/МояОбработка/Forms/Форма/Ext/Form.xml
> /form-add src/МояОбработка/Forms/Форма/Ext/Form.xml src/additions.json
> /form-validate src/МояОбработка/Forms/Форма/Ext/Form.xml

Связь с EPF-навыками

Навыки /form-* работают с формами из любых источников — конфигурации и внешних обработок. При работе с обработками:

1. /epf-add-form — создать форму (каркас)
2. /form-compile — сгенерировать Form.xml из JSON-определения
3. /form-add — добавить элементы/реквизиты/команды в существующую форму
4. /form-validate — проверить корректность
5. /form-info — проанализировать результат
6. /epf-build — собрать EPF

Спецификации

• Управляемая форма — Form.xml, элементы, команды, реквизиты, система типов
• Form DSL — JSON-формат описания формы для /form-compile и /form-add
• Паттерны компоновки — типовые архетипы форм, конвенции именования, примеры DSL