При программной работе с отчетами на базе Системы компоновки данных (СКД) разработчики часто сталкиваются с необходимостью передать определенные параметры (например, ДокументОснование, Организация или Период) непосредственно в момент открытия формы отчета. При этом хочется избежать лишних серверных вызовов, не писать сложный код в обработчиках модуля отчета типа ПриКомпоновкеРезультата() и выполнить всю операцию изящно — буквально одной строкой на клиенте.
В этой статье мы подробно разберем, как решить эту задачу стандартными средствами платформы «1С:Предприятие 8», изучим недокументированные особенности платформенного механизма, рассмотрим возможные подводные камни, а также разберем альтернативные и максимально надежные способы передачи параметров.
Казалось бы, логично передавать параметры данных СКД через структуру параметров формы, передавая туда структуру ПараметрыДанных. На практике разработчики часто пытаются написать следующий код:
// Попытка передать параметры напрямую - этот способ не сработает автоматически
ПараметрыДанных = Новый Структура("ДокументОснование", Объект.Ссылка);
ПараметрыФормы = Новый Структура("ПараметрыДанных, СформироватьПриОткрытии", ПараметрыДанных, Истина);
ОткрытьФорму("Отчет.ИмяОтчета.Форма", ПараметрыФормы);
Однако при таком подходе платформа «1С» проигнорирует структуру ПараметрыДанных. Параметр отчета останется незаполненным, и отчет либо откроется пустым, либо потребует от пользователя ручного ввода данных. Нам приходится искать обходные пути. Давайте разберем самый простой и быстрый способ, предоставляемый самой платформой.
Обратимся к синтакс-помощнику «1С:Предприятия». В описании расширения формы клиентского приложения для отчета для параметра Отбор (тип Структура) указано следующее:
Используется для установки отбора и параметров данных в форме отчета. Ключ элемента структуры содержит имя поля или параметра, на которое нужно наложить отбор. Значение элемента структуры содержит значение отбора. Если имеется параметр системы компоновки данных с именем, соответствующим имени ключа структуры, то значение будет установлено ему. Если параметра нет, но есть поле, то будет добавлен отбор на это поле.
Это означает, что платформа берет на себя интеллектуальное распределение данных! Мы можем просто передать наши параметры данных СКД в обычную структуру Отбор. Платформа сама определит, есть ли в схеме компоновки параметр с таким именем, и если он существует, то заполнит его значением из структуры.
Рассмотрим, как это выглядит на практике. Ниже представлен готовый пример кода для вызова формы отчета с клиента:
&НаКлиенте
Процедура ОткрытьОтчетСПараметрамиКлиент()
// Создаем структуру отбора, в которую помещаем имя параметра СКД и его значение
ПараметрыОтбора = Новый Структура;
ПараметрыОтбора.Вставить("ДокументОснование", Объект.Ссылка);
// Формируем параметры для открытия формы отчета
ПараметрыФормы = Новый Структура;
ПараметрыФормы.Вставить("Отбор", ПараметрыОтбора);
ПараметрыФормы.Вставить("СформироватьПриОткрытии", Истина);
// Открываем форму отчета
ОткрытьФорму("Отчет.ИмяОтчета.Форма", ПараметрыФормы);
КонецПроцедуры
Этот код отлично работает, не требует ни единой строчки на сервере и выполняется мгновенно с клиента. Но, как и у любого быстрого решения, у него есть скрытые особенности, которые важно учитывать при разработке крупных корпоративных систем.
Проанализируем детально особенности поведения платформы при использовании структуры Отбор для передачи параметров:
ДокументОснование, и одноименное поле в наборе данных (например, реквизит выборки запроса ДокументОснование), платформа всегда отдаст приоритет параметру. Она заполнит значение параметра СКД, при этом обычный отбор по полю в настройках компоновщика создан не будет.ДокументОснование на СсылкаНаДокумент. При открытии формы платформа не выдаст никаких ошибок или предупреждений! Она просто проанализирует структуру Отбор, не найдет в СКД параметра с именем ДокументОснование и молча создаст обычный отбор по одноименному полю (если оно доступно для отбора). В результате логика работы отчета может незаметно нарушиться, что приведет к трудновыявляемым ошибкам.Очень часто параметром СКД выступает период отчета. Обратите внимание, что если параметр в схеме имеет тип СтандартныйПериод, передача простой даты или строки в структуру отбора вызовет ошибку несоответствия типов на уровне платформы.
Выясним, как правильно передавать такие данные. Нам необходимо предварительно инициализировать и заполнить специальный объект платформы:
&НаКлиенте
Процедура ОткрытьОтчетЗаПериод()
// Инициализируем стандартный период
НастройкаПериода = Новый СтандартныйПериод;
НастройкаПериода.Вариант = ВариантСтандартногоПериода.ЭтотМесяц;
// Если нужны точные даты, можно использовать свойства:
// НастройкаПериода.ДатаНачала = НачалоМесяца(ТекущаяДата());
// НастройкаПериода.ДатаОкончания = КонецМесяца(ТекущаяДата());
ПараметрыОтбора = Новый Структура;
ПараметрыОтбора.Вставить("ПериодОтчета", НастройкаПериода);
ПараметрыФормы = Новый Структура;
ПараметрыФормы.Вставить("Отбор", ПараметрыОтбора);
ПараметрыФормы.Вставить("СформироватьПриОткрытии", Истина);
ОткрытьФорму("Отчет.ИмяОтчета.Форма", ПараметрыФормы);
КонецПроцедуры
Если вы хотите полностью контролировать процесс инициализации параметров, гарантировать работоспособность кода при любых переименованиях в СКД и не зависеть от скрытой логики платформы, рекомендуется использовать явную установку параметров в компоновщике настроек. Для этого нам понадобится один легкий внеконтекстный серверный вызов для подготовки настроек отчета.
Разберем этот надежный способ по шагам:
// На стороне клиента: готовим параметры и открываем форму
&НаКлиенте
Процедура ОткрытьОтчетНадежноКлиент()
// Получаем структуру настроек с сервера (один быстрый вызов без контекста формы)
ДанныеНастроек = ПолучитьНастройкиКомпоновщикаНаСервере(Объект.Ссылка);
ПараметрыФормы = Новый Структура;
// Передаем измененные настройки напрямую в форму отчета
ПараметрыФормы.Вставить("Вариант", ДанныеНастроек.Настройки);
ПараметрыФормы.Вставить("ПользовательскиеНастройки", ДанныеНастроек.ПользовательскиеНастройки);
ПараметрыФормы.Вставить("СформироватьПриОткрытии", Истина);
ОткрытьФорму("Отчет.ИмяОтчета.Форма", ПараметрыФормы);
КонецПроцедуры
// На стороне сервера: обращаемся к схеме СКД и явно заполняем нужный параметр
&НаСервереБезКонтекста
Функция ПолучитьНастройкиКомпоновщикаНаСервере(ЗначениеДокумента)
// Создаем экземпляр отчета для доступа к компоновщику настроек
ОтчетОбъект = Отчеты.ИмяОтчета.Создать();
Компоновщик = ОтчетОбъект.КомпоновщикНастроек;
// Явно находим нужный параметр по его имени в СКД
ИмяПараметра = "ДокументОснование";
ПараметрДанных = Компоновщик.Настройки.ПараметрыДанных.НайтиЗначениеПараметра(Новый ПараметрКомпоновкиДанных(ИмяПараметра));
Если ПараметрДанных <> Неопределено Тогда
ПараметрДанных.Значение = ЗначениеДокумента;
ПараметрДанных.Использование = Истина;
Иначе
ВызватьИсключение "В схеме компоновки данных отчета не найден обязательный параметр: " + ИмяПараметра;
КонецЕсли;
// Возвращаем измененные настройки и пользовательские настройки на клиент
Результат = Новый Структура;
Результат.Вставить("Настройки", Компоновщик.Настройки);
Результат.Вставить("ПользовательскиеНастройки", Компоновщик.ПользовательскиеНастройки);
Возврат Результат;
КонецФункции
Преимущества явного метода:
Использование нашего параметра.Мы подробно проанализировали два полярных решения одной задачи. Использование структуры Отбор — это прекрасный инструмент для быстрой разработки и простых отчетов, когда нужно передать параметры «здесь и сейчас» минимальным количеством кода. Однако для критически важных бизнес-процессов и сложных тиражируемых конфигураций лучше использовать явное заполнение настроек компоновщика на сервере, обеспечивающее стабильность и предсказуемость работы системы в будущем.