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

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

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

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

Как работает механизм передачи параметров

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

ПараметрыФормы = Новый Структура;
ПараметрыФормы.Вставить("Контрагент", КонтрагентСсылка);
ПараметрыФормы.Вставить("РежимВыбора", Истина);

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

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

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

Базовый синтаксис: ОткрытьФорму с параметрами

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

ОткрытьФорму(ИмяФормы, Параметры, Владелец, Уникальность, Окно, НавигационнаяСсылка, ОписаниеОповещенияОЗакрытии, РежимОткрытияОкна);

Разберём аргументы, которые чаще всего используются вместе с параметрами:

• ИмяФормы — полное имя, например "Справочник.Номенклатура.Форма.ФормаЭлемента" или "ОбщаяФорма.ФормаПодбора";
• Параметры — структура с передаваемыми данными;
• Владелец — форма-владелец; от неё зависит, кому придёт оповещение о выборе и кто будет заблокирован при модальном открытии;
• Уникальность — произвольное значение; если форма с таким ключом уникальности уже открыта, вместо новой формы активируется существующая;
• ОписаниеОповещенияОЗакрытии — обработчик, который вызовется после закрытия формы и получит возвращённое значение.

Типовой пример с владельцем и оповещением:

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

ОткрытьФорму("Справочник.Контрагенты.Форма.ФормаВыбора", ПараметрыФормы,
ЭтотОбъект, , , , Оповещение, РежимОткрытияОкнаФормы.БлокироватьОкноВладельца);

Стандартные параметры, которые обрабатывает платформа

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

Пример открытия списка номенклатуры с отбором по поставщику и позиционированием:

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

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

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

Как принять параметры в открываемой форме

На стороне открываемой формы параметры доступны через объект Параметры в обработчике ПриСозданииНаСервере. Именно здесь принято читать произвольные параметры и настраивать форму: менять заголовок, скрывать элементы, заполнять реквизиты.

&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)

Если Параметры.Свойство("Организация") Тогда
ОрганизацияОтбор = Параметры.Организация;
КонецЕсли;

Если Параметры.Свойство("РежимТолькоПросмотр")
И Параметры.РежимТолькоПросмотр = Истина Тогда
ЭтотОбъект.ТолькоПросмотр = Истина;
КонецЕсли;

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

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

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

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

Передача значений заполнения для нового объекта

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

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

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

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

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

Способы заполнения нового объекта

ЗначенияЗаполнения

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

Основание

Использует типовой механизм ввода на основании. Надёжно в типовых конфигурациях, но заполнение идёт строго по предопределённым правилам.

Программное создание и запись

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

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

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

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

&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)

Если Параметры.Свойство("ДатаНачала") Тогда
ЭлементОтбора = Список.Отбор.Элементы.Добавить(Тип("ЭлементОтбораКомпоновкиДанных"));
ЭлементОтбора.ЛевоеЗначение = Новый ПолеКомпоновкиДанных("Дата");
ЭлементОтбора.ВидСравнения = ВидСравненияКомпоновкиДанных.БольшеИлиРавно;
ЭлементОтбора.ПравоеЗначение = Параметры.ДатаНачала;
ЭлементОтбора.Использование = Истина;
КонецЕсли;

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

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

Уникальность формы и повторное открытие

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

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

ОткрытьФорму("Обработка.АнализОстатков.Форма.ФормаОтчета", ПараметрыФормы,
ЭтотОбъект, Новый УникальныйИдентификатор);

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

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

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

Форма открылась без ошибок

Норма

Нет сообщений о несериализуемых данных или отсутствующих параметрах

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

Ошибка передачи данных между клиентом и сервером или обращение к несуществующему полю структуры

Параметры применились

Норма

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

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

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

Открытие из всех точек вызова

Норма

Форма корректно работает и из вашей кнопки, и из стандартной команды интерфейса

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

При стандартном открытии возникает ошибка из-за отсутствия ожидаемых параметров

Повторное открытие

Норма

Поведение соответствует замыслу: либо активируется та же форма, либо открывается новая

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

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

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

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

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

&НаКлиенте
Процедура ПослеЗакрытияПодбора(Результат, ДополнительныеПараметры) Экспорт
Если Результат <> Неопределено Тогда
ЗаполнитьТабличнуюЧасть(Результат);
КонецЕсли;
КонецПроцедуры

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

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

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

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

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

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

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

Почему параметр Отбор не применяется в форме списка?

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

Как открыть форму с параметрами из внешней обработки?

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

Чем отличается ЗначенияЗаполнения от Основания?

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

Как запретить пользователю отключать переданный отбор?

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