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

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

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

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

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

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

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

ОткрытьЗначение(Ссылка)

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

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

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

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

Возвращает объект формы до открытия — можно вызвать её методы и затем показать через Открыть(). Выполняется с обращением к серверу.

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

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

&НаКлиенте
Процедура ОткрытьДокумент(Команда)

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

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

КонецПроцедуры

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

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

Получение объекта формы через ПолучитьФорму

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

&НаКлиенте
Процедура ПолучитьИОткрыть(Команда)

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

// Можно обратиться к экспортным процедурам формы или её реквизитам
Форма.Открыть();

КонецПроцедуры

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

Третий параметр ПолучитьФорму() — уникальность. Если передать Истина или уникальный ключ, при повторном вызове будет создана новая форма; иначе платформа вернёт уже существующую форму с тем же ключом и параметрами.

Получение формы в обычном приложении

В обычном приложении (толстый клиент, режим обычных форм) синтаксис другой: форму получают через менеджер документа или через объект документа.

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

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

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

Параметры формы: что можно передать и как их принять

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

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

1. 1
   Определите режим: управляемое или обычное приложение
2. 2
   Выберите метод: ОткрытьЗначение, ОткрытьФорму или ПолучитьФорму
3. 3
   Сформируйте структуру параметров с ключом Ключ для существующего документа
4. 4
   При необходимости объявите произвольные параметры в форме документа
5. 5
   Вызовите метод на клиенте и проверьте, что открылась нужная форма с верными данными

Открытие формы выбора и обработка результата

Чтобы пользователь выбрал документ из списка, откройте форму выбора с описанием оповещения — процедурой, которая получит результат после закрытия.

&НаКлиенте
Процедура ВыбратьДокумент(Команда)

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

КонецПроцедуры

&НаКлиенте
Процедура ПослеВыбораДокумента(Результат, ДопПараметры) Экспорт

Если Результат <> Неопределено Тогда
// Результат — ссылка на выбранный документ
КонецЕсли;

КонецПроцедуры

Обратите внимание на третий параметр — владелец формы. Если передать ЭтотОбъект, форма выбора откроется поверх текущей и уведомление о выборе придёт именно ей. В форме списка для отбора по реквизитам используйте параметр Отбор — структуру вида «имя поля — значение».

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

Чаще всего проблемы возникают не из-за синтаксиса, а из-за контекста выполнения и прав доступа.

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

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

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

Открылась ли форма

Норма

Показана форма нужного вида документа

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

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

Данные в форме

Норма

Реквизиты соответствуют документу по ссылке

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

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

Повторный вызов

Норма

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

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

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

FAQ

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

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

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

Нет. Формы создаются только в клиентском контексте. На сервере работают с данными через ДокументОбъект и ДокументСсылка, а открытие формы выполняют в клиентской процедуре.

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

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

Как открыть форму только для просмотра?

Передайте структуру с ключом Ключ и откройте форму, а в самой форме установите ТолькоПросмотр через параметр — для этого объявите в форме параметр и в ПриСозданииНаСервере установите ЭтотОбъект.ТолькоПросмотр = Истина. Альтернатива — стандартный параметр формы, если конфигурация его поддерживает.

Почему ОткрытьФорму выдаёт ошибку «формула не найдена» или «формы не существует»?

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

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

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