Параметризованная команда 1С: что это и как ей пользоваться

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

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

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

Где в конфигурации находятся параметризованные команды

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

Ключевые свойства команды:

• Тип параметра команды — какие типы данных команда принимает в качестве параметра. Можно выбрать один тип (например, «ДокументСсылка.РеализацияТоваровУслуг») или составной тип из нескольких ссылок.
• Режим использования параметра — определяет, как формируется параметр: одиночное значение или множественный выбор.
• Обработчик — модуль, в котором пишется код, выполняемый при вызове команды.
• Группа команд — место размещения кнопки в командном интерфейсе формы.

Отдельно существуют глобальные команды (ветка «Общие» → «Общие команды»), которые не привязаны к объекту и работают без параметра. Их не следует путать с параметризованными: если команде нужен контекст вызова, она должна принадлежать объекту или иметь тип параметра.

Как работает передача параметра

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

Если в свойстве «Тип параметра команды» указано несколько типов, команда появится в формах списков и формах объектов всех этих типов. Например, команда «Печать накладной» с параметрами «РеализацияТоваровУслуг» и «ПередачаТоваров» будет доступна в обоих списках документов, а в обработчике тип параметра можно определить через функцию ТипЗнч().

Режим использования параметра имеет два значения:

• Одиночный — в обработчик передаётся одна ссылка, команда работает с одним объектом.
• Множественный — в обработчик передаётся массив ссылок, если пользователь выделил несколько строк в списке. Это удобно для групповой печати или пакетной обработки.

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

Создание параметризованной команды по шагам

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

1. 1
   Откройте в конфигураторе объект (документ) и перейдите на закладку «Команды»
2. 2
   Добавьте новую команду, задайте имя и синоним, например «ВзаиморасчетыПоДокументу»
3. 3
   В свойстве «Тип параметра команды» выберите ДокументСсылка.РеализацияТоваровУслуг
4. 4
   Установите режим использования параметра: одиночный или множественный
5. 5
   В поле «Обработчик» нажмите кнопку открытия — платформа создаст процедуру ОбработкаКоманды в модуле команды
6. 6
   Напишите код обработчика: открытие формы отчёта с передачей параметра
7. 7
   В свойстве «Группа» укажите место размещения кнопки в командной панели формы
8. 8
   Обновите конфигурацию базы данных и проверьте кнопку в форме списка документов

После создания обработчика платформа формирует процедуру с предопределённым параметром ПараметрКоманды. Внутри неё и пишется логика. Типовой код открытия формы с параметром выглядит так:

&НаКлиенте
Процедура ОбработкаКоманды(ПараметрКоманды, ПараметрыВыполненияКоманды)

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

ОткрытьФорму("Отчет.Взаиморасчеты.Форма",
ПараметрыФормы,
ПараметрыВыполненияКоманды.Источник,
ПараметрыВыполненияКоманды.Уникальность,
ПараметрыВыполненияКоманды.Окно);

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

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

Стандартные команды с параметром и открытие форм с отбором

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

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

Для собственных команд аналогичного эффекта добиваются передачей структуры отбора в параметры формы:

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

Способы использования параметра

Автоматический отбор (без кода)

Подходит для регистров, подчинённых регистратору, и стандартных переходов. Ограничение: работает только при совпадении типов связи.

Обработчик с ОткрытьФорму

Гибкий вариант: можно вычислить отбор, проверить права, задать уникальность окна. Требует написания клиентского кода.

Обработчик с серверным вызовом

Нужен, когда перед открытием формы требуется получить данные с сервера (проверки, расчёты). Медленнее из-за серверного вызова.

Размещение команды в интерфейсе

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

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

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

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

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

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

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

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

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

Проверка результата и FAQ

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

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

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

Кнопка в форме списка

Норма

Кнопка видна при выделенной строке, открывает форму с верным отбором

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

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

Работа с несколькими строками

Норма

При выделении нескольких строк обрабатываются все объекты

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

Обрабатывается только одна строка или возникает ошибка типа

Права пользователя

Норма

Команда выполняется под типовой ролью пользователя без ошибок доступа

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

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

Окно открытой формы

Норма

Форма открывается поверх формы-источника с корректной навигацией

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

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

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

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

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

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

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

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

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

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

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

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

Что делать, если при вызове команды возникает ошибка «Несоответствие типов»?

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