Как обратиться к макету внешней обработки в 1С

Макет внешней обработки в 1С — это ресурс, хранящийся внутри файла .epf: табличный документ, схема компоновки данных, двоичные данные, текст или ActiveX-компонент. К нему обращаются из кода модуля объекта обработки, из модуля формы или из режима «1С:Предприятие» через объект внешней обработки. Выбор способа зависит от того, где выполняется код и как обработка подключена к системе.

Главное отличие от макетов конфигурации в том, что к макету внешней обработки нельзя обратиться через глобальный контекст ПолучитьМакет() или ПолучитьОбщийМакет() — нужен объект обработки. Из-за этого начинающие разработчики часто получают ошибку «Метод объекта не обнаружен» или «Макет не найден», хотя макет в дереве обработки существует.

Ниже разобраны все рабочие способы обращения к макету: из модуля объекта, из формы обработки, из внешнего кода через ВнешниеОбработки.Создать() и при подключении через механизм дополнительных отчетов и обработок (БСП). Для каждого способа приведены условия применения и типичные ошибки.

Какие макеты бывают у внешней обработки и зачем они нужны

Внешняя обработка может содержать макеты тех же типов, что и объекты конфигурации: табличный документ (для печатных форм), схема компоновки данных (для отчетов на СКД), макет оформления компоновки, двоичные данные (картинки, шаблоны Word/Excel), текстовый документ, HTML-документ и другие. Создаются они в конфигураторе: правой кнопкой по ветке «Макеты» в дереве обработки → «Добавить».

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

Важно понимать: макет хранится внутри файла .epf и недоступен напрямую из конфигурации. Любое обращение к нему идет через объект внешней обработки, поэтому первый шаг всегда — получить этот объект.

Обращение к макету из модуля объекта обработки

Самый простой случай — код находится в модуле объекта самой внешней обработки. Здесь доступен контекст объекта, и макет получают методом ПолучитьМакет() с именем макета в качестве параметра:

// Модуль объекта внешней обработки
Функция СформироватьПечатнуюФорму(СсылкаНаДокумент) Экспорт

Макет = ЭтотОбъект.ПолучитьМакет("МакетПечати");

ТабДок = Новый ТабличныйДокумент;
ОбластьШапка = Макет.ПолучитьОбласть("Шапка");
ОбластьШапка.Параметры.НомерДокумента = СсылкаНаДокумент.Номер;
ТабДок.Вывести(ОбластьШапка);

Возврат ТабДок;

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

Ключевое слово ЭтотОбъект в модуле объекта можно опустить — вызов ПолучитьМакет("МакетПечати") тоже сработает, так как контекст объекта доступен неявно. Однако явное указание делает код понятнее и защищает от конфликтов имен.

Если макет — схема компоновки данных, результат ПолучитьМакет() передают в источник настроек компоновщика:

СхемаКомпоновки = ЭтотОбъект.ПолучитьМакет("ОсновнаяСхемаКомпоновкиДанных");
КомпоновщикНастроек.ЗагрузитьНастройки(СхемаКомпоновки.НастройкиПоУмолчанию);

Обращение к макету из модуля формы обработки

Из модуля формы внешней обработки контекст объекта напрямую недоступен — форма работает с данными через реквизиты. Способ обращения зависит от типа формы: обычная или управляемая.

Обычная форма

В обычной форме объект обработки доступен через свойство ЭтотОбъект (если форма основная) или через реквизит формы типа «ВнешняяОбработкаОбъект». Поэтому вызов выглядит так же просто:

// Модуль обычной формы
Макет = ЭтотОбъект.ПолучитьМакет("МакетПечати");

Управляемая форма

В управляемой форме прямого доступа к объекту обработки нет. Стандартный прием — получить объект через реквизит формы, в который обработка передана, либо через РеквизитФормыВЗначение("Объект"), если основной реквизит формы называется «Объект» (так делает БСП для дополнительных отчетов и обработок):

&НаСервере
Функция ПолучитьМакетОбработки(ИмяМакета)

ОбъектОбработки = РеквизитФормыВЗначение("Объект");
Возврат ОбъектОбработки.ПолучитьМакет(ИмяМакета);

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

Если основного реквизита «Объект» нет (форма произвольная), объект создают заново через ВнешниеОбработки.Создать() с указанием имени файла обработки — этот способ разобран ниже. Учтите, что РеквизитФормыВЗначение выполняется только на сервере и требует директивы &НаСервере.

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

Обращение к макету из внешнего кода конфигурации

Когда макет нужен из кода конфигурации (например, из общего модуля или команды документа), сначала создают объект внешней обработки методом ВнешниеОбработки.Создать(). В параметре указывают либо полный путь к файлу .epf, либо имя файла без пути, если обработка зарегистрирована.

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

Обработка = ВнешниеОбработки.Создать("C:\Обработки\ПечатьЗаказа.epf", Ложь);
Макет = Обработка.ПолучитьМакет("МакетПечати");

ТабДок = Новый ТабличныйДокумент;
Область = Макет.ПолучитьОбласть("Шапка");
ТабДок.Вывести(Область);

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

Второй параметр Ложь отключает безопасный режим — используйте его осознанно, только для доверенных файлов. Для обработок из справочника «Дополнительные отчеты и обработки» (БСП) вместо пути к файлу применяют ДополнительныеОтчетыИОбработки.ОбъектВнешнейОбработки(Ссылка) или получают навигационную ссылку двоичных данных из хранилища.

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

Типичные ошибки и их причины

Ошибка «Макет не найден» возникает, когда имя в вызове ПолучитьМакет() не совпадает с именем макета в дереве обработки, либо макет добавлен в форму обработки, а не в саму обработку. Макеты формы и макеты объекта — разные коллекции: из модуля объекта доступны только макеты объекта.

Ошибка «Метод объекта не обнаружен (ПолучитьМакет)» означает, что метод вызван у неправильного объекта — например, у формы в управляемом приложении или у значения, не являющегося объектом обработки. Проверьте, что переменная содержит именно ВнешняяОбработкаОбъект.

Ошибка «Ошибка при вызове метода контекста (Создать)» при обращении к ВнешниеОбработки.Создать() обычно связана с неверным путем к файлу, отсутствием прав на чтение файла у пользователя, под которым работает сервер 1С, или с попыткой выполнить вызов на клиенте без доступа к файлу.

Проверка результата и отладка

После получения макета убедитесь, что возвращается объект ожидаемого типа. Для табличного документа проверьте наличие нужных областей методом Макет.Области.Найти("Шапка") — если вернулось Неопределено, область в макете отсутствует или названа иначе. Это позволяет перехватить проблему до вывода в итоговый документ.

Для отладки откройте внешнюю обработку в конфигураторе через «Файл → Открыть» и поставьте точку останова на строке с ПолучитьМакет(). При отладке внешних обработок убедитесь, что в настройках отладчика разрешена отладка внешних объектов, а файл обработки, открытый в конфигураторе, совпадает с файлом, запущенным в предприятии.

Контрольные точки

Как проверить результат

Тип возвращаемого значения

Норма

ТабличныйДокумент, СхемаКомпоновкиДанных или ДвоичныеДанные — по типу макета

Тревожный признак

Неопределено или исключение «Макет не найден»

Наличие областей в табличном макете

Норма

Макет.Области.Найти("Шапка") возвращает область

Тревожный признак

Возвращается Неопределено — области нет или имя другое

Заполнение параметров

Норма

После вывода области в табличном документе подставлены значения

Тревожный признак

В документе видны пустые места или имена параметров

Часто задаваемые вопросы

Можно ли обратиться к макету внешней обработки через ПолучитьОбщийМакет()?

Нет. Метод ПолучитьОбщийМакет() работает только с общими макетами конфигурации. Макеты внешней обработки доступны исключительно через объект обработки методом ПолучитьМакет().

Как получить макет, если обработка подключена через «Дополнительные отчеты и обработки» БСП?

Получите объект обработки функцией ДополнительныеОтчетыИОбработки.ОбъектВнешнейОбработки(СсылкаНаЭлементСправочника), затем вызовите у него ПолучитьМакет("ИмяМакета"). Хранить путь к файлу в этом случае не нужно — двоичные данные лежат в информационной базе.

Почему в управляемой форме ЭтотОбъект.ПолучитьМакет() не работает?

В управляемой форме ЭтотОбъект — это объект формы, а не объект обработки. Получите объект обработки через РеквизитФормыВЗначение("Объект") на сервере и вызовите ПолучитьМакет() уже у него.

Можно ли получить макет внешней обработки на клиенте?

Метод ПолучитьМакет() для табличных документов и СКД доступен в контексте сервера. На тонком клиенте стандартный путь — серверный вызов, который возвращает готовый табличный документ или помещает данные во временное хранилище.

Что делать, если макет — двоичные данные (шаблон Word или Excel)?

ПолучитьМакет() вернет объект ДвоичныеДанные. Сохраните их во временный файл методом Записать(ИмяФайла), откройте нужным приложением или COM-объектом, заполните и удалите временный файл после использования.

Как передать макет из внешней обработки в отчет на СКД?

Получите схему компоновки: Схема = ОбъектОбработки.ПолучитьМакет("ИмяСхемы"), затем передайте ее в компоновщик настроек или процессор компоновки. В отчетах, созданных как внешние обработки с СКД, схема обычно подключается автоматически через основную схему отчета.