Как программно открыть документ в 1С

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

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

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

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

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

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

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

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

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

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

ПолучитьФорму().Открыть()

Только обычное приложение. В управляемом режиме не работает.

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

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

// Универсальный способ, работает с любым типом ссылки
ОткрытьЗначение(СсылкаНаДокумент);

Если тип документа известен и нужен контроль над формой, используется ОткрытьФорму() с параметром Ключ, в который передаётся ссылка:

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

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

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

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

Чтобы открыть форму нового документа, достаточно вызвать ОткрытьФорму() без параметра Ключ. Часто требуется сразу заполнить часть реквизитов — для этого служит параметр ЗначенияЗаполнения:

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

ПараметрыФормы = Новый Структура;
ПараметрыФормы.Вставить("ЗначенияЗаполнения", ЗначенияЗаполнения);

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

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

Открытие копии документа

Для создания документа копированием передаётся параметр ЗначениеКопирования:

ПараметрыФормы = Новый Структура;
ПараметрыФормы.Вставить("ЗначениеКопирования", ИсходнаяСсылка);

ОткрытьФорму("Документ.ЗаказКлиента.ФормаОбъекта", ПараметрыФормы);

Открытие списка документов с отбором

Иногда нужно открыть не один документ, а список с предустановленным отбором — например, все документы по контрагенту. Для этого открывается форма списка с параметром Отбор:

Отбор = Новый Структура;
Отбор.Вставить("Контрагент", ВыбранныйКонтрагент);

ПараметрыФормы = Новый Структура;
ПараметрыФормы.Вставить("Отбор", Отбор);

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

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

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

Асинхронное открытие и веб-клиент

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

Оповещение = Новый ОписаниеОповещения("ПослеОткрытияДокумента", ЭтотОбъект);
ПоказатьЗначение(Оповещение, СсылкаНаДокумент);

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

Открытие в обычном приложении

В толстом клиенте обычного приложения форма получается напрямую у объекта:

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

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

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

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

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

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

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

Форма открылась

Норма

Отображается форма документа с ожидаемыми данными

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

Ошибка «Метод недоступен» — код выполняется на сервере

Открылся нужный документ

Норма

Номер и дата в форме совпадают со ссылкой

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

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

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

Норма

Открывается новое окно или активируется существующее — по замыслу

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

Форма «не открывается» — сработал параметр Уникальность

Практические рекомендации

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

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

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

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

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

Как открыть документ в режиме «только просмотр»?

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

Почему ОткрытьФорму не работает в общем модуле?

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

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

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

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

Да. Открытие формы нового документа (без параметра Ключ) не создаёт запись в базе — документ будет записан только когда пользователь нажмёт «Записать» или «Провести». Если форму просто закрыть, никаких данных в базе не появится.