Свой код в расширении конфигурации: заимствование, аннотации и отладка

Чтобы добавить код в расширение 1С, откройте Конфигуратор, меню Конфигурация → Расширения конфигурации, создайте или откройте расширение и заимствуйте нужный объект основной конфигурации. Затем в модуле основной конфигурации вызовите контекстное меню на процедуре, выберите Добавить в расширение и укажите тип вызова: перед, после, вместо или с изменением и контролем. Платформа сама создаст в модуле расширения процедуру с аннотацией — туда и пишется ваш код.

Типичная ситуация: бухгалтер просит, чтобы при проведении реализации проверялось заполнение договора, а конфигурация типовая и на поддержке. Снимать её с поддержки ради трёх строк — значит усложнить каждое следующее обновление. Расширение решает это без вмешательства в типовой код. Всё ниже относится к платформе 8.3 (расширения появились в 8.3.6) и одинаково работает в БП 3.0, ЗУП 3.1, УТ 11 и других конфигурациях на БСП.

Когда код лучше нести в расширение

Расширение — это отдельная маленькая конфигурация, которая накладывается на основную при запуске. Типовой код остаётся нетронутым, а ваши правки живут рядом.

Расширение подходит, если нужно:

• 🔧 поправить поведение типового модуля — проверку, заполнение, расчёт;
• 📄 добавить печатную форму, отчёт или обработку, которые используют типовые данные;
• 🧩 вставить на форму документа своё поле или кнопку;
• 🗂 добавить реквизит к справочнику или документу и обрабатывать его в коде;
• 🩹 закрыть ошибку типового релиза до выхода исправления.

Когда расширение не лучший выбор:

• нужна глубокая переделка структуры, затрагивающая десятки объектов и регистров — проще вести доработанную конфигурацию;
• правка нужна разово, а данные можно поправить внешней обработкой — заводить расширение ради одного запуска нет смысла.

Подготовка: создаём расширение и задаём свойства

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

Создание расширения

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

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

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

Как добавить код в расширение: заимствование и аннотации

Писать код «поверх» типового объекта нельзя, пока объект не заимствован. Заимствование — это ссылка на объект основной конфигурации внутри расширения.

Шаг 1. Заимствуйте объект

1. В дереве основной конфигурации найдите объект, например документ РеализацияТоваровУслуг.
2. Правой кнопкой мыши — Добавить в расширение и выберите своё расширение.
3. Объект появится в дереве расширения с пометкой заимствования.

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

Шаг 2. Перехватите нужный метод

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

1. Откройте модуль объекта в основной конфигурации.
2. Встаньте на имя процедуры, например ОбработкаПроверкиЗаполнения.
3. Контекстное меню → Добавить в расширение.
4. Выберите расширение и тип вызова.

Платформа создаст в модуле расширения процедуру с тем же набором параметров и аннотацией. Имя процедуры будет содержать префикс расширения.

Какую аннотацию выбрать

Пример: дополнительная проверка договора при проведении реализации.

&После("ОбработкаПроверкиЗаполнения")
Процедура мк_ОбработкаПроверкиЗаполнения(Отказ, ПроверяемыеРеквизиты)

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

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

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

Аннотация «Вместо» и ПродолжитьВызов

&Вместо даёт полный контроль. Типовой метод выполнится, только если вы явно напишете ПродолжитьВызов(...) с теми же параметрами:

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

	Если Комментарий = "тест" Тогда
		Отказ = Истина;
		Возврат;
	КонецЕсли;

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

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

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

Изменение и контроль: правка в середине метода

Если нужно поменять одну строку в длинной процедуре, &Перед и &После не помогут. Здесь выручает &ИзменениеИКонтроль. Платформа копирует текст типового метода, а вы размечаете правки:

&ИзменениеИКонтроль("ЗаполнитьПоОснованию")
Процедура мк_ЗаполнитьПоОснованию(Основание)

	// ... типовой код без изменений ...

	#Вставка
	Комментарий = "Создан на основании: " + Строка(Основание);
	#КонецВставки

	#Удаление
	СтароеЗаполнение(Основание);
	#КонецУдаления

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

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

Код в формах и общих модулях

Модули объекта — лишь часть задачи. Часто код нужен на форме или в общем модуле.

Обработчики событий формы

1. Заимствуйте форму: в дереве основной конфигурации раскройте документ, найдите форму, Добавить в расширение.
2. Откройте заимствованную форму в расширении.
3. В палитре свойств формы или элемента найдите нужное событие, например ПриСозданииНаСервере.
4. Рядом с событием задайте тип вызова: перед, после или вместо типового обработчика, и создайте процедуру.

&НаСервере
Процедура мк_ПриСозданииНаСервереПосле(Отказ, СтандартнаяОбработка)

	Элементы.Комментарий.Подсказка = "Укажите номер заявки из CRM";

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

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

Общие модули

Метод общего модуля перехватывается так же: заимствуйте модуль, затем Добавить в расширение на процедуре. Флаги модуля (сервер, клиент, вызов сервера) берутся из основной конфигурации.

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

Порядок директив

Директива компиляции стоит над аннотацией, параметры метода совпадают с типовым:

&НаКлиенте
&Перед("ПередЗакрытием")
Процедура мк_ПередЗакрытием(Отказ, ЗавершениеРаботы, ТекстПредупреждения, СтандартнаяОбработка)
	// ваш код
КонецПроцедуры

Как не сломать типовую логику: правила работы с модулями

Несколько привычек, которые избавляют от проблем при следующем обновлении:

• ✂️ Минимум перехвата. Заимствуйте только те объекты и методы, которые реально меняете. Каждый лишний объект — ещё одна точка проверки при обновлении.
• 🧱 Своя логика — в свои методы. В перехватчике оставьте вызов, а основной код вынесите в новый общий модуль расширения. Так правка видна в одном месте.
• 🔁 &После вместо &Вместо. Если можно дописать результат, а не заменять логику, — дописывайте.
• 🏷 Префикс везде. Новые реквизиты, формы, процедуры и общие модули — с префиксом расширения.
• 📝 Комментарий к перехвату. Одна строка: зачем перехвачено и по чьей заявке. Через год это сэкономит час разбирательств.

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

Ошибки, на которых спотыкаются чаще всего

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

Отладка, тестирование и передача в рабочую базу

Отладка

Точки останова в модулях расширения ставятся так же, как в основной конфигурации. Запустите отладку из Конфигуратора (F5), выполните действие в 1С:Предприятии — выполнение остановится на вашей строке.

Если перехватчик не срабатывает, поставьте точку и в типовом методе. Так видно, вызывается ли он вообще и в каком порядке идут ваши процедуры.

Что проверить перед передачей

Выгрузка и загрузка

1. В списке Конфигурация → Расширения конфигурации выделите расширение.
2. Выберите сохранение в файл — получите файл .cfe.
3. В рабочей базе загрузите файл одним из способов:
   • в Конфигураторе — тот же список расширений, загрузка из файла, затем Обновить конфигурацию базы данных;
   • в пользовательском режиме конфигураций на БСП — Администрирование → Печатные формы, отчеты и обработки → Расширения, кнопка добавления из файла.
4. Перезапустите сеансы пользователей, чтобы расширение подключилось.

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

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

Рабочий порядок:

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

Чтобы не потерять историю, храните выгрузки .cfe с номером версии в имени, а лучше — исходники расширения в системе контроля версий. Конфигуратор умеет выгружать расширение в файлы XML, а 1С:EDT работает с расширениями как с отдельным проектом.

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