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

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

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

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

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

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

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

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

Сравнение способов открытия

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

Универсальный вариант: параметры, владелец, уникальность. Подходит для большинства задач.

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

Только просмотр существующего объекта по ссылке, без передачи параметров.

ОткрытьФормуМодально()

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

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

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

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

Если указать просто имя объекта без конкретной формы — "Документ.РеализацияТоваровУслуг.ФормаОбъекта" — платформа откроет форму, назначенную основной. Это удобно, когда конфигурация дорабатывается и состав форм меняется: код не придётся править при смене основной формы.

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

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

Для нового документа в параметры передают структуру ЗначенияЗаполнения — вложенную структуру, где ключи совпадают с именами реквизитов объекта:

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

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

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

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

Копирование документа и ввод на основании

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

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

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

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

Передача произвольных параметров и их обработка в форме

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

&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)
Если Параметры.Свойство("РежимВыбора") И Параметры.РежимВыбора Тогда
// настройка формы под выбор
КонецЕсли;
КонецПроцедуры

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

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

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

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

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

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

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

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

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

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

Норма

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

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

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

Заполнение нового документа

Норма

Переданные реквизиты подставлены в поля формы

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

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

Отбор в списке

Норма

Список показывает только документы по условию, отбор виден в панели настроек

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

Показаны все документы — поле отбора отсутствует в динамическом списке или имя не совпадает

Ограничения, безопасность и когда нужна доработка конфигурации

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

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

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

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

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

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

Почему параметр Ключ игнорируется и открывается новый документ?

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

Как передать таблицу товаров в новый документ?

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

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

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

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

Через структуру Отбор по полю Дата задать диапазон нельзя — структура поддерживает только равенство. Передайте даты начала и окончания как произвольные параметры, а в ПрисозданииНаСервере формы списка программно добавьте два элемента отбора с видом сравнения «БольшеИлиРавно» и «МеньшеИлиРавно» в Список.Отбор.

Работают ли параметры формы в обычном приложении?

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