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

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

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

1. Что подготовить перед созданием обработки

Для работы нужны три вещи:

• 🖥️ установленная платформа 1С:Предприятие 8.3 с компонентом Конфигуратора;
• 🗄️ копия рабочей базы или любая база с той же конфигурацией;
• 🔑 пользователь с правом входа в Конфигуратор.

Копия нужна по двум причинам. Обработка на этапе отладки может записать в базу что угодно. А ещё Конфигуратор подставляет типы данных открытой базы: если обработка будет работать с Справочник.Контрагенты из Бухгалтерии 3.0, открывать Конфигуратор надо именно в базе Бухгалтерии.

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

Обработка, отчёт или расширение

Перед стартом решите, что именно вы делаете. От этого зависит тип файла.

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

2. Как создать внешнюю обработку в Конфигураторе

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

У обработки есть несколько веток в дереве объекта. Нужны не все:

• 📌 Реквизиты — переменные уровня объекта, видны в форме и коде (например, дата отбора);
• 📋 Табличные части — таблицы внутри обработки, в них удобно выводить результат;
• 🪟 Формы — интерфейс; одна форма назначается основной;
• 📄 Макеты — шаблоны печатных форм, табличные документы, двоичные данные;
• 🧩 Модуль объекта — общий код, который можно вызвать из формы и из других обработок.

Для примера добавьте табличную часть Список с двумя реквизитами:

• Контрагент, тип СправочникСсылка.Контрагенты;
• ИНН, тип «Строка», длина 12.

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

3. Модуль объекта и модуль формы: где писать код внешней обработки

В управляемом интерфейсе код живёт в двух местах, и путаница между ними — главная причина ошибок у новичков.

Модуль объекта открывается кнопкой «Действия → Открыть модуль объекта» в окне обработки или из контекстного меню корня дерева. Он выполняется на сервере. Сюда пишут:

• общую логику, которая не зависит от формы;
• экспортные процедуры для вызова снаружи;
• функцию регистрации СведенияОВнешнейОбработке() (о ней в разделе 6).

Модуль формы открывается на вкладке «Модуль» внизу редактора формы. Каждая процедура в нём помечается директивой:

Запросы к базе с клиента не выполняются. Кнопка на форме вызывает клиентскую процедуру, а та уже вызывает серверную.

Если логика лежит в модуле объекта, из формы до неё добираются так:

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

РеквизитФормыВЗначение превращает данные формы в настоящий объект обработки, а ЗначениеВРеквизитФормы возвращает изменения обратно на форму. Без второй строки заполненная табличная часть на экране останется пустой.

4. Запрос к базе: заполняем табличную часть

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

Полный серверный код для примера:

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

	Объект.Список.Очистить();

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

	Выборка = Запрос.Выполнить().Выбрать();
	Пока Выборка.Следующий() Цикл
		НоваяСтрока = Объект.Список.Добавить();
		ЗаполнитьЗначенияСвойств(НоваяСтрока, Выборка);
	КонецЦикла;

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

ЗаполнитьЗначенияСвойств копирует поля с одинаковыми именами. Поэтому псевдонимы в запросе (КАК Контрагент, КАК ИНН) должны совпадать с именами реквизитов табличной части.

Несколько правил, которые избавляют от тормозов:

• ⚡ не обращайтесь к реквизитам через точку внутри цикла (Выборка.Контрагент.ИНН) — каждое такое обращение идёт в базу отдельно; выбирайте нужные поля в самом запросе;
• 📦 тяжёлые запросы по регистрам строите к виртуальным таблицам (Остатки, Обороты) с параметрами, а не к основной таблице регистра;
• 🧮 если строк десятки тысяч, не выводите их на форму целиком — сначала посчитайте итог запросом.

5. Форма внешней обработки: реквизиты, кнопки, вывод результата

1. В дереве обработки щёлкните правой кнопкой по ветке «Формы» и выберите «Добавить».
2. В конструкторе формы оставьте тип «Форма обработки» и отметьте флажок «Назначить форму основной». Без основной формы файл откроется, но пользователь ничего не увидит.
3. Нажмите «Готово». Откроется редактор с тремя областями: элементы, реквизиты и команды.

Вывести табличную часть на форму просто: перетащите Объект → Список из панели реквизитов в дерево элементов. Платформа создаст таблицу с колонками.

Теперь кнопка:

1. На вкладке «Команды» добавьте команду Заполнить.
2. В свойстве «Действие» нажмите на лупу — Конфигуратор создаст в модуле процедуру с директивой &НаКлиенте.
3. Перетащите команду в командную панель формы или в дерево элементов.
4. В созданной процедуре вызовите серверную часть:

&НаКлиенте
Процедура Заполнить(Команда)
	ЗаполнитьНаСервере();
	Если Объект.Список.Количество() = 0 Тогда
		ПоказатьПредупреждение(, "Контрагентов без ИНН не найдено.");
	КонецЕсли;
КонецПроцедуры

Колонки, которые пользователь не должен менять, переведите в «Только просмотр» в свойствах элемента. Для параметров (даты, организации) добавьте реквизиты обработки и вытащите их на форму полями ввода.

6. Сохранение файла .epf и публикация для пользователей

После правок сохраняйте файл через Файл → Сохранить или Ctrl+S. При сохранении Конфигуратор проверяет синтаксис модулей, но запустить обработку с ошибкой компиляции всё равно не получится. Отдельно проверить модуль можно через Ctrl+F7.

Дальше два пути доставки до пользователя.

Открыть через меню «Файл»

Пользователь выбирает в главном меню программы Файл → Открыть (Ctrl+O) и указывает файл .epf. Способ подходит для разовых задач. Но у пользователя должна быть роль с правом интерактивного открытия внешних обработок. В типовых конфигурациях на БСП его даёт роль «Интерактивное открытие внешних отчетов и обработок», обычно она есть только у администратора.

Зарегистрировать как дополнительную обработку

Это правильный способ для работы без прав администратора. Администратор один раз добавляет файл в базу, а пользователи запускают обработку из раздела программы, и право на открытие файлов им не выдают.

Чтобы обработку можно было зарегистрировать, в модуле объекта должна быть экспортная функция регистрации. Минимальный вариант для конфигураций на БСП:

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

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

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

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

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

Порядок регистрации в Бухгалтерии 3.0:

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

В ЗУП 3.1 и УТ 11 механизм тот же, только пункт лежит в разделе НСИ и администрирование → Печатные формы, отчеты и обработки. После регистрации обработка появится в выбранном разделе по команде «Дополнительные обработки».

7. Запуск и отладка внешней обработки в режиме 1С:Предприятие

Отладчик показывает значения переменных на каждом шаге, поэтому не нужно расставлять Сообщить() по всему коду.

1. Откройте файл .epf в Конфигураторе той же базы и поставьте точку останова: курсор на строку, F9.
2. Запустите отладку: Отладка → Начать отладку → 1С:Предприятие или F5.
3. В открывшейся программе выберите Файл → Открыть и укажите тот же файл, который открыт в Конфигураторе. Путь должен совпадать до символа, иначе точки останова не сработают.
4. Нажмите кнопку на форме. Выполнение остановится, Конфигуратор покажет значения переменных: наведите на имя или добавьте выражение в табло (Shift+F9).
5. Дальше — пошагово: F11 с заходом в процедуру, F10 без захода, F5 продолжить.

Поменяли код — сохраните файл, закройте форму обработки в программе и откройте файл заново. Перезапускать сеанс не требуется.

Для клиент-серверной базы серверный код отлаживается, только если на сервере 1С разрешена отладка. Это настраивает администратор сервера при запуске службы. Если точки в серверных процедурах «не ловятся», а в клиентских ловятся, причина почти всегда в этом. Проверить, к каким процессам подключён отладчик, можно в окне Отладка → Подключение.

8. Безопасный режим и другие ограничения платформы

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

Защита от опасных действий

Платформа 8.3 актуальных версий предупреждает при открытии внешнего файла, что он может быть небезопасен. Предупреждение управляется флажком «Защита от опасных действий» в свойствах пользователя: в Конфигураторе это Администрирование → Пользователи, карточка пользователя. Снимать флажок у рядовых пользователей не стоит: предупреждение реально спасает от присланных «обработок для исправления».

Что запрещает безопасный режим

Зарегистрированная с параметром БезопасныйРежим = Истина обработка работает в песочнице. В ней нельзя:

• 🚫 читать и писать файлы на диске;
• 🚫 создавать COM-объекты и подключать внешние компоненты;
• 🚫 запускать внешние программы;
• 🚫 включать привилегированный режим;
• 🚫 обращаться к интернет-ресурсам без отдельного разрешения.

Если обработке нужен файл или HTTP-запрос, поставьте БезопасныйРежим = Ложь. При регистрации администратор увидит, какие права запрашивает файл, и решит, доверять ли ему.

Облачные базы

В облачных сервисах на технологии 1cFresh нельзя просто открыть .epf. Файл проходит проверку у провайдера сервиса, и только после этого его можно подключить к приложению. Закладывайте на это время, если делаете обработку для клиента в облаке.

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