1С: как передать параметры в обработку заполнения

Обработка заполнения в 1С — это механизм, который автоматически заполняет табличные части документов и справочников по команде пользователя или программно. Часто одной процедуры заполнения недостаточно: нужно передать в неё дополнительные данные — выбранный склад, период, договор, настройки отбора. От того, как правильно организована передача параметров, зависит, будет ли команда работать предсказуемо и не сломается ли она при доработках.

В типовых конфигурациях на БСП (Библиотека стандартных подсистем) передача параметров реализована через структуру ПараметрыВыполненияКоманды и механизм подключаемых команд. В самописных решениях чаще используют прямой вызов процедуры с параметрами или открытие формы с параметрами и обработчиком оповещения. Ниже разобраны оба подхода с примерами кода.

Как устроен механизм заполнения в типовых конфигурациях

В конфигурациях на основе БСП (УТ, ERP, Бухгалтерия, ЗУП) команды заполнения табличных частей регистрируются в модуле менеджера объекта, в процедуре ДобавитьКомандыЗаполнения. Каждая команда получает имя, представление и обработчик. Когда пользователь нажимает кнопку «Заполнить», платформа вызывает подключаемую процедуру, в которую уже встроена передача контекста.

Стандартная цепочка выглядит так: клиентская процедура-обработчик получает массив объектов и структуру ПараметрыВыполненияКоманды, затем вызывает серверную процедуру заполнения, передавая ей нужные значения. Именно в этой точке разработчик добавляет свои параметры — например, склад или дату, по которой нужно подобрать остатки.

Передача параметров через структуру в процедуру заполнения

Самый прямой способ — объявить серверную процедуру заполнения с параметром-структурой. Клиентский обработчик собирает значения из реквизитов формы и передаёт их одним пакетом. Это снижает количество серверных вызовов и делает код читаемым.

&НаКлиенте
Процедура ЗаполнитьПоОстаткам(Команда)
ПараметрыЗаполнения = Новый Структура;
ПараметрыЗаполнения.Вставить("Склад", Объект.Склад);
ПараметрыЗаполнения.Вставить("ДатаОстатков", Объект.Дата);
ПараметрыЗаполнения.Вставить("ОчищатьПередЗаполнением", Истина);
ЗаполнитьПоОстаткамНаСервере(ПараметрыЗаполнения);
КонецПроцедуры

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

Обратите внимание: в клиентской структуре нельзя размещать несериализуемые типы — запросы, таблицы значений с данными формы, COM-объекты. Передавайте примитивы: ссылки, даты, строки, числа, булево, массивы и структуры из них. Если нужно передать таблицу, сначала выгрузите её в массив структур на клиенте или выполните всю работу на сервере.

Параметры через форму выбора настроек заполнения

Если перед заполнением пользователь должен указать несколько значений (период, склад, вариант цен), удобнее открыть отдельную форму настроек и получить результат через ОписаниеОповещения. Так работает, например, заполнение по остаткам в типовых документах инвентаризации.

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

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

Форма настроек при закрытии возвращает структуру через Закрыть(СтруктураРезультата). Обязательно обрабатывайте случай, когда пользователь закрыл форму крестиком — тогда результат равен Неопределено, и заполнение выполнять нельзя.

1. 1
   Создайте форму настроек с реквизитами для параметров заполнения
2. 2
   В команде заполнения откройте форму с ОписаниеОповещения в режиме БлокироватьОкноВладельца
3. 3
   В форме настроек по кнопке ОК соберите структуру и вызовите Закрыть(Структура)
4. 4
   В обработчике оповещения проверьте результат на Неопределено
5. 5
   Передайте структуру в серверную процедуру заполнения
6. 6
   После заполнения обновите форму и при необходимости установите Модифицированность

Параметры в механизме подключаемых команд БСП

Если конфигурация использует подсистему «Подключаемые команды», команда заполнения описывается в модуле менеджера объекта. Обработчик получает стандартную сигнатуру, и свои параметры нужно пробрасывать через реквизиты формы или дополнительную структуру внутри обработчика.

// Модуль менеджера объекта
Процедура ДобавитьКомандыЗаполнения(КомандыЗаполнения, Параметры) Экспорт
Команда = КомандыЗаполнения.Добавить();
Команда.Представление = НСтр("ru = 'По остаткам на складе'");
Команда.Идентификатор = "ЗаполнитьПоОстаткам";
Команда.Обработчик = "ЗаполнениеОбъектовКлиент.ЗаполнитьПоОстаткам";
Команда.РежимЗаписи = "НеЗаписывать";
КонецПроцедуры

В клиентском обработчике первым параметром приходит массив ссылок на заполняемые объекты, вторым — ПараметрыВыполненияКоманды с источником (формой). Пользовательские значения берите из реквизитов формы-источника или спрашивайте у пользователя через форму настроек, как в предыдущем разделе.

Способы передачи параметров

Структура напрямую в серверную процедуру

Подходит, когда все параметры уже есть в реквизитах объекта или формы. Минимум кода, но нет диалога с пользователем.

Форма настроек + ОписаниеОповещения

