Как программно добавить команду в командную панель формы 1С

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

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

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

Как устроена связка «команда — кнопка — обработчик»

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

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

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

Пошаговое создание команды и кнопки

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

&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)

// 1. Создаём команду
НоваяКоманда = ЭтаФорма.Команды.Добавить("ПоказатьОстатки");
НоваяКоманда.Заголовок  = "Остатки";
НоваяКоманда.Подсказка  = "Показать остатки по выбранной номенклатуре";
НоваяКоманда.Действие   = "Подключаемый_ПоказатьОстатки";
НоваяКоманда.Картинка   = БиблиотекаКартинок.Информация;
НоваяКоманда.Отображение = ОтображениеКнопки.НадписьКартинка;

// 2. Добавляем кнопку в командную панель формы
НоваяКнопка = ЭтаФорма.Элементы.Добавить("КнопкаПоказатьОстатки",
Тип("КнопкаФормы"), ЭтаФорма.КоманднаяПанель);
НоваяКнопка.ИмяКоманды = "ПоказатьОстатки";

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

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

&НаКлиенте
Процедура Подключаемый_ПоказатьОстатки(Команда)

ПоказатьПредупреждение(, "Команда выполнена");

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

1. 1
   Откройте модуль формы и найдите или создайте обработчик ПриСозданииНаСервере
2. 2
   Добавьте команду через ЭтаФорма.Команды.Добавить() и заполните Заголовок, Действие, Картинку
3. 3
   Добавьте кнопку через ЭтаФорма.Элементы.Добавить() с типом КнопкаФормы, указав родителем нужную командную панель
4. 4
   Свяжите кнопку с командой через свойство ИмяКоманды
5. 5
   Создайте клиентскую процедуру-обработчик с именем, указанным в свойстве Действие
6. 6
   Запустите форму в режиме предприятия и проверьте появление и работу кнопки

Размещение кнопки в разных командных панелях

Третий параметр метода Элементы.Добавить() определяет родителя кнопки. Если его не указать, кнопка попадёт в корень формы и может не отображаться ожидаемым образом. Для командной панели таблицы родителем должна быть именно её панель.

// Кнопка в командной панели табличной части "Товары"
КнопкаТаблицы = ЭтаФорма.Элементы.Добавить("КнопкаЗаполнить",
Тип("КнопкаФормы"), ЭтаФорма.Элементы.Товары.КоманднаяПанель);
КнопкаТаблицы.ИмяКоманды = "ЗаполнитьТовары";

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

Если командная панель элемента не создана в конфигураторе, обращение к Элементы.Товары.КоманднаяПанель всё равно корректно: у таблицы формы командная панель существует всегда, просто может быть скрыта. Проверьте свойство АвтоЗаполнение и видимость панели, если кнопка не появилась.

Передача параметров и вызов серверной логики

Обработчик команды получает единственный параметр — саму команду. Дополнительные данные удобно хранить в реквизитах формы или читать из текущих данных: Объект.Ссылка, Элементы.Товары.ТекущиеДанные и т.п.

Если действие требует обращения к базе — запроса, записи, получения остатков — из клиентского обработчика вызовите серверную процедуру. Типовой шаблон выглядит так:

&НаКлиенте
Процедура Подключаемый_ПоказатьОстатки(Команда)

ТекДанные = Элементы.Товары.ТекущиеДанные;
Если ТекДанные = Неопределено Тогда
Возврат;
КонецЕсли;

Остаток = ПолучитьОстатокНаСервере(ТекДанные.Номенклатура);
ПоказатьОповещениеПользователя("Остаток: " + Остаток);

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

&НаСервереБезКонтекста
Функция ПолучитьОстатокНаСервере(Номенклатура)
// запрос к регистру остатков
Возврат 0;
КонецФункции

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

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

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

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

Маршрут решения

Как выбрать действие

Кнопка зависит от роли пользователя или функциональной опцииПроверяйте условие в ПриСозданииНаСервере и не создавайте команду вовсе

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

Кнопка нужна только для определённого вида документа или операцииПроверяйте вид объекта на сервере до добавления команды

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

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

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

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

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

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

Отображение кнопки

Норма

Кнопка видна в нужной командной панели с заданным заголовком

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

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

Нажатие кнопки

Норма

Выполняется клиентский обработчик без сообщений об ошибке

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

Ошибка «Процедура или функция не обнаружена»

Повторное открытие формы

Норма

Форма открывается без ошибок дублирования

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

Ошибка «Элемент с таким именем уже существует»

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

Норма

Под пользователем без нужных прав кнопка отсутствует

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

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

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

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

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

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

Сравнение вариантов

Команда в конфигураторе

Подходит для постоянного набора команд; видна в редакторе формы, не требует кода. Не подходит для динамических условий

Программное добавление в ПриСозданииНаСервере

Подходит для команд, зависящих от прав, вида объекта, настроек. Требует аккуратности с уникальностью имён

Общая команда конфигурации

Подходит для действий, доступных из разных форм и разделов. Не размещается в произвольной командной панели конкретной формы

Расширение конфигурации

Подходит для доработки типовых форм без изменения конфигурации. Зависит от стабильности имён элементов типовой формы

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

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

Да, коллекции Команды и Элементы доступны в любом серверном обработчике формы, пока она открыта. Однако делать это стоит обоснованно: каждое изменение структуры формы вызывает её перерисовку на клиенте. Для управления доступностью в процессе работы обычно достаточно менять свойства Видимость и Доступность уже созданной кнопки.

Почему кнопка появилась, но при нажатии ошибка «Процедура не обнаружена»?

Почти всегда причина в том, что процедура-обработчик объявлена с директивой &НаСервере или её имя не совпадает со значением свойства Действие команды. Действие команды формы ищется только среди клиентских процедур модуля формы. Проверьте директиву компиляции и посимвольно сравните имена.

Как добавить кнопку в подменю «Ещё» командной панели?

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

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

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

Работает ли этот способ в формах, доработанных расширением?

Работает. В модуле формы расширения доступны те же коллекции Команды и Элементы. Главный риск — изменение имён элементов в основной конфигурации после её обновления, поэтому обращения к элементам заимствованной формы стоит сопровождать проверками на Неопределено.

Как удалить программно добавленную команду?

Используйте ЭтаФорма.Команды.Удалить() с найденной командой и ЭтаФорма.Элементы.Удалить() для кнопки — удалять нужно оба объекта. На практике удаление требуется редко: чаще достаточно скрыть кнопку через свойство Видимость, что дешевле по производительности и безопаснее для стабильности формы.