Расширение конфигурации 1С 8.3 своими руками: от пустого файла до рабочей базы
Содержание
Расширение в 1С 8.3 пишут в Конфигураторе: Конфигурация → Расширения конфигурации → Добавить, затем в дерево расширения заимствуют нужные объекты типовой конфигурации и вешают на их методы свой код с аннотациями &Перед, &После, &Вместо или &ИзменениеИКонтроль. Типовая конфигурация при этом остаётся на поддержке, снимать её с замка не нужно.
Механизм появился в платформе 8.3.6 и с тех пор сильно вырос. Сейчас расширением можно добавить реквизит в справочник, новую печатную форму, отчёт, роль, кнопку на форме документа и поправить логику проведения. Обновление типовой при этом проходит как обычно: расширение лишь проверяют на применимость после обновления.
Что подготовить до первой строки кода
Работать в рабочей базе сразу — плохая идея. Сделайте копию: выгрузите .dt через Администрирование → Выгрузить информационную базу в Конфигураторе и загрузите её в отдельную тестовую базу. На этой копии и пишите.
Что понадобится:
- 🧩 платформа 8.3 с той же версией, что на рабочем сервере (или с номером не ниже);
- 🔑 пользователь с правом «Администрирование» в тестовой базе;
- 📄 понимание, какой объект и какой метод вы меняете — откройте модуль типового объекта и найдите место, куда нужно встроиться;
- 🏷 короткий префикс для своих объектов, например
мп_(инициалы или имя компании).
Назначение расширения
При создании у расширения есть свойство «Назначение». От него зависит порядок, в котором платформа применяет несколько расширений к одной базе.
| Назначение | Для чего | Пример |
|---|---|---|
| Исправление | Срочно закрыть ошибку типовой | Поправить расчёт в одной процедуре до выхода релиза |
| Адаптация | Подогнать типовую под процессы компании | Доп. реквизит, своя печатная форма, кнопка |
| Дополнение | Добавить новую функциональность | Отдельный обмен, интеграция, свой отчёт |
Расширения применяются в порядке «Исправление → Адаптация → Дополнение». Внутри одной группы порядок определяется очерёдностью в списке.
Создание расширения в Конфигураторе
- Откройте базу в Конфигураторе и откройте конфигурацию (
Конфигурация → Открыть конфигурацию). - Выберите
Конфигурация → Расширения конфигурации. - Нажмите «Добавить». В окне свойств задайте имя (латиницей или кириллицей без пробелов), синоним, префикс и назначение.
- Двойным щелчком по строке откройте дерево расширения. Слева появится вторая панель с объектами — это и есть ваше расширение.
Префикс указывается в свойствах расширения один раз. Дальше Конфигуратор сам подставляет его в имена новых объектов и процедур. Совпадение имён с типовой после обновления — частая причина сломанных расширений, префикс от этого защищает.
Заимствование объектов метаданных и новые реквизиты
Расширение не видит типовую конфигурацию целиком. Работать можно только с тем, что вы явно заимствовали.
Как заимствовать объект
- В дереве основной конфигурации найдите объект, например документ «Реализация (акты, накладные)».
- Щёлкните правой кнопкой и выберите «Добавить в расширение».
- Объект появится в дереве расширения с особым значком. Заимствуется «оболочка», без всех реквизитов и форм.
- Чтобы поменять форму, заимствуйте и её: правой кнопкой по форме в дереве основной конфигурации → «Добавить в расширение».
Заимствованный объект подтягивает за собой только то, что нужно для ссылок. Модуль объекта, модуль менеджера и формы появляются пустыми — туда вы и пишете свой код.
Добавление своих объектов и реквизитов
В расширении можно создать с нуля:
- 📁 справочники, документы, регистры, перечисления;
- 📊 отчёты и обработки (в том числе печатные формы);
- 🔐 роли;
- 🧰 общие модули, подписки на события, регламентные задания.
В заимствованный справочник или документ можно добавить свой реквизит или табличную часть. Для этого раскройте объект в дереве расширения и добавьте реквизит, как в обычной конфигурации.
Как только расширение добавляет реквизит или новый объект с данными, оно начинает хранить данные в базе. Удаление такого расширения удалит и эти данные. Поэтому для расширений с данными держите отдельную резервную копию перед любыми экспериментами со снятием.
Контроль свойств заимствованных объектов
У заимствованного объекта в палитре свойств есть флажки контроля. Если включить контроль, например, типа реквизита, то после обновления типовой платформа проверит, не изменился ли он. Изменился — расширение станет неприменимым, и вы узнаете об этом сразу, а не по ошибке у бухгалтера.
Код расширения: аннотации Перед, После, Вместо и ИзменениеИКонтроль
Основной приём при написании расширения — перехват метода типового модуля. Вы не копируете процедуру целиком, а пишете в модуле заимствованного объекта свою процедуру с аннотацией. Платформа сама вызывает её до, после или вместо типовой.
| Аннотация | Когда срабатывает | Когда использовать |
|---|---|---|
&Перед("Имя") | До типового метода | Проверки, подготовка параметров |
&После("Имя") | После типового метода | Донастроить результат, добавить элемент |
&Вместо("Имя") | Вместо метода | Полная замена или вызов по условию через ПродолжитьВызов() |
&ИзменениеИКонтроль("Имя") | Вместо метода, с контролем текста | Поправить несколько строк в середине типовой процедуры |
Перехват с ПродолжитьВызов
Аннотация &Вместо не обязательно отключает типовой код. Внутри своей процедуры вызовите ПродолжитьВызов() — и типовой метод выполнится с теми параметрами, которые вы передадите. Для функции так же получают возвращаемое значение.
&Вместо("ПолучитьСтавкуСкидки")
Функция мп_ПолучитьСтавкуСкидки(Контрагент)
Ставка = ПродолжитьВызов(Контрагент);
// Ограничиваем скидку сверху: не больше 15 процентов
Если Ставка > 15 Тогда
Ставка = 15;
КонецЕсли;
Возврат Ставка;
КонецФункции
Имя ПолучитьСтавкуСкидки здесь условное — подставьте реальный метод из модуля, который заимствовали. Метод с таким именем обязан существовать в типовом модуле, иначе расширение не применится.
ИзменениеИКонтроль: вставки в середину процедуры
Когда нужно поменять одну проверку в процедуре на 200 строк, &Вместо неудобен: придётся переносить всё. Для этого есть &ИзменениеИКонтроль. Конфигуратор копирует текст типового метода в расширение, а вы отмечаете свои правки инструкциями препроцессора.
&ИзменениеИКонтроль("ЗаполнитьПоОснованию")
Процедура мп_ЗаполнитьПоОснованию(Основание)
// ... строки типового метода остаются как есть ...
#Вставка
Комментарий = "Создан на основании: " + Строка(Основание);
#КонецВставки
#Удаление
СтарыйВызов(Основание);
#КонецУдаления
КонецПроцедуры
Плюс подхода: после обновления типовой платформа сверяет текст метода с копией. Разработчики поменяли процедуру — расширение отметится как неприменимое, и вы перенесёте правку в новую версию, а не получите тихую поломку.
Быстрый способ создать перехват: откройте модуль заимствованного объекта в основной конфигурации, встаньте на нужную процедуру, правой кнопкой выберите «Добавить в расширение» и тип вызова. Заготовка с аннотацией появится в модуле расширения.
События форм
В заимствованной форме обработчик события назначают в палитре свойств формы или элемента. Рядом с именем события выбирают тип вызова: перед, после или вместо типового обработчика. Свой элемент формы — поле, кнопку, группу — добавляют в дерево элементов формы расширения как обычно.
&НаСервере
Процедура мп_ПриСозданииНаСервереПосле(Отказ, СтандартнаяОбработка)
Если Не Пользователи.ЭтоПолноправныйПользователь() Тогда
Элементы.мп_Согласовано.ТолькоПросмотр = Истина;
КонецЕсли;
КонецПроцедуры
Здесь мп_Согласовано — элемент, который вы сами добавили на форму. Метод Пользователи.ЭтоПолноправныйПользователь() есть в типовых конфигурациях на БСП; в самописной базе используйте свою проверку роли через РольДоступна().
Отладка и проверка расширения
Отладчик работает с расширениями так же, как с основной конфигурацией. Точки останова ставятся в модулях расширения клавишей F9, запуск отладки — F5.
Порядок проверки:
- Сохраните расширение и обновите его в базе: в окне расширения нажмите F7 («Обновить конфигурацию базы данных»). Для расширения с данными при этом перестраиваются таблицы.
- Запустите отладку (F5) и откройте объект, который меняли.
- Поставьте точку останова в своей процедуре и убедитесь, что вызов приходит. Если не приходит — проверьте имя метода в аннотации и контекст (
&НаСервере/&НаКлиенте). - Пройдите типовой сценарий целиком: создать, записать, провести, распечатать документ . Ошибка часто вылезает не в вашей процедуре, а дальше по цепочке.
- Проверьте под обычным пользователем, а не только под администратором — права из ролей расширения ведут себя иначе.
Безопасный режим
У расширения есть свойство «Безопасный режим». В нём код не может работать с файлами, COM-объектами, внешними компонентами и привилегированным режимом. Если код расширения пишет файл или ходит в интернет, при загрузке через пользовательский режим безопасный режим нужно снимать явно — иначе получите ошибку выполнения на первой же такой операции.
Снимайте безопасный режим только у тех расширений, код которых вы проверили. Расширение без него выполняется с полными правами на сервере 1С.
Проверка применимости
После обновления типовой откройте список расширений в Конфигураторе. Если заимствованный объект или контролируемый метод изменился, расширение помечается как неприменимое и не подключается. Сообщение в окне подскажет, какой объект или метод расходится.
Выгрузка .cfe, загрузка в рабочую базу и версии
Готовое расширение переносят файлом .cfe.
Выгрузка из тестовой базы
- Сохраните последние правки в расширении.
- В окне
Конфигурация → Расширения конфигурациивыделите расширение и в меню «Действия» выберите сохранение в файл. - Укажите имя файла. Удобно добавлять номер версии:
мп_Доработки_1.0.3.cfe.
Номер версии задаётся в свойстве «Версия» расширения. Поднимайте его при каждой выдаче в рабочую базу — так проще понять, что сейчас стоит у пользователей.
Загрузка в рабочую базу
Два способа:
| Способ | Где | Когда удобен |
|---|---|---|
| Конфигуратор | Конфигурация → Расширения конфигурации, в меню «Действия» — загрузка из файла, затем F7 | Расширение с данными, нужна проверка применимости |
| Пользовательский режим | Администрирование → Печатные формы, отчеты и обработки → Расширения (в конфигурациях на БСП) | Быстрая замена без Конфигуратора |
Загрузка файла и обновление конфигурации базы данных — два отдельных шага. Пока не выполнен второй, пользователи работают со старой версией.
Для расширения, которое меняет структуру данных, обновление требует монопольного доступа или динамического обновления, а пользователи увидят изменения после перезапуска сеанса. Делайте это вне рабочего времени и предупредите людей: сеансы придётся завершить.
Хранилище и Git
Расширение можно подключить к своему хранилищу конфигурации: в окне расширения есть отдельные команды для работы с хранилищем. Командам из нескольких разработчиков это обязательно — иначе правки перетирают друг друга.
Для Git выгружайте расширение в XML-файлы командой выгрузки в файлы из меню «Действия» окна расширений или ведите разработку сразу в 1С:EDT. Тексты модулей и XML-описания объектов ложатся в репозиторий, видно каждое изменение.
Ограничения платформы и частые сбои
Расширение — не замена правке конфигурации на все случаи.
Чего расширение не умеет или умеет с оговорками:
- 🚫 изменить тип или удалить реквизит типового объекта;
- 🚫 переименовать типовые объекты и их реквизиты;
- ⚠️ перехватить метод, которого нет в типовом модуле, — аннотация упадёт при применении;
- ⚠️ перехватить метод не в том модуле: аннотацию пишут в заимствованном модуле, где метод объявлен, а не там, откуда его вызывают;
- ⚠️ работать в режиме совместимости выше, чем у основной конфигурации.
Когда расширение не подходит
Если доработка переписывает половину типового модуля, тянет десятки перехватов &Вместо и меняет структуру типовых регистров, расширение превращается в хрупкую копию. Каждое обновление будет его ломать. В таком случае честнее снять конфигурацию с поддержки частично или пересмотреть задачу.