Как обратиться к форме списка документа в 1С

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

Способ обращения зависит от режима работы конфигурации. В управляемом приложении (1С 8.2/8.3, тонкий и веб-клиент) используются методы ОткрытьФорму() и ПолучитьФорму() с передачей параметров, а отбор настраивается через свойства динамического списка. В обычном приложении применяется ПолучитьФормуСписка() — этот метод на управляемых формах не работает.

Ниже разобраны основные сценарии: открытие формы списка из кода, установка отбора, программное обращение к уже открытой форме, встраивание списка в свою форму и типичные ошибки, из-за которых отбор «не срабатывает» или форма открывается пустой.

Как устроена форма списка и какие виды обращения существуют

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

Обращаться к форме списка можно четырьмя принципиально разными способами: открыть её пользователю интерактивно, получить объект формы для программной работы, встроить динамический список документа в собственную форму и обратиться к уже открытой форме через оповещения или уникальность. Выбор зависит от задачи: показать данные пользователю или прочитать/изменить состояние списка из кода.

Открытие формы списка из кода в управляемом приложении

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

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

Если нужна конкретная, не основная форма списка, её имя добавляется после точки: "Документ.РеализацияТоваровУслуг.Форма.МояФормаСписка". Вторым параметром передаётся структура с параметрами формы, третьим — владелец, четвёртым — ключ уникальности (по нему платформа определяет, открывать новую форму или активировать уже открытую).

Метод ПолучитьФорму() работает иначе: он возвращает объект формы, не открывая её на экране. Это нужно, когда требуется сначала что-то настроить в форме, а потом показать её методом Открыть():

ФормаСписка = ПолучитьФорму("Документ.ПриходнаяНакладная.ФормаСписка");
ФормаСписка.Открыть();

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

Установка отбора при открытии формы списка

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

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

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

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

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

Программное обращение к уже открытой форме списка

Иногда форма списка уже открыта, и нужно не создавать новую, а повлиять на существующую: обновить список, изменить отбор, активировать окно. Прямого «глобального поиска» открытых форм в платформе нет, поэтому применяют два подхода.

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

Для принудительного обновления данных списка извне чаще всего достаточно стандартного оповещения об изменении: ОповеститьОбИзменении(Тип("ДокументСсылка.РеализацияТоваровУслуг")) — все открытые динамические списки этого документа обновятся автоматически.

Встраивание списка документа в собственную форму

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

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

Обращение к форме списка в обычном приложении

В конфигурациях на обычных формах (режим обычного приложения, типичен для старых решений на платформе 8.1–8.2) синтаксис другой. Форму списка получают через менеджер документа:

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

Здесь отбор задаётся не структурой, а через объект Отбор списка документов: у каждого элемента отбора вызывается метод Установить() или заполняются свойства ВидСравнения и Значение. Этот код не переносится в управляемое приложение — при переводе конфигурации на управляемые формы его нужно переписывать на ОткрытьФорму() с параметрами.

Типичные ошибки и ограничения

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

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

Как проверить, что обращение к форме сработало

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

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