Form Work

---
name: form-work
description: "Паттерны управляемой формы 1С — директивы компиляции, батчинг серверных вызовов, программное добавление реквизитов и элементов формы, назначение обработчиков событий формы и её элементов, динамические списки, условное оформление, управление видимостью, асинхронные диалоги, преобразование данных формы. Используй при создании и доработке форм и их обработчиков, в том числе когда нужно программно вывести на типовую форму поле, реквизит, колонку, группу или кнопку."
---

# Паттерны модуля формы

> Нормы кода — в `.claude/rules/1c-rules.md` (единственный источник правил).
> Здесь — развёрнутые паттерны и примеры «как именно».

## Приоритеты

🔴 КРИТИЧНО (нарушение = медленные формы): &НаСервереБезКонтекста; батчинг серверных вызовов; группировка изменений видимости.
🟡 ВАЖНО: ДанныеФормыВЗначение + ЗначениеВДанныеФормы; асинхронные диалоги (веб-клиент); сериализуемые типы.
🟢 РЕКОМЕНДУЕТСЯ: правильные обработчики событий; пересчёт на клиенте; оповещения между формами.

---

## ШАБЛОНЫ КОДА (копируй и адаптируй)

### Шаблон 1: Батчинг серверных вызовов
```bsl
// КЛИЕНТ: один вызов для всех данных
&НаКлиенте
Процедура КонтрагентПриИзменении(Элемент)
    ДанныеЗаполнения = ПолучитьВсеДанныеОдинВызов(Объект.Контрагент, Объект.Дата);
    
    Объект.Договор = ДанныеЗаполнения.Договор;
    Объект.Валюта = ДанныеЗаполнения.Валюта;
    КурсВалюты = ДанныеЗаполнения.Курс;
КонецПроцедуры

// СЕРВЕР БЕЗ КОНТЕКСТА: все данные за один раз
&НаСервереБезКонтекста
Функция ПолучитьВсеДанныеОдинВызов(КонтрагентСсылка, ДатаДокумента)
    Результат = Новый Структура("Договор, Валюта, Курс");
    
    РеквизитыКонтрагента = ОбщегоНазначения.ЗначенияРеквизитовОбъекта(
        КонтрагентСсылка, "ДоговорПоУмолчанию");
    
    Результат.Договор = РеквизитыКонтрагента.ДоговорПоУмолчанию;
    
    Если ЗначениеЗаполнено(Результат.Договор) Тогда
        ВалютаДоговора = ОбщегоНазначения.ЗначениеРеквизитаОбъекта(
            Результат.Договор, "ВалютаВзаиморасчетов");
        Результат.Валюта = ВалютаДоговора;
        Результат.Курс = РаботаСКурсамиВалют.ПолучитьКурсВалюты(ВалютаДоговора, ДатаДокумента);
    КонецЕсли;
    
    Возврат Результат;
КонецФункции
```

### Шаблон 2А: Диалог через Показать* с обработчиком оповещения
```bsl
// Команда с подтверждением
&НаКлиенте
Процедура УдалитьСтроку(Команда)
    ПоказатьВопрос(
        Новый ОписаниеОповещения("ПослеПодтверждения", ЭтотОбъект),
        НСтр("ru = 'Удалить выбранную строку?'"),
        РежимДиалогаВопрос.ДаНет);
КонецПроцедуры

// Обработчик после ответа
&НаКлиенте
Процедура ПослеПодтверждения(Результат, ДополнительныеПараметры) Экспорт
    Если Результат = КодВозвратаДиалога.Да Тогда
        // Выполняем действие
        Объект.Товары.Удалить(Элементы.Товары.ТекущаяСтрока);
    КонецЕсли;
КонецПроцедуры
```

### Шаблон 2Б: Диалог через Асинх/Ждать (платформа 8.3.18+)
```bsl
&НаКлиенте
Асинх Процедура УдалитьСтроку(Команда)

    Результат = Ждать ВопросАсинх(
        НСтр("ru = 'Удалить выбранную строку?'"),
        РежимДиалогаВопрос.ДаНет);

    Если Результат = КодВозвратаДиалога.Да Тогда
        Объект.Товары.Удалить(Элементы.Товары.ТекущаяСтрока);
    КонецЕсли;

КонецПроцедуры
```

### Шаблон 3: Преобразование данных формы
```bsl
&НаСервере
Процедура ВыполнитьДействиеНаСервере()
    // Преобразуем данные формы в объект
    ДокументОбъект = РеквизитФормыВЗначение("Объект");
    
    // Вызываем методы модуля объекта
    ДокументОбъект.ЗаполнитьПоУмолчанию();
    
    // ОБЯЗАТЕЛЬНО преобразуем обратно!
    ЗначениеВРеквизитФормы(ДокументОбъект, "Объект");
КонецПроцедуры
```

### Шаблон 4: Открытие формы с параметрами и обработчиком завершения
```bsl
&НаКлиенте
Процедура ОткрытьФормуПодбора(Команда)
    ПараметрыФормы = Новый Структура;
    ПараметрыФормы.Вставить("Организация", Объект.Организация);
    ПараметрыФормы.Вставить("МножественныйВыбор", Истина);
    
    ОткрытьФорму("Обработка.Подбор.Форма",
        ПараметрыФормы,
        ЭтотОбъект,
        ,,,
        Новый ОписаниеОповещения("ПослеПодбора", ЭтотОбъект));
КонецПроцедуры

&НаКлиенте
Процедура ПослеПодбора(Результат, ДополнительныеПараметры) Экспорт
    Если Результат = Неопределено Тогда
        Возврат;
    КонецЕсли;
    
    Для Каждого Элемент Из Результат Цикл
        НоваяСтрока = Объект.Товары.Добавить();
        ЗаполнитьЗначенияСвойств(НоваяСтрока, Элемент);
    КонецЦикла;
КонецПроцедуры
```

---

## Подробные паттерны (reference)

**Не загружаются автоматически — открой нужный файл инструментом Read по теме задачи.**

| Тема | Файл |
|---|---|
| Клиент-сервер: иерархия директив, батчинг серверных вызовов, ДанныеФормыВЗначение, передаваемые типы | `references/client-server.md` |
| Обработчики и асинхронность: выбор стиля, события и привязка обработчиков, команды, Асинх/Ждать, открытие форм, оповещения между формами | `references/handlers-async.md` |
| Элементы и списки: динамические списки, условное оформление, видимость, табличные части, сообщение с привязкой к полю, правила новых форм | `references/elements.md` |

---

## Чек-лист форм

Дополнение к общему «Чек-листу проверки кода» из `.claude/rules/1c-rules.md` — детализация для модулей форм:

### Серверные вызовы
- [ ] Используется `&НаСервереБезКонтекста` вместо `&НаСервере` где возможно
- [ ] Нет нескольких последовательных серверных вызовов (батчинг применён)
- [ ] Серверная функция возвращает ВСЕ нужные данные за один раз
- [ ] Нет серверных вызовов в циклах обработки данных

### Преобразование данных
- [ ] После `РеквизитФормыВЗначение()` есть `ЗначениеВРеквизитФормы()`
- [ ] Преобразование используется только когда нужны методы объекта
- [ ] Передаваемые типы данных сериализуемы (нет ТаблицаЗначений, Запрос и т.д.)

### Диалоги и навигация
- [ ] Диалоги реализованы в выбранном стиле; если его не поддерживает версия платформы или API предоставляет один вариант, применено исключение из `.claude/rules/1c-rules.md`
- [ ] Для `Асинх/Ждать` подтверждена платформа 8.3.18 или выше
- [ ] Нет модальных вызовов (`Вопрос()`, `Предупреждение()`, `ОткрытьФормуМодально()`)
- [ ] Формы открываются через `ОткрытьФорму()` с обработчиком завершения, когда нужен результат закрытия
- [ ] Процедуры, переданные в `ОписаниеОповещения`, имеют `Экспорт`

### Обработчики событий
- [ ] Каждый новый обработчик назначен соответствующему событию; если привязку нельзя изменить из исходников — дана инструкция для Конфигуратора/EDT
- [ ] Инициализация формы в `ПриСозданииНаСервере`
- [ ] Интерактивная проверка в `ПередЗаписьюНаКлиенте` используется только когда без неё нельзя обойтись и после подтверждения можно корректно повторить исходный сценарий записи
- [ ] Обработчик отменяемого события оставлен обычной процедурой: он синхронно устанавливает `Отказ = Истина` и запускает отдельное продолжение — обработчик оповещения или `Асинх`-процедуру
- [ ] Дополнительная логика записи в `ПриЗаписиНаСервере`
- [ ] Оповещения других форм в `ПослеЗаписи`

### Программное изменение формы
- [ ] Проверено, как программная модификация уже сделана в этом модуле формы; принятый там подход продолжен, два стиля в одном модуле не разведены
- [ ] Реквизит формы добавлен раньше элемента, который на него ссылается
- [ ] Программно добавленный реквизит читается через `ЭтотОбъект["Имя"]`, а не по имени
- [ ] Реквизит объекта не пытались создать кодом — это Конфигуратор или EDT
- [ ] Обработчик программно созданного элемента назначен через `УстановитьДействие()`, а сама процедура объявлена в модуле формы заранее

### Производительность
- [ ] Изменения видимости сгруппированы в одну процедуру
- [ ] Пересчёты делаются на клиенте где возможно
- [ ] Динамические списки используют параметры отбора (не фиксированные настройки)
- [ ] Условное оформление настроено программно в `ПриСозданииНаСервере`

---