К статье
Практический материал

Другое · 8 мин

Обработчики событий 1С: практическое руководство

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

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

События делят на клиентские и серверные. Клиентские выполняются на рабочей станции пользователя, серверные — на сервере 1С:Предприятия. От места выполнения зависит, какие объекты и методы доступны внутри обработчика, а также как поведёт себя система при ошибке.

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

Что такое обработчик события в 1С

Обработчик оформляется как процедура в модуле формы, модуле объекта, общем модуле или модуле документа. Имя процедуры часто совпадает с именем события, но важно не только имя, а правильная подписка: система должна знать, на какое событие и на каком объекте нужно реагировать.

В управляемых формах обработчики обычно пишутся в модуле формы и могут быть помечены директивами &НаКлиенте или &НаСервере. Это определяет, где будет выполнен код: на стороне пользователя или на стороне сервера. В обычных формах порядок аналогичен, но область доступных объектов и событий отличается.

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

Где и как создаются обработчики

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

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

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

Порядок создания обработчика
  1. 1
    Определите событие и объект, на котором оно возникает
  2. 2
    Откройте модуль формы или объекта в конфигураторе
  3. 3
    Создайте процедуру с нужной сигнатурой или сгенерируйте её через события объекта
  4. 4
    Напишите логику и укажите директиву выполнения при необходимости
  5. 5
    Проверьте синтаксис и протестируйте на копии базы

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

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

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

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

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

Когда нужен серверный контекст

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

Часто используемые события форм и документов

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

ПриИзменении срабатывает при изменении значения реквизита и подходит для пересчёта зависимых полей. НачалоВыбора и ОбработкаВыбора помогают управлять списком доступных значений в справочниках и перечислениях.

ПриОткрытие и ПриЗапись

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

ПриИзменении и выбор значения

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

Типичные ошибки
01
Размещение серверного кода в клиентском обработчике без вызова процедуры на сервере
02
Забытие директивы экспорта или неверная сигнатура процедуры события
03
Неконтролируемое использование Отказ, которое блокирует запись без понятного сообщения пользователю
04
Поведение тяжёлых расчётов внутри часто вызываемого события ПриИзменении

Возврат результата: Отказ и СтандартнаяОбработка

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

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

Проверка и отладка обработчиков

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

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

Итог

Что важно запомнить

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

Ограничения и альтернативы

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

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

Нужно ли каждому событию свой обработчик?

Нет. Обработчик создаётся только тогда, когда типовой возможности платформы недостаточно. Если задачу можно решить настройкой свойств объекта, ролями или стандартной проверкой заполнения, дополнительный код не требуется.

Может ли один обработчик работать на нескольких формах?

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

Что делать, если обработчик не срабатывает?

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

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

Безопасно только после проверки на копии базы и с понятным сообщением пользователю. Блокировка без объяснения причины может привести к остановке работы пользователей и потере введённых данных.

Нужно ли тестировать обработчики перед внедрением?

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