Параметры схемы компоновки данных: от символа & в запросе до кода в модуле отчёта

Параметр в СКД 1С устанавливают не методом Запрос.УстановитьПараметр(), а через настройки компоновщика: интерактивно — на вкладке Параметры схемы и в настройках варианта, программно — через КомпоновщикНастроек.Настройки.ПараметрыДанных.УстановитьЗначениеПараметра("Имя", Значение). Сам параметр появляется в схеме автоматически, как только в тексте запроса набора данных написано &ИмяПараметра.

Частая ошибка новичка — писать в модуле отчёта код в духе обычного запроса и удивляться, что значение не доходит до выборки. У схемы компоновки свой механизм: запрос собирает компоновщик макета, и значения он берёт только из настроек. Механизм общий для платформы 8.3: конструктор схемы одинаков в БП, ЗУП, УТ и собственных разработках.

Как объявить параметр в тексте запроса набора данных

Откройте отчёт в конфигураторе, затем макет ОсновнаяСхемаКомпоновкиДанных (так платформа называет схему, созданную по умолчанию). На вкладке Наборы данных выберите набор-запрос и впишите параметр с префиксом &.

Пример запроса с тремя параметрами:

ВЫБРАТЬ
	Остатки.Номенклатура КАК Номенклатура,
	Остатки.Склад КАК Склад,
	Остатки.КоличествоОстаток КАК Количество
ИЗ
	РегистрНакопления.ТоварыНаСкладах.Остатки(&ДатаОстатков, Склад В (&Склады)) КАК Остатки
ГДЕ
	Остатки.Номенклатура.ЭтоГруппа = ЛОЖЬ
	И Остатки.Номенклатура.Родитель = &Группа

Имя регистра здесь условное — подставьте свой. После выхода из поля запроса перейдите на вкладку Параметры: там уже стоят строки ДатаОстатков, Склады и Группа. Платформа создала их сама и попыталась угадать тип по контексту.

Правила, которые стоит держать в голове:

• 🔤 Имя параметра — без пробелов, начинается с буквы. Регистр букв не важен: &склады и &Склады — один параметр.
• 🧩 Параметры можно ставить в условия ГДЕ, в параметры виртуальных таблиц, в выражения полей и в ВЫБОР КОГДА.
• 🗑 Если параметр удалили из текста запроса, строка на вкладке Параметры остаётся. Лишние строки удаляйте вручную, иначе пользователь увидит поле, которое ни на что не влияет.

Необязательное условие в фигурных скобках

У языка запросов СКД есть расширение — фигурные скобки. Условие, взятое в {ГДЕ ...}, компоновщик включает в итоговый запрос только тогда, когда параметр используется:

ГДЕ
	Остатки.КоличествоОстаток > 0
{ГДЕ
	Остатки.Номенклатура.Родитель В ИЕРАРХИИ (&Группа)}

Сняли флажок у параметра Группа — условие исчезло, отчёт строится по всей номенклатуре. Без скобок тот же отчёт при пустом параметре упадёт с ошибкой.

Параметр-флаг: включить или выключить часть выборки

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

ГДЕ
	(&ПоказыватьНулевые ИЛИ Остатки.КоличествоОстаток <> 0)

Задайте параметру тип Булево и значение по умолчанию Ложь. Если флажок у пользователя включён, первая часть условия истинна и в отчёт попадают все строки. Если выключен — только строки с ненулевым остатком.

Тот же приём работает в выражении поля. Например, ВЫБОР КОГДА &ВРазрезеСкладов ТОГДА Остатки.Склад ИНАЧЕ НЕОПРЕДЕЛЕНО КОНЕЦ даёт колонку склада только по желанию пользователя. Но учтите: группировку по такому полю всё равно придётся настроить в структуре отчёта, параметр её не создаёт.

Вкладка «Параметры» в конструкторе схемы: что значит каждая колонка

Здесь параметру задают тип, заголовок и поведение. Колонки таблицы:

Двойной щелчок по ячейке Тип открывает окно выбора типа. Для даты там же задают состав: «Дата», «Время» или «Дата и время». Для строки — длину. Мелочь, но из-за даты без времени отчёт за «сегодня» иногда теряет документы, проведённые после полуночи.

Связанные параметры через колонку «Выражение»

Классика — один стандартный период вместо двух дат. Заведите параметр Период с типом СтандартныйПериод. Для параметров НачалоПериода и КонецПериода в колонке Выражение впишите:

&Период.ДатаНачала
&Период.ДатаОкончания

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

Значения по умолчанию и разница между параметром и отбором

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

Для дат отдельного параметра есть тип СтандартнаяДатаНачала с вариантами вроде «Начало этого дня». Он решает ту же задачу: значение пересчитывается при каждом формировании.

Чтобы пользователь увидел параметр в форме отчёта

Строки на вкладке Параметры сами по себе в форме отчёта не появляются. Дальше нужно:

1. Перейти на вкладку Настройки схемы.
2. Внизу открыть закладку Параметры — там список параметров данных.
3. Поставить флажок у нужного параметра и при желании задать значение для этого варианта.
4. Правой кнопкой по строке выбрать Свойства элемента пользовательских настроек.
5. Включить флажок Включать в пользовательские настройки и выбрать режим: Быстрый доступ (поле на самой форме) или Обычный (в окне «Настройки»).

Параметр или отбор: что выбрать

Оба способа сужают выборку, но работают на разных этапах.

Дату остатков, период оборотов и обязательную организацию делайте параметрами. Всё, что пользователь хочет «докрутить» сам, оставьте отборам.

Установка параметра из кода перед формированием отчёта

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

В модуле объекта отчёта

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

Процедура ПриКомпоновкеРезультата(ДокументРезультат, ДанныеРасшифровки, СтандартнаяОбработка)

	СтандартнаяОбработка = Ложь;

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

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

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

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

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

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

Метод УстановитьЗначениеПараметра сам включает флажок использования. Если параметра с таким именем в схеме нет, ошибки не будет — значение просто никуда не попадёт. Поэтому имя проверяйте по вкладке Параметры, а не по памяти.

Из формы отчёта или при открытии из другого объекта

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

&НаСервере
Процедура УстановитьПараметрОтчета(ИмяПараметра, Значение)

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

	ЗначениеПараметра.Значение = Значение;
	ЗначениеПараметра.Использование = Истина;

	Идентификатор = ЗначениеПараметра.ИдентификаторПользовательскойНастройки;
	Если ЗначениеЗаполнено(Идентификатор) Тогда
		Для Каждого Элемент Из Компоновщик.ПользовательскиеНастройки.Элементы Цикл
			Если Элемент.ИдентификаторПользовательскойНастройки = Идентификатор Тогда
				Элемент.Значение = Значение;
				Элемент.Использование = Истина;
			КонецЕсли;
		КонецЦикла;
	КонецЕсли;

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

Код меняет значение и в настройках варианта, и в пользовательской настройке. Тогда не важно, в каком режиме параметр показан пользователю.

Список значений: как передать несколько складов или организаций

Условие В (&Склады) принимает несколько значений, но только если на вкладке Параметры у строки Склады стоит флажок Доступен список значений. Без него пользователь выберет только один склад.

В коде передавайте СписокЗначений:

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

Что учесть при работе со списком:

• 📭 Пустой список при включённом флажке использования даёт пустой результат: условию В () не соответствует ни одна запись. Если пустой список должен означать «все склады», уберите условие в {ГДЕ ...} и снимайте флажок использования, когда список пуст.
• 🌳 Для иерархических справочников пишите В ИЕРАРХИИ (&Группы) — тогда выбранная группа захватит и вложенные элементы.
• 🔢 Тип параметра-списка задаётся как тип одного элемента. Ставить тип «Список значений» не нужно.
• 📋 Значение по умолчанию для списка задают в той же колонке Значение — откроется окно списка, куда добавляют несколько элементов.

Почему параметр не срабатывает: ошибки и как их найти

Большинство проблем с параметрами укладывается в несколько симптомов. Найдите свой:

Как посмотреть, что реально ушло в запрос

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

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