Параметризуемые команды в 1С 8.3: как добавить и настроить

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

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

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

Что такое параметризуемая команда и когда она нужна

У любой команды в конфигураторе есть свойство «Тип параметра команды». Если оно пустое — команда обычная, непараметризуемая. Если указан тип, например ДокументСсылка.РеализацияТоваровУслуг или составной тип из нескольких ссылок, команда становится параметризуемой.

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

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

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

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

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

Ключевое свойство — «Режим использования параметра». Значение «Одиночный» означает, что команда получает одну ссылку. Значение «Множественный» позволяет передать массив выделенных в списке объектов — так работают групповые команды, например групповая печать выделенных документов.

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

Как написать обработчик команды

Обработчик размещается в модуле команды. Платформа вызывает процедуру ОбработкаКоманды с двумя параметрами: ПараметрКоманды — переданное значение (ссылка или массив ссылок) и ПараметрыВыполненияКоманды — структура с данными об источнике вызова, включая ссылку на форму-источник.

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

Пример выше — ввод на основании: команда открывает форму нового документа и передаёт в неё ссылку на основание. Документ-основание попадёт в обработчик ОбработкаЗаполнения создаваемого объекта, если у него в свойстве «Вводится на основании» указан соответствующий тип.

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

Где появится команда и как управлять её видимостью

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

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

Если команда не появилась, чаще всего тип параметра не совпадает с типом объекта формы. Например, у команды указан ДокументСсылка.ЗаказКлиента, а вы ищете её в форме справочника. Также проверьте, что конфигурация базы данных обновлена, а не только сохранена конфигурация поставщика.

Практические сценарии использования

Печать документа

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

Создание на основании

Команда с типом параметра «документ-основание» открывает форму нового объекта и передаёт ссылку. Заполнение выполняется в ОбработкаЗаполнения создаваемого документа. Это стандартный и самый надёжный способ связки документов в цепочку.

Открытие отчёта с отбором

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

Ограничения и альтернативы

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

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

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