Оставшийся тег в DOCX обычно означает, что движок не распознал его, не нашёл значение или обрабатывал другую версию шаблона. Начните с одного плейсхолдера и маленького объекта данных. Сохраните исходный DOCX, входной JSON и результат одного запуска: тогда можно определить границу сбоя без реальных реквизитов клиента.
Если поле заменилось пустотой, посмотрите значение до рендеринга и правила обработки отсутствующих ключей. Пустая строка, null, отсутствие свойства и число 0 имеют разный смысл. Генератор должен сообщать об обязательном пропущенном поле до выпуска документа, а допустимое пустое поле обрабатывать по заранее выбранному правилу.
Минимальный пример под выбранный движок
// условные данные для Docxtemplater
{
"company_name": "Компания Тест",
"amount": "1250,00",
"items": [{"name": "Услуга A"}]
}
// текст шаблона
{company_name}
{amount}
{#items}{name}{/items}Синтаксис здесь относится к Docxtemplater. Его документация описывает простые теги в фигурных скобках и секции для циклов и условий. Запись company.name требует поддерживающего её парсера; нельзя предполагать, что любой движок автоматически понимает вложенные свойства. Сначала используйте плоское поле, затем добавляйте вложенность и циклы по одному.
Одинаковый вид на экране не означает одинаковый тег
| Признак | Возможная причина | Контроль |
|---|---|---|
| тег остался целиком | другие delimiters или не тот файл | версия и хеш шаблона |
| пустое поле | ключ отсутствует или null | схема JSON перед render |
| в цикле пусто | изменился текущий scope | данные одного элемента items |
| ошибка компиляции | незакрытая секция | баланс открывающих и закрывающих тегов |
| ломается после правки Word | текст разделён XML-элементами | парсер DOCX вместо замены строки |
DOCX представляет собой ZIP с XML. Docxtemplater объясняет, что Word может разделять видимый тег на несколько XML-элементов. Обычный поиск и замена по байтам тогда пропустит его. Для работы с документом нужен движок, понимающий структуру формата; склейка всего XML в строку рискует повредить оформление и другие части документа.
Секция меняет контекст обращения к полю
Внутри цикла items поле name относится к текущему элементу массива. Если данные имеют items: [{product: {name: ...}}], простой тег name не совпадает со структурой. В секции объекта также меняется область данных. Нарисуйте конкретную связь: тег → область → ключ → значение, вместо добавления одного поля во все уровни JSON.
- проверить регистр и пробелы в именах ключей;
- различать отсутствие свойства, null, пустую строку и 0;
- сверить тип массива или объекта для секции;
- проверить пары начала и конца циклов;
- посмотреть настройки parser и delimiters;
- зафиксировать хеш шаблона и версию библиотеки.
Документ выпускается только после проверки обязательных полей
Перед render приложение валидирует входные данные по схеме. После render проверяет оставшиеся маркеры, количество строк таблицы и ключевые значения. Одного поиска фигурных скобок мало: они могут быть обычным текстом документа. Полезно хранить список обязательных тегов конкретной версии шаблона и сопоставлять его с данными до генерации.
Ошибку рендеринга возвращайте оператору как понятное сообщение с названием поля и версией шаблона. Не выдавайте частично заполненный документ за готовый. Журнал содержит технический job ID и причину, но не паспортные данные, банковские реквизиты или весь входной JSON.
Тестовый набор ловит регрессии редактора
- Сгенерировать файл с обычными короткими значениями.
- Повторить с пустым необязательным полем и обязательным пропуском.
- Проверить массив из нуля, одного и нескольких элементов.
- Добавить длинное название и символы амперсанда и кавычек.
- Открыть итоговый DOCX и проверить колонтитулы, таблицы и переносы.
Шаблон храните как версионируемый артефакт. После правки в Word сначала прогоняйте тестовый набор; прежний проверенный файл остаётся доступным для отката. Если потребуется помощь, достаточно минимального DOCX, обезличенного JSON, конфигурации парсера и точного сообщения ошибки. Такой комплект показывает, потерялось ли значение до рендеринга или внутри документа.