Параметры СКД: период, список значений, установка из кода

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

Откуда берутся параметры в схеме компоновки

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

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

Какие свойства параметра нужны на практике

Свойств у параметра на закладке «Параметры» много, чаще всего нужны эти:

Как добавить параметр в СКД

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

Необязательное условие в запросе СКД пишут в фигурных скобках: если параметр в настройках не используется, система компоновки выбросит условие из запроса без ошибки. Имена регистра и полей ниже условные:

ВЫБРАТЬ
    Продажи.Контрагент КАК Контрагент,
    Продажи.Номенклатура КАК Номенклатура,
    Продажи.КоличествоОборот КАК Количество,
    Продажи.СуммаОборот КАК Сумма
ИЗ
    РегистрНакопления.Продажи.Обороты(&НачалоПериода, &КонецПериода, , ) КАК Продажи
{ГДЕ
    Продажи.Контрагент В (&Контрагенты)}

Параметры СКД для периода: стандартный период

Два поля «Дата начала» и «Дата окончания» неудобны: нельзя одним кликом выбрать «Этот квартал», а у даты без времени легко потерять последний день. Удобнее один параметр стандартного периода, из которого вычисляются даты для запроса.

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

Почему «дата и время», а не просто «дата»: дата окончания стандартного периода приходит с временем конца дня. Если у параметра КонецПериода состав «Дата», время отрежется и в запрос уйдёт полночь последнего дня: пользователь выбирает 30-е число, а продажи за 30-е в отчёт не попадают.

Список значений и доступные значения

Это два разных свойства параметра, и их часто путают.

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

Пример переключателя: параметр Показатель типа «Строка» с доступными значениями «Сумма» и «Количество». В запросе он выбирает, какую колонку считать:

ВЫБОР
    КОГДА &Показатель = "Сумма"
        ТОГДА Продажи.СуммаОборот
    ИНАЧЕ Продажи.КоличествоОборот
КОНЕЦ КАК Значение

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

Как вывести параметр в быстрые настройки и на форму отчёта

Чтобы параметр был виден над табличным документом, а не только в окне «Настройки…», его выводят в пользовательские настройки:

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

Стандартная форма отчёта покажет такие поля сама. В собственной форме период часто делают обычным реквизитом и связывают с настройками кодом — пример ниже.

Как установить параметр СКД программно

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

// Модуль формы отчёта (управляемая форма, платформа 8.3).
// На форме: основной реквизит «Отчет» и реквизит «Период» (тип СтандартныйПериод),
// выведенный полем ввода. В схеме компоновки есть параметр «Период».
// Обработчики событий формы назначьте в палитре свойств формы.

&НаКлиенте
Процедура ПриОткрытии(Отказ)

    ОбновитьПолеПериода();

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

// Пользователь выбрал другой вариант отчёта.
&НаСервере
Процедура ПриЗагрузкеВариантаНаСервере(Настройки)

    ОбновитьПолеПериода();

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

// Загружены сохранённые пользовательские настройки.
&НаСервере
Процедура ПриЗагрузкеПользовательскихНастроекНаСервере(Настройки)

    ОбновитьПолеПериода();

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

&НаКлиенте
Процедура ПериодПриИзменении(Элемент)

    Если Не УстановитьПараметрСКД(Отчет.КомпоновщикНастроек, "Период", Период) Тогда
        Сообщение = Новый СообщениеПользователю;
        Сообщение.Текст = НСтр("ru = 'В настройках отчёта не найден параметр Период'");
        Сообщение.Сообщить();
    КонецЕсли;

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

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

    УстановитьПараметрСКД(Отчет.КомпоновщикНастроек, "Период", Период);
    СкомпоноватьРезультат(РежимКомпоновкиРезультата.Авто);

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

// Показывает в поле то значение, с которым сейчас сформируется отчёт.
&НаКлиентеНаСервере
Процедура ОбновитьПолеПериода()

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

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

// Записывает значение параметра данных в настройки варианта
// и в пользовательские настройки, если параметр туда выведен.
// Возвращает Ложь, если параметра в настройках нет.
&НаКлиентеНаСервереБезКонтекста
Функция УстановитьПараметрСКД(КомпоновщикНастроек, ИмяПараметра, Значение, Использование = Истина)

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

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

    ПользовательскийЭлемент = ПользовательскийЭлементПараметра(КомпоновщикНастроек, ЭлементНастроек);
    Если ПользовательскийЭлемент <> Неопределено Тогда
        ПользовательскийЭлемент.Значение = Значение;
        ПользовательскийЭлемент.Использование = Использование;
    КонецЕсли;

    Возврат Истина;

КонецФункции

// Возвращает значение параметра с учётом пользовательских настроек.
&НаКлиентеНаСервереБезКонтекста
Функция ЗначениеПараметраСКД(КомпоновщикНастроек, ИмяПараметра)

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

    ПользовательскийЭлемент = ПользовательскийЭлементПараметра(КомпоновщикНастроек, ЭлементНастроек);
    Если ПользовательскийЭлемент <> Неопределено Тогда
        Возврат ПользовательскийЭлемент.Значение;
    КонецЕсли;

    Возврат ЭлементНастроек.Значение;

КонецФункции

// Находит «двойника» параметра в пользовательских настройках.
&НаКлиентеНаСервереБезКонтекста
Функция ПользовательскийЭлементПараметра(КомпоновщикНастроек, ЭлементНастроек)

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

    Возврат КомпоновщикНастроек.ПользовательскиеНастройки.Элементы.Найти(Идентификатор);

КонецФункции

Разбор ключевых строк:

• НайтиЗначениеПараметра(Новый ПараметрКомпоновкиДанных(ИмяПараметра)) ищет параметр именно в настройках варианта. Если вернулось Неопределено, проверьте имя и флаг «Ограничение доступности»: параметр с этим флагом в настройки не попадает.
• ЭлементНастроек.Использование = Использование (по умолчанию Истина): без включённого использования значение есть, но в запрос не идёт.
• ИдентификаторПользовательскойНастройки заполнен только у параметров, выведенных в пользовательские настройки. По нему находим «двойника» в ПользовательскиеНастройки.Элементы и меняем значение там же.
• Функции &НаКлиентеНаСервереБезКонтекста работают и на клиенте, и на сервере без лишнего серверного вызова. ОбновитьПолеПериода — &НаКлиентеНаСервере: ей нужен контекст формы, чтобы записать реквизит Период.

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

Эти события относятся к загрузке настроек, а не к правке значения. Если «Период» выведен в пользовательские настройки, его можно поменять ещё и в окне «Настройки…», и поле отстанет. Когда период вводится только через реквизит Период, снимите у параметра «Включать в пользовательские настройки». Если вывести всё же нужно, формируйте отчёт командой СформироватьОтчет из листинга: перед компоновкой она переносит значение поля в настройки.

Служебный параметр перед каждым формированием

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

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

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

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

Параметры при выводе отчёта из кода

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

&НаСервере
Процедура СформироватьНаСервере()

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

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

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

    ПараметрМакета = МакетКомпоновки.ЗначенияПараметров.Найти("ДатаФормирования");
    Если ПараметрМакета <> Неопределено Тогда
        ПараметрМакета.Значение = ТекущаяДатаСеанса();
    КонецЕсли;

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

    Результат.Очистить();

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

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

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

Как передать параметр СКД при открытии отчёта

Типичная задача: из карточки контрагента открыть отчёт по продажам сразу по этому контрагенту. У формы отчёта есть стандартные параметры Отбор и СформироватьПриОткрытии. В Отбор передают структуру: ключ — имя, значение — то, что нужно установить. Если имя совпадает с параметром данных схемы, устанавливается параметр, иначе добавляется отбор по полю с этим именем:

&НаКлиенте
Процедура ОткрытьОтчетПоПродажам(Команда)

    Если Не ЗначениеЗаполнено(Объект.Ссылка) Тогда
        Возврат;
    КонецЕсли;

    // Отбор по полю результата «Контрагент» (параметр в схеме не нужен):
    // ЗначенияОтбора = Новый Структура("Контрагент", Объект.Ссылка);

    // Заполнение параметра данных «Контрагенты» из запроса выше:
    СписокКонтрагентов = Новый СписокЗначений;
    СписокКонтрагентов.Добавить(Объект.Ссылка);
    ЗначенияОтбора = Новый Структура("Контрагенты", СписокКонтрагентов);

    ПараметрыФормы = Новый Структура;
    ПараметрыФормы.Вставить("Отбор", ЗначенияОтбора);
    ПараметрыФормы.Вставить("СформироватьПриОткрытии", Истина);

    ОткрытьФорму("Отчет.ПродажиПоКонтрагентам.Форма", ПараметрыФормы, ЭтотОбъект);

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

Основная форма отчёта в пути называется Форма; имени ФормаОбъекта, как у документов, у отчётов нет. Неосновную форму указывают полностью: "Отчет.ПродажиПоКонтрагентам.Форма.ФормаОтчета".

В параметризуемой команде ссылку берут из ПараметрКоманды, а владельцем формы передают ПараметрыВыполненияКоманды.Источник: ЭтотОбъект в модуле команды не определён. Если у команды режим использования параметра «Множественный», в ПараметрКоманды приходит массив:

&НаКлиенте
Процедура ОбработкаКоманды(ПараметрКоманды, ПараметрыВыполненияКоманды)

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

    ПараметрыФормы = Новый Структура;
    ПараметрыФормы.Вставить("Отбор", Новый Структура("Контрагенты", СписокКонтрагентов));
    ПараметрыФормы.Вставить("СформироватьПриОткрытии", Истина);

    ОткрытьФорму("Отчет.ПродажиПоКонтрагентам.Форма", ПараметрыФормы,
        ПараметрыВыполненияКоманды.Источник, ПараметрыВыполненияКоманды.Уникальность,
        ПараметрыВыполненияКоманды.Окно, ПараметрыВыполненияКоманды.НавигационнаяСсылка);

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

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

Типичные ошибки

• «Не установлено значение параметра "Контрагент"». Параметр есть в запросе, но в настройках у него снят флажок или значение не задано. Отметьте параметр в настройках, задайте значение по умолчанию или вынесите условие в {ГДЕ …}.
• Значение из кода игнорируется. Параметр выведен в пользовательские настройки, а код пишет только в Настройки. Нужно менять оба слоя.
• Из отчёта пропал последний день. У даты окончания состав «Дата» без времени. Используйте стандартный период с выражением &Период.ДатаОкончания.
• Отчёт падает при выборе нескольких значений. Включён «Доступен список значений», а в запросе осталось =. Замените на В.
• Параметр не виден в быстрых настройках. Не включено «Включать в пользовательские настройки» либо у пользователя сохранены старые настройки. Сбросьте их командой «Ещё → Стандартные настройки» в форме отчёта.

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

Чем параметр отличается от отбора?

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

Как показать значение параметра в шапке отчёта?

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

Можно ли добавить параметр в схему программно?

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

Когда проще заказать

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

По теме

• СКД программно: вывод отчёта из кода
• Отбор динамического списка программно
• Пустая ссылка в запросе 1С
• Программное изменение формы