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

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

Механизм состоит из трёх шагов: создание команды формы, добавление элемента формы типа «Кнопка» в нужную командную панель и привязка кнопки к команде с обработчиком. Всё это выполняется в модуле формы, обычно в обработчике ПриСозданииНаСервере.

Дальше разобраны конкретные примеры кода для управляемых форм, особенности работы с расширениями, типичные ошибки и способы проверить результат.

Общий принцип: команда, кнопка, обработчик

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

Родителем кнопки указывают командную панель формы (Элементы.КоманднаяПанель или другую, например панель табличной части). Все операции выполняются на сервере, потому что изменение состава элементов формы недоступно в клиентском контексте.

Пошаговый пример кода

Ниже минимальный рабочий пример для управляемой формы. Код размещается в модуле формы в обработчике ПриСозданииНаСервере.

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

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

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

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

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

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

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

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

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

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

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

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

Здесь Элементы.Товары — таблица формы, связанная с табличной частью. Если командная панель таблицы скрыта свойством «Автоотображение», кнопка может не появиться — проверьте свойство Отображение командной панели. Для обработки текущей строки в обработчике используют Элементы.Товары.ТекущиеДанные или ВыделенныеСтроки.

Добавление кнопки в расширении конфигурации

В расширениях 1С программное добавление кнопок — основной способ доработки типовых форм, потому что изменение заимствованной формы визуально ограничено. Код аналогичен, но есть нюансы: обработчик ПриСозданииНаСервере в расширении подключается через аннотацию &После или &ИзменениеИКонтроль.

&После("ПриСозданииНаСервере")
Процедура Расш1_ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)

НоваяКоманда = Команды.Добавить("Расш1_КомандаПечатьАкта");
НоваяКоманда.Действие  = "Расш1_ПечатьАкта";
НоваяКоманда.Заголовок = "Печать акта";

НоваяКнопка = Элементы.Добавить("Расш1_КнопкаПечатьАкта", Тип("КнопкаФормы"),
Элементы.КоманднаяПанель);
НоваяКнопка.ИмяКоманды = "Расш1_КомандаПечатьАкта";

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

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

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

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

Если РольДоступна("ПолныеПрава") Тогда
НоваяКоманда = Команды.Добавить("КомандаУтвердить");
НоваяКоманда.Действие  = "Подключаемый_Утвердить";
НоваяКоманда.Заголовок = "Утвердить";

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

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

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

Как выбрать подход

Кнопка нужна всем пользователям и всегдаДобавьте её в конфигураторе визуально — это проще и надёжнее

Кнопка зависит от роли, статуса или другого условия на момент открытияДобавляйте программно в ПриСозданииНаСервере с проверкой условия

Условие меняется уже после открытия формыСоздайте кнопку один раз и управляйте свойствами Видимость и Доступность

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

Как проверить результат и где искать ошибки

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

Ошибка «Процедура или функция с указанным именем не определена» при нажатии означает, что имя в свойстве Действие не совпадает с именем процедуры в модуле или процедура не экспортная в нужном контексте. Ошибка «Элемент с таким именем уже существует» возникает при повторном добавлении — например, если код выполняется дважды. В этом случае перед добавлением проверяйте наличие элемента: Если Элементы.Найти("КнопкаУтвердить") = Неопределено Тогда ....

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

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

Кнопка отображается в нужной командной панели

Норма

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

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

Кнопки нет — проверьте условие добавления и видимость панели

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

Норма

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

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

Ошибка о ненайденной процедуре — сверьте имя в свойстве Действие

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

Норма

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

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

Ошибка «элемент уже существует» — добавьте проверку Элементы.Найти()

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

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

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

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

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

Можно ли добавить кнопку программно в обычной (не управляемой) форме?

Да, но механизм другой: в обычных формах используется коллекция ЭлементыФормы.КоманднаяПанель.Кнопки.Добавить() с указанием типа кнопки и действия через объект Действие. Обычные формы встречаются только в старых конфигурациях на платформе 8.2–8.3 в режиме совместимости.

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

Сначала программно создайте элемент типа ПодменюФормы с родителем — командной панелью, а затем добавляйте кнопки, указывая родителем это подменю. Заголовок подменю задаётся его свойством Заголовок.

Почему кнопка появляется, но не нажимается (неактивна)?

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

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

Используйте Элементы.Удалить(Элементы.ИмяКнопки) в серверном контексте, предварительно убедившись, что элемент существует. Команду при необходимости удаляют через Команды.Удалить(). На практике чаще просто скрывают кнопку через свойство Видимость.

Можно ли назначить кнопке картинку?

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

Работает ли этот способ в мобильном клиенте и веб-клиенте?

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