Как получить доступ к переданным параметрам в форме отчета 1С?

← На главную

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

Передача параметров в управляемых формах отчета

В управляемых формах 1С:Предприятия параметры передаются при вызове функции ОткрытьФорму(). Вторым аргументом этой функции выступает структура, где ключами являются имена параметров, а значениями – передаваемые данные.

Рассмотрим пример кода, в котором осуществляется передача параметров:


УсловияОтбора = Новый Структура("Стр", ЭлементыФормы.ДокументСписок.ТекущаяСтрока);
ПараметрыФормы = Новый Структура("Отбор, СформироватьПриОткрытии", УсловияОтбора, Истина);
ОткрытьФорму("Отчет.РасходГСМ.ФормаОбъекта", ПараметрыФормы);

В этом примере мы создаем структуру ПараметрыФормы, которая содержит два параметра:

Отбор: Ему присваивается структура УсловияОтбора, содержащая дополнительное условие отбора (в данном случае, по текущей строке списка документов).
СформироватьПриОткрытии: Ему присваивается булево значение Истина, что может быть использовано для автоматического формирования отчета сразу после его открытия.

Функция ОткрытьФорму() затем вызывается с указанием полного имени формы отчета ("Отчет.РасходГСМ.ФормаОбъекта") и нашей структурой параметров.

Получение параметров в управляемой форме отчета

Для получения переданных параметров в модуле управляемой формы отчета мы используем обработчик события ПриСозданииНаСервере(). Эта процедура выполняется однократно на сервере при создании экземпляра формы, до того как она будет отображена пользователю.

Внутри процедуры ПриСозданииНаСервере() переданные параметры доступны через коллекцию Параметры формы. Доступ к каждому параметру осуществляется по его имени, как к свойству этой коллекции.

Рассмотрим пример кода, демонстрирующий получение параметров:


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

Важный момент: Перед тем как обращаться к конкретному свойству коллекции Параметры (например, Параметры.Отбор), всегда рекомендуется проверять его наличие с помощью метода Параметры.Свойство("ИмяСвойства"). Это позволит избежать ошибок времени выполнения, если данный параметр не был передан при открытии формы.

Явное объявление параметров формы

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

Отсутствие проверки наличия: Если параметр объявлен в форме, нам не нужно проверять его наличие методом Параметры.Свойство() в коде ПриСозданииНаСервере(), поскольку система гарантирует его существование (даже если он не был передан, его значение будет Неопределено).
Наглядность: Список параметров формы становится очевиден для любого разработчика, работающего с формой, улучшая читаемость и поддерживаемость кода.
Ключевые параметры: Мы можем пометить параметры как "ключевые". Ключевые параметры будут доступны на протяжении всего времени жизни формы, а не только в ПриСозданииНаСервере(), что полезно для сохранения контекста или условий, которые должны влиять на форму в течение всего ее существования.

Взаимодействие с КомпоновщикомНастроек

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

Приведем пример программного применения переданного отбора к КомпоновщикНастроек:


// Предположим, что ПереданныйОтбор - это объект типа ЭлементОтбораКомпоновкиДанных,
// или структура, из которой можно создать такой элемент.
Если ПереданныйОтбор <> Неопределено Тогда
    // Если ПереданныйОтбор уже является готовым элементом отбора СКД, просто добавляем его:
    // КомпоновщикНастроек.Настройки.Отбор.Элементы.Добавить(ПереданныйОтбор);
    
    // Чаще ПереданныйОтбор является простым значением, которое нужно применить к существующему элементу отбора:
    // Например, если мы хотим применить отбор по полю "Контрагент"
    Для Каждого ЭлементНастройкиОтбора Из КомпоновщикНастроек.Настройки.Отбор.Элементы Цикла
        Если ТипЗнч(ЭлементНастройкиОтбора) = Тип("ЭлементОтбораКомпоновкиДанных") Тогда
            Если ЭлементНастройкиОтбора.ЛевоеЗначение = Новый ПолеКомпоновкиДанных("Контрагент") Тогда
                ЭлементНастройкиОтбора.ВидСравнения = ВидСравненияКомпоновкиДанных.Равно;
                ЭлементНастройкиОтбора.Использование = Истина;
                ЭлементНастройкиОтбора.Значение = ПереданныйОтбор; // Применяем переданное значение
                Прервать;
            КонецЕсли;
        КонецЕсли;
    КонецЦикла;
КонецЕсли;

// Также можно устанавливать значения параметров СКД
// Если у отчета есть параметр СКД "НачалоПериода"
// КомпоновщикНастроек.Настройки.ПараметрыДанных.УстановитьЗначениеПараметра("НачалоПериода", ТекущаяДата());

Этот подход позволяет создавать очень гибкие отчеты, поведение которых динамически изменяется в зависимости от контекста, из которого они были открыты.

Получение параметров в обычных формах отчета (исторический контекст)

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

Экспортная переменная: В модуле обычной формы отчета можно было объявить экспортную переменную. Перед вызовом функции ОткрытьФорму() в эту переменную записывалось значение, которое затем обрабатывалось в обработчике ПередОткрытием() или ПриОткрытии() самой формы.
Реквизит формы: Другой способ заключался в добавлении реквизита на вкладке "Реквизиты" формы объекта. Программно, перед открытием формы, этот реквизит заполнялся необходимыми данными. Затем в обработчиках событий формы (например, ПриОткрытии()) можно было получить доступ к значению этого реквизита.
Через параметры ПолучитьФорму(): При вызове функции ПолучитьФорму() (аналог ОткрытьФорму() для обычных форм) можно было передать массив или структуру с параметрами. Эти параметры затем обрабатывались в обработчике ПриОткрытии() формы, обычно через свойство формы, содержащее эти переданные параметры (хотя это было менее стандартизировано, чем текущая коллекция Параметры в управляемых формах).

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

Дополнительные рекомендации

Для более эффективной работы с параметрами в формах отчетов учтите следующие моменты:

Время жизни параметров: Не забывайте, что "обычные" пользовательские параметры формы (не помеченные как "ключевые") доступны главным образом в обработчике ПриСозданииНаСервере(). Если требуется, чтобы параметр был доступен на протяжении всего жизненного цикла формы (например, для использования в различных клиентских и серверных процедурах), его необходимо объявить как "ключевой" параметр формы на закладке "Параметры" в конструкторе.
Обработка в БСП: Если вы разрабатываете отчет на основе стандартных форм, предоставляемых Библиотекой стандартных подсистем (БСП), для программного заполнения параметров отчета или отборов, рекомендуется использовать обработчик события ПередЗагрузкойПользовательскихНастроекНаСервере. Этот обработчик вызывается до того, как будут загружены пользовательские варианты отчета, что позволяет нашим программным настройкам иметь приоритет или корректно дополнять пользовательские.

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