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

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

Ниже путь целиком, на одном сквозном примере. Обработка «Продажи за период» берёт даты с формы, выбирает документы реализации запросом и показывает их в таблице. Пример подходит для БП 3.0 и УТ 11: в обеих конфигурациях есть документ «Реализация товаров и услуг» и справочник «Контрагенты».

Что подготовить до создания обработки

Обработку не пишут в рабочей базе. Нужны три вещи:

• 🗂️ копия базы — файловая выгрузка .dt или отдельная информационная база с теми же данными;
• 🔑 пользователь с правами администратора в этой копии — для запуска Конфигуратора и отладки;
• 🧩 открытая конфигурация в Конфигураторе (Конфигурация → Открыть конфигурацию). Без неё обработка создаётся, но контекстная подсказка не знает ни одного справочника и документа базы, и имена объектов придётся писать вслепую.

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

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

Шаг 1. Создаём новую внешнюю обработку в Конфигураторе

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

Окно объекта показывает дерево: «Реквизиты», «Табличные части», «Формы», «Команды», «Макеты». Там же есть кнопки для открытия модуля объекта и модуля менеджера.

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

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

• реквизит ДатаНачала, тип «Дата», состав даты «Дата»;
• реквизит ДатаОкончания, тип «Дата», состав даты «Дата»;
• табличная часть Продажи с реквизитами Документ (тип «ДокументСсылка.РеализацияТоваровУслуг»), Контрагент (тип «СправочникСсылка.Контрагенты») и Сумма (тип «Число», 15 знаков, 2 после запятой).

Добавьте их через контекстное меню ветки «Реквизиты» и «Табличные части» → Добавить. Свойства открываются по Alt+Enter или двойным щелчком.

Шаг 2. Форма обработки: поля, таблица и кнопки

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

1. В дереве обработки выделите ветку «Формы» и нажмите Добавить.
2. В конструкторе выберите тип «Форма обработки» и оставьте флажок назначения основной формой.
3. Нажмите Готово — откроется редактор управляемой формы.

Редактор делится на несколько областей. Слева вверху — дерево элементов формы, справа вверху — закладки «Реквизиты» и «Команды», внизу — предварительный просмотр. Переключение между формой и её модулем — закладки «Форма» и «Модуль» в нижней части окна.

Как вывести поля на форму

1. На закладке «Реквизиты» раскройте реквизит Объект. Это сама обработка со всеми её реквизитами.
2. Перетащите мышью ДатаНачала и ДатаОкончания в дерево элементов. Появятся поля ввода.
3. Перетащите туда же табличную часть Продажи. Появится таблица с колонками.
4. У таблицы в свойствах включите «Только просмотр» — результат пользователь править не должен.

Как добавить кнопку

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

После пункта 3 в модуле формы появятся две заготовки процедур. Их и будем заполнять.

Шаг 3. Пишем код обработки: клиент, сервер и модуль объекта

Управляемая форма работает в двух местах. Нажатие кнопки обрабатывается на клиенте, а запросы к базе выполняются только на сервере. Поэтому код всегда разделяют директивами компиляции.

Клиентская часть проверяет даты и вызывает сервер:

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

    Если Не ЗначениеЗаполнено(Объект.ДатаНачала)
        Или Не ЗначениеЗаполнено(Объект.ДатаОкончания) Тогда
        ПоказатьПредупреждение(, "Укажите обе даты периода.");
        Возврат;
    КонецЕсли;

    Если Объект.ДатаНачала > Объект.ДатаОкончания Тогда
        ПоказатьПредупреждение(, "Дата начала позже даты окончания.");
        Возврат;
    КонецЕсли;

    СформироватьНаСервере();

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

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

Модуль формы и модуль объекта — в чём разница

• 📄 Модуль формы — всё, что связано с интерфейсом: кнопки, события полей, заполнение таблицы на форме.
• ⚙️ Модуль объекта — логика, которая не зависит от формы. Её можно вызвать и из другой обработки, и при регистрации в программе (об этом в шаге 6).

Простое правило: если процедура нужна без открытой формы, ей место в модуле объекта. Остальное — в модуле формы.

Шаг 4. Запрос к базе и вывод результата в таблицу

Серверная процедура выбирает проведённые реализации за период и загружает их в табличную часть:

&НаСервере
Процедура СформироватьНаСервере()

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

    Запрос.УстановитьПараметр("ДатаНачала", НачалоДня(Объект.ДатаНачала));
    Запрос.УстановитьПараметр("ДатаОкончания", КонецДня(Объект.ДатаОкончания));

    Объект.Продажи.Загрузить(Запрос.Выполнить().Выгрузить());

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

Разберём три приёма, без которых запросы в обработке быстро ломаются.

1. КонецДня() для правой границы. Дата на форме хранится как полночь. Без КонецДня документы последнего дня, проведённые, скажем, в 15:40, в выборку не попадут.
2. Параметры, а не склейка строк. Значения передают через УстановитьПараметр. Подстановка даты прямо в текст запроса даёт ошибки формата и делает запрос нечитаемым.
3. Конструктор запроса. Текст не обязательно писать руками. Поставьте курсор между кавычками, вызовите контекстное меню → «Конструктор запроса» и выберите таблицы и поля мышью. Конструктор работает с метаданными открытой конфигурации — ещё одна причина открыть её до начала работы.

Если результат нужно обработать построчно

Когда нужна не таблица, а действие над каждой записью, используйте выборку:

Выборка = Запрос.Выполнить().Выбрать();
Итого = 0;
Пока Выборка.Следующий() Цикл
    Итого = Итого + Выборка.Сумма;
КонецЦикла;
Сообщить("Сумма продаж за период: " + Формат(Итого, "ЧДЦ=2"));

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

Шаг 5. Отладка и тестирование обработки

Код, который ни разу не прошёл через отладчик, редко работает с первого раза. Внешнюю обработку отлаживают так:

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

В клиент-серверной базе остановка на серверной процедуре сработает, только если на сервере 1С включена отладка. Если клиентские точки срабатывают, а серверные нет, дело в этом — попросите администратора сервера включить её в окне обслуживания: для этого перезапускают службу агента, и все сеансы пользователей оборвутся.

Что проверить перед тем, как отдавать обработку

• 📅 пустые даты и перевёрнутый период — обработка должна сказать об этом словами, а не падать;
• 📉 период без документов — таблица пустая, без ошибок;
• 📈 большой период, например год, — время формирования приемлемое;
• 👤 запуск под пользователем без полных прав — не все роли видят все документы.

Шаг 6. Публикация обработки для пользователей

Готовый файл .epf можно отдать тремя путями.

Открытие файла напрямую

Пользователь выбирает в главном меню Файл → Открыть и указывает файл. Для этого у него должно быть право «Интерактивное открытие внешних обработок». Платформа при открытии внешнего файла может показать предупреждение о безопасности — это защита от опасных действий, и у пользователя должно хватить знаний ответить на неё осознанно.

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

Регистрация в «Дополнительных отчётах и обработках»

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

Чтобы конфигурация приняла файл, в модуле объекта обработки нужна экспортная функция СведенияОВнешнейОбработке():

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

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

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

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

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

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

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

В ЗУП 3.1 и УТ 11 механизм тот же, он входит в БСП: ищите группу «Печатные формы, отчеты и обработки» в разделе «Администрирование» (в УТ 11 — в «НСИ и администрирование»).

Перенос в расширение

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

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