Как программно заполнить параметры СКД в 1С

Программное заполнение параметров схемы компоновки данных (СКД) — типовая задача при разработке отчётов, которые должны открываться с заранее заданными значениями: текущей датой, выбранной организацией, периодом из формы документа. Ручная установка параметров пользователем неудобна и чревата ошибками, поэтому разработчик подставляет значения кодом до формирования отчёта.

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

Ниже разобраны рабочие приёмы: получение компоновщика настроек в разных контекстах (форма отчёта, внешний отчёт, программное формирование), установка простых и составных значений, работа со стандартными периодами, а также типовые ошибки, из-за которых параметр «не применяется».

Где в коде доступен компоновщик настроек

Точка, из которой вы обращаетесь к СКД, зависит от способа формирования отчёта. В типовом отчёте на управляемых формах компоновщик доступен в модуле объекта отчёта как КомпоновщикНастроек, а переопределяемые события — это ПриКомпоновкеРезультата и ПередЗагрузкойВариантаНаСервере. В форме отчёта компоновщик обычно лежит в реквизите Отчет.КомпоновщикНастроек.

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

Частая ошибка новичков — пытаться менять параметры в обработчике ПриСозданииНаСервере формы отчёта, когда настройки ещё не загружены или будут перезаписаны вариантом отчёта. Безопаснее работать в ПриКомпоновкеРезультата или в команде, которая выполняется непосредственно перед формированием.

Установка простого параметра данных

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

Настройки = КомпоновщикНастроек.Настройки;
ПараметрОрганизация = Настройки.ПараметрыДанных.НайтиЗначениеПараметра(
Новый ПараметрКомпоновкиДанных("Организация"));
Если ПараметрОрганизация <> Неопределено Тогда
ПараметрОрганизация.Использование = Истина;
ПараметрОрганизация.Значение = ВыбраннаяОрганизация;
КонецЕсли;

Проверка на Неопределено обязательна: если параметр с таким именем не объявлен в схеме (например, его переименовали при доработке), метод вернёт Неопределено, и обращение к свойству вызовет ошибку. Устойчивый код не должен падать из-за расхождения имён.

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

Заполнение периодов: даты и стандартный период

Период — самый частый параметр отчётов. В СКД его оформляют двумя способами: двумя отдельными параметрами НачалоПериода и КонецПериода с типом «Дата» либо одним параметром типа СтандартныйПериод. Программная установка различается.

Для пары дат каждому параметру присваивается значение типа «Дата». Обратите внимание на границу конца периода: если в запросе сравнение идёт как <= &КонецПериода, а вы передали начало дня, последний день попадёт в отчёт только частично. Используйте КонецДня(Дата) или в параметрах виртуальных таблиц передавайте дату с явным указанием границы.

Для стандартного периода создайте объект СтандартныйПериод, задайте ДатаНачала и ДатаОкончания (или вариант ВариантСтандартногоПериода, например ЭтотМесяц) и присвойте его параметру. Вариант удобен тем, что при следующем формировании отчёт сам пересчитает границы относительно текущей даты.

Период = Новый СтандартныйПериод;
Период.Вариант = ВариантСтандартногоПериода.ЭтотМесяц;
ПараметрПериод = Настройки.ПараметрыДанных.НайтиЗначениеПараметра(
Новый ПараметрКомпоновкиДанных("Период"));
ПараметрПериод.Использование = Истина;
ПараметрПериод.Значение = Период;

Параметры виртуальных таблиц и параметры-списки

Если запрос использует виртуальную таблицу регистра (например, Продажи.Обороты(&НачалоПериода, &КонецПериода)), её параметры объявляются в тексте запроса, но в схеме они появляются на закладке «Параметры» автоматически после анализа запроса конструктором. Заполняются они тем же способом — через ПараметрыДанных.

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

Альтернатива параметру-списку — элемент отбора с видом сравнения «В списке». Это гибче, потому что пользователь сможет потом изменить условие в настройках отчёта, но требует аккуратной работы уже с коллекцией Отбор, а не с параметрами.

Отличие параметров от отборов и когда что использовать

Параметр — это жёсткое условие, вшитое в запрос: без значения запрос либо не выполнится, либо вернёт не те данные. Отбор — гибкое условие, которое СКД накладывает на уже построенный набор данных, и его можно включать, отключать и менять вид сравнения. Путать их — распространённая причина «тормозящих» отчётов.

Программно отбор заполняется через коллекцию Настройки.Отбор.Элементы: добавляется элемент типа ЭлементОтбораКомпоновкиДанных, задаётся ЛевоеЗначение (поле компоновки), ВидСравнения, ПравоеЗначение и Использование. Если отбор по этому полю уже может существовать в настройках, сначала найдите его перебором элементов, иначе получите дубли условий.

Сравнение вариантов

Параметр данных

Подходит для периодов и обязательных условий запроса; ограничение — пользователь не может изменить вид сравнения

Элемент отбора

Подходит для необязательных фильтров; ограничение — нельзя использовать как параметр виртуальной таблицы

Параметр-список с В (&Список)

Подходит для множественного выбора ссылок; ограничение — требует флага «Доступен список значений» в схеме

