Кнопка на командной панели управляемой формы: команда, обработчик, размещение

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

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

Что понадобится до начала работы

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

• 🔑 доступ к конфигурации в режиме конфигуратора, то есть права разработчика;
• 🧩 форма принадлежит вашей собственной конфигурации или вашему расширению;
• 🗂 вы знаете, на какой форме нужна кнопка: форма документа, форма списка, форма элемента справочника или обработки.

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

Из чего состоит командная панель формы

В редакторе управляемой формы слева вверху находятся вкладки. Нас интересуют две:

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

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

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

Пошагово: как добавить кнопку в командную панель

1. Создайте команду

1. Откройте нужную форму в конфигураторе: двойной щелчок по объекту, затем ветка Формы, затем сама форма.
2. Перейдите на вкладку Команды и нажмите кнопку Добавить.
3. Задайте имя — без пробелов, понятное, например ЗаполнитьПоШаблону.
4. Заполните заголовок — то, что увидит пользователь на кнопке: «Заполнить по шаблону».
5. Для подсказки заполните свойство Подсказка: текст всплывает при наведении курсора.

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

2. Назначьте обработчик

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

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

&НаКлиенте
Процедура ЗаполнитьПоШаблону(Команда)
	// действия по нажатию кнопки
КонецПроцедуры

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

&НаКлиенте
Процедура ЗаполнитьПоШаблону(Команда)
	ЗаполнитьПоШаблонуНаСервере();
	Оповестить("Заполнено");
КонецПроцедуры

&НаСервере
Процедура ЗаполнитьПоШаблонуНаСервере()
	Объект.Товары.Очистить();
	Строка = Объект.Товары.Добавить();
	Строка.Количество = 1;
КонецПроцедуры

Пример нарочно простой: очистка табличной части и одна новая строка. Подставьте свою логику.

3. Выведите команду кнопкой на форму

Команда без кнопки пользователю не видна. Перейдите на вкладку Элементы и выделите нужную командную панель. Затем:

1. Нажмите Добавить над деревом элементов и выберите Кнопку формы.
2. Откроется палитра свойств новой кнопки. В свойстве ИмяКоманды выберите вашу команду из списка: имя она получает вида Форма.Команда.ЗаполнитьПоШаблону.
3. Дайте кнопке имя элемента, например ЗаполнитьПоШаблонуКнопка. Заголовок подтянется из команды.
4. Проверьте свойство Вид: для командной панели нужна обычная кнопка или кнопка командной панели; гиперссылка в панели смотрится чужеродно.

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

4. Проверьте в тонком или веб-клиенте

Запустите 1С:Предприятие из конфигуратора в режиме отладки (F5). Откройте форму, найдите кнопку, нажмите. Если обработчик не сработал, ошибка почти всегда на одном из двух шагов: команда не привязана к кнопке или в свойстве Действие пусто.

Как привязать действие к кнопке: варианты

Не всякая кнопка запускает свою процедуру. Есть три типа назначения:

Для открытия формы подойдёт такой обработчик:

&НаКлиенте
Процедура ОткрытьОтчет(Команда)
	ПараметрыФормы = Новый Структура("Контрагент", Объект.Контрагент);
	ОткрытьФорму("Отчет.ОтчетПоКонтрагенту.Форма", ПараметрыФормы, ЭтаФорма);
КонецПроцедуры

Имя формы отчёта здесь учебное. Подставьте имя реального объекта из своей конфигурации.

Видимость и доступность кнопки

Бывает, что кнопка нужна не всегда. Для проведённого документа «Заполнить» уже не нужна, для обычного пользователя «Выгрузить» — тем более. Платформа даёт два разных свойства.

• 👁 Видимость — кнопка есть на форме или её нет совсем.
• 🔒 Доступность — кнопка видна, но серая: нажать нельзя.

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

Оба свойства меняются программно. Обращение идёт к элементу формы, а не к команде:

&НаКлиенте
Процедура ПриОткрытии(Отказ)
	Элементы.ЗаполнитьПоШаблонуКнопка.Видимость = Не Объект.Проведен;
КонецПроцедуры

У проведённого документа реквизит Проведен вернёт Истина, поэтому кнопка скроется. Для нового документа она останется на панели.

Если условие зависит от данных, которые меняются при редактировании, подписывайтесь на событие формы ПриЧтенииНаСервере или на нужный обработчик изменения реквизита. Установка видимости один раз при открытии не отследит изменений.

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

Где разместить кнопку и как сгруппировать

В командной панели кнопки идут слева направо в том порядке, в каком стоят в дереве. Порядок меняют стрелками в редакторе или перетаскиванием.

Что стоит настроить:

1. Группа кнопок. Если кнопок три и больше, объедините их в группу вида «Группа — командная панель» или «Подменю». Подменю складывает команды в выпадающий список и освобождает место.
2. Расположение в командной панели. У кнопки есть свойство, определяющее, показывать её на самой панели, в дополнительном подменю или дать платформе решить автоматически. Для редких команд выбирайте дополнительное подменю.
3. Разделитель. Между логически разными блоками добавьте группу-разделитель, чтобы пользователь не путал «Записать» и ваше «Заполнить».
4. Кнопка по умолчанию. Для главной команды формы задайте свойство КнопкаПоУмолчанию: тогда её вызывает клавиша Enter в подходящем контексте.

Когда панель переполнена, платформа сама переносит лишние кнопки в меню Ещё. Это нормально и зависит от ширины окна. Самые нужные команды ставьте первыми, чтобы они не уходили в Ещё при узком окне.

Кнопка в командной панели таблицы

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

1. На вкладке Элементы найдите таблицу, например табличную часть Товары.
2. Раскройте её и выделите вложенный элемент командной панели таблицы.
3. Добавьте кнопку формы и привяжите к ней ту же или новую команду.

Обработчик для строки получает текущие данные через элемент таблицы:

&НаКлиенте
Процедура УстановитьКоличествоЕдиница(Команда)
	ТекущиеДанные = Элементы.Товары.ТекущиеДанные;
	Если ТекущиеДанные = Неопределено Тогда
		Возврат;
	КонецЕсли;
	ТекущиеДанные.Количество = 1;
КонецПроцедуры

Проверка на Неопределено обязательна: когда в таблице нет строк или ни одна не выбрана, ТекущиеДанные пусты, и обращение к полю вызовет ошибку.

Если кнопка должна работать сразу с несколькими выделенными строками, перебирайте коллекцию Элементы.Товары.ВыделенныеСтроки. Она хранит идентификаторы строк, по которым данные получают через Объект.Товары.НайтиПоИдентификатору(Идентификатор).

Контрольный список перед сдачей правки

Прежде чем отдавать форму пользователям, пройдите её руками:

Последний пункт часто забывают: разработчик работает с полными правами и не замечает, что у бухгалтера кнопка не видна или не срабатывает из-за ограничений на объект.

Типичные ошибки при добавлении кнопки

Три сбоя встречаются чаще всего.

Кнопка есть, нажатие ничего не даёт. Проверьте свойство Действие у команды. Платформа не ругается на пустое действие.

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

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

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

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