Как правильно добавить новую процедуру или функцию в расширение формы 1С

При работе с расширениями конфигураций в системе «1С:Предприятие 8.3» разработчики часто сталкиваются с вопросом: как правильно внедрить в форму собственный программный код, которого изначально не было в типовом решении? Типичная ситуация — добавление новой кнопки и соответствующей команды, которая должна выполнять уникальные действия. В процессе создания обработчика система может предложить выбрать тип вызова: &Перед, &После или &Вместо. Давайте разберем по шагам, что выбирать в таких случаях и как правильно структурировать код в расширении.

Нужны ли аннотации для новых функций?

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

Аннотации &Перед, &После и &Вместо предназначены исключительно для модификации уже существующих процедур и функций основной конфигурации. Если вы создаете свой собственный метод «с нуля», он должен выглядеть как обычная процедура или функция в стандартном модуле. Выясним причину: расширение не заменяет модуль формы, а дополняет его. При запуске системы 1С динамически объединяет тексты модулей, и ваша новая функция просто становится частью общего контекста формы.

Пример оформления новой процедуры в модуле расширения формы:

&НаКлиенте
Процедура мп_СоздатьПакетДокументов(Команда)
    // Ваша логика создания документов
    мп_ВыполнитьСерверныеДействия();
КонецПроцедуры

&НаСервере
Процедура мп_ВыполнитьСерверныеДействия()
    // Логика на стороне сервера
КонецПроцедуры

Важность использования префиксов

Проанализируем критически важный нюанс — именование. При добавлении новых методов в расширение крайне важно использовать уникальные префиксы (например, мп_, х_ или сокращение названия вашей компании). Это необходимо для предотвращения конфликтов имен в будущем.

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

Правила хорошего тона при работе с расширениями:

1. Всегда добавляйте префикс к именам новых команд.
2. Всегда добавляйте префикс к именам новых процедур и функций.
3. Добавляйте префикс к именам добавленных реквизитов формы.

Как добавить команду и обработчик правильно

Разберем по шагам процесс добавления новой логики в форму через расширение:

1. Открываем форму в расширении (добавляем её туда из основной конфигурации).
2. Переходим на вкладку Команды и создаем новую команду. Например, мп_СформироватьОтчет.
3. Устанавливаем свойства команды (заголовок, картинку).
4. Нажимаем на кнопку «лупа» в поле Действие. Система предложит создать обработчик.
5. Поскольку команды мп_СформироватьОтчет нет в основной конфигурации, система создаст обычную процедуру без аннотаций &Перед/&После. Это именно то, что нам нужно.
6. Выносим кнопку на форму, привязав её к созданной команде.

Взаимодействие с типовым кодом

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

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

&После("СтандартнаяПроцедураСоздания")
Процедура мп_СтандартнаяПроцедураСозданияПосле()
    // Вызов нашей уникальной функции
    мп_МояДополнительнаяЛогика();
КонецПроцедуры

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

Особенности компиляции и контекста

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

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

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