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

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

Работа с параметрами возможна двумя путями: через настройку запроса динамического списка в конфигураторе и программно — через свойство Параметры объекта динамического списка. Чаще всего оба подхода комбинируются: параметр объявляется в тексте запроса, а его значение устанавливается кодом при создании формы или при изменении реквизита на форме.

Ниже разобраны оба способа, приведены примеры кода, типичные ошибки и способы проверки результата. Материал применим к управляемым формам в конфигурациях на платформе 1С:Предприятие 8.3.

Что такое параметр динамического списка и когда он нужен

Параметр динамического списка — это именованное значение, которое подставляется в запрос при его выполнении. В тексте запроса параметр обозначается символом амперсанда: &Период, &Организация, &Контрагент. При выполнении запроса платформа подставляет вместо параметра конкретное значение, заданное разработчиком или пользователем.

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

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

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

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

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

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

Конструктор запроса автоматически распознает параметры на закладке «Параметры», но тип значения там не задаётся — он определяется в момент установки значения. После сохранения запроса параметр станет доступен в коллекции Параметры динамического списка и в настройках компоновщика.

Установка значения параметра программно

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

&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)
Список.Параметры.УстановитьЗначениеПараметра("Организация",
Справочники.Организации.НайтиПоНаименованию("ООО Ромашка"));
КонецПроцедуры;

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

&НаКлиенте
Процедура ОтборОрганизацияПриИзменении(Элемент)
УстановитьПараметрСписка();
КонецПроцедуры

&НаСервере
Процедура УстановитьПараметрСписка()
Список.Параметры.УстановитьЗначениеПараметра("Организация", ОтборОрганизация);
КонецПроцедуры;

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

1. 1
   Откройте свойства динамического списка и включите произвольный запрос, если он ещё не включён
2. 2
   Добавьте параметр в текст запроса через символ & и условие ГДЕ
3. 3
   Сохраните запрос и убедитесь, что параметр появился в коллекции параметров
4. 4
   В обработчике ПриСозданииНаСервере установите значение через Параметры.УстановитьЗначениеПараметра
5. 5
   Откройте форму в режиме предприятия и проверьте, что список показывает отфильтрованные данные

Параметры в настройках компоновки данных

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

Обращение к параметру через настройки выглядит так:

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

Ключевое отличие от прямой установки: здесь есть свойство Использование. Если оно равно Ложь, параметр не применяется, и условие с ним игнорируется — список показывает все записи. Это удобно для необязательных фильтров, но требует аккуратности: забытое свойство Использование — частая причина «неработающего» отбора.

Способы установки параметра

Список.Параметры.УстановитьЗначениеПараметра

Быстрый и короткий способ. Параметр всегда применяется. Подходит для обязательных условий, заданных программно.

КомпоновщикНастроек.Настройки.ПараметрыДанных

Позволяет управлять флагом Использование и делать параметр видимым пользователю. Подходит для необязательных фильтров.

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

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

Передача параметров через параметры формы

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

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

Открытие такой формы выполняется с передачей структуры параметров: ОткрытьФорму("Документ.РеализацияТоваровУслуг.ФормаСписка", Новый Структура("ОтборОрганизация", Организация)). Проверка Параметры.Свойство() обязательна: если форму откроют стандартным способом без параметров, обращение к несуществующему параметру вызовет ошибку.

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

Типичные ошибки и их устранение

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

Вторая группа ошибок связана с типами. Если параметру присвоено значение несовместимого типа (например, строка вместо ссылки на справочник), сравнение в запросе не сработает — список окажется пустым без каких-либо сообщений. Всегда проверяйте, что тип значения совпадает с типом поля, с которым сравнивается параметр.

Третья типичная ситуация — параметр установлен, но список не меняется. Причины: значение установлено на клиенте, а список находится на сервере (нужен серверный вызов); параметр задан через настройки компоновки, но Использование = Ложь; либо изменение выполнено для другого реквизита формы с похожим именем.

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

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

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

Если условие необязательное (например, фильтр «по контрагенту, если он выбран»), используйте шаблон с проверкой на пустое значение:

ГДЕ
(&Контрагент = ЗНАЧЕНИЕ(Справочник.Контрагенты.ПустаяСсылка)
ИЛИ Продажи.Контрагент = &Контрагент)

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

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

Открытие формы

Норма

Форма открывается, список заполнен данными

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

Ошибка «Параметр не определен» или пустой список

Состав записей

Норма

Все строки соответствуют условию параметра

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

Присутствуют лишние записи или отсутствуют нужные

Смена значения

Норма

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

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

Список остаётся прежним — параметр не переустанавливается

Тип значения

Норма

Тип значения совпадает с типом поля в условии

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

Строка или число вместо ссылки — сравнение не срабатывает

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

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

Нет. Если список построен по основной таблице без произвольного запроса, коллекция параметров пуста. В этом случае используйте отбор динамического списка (Список.КомпоновщикНастроек.Настройки.Отбор) либо включите произвольный запрос и напишите его текст с параметром.

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

Два рабочих варианта: добавить в запрос условие вида «&Параметр = ПустоеЗначение ИЛИ Поле = &Параметр» и по умолчанию присваивать пустую ссылку, либо управлять параметром через настройки компоновки, переключая свойство Использование. Второй способ предпочтительнее для производительности, так как лишнее условие не участвует в запросе.

Почему список пустой, хотя параметр установлен?

Чаще всего причина в несовпадении типов: параметру присвоена строка или число, а поле в условии — ссылка. Также проверьте, что значение реально существует в базе и что условие в запросе написано корректно (правильное поле, правильный знак сравнения). Для диагностики временно замените параметр на литеральное значение в запросе.

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

Напрямую — нет: объект динамического списка доступен только на сервере. Из клиентского обработчика (например, при изменении поля отбора) вызовите серверную процедуру, которая установит значение параметра. После этого список обновится автоматически.

Чем параметр отличается от отбора динамического списка?

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

Как передать список значений в параметр для условия «В»?

Присвойте параметру объект СписокЗначений или массив, а в запросе используйте оператор В: «ГДЕ Номенклатура В (&СписокНоменклатуры)». Платформа корректно разворачивает коллекции в условие. Для иерархических справочников применяйте «В ИЕРАРХИИ», чтобы отобрать вложенные элементы группы.