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

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

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

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

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

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

Передача параметра при открытии формы

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

Типовой код выглядит так. На стороне вызывающей формы:

ПараметрыФормы = Новый Структура;
ПараметрыФормы.Вставить("Контрагент", КонтрагентСсылка);
ОткрытьФорму("Документ.РеализацияТоваровУслуг.ФормаСписка", ПараметрыФормы);

На стороне формы со списком:

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

Чтобы этот код сработал, в запросе динамического списка параметр должен быть объявлен и использован, например: ГДЕ РеализацияТоваровУслуг.Контрагент = &Контрагент. Если параметр объявлен в запросе, но значение не установлено, платформа при открытии формы выдаст ошибку о незаполненном параметре либо список окажется пустым — поведение зависит от версии платформы и настроек.

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

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

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

Пример обработчика изменения поля:

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

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

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

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

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

Параметр незаменим в трёх случаях: когда условие передаётся в параметры виртуальной таблицы регистра (например, период остатков), когда значение используется внутри сложного произвольного запроса (соединения, объединения, вычисляемые поля) и когда нужно скрыть механику фильтрации от пользователя. Установка отбора программно выглядит так:

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

Сравнение вариантов

Параметр запроса

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

Отбор компоновщика

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

Параметры формы списка (Отбор)

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

Передача параметра в виртуальную таблицу регистра

Отдельный и самый чувствительный к ошибкам случай — динамический список на базе виртуальной таблицы, например остатков или оборотов регистра. Здесь параметр нужно передавать внутрь виртуальной таблицы, а не в общее условие ГДЕ. Иначе СУБД сначала выберет весь регистр, а потом отфильтрует результат, что на больших таблицах приводит к заметным задержкам.

Правильный фрагмент запроса:

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

Оба параметра — &Период и &Склад — появятся в коллекции Список.Параметры и устанавливаются стандартным способом. Если период не нужен, в параметре виртуальной таблицы можно оставить пустое место перед запятой, но параметр склада всё равно объявляется в тексте запроса.

Проверка результата и типичные ошибки

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

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

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

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

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

Содержимое списка после открытия

Норма

Видны только записи, соответствующие переданному значению

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

Пустой список или все записи без фильтрации

Смена значения параметра в работающей форме

Норма

Список обновляется автоматически

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

Данные не меняются до переоткрытия формы

Открытие формы из всех точек вызова

Норма

Форма открывается без ошибок из любого места

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

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

FAQ

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

Нет, параметры запроса доступны только при включённом флаге «Произвольный запрос». Без него используйте программный отбор через КомпоновщикНастроек или стандартную передачу структуры Отбор в параметрах формы.

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

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

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

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

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

Добавьте элемент отбора в Настройки компоновщика (а не в пользовательские настройки) и не выводите его в быстрый доступ. Либо реализуйте фильтрацию параметром запроса — параметры в настройках списка пользователю не показываются.

Чем УстановитьЗначениеПараметра отличается от прямого присваивания?

Метод УстановитьЗначениеПараметра ищет параметр по имени и устанавливает значение с признаком использования. Прямой поиск элемента коллекции с присваиванием тоже работает, но требует отдельно установить Использование = Истина, иначе параметр может быть проигнорирован.

Нужно ли обновлять список после установки параметра?

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