Ключевой параметр формы в 1С: что это и как с ним работать

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

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

Что такое параметр формы и чем ключевой отличается от обычного

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

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

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

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

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

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

1. 1
   Откройте форму в конфигураторе и перейдите на закладку «Параметры»
2. 2
   Добавьте параметр или выберите существующий, задайте имя и тип
3. 3
   Откройте палитру свойств параметра и включите флажок «Ключевой»
4. 4
   Сохраните конфигурацию и проверьте повторное открытие формы с теми же значениями

Как передать ключевой параметр из кода

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

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

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

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

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

При вызове ОткрытьФорму() платформа строит ключ уникальности из имени формы и значений всех ключевых параметров. Если форма с таким ключом уже открыта, новое окно не создаётся — активируется существующее. Это удобно для обработок и отчётов: пользователь, дважды нажавший кнопку «Сверка по складу Х», получит одну и ту же форму, а не два одинаковых окна.

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

Стандартный ключевой параметр «Ключ» у форм объектов

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

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

Типичные ошибки при работе с ключевыми параметрами

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

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

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

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

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

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