Параметры формы в 1С: что это и как с ними работать

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

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

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

Что такое параметры формы и зачем они нужны

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

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

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

Как передать параметры при открытии формы

Стандартный способ — метод глобального контекста ОткрытьФорму. Вторым аргументом ему передаётся структура с параметрами. Типичный вызов выглядит так:

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

ОткрытьФорму("Справочник.ДоговорыКонтрагентов.ФормаВыбора", ПараметрыФормы, ЭтотОбъект);

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

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

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

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

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

&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)
Если Параметры.Свойство("ОрганизацияОтбор") Тогда
УстановитьОтборПоОрганизации(Параметры.ОрганизацияОтбор);
КонецЕсли;
КонецПроцедуры

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

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

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

Объявление параметров формы в конфигураторе

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

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

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

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

Часть имён параметров зарезервирована платформой и обрабатывается автоматически, без кода в ПриСозданииНаСервере. Знание этих имён избавляет от лишней разработки.

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

Типичные сценарии использования

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

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

Передача контекста в отчёт

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

Открытие формы в режиме только просмотр

Когда форму нужно показать без возможности редактирования, передают собственный параметр, например ТолькоПросмотрДанных, и в ПриСозданииНаСервере устанавливают ЭтотОбъект.ТолькоПросмотр = Истина или блокируют отдельные элементы. Стандартного параметра «только просмотр» у произвольных форм нет, поэтому логика реализуется вручную.

Ограничения и типичные ошибки

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

Второе ограничение — время жизни. Как уже отмечено, свойство Параметры актуально только при создании формы. Частая ошибка новичков — обращение к Параметры.ИмяПараметра в обработчике команды формы, что приводит к ошибке исполнения.

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

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

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

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

Частые вопросы о параметрах формы