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

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

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

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

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

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

Имя формы задаётся строкой по иерархии метаданных: "Справочник.Номенклатура.Форма.ФормаЭлемента" — конкретная форма, созданная разработчиком, или "Справочник.Номенклатура.ФормаСписка" — форма по умолчанию. Если нужная форма не назначена основной, обращение по короткому имени вернёт исключение, поэтому надёжнее указывать полный путь с именем конкретной формы.

Базовый синтаксис выглядит так:

ОткрытьФорму("Справочник.Номенклатура.Форма.ФормаЭлемента",
ПараметрыФормы,
ЭтаФорма,           // владелец
Новый УникальныйИдентификатор, // ключ уникальности
,
,
ОписаниеОповещения  // обработчик закрытия
);

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

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

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

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

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

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

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

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

Открытие формы объекта и создание нового элемента

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

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

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

Для создания нового элемента с предзаполненными полями используют параметр ЗначенияЗаполнения:

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

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

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

Получение результата: формы выбора и оповещения

Когда открываемая форма должна вернуть значение — например, пользователь выбирает договор, и выбор надо подставить в текущий документ, — используют пару «описание оповещения + обработчик». Модальные вызовы в тонком и веб-клиенте по умолчанию запрещены, поэтому асинхронная модель является стандартом.

Оповещение = Новый ОписаниеОповещения("ПослеВыбораДоговора", ЭтотОбъект);

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

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

Обработчик объявляют в том же модуле с ключевым словом Экспорт, если он в общем модуле, и двумя параметрами: результат и дополнительные параметры:

&НаКлиенте
Процедура ПослеВыбораДоговора(Результат, ДопПараметры) Экспорт
Если Результат = Неопределено Тогда
Возврат; // пользователь отменил выбор
КонецЕсли;
Объект.Договор = Результат;
КонецПроцедуры

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

Альтернативные способы: ПолучитьФорму и ОткрытьЗначение

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

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

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

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

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

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

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

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

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

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

Быстрое открытие объекта по ссылке без параметров. Не позволяет передать отбор или обработчик.

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

Останавливает код до закрытия. Требует включённой модальности, не работает в веб-клиенте по умолчанию.

Ключ уникальности и управление окнами

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

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

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

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

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

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

Норма

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

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

Список полный или пустой при наличии данных — проверьте имена полей отбора

Повторное открытие того же объекта

Норма

Активируется уже открытое окно

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

Создаётся второе окно того же документа — не задан ключ уникальности

Возврат результата выбора

Норма

Обработчик оповещения срабатывает, значение подставляется

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

Обработчик не вызывается — проверьте имя процедуры и Экспорт

Типичные ошибки и их диагностика

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

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

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

Часто задаваемые вопросы

Как открыть форму и сразу установить текущую строку списка?

Передайте в параметрах ключ ТекущаяСтрока со ссылкой на нужный элемент: ПараметрыФормы.Вставить("ТекущаяСтрока", СсылкаНаЭлемент). После открытия список спозиционируется на указанной записи, если она попадает под установленный отбор.

Почему параметры не доходят до формы?

Проверьте, что в модуле формы в обработчике ПриСозданииНаСервере вы читаете значения через Параметры.ИмяПараметра, а сами параметры объявлены в редакторе формы на закладке «Параметры», если форма должна их типизировать. Необъявленные параметры доступны, но без контроля типов.

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

Нет. Открытие форм — клиентская операция, на сервере методы ОткрытьФорму и ПолучитьФорму недоступны. Серверная логика должна вернуть данные на клиент, а уже клиентский код открывает форму с этими данными.

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

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

Чем заменить ОткрытьФормуМодально в веб-клиенте?

Связкой ОписаниеОповещения и режимом открытия БлокироватьОкноВладельца или БлокироватьВесьИнтерфейс. Пользователь получает модальное поведение окна, а логика продолжения переносится в процедуру-обработчик, которая сработает после закрытия формы.

Как открыть внешнюю обработку программно?

Через ОткрытьФорму("ВнешняяОбработка.ИмяОбработки.Форма", Параметры) для подключённых обработок, либо сначала подключить файл через ВнешниеОбработки.Создать(ИмяФайла) в безопасном режиме, а затем открыть её форму по полученному имени. Учитывайте, что в клиент-серверном режиме путь к файлу должен быть доступен серверу.