Как получить форму документа в 1С

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

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

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

Какие виды форм документа существуют в 1С

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

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

Отдельный случай — внешние печатные формы и обработки. Они не являются формами документа, но часто открываются из него. Их получают иначе, через объект внешней обработки, и путать эти механизмы не следует.

Как получить форму документа в обычном приложении

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

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

Если объект получать не хочется (это лишнее чтение из базы), форму можно взять через менеджер документа, передав ключ — ссылку:

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

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

1. 1
   Получите ссылку на документ запросом или через НайтиПоНомеру
2. 2
   Вызовите ПолучитьФорму() у объекта или менеджера документа
3. 3
   Передайте имя формы, если нужна не основная
4. 4
   Вызовите Открыть() или ОткрытьМодально()
5. 5
   Проверьте, что форма отобразилась и содержит данные документа

Как открыть форму документа в управляемом приложении

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

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

Параметр Ключ — это ссылка на документ. Если передать структуру без ключа, откроется форма нового документа. Имя формы строится по шаблону: Документ.<ИмяДокумента>.Форма.<ИмяФормы>. Если имя формы не указать и написать только Документ.Имя.Форма, откроется основная форма объекта.

Метод ОткрытьФорму() возвращает ссылку на открытую форму — её можно сохранить в переменную и вызывать экспортные процедуры формы, если они объявлены с директивой &НаКлиенте и помечены как экспортные. Это ограниченный аналог прямого доступа к форме из обычного приложения.

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

Получение формы нового документа и передача параметров

Частая задача — открыть форму нового, ещё не записанного документа с предзаполненными реквизитами. В управляемом приложении для этого служит параметр ЗначенияЗаполнения:

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

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

Дополнительно в форму можно передавать произвольные параметры, объявленные в её модуле через Параметры в обработчике ПриСозданииНаСервере (управляемая форма) или через экспортные переменные формы (обычная). Так передают режим открытия, отборы, признаки только просмотра и другие служебные данные.

Как получить форму из внешней обработки или другого документа

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

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

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

Сравнение подходов

ПолучитьФорму()

Обычное приложение, толстый клиент. Даёт прямой доступ к форме и её элементам. Не работает в тонком и веб-клиенте.

ОткрытьФорму()

Управляемое приложение, все клиенты. Универсальный способ, но доступ к форме ограничен экспортными методами.

Работа через объект без формы

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

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

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

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

Третья группа ошибок связана с модальностью. В конфигурациях с запрещённой модальностью вызов ОткрытьМодально() приводит к исключению. Используйте асинхронную модель с описанием оповещения о закрытии — это работает в любом режиме совместимости.

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

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

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

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

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

Заголовок открытой формы

Норма

Номер и дата нужного документа

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

Новый пустой документ — ключ не передан

Данные реквизитов

Норма

Совпадают с данными в базе

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

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

Повторное открытие

Норма

Активируется уже открытая форма того же документа

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

Открываются дубли форм одного документа — не задан ключ уникальности

FAQ

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

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

Как открыть форму списка документов с отбором?

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

Чем отличается Открыть() от ОткрытьМодально()?

Открыть() показывает форму без блокировки родительского окна, ОткрытьМодально() блокирует работу до закрытия формы и возвращает результат. Модальный режим может быть запрещён настройками конфигурации, тогда следует использовать описание оповещения.

Как открыть форму документа, зная только его номер?

Сначала получите ссылку методом менеджера: Документы.Имя.НайтиПоНомеру(Номер, Дата). Затем передайте найденную ссылку в параметр Ключ при открытии формы. Проверьте, что ссылка не пустая, иначе откроется форма нового документа.

Почему открывается не та форма, которую я указал?

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

Можно ли получить форму документа из COM-соединения?

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