Как правильно использовать параметры и области в текстовом макете 1С?

← На главную

При разработке интеграций, формировании структурированных файлов или выгрузке текстовых данных разработчики часто обращаются к макетам типа Текстовый документ. Однако попытка заполнить параметры напрямую в исходном объекте макета приводит к ошибке или отсутствию подстановки данных. Разберем по шагам, как устроен механизм текстовых макетов в платформе 1С, почему прямая запись в макет не работает и как правильно выводить заполненные секции в результирующий документ.

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

Проанализируем типичную ошибку начинающих разработчиков. Часто встречается следующий подход к заполнению:


лМакет = ПолучитьМакет("Message_ЦБ_ЭД");
лМакет.Параметры.СтатусЗаказа = "Согласовано";
лМакет.Записать("e:\REPO\ОбменЦБ\Message_ЦБ_ЭД.xml", КодировкаТекста.UTF8);

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

Правила разметки текстового макета

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

Объявление областей: секция начинается с директивы #Область <ИмяОбласти> и завершается директивой #КонецОбласти. При этом закрывать область не обязательно: начало следующей области автоматически завершает предыдущую.
Обозначение параметров: имена параметров заключаются в прямые квадратные скобки: [ИмяПараметра].
Последовательность: области в текстовом документе располагаются последовательно. Вложенные или пересекающиеся области платформой не поддерживаются.

Посмотрим на пример структуры текстового макета с именем Message_ЦБ_ЭД:


#Область Шапка
<?xml version="1.0" encoding="UTF-8"?>
<Packet ID="[ИдентификаторПакета]" Date="[ДатаПакета]">
#КонецОбласти

#Область Строка
    <Order Number="[НомерЗаказа]" Status="[СтатусЗаказа]"/>
#КонецОбласти

#Область Подвал
</Packet>
#КонецОбласти

Пошаговый алгоритм заполнения и вывода текстового макета

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


// 1. Получаем исходный макет из метаданных обработки или общего макета
Макет = ПолучитьМакет("Message_ЦБ_ЭД");

// 2. Создаем новый текстовый документ для результата
Результат = Новый ТекстовыйДокумент;

// 3. Получаем и заполняем область шапки
ОбластьШапка = Макет.ПолучитьОбласть("Шапка");
ОбластьШапка.Параметры.ИдентификаторПакета = "PKG-2024-001";
ОбластьШапка.Параметры.ДатаПакета = Формат(ТекущаяДатаСеанса(), "ДФ=yyyy-MM-dd");
Результат.Вывести(ОбластьШапка);

// 4. В цикле получаем и выводим строки
Для Каждого СтрДанных Из ТаблицаЗаказов Цикл
    ОбластьСтрока = Макет.ПолучитьОбласть("Строка");
    ОбластьСтрока.Параметры.НомерЗаказа = СтрДанных.Номер;
    ОбластьСтрока.Параметры.СтатусЗаказа = ?(СтрДанных.Согласован, "Согласовано", "Не согласовано");
    Результат.Вывести(ОбластьСтрока);
КонецЦикла;

// 5. Выводим подвал документа
ОбластьПодвал = Макет.ПолучитьОбласть("Подвал");
Результат.Вывести(ОбластьПодвал);

// 6. Сохраняем готовый файл на диск или отображаем пользователю
Результат.Записать("e:\REPO\ОбменЦБ\Message_ЦБ_ЭД.xml", КодировкаТекста.UTF8);

Ограничения текстовых макетов и альтернативные решения

Выясним особенности и ограничения использования текстовых макетов при решении прикладных задач:

Форматирование и обрезка строк: если в параметрах текстового макета не заданы позиционные ограничители ширины, длинные строковые значения могут обрезаться или смещать соседний текст.
Экранирование спецсимволов: при генерации XML- и JSON-структур через текстовый макет платформа не производит автоматическое экранирование спецсимволов (таких как &, <, >, "). Если значение параметра содержит эти знаки, результирующий файл окажется синтаксически невалидным.
Специализированные объекты для XML/JSON: для формирования структурированных файлов формата XML и JSON безопаснее и удобнее использовать объекты ЗаписьXML, ФабрикаXDTO, СериализаторXDTO или ЗаписьJSON.
Метод СтрШаблон(): для небольших фрагментов текста или шаблонов без циклов создание макета с областями избыточно — достаточно применить встроенную функцию СтрШаблон() или СтрЗаменить().
Потоковая запись больших файлов: при формировании больших объемов выгрузки использование результирующего документа ТекстовыйДокумент приводит к повышенному расходу оперативной памяти. В таких случаях предпочтительно использовать объект ЗаписьТекста с последовательной записью строк в поток.