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

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

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

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

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

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

Где размещать код создания кнопки

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

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

Пошаговое создание кнопки с обработчиком

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

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

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

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

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

// 3. Обработчик нажатия — имя совпадает со свойством Действие команды
&НаКлиенте
Процедура Подключаемый_ЗаполнитьПоУмолчанию(Команда)

ЗаполнитьПоУмолчаниюНаСервере();

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

&НаСервере
Процедура ЗаполнитьПоУмолчаниюНаСервере()
// Логика заполнения объекта
КонецПроцедуры

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

Обратите внимание на порядок: сначала команда, потом кнопка. Если создать кнопку и присвоить ей ИмяКоманды несуществующей команды, при открытии формы возникнет ошибка, и форма может не открыться вовсе.

Размещение кнопки в нужном месте формы

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

Чтобы вставить кнопку в конкретное место, а не в конец группы, используйте метод Элементы.Вставить() или свойство Элементы.Переместить() после добавления. Если нужной группы на форме нет, её тоже можно создать программно — типом Тип("ГруппаФормы") с видом ВидГруппыФормы.ГруппаКнопок.

Кнопка в командной панели динамического списка или табличной части

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

Настройка внешнего вида и поведения

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

Для важных кнопок полезны свойства КнопкаПоУмолчанию (срабатывает по Enter) и СочетаниеКлавиш у команды. Учтите: кнопкой по умолчанию на форме может быть только одна кнопка, и назначение горячих клавиш не должно конфликтовать со стандартными сочетаниями платформы.

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

Статическая кнопка в конфигураторе

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

Программное создание в модуле формы

Подходит, когда состав кнопок зависит от данных, прав или настроек. Требует аккуратности с именами и контекстом исполнения.

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

Подходит для доработки типовых форм без снятия с поддержки. Команды и элементы добавляются в расширении, обработчики подключаются через аннотации.

Типичные ошибки и их причины

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

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

Проверка результата и отладка

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

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

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

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

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

Норма

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

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

Кнопка в корне формы или отсутствует — проверьте родителя и вызов Элементы.Добавить()

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

Норма

Выполняется процедура-обработчик, точка останова срабатывает

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

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

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

Норма

Форма открывается без ошибок любое число раз

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

Ошибка о дублировании имени — добавьте проверку существования команды и элемента

FAQ

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

Да, через расширение конфигурации. В расширении заимствуется форма, в ней добавляется команда и кнопка (статически или программно в ПриСозданииНаСервере расширения), а обработчик объявляется в модуле расширения. Основная конфигурация при этом остаётся на поддержке.

Почему кнопка видна, но нажатие ничего не делает?

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

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

Весь код создания оберните в условие внутри ПриСозданииНаСервере: например, проверку права доступа, значения функциональной опции или статуса объекта. Если условие может измениться уже после открытия формы, создайте кнопку сразу и управляйте её свойством Видимость.

Можно ли удалить программно созданную кнопку?

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

Как назначить кнопке картинку из стандартного набора?

Установите свойство Картинка у команды или у самой кнопки, например: НоваяКоманда.Картинка = БиблиотекаКартинок.Заполнить. Затем задайте кнопке свойство Отображение со значением, включающим картинку, иначе изображение не будет показано.