Внешняя обработка 1С 8.3 с нуля: форма, код, отладка и подключение в базу

Чтобы создать обработку в 1С 8.3, откройте конфигуратор любой базы, выберите Файл → Новый → Внешняя обработка, добавьте реквизиты и форму, напишите код в модуле формы и сохраните файл с расширением .epf. Конфигурацию при этом трогать не нужно: внешняя обработка живёт отдельным файлом и не снимает базу с поддержки.

Частое заблуждение новичков — что для своей обработки нужно «снять конфигурацию с замка» и добавить объект в дерево метаданных. Для разовых задач и доработок типовой БП 3.0, ЗУП 3.1 или УТ 11 это лишнее. Встроенные обработки делает разработчик конфигурации, а пользователю и внедренцу почти всегда хватает внешних. Ниже — полная пошаговая инструкция для новичков: от пустого файла до обработки, которая сама появляется в нужном разделе программы.

Что такое обработка в 1С и когда её писать

Обработка — объект, который выполняет действие над данными, но сам ничего не хранит. Документ записывает операцию, справочник — список, регистр — итоги. Обработка же берёт эти данные, что-то с ними делает и закрывается.

Типичные задачи, ради которых разрабатывают обработки:

• 🔄 групповое изменение реквизитов: проставить договор, статью затрат, подразделение у сотен документов;
• 📥 загрузка данных из Excel , CSV или XML, которые не берёт типовой механизм;
• 🧹 поиск ошибок: контрагенты без ИНН, документы с пустым складом, задвоенные номенклатурные позиции;
• 🖨 своя печатная форма или выгрузка в формат банка либо контрагента;
• ⚙️ служебные действия: перезаполнение регистров, массовая отправка писем, пакетное проведение.

Какие бывают обработки: встроенные, внешние, дополнительные

Сначала решите, какой вид нужен. От этого зависит, где вы будете её создавать и как пользователь её откроет.

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

Внутри дополнительных есть свои виды:

• 📌 дополнительная обработка — открывается из раздела программы;
• 📝 заполнение объекта — кнопка в форме документа или справочника;
• 🖨 печатная форма — пункт в меню «Печать»;
• 🔗 создание связанных объектов — создаёт документы на основании выбранных.

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

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

Разберём на рабочем примере: обработка находит в БП 3.0 контрагентов без ИНН и показывает их списком. Задача простая, но в ней есть всё: реквизиты, табличная часть, форма, запрос и серверный вызов.

Шаг 1. Новый файл

1. Запустите базу в режиме «Конфигуратор». Подойдёт копия рабочей базы или демобаза: открывать конфигурацию для редактирования не нужно.
2. Выберите Файл → Новый, в списке — «Внешняя обработка».
3. Откроется окно объекта. В поле «Имя» задайте латиницу или кириллицу без пробелов, например КонтрагентыБезИНН. В поле «Синоним» — человеческое название: «Контрагенты без ИНН».

Шаг 2. Реквизиты и табличная часть

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

1. На вкладке «Табличные части» нажмите «Добавить», имя — Список.
2. Внутри добавьте реквизит Контрагент с типом СправочникСсылка.Контрагенты.
3. На вкладке «Реквизиты» можно добавить флаг ТолькоПокупатели типа «Булево» — пригодится для отбора.

Тип ссылки на справочник появится в списке, потому что вы открыли обработку в конфигураторе конкретной базы. Обработка, созданная в пустой базе, о справочниках БП ничего не знает.

Шаг 3. Форма

1. На вкладке «Формы» нажмите «Добавить». Конструктор предложит тип «Форма обработки» и флажок «Назначить основной» — оставьте как есть, нажмите «Готово».
2. В редакторе формы перетащите табличную часть Список из окна реквизитов в дерево элементов.
3. На вкладке «Команды» создайте команду Заполнить и перетащите её в командную панель формы.

Шаг 4. Код

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

&НаКлиенте
Процедура Заполнить(Команда)
	ЗаполнитьНаСервере();
КонецПроцедуры

