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

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

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

Какой тип команды выбрать

Сначала решите, где кнопка должна быть видна. От этого зависит тип команды.

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

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

Что нужно знать до начала

• Форма должна быть управляемой. В обычных формах (старый тонкий клиент «Обычное приложение») кнопки устроены иначе, там своя панель.
• У вас должны быть права на изменение конфигурации. Без них пункт «Конфигуратор» при запуске не откроется.
• Если конфигурация типовая и стоит на поддержке, включите возможность изменения: Конфигурация → Поддержка → Настройка поддержки.

Создание команды формы по шагам

Разберём типичный случай: на форме документа нужна кнопка, которая что-то делает с данными документа.

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

Хорошее имя команды сразу объясняет, что она делает: ЗаполнитьПоШаблону, а не Команда1. Через полгода вы сами скажете спасибо.

Дополнительные свойства команды

• Подсказка показывается при наведении курсора. Пишите коротко: что произойдёт после нажатия.
• Картинка подбирается из библиотеки стандартных картинок или загружается своя.
• Отображение: только картинка, только текст или оба.
• Сочетание клавиш задаётся в свойстве команды. Не занимайте комбинации, которые платформа уже использует (например, Ctrl+S).
• Функциональные опции привязывают команду к настройке программы: кнопка появляется, только когда опция включена.

Размещение кнопки на форме и в командной панели

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

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

Откройте вкладку «Элементы». Перетащите команду из вкладки «Команды» в нужное место: в командную панель формы либо прямо в группу элементов. Платформа создаст кнопку и подставит CommandName сама.

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

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

Если кнопок много, сгруппируйте их. Для этого создайте элемент Группа — Командная панель или Всплывающая группа (выпадающий список «Ещё», «Заполнить»). Так форма не превращается в ряд из десяти одинаковых прямоугольников.

Свойства кнопки, которые часто забывают

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

Общая команда: кнопка в разделе или панели навигации

Когда действие нужно из разных мест, создайте общую команду.

1. В дереве метаданных откройте Общие → Общие команды, нажмите «Добавить».
2. Задайте имя и синоним. Синоним видит пользователь.
3. В свойстве «Группа» выберите, где команда появится: панель навигации раздела, командная панель раздела, панель действий формы.
4. «Тип параметра команды» задайте, если команда работает с выбранным объектом. Например, указав ДокументСсылка.РеализацияТоваровУслуг, вы сделаете команду доступной в формах этого документа.
5. Откройте «Модуль команды». Там будет процедура ОбработкаКоманды(ПараметрКоманды, ПараметрыВыполненияКоманды).
6. Подключите команду к нужному разделу: Подсистемы → ваша подсистема → Состав (для панели навигации).

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

Код обработчика нажатия

Платформа сама создаёт заготовку. Вам остаётся наполнить её содержанием.

Простейший вариант на клиенте

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

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

Вызов сервера

Чтение и запись в базу выполняйте на сервере. Схема из двух процедур:

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

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

Клиентская процедура только запускает серверную. Серверная меняет данные и возвращает их в форму через ЗначениеВРеквизитФормы.

Что не нужно делать

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

Открыть другую форму по кнопке

Для кнопки «Открыть отчёт» или «Создать связанный документ» достаточно одной строки:

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

Имя формы бывает в дереве метаданных в ветке Отчёты → МойОтчет → Формы. Если форм несколько, платформа покажет выбор формы по умолчанию.

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

Добавили кнопку и проверили у себя — всё работает. А у кассира она не видна. Причина обычно в правах или в условиях видимости.

Права ролей

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

Для команды формы права нет: её видимость определяют права на сам объект и условия на форме.

Видимость и доступность на форме

У элемента «Кнопка» есть свойства Видимость и Доступность. Их можно менять из кода:

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

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

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

Если вы пользователь, а не разработчик

Нужную кнопку можно вывести без Конфигуратора. В режиме 1С:Предприятие откройте форму и нажмите Ещё → Изменить форму (или значок шестерёнки). Откроется настройка, где доступные команды можно добавить в панель. Эти изменения хранятся в вашем профиле и не затрагивают других пользователей.

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

Кнопка добавлена, права выданы. Теперь убедитесь, что она работает так, как задумано.

Запуск для проверки

1. Нажмите F5 (или Отладка → Начать отладку). Откроется клиент с вашей базой.
2. Найдите форму и убедитесь, что кнопка на месте и подпись читается.
3. Нажмите её и проверьте результат.

Точки останова

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

Если процедура не вызывается вообще, проверьте три вещи:

• в свойстве «Действие» команды указано имя процедуры;
• у кнопки выбрана нужная команда (Имя команды);
• процедура имеет директиву &НаКлиенте или &НаСервере, и параметр Команда.

Типичные причины «не работает»

Тестирование на разных пользователях

Запустите базу под пользователем с обычной ролью, а не только под администратором. У администратора всё видно, и вы не заметите проблему с правами. Создайте тестового пользователя (Администрирование → Пользователи) и проверьте кнопку от его имени.

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

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

Порядок такой:

1. В Конфигураторе: Конфигурация → Расширения конфигурации → Добавить.
2. Создайте расширение и «заимствуйте» нужную форму: правой кнопкой по объекту в расширении, пункт «Добавить в расширение» (заимствование).
3. Добавьте команду и кнопку в заимствованную форму так же, как описано выше.
4. Обработчик помещайте в модуль расширения, а перехват событий делайте через директивы &После, &Перед, &Вместо.
5. Нажмите F7 и загрузите расширение (.cfe) в рабочую базу отдельным шагом: загрузка файла и обновление конфигурации БД — разные действия.

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

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