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

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

Ниже путь от пустой формы до рабочей кнопки с картинкой, условием видимости и проверкой прав. Все примеры для платформы 8.3 и управляемых форм, то есть для обычной разработки в Конфигураторе.

С чего начать: команда формы или общая команда

Выбор зависит от того, где кнопка должна появиться. Проще всего решить это до начала работы.

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

Шаг 1. Создаём команду формы

Откройте Конфигуратор, найдите нужный объект и откройте его форму двойным щелчком. Дальше по порядку:

1. В окне редактора формы перейдите на закладку «Команды».
2. Нажмите зелёный плюс («Добавить»). Появится строка новой команды.
3. В палитре свойств задайте «Имя»: латиницей или кириллицей без пробелов, например ЗаполнитьКомментарий. По имени команда подключается в коде и на форме.
4. В поле «Заголовок» впишите текст, который увидит пользователь: «Заполнить комментарий». Заголовок может содержать пробелы.
5. В свойстве «Действие» нажмите лупу. Платформа предложит создать процедуру обработчика на клиенте или на сервере. Для начала выбирайте клиент.
6. Задайте «Подсказку»: короткий текст, появляющийся при наведении курсора.

После выбора действия платформа сама создаст заготовку в модуле формы и откроет её. Имя процедуры совпадает с именем команды, параметр у неё один: Команда.

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

Шаг 2. Размещаем кнопку на форме

Сама по себе команда на форме не видна. Её надо вывести.

Способ 1: перетаскиванием. В левой части редактора формы откройте закладку «Элементы». Перетащите команду из закладки «Команды» на нужное место в дерево элементов. Платформа создаст кнопку, привязанную к команде.

Способ 2: через добавление элемента. Нажмите правой кнопкой на группу элементов, выберите «Добавить → Кнопка формы» и в свойстве «Имя команды» укажите нужную.

Куда её положить, решает задача:

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

Если кнопка стоит вне командной панели, у неё есть вид «Обычная кнопка». Внутри командной панели она работает как пункт панели, и платформа сама выбирает оформление.

Шаг 3. Пишем обработчик нажатия

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

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

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

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

Пример рассчитан на документ с реквизитами Контрагент (ссылка на справочник) и Комментарий (строка). Подставьте свои имена.

Что здесь важно:

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

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

Кнопка, которой нет в конфигураторе: создание из кода

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

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

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

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

Шаг 4. Видимость и доступность кнопок

Кнопка может быть скрыта (не видна совсем) или недоступна (видна, но серая). Это два разных свойства элемента: «Видимость» и «Доступность».

Задать их можно в палитре свойств в Конфигураторе, но чаще нужна логика: кнопка видна только для проведённого документа или только для определённой роли. Для этого меняют свойства элемента из кода:

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

Имя Элементы.ЗаполнитьКомментарий здесь указывает на кнопку, а не на команду. Замените имя документа в метаданных на свой объект.

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

Скрытая кнопка не защищает данные. Если пользователь получит доступ к форме иным путём (отчёт, другая команда), обработчик всё равно выполнится. Права проверяйте в коде и в ролях, а не только скрытием.

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

Шаг 5. Картинка и оформление кнопки

У команды есть свойство «Картинка». Нажмите «Выбрать», и платформа откроет библиотеку картинок. Подойдёт любая из стандартной библиотеки или своя из ветки «Общие → Картинки».

Как кнопка выглядит, задаёт свойство «Отображение»:

• 🎨 Авто: платформа выбирает сама.
• 🎨 Картинка: только значок. Хорошо для узких панелей, но пользователь без подсказки не поймёт, что это.
• 🎨 Текст: только заголовок.
• 🎨 Картинка и текст: вариант для заметных кнопок, которые нельзя перепутать.

Если у кнопки есть картинка, но её не видно, чаще всего причина в отображении «Текст» или в том, что кнопка лежит в подменю, где значки не выводятся.

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

Общая команда: кнопка сразу во многих формах

Если действие нужно в разных местах, создавать одну и ту же команду на десяти формах не надо. Откройте ветку «Общие → Общие команды» и добавьте новую.

Основные свойства:

1. «Группа»: где команда появится по умолчанию. Для панели навигации формы есть одно значение, для панели действий другое.
2. «Тип параметра команды»: объекты, к которым команда применима. Если оставить пустым, команда не привязана к объекту, как «Открыть справочник».
3. «Модуль команды»: процедура ОбработкаКоманды выполняется на клиенте, в нём и пишется действие.

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

Чтобы команда появилась в интерфейсе, включите её в состав подсистемы или отметьте её в форме через свойство «Командный интерфейс» / состав команд. Если команда есть, а на форме её нет, причина почти всегда в том, что она не добавлена ни в одну подсистему и не привязана к типу параметра.

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

Если кнопка не работает: частые причины

Большинство проблем сводится к нескольким сценариям. Проверяйте по порядку.

Две ловушки, которые встречаются постоянно:

• ⚠️ Обработчик с директивой &НаКлиенте пытается выполнить запрос к базе или обратиться к реквизиту через точку. Платформа не пустит. Перенесите работу в &НаСервере.
• ⚠️ После правки формы пользователь запускает старую копию конфигурации. Сохраните изменения кнопкой «Обновить конфигурацию базы данных» и перезапустите сеанс.

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