Полный цикл программного формирования отчёта

Когда отчёт формируется без формы — в регламентном задании, при записи документа, в фоновом задании, — весь цикл выполняется вручную. Последовательность строгая: схема → компоновщик → настройки → параметры → макет компоновки → процессор компоновки → результат. Нарушение порядка приводит к тому, что параметры не применяются.

Схема = Отчеты.ПродажиПоМенеджерам.ПолучитьМакет("ОсновнаяСхемаКомпоновкиДанных");
Компоновщик = Новый КомпоновщикНастроекКомпоновкиДанных;
Компоновщик.Инициализировать(Новый ИсточникДоступныхНастроекКомпоновкиДанных(Схема));
Компоновщик.ЗагрузитьНастройки(Схема.НастройкиПоУмолчанию);

Настройки = Компоновщик.Настройки;
Парам = Настройки.ПараметрыДанных.НайтиЗначениеПараметра(
Новый ПараметрКомпоновкиДанных("НачалоПериода"));
Парам.Использование = Истина;
Парам.Значение = НачалоМесяца(ТекущаяДатаСеанса());

КомпоновщикМакета = Новый КомпоновщикМакетаКомпоновкиДанных;
Макет = КомпоновщикМакета.Выполнить(Схема, Настройки);

Процессор = Новый ПроцессорКомпоновкиДанных;
Процессор.Инициализировать(Макет);

Результат = Новый ТабличныйДокумент;
ПроцессорВывода = Новый ПроцессорВыводаРезультатаКомпоновкиДанныхВТабличныйДокумент;
ПроцессорВывода.УстановитьДокумент(Результат);
ПроцессорВывода.Вывести(Процессор);

Обратите внимание на Инициализировать компоновщика с источником доступных настроек: без этого шага компоновщик не знает структуру схемы, и загрузка настроек может работать некорректно. В модуле объекта отчёта вместо создания объектов вручную обычно достаточно переопределить ПриКомпоновкеРезультата и работать с готовым КомпоновщикНастроек.

1. 1
   Получите схему компоновки данных через ПолучитьМакет()
2. 2
   Создайте компоновщик и инициализируйте его источником доступных настроек
3. 3
   Загрузите настройки по умолчанию или сохранённый вариант
4. 4
   Найдите параметр через ПараметрыДанных.НайтиЗначениеПараметра()
5. 5
   Установите Использование = Истина и Значение нужного типа
6. 6
   Скомпонуйте макет, инициализируйте процессор и выведите результат
7. 7
   Проверьте, что в отчёте отражены только данные за заданные условия

Проверка результата и ограничения

После формирования убедитесь, что параметр действительно применился. Прямой признак — данные в отчёте ограничены заданным периодом или организацией. Косвенный — в режиме предприятия можно открыть настройки отчёта и увидеть установленные значения. Для отладки полезно временно вывести значения параметров через Сообщить() до компоновки макета.

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

Риск для данных при заполнении параметров минимален — отчёт ничего не записывает. Реальная опасность в другом: отчёт, сформированный с неприменившимся параметром периода, может выполнить тяжёлый запрос по всей базе и надолго заблокировать работу пользователей. Поэтому для обязательных параметров в схеме устанавливайте флаг «Запрещать незаполненные значения» или проверяйте заполненность в коде до компоновки.

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

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

Значение параметра в настройках отчёта

Норма

В диалоге настроек видно установленное значение и включённый флажок

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

Параметр пуст или флажок снят — значение не применилось

Состав данных отчёта

Норма

В отчёт попали только записи за заданный период или по заданной организации

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

Данные за все периоды — параметр не попал в запрос

Время формирования

Норма

Отчёт формируется за ожидаемое время

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

Резкое замедление — вероятно, параметр периода не применился и запрос идёт по всей таблице

Часто задаваемые вопросы

Почему параметр установлен, но отчёт его игнорирует?

Чаще всего не установлен флаг Использование у найденного параметра. Вторая причина — значение задано в основных настройках, но перекрыто пользовательскими настройками или вариантом отчёта, загруженным позже. Проверьте также, что параметр реально используется в тексте запроса схемы.

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

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

Как задать параметр типа «Список значений»?

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

Чем отличается установка параметра в ПриКомпоновкеРезультата от установки в форме?

ПриКомпоновкеРезультата вызывается непосредственно перед построением макета компоновки, поэтому изменения гарантированно попадут в отчёт и не будут перезаписаны загрузкой варианта. Установка в форме (например, при создании) может быть перекрыта последующей загрузкой настроек варианта или пользовательских настроек.

Можно ли заполнить параметры СКД во внешнем отчёте?

Да, механизм идентичен: в модуле объекта внешнего отчёта доступен КомпоновщикНастроек и событие ПриКомпоновкеРезультата, а схема получается через ПолучитьМакет() с именем макета СКД, добавленного в структуру внешнего отчёта.

Как передать в параметр дату с точностью до конца дня?

Используйте функцию КонецДня(Дата) перед присваиванием значения параметру. Это важно, когда в запросе сравнение выполняется оператором «меньше или равно»: без приведения к концу дня записи последнего дня периода могут не попасть в отчёт.