&НаСервере
Процедура ЗаполнитьНаСервере()

	Запрос = Новый Запрос;
	Запрос.Текст =
	"ВЫБРАТЬ
	|	Контрагенты.Ссылка КАК Контрагент
	|ИЗ
	|	Справочник.Контрагенты КАК Контрагенты
	|ГДЕ
	|	НЕ Контрагенты.ЭтоГруппа
	|	И НЕ Контрагенты.ПометкаУдаления
	|	И Контрагенты.ИНН = """"
	|
	|УПОРЯДОЧИТЬ ПО
	|	Контрагенты.Наименование";

	ОбработкаОбъект = РеквизитФормыВЗначение("Объект");
	ОбработкаОбъект.Список.Загрузить(Запрос.Выполнить().Выгрузить());
	ЗначениеВРеквизитФормы(ОбработкаОбъект, "Объект");

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

Колонка в запросе называется Контрагент — так же, как реквизит табличной части. Поэтому Загрузить сама разложит значения по строкам.

Шаг 5. Сохранение и запуск

1. Файл → Сохранить, укажите папку и имя КонтрагентыБезИНН.epf.
2. Запустите базу в режиме 1С:Предприятие.
3. Откройте главное меню (кнопка с тремя полосками или стрелкой в левом верхнем углу) и выберите Файл → Открыть, укажите файл.

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

Параметры обработки: реквизиты, отборы и передача данных в форму

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

Реквизиты как поля ввода

Любой реквизит обработки можно вывести на форму как поле. Добавили реквизит Организация типа СправочникСсылка.Организации — перетащили на форму — получили поле выбора. В запросе используйте его через параметр:

Запрос.УстановитьПараметр("Организация", Объект.Организация);

Значения полей лучше проверять до запуска основной логики. Флажок «Проверка заполнения» у реквизита плюс вызов ПроверитьЗаполнение() на сервере дадут подсветку пустых полей без лишнего кода.

Параметры формы

Если обработку открывают из другого кода, данные передают через параметры формы. На вкладке «Параметры» формы добавьте, например, Документ, а при открытии:

ПараметрыФормы = Новый Структура("Документ", ТекущийДокумент);
ОткрытьФорму("ВнешняяОбработка.КонтрагентыБезИНН.Форма.Форма", ПараметрыФормы);

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

Параметры дополнительной обработки

У видов «Заполнение объекта» и «Печатная форма» БСП передаёт в обработку ссылки на объекты, из формы которых её вызвали. В серверной процедуре ВыполнитьКоманду они приходят в ПараметрыВыполненияКоманды.ОбъектыНазначения — это массив ссылок на выбранные документы.

Регистрация в БСП: как сделать обработку дополнительной

Это тот приём, которого обычно не хватает в инструкциях для начинающих. Без него пользователь каждый раз ищет файл через Файл → Открыть. С ним обработка лежит в базе и вызывается из нужного раздела.

В модуль объекта (не формы) добавьте экспортную функцию:

Функция СведенияОВнешнейОбработке() Экспорт

	ПараметрыРегистрации = ДополнительныеОтчетыИОбработки.СведенияОВнешнейОбработке("2.4.1.1");
	ПараметрыРегистрации.Вид = ДополнительныеОтчетыИОбработкиКлиентСервер.ВидОбработкиДополнительнаяОбработка();
	ПараметрыРегистрации.Версия = "1.0";
	ПараметрыРегистрации.БезопасныйРежим = Истина;

	Команда = ПараметрыРегистрации.Команды.Добавить();
	Команда.Представление = "Контрагенты без ИНН";
	Команда.Идентификатор = "ОткрытьФорму";
	Команда.Использование = ДополнительныеОтчетыИОбработкиКлиентСервер.ТипКомандыОткрытиеФормы();
	Команда.ПоказыватьОповещение = Ложь;

	Возврат ПараметрыРегистрации;

КонецФункции

Дальше в режиме 1С:Предприятие:

1. Включите функциональность: Администрирование → Печатные формы, отчеты и обработки, флажок «Дополнительные отчеты и обработки».
2. Перейдите по ссылке «Дополнительные отчеты и обработки» и нажмите «Добавить из файла».
3. Укажите .epf. Программа прочитает функцию регистрации и заполнит карточку: вид, версию, команды.
4. В карточке на вкладке «Размещение» укажите разделы, где появится команда, и пользователей, которым она доступна.
5. Нажмите «Записать и закрыть».

Какой тип команды выбрать

Для серверного вызова в модуле объекта нужна процедура:

Процедура ВыполнитьКоманду(ИдентификаторКоманды, ПараметрыВыполненияКоманды) Экспорт
	Если ИдентификаторКоманды = "ПерезаполнитьСписок" Тогда
		// основная логика
	КонецЕсли;
КонецПроцедуры

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

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

1. В конфигураторе откройте .epf через Файл → Открыть.
2. Поставьте точку останова: курсор на строку, клавиша F9.
3. Запустите режим 1С:Предприятие клавишей F5 («Начать отладку»).
4. В запущенной базе откройте ту же обработку и нажмите кнопку. Выполнение остановится на точке.

Пошаговое выполнение — F11 (с заходом в процедуры) и F10 (без захода). Значение переменной показывает «Вычислить выражение» по Shift+F9.

Если обработку правили в конфигураторе, сохраните файл и откройте её в базе заново. Иначе отлаживаться будет старая версия, и точки останова «не сработают».

В клиент-серверной базе остановка в серверном коде требует, чтобы сервер 1С был запущен с отладкой: агенту ragent передают ключ -debug в параметрах службы. Без этого клиентские точки останавливают выполнение, а серверные — нет. Перезапуск службы сервера 1С обрывает все сеансы пользователей, поэтому ключ включают на тестовом сервере или после рабочего дня.

Оптимизация и правила хорошего тона

Обработка, которая быстро работает на 50 документах, может висеть час на 50 000. Несколько правил снимают большую часть проблем.

Запрос вместо перебора

• 🚫 Не перебирайте справочник через Выбрать() с проверкой условия в цикле. Отбор делайте в запросе, в секции ГДЕ.
• 🚫 Не обращайтесь через точку к реквизитам ссылок в цикле: Документ.Контрагент.ИНН на каждой строке — это отдельное чтение из базы. Получите нужные поля сразу в запросе.
• ✅ Нужно несколько связанных выборок — пишите пакетный запрос с временными таблицами.

Клиент и сервер

Каждый вызов &НаСервере из клиента — это обмен данными по сети. Собирайте всю работу в один серверный вызов, а не вызывайте сервер в цикле по строкам таблицы. Если процедура не обращается к данным формы, помечайте её &НаСервереБезКонтекста: так на сервер не передаётся вся форма.

Запись объектов

• ✍️ Изменяя документы, получайте объект через ПолучитьОбъект() и вызывайте Записать() в попытке, с понятным сообщением об ошибке.
• 🔁 Для проведённых документов решите заранее: перепроводить (РежимЗаписиДокумента.Проведение) или только записать. Перепроведение закрытого периода изменит отчётность.
• 📦 Изменение сотен объектов оборачивайте в транзакции порциями по 100–500 штук. Одна транзакция на 50 000 объектов надолго заблокирует данные для остальных.

Распространение и обновление обработок

Файл .epf можно просто передать коллеге. Но как только обработкой пользуются несколько человек, лучше держать её в базе как дополнительную.

Как выпустить новую версию

1. Внесите правки в конфигураторе.
2. Поднимите номер в ПараметрыРегистрации.Версия: было «1.0», стало «1.1».
3. Сохраните .epf.
4. В карточке дополнительной обработки загрузите новый файл через команду загрузки из файла. Размещение и доступы, настроенные раньше, сохранятся.

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

Хранение исходников

Двоичный .epf неудобно сравнивать между версиями. Его можно разобрать в XML-файлы и хранить в Git:

"C:\Program Files\1cv8\8.3.24.1586\bin\1cv8.exe" DESIGNER /F "D:\Bases\Test" /DumpExternalDataProcessorOrReportToFiles "D:\src\KontragentyBezINN.xml" "D:\epf\КонтрагентыБезИНН.epf"

Обратная сборка — ключ /LoadExternalDataProcessorOrReportFromFiles с теми же двумя путями в обратном порядке. Номер платформы в пути подставьте свой.

Совместимость с релизами

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

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