Как добавить обработчик в 1С: форма, модуль объекта и подписки на события

Обработчик в 1С — это процедура или функция, которая выполняется при наступлении определённого события: открытии формы, записи документа, изменении реквизита, нажатии кнопки. Платформа вызывает такие процедуры автоматически, а задача разработчика — правильно разместить код в нужном модуле и выбрать подходящее событие.

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

Ниже разобраны все три подхода с примерами кода, условиями выбора и типичными ошибками. Материал ориентирован на конфигуратор 1С:Предприятие 8.3 с управляемыми формами, но принципы применимы и к обычному приложению.

Где именно размещается обработчик: выбор модуля

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

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

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

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

Сравнение вариантов размещения

Модуль формы

Только интерфейсная логика конкретной формы; не сработает при программной записи объекта

Модуль объекта

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

Подписка на события

Один обработчик для нескольких типов объектов; не требует изменения типовых модулей, но чуть сложнее в отладке

Как добавить обработчик события в форме

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

В палитре свойств прокрутите до раздела «События». Для формы это «ПриСозданииНаСервере», «ПриОткрытии», «ПередЗаписью», «ПослеЗаписи» и другие; для поля ввода — «ПриИзменении», «НачалоВыбора», «ОбработкаВыбора»; для кнопки — «Нажатие».

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

1. 1
   Откройте форму объекта в конфигураторе и выделите элемент или форму
2. 2
   Откройте палитру свойств (правый клик → Свойства)
3. 3
   Найдите раздел «События» и выберите нужное событие
4. 4
   Нажмите лупу в поле события и выберите контекст выполнения
5. 5
   Впишите код в созданную заготовку процедуры
6. 6
   Обновите конфигурацию базы данных и проверьте работу в режиме предприятия

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

&НаКлиенте
Процедура КоличествоПриИзменении(Элемент)
Объект.Сумма = Объект.Количество * Объект.Цена;
КонецПроцедуры

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

Обработчики в модуле объекта

Чтобы открыть модуль объекта, выделите объект конфигурации (документ, справочник), нажмите правой кнопкой и выберите «Открыть модуль объекта». Здесь обработчики не привязываются через палитру свойств — платформа вызывает их по фиксированным именам.

Наиболее востребованные события модуля объекта: ПередЗаписью, ПриЗаписи, ОбработкаПроверкиЗаполнения, ОбработкаПроведения, ПриКопировании. Полный список удобно посмотреть через кнопку «Процедуры и функции» над текстом модуля или через синтакс-помощник.

Пример проверки заполнения с отказом от записи:

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

Установка параметра Отказ = Истина в событиях «ПередЗаписью» и «ОбработкаПроверкиЗаполнения» прерывает запись объекта. Это штатный механизм контроля, но используйте его осознанно: отказ сработает и при программной записи, что может сломать обмены и обработки загрузки данных.

Подписка на события: когда и как создать

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

В свойстве «Событие» выберите нужное событие (чаще всего «ПриЗаписи» или «ПередЗаписью»), а в свойстве «Обработчик» через лупу укажите процедуру. Процедура должна находиться в общем модуле с установленными свойствами «Сервер» и, как правило, «Вызов сервера» не требуется.

Сигнатура обработчика подписки зависит от события. Для «ПриЗаписи» она выглядит так:

// В общем модуле, свойство "Сервер" = Истина
Процедура ПротоколироватьЗаписьПриЗаписи(Источник, Отказ) Экспорт
// Источник — записываемый объект любого из выбранных типов
ЗаписьЖурналаРегистрации("Запись документа",
УровеньЖурналаРегистрации.Информация, , ,
Строка(Источник.Ссылка));
КонецПроцедуры

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

Обработчик для команды и кнопки

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

Затем перетащите команду из дерева команд в дерево элементов формы — появится кнопка. Обработчик команды создаётся так же через лупу, с выбором контекста выполнения.

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

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

Обратите внимание на приём «клиентская обёртка + серверная процедура»: это стандартный шаблон для управляемых форм, когда логика требует обращения к данным базы.

Как проверить, что обработчик работает

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

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

Контрольные точки

Как проверить результат

Поле события в палитре свойств

Норма

Указано имя процедуры, по лупе открывается именно ваш код

Тревожный признак

Поле пустое или ведёт к другой процедуре

Срабатывание при записи из формы

Норма

Обработчик выполняется, изменения видны

Тревожный признак

Код в модуле формы, а объект записан программно — обработчик не вызван

Отладка

Норма

Точка останова срабатывает при ожидаемом действии

Тревожный признак

Отладчик молчит — неверный модуль или событие не привязано

Типичные ошибки и ограничения

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

Вторая ошибка — обращение к элементам формы из модуля объекта или общего модуля. Там нет ни формы, ни её элементов: попытка обратиться к ним приведёт к ошибке исполнения. Данные между сервером и клиентом передаются через параметры процедур и реквизиты формы.

Третья группа проблем связана с подписками: забыт признак «Сервер» у общего модуля, неверная сигнатура процедуры (число параметров должно строго соответствовать событию), рекурсивный вызов — когда обработчик «ПриЗаписи» сам записывает тот же объект и вызывает сам себя.

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

Как добавить обработчик, не изменяя типовую конфигурацию?

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

Почему обработчик «ПриИзменении» не срабатывает при программном заполнении реквизита?

События формы возникают только при интерактивных действиях пользователя. Если реквизит заполнен кодом, вызовите нужную процедуру явно после присваивания значения — это штатная практика.

Чем подписка на события отличается от кода в модуле объекта?

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

Какой контекст выбрать: «На клиенте» или «На сервере»?

Если нужен запрос к базе, обращение к менеджерам объектов или вычисления с данными — только сервер. Если это реакция на действие пользователя без обращения к данным (очистка поля, управление видимостью) — клиент, так быстрее и без лишних серверных вызовов.

Можно ли к одному событию привязать несколько обработчиков?

Напрямую в палитре свойств — нет, событие указывает на одну процедуру. Но внутри этой процедуры можно вызывать сколько угодно других процедур. Для событий записи объектов несколько независимых обработчиков реализуются через несколько подписок на одно событие.

Опасно ли добавлять обработчики в рабочей базе?

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