API pw_Исполнитель

Обработка pw_Исполнитель — движок формирования печатных форм. Принимает макет (из справочника, XML, JSON, *.epf или *.pdwx), получает данные по списку ссылок и возвращает готовый ТабличныйДокумент или набор DOCX-файлов.

Исполнитель зависит только от pw_Ядро. Никаких вызовов к общим модулям или другим обработкам.

Создание объекта

Исполнитель = Обработки.pw_Исполнитель.Создать();

Инициализация ядра выполняется автоматически в ПриСозданииОбъекта.

Публичные переменные

Переменная	Тип	Назначение
`ПараметрыКоманды`	`Структура`, `Неопределено`	Параметры команды печати БСП (МассивОбъектов, ПараметрыПечати, КоллекцияПечатныхФорм и др.). Заполняется до вызова `Печать()`, если исполнитель вызывается из обработчика `ПриПечати`.
`Функции`	`ФиксированнаяСтруктура`	Список функций макета. Обновляется после `Загрузить()` и перед `Печать()`. Ключ — имя функции, значение — алгоритм.

Загрузка макета

Загрузить(Значение)

Универсальный загрузчик. Автоматически определяет формат по типу и содержимому значения.

Тип `Значение`	Делегирует в
`СправочникСсылка.pw_Макеты`, `СправочникОбъект.pw_Макеты`	`ЗагрузитьИзМакета`
`Строка` с XML-содержимым	`ЗагрузитьИзXML`
`Строка` с JSON-содержимым	`ЗагрузитьИзJSON`
`Строка` — адрес временного хранилища (*.epf)	`ЗагрузитьИзОбработки`

Исполнитель.Загрузить(СсылкаНаМакет);       // из справочника
Исполнитель.Загрузить(СтрокаXML);           // из XML
Исполнитель.Загрузить(АдресВоХранилище);    // из *.epf

ЗагрузитьИзМакета(Значение)

Загружает из объекта или ссылки справочника pw_Макеты.

Параметры:

Параметр	Тип
`Значение`	`СправочникСсылка.pw_Макеты`, `СправочникОбъект.pw_Макеты`

Вызывает исключение, если справочник pw_Макеты не найден в конфигурации или передан некорректный тип.

ЗагрузитьИзXML(Значение)

Загружает из строки XML в формате XDTO-схемы PrintWizard (namespace http://printwizard.ru/export/vX.X, корневой тип Template).

ЗагрузитьИзJSON(Значение)

Загружает из строки JSON в формате pw_СериализаторКлиентСервер — внутренний формат (Макет) или экспортный (МакетНаЭкспорт).

ЗагрузитьИзСхемы(СхемаМакета)

Загружает из структуры схемы (десериализованный объект внутреннего или экспортного формата).

Параметр	Тип
`СхемаМакета`	`Структура` — формат `Макет` или `МакетНаЭкспорт` из `pw_СериализаторКлиентСервер`

ЗагрузитьИзОбработки(АдресХранилища, ИмяМакета = "")

Загружает макет из внешней *.epf обработки. Поддерживает оба формата:

до версии 2025.2: код инициализации в модуле объекта;
начиная с 2025.2: XML в текстовом макете pw_[Идентификатор].

Параметр	Тип	Описание
`АдресХранилища`	`Строка`	Адрес временного хранилища с двоичными данными *.epf
`ИмяМакета`	`Строка`	Идентификатор макета. Если не указан — загружается первый из таблицы команд

Возможные исключения:

некорректный адрес временного хранилища;
ошибка подключения внешней обработки;
файл не содержит макетов PrintWizard;
не определены команды для печати;
ошибка при получении макета.

ЗагрузитьИзPDWX(АдресХранилища, Пароль = "")

Загружает макет из файла *.pdwx (ZIP-архив с XML или JSON).

Параметр	Тип	Описание
`АдресХранилища`	`Строка`	Адрес временного хранилища с двоичными данными *.pdwx
`Пароль`	`Строка`	Пароль к архиву, если установлен

Выполнение печати

Подготовлен() → Булево

Возвращает Истина, если макет успешно загружен. Проверять перед вызовом Печать().

Если НЕ Исполнитель.Подготовлен() Тогда
    // обработать ошибку загрузки
КонецЕсли;

Печать(Значение, Параметры = Неопределено, Отказ = Ложь) → Структура

Выполняет полный цикл: подготовка параметров → выполнение запросов → формирование наборов данных → рендеринг макета.

Параметры:

Параметр	Тип	Описание
`Значение`	`ЛюбаяСсылка`, `Массив`, `ФиксированныйМассив`	Ссылка или массив ссылок на объекты печати
`Параметры`	`Структура`, `Неопределено`	Входящие параметры для события `ПередИнициализацией`
`Отказ`	`Булево`	Выходной параметр; `Истина`, если событие `ПередИнициализацией` установило отказ

Возвращаемое значение — Структура:

Ключ	Тип	Описание
`Выполнено`	`Булево`	`Истина`, если печать прошла без ошибок
`Документы`	`ТабличныйДокумент` / `Соответствие` / `Неопределено`	Для XLS-макетов — `ТабличныйДокумент`; для DOCX — `Соответствие<ИмяФайла, ДвоичныеДанные>`
`Отказ`	`Булево`	Признак отказа от инициализации
`ТекстОтказа`	`Строка`	Комментарий, установленный при отказе
`ЕстьОшибки`	`Булево`	Признак наличия ошибок в журнале

Исполнитель = Обработки.pw_Исполнитель.Создать();
Исполнитель.Загрузить(СсылкаНаМакет);

Отказ = Ложь;
Результат = Исполнитель.Печать(МассивОбъектов,, Отказ);

Если НЕ Результат.Выполнено Тогда
    // см. ТекстОшибок()
КонецЕсли;

Диагностика

ТекстОшибок(Расширенный = Ложь) → Строка

Возвращает текст всех ошибок журнала, разделённых переносом строки.

Параметр	Тип	Описание
`Расширенный`	`Булево`	Если `Истина`, включает подробный стек ошибки

ЕстьОшибки() → Булево

Возвращает Истина, если журнал содержит хотя бы одну запись уровня «Ошибка».

Функции макета

Функции — именованные алгоритмы, описанные в макете. Вызываются из событий и из прикладного кода.

ПараметрыФункции(КлючИмя) → Структура

Возвращает структуру-шаблон для передачи параметров в функцию. Ключи соответствуют именам параметров функции в порядке объявления.

Параметр	Тип	Описание
`КлючИмя`	`Строка`	Ключ или имя функции

ВыполнитьФункцию(КлючИмя, П1..П10) → Произвольный

Выполняет функцию макета и возвращает её результат.

Параметр	Тип	Описание
`КлючИмя`	`Строка`	Ключ или имя функции
`П1`..`П10`	`Произвольный`	Позиционные параметры или структура из `ПараметрыФункции` первым аргументом

Если П1 — это структура с маркером Типы_ПараметрыАлгоритма, она интерпретируется как именованные параметры. Иначе значения сопоставляются с параметрами по позиции.

// Позиционный вызов
Итог = Исполнитель.ВыполнитьФункцию("РассчитатьСумму", 10, 500);

// Именованный вызов
Пар = Исполнитель.ПараметрыФункции("РассчитатьСумму");
Пар.Количество = 10;
Пар.Цена = 500;
Итог = Исполнитель.ВыполнитьФункцию("РассчитатьСумму", Пар);

Прямая работа с областями макета

Методы для ручного управления выводом внутри событий макета (ПередВыводомОбласти, ПослеВыводаОбласти и др.).

ОбластьМакета(ИмяОбласти, Заполнить = Ложь) → ТабличныйДокумент, Неопределено

Возвращает новый независимый экземпляр шаблона области из текущего макета. Повторный вызов — новый экземпляр. Возвращает Неопределено, если область не найдена.

Параметр	Тип	Описание
`ИмяОбласти`	`Строка`	Имя области в макете
`Заполнить`	`Булево`	Если `Истина`, сразу заполняет параметры из текущего контекста данных

ЗаполнитьПараметрыОбласти(Область, ТолькоПустые = Ложь)

Заполняет параметры области значениями из текущего контекста. Применяет полный механизм: резолвинг полей набора, алгоритмы, форматирование, QR-коды, суммы прописью.

Параметр	Тип	Описание
`Область`	`ТабличныйДокумент`	Шаблон для заполнения
`ТолькоПустые`	`Булево`	Если `Истина`, заполняет только параметры без значения (ручные значения сохраняются)

ВывестиОбласть(Область, ПроверитьВывод = Ложь)

Выводит заполненную область в текущий табличный документ. Не вызывает события ПередВыводомОбласти / ПослеВыводаОбласти.

Параметр	Тип	Описание
`Область`	`ТабличныйДокумент`	Заполненная область
`ПроверитьВывод`	`Булево`	Если `Истина` и область не помещается на текущей странице, вставляет разрыв страницы

// Пример внутри события ПередВыводомОбласти
Область = ЭтотМакет.ОбластьМакета("Заголовок", Истина);
Область.Параметры.Дата = ТекущаяДатаСеанса();
ЭтотМакет.ВывестиОбласть(Область, Истина);

Работа с табличным документом

Обёртки над платформенным API ТабличногоДокумента, доступные из событий макета.

ОбъединитьЯчейки(ТабличныйДокумент, АдресПерваяСтрока, ПерваяКолонка, ПоследняяСтрока, ПоследняяКолонка)

Объединяет ячейки в переданном табличном документе. Параметры адресации соответствуют ТабличныйДокумент.Область(...).

СгруппироватьСтроки(ТабличныйДокумент, ПерваяСтрока, ПоследняяСтрока, ИмяГруппы, РасположениеЗаголовка)

Группирует строки. Если РасположениеЗаголовка не передан — используется Начало.

СгруппироватьКолонки(ТабличныйДокумент, ПерваяКолонка, ПоследняяКолонка, ИмяГруппы, РасположениеЗаголовка)

Группирует колонки. Если РасположениеЗаголовка не передан — используется Начало.

Типичный сценарий интеграции

// 1. Создание и загрузка макета
Исполнитель = Обработки.pw_Исполнитель.Создать();
Исполнитель.Загрузить(СсылкаНаМакет);

Если НЕ Исполнитель.Подготовлен() Тогда
    ВызватьИсключение "Не удалось загрузить макет PrintWizard";
КонецЕсли;

// 2. Передача контекста команды (при вызове из обработчика ПриПечати БСП)
Исполнитель.ПараметрыКоманды = ПараметрыКоманды;

// 3. Запуск печати
Отказ = Ложь;
Результат = Исполнитель.Печать(МассивОбъектов,, Отказ);

Если Отказ Тогда
    Возврат; // событие ПередИнициализацией установило Отказ
КонецЕсли;

Если НЕ Результат.Выполнено Тогда
    ОбщегоНазначения.СообщитьПользователю(
        НСтр("ru='Ошибка при формировании формы:'") + Символы.ПС
        + Исполнитель.ТекстОшибок());
    Возврат;
КонецЕсли;

// 4. Получение результата
Если ЭтотОбъект.IsOfficeOpenXML Тогда
    // Соответствие<ИмяФайла, ДвоичныеДанные>
    Для Каждого Элемент Из Результат.Документы Цикл
        // сохранить Элемент.Значение как Элемент.Ключ + ".docx"
    КонецЦикла;
Иначе
    ТабДок = Результат.Документы; // ТабличныйДокумент
КонецЕсли;