Подходит, когда пользователь должен выбрать параметры перед заполнением. Требует отдельной формы и обработки отмены.

Подключаемые команды БСП

Стандарт для типовых конфигураций и расширений. Параметры пробрасываются внутри обработчика, сигнатуру менять нельзя.

Передача параметров при программном создании объекта

Отдельный случай — событие ОбработкаЗаполнения в модуле объекта, которое срабатывает при создании документа. Сюда параметры попадают через Параметры при открытии формы нового объекта или через ДанныеЗаполнения при вводе на основании.

// Модуль объекта
Процедура ОбработкаЗаполнения(ДанныеЗаполнения, СтандартнаяОбработка)
Если ТипЗнч(ДанныеЗаполнения) = Тип("Структура") Тогда
Если ДанныеЗаполнения.Свойство("Склад") Тогда
Склад = ДанныеЗаполнения.Склад;
КонецЕсли;
Если ДанныеЗаполнения.Свойство("ЗаполнитьПоОстаткам")
И ДанныеЗаполнения.ЗаполнитьПоОстаткам Тогда
ЗаполнитьТоварыПоОстаткам(ДанныеЗаполнения);
КонецЕсли;
КонецЕсли;
КонецПроцедуры

При открытии формы нового документа структуру передают в параметрах формы: платформа автоматически проставит её как основание заполнения, если ключ параметра — «ЗначенияЗаполнения». При программном создании через Документы.РеализацияТоваровУслуг.СоздатьДокумент() вызовите Заполнить(СтруктураДанных) — она попадёт в ДанныеЗаполнения без изменений.

Проверка результата и отладка передачи параметров

После внедрения проверьте три вещи: параметры доходят до серверной процедуры в полном составе, заполнение использует именно переданные значения, а форма корректно обновляется после изменения объекта. Проще всего поставить точку останова в серверной процедуре и посмотреть содержимое структуры в табло.

Если параметр «теряется», типичные причины — опечатка в имени ключа структуры (проверяйте через Свойство("Имя", Значение) с явной обработкой отсутствия), передача по значению вместо ссылки или попытка прочитать реквизит формы после того, как форма-источник уже закрыта. Для диагностики добавьте временный вывод содержимого структуры в журнал регистрации или сообщение пользователю.

Контрольные точки

Как проверить результат

Состав структуры на сервере

Норма

Все ключи присутствуют, значения соответствуют выбранным на форме

Тревожный признак

Ключ отсутствует или значение Неопределено

Содержимое табличной части после заполнения

Норма

Строки соответствуют отбору по переданным параметрам (склад, период)

Тревожный признак

Заполнено по другому складу или без учёта отбора

Состояние формы после заполнения

Норма

Форма модифицирована, табличная часть обновлена на экране

Тревожный признак

Данные в объекте есть, но на форме не отображаются

Ограничения и безопасные границы доработки

Дорабатывать обработчики заполнения типовых конфигураций лучше через расширение: аннотации &После и &Вместо позволяют добавить свои параметры, не изменяя типовой код. Прямая правка модуля затруднит обновление конфигурации и может быть потеряна при очередном релизе.

Перед изменением логики заполнения в рабочей базе сделайте копию и проверьте сценарий на тестовых документах. Ошибка в обработке заполнения не повредит уже записанные документы, но может создать некорректные данные в новых, если заполнение срабатывает автоматически при создании.

Частые вопросы

Можно ли передать таблицу значений в обработку заполнения с клиента?

Напрямую — нет: таблица значений не сериализуется между клиентом и сервером. На клиенте преобразуйте данные в массив структур и передайте его, либо перенесите всю логику получения данных на сервер, передав только отборы.

Как передать параметры, если команда заполнения добавлена через расширение?

В расширении создайте свою команду формы и обработчик, внутри которого соберите структуру параметров и вызовите серверную процедуру расширения. Менять типовые подключаемые команды не требуется — добавьте рядом собственную кнопку.

Почему после заполнения данные не видны на форме?

Чаще всего объект изменён на сервере, но форма не обновлена. Если работаете через РеквизитФормыВЗначение, верните результат через ЗначениеВРеквизитФормы. Также проверьте, что заполняется именно тот объект, который открыт в форме, а не отдельная ссылочная копия.

Как передать параметры в ОбработкаЗаполнения при вводе на основании?

При вводе на основании в ДанныеЗаполнения приходит ссылка на объект-основание. Дополнительные значения передавайте через параметры открытия формы (ключ «ЗначенияЗаполнения») или дочитывайте их из объекта-основания запросом внутри ОбработкаЗаполнения.

Что делать, если пользователь может отменить выбор параметров?

В обработчике оповещения всегда проверяйте результат на Неопределено и просто завершайте процедуру без заполнения. Дополнительно можно вывести информационное сообщение, что заполнение отменено, чтобы поведение было понятным.

Нужно ли записывать документ перед программным заполнением табличной части?

Нет, заполнение работает с объектом в памяти. Но если логика заполнения опирается на данные самого документа в базе (например, движения), сначала запишите объект, иначе запрос увидит неактуальное состояние.