Подписка на событие 1С: создание, обработчик, расширение

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

Ниже — как устроены подписки на события в 1С 8.3; имена типовых объектов сверены по УТ 11.4 и КА 2.5.

Где встречаются подписки на события

Подписка нужна, когда одну логику надо повесить на многие объекты или встроить в типовую, не трогая модули: заполнить реквизит, запретить проведение, поставить изменения в очередь выгрузки. В УТ 11.4 подписок больше 260: около 120 на ПередЗаписью, 75 на ПриЗаписи и всего две на ОбработкаПроведения. В КА 2.5 их больше 500, а на документ «Реализация товаров и услуг» в УТ 11.4 срабатывает больше 50 подписок.

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

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

&НаКлиенте
Процедура ПоказатьПодписки(Команда)

	ВывестиПодпискиНаСервере("ДокументОбъект.РеализацияТоваровУслуг");

КонецПроцедуры

&НаСервереБезКонтекста
Процедура ВывестиПодпискиНаСервере(ИмяТипа)

	ТипИсточника = Тип(ИмяТипа);
	Найдено = 0;

	Для Каждого Подписка Из Метаданные.ПодпискиНаСобытия Цикл

		Если Не Подписка.Источник.СодержитТип(ТипИсточника) Тогда
			Продолжить;
		КонецЕсли;
		Найдено = Найдено + 1;

		// Собственные подписки расширений, применённых в сеансе, тоже здесь.
		Расширение = Подписка.РасширениеКонфигурации();
		Принадлежность = ?(Расширение = Неопределено, "конфигурация", "расширение " + Расширение.Имя);

		// Много типов в источнике — подписка на все документы или определяемый тип:
		// с неё начинают, если запись документа тормозит.
		Сообщить(СтрШаблон("%1 (%2): типов в источнике %3, %4",
			Подписка.Имя, Подписка.Синоним, Подписка.Источник.Типы().Количество(), Принадлежность));

	КонецЦикла;

	Сообщить(СтрШаблон("Всего подписок на %1: %2", ИмяТипа, Найдено));

КонецПроцедуры

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

Как создать подписку на событие 1С в конфигураторе

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

Подписки на события при записи — ПередЗаписью и ПриЗаписи — самые частые, но не единственные:

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

Типичная подписка на событие проведения — запрет провести заказ клиента и реализацию с нулевой ценой. Проверять надо до движений, поэтому событие — ПередЗаписью в режиме проведения: ОбработкаПроведения подписки вызывается после модуля документа, и отказ в ней выбросит готовые движения. Колонки Товары.Цена и Товары.Отменено (только у заказа) есть в УТ 11.4 и КА 2.5.

// Общий модуль КонтрольЦенСобытия (суффикс «События» — как у модулей подписок в БСП,
// например ВерсионированиеОбъектовСобытия). Флаги «Сервер», «Внешнее соединение»,
// «Клиент (обычное приложение)»; «Вызов сервера» и «Глобальный» сняты.
// Подписка КонтрольЦенПередПроведением:
//   Источник — ДокументОбъект.ЗаказКлиента, ДокументОбъект.РеализацияТоваровУслуг;
//   Событие — ПередЗаписью;
//   Обработчик — КонтрольЦенСобытия.ПроверитьЦеныПередЗаписью.

Процедура ПроверитьЦеныПередЗаписью(Источник, Отказ, РежимЗаписи, РежимПроведения) Экспорт

	// Сначала дешёвые проверки: загрузка обмена, режим записи, флаг от вызывающего кода.
	Если Источник.ОбменДанными.Загрузка
		Или РежимЗаписи <> РежимЗаписиДокумента.Проведение
		Или Источник.ДополнительныеСвойства.Свойство("НеПроверятьЦены") Тогда
		Возврат;
	КонецЕсли;

	// В заказе есть отменённые строки, у реализации колонки Отменено нет.
	ЭтоЗаказ = ТипЗнч(Источник) = Тип("ДокументОбъект.ЗаказКлиента");

	Для Каждого СтрокаТоваров Из Источник.Товары Цикл

		Если ЭтоЗаказ И СтрокаТоваров.Отменено Тогда
			Продолжить;
		КонецЕсли;

		Если ЗначениеЗаполнено(СтрокаТоваров.Цена) Тогда
			Продолжить;
		КонецЕсли;

		Сообщение = Новый СообщениеПользователю;
		Сообщение.Текст = СтрШаблон(НСтр("ru = 'Строка %1: не указана цена для «%2».'"),
			СтрокаТоваров.НомерСтроки, СтрокаТоваров.Номенклатура);
		// Индекс строки в пути к полю — с нуля и без разделителя разрядов.
		Сообщение.Поле = "Товары[" + Формат(СтрокаТоваров.НомерСтроки - 1, "ЧН=0; ЧГ=0") + "].Цена";
		Сообщение.УстановитьДанные(Источник);
		Сообщение.Сообщить();

		Отказ = Истина;

	КонецЦикла;

КонецПроцедуры

• Объект приходит в параметре Источник: ЭтотОбъект и Движения в общем модуле нет.
• Обойти подписку из своего кода — флаг ДокОбъект.ДополнительныеСвойства.Вставить("НеПроверятьЦены", Истина) перед Записать(), например когда вы создаёте документы программно.
• Колонки Отменено у реализации нет, но условие с И 1С вычисляет слева направо и до неё не дойдёт.
• Поле и УстановитьДанные(Источник) привязывают сообщение к цене нужной строки в форме документа. На БСП то же делает ОбщегоНазначения.СообщитьПользователю(Текст, Источник, Поле, , Отказ).

Порядок вызова: модуль объекта, подписки, расширения

По справке платформы:

1. Сначала выполняется обработчик события в модуле объекта или набора записей — вместе с перехватчиками &Перед и &После из расширений.
2. Если модуль установил Отказ = Истина или вызвал исключение, действие прерывается, подписки не вызываются.
3. Затем в произвольном порядке вызываются подписки основной конфигурации и расширений. В Источник приходит тот же объект.
4. Отказ или исключение в подписке тоже прерывает действие, транзакция откатывается.

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

Подписка в расширении: доработка без снятия с поддержки

С платформы 8.3.17 в расширении можно создавать свои подписки и заимствовать типовые. Для типовой на поддержке это основной путь: конфигурация не меняется и обновляется штатно, а подписке всё равно, как 1С переименует методы модуля документа. Подписка на событие в расширении создаётся так же:

1. Заимствуйте документы-источники: контекстное меню документа → «Добавить в расширение».
2. Создайте в расширении собственный общий модуль с теми же флагами и добавьте подписку в ветку «Общие» → «Подписки на события» дерева расширения.
3. Продумайте права. Безопасный режим платформа снимает на время обработчиков основной конфигурации, а для кода расширения он остаётся: при флаге «Безопасный режим» привилегированный режим игнорируется, интернет и файлы недоступны.

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

// Расширение «Интеграция», префикс Расш1_. Заимствован документ РеализацияТоваровУслуг.
// Собственный регистр сведений Расш1_ОчередьОтправки (независимый, непериодический):
//   измерение Документ — ДокументСсылка.РеализацияТоваровУслуг;
//   ресурсы Действие — Строка(20), ДатаИзменения — Дата (дата и время).
// Собственный общий модуль Расш1_ОчередьОтправкиСобытия, флаги — как в листинге 2.
// Подписки расширения с источником ДокументОбъект.РеализацияТоваровУслуг:
//   Расш1_ОчередьПриПроведении — событие ОбработкаПроведения, обработчик ПриПроведении;
//   Расш1_ОчередьПриОтменеПроведения — событие ОбработкаУдаленияПроведения,
//   обработчик ПриОтменеПроведения.

Процедура ПриПроведении(Источник, Отказ, РежимПроведения) Экспорт

	// Вызывается после ОбработкаПроведения модуля документа.
	// Если проведение потом откатится, исчезнет и запись в очереди.
	ПоставитьВОчередь(Источник.Ссылка, "Проведение");

КонецПроцедуры

Процедура ПриОтменеПроведения(Источник, Отказ) Экспорт

	ПоставитьВОчередь(Источник.Ссылка, "ОтменаПроведения");

КонецПроцедуры

// В транзакции только записываем, что отправить. Саму отправку во внешнюю
// систему делает регламентное задание после фиксации транзакции.
Процедура ПоставитьВОчередь(Документ, Действие)

	// Прав на регистр очереди у пользователя может не быть. Привилегированный
	// режим работает, только если у расширения снят флаг «Безопасный режим».
	УстановитьПривилегированныйРежим(Истина);

	Запись = РегистрыСведений.Расш1_ОчередьОтправки.СоздатьМенеджерЗаписи();
	Запись.Документ = Документ;
	Запись.Действие = Действие;
	Запись.ДатаИзменения = ТекущаяДатаСеанса();
	// Ключ записи — документ: перепроведение перезапишет строку, дублей не будет.
	Запись.Записать(Истина);

КонецПроцедуры

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

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

Обработчик типовой подписки — экспортная процедура общего модуля: заимствуйте модуль и перехватите её. В УТ 11.4 подписка УстановитьАвтораДокумента ставит автором нового заказа клиента, реализации и других документов текущего пользователя, и автор, которого указала фоновая загрузка заказов с сайта, затирается пользователем задания:

// Расширение: заимствован общий модуль ЗаполнениеСвойствПоСтатистикеСервер (УТ 11.4).
// Его процедура — обработчик типовой подписки УстановитьАвтораДокумента (ПередЗаписью).
// В КА 2.5 то же делает ЗаполнениеОбъектовПоСтатистике.УстановитьАвтораОбъектаПередЗаписью.

&Вместо("УстановитьАвтораДокументаПередЗаписью")
Процедура Расш1_УстановитьАвтораДокументаПередЗаписью(Источник, Отказ, РежимЗаписи, РежимПроведения)

	// Загрузка заказов с сайта в фоновом задании сама указывает автора и ставит
	// этот флаг. Без него типовой код заменил бы автора пользователем задания.
	Если Источник.ДополнительныеСвойства.Свойство("Расш1_СохранитьАвтора") Тогда
		Возврат;
	КонецЕсли;

	// Во всех остальных случаях — типовое поведение.
	ПродолжитьВызов(Источник, Отказ, РежимЗаписи, РежимПроведения);

КонецПроцедуры

• Без ПродолжитьВызов типовая логика выключится для всех документов источника.
• Проверка «автор уже заполнен» вместо флага не годится: при копировании реализации в УТ 11.4 автор переходит из исходного документа, и типовой код правильно его заменяет.
• Аннотация ищет процедуру по имени: после обновлений проверяйте расширение на копии базы.

События формы и ОбработкаПолученияФормы

Подписка на события формы невозможна: подписки обрабатывают только неинтерактивные события прикладных объектов. ПриСозданииНаСервере, ПередЗаписьюНаСервере и команды формы дорабатывают расширением формы. Подписка умеет другое: событие менеджера ОбработкаПолученияФормы подменяет открываемую форму целиком. В УТ 11.4 так работают девять подписок, например ПереопределитьПолучаемуюФормуПрисоединенногоФайла.

// Общий модуль расширения, флаги — как в листинге 2.
// Подписка Расш1_ФормаЗаказаДляСклада: источник ДокументМенеджер.ЗаказКлиента,
// событие ОбработкаПолученияФормы. В заимствованном документе создана
// собственная форма расширения Расш1_ФормаСклад.

Процедура ФормаЗаказаДляСкладаОбработкаПолученияФормы(Источник, ВидФормы, Параметры,
	ВыбраннаяФорма, ДополнительнаяИнформация, СтандартнаяОбработка) Экспорт

	// Кладовщику вместо типовой формы заказа открываем упрощённую.
	// Форма списка и форма выбора остаются типовыми.
	Если ВидФормы = "ФормаОбъекта" И РольДоступна("Расш1_Кладовщик") Тогда
		ВыбраннаяФорма = "Расш1_ФормаСклад";
		СтандартнаяОбработка = Ложь;
	КонецЕсли;

КонецПроцедуры

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

Производительность и ОбменДанными.Загрузка

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

• Ранний выход. До запросов — ОбменДанными.Загрузка, режим записи, тип, флаг в ДополнительныеСвойства. Типовая подписка на все документы ОтветственныеЛицаДокументаПриКопировании выходит по проверке, закэшированной в ОтветственныеЛицаПовтИсп.
• Реквизиты ссылок — запросом. Источник.Контрагент.ИНН заставляет платформу прочитать объект контрагента, а не одно поле. Одно-два поля берите запросом или ОбщегоНазначения.ЗначенияРеквизитовОбъекта.
• Внешние вызовы — после транзакции, через очередь, как в листинге 3.
• Замер. «Отладка» → «Замер производительности» покажет время строк обработчиков, см. отладку 1С.

ОбменДанными.Загрузка = Истина ставят обмен, загрузка из XML, групповые обработки и обработчики обновления БСП: у ОбновлениеИнформационнойБазы.ЗаписатьОбъект по умолчанию ВключитьБизнесЛогику = Ложь. Платформа делает минимум проверок, но обработчики модуля и подписок вызывает, поэтому флаг проверяет сам обработчик, первой строкой, — как ДатыЗапретаИзменения.ПроверитьДатуЗапретаИзмененияПередЗаписьюДокумента в УТ 11.4. Это не догма: ВерсионированиеОбъектовСобытия.ЗаписатьВерсиюОбъекта флаг сознательно не проверяет, чтобы хранить версии и при обмене. Проверки и автозаполнение при загрузке пропускайте, а регистрацию для своих выгрузок обычно оставляйте — см. план обмена.

Типичные ошибки

• «При подписке … на событие … произошла ошибка. Метод обработчика события … не найден.» — у процедуры нет Экспорт, её переименовали или модуль не компилируется там, где идёт запись: снят флаг «Сервер», а для обычного приложения — «Клиент (обычное приложение)».
• «Переменная не определена (ЭтотОбъект)» — код перенесли из модуля объекта. Замените ЭтотОбъект на Источник, а Движения — на Источник.Движения.
• Подписка не срабатывает. Документа нет в источнике, обработчик вышел по ОбменДанными.Загрузка или расширение не применено. ОбработкаПроверкиЗаполнения вызывают интерактивная запись и ПроверитьЗаполнение(), а не Записать().
• Изменения в ПриЗаписи не сохранились. Объект к этому моменту уже в базе. Реквизиты меняют в ПередЗаписью, а Источник.Записать() внутри обработчика снова вызовет ту же подписку.
• «Нарушение прав доступа!» у пользователя, но не у администратора — обработчик пишет в регистр без прав, а привилегированный режим в безопасном расширении игнорируется.

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

Подписка или код в модуле объекта?

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

Как временно отключить подписку?

Из кода — никак. Обработчик проверяет флаг в ДополнительныеСвойства, а вызывающий код ставит его перед Записать(), как в листингах 2 и 4. ОбменДанными.Загрузка тоже выключит подписки, которые его проверяют, но вместе со всей логикой типовой.

Можно ли подписаться на запись регистра или константы?

Да. Источник — РегистрНакопленияНаборЗаписей.<Имя> или РегистрСведенийНаборЗаписей.<Имя>, события ПередЗаписью и ПриЗаписи с параметром Замещение, отбор набора — в Источник.Отбор. Для констант источник — КонстантаМенеджерЗначения.<Имя>; в УТ 11.4 подписка ПриЗаписиКонстанты срабатывает на запись любой константы.

Когда проще заказать

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

По теме

• Расширение конфигурации 1С: создание, аннотации, ошибки
• Общий модуль 1С 8.3: Клиент, Сервер, Вызов сервера, ПовтИсп
• Регистр сведений 1С: периодический, независимый, создание
• БСП 1С: что это и какие подсистемы нужны программисту