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

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

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

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

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

&НаКлиенте
Процедура ОткрытьДокумент(Команда)
СсылкаНаДокумент = ПолучитьСсылкуНаДокумент(); // любой способ получения ссылки
Если ЗначениеЗаполнено(СсылкаНаДокумент) Тогда
ОткрытьЗначение(СсылкаНаДокумент);
КонецЕсли;
КонецПроцедуры

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

Способ 2. ОткрытьФорму с параметром Ключ — полный контроль

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

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

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

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

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

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

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

&НаКлиенте
Процедура ПослеЗакрытияДокумента(Результат, ДополнительныеПараметры) Экспорт
Элементы.Список.Обновить();
КонецПроцедуры

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

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

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

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

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

Как получить ссылку на документ для открытия

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

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

&НаСервереБезКонтекста
Функция НайтиДокументПоНомеру(Номер, Дата)
Запрос = Новый Запрос("ВЫБРАТЬ ПЕРВЫЕ 1 Ссылка
|ИЗ Документ.РеализацияТоваровУслуг
|ГДЕ Номер = &Номер И Дата МЕЖДУ &Начало И &Конец");
Запрос.УстановитьПараметр("Номер", Номер);
Запрос.УстановитьПараметр("Начало", НачалоДня(Дата));
Запрос.УстановитьПараметр("Конец", КонецДня(Дата));
Выборка = Запрос.Выполнить().Выбрать();
Возврат ?(Выборка.Следующий(), Выборка.Ссылка, Неопределено);
КонецФункции

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

&НаКлиенте
Процедура ОткрытьПоСсылке(Ссылка)
	Если Не ЗначениеЗаполнено(Ссылка) Тогда
		Возврат;
	КонецЕсли;
	ПоказатьЗначение(, Ссылка); // альтернатива ОткрытьЗначение
КонецПроцедуры

Особые сценарии и ограничения

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

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

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

Типичные ошибки и как их исправить

Самая распространённая ошибка — «Ошибка открытия формы. Недопустимое значение параметра Ключ»: она возникает, когда в параметр Ключ передали значение не того типа (например, ссылку на справочник вместо документа) или «битую» ссылку на удалённый объект. Перед открытием проверяйте тип через ТипЗнч(Ссылка) и существование объекта запросом или функцией ОбщегоНазначения.СсылкаСуществует() в типовых конфигурациях на БСП.

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

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

Как проверить, что открытие работает правильно

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

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

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