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

Чтобы добавить кнопку в конфигураторе 1С 8.3, сначала создают команду, а уже потом кнопку, которая на неё ссылается. Откройте форму в редакторе, на вкладке Команды добавьте команду формы, создайте для неё обработчик в модуле и перетащите команду в дерево Элементы — в командную панель или в любую группу. Кнопка без команды на управляемой форме ничего не делает.

Если команда нужна сразу в нескольких местах — в панели навигации раздела, в списке документов и в самом документе, — вместо команды формы создают общую команду в ветке Общие → Общие команды. Для типовых конфигураций (Бухгалтерия, ЗУП, УТ) всё это лучше делать в расширении, а не в основной конфигурации: так кнопка переживёт обновление релиза.

Что подготовить и где найти нужную форму

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

Как найти форму:

1. 🔍 Откройте дерево конфигурации (Конфигурация → Открыть конфигурацию).
2. 🔍 Встаньте в дерево и наберите имя объекта на клавиатуре — сработает быстрый поиск по дереву. Например, ПоступлениеТоваровУслуг.
3. 📂 Раскройте объект, ветку Формы и откройте нужную форму двойным щелчком. Форма документа обычно называется ФормаДокумента, списка — ФормаСписка, но в типовых бывают свои имена.
4. 🧭 Не уверены, та ли форма? В пользовательском режиме откройте форму и посмотрите её имя через Ещё → Изменить форму или режим отладки. Проще всего — поставить точку останова в ПриСозданииНаСервере кандидата и открыть форму.

Перед правкой рабочей базы сделайте выгрузку Администрирование → Выгрузить информационную базу (файл .dt) или работайте в копии.

Как создать команду для кнопки и задать её свойства

В редакторе формы справа вверху есть вкладки Реквизиты, Команды, Параметры. Нужна вкладка Команды, раздел Команды формы.

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

Свойства, которые стоит знать:

• 🖼 Картинка — иконка из общих картинок или библиотеки платформы.
• 🔤 Отображение — только картинка, только текст или картинка и текст.
• 💬 Подсказка — всплывающий текст при наведении.
• ⌨️ Сочетание клавиш — например, Ctrl+Shift+F. Следите, чтобы не перекрыть стандартное.
• ✏️ Изменяет сохраняемые данные — если флажок стоит, команда становится недоступной, когда форма открыта только для просмотра. Для кнопки «Распечатать» его ставить не нужно, для «Заполнить» — нужно.
• 🧩 Функциональные опции — кнопка спрячется, если опция выключена в настройках программы.

Общая команда: что отличается

Общую команду создают в Общие → Общие команды. У неё другие ключевые свойства:

• Группа — куда команда встанет автоматически. Например, Панель навигации.Обычное, Панель действий.Создать, Командная панель формы.Важное.
• Тип параметра команды — тип объекта, к которому она относится (например, ДокументСсылка.РеализацияТоваровУслуг). Только при совпадении типа команда сама появится на формах этого документа.
• Режим использования параметра — Одиночный или Множественный. Во втором случае в обработчик придёт массив ссылок на все выделенные строки списка.

Размещение кнопки на форме

Команда создана, но на форме её ещё нет. Есть три способа вывести кнопку.

Перетаскиванием

Возьмите команду мышью на вкладке Команды и перетащите в дерево Элементы слева. Отпускайте на нужный узел:

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

Через добавление элемента

Выделите группу в дереве Элементы, нажмите добавление и выберите Кнопка. В свойстве ИмяКоманды укажите команду через выбор. Так удобнее, когда группа глубоко вложена.

Внешний вид кнопки

У элемента-кнопки свои свойства, независимые от команды:

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

Код обработчика: клиент и сервер

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

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

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

Модальный Вопрос() работает, только если в свойствах конфигурации разрешён режим использования модальности. В типовых конфигурациях он запрещён, поэтому там используют асинхронный вариант:

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

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

Правила, о которые спотыкаются чаще всего:

• 🖥 Обработчик команды формы всегда начинается на клиенте (&НаКлиенте). К базе из него не обратиться — нужен серверный вызов.
• 🔁 &НаСервере передаёт на сервер всю форму с реквизитами. Если реквизиты формы не нужны, берите &НаСервереБезКонтекста — вызов легче.
• 🚫 Из &НаСервереБезКонтекста нельзя читать Объект и Элементы: передавайте нужные значения параметрами.

Обработчик общей команды

В модуле общей команды заготовка другая:

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

Кнопка, добавленная программно

Иногда кнопку создают кодом — например, когда нельзя трогать форму. Это делается в ПриСозданииНаСервере:

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

&НаКлиенте
Процедура МояКомандаОбработка(Команда)
	Сообщить("Кнопка нажата");
КонецПроцедуры

Имя командной панели формы смотрите в дереве Элементы: в разных формах оно своё. Процедура-обработчик всё равно должна существовать в модуле формы.

Кнопка в типовой конфигурации через расширение

Для Бухгалтерии, ЗУП и УТ рабочий путь — расширение конфигурации . Расширения поддерживаются начиная с платформы 8.3.6.

1. Конфигурация → Расширения конфигурации → добавить новое расширение. Задайте имя и префикс, например Расш1_.
2. В основной конфигурации найдите форму, щёлкните правой кнопкой → Добавить в расширение. Форма появится в дереве расширения как заимствованная.
3. Откройте заимствованную форму. Добавьте команду, обработчик и кнопку теми же шагами, что описаны выше. Имена своих объектов начинайте с префикса — так их не спутать с типовыми.
4. Сохраните расширение и обновите его в базе (Конфигурация → Обновить конфигурацию базы данных в окне расширения).

Расширение можно выгрузить в файл .cfe и подключить в другой базе через Администрирование → Печатные формы, отчеты и обработки → Расширения без открытия конфигуратора.

Права доступа: кто увидит кнопку

Кнопка видна пользователю, только если у одной из его ролей есть права на команду и на объект, с которым она работает.

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

Для команды формы. Отдельного права в ролях нет. Ограничивают так:

• свойство команды Использование — по ролям: отметьте, каким ролям команда доступна;
• свойство кнопки Пользовательская видимость — по ролям, если кнопку нужно спрятать, но команду оставить доступной по горячей клавише;
• код в ПриСозданииНаСервере:

Элементы.ЗаполнитьПоОстаткам.Видимость = РольДоступна("ПолныеПрава");

В типовых конфигурациях с профилями групп доступа новую роль из расширения добавляют пользователям через Администрирование → Настройки пользователей и прав → Профили групп доступа.

Проверка и отладка новой кнопки

1. Сохраните конфигурацию и выполните Конфигурация → Обновить конфигурацию базы данных (F7). Если в изменённой структуре нет новых реквизитов, обновление пройдёт быстро и без монопольного режима.
2. Запустите отладку: Отладка → Начать отладку (F5).
3. В модуле формы поставьте точку останова на первой строке обработчика (F9).
4. Нажмите кнопку в пользовательском режиме. Выполнение остановится, и в табло можно посмотреть значения переменных, шагать по строкам F10 и F11.
5. Проверьте кнопку под обычным пользователем, а не под администратором. Права — самое частое место, где всё работает «у меня» и не работает у бухгалтера.

В клиент-серверной базе для отладки серверного кода на сервере 1С должна быть включена отладка. Если точка останова в процедуре &НаСервере не срабатывает, а клиентская срабатывает, причина обычно в этом — вопрос к администратору сервера.

Почему кнопка не появляется или не работает