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

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

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

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

Что такое общая команда и когда она нужна

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

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

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

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

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

Далее заполните свойства в палитре свойств. Минимально важные: «Тип параметра команды», «Группа» (куда поместить кнопку в командной панели), «Картинка» и «Отображение» (автоматически, картинка, надпись или оба варианта). Свойство «Режим использования параметра» определяет, передаётся одна ссылка или массив выделенных в списке элементов.

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

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

Настройка типа параметра и режима использования

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

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

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

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

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

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

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

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

Добавление кнопки на форму вручную

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

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

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

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

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

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

Ограничения и альтернативные подходы

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

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

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

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