Оставшийся тег в 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.

Тестовый набор ловит регрессии редактора

  1. Сгенерировать файл с обычными короткими значениями.
  2. Повторить с пустым необязательным полем и обязательным пропуском.
  3. Проверить массив из нуля, одного и нескольких элементов.
  4. Добавить длинное название и символы амперсанда и кавычек.
  5. Открыть итоговый DOCX и проверить колонтитулы, таблицы и переносы.

Шаблон храните как версионируемый артефакт. После правки в Word сначала прогоняйте тестовый набор; прежний проверенный файл остаётся доступным для отката. Если потребуется помощь, достаточно минимального DOCX, обезличенного JSON, конфигурации парсера и точного сообщения ошибки. Такой комплект показывает, потерялось ли значение до рендеринга или внутри документа.

Проверенные источники