Как добавить код в расширение 1С: пошаговое руководство

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

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

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

Создание расширения и подготовка к работе

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

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

Перед началом работы убедитесь, что конфигурация поддерживает расширения: режим совместимости конфигурации должен быть не ниже версии, в которой появились нужные механизмы (аннотация &ИзменениеИКонтроль требует платформу 8.3.11 и выше). Сохраните расширение командой «Обновить конфигурацию базы данных» (F7) — без этого оно не заработает в режиме предприятия.

Заимствование объектов: формы, модули, роли

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

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

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

Добавление кода в обработчики формы

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

Аннотация определяет, как ваш код соотносится с типовым:

• &Перед("ПриСозданииНаСервере") — ваш код выполнится до типового обработчика;
• &После("ПриСозданииНаСервере") — после типового;
• &Вместо("ПриСозданииНаСервере") — типовой обработчик не выполнится, работает только ваш код;
• &ИзменениеИКонтроль("ПриСозданииНаСервере") — типовой код копируется в вашу процедуру, вы правите его, а платформа проверяет, не изменился ли оригинал при обновлении.

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

&После("ПриСозданииНаСервере")
Процедура Расш1_ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)
	Если Параметры.Ключ.Пустая() Тогда
		Объект.Комментарий = "Создано через расширение";
	КонецЕсли;
КонецПроцедуры

Аннотация «Изменение и контроль»: безопасная правка типового кода

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

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

Ограничение: &ИзменениеИКонтроль не применяется к функциям с возвратом значения в некоторых контекстах модуля объекта и требует аккуратности с директивами компиляции (&НаСервере, &НаКлиенте) — они должны соответствовать оригиналу, иначе код не скомпилируется.

Добавление собственного кода: модули, команды, подписки

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

Собственная команда формы — способ добавить кнопку без заимствования всей структуры формы. В заимствованной форме добавьте команду, перетащите её на дерево элементов (например, в командную панель) и создайте обработчик Расш1_ВыполнитьПечать с директивой &НаКлиенте или &НаСервере. Имена новых элементов получают префикс расширения автоматически.

Подписки на события позволяют реагировать на запись документов и справочников без заимствования их модулей. Создайте в расширении подписку, укажите источник (например, ДокументОбъект.РеализацияТоваровУслуг), событие ПередЗаписью или ПриЗаписи и обработчик — процедуру в общем модуле расширения с параметрами Источник и Отказ. Это удобно для проверок и автозаполнения, не затрагивающих типовой модуль объекта.

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

Ограничения и частые ошибки

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

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

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

Проверка результата и отладка

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

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

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

FAQ