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

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

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

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

Когда расширение подходит, а когда нужна доработка конфигурации

Прежде чем начинать, важно убедиться, что задача решается средствами расширения. Через расширение можно добавлять новые объекты метаданных (справочники, документы, отчёты, обработки, роли, подсистемы), заимствовать формы и модули типовых объектов и переопределять их обработчики, добавлять собственные реквизиты к заимствованным объектам.

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

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

Любую разработку начинайте на копии рабочей базы. Даже безопасный механизм расширений при ошибке в коде может нарушить работу пользователей: например, обработчик «ПередЗаписью» с исключением заблокирует проведение документов. Копию создают через выгрузку в dt (Конфигуратор → Администрирование → Выгрузить информационную базу) или средствами СУБД.

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

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

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

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

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

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

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

Программирование: аннотации и порядок вызова обработчиков

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

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

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

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

&ИзменениеИКонтроль("ОбработкаПроведения")
Процедура Расш1_ОбработкаПроведения(Отказ, Режим)
	#Вставка
	// собственный код до типового
	#КонецВставки
КонецПроцедуры

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

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

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

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

Подключение, отладка и проверка применимости

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

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

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

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

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

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

Безопасность и распространение расширения

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

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

Частые вопросы о расширениях 1С