Как передать список значений в параметр СКД 1С

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

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

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

Настройка типа данных параметра в СКД

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

Для передачи перечня элементов наиболее подходящим типом является СписокЗначений. Этот тип данных специально предназначен для хранения коллекций однородных или разнородных значений с дополнительными признаками (пометками удаления, представлениями). Альтернативой может служить тип Массив, однако СписокЗначений предпочтительнее из-за встроенных методов работы и лучшей совместимости с элементами управления формы.

Также важно указать допустимые типы значений внутри коллекции. Если вы планируете передавать список документов, в настройках типа параметра нужно добавить тип ДокументСсылка или конкретный вид документа. Это позволит системе 1С корректно обрабатывать выборку в диалоге настроек отчета.

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

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

Использование оператора В в тексте запроса

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

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

ВЫБРАТЬ
РеализацияТоваровУслуг.Ссылка КАК Ссылка,
РеализацияТоваровУслуг.Дата КАК Дата,
РеализацияТоваровУслуг.Контрагент КАК Контрагент
ИЗ
Документ.РеализацияТоваровУслуг КАК РеализацияТоваровУслуг
ГДЕ
РеализацияТоваровУслуг.Ссылка В(&СписокДокументов)

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

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

Обработка пустого списка и логика отбора

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

Чтобы реализовать логику «если список не заполнен, показать все данные», необходимо использовать составное условие. Для этого применяется конструкция ИЛИ в сочетании с проверкой количества элементов. В языке запросов 1С нет прямой функции Count() для параметров внутри текста запроса, поэтому используют трюк с вложенными запросами или предварительную обработку в модуле объекта.

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

Сценарий	Метод реализации	Поведение при пустом списке
Фильтр в тексте запроса	ГДЕ Поле В(&Параметр)	Часто возвращает пусто (зависит от версии)
Отбор в настройках СКД	Вкладка «Отборы» → Поле → В списке	Игнорирует условие (показывает все)
Сложная логика	Временная таблица + соединение	Требует явной проверки в коде

Если вы вынуждены использовать текст запроса, рассмотрите вариант создания временной таблицы из параметра. Это дает больше контроля над данными. Вы можете явно проверить, есть ли в таблице записи, и на основе этого формировать основной запрос.

⚠️ Внимание: Логика работы оператора В с пустым параметром может различаться на разных версиях платформы 1С. Всегда тестируйте сценарий «ничего не выбрано» на актуальной версии конфигурации.

Передача списка из кода в объект СКД

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

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

// Пример кода на встроенном языке 1С
Параметры = Новый Структура;
СписокЗначений = Новый СписокЗначений;

// Заполнение списка
СписокЗначений.Добавить(СсылкаНаДокумент1);
СписокЗначений.Добавить(СсылкаНаДокумент2);

// Присваивание параметру
Параметры.Вставить("СписокДокументов", СписокЗначений);

// Установка параметров в компоновщик
Компоновщик.Параметры = Параметры;

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

Также стоит учитывать, что при передаче больших объемов данных из кода в СКД может наблюдаться небольшое снижение производительности на этапе инициализации отчета. Однако это обычно компенсируется скоростью выполнения самого запроса благодаря оптимизации СУБД.

Особенность работы со значениями

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

Работа с составными типами и выражениями

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

При использовании составных типов в операторе В язык запросов 1С корректно обрабатывает сравнение, если типы совместимы. Однако, если в списке окажутся значения, несовместимые с типом поля в таблице (например, строка вместо ссылки), возникнет ошибка выполнения.

Для сложных случаев фильтрации можно использовать выражения. Например, если нужно отбирать документы по списку контрагентов, но в параметре переданы ссылки на договоры, потребуется дополнительное соединение или использование функции ЕСТЬNULL для обработки отсутствующих связей.

Иногда полезно использовать функцию ЗНАЧЕНИЕ для жесткого задания значений прямо в тексте запроса, но при работе с динамическими списками от пользователя это неприменимо. Параметризация остается единственным гибким решением.

⚠️ Внимание: Интерфейс и возможности настройки типов данных могут обновляться с выходом новых релизов платформы 1С. Рекомендуется сверять доступные типы в вашей конкретной версии конфигуратора.

Оптимизация производительности при больших списках

Передача списка из нескольких тысяч элементов может стать узким местом. Хотя механизм параметров оптимизирован, существуют пределы. Если список превышает несколько тысяч записей, стоит рассмотреть альтернативные подходы, такие как запись списка во временную таблицу перед основным запросом.

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

Также стоит избегать использования параметров-списков в условиях соединения (ЛЕВОЕ СОЕДИНЕНИЕ.. ПО.. В(&Параметр)), если это возможно. Лучше вынести фильтрацию в блок ГДЕ основного запроса или использовать отборы СКД.

Проверка производительности должна проводиться на тестовой базе, приближенной по объему к промышленной. Используйте инструменты мониторинга запросов, встроенные в платформу 1С, чтобы анализировать длительность выполнения и потребление ресурсов.

Можно ли передать в параметр СКД таблицу значений?

Нет, напрямую передать объект ТаблицаЗначений в параметр типа СписокЗначений нельзя. Необходимо предварительно преобразовать таблицу значений в список, пройдя циклом по строкам и добавив нужные колонки в список значений.

Что делать, если отчет не видит параметр?

Проверьте, сохранена ли схема компоновки данных после добавления параметра. Убедитесь, что имя параметра в тексте запроса совпадает с именем в настройках СКД (включая регистр) и начинается с символа &.

Как очистить список значений в параметре программно?

Для очистки создайте новый пустой объект СписокЗначений и присвойте его параметру в структуре параметров перед запуском компоновщика. Метод Очистить() у существующего объекта также подойдет, если вы работаете с ссылкой на объект параметра.

Влияет ли порядок элементов в списке на результат?

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