Как установить параметр в запросе СКД 1С: пошаговая инструкция

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

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

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

Объявление параметров в тексте запроса

Первым шагом при работе с параметрами является их объявление непосредственно в тексте запроса. В языке запросов 1С для этого используется ключевое слово ПАРАМЕТРЫ, которое должно располагаться перед основным текстом запроса. Синтаксис требует указания имени параметра и его типа данных. Имя параметра всегда начинается с символа &, что отличает его от полей таблиц и псевдонимов.

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

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

Обратите внимание, что порядок объявления параметров не имеет значения для движка запросов, но для читаемости кода рекомендуется группировать их логически. Если вы используете параметр в условии ЕСТЬ NULL или для динамического построения запроса, тип может быть указан как Неопределено, однако это снижает производительность и безопасность кода. Всегда старайтесь использовать конкретные типы, такие как Число, Строка или ссылки на конкретные справочники.

Настройка элементов отчета в конструкторе СКД

После того как параметры объявлены в запросе, их необходимо связать с полями формы отчета. В конструкторе СКД это делается через вкладку «Параметры». Система автоматически подтянет все переменные, найденные в тексте запроса после ключевого слова ПАРАМЕТРЫ. Однако автоматическое определение не всегда гарантирует правильную настройку видов сравнения и обязательности заполнения.

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

• 📅 Период: Установите вид сравнения «В интервале» для параметров даты, чтобы пользователь мог выбрать диапазон.
• 🏢 Организация: Используйте вид сравнения «В списке», если отчет должен строиться по нескольким организациям одновременно.
• 🔢 Сумма: Для числовых параметров часто применяют виды «Больше», «Меньше» или «В интервале» для фильтрации итогов.

Также важным аспектом является настройка свойства «Использование». Если параметр помечен как «Не использовать», он не будет отображаться на форме отчета, но его значение можно передать программно. Это полезно для скрытых фильтров, которые зависят от прав доступа пользователя или контекста запуска отчета. Не забудьте проверить галочку «Обязательное заполнение», если отчет не имеет смысла без указания конкретного значения, например, без выбора склада или контрагента.

Работа со значениями по умолчанию и отборами

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

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

⚠️ Внимание: При использовании выражений в значениях по умолчанию убедитесь, что они не вызывают циклических зависимостей. Если параметр А зависит от параметра Б, а параметр Б зависит от А, система выдаст ошибку при открытии отчета.

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

Тип параметра	Рекомендуемый вид сравнения	Пример значения по умолчанию
Дата	В интервале	НачалоМесяца(ТекущаяДата), КонецМесяца(ТекущаяДата)
СправочникСсылка	В списке / Равно	ПустаяСсылка (для выбора всех) или КонкретныйЭлемент
Число	Больше или равно	0
Строка	Начинается с / Содержит	Пустая строка

Программная установка параметров перед выводом

В ряде случаев требуется установить значение параметра программно перед показом формы отчета. Это актуально при запуске отчета из другой обработки, при переходе из документа или для ограничения данных в зависимости от прав пользователя. Для этого используется объект ПараметрКомпоновкиДанных и коллекция параметров настройки.

В коде модуля объекта или формы, где происходит инициализация отчета, необходимо получить доступ к настройкам компоновки данных. Затем создается новый элемент параметра, ему присваивается имя, соответствующее имени в запросе (без символа &), и устанавливается значение. После этого настройки передаются в схему компоновки данных.

Параметр = Новый ПараметрКомпоновкиДанных;
Параметр.Имя ="Организация";
Параметр.Установить(ТекущаяОрганизация);

Настройки.Параметры.Добавить(Параметр);
Компоновщик.ПроцессКомпоновкиДанных(Настройки);

Если требуется жестко зафиксировать значение, необходимо установить свойство «Доступность» параметра в значение Недоступно или скрыть поле параметра на форме.

Что будет если имя параметра в коде не совпадет с запросом?

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

Особенности работы с параметрами типа «Список значений»

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

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

• ✅ Гибкость: Позволяет пользователю выбрать произвольное количество элементов для анализа.
• ⚡ Производительность: Фильтрация по списку значений выполняется на стороне СУБД, что быстрее, чем фильтрация в коде 1С.
• ⚙️ Универсальность: Подходит для любых типов данных: чисел, строк, дат и ссылок.

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

⚠️ Внимание: Количество элементов в списке значений может влиять на длину генерируемого SQL-запроса. Некоторые СУБД имеют ограничение на количество элементов в операторе IN. Если список очень большой (тысячи позиций), рассмотрите возможность использования временной таблицы или другого механизма фильтрации.

Диагностика и решение ошибок

Несмотря на кажущуюся простоту, при работе с параметрами часто возникают ошибки. Самая распространенная из них — «Не заполнен обязательный параметр». Это происходит, когда в свойствах параметра стоит галочка обязательности, но значение не передано ни по умолчанию, ни пользователем, ни программно. Решение — проверить настройки вида сравнения и значения по умолчанию.

Другая частая проблема — несоответствие типов. Если в запросе параметр объявлен как Число, а пользователь пытается ввести строку или дату, отчет не сформируется. В современных версиях платформы 1С интерфейс ввода старается предотвратить это, ограничивая ввод, но при программной установке ошибка возможна. Всегда проверяйте типы переменных перед присваиванием.

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

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

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

Для этого в тексте запроса используйте конструкцию ЕСТЬ NULL. Пример условия: ГДЕ (Продажи.Организация = &Организация ИЛИ &Организация ЕСТЬ NULL). В настройках СКД снимите галочку «Обязательное заполнение» и установите значение по умолчанию в ПустаяСсылка или Неопределено.

Можно ли использовать один параметр для нескольких полей в запросе?

Да, это стандартная практика. Вы можете объявить один параметр, например &ПериодНачало, и использовать его в условиях отбора для разных таблиц или регистров. Это упрощает управление отчетом, так как пользователю нужно ввести дату только один раз.

Почему параметр не виден на форме отчета после добавления в запрос?

Вероятно, вы не обновили схему компоновки данных. После изменения текста запроса необходимо нажать кнопку «Обновить» в конструкторе СКД или перезапустить конструктор, чтобы новые переменные из секции ПАРАМЕТРЫ появились в списке доступных параметров настройки.

Как передать параметр из внешней обработки в отчет СКД?

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

Можно ли изменить список доступных значений параметра (выбор из списка) динамически?

Да, это можно сделать через событие ПриИзмененииНастроек или используя расширенные настройки отчета. Также можно использовать механизм «Выбор из списка» с предопределенным списком значений, который формируется программно перед открытием формы.