Как писать расширения для 1С: от заимствования объекта до выпуска файла .cfe

Расширение 1С создают в Конфигураторе: Конфигурация → Расширения конфигурации → Добавить. Дальше заимствуют нужные объекты типовой конфигурации, дописывают свой код через аннотации &Перед, &После, &Вместо или &ИзменениеИКонтроль и выгружают результат в файл .cfe. Типовая при этом остаётся на поддержке и обновляется без сравнения-объединения.

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

Расширение конфигурации 1С: что это и когда его использовать

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

Что можно сделать расширением:

• 📄 добавить свою печатную форму, отчёт или обработку;
• 🧩 добавить реквизит в типовой справочник или документ (платформа 8.3.11 и новее);
• 🖥️ вывести на типовую форму новое поле, кнопку, страницу;
• ⚙️ встроить проверку при записи или проведении документа;
• 🛠️ исправить ошибку в типовом модуле до выхода официального релиза;
• 🗂️ создать собственные справочники, регистры, документы.

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

Назначение расширения

В свойствах есть поле Назначение с тремя значениями: Исправление, Адаптация, Дополнение. От него зависит порядок применения, если в базе несколько расширений: сначала исправления, затем адаптации, затем дополнения. Для типичной доработки под клиента ставьте «Адаптация», для временной заплатки ошибки — «Исправление».

Подготовка среды для разработки расширений

Разрабатывать в рабочей базе нельзя. Сначала подготовьте копию.

1. Выгрузите рабочую базу в .dt: Администрирование → Выгрузить информационную базу в Конфигураторе.
2. Создайте новую пустую базу и загрузите в неё этот файл. Загрузка .dt требует монопольного доступа — делайте это в копии, а не в рабочей.
3. Проверьте, что версия платформы на машине разработчика не ниже версии на сервере заказчика. Иначе можно задействовать возможности, которых у клиента нет.
4. Если над расширением работают двое и более, подключите его к хранилищу. Расширение подключается к своему хранилищу отдельно от основной конфигурации.

Инструмент выбирайте по команде и объёму:

• Конфигуратор — хватает для небольших расширений и одиночной работы.
• 1С:EDT — удобнее для крупных проектов: Git, рефакторинг, проверки кода. Расширение там — отдельный проект, привязанный к проекту конфигурации.

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

Шаг 1. Добавьте расширение

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

Откроется второе дерево — дерево расширения. Основная конфигурация в нём видна как источник объектов для заимствования.

Шаг 2. Заимствуйте нужные объекты

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

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

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

Шаг 3. Добавьте реквизит в типовой объект

В заимствованном документе добавьте реквизит обычным способом, имя — с префиксом: Расш1_ДатаДоставки, тип Дата. После этого расширение начинает менять структуру данных. В Конфигураторе после этого нужно обновить конфигурацию базы данных (F7). У заказчика установка такого расширения тоже потребует обновления структуры базы — учитывайте это при планировании.

Шаг 4. Перехватите метод типового модуля

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

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

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

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

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

Перехват работает, только если в типовом модуле процедура с таким именем есть. Перед написанием проверьте это поиском по модулю (Ctrl+F).

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

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

	// ... исходный текст типового метода ...

	#Вставка
	Расш1_ДатаДоставки = ТекущаяДатаСеанса() + 86400;
	#КонецВставки

	#Удаление
	// строка типового кода, которую нужно отключить
	#КонецУдаления

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

Сила этой аннотации — в контроле: если в новом релизе текст типового метода изменится, расширение не применится, и вы увидите, где именно расхождение.

Работа с формами и элементами управления в расширении

Форму заимствуют так же, как объект: правой кнопкой по форме в дереве основной конфигурации → Добавить в расширение. В расширении откроется редактор формы с типовыми элементами.

Визуальный способ

1. Откройте заимствованную форму документа.
2. На вкладке реквизитов найдите Объект и в нём свой Расш1_ДатаДоставки.
3. Перетащите его в дерево элементов, в нужную группу шапки.
4. Для события элемента создайте обработчик в модуле формы расширения.

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

Программный способ

Если типовая форма часто меняется от релиза к релизу, надёжнее создать элемент кодом. Тогда расширение не зависит от того, куда разработчики 1С переставили группы.

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

	Поле = Элементы.Добавить("Расш1_ДатаДоставки", Тип("ПолеФормы"));
	Поле.Вид = ВидПоляФормы.ПолеВвода;
	Поле.ПутьКДанным = "Объект.Расш1_ДатаДоставки";

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

Чтобы поставить поле в конкретное место, используйте Элементы.Вставить(Имя, Тип, Родитель, ПередЭлементом). Имя группы-родителя смотрите в дереве элементов заимствованной формы.

Отладка и тестирование расширения

Отладка расширений не отличается от отладки конфигурации: точки останова ставятся в модулях расширения (F9), запуск — Отладка → Начать отладку (F5).

Что проверить до передачи заказчику:

• 🔁 Обновление конфигурации БД. Если вы добавили реквизиты, нажмите F7 и убедитесь, что структура обновилась без ошибок.
• 🧪 Типовые сценарии. Проведите документ, перепроведите, отмените проведение, создайте на основании. Перехват часто ломает именно «соседний» сценарий.
• 👤 Права. Зайдите пользователем без полных прав. Новые объекты расширения нужно включить в роли — заимствуйте роль или создайте свою.
• 🔒 Безопасный режим. У расширения есть свойство Безопасный режим. В нём код не может работать с файлами, COM-объектами и внешними компонентами. Если ваш код это делает, при включённом безопасном режиме он упадёт с ошибкой — проверьте с теми настройками, которые будут у клиента.
• ⏱️ Производительность. Если перехвачен метод, который вызывается в цикле или при каждом открытии формы, замерьте время замером производительности (Отладка → Замер производительности).

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

Главная причина писать расширения — спокойные обновления. Но «спокойные» не значит «бесплатные».

После установки нового релиза типовой:

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

Если расширение не применилось, пользователь видит об этом сообщение, а доработка отключается. Данные из реквизитов расширения при этом не пропадают — вернутся, когда вы исправите расширение. Но учёт в этот период ведётся без вашей логики.

Проверяйте расширение на новом релизе до обновления рабочей базы, а не после.

Публикация и распространение расширения

Выгрузка в файл

В окне Конфигурация → Расширения конфигурации выделите расширение и выберите сохранение в файл в меню действий. Получится файл .cfe.

Установка у заказчика

Есть два пути:

• Через Конфигуратор. То же окно расширений → загрузка из файла → обновление конфигурации базы данных. Загрузка .cfe и обновление конфигурации БД — отдельные шаги, второй не происходит сам.
• В режиме 1С:Предприятие. В конфигурациях на БСП, например БП 3.0 и ЗУП 3.1: Администрирование → Печатные формы, отчеты и обработки → Расширения. Конфигуратор не нужен, но у пользователя должны быть права администратора.

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

Версии и описание

Заполните в свойствах версию (1.0.3), поставщика и краткое описание. Через полгода в базе клиента будет видно, что за расширение стоит и откуда оно. Храните исходники в хранилище или Git, а не только в виде последнего .cfe на почте.

Распространение готового решения

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

Правила, которые экономят время на поддержке расширения

• 🏷️ Префикс везде. Объекты, реквизиты, методы, общие модули, элементы форм.
• ✂️ Минимум заимствований. Не берите форму целиком ради одного поля, если поле можно добавить кодом.
• 🎯 &Перед и &После вместо &Вместо. Полная замена метода отрезает вас от исправлений фирмы 1С в этом методе.
• 🧱 Логику — в общий модуль расширения. В перехвате оставьте одну строку вызова, а саму логику держите в своём модуле Расш1_ДоставкаСервер. Так проще тестировать и переносить.
• 📏 Одна задача — одно расширение. Расширение «всё для клиента» на 200 объектов после обновления разбирается днями.
• 🔕 Без молчаливых ошибок. Не глушите исключения пустым Исключение КонецПопытки — запишите их в журнал регистрации через ЗаписьЖурналаРегистрации.

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