Расширение конфигурации 1С: создание, установка и перехват методов

Задача: доработать типовую конфигурацию, не снимая её с поддержки

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

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

Как создать расширение в конфигураторе

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

Готовое расширение сохраняется в файл .cfe командой «Конфигурация — Сохранить в файл» из окна расширения. Этот файл переносят в рабочую базу.

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

Добавить расширение в рабочую базу можно без конфигуратора. В конфигурациях на БСП это делается в разделе «Администрирование — Печатные формы, отчёты и обработки — Расширения». В любой конфигурации доступна стандартная функция: «Все функции — Стандартные — Управление расширениями конфигурации».

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

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

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

Заимствование объектов

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

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

Перехват методов: &Перед, &После, &Вместо

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

// Модуль объекта заимствованного документа РеализацияТоваровУслуг

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

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

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

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

    Если Не Отказ И РежимЗаписи = РежимЗаписиДокумента.Проведение Тогда
        // дополнительное заполнение после типовой логики
    КонецЕсли;

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

• &Перед("Метод") — ваш код выполняется до типового. Параметры передаются те же, поэтому можно, например, установить Отказ = Истина.
• &После("Метод") — ваш код выполняется после типового. Это самый безопасный вариант: типовая логика отрабатывает полностью, а вы дополняете результат.
• &Вместо("Метод") — типовой метод не выполняется, если вы не вызовете его явно через ПродолжитьВызов().

// Общий модуль, заимствованный из основной конфигурации

&Вместо("ЦенаНоменклатуры")
Функция Расш1_ЦенаНоменклатуры(Номенклатура, ВидЦены, Дата)

    Цена = ПродолжитьВызов(Номенклатура, ВидЦены, Дата);

    Если Номенклатура.Акционная Тогда
        Цена = Окр(Цена * 0.9, 2);
    КонецЕсли;

    Возврат Цена;

КонецФункции

Для функций подходит только &Вместо: так можно получить результат типовой функции через ПродолжитьВызов(), изменить его и вернуть своё значение. Имя ЦенаНоменклатуры и реквизит Акционная в примере условные — подставьте свои.

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

&ИзменениеИКонтроль: правка внутри типового метода

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

&ИзменениеИКонтроль("ЗаполнитьТоварыПоЗаказу")
Процедура Расш1_ЗаполнитьТоварыПоЗаказу(Заказ)

    Товары.Очистить();
    Для Каждого СтрокаЗаказа Из Заказ.Товары Цикл
        #Вставка
        Если СтрокаЗаказа.Отменено Тогда
            Продолжить;
        КонецЕсли;
        #КонецВставки
        НоваяСтрока = Товары.Добавить();
        ЗаполнитьЗначенияСвойств(НоваяСтрока, СтрокаЗаказа);
        #Удаление
        НоваяСтрока.Скидка = 0;
        #КонецУдаления
    КонецЦикла;

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

Код между #Вставка и #КонецВставки добавляется, между #Удаление и #КонецУдаления — исключается. Если после обновления типовой метод изменится, расширение не применится, а платформа сообщит, какой метод разошёлся. Удобная команда для правки — «Сравнить и объединить» в окне расширения или кнопка сравнения прямо в модуле: видно, что поменялось в оригинале.

Добавление реквизита, формы и новых объектов

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

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

Программная проверка подключённых расширений

Список подключённых к базе расширений можно получить из кода — например, чтобы вывести версии в окне «О программе» или проверить, установлено ли нужное расширение.

&НаСервере
Процедура ПоказатьРасширенияНаСервере()

    Для Каждого Расширение Из РасширенияКонфигурации.Получить() Цикл
        Сообщить(Расширение.Имя + ", версия " + Расширение.Версия
            + ", безопасный режим: " + Строка(Расширение.БезопасныйРежим));
    КонецЦикла;

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

Обновление типовой конфигурации с расширением

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

Расширения с аннотациями &Перед и &После переживают обновления лучше всего: им важно лишь, чтобы перехватываемый метод существовал с прежними параметрами. Если метод переименован или удалён, расширение сообщит об ошибке при подключении.

Как отключить или удалить расширение

Временно отключить расширение можно, сняв флажок «Активно» в списке расширений — в режиме «Предприятие» или в конфигураторе. Удаляют кнопкой «Удалить» там же. После любого из этих действий нужен перезапуск сеанса.

Если из-за ошибки в расширении база не запускается в пользовательском режиме, отключите его в конфигураторе через «Конфигурация — Расширения конфигурации». Расширения, загруженные пользователем, можно также удалить средствами БСП. Помните, что при удалении расширения с собственными реквизитами их данные будут потеряны.

Типичные ошибки при работе с расширениями

• Заимствование объекта целиком «на всякий случай» — увеличивает число точек, которые проверяются при обновлении.
• &Вместо без ПродолжитьВызов() там, где достаточно &После: типовая логика перестаёт выполняться и не обновляется.
• Копирование большого метода через &Вместо вместо &ИзменениеИКонтроль — после обновления копия устаревает незаметно.
• Попытка работать с файлами или COM в безопасном режиме — код падает с ошибкой; режим нужно отключать осознанно.
• Оставленный по умолчанию префикс Расш1_ — при нескольких расширениях имена становятся неразличимы.

Какая аннотация когда подходит

Аннотация	Когда выполняется ваш код	Типовой код	Типичное применение
&Перед	До типового метода	Выполняется	Проверки, отказ
&После	После типового метода	Выполняется	Дозаполнение, доп. действия
&Вместо	Вместо типового	Только через ПродолжитьВызов()	Изменение результата функции
&ИзменениеИКонтроль	Изменённая копия метода	Сверяется с оригиналом	Точечные правки внутри метода