Как добавить на форму общую команду в 1С

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

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

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

Чем общая команда отличается от команды формы

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

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

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

Создание общей команды в конфигураторе

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

В палитре свойств новой команды обратите внимание на ключевые свойства:

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

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

Настройка типа параметра команды

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

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

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

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

Написание обработчика команды

Логика команды описывается в её модуле. Откройте палитру свойств команды и нажмите кнопку с изображением лупы у поля «Действие» либо перейдите на закладку «Модуль команды». Платформа создаст заготовку процедуры ОбработкаКоманды с двумя параметрами: ПараметрКоманды (ссылка или массив ссылок) и ПараметрыВыполненияКоманды (структура со сведениями об источнике вызова).

Типичный обработчик открывает другую форму, передавая в неё параметр. Пример — команда, открывающая отчет по движениям документа:

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

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

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

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

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

&НаКлиенте
Процедура ОбработкаКоманды(ПараметрКоманды, ПараметрыВыполненияКоманды)
	ПоказатьВопрос(Новый ОписаниеОповещения("ПослеВопроса", ЭтотОбъект, ПараметрКоманды), "Выполнить действие для " + ПараметрКоманды + "?", РежимДиалогаВопрос.ДаНет);
КонецПроцедуры

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

Размещение команды на форме и управление видимостью

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

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

Управление доступностью по правам

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

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

Проверка результата и типичные ошибки

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

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

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