Кнопка на форме 1С 8.3: команда, размещение и обработчик

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

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

Статья написана для платформы 8.3 с интерфейсом «Такси» и управляемых форм. Обычные формы (режим «Обычное приложение») устроены иначе и здесь не разбираются.

Что нужно решить до первой кнопки

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

1. Где будет кнопка. В командной панели формы, внутри группы на самой форме или рядом с полем.
2. Что она делает. Открывает другую форму, считает что-то, меняет данные документа, печатает.
3. Где выполняется действие. На клиенте (интерфейс, открытие форм, вопросы пользователю) или на сервере (запросы, запись в базу).

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

Три способа добавить кнопку

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

Создание команды формы в Конфигураторе

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

В редакторе четыре закладки: «Элементы», «Реквизиты», «Команды» и «Параметры». Нужна «Команды».

Добавление команды

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

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

Свойства команды, которые стоит заполнить сразу

• ✏️ Действие — имя процедуры-обработчика. Заполним на следующем шаге.
• 🖼️ Картинка — значок из библиотеки картинок или своя.
• 👁️ Отображение — только текст, только картинка или картинка вместе с текстом. Для плотной панели часто берут картинку с подсказкой.
• ⌨️ Сочетание клавиш — если действие частое.
• 🔌 Использование — привязка к функциональным опциям: команда исчезнет, если опция выключена.

Привязка обработчика к команде

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

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

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

Имя процедуры совпадает с именем команды, если вы не меняли его вручную. Параметр Команда обычно не используют, но убирать его нельзя.

Пример: клиент вызывает сервер

Допустим, нужно заполнить табличную часть документа по шаблону. Работа с данными идёт на сервере, а клиент только запускает её и сообщает результат.

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

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

Здесь ЗаполнитьПоШаблону() — метод модуля объекта, который вы написали сами. Схема «объект на сервер и обратно» нужна, потому что данные формы на клиенте и на сервере хранятся отдельно, а ЗначениеВРеквизитФормы возвращает результат в форму.

⚠️ Не вызывайте из клиентской процедуры запросы и методы, которые доступны только на сервере. Конфигуратор покажет ошибку при проверке модуля, а в работе получите «Метод объекта не обнаружен ».

Если обработчик ничего не меняет в данных, а только открывает форму, серверная часть не нужна:

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

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

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

Способ 1. Перетащить команду на закладку «Элементы»

1. Откройте закладку «Элементы». Вы увидите дерево: корневой элемент формы и его командную панель.
2. В нижней части окна редактора (или на закладке «Команды») найдите свою команду.
3. Перетащите её мышью в нужное место дерева.

Платформа создаст элемент «Кнопка» и сама заполнит в нём свойство «Имя команды».

Способ 2. Создать кнопку и выбрать команду

1. На закладке «Элементы» выделите группу, в которую хотите поместить кнопку.
2. Нажмите «Добавить» и выберите кнопку.
3. В свойствах кнопки найдите Имя команды и выберите из списка свою команду. Команды формы в списке идут с приставкой Форма..

Куда ставить кнопку

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

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

В свойствах кнопки доступны:

• Вид — обычная кнопка, гиперссылка или кнопка командной панели.
• Ширина и Высота — для кнопок вне командной панели.
• Цвет и шрифт — если нужно выделить главное действие.
• Отображение — как выше, текст и/или картинка.

Порядок кнопок и группы

Кнопки в панели идут в том порядке, в каком стоят в дереве «Элементы». Двигайте их стрелками «Вверх» и «Вниз» или перетаскиванием. Частые команды ставьте левее, редкие уводите в подменю.

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

Проверить результат можно сразу. Запустите «1С:Предприятие» из Конфигуратора (меню «Отладка → Начать отладку»), откройте форму и нажмите кнопку. Остановитесь на первой строке обработчика, чтобы убедиться, что он вызывается.

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

Обычно кнопка нужна не всегда. Например, «Заполнить по шаблону» не нужна в проведённом документе. Для этого у элемента есть два свойства:

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

Выбор простой: если пользователь не должен даже знать о команде, скрывайте. Если важно показать, что команда существует, но сейчас недоступна, делайте недоступной.

Управление из кода

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

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

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

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

Права и роли

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

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

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

Править типовую форму напрямую можно, но обновление релиза потом превратится в ручное сравнение. Надёжнее расширение.

1. В Конфигураторе откройте меню «Конфигурация → Расширения конфигурации ».
2. Создайте новое расширение и задайте имя.
3. Добавьте в него нужный объект: «Добавить в расширение» на объекте.
4. Откройте форму из расширения. Она перенесётся в «заимствованном» виде.
5. Добавьте команду и кнопку так же, как описано выше.

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

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

Кнопка без Конфигуратора

Если команда уже есть в программе, а на форме её нет, программисту не нужен. Пользователь с правом настройки может добавить её сам:

1. Откройте нужную форму.
2. В командной панели выберите «Ещё», затем «Изменить форму».
3. В открывшемся окне нажмите «Добавить» и выберите из списка существующую команду.
4. Расположите её в панели и подтвердите настройку.

Этот способ создаёт только ссылку на готовую команду. Своего кода так не добавить. Настройка сохраняется для пользователя, а при необходимости её можно сбросить кнопкой «Установить стандартную настройку».

Если кнопка не появилась или не работает

Проверьте по порядку.

• 🔍 Кнопки нет на форме. Откройте закладку «Элементы» и посмотрите, есть ли элемент. Часто команду создали, а на форму не перетащили. Проверьте также свойство «Видимость» и привязку к функциональной опции.
• 🚫 Кнопка серая. Смотрите «Доступность» и код, который её меняет. Серой кнопка бывает и при просмотре формы, открытой только для чтения.
• 💥 Нажатие ничего не делает. Откройте свойства команды и убедитесь, что в поле «Действие» стоит имя процедуры. Без него команда ничего не запускает.
• ❗ Ошибка «Процедура или функция не обнаружена». Процедура в модуле есть, но без директивы &НаКлиенте или с другим именем. Директива над обработчиком обязательна.
• 🧩 Кнопка в расширении исчезла после обновления. Проверьте, что расширение подключено и «Обновить конфигурацию базы данных» выполнено.

Чтобы быстро найти причину, запустите в Конфигураторе «Конфигурация → Проверка конфигурации» и отметьте проверку модулей. Ошибки контекста клиент-сервер видны сразу.

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