Своё расширение конфигурации 1С с нуля: от пустого файла до работы у пользователей
Содержание
Новое расширение создают в Конфигураторе: Конфигурация → Расширения конфигурации, кнопка «Добавить». Задайте имя, префикс и назначение, откройте дерево расширения и добавьте в него нужные объекты основной конфигурации через контекстное меню «Добавить в расширение». После правок выполните «Обновить конфигурацию
базы данных» для расширения — и доработка заработает без снятия типовой с поддержки.
Расширения появились в платформе 8.3.6 и сегодня это основной способ дорабатывать типовые БП 3.0, ЗУП 3.1, УТ 11 и ERP. Типовая обновляется как обычно, а ваш код живёт отдельно и подключается поверх. Механизм общий для платформы, от конфигурации зависит только то, какие объекты вы будете дорабатывать.
Подготовка: что проверить до создания расширения
Расширение не требует включать возможность изменения основной конфигурации. Это главный плюс: поддержка поставщика остаётся «на замке», типовые обновления ставятся без сравнения и объединения.
Перед стартом проверьте несколько вещей:
- 🧩 Версия платформы. Чем новее, тем больше можно: добавлять реквизиты в заимствованные справочники и документы, использовать аннотацию
&ИзменениеИКонтроль, заимствовать больше видов объектов. Работайте на актуальной 8.3.2x. - 🗄️ Тестовая копия базы. Разрабатывайте на копии, а не в рабочей базе. Выгрузка
.dtили копия каталога файловой базы — пять минут работы. - 🔑 Права. Для добавления расширений в Конфигураторе нужен пользователь с административными правами.
- 📐 Режим совместимости. У расширения есть свой режим совместимости. Он не должен быть выше, чем у основной конфигурации, иначе расширение не применится.
Заранее решите, одно это будет расширение или несколько. Удобная практика — отдельное расширение под каждую независимую задачу: печатную форму, доработку проведения, интеграцию. Так проще отключить одну доработку, не трогая остальные.
Как создать новое расширение в Конфигураторе
Шаг 1. Добавить пустое расширение
- Откройте базу в режиме Конфигуратора.
- Выберите
Конфигурация → Расширения конфигурации. - В открывшемся списке нажмите «Добавить».
- В окне свойств заполните поля (подробнее в таблице ниже).
- Двойной щелчок по строке или кнопка «Конфигурация» откроет дерево расширения — оно выглядит как обычное дерево конфигурации, только почти пустое.
| Свойство | Что вписать | Зачем |
|---|---|---|
| Имя | ПечатьАктаСверки — латиница или кириллица без пробелов | Идентификатор расширения в базе |
| Синоним | Понятное название для пользователя | Видно в списке расширений в режиме Предприятия |
| Префикс | Короткий, например пак_ | Добавляется к именам новых объектов и процедур, чтобы не пересечься с типовой |
| Назначение | Исправление, Адаптация или Дополнение | Определяет порядок применения при нескольких расширениях |
Шаг 2. Выбрать назначение
Назначение влияет на очерёдность, в которой платформа применяет расширения поверх конфигурации:
- 🩹 Исправление — срочные правки ошибок типовой. Применяется первым.
- 🛠️ Адаптация — изменение поведения типовой под процессы компании.
- ➕ Дополнение — новая функциональность: отчёты, обработки, справочники.
Для одной доработки внутри компании обычно выбирают «Адаптацию» или «Дополнение». Ошибка в выборе не фатальна, свойство можно поменять позже.
Шаг 3. Сохранить и обновить
После любых изменений в дереве расширения выполните «Обновить конфигурацию базы данных» (F7), когда активно именно окно расширения. Обновление основной конфигурации и расширения — разные команды: если окно основной конфигурации в фокусе, F7 расширение не затронет.
Заимствование объектов и доработка форм
Заимствовать — значит добавить в расширение «ссылку» на объект основной конфигурации, чтобы менять его поведение.
Как заимствовать объект
- Откройте дерево основной конфигурации (
Конфигурация → Открыть конфигурацию). - Найдите объект, например документ «Реализация (акт, накладная, УПД)».
- Правый клик → «Добавить в расширение» и выберите нужное расширение.
Объект появится в дереве расширения с особым значком. Модуль объекта в расширении изначально пустой: в нём вы пишете только свои процедуры, типовой код остаётся в основной конфигурации.
Новые реквизиты в типовом объекте
В заимствованный справочник или документ можно добавить собственный реквизит или табличную часть. Имя получит префикс расширения, например пак_ОтветственныйЗаОтгрузку. Данные хранятся в базе, а после отключения расширения просто перестают быть видны.
Если расширение меняет структуру данных, то при его удалении сохранённые в новых реквизитах значения будут потеряны. Перед удалением такого расширения в рабочей базе сделайте резервную копию.
Доработка формы
- В дереве основной конфигурации раскройте объект → «Формы».
- Правый клик по форме → «Добавить в расширение».
- Откройте заимствованную форму в дереве расширения.
В редакторе формы элементы типовой отображаются серыми — их нельзя удалить, но можно скрыть, переместить и поменять часть свойств. Свои поля, кнопки и группы добавляйте как обычно. Чтобы вывести на форму новый реквизит, перетащите его из реквизитов объекта в дерево элементов.
Контроль свойств
У заимствованного объекта есть свойства, которые расширение «помнит» в состоянии на момент заимствования. Если отметить их как контролируемые, а поставщик потом изменит это свойство в типовой, расширение не применится и выдаст ошибку. Это защита от тихих поломок: лучше явный отказ, чем код, работающий с изменившимся объектом.
Обработчики событий: &Перед, &После, &Вместо
Собственная логика подключается через аннотации перед процедурами в модуле заимствованного объекта. В аннотации указывается имя процедуры типовой, которую вы перехватываете.
| Аннотация | Когда выполняется ваш код | Где уместна |
|---|---|---|
&Перед | До типовой процедуры | Предзаполнение, дополнительные проверки |
&После | После типовой процедуры | Дозаполнение, движения по своим регистрам |
&Вместо | Вместо типовой; вызвать её можно через ПродолжитьВызов() | Полная замена логики |
&ИзменениеИКонтроль | Копия типовой процедуры с вашими вставками и удалениями | Правка нескольких строк внутри большой процедуры |
Пример: запретить проведение реализации без комментария. В модуле объекта заимствованного документа:
&После("ОбработкаПроверкиЗаполнения")
Процедура пак_ОбработкаПроверкиЗаполнения(Отказ, ПроверяемыеРеквизиты)
Если ПустаяСтрока(Комментарий) Тогда
ОбщегоНазначения.СообщитьПользователю(
"Заполните комментарий к документу",
ЭтотОбъект, "Комментарий", "Объект", Отказ);
КонецЕсли;
КонецПроцедуры
ОбщегоНазначения.СообщитьПользователю — процедура Библиотеки стандартных подсистем, она есть в БП, ЗУП, УТ и других типовых на БСП. В самописной конфигурации используйте объект СообщениеПользователю.
Как работает &ИзменениеИКонтроль
Платформа копирует текст исходной процедуры в расширение. Свои строки вы обрамляете #Вставка … #КонецВставки, ненужные — #Удаление … #КонецУдаления:
&ИзменениеИКонтроль("ЗаполнитьПоОснованию")
Процедура пак_ЗаполнитьПоОснованию(Основание)
// ... текст типовой процедуры ...
#Вставка
Комментарий = "Создан на основании";
#КонецВставки
// ... продолжение типовой процедуры ...
КонецПроцедуры
Если поставщик изменит текст исходной процедуры, расширение перестанет применяться. Так вы узнаете о конфликте сразу после обновления, а не от бухгалтера через месяц.
События формы
В заимствованной форме выделите форму или элемент, откройте палитру свойств и найдите нужное событие. У обработчика в расширении выбирается тип вызова: перед, после или вместо типового. Конфигуратор создаст процедуру в модуле формы расширения с префиксом в имени.
&Вместо без вызова ПродолжитьВызов() полностью отключает типовой код. После обновления типовой вы не получите исправлений поставщика в этой процедуре. Используйте &Вместо только когда без него действительно нельзя.
Общие модули в расширении
Общие модули решают две задачи.
Свой общий модуль. Создайте в дереве расширения новый общий модуль (Общие модули → Добавить) и вынесите туда функции, которые вызываются из нескольких мест: расчёты, обращения к внешним сервисам, формирование текстов. Настройте флажки «Сервер», «Клиент», «Вызов сервера» так же, как в обычной конфигурации.
Заимствованный общий модуль. Если нужно поменять поведение типовой функции, которую вызывает весь код конфигурации, заимствуйте общий модуль и перехватите функцию через &Вместо или &ИзменениеИКонтроль. Изменение подхватят все места, где функция вызывается.
Пример своей функции в общем модуле расширения:
Функция пак_СуммаСНДС(Сумма, СтавкаПроцентов) Экспорт
Возврат Окр(Сумма * (100 + СтавкаПроцентов) / 100, 2);
КонецФункции
Роли и права
Новые объекты расширения по умолчанию недоступны пользователям без полных прав. Это самая частая жалоба «у меня отчёт есть, а у бухгалтера нет». Варианты решения:
- 🔐 создать в расширении собственную роль с правами на новые объекты и включить её в профили групп доступа;
- 🔐 заимствовать типовую роль и в расширении отметить права на свои объекты.
Загрузка расширения в рабочую базу и обновление
Выгрузка файла .cfe
В Конфигураторе, когда активно окно расширения, выберите Конфигурация → Сохранить конфигурацию в файл. Получится файл с расширением .cfe — его и переносят в рабочую базу.
Загрузка через режим Предприятия
В типовых на БСП: Администрирование → Печатные формы, отчеты и обработки → Расширения. Кнопка «Добавить из файла» → выбрать .cfe. Расширение станет активным после перезапуска сеансов.
В списке расширений есть флажок безопасного режима. В безопасном режиме код не может работать с файлами, COM-объектами и внешними компонентами. Если ваш код это делает, снимите флажок — платформа запросит подтверждение.
Загрузка через Конфигуратор и командную строку
В Конфигураторе: Конфигурация → Расширения конфигурации, выделить строку → Конфигурация → Загрузить конфигурацию из файла, затем F7.
Для автоматизации в пакетном режиме:
"C:\Program Files\1cv8\8.3.25.1374\bin\1cv8.exe" DESIGNER /S srv1c\buh /N Админ /P Пароль ^
/LoadCfg "D:\ext\PechatAkta.cfe" -Extension ПечатьАктаСверки ^
/UpdateDBCfg -Extension ПечатьАктаСверки /Out "D:\ext\log.txt"
Путь к платформе подставьте свой. Загрузка .cfe и обновление конфигурации
базы данных — отдельные шаги: без /UpdateDBCfg расширение будет загружено, но не применено.
Клиент-серверный вариант
Расширение хранится в самой информационной базе, а не на компьютере пользователя. Отдельно «публиковать» его на каждом рабочем месте не нужно: после загрузки пользователи получат доработку при следующем входе. Для веб-клиента и тонкого клиента через веб-публикацию порядок тот же.
Если расширение меняет структуру данных, обновление в рабочей базе может потребовать монопольного доступа. Планируйте загрузку на нерабочее время и предупредите пользователей: их сеансы придётся завершить.
Обновление новой версии
Новую версию загружают поверх старой с тем же именем расширения. Данные в реквизитах, добавленных расширением, сохраняются, если вы не удалили и не переименовали сами реквизиты.
Отладка и типичные ошибки расширений
Отладчик Конфигуратора работает с расширениями так же, как с основной конфигурацией. Ставьте точки останова прямо в модулях расширения (F9) и запускайте отладку (F5). Для отладки серверного кода в клиент-серверной базе служба сервера 1С должна быть запущена с ключом -debug. Включать его на рабочем сервере — только с согласия администратора: для применения нужен перезапуск службы, а он обрывает сеансы пользователей.
Частые ситуации и что с ними делать:
Проверка применимости
После каждого обновления типовой откройте список расширений в Конфигураторе: неприменимые расширения отмечены, а в окне сообщений видна причина. Удобно делать это на тестовой копии до обновления рабочей базы.
Если не помогло
Отключите расширение (флажок «Активно» в режиме Предприятия) и проверьте, воспроизводится ли проблема. Если без расширения всё работает, отключайте свои перехваты по одному и ищите виновника. Если проблема остаётся и без расширения — дело в типовой или данных, а не в вашей доработке.