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

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

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

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

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

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

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

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

Способ 1. ОткрытьФорму — основной метод для управляемого приложения

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

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

Серверная часть, которая создаёт и записывает документ:

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

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

Если нужно дождаться закрытия формы и выполнить действия после него, используйте описание оповещения:

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

1. 1
   Создайте документ на сервере через Документы.<Имя>.СоздатьДокумент()
2. 2
   Заполните обязательные реквизиты и запишите документ методом Записать()
3. 3
   Верните ссылку на клиентскую процедуру
4. 4
   Сформируйте структуру параметров с ключом Ключ = Ссылка
5. 5
   Вызовите ОткрытьФорму с полным именем формы документа
6. 6
   Проверьте, что открылась форма именно созданного документа, а не нового

Способ 2. ОткрытьЗначение — быстрый вариант без параметров

Метод ОткрытьЗначение — самый короткий способ показать пользователю созданный документ. Он принимает ссылку и открывает для неё форму по умолчанию, определённую в конфигураторе:

&НаКлиенте
Процедура ПоказатьДокумент(СсылкаНаДокумент)
ОткрытьЗначение(СсылкаНаДокумент);
КонецПроцедуры

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

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

Способ 3. ПолучитьФорму — обычное приложение и особые случаи

В обычном приложении форму документа получают методом ПолучитьФорму() у ссылки или у объекта:

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

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

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

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

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

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

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

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

Для создания документа на основании другого объекта используйте параметр Основание:

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

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

Сравнение способов

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

Управляемое приложение, нужны параметры, владелец, оповещение о закрытии. Рекомендуемый основной способ.

ОткрытьЗначение

Быстро показать объект по ссылке без параметров. Не подходит, если нужна нестандартная форма или обработка закрытия.

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

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

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

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

Ещё один контрольный приём — программная проверка ссылки перед открытием. Убедитесь, что переменная содержит заполненную ссылку, а не Неопределено из-за необработанного исключения при записи. Оберните запись документа в попытку и сообщите пользователю причину отказа:

Попытка
НовыйДокумент.Записать(РежимЗаписиДокумента.Проведение);
Исключение
ВызватьИсключение "Не удалось записать документ: " + ОписаниеОшибки();
КонецПопытки;

Открытие формы из внешней обработки и по навигационной ссылке

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

Альтернативный вариант — навигационная ссылка. Метод ПолучитьНавигационнуюСсылку(СсылкаНаДокумент) возвращает строку вида e1cib/data/Документ.РеализацияТоваровУслуг?ref=..., которую можно передать пользователю, вывести в сообщении или положить в буфер обмена. Переход по такой ссылке внутри клиента 1С открывает стандартную форму объекта. Это удобно для уведомлений и журналов обработки, где прямой вызов открытия формы неуместен.

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

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

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

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

Норма

Содержит номер и дату созданного документа

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

Заголовок «(не записан)» — ссылка не передана в параметр Ключ

Состояние записи

Норма

Документ записан, доступны команды Провести и Записать

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

Форма нового объекта со звёздочкой модифицированности

Место вызова кода

Норма

Открытие выполняется в клиентской процедуре

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

Вызов на сервере или в фоновом задании — ошибка исполнения

Навигационная ссылка формы

Норма

Содержит ref с уникальным идентификатором документа

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

Навигационная ссылка отсутствует — объект не записан

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

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

Нет. Формы — клиентские объекты, на сервере доступна только работа с данными: создание, запись, проведение документа. Правильная схема — серверная функция создаёт документ и возвращает ссылку, а клиентская процедура открывает форму через ОткрытьФорму или ОткрытьЗначение.

Чем ОткрытьФорму отличается от ОткрытьЗначение?

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

Открывается форма нового документа вместо созданного — в чём причина?

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

Как открыть форму и выполнить код после её закрытия?

Передайте в ОткрытьФорму описание оповещения: Новый ОписаниеОповещения("ИмяПроцедуры", ЭтотОбъект, ДополнительныеПараметры). После закрытия формы платформа вызовет указанную клиентскую процедуру, куда придёт результат закрытия, если форма его возвращает.

Работает ли ПолучитьФорму в управляемом приложении?

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

Как открыть сразу все документы, созданные обработкой?

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