ONLYOFFICE Document Builder позволяет по сценарию создавать и изменять DOCX, XLSX, PPTX и PDF, подставлять данные в шаблоны, собирать таблицы и диаграммы, заполнять формы, конвертировать файлы и получать изображения страниц. Основные инструменты здесь — JavaScript API объектов документа, команды CreateFile, OpenFile, SaveFile и CloseFile, аргументы командной строки, а также обёртки для Python, C++, Java, COM и .NET.

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

Для первого запуска удобнее держать сценарий, входные файлы, шрифты и папку результата в одном тестовом каталоге. Сначала формируют небольшой документ, проверяют его в просмотрщике и только после этого добавляют циклы, внешние данные и пакетную обработку. Такой порядок быстро отделяет ошибки API от проблем с путями, правами доступа, отсутствующими шрифтами и неверными значениями в шаблоне.

Как устроен рабочий процесс

В минимальном сценарии первая команда создаёт файл требуемого типа, затем переменная получает корневой объект документа. Для текста это Api.GetDocument(), для электронной таблицы — Api.GetActiveSheet(), для презентации — Api.GetPresentation(). После наполнения вызывается SaveFile с форматом и путём назначения, а CloseFile освобождает связанные с документом ресурсы. Важно не оставлять открытый объект между независимыми заданиями: следующий запуск иначе может получить состояние, которое не относится к новому файлу.

Сценарии запускаются из терминала. В Windows используется docbuilder.exe, а в Linux и macOS — documentbuilder; после имени исполняемого файла указывают путь к JavaScript-файлу. Если команда вызывается не из каталога программы, надёжнее передавать абсолютный путь и к исполняемому файлу, и к сценарию. Относительные пути внутри кода считаются от рабочего каталога процесса, а не обязательно от папки, где лежит сам сценарий, поэтому в серверной очереди их лучше предварительно нормализовать.

Объект builder отвечает за жизненный цикл файла и преобразование форматов, а объект Api создаёт содержимое. Это разделение помогает диагностике: ошибка OpenFile обычно относится к пути, доступу или формату входного файла; ошибка в Api.CreateParagraph, GetRange либо AddShape относится к структуре сценария; неудачный SaveFile чаще указывает на недоступную папку, неподдерживаемое сочетание форматов или занятый выходной файл.

• Создать или открыть документ и проверить успешность операции.
• Получить корневой объект и найти место вставки.
• Добавить данные небольшими логическими блоками.
• Сохранить рабочий формат, затем при необходимости PDF или изображения.
• Закрыть файл и проверить наличие результата, размер и возможность открытия.

Проверка сценария в Playground и отладчике

В документации доступна площадка Playground, где пример Office API можно изменять и сразу видеть сформированный результат. Она полезна для проверки отдельного метода, порядка аргументов и единиц измерения. Площадка не заменяет испытание в целевой среде: в ней уже настроены движок, шрифты и доступ к образцам, тогда как на рабочем сервере могут отличаться пути, локаль, набор шрифтов и права пользователя процесса.

Для сложного JavaScript-сценария предусмотрена отладка через инспектор V8. Перед запуском задают переменную окружения V8_USE_INSPECTOR=1, после чего команда выводит адрес инспектора. Его открывают в Chromium-совместимом браузере, ставят точки останова, смотрят локальные переменные, стек вызовов и значения объектов. Это особенно полезно, когда документ создаётся, но часть таблицы пуста, цикл завершается раньше ожидаемого или свойство получает undefined.

При отладке удобнее сначала остановиться сразу после CreateFile или OpenFile и убедиться, что корневой объект существует. Следующую точку ставят перед проблемной вставкой, а последнюю — перед SaveFile. Если ошибка исчезает после добавления паузы, нужно искать гонку в окружающем приложении, конфликт имён выходных файлов или преждевременное удаление временного каталога, а не пытаться лечить сценарий случайными задержками.

Структура JavaScript-сценария

Файл сценария может использовать синтаксис с объектом builder, который разбирает команды верхнего уровня, либо builderJS, предназначенный для обычной JavaScript-обёртки. Вариант builder удобен для коротких файлов с CreateFile, OpenFile, SaveFile и CloseFile. Вариант builderJS проще включать в функции, условия и общую структуру JavaScript, когда путь, формат и данные вычисляются программно. Смешивать два стиля без необходимости не стоит: единообразный сценарий легче читать и переносить между командной строкой и языковыми обёртками.

Офисный API работает с объектной моделью. Текстовый документ содержит секции, абзацы, запуски текста, таблицы и рисунки; лист — диапазоны, ячейки, строки, столбцы, рисунки и диаграммы; презентация — слайды и размещённые на них объекты; PDF — страницы, текстовые блоки, фигуры, изображения, таблицы, поля и аннотации. Большинство операций выполняется в три этапа: создать объект, настроить свойства, вставить его в контейнер.

Единицы измерения требуют отдельного внимания. В ряде методов размеры задаются в English Metric Units, где 36 000 единиц соответствуют миллиметру; в других применяются пункты, пиксели или целые значения, определённые конкретным методом. Нельзя переносить число из настройки CSS или интерфейса редактора без пересчёта. Для часто используемых размеров лучше завести функции mm(), pt() и px(), а рядом с каждым числом оставить имя единицы в переменной.

builder.CreateFile("docx");
const document = Api.GetDocument();
const paragraph = Api.CreateParagraph();
paragraph.AddText("Сформировано автоматически");
document.Push(paragraph);
builder.SaveFile("docx", "result.docx");
builder.SaveFile("pdf", "result.pdf");
builder.CloseFile();

В одном открытии можно сохранить несколько представлений: например, рабочий DOCX для последующего редактирования и PDF для отправки. При этом второй SaveFile не должен заменять исходный путь, если дальнейшая логика ещё использует файл. Для пакетной обработки имена лучше строить из безопасного идентификатора задания и расширения, а пользовательское название хранить отдельно, чтобы кавычки, двоеточия и символы пути не ломали сохранение.

Передача данных через аргументы

Командная строка принимает JSON-аргумент, который становится доступен сценарию через глобальную переменную Argument. Такой способ подходит для номера заказа, имени клиента, массива строк таблицы и параметров оформления. Данные следует сериализовать стандартной библиотекой вызывающего языка, а не собирать строкой: ручная склейка быстро ломается на кавычках, переводах строк, обратных слешах и символах Unicode.

Аргумент лучше рассматривать как входной контракт. В начале сценария проверяют наличие обязательных полей, типы значений и допустимые пределы. Дату приводят к одному формату до передачи, денежные суммы передают числом и форматируют уже в документе, а пути разрешают только внутри выделенного каталога. Если поле необязательно, для него задают явное значение по умолчанию; молчаливое превращение undefined в пустую строку скрывает ошибки источника данных.

Крупный набор данных разумнее передавать не одной гигантской строкой команды, а через файл JSON, созданный вызывающим приложением во временном каталоге. Сам сценарий получает путь к этому файлу или уже разобранные значения через языковую обёртку. Это уменьшает риск превышения ограничения длины командной строки и упрощает повторный запуск конкретного задания при разборе сбоя.

• Проверяйте тип каждого обязательного поля до создания документа.
• Не используйте пользовательский текст как часть пути без очистки.
• Храните идентификатор шаблона отдельно от его физического имени.
• Логируйте идентификатор задания, но не секретные данные документа.
• Удаляйте временный JSON после успешного сохранения и проверки результата.

Текстовые документы: абзацы, стили и секции

Для нового DOCX создают абзац через Api.CreateParagraph, добавляют текст методом AddText или отдельными объектами Run и помещают абзац в документ. Отдельные Run нужны, когда внутри одной строки меняются полужирное начертание, размер, цвет, язык или шрифт. Если весь абзац оформлен одинаково, лишнее дробление на десятки запусков усложняет сценарий и увеличивает время обработки.

Стили полезнее прямого форматирования в документах, которые будут редактироваться после генерации. Заголовкам назначают Heading 1, Heading 2 и другие существующие стили либо создают собственный стиль с понятным именем. Тогда оглавление, навигация и пакетное изменение оформления работают предсказуемо. Назначать только крупный шрифт и полужирное начертание недостаточно: визуально строка будет похожа на заголовок, но в структуре останется обычным абзацем.

Секции управляют размером страницы, ориентацией, полями, колонками, колонтитулами и нумерацией. Для приложения к договору можно начать новую секцию в альбомной ориентации, вставить широкую таблицу, затем вернуть книжную ориентацию в следующей секции. Перед вставкой разрыва нужно решить, требуется новая страница или продолжение на текущей: неправильный тип разрыва порождает пустой лист или переносит колонтитул не туда, где его ожидают.

Оглавление вставляется в позицию курсора. Если сначала вызвать AddTableOfContents без перемещения курсора, оно может оказаться в начале документа. Надёжный сценарий создаёт заголовки со стилями, получает подходящий Run или другой опорный элемент, перемещает курсор методом MoveCursorToPos и лишь затем добавляет оглавление. После генерации проверяют не только расположение, но и наличие ссылок и номеров страниц.

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

Таблицы в DOCX и шаблонные отчёты

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

Ширина столбцов должна учитывать доступную область страницы: из ширины листа вычитают левое и правое поля, после чего распределяют остаток. Автоматический подбор удобен для черновика, но длинный артикул или адрес может растянуть один столбец и испортить весь макет. Для финансовых таблиц лучше фиксировать ключевые столбцы, разрешать перенос текста и выравнивать числа по правому краю.

Объединение ячеек выполняют только после проверки размеров диапазона. Частая ошибка — объединить заголовок, а затем в цикле попытаться записать данные в поглощённые ячейки. Удобнее отдельно создать верхний блок, затем строку названий столбцов и только после этого тело. Повторяющуюся строку заголовка следует пометить так, чтобы она отображалась на каждой странице при печати длинной таблицы.

Шаблон можно использовать как каркас: открыть DOCX, найти маркеры, заменить текст, заполнить таблицу и сохранить копию. Маркеры должны быть уникальными и не разбиваться редактором на несколько Run. Для устойчивого решения лучше применять поля, закладки или структурированные элементы, где это допускает модель документа, а простую замену текста оставлять для коротких неподвижных шаблонов.

• Не вставляйте форматированное число как текст, если позже его нужно суммировать.
• Не рассчитывайте ширину таблицы по числу символов без учёта шрифта.
• Проверяйте повтор заголовка на второй странице, а не только на первой.
• После объединения ячеек пересчитывайте индексы доступных элементов.
• Для пустого набора данных выводите понятную строку, а не пустую рамку.

Изображения, фигуры и диаграммы в документах

Изображение можно добавить из файла или доступного ресурса, указав размеры и положение. Для серверного сценария безопаснее заранее загрузить картинку в контролируемый каталог и передать локальный путь: результат не будет зависеть от времени ответа внешнего узла и изменения адреса. Перед вставкой проверяют тип файла, размеры и возможность декодирования, иначе повреждённая картинка прервёт всё задание.

Сохранение пропорций особенно важно для логотипов и фотографий. Сценарий должен вычислять коэффициент масштабирования по исходной ширине и высоте, а затем вписывать изображение в заданный прямоугольник без растяжения. Для печати выбирают достаточное разрешение; увеличение маленького PNG до ширины страницы не добавляет детализации и даёт размытый результат в PDF.

Фигуры состоят из геометрии, заливки, обводки и текстового содержимого. Их удобно применять для плашек, схем, подписей, кнопок в PDF и декоративных блоков отчёта. Координаты и размеры лучше хранить в именованных константах, иначе несколько чисел вида 608400 или 1267200 быстро становятся непонятными. При построении схем проверяют порядок слоёв: позднее добавленный объект может перекрыть текст или линию.

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

Электронные таблицы: диапазоны, формулы и форматирование

При создании XLSX рабочий процесс начинается с активного листа. Диапазон получают по адресу, например A1:D20, либо через индексы, после чего записывают значения, формулы и свойства. Для прямоугольного набора эффективнее передать двумерный массив сразу, чем вызывать SetValue для каждой ячейки. Такой подход уменьшает число переходов между JavaScript и внутренним объектом документа.

Число и его отображение нужно разделять. В ячейку записывают числовое значение, а денежный знак, проценты, количество знаков после запятой и разделители задают форматом. Если сохранить 1 250,00 ₽ как текст, сортировка, формулы и диаграммы будут работать неправильно. Даты также следует записывать в форме, которую движок распознаёт как дату, и применять к ним явный формат отображения.

Формулы можно размещать в итоговой строке, расчетных столбцах и вспомогательных диапазонах. Ссылки на строки формируют после определения фактического размера данных. Если таблица содержит заголовок и строку итогов, индексы полезно вычислять переменными firstDataRow, lastDataRow и totalRow; захардкоженное число быстро перестаёт совпадать с реальным диапазоном после добавления нового поля.

Оформление включает шрифт, заливку, границы, выравнивание, перенос, ширину столбцов и высоту строк. Автоподбор ширины следует ограничивать: длинный комментарий способен сделать столбец шире экрана. Для отчёта лучше задать максимальную ширину и включить перенос, а для идентификаторов оставить фиксированную ширину. Закрепление верхней строки помогает при просмотре, но его наличие нужно проверять в конечном XLSX, а не в PDF, где оно не имеет смысла.

Диаграммы и изображения привязываются к листу, но их положение зависит от размеров строк и столбцов. Поэтому сначала настраивают сетку, затем добавляют графику. Если после вставки диаграммы изменить ширину нескольких столбцов, объект может сместиться или перекрыть таблицу. Для печатного отчёта дополнительно проверяют область печати, ориентацию, поля и масштабирование на страницу.

• Записывайте данные блоками двумерных массивов.
• Храните числа числами, а внешний вид задавайте форматом.
• Не используйте объединённые ячейки внутри диапазона сортировки.
• Сначала задавайте размеры сетки, затем размещайте диаграммы.
• Проверяйте формулы на пустом, одиночном и максимальном наборе строк.

Презентации: слайды и объекты

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

Заголовок и основной текст следует помещать в отдельные фигуры, чтобы управлять их размерами, отступами и переносом. Для текста заранее задают максимально допустимое число строк. Если источник может вернуть длинный абзац, сценарий должен сокращать, делить материал на два слайда или уменьшать кегль в ограниченном диапазоне; бесконтрольное уменьшение до нечитаемого размера нельзя считать корректным решением.

Изображения вписывают в рамку с сохранением пропорций и при необходимости обрезают по заранее выбранному правилу. Для пакетной презентации полезна проверка минимального разрешения. Фото шириной 320 пикселей может выглядеть приемлемо в миниатюре, но станет размытым на проекторе. При отсутствии изображения лучше использовать предусмотренный макетом нейтральный блок, а не оставлять пустую область с техническим маркером.

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

PDF: создание, изменение и экспорт

PDF можно получить двумя путями. Первый — сформировать DOCX, XLSX или PPTX и сохранить его как PDF; он удобен для документов с обычной поточной версткой, таблицами, заголовками и колонтитулами. Второй — создать PDF и работать с его страницами и объектами через PDF API; этот подход подходит для точного позиционирования, аннотаций, интерактивных полей и графических макетов.

При формировании через DOCX сначала настраивают размер страницы, поля, стили и разрывы, а затем выполняют SaveFile("pdf", ...). Такой маршрут проще для договоров и отчётов, потому что движок сам рассчитывает перенос строк и страниц. Для этикеток, бланков и схем с фиксированными координатами удобнее создавать объекты непосредственно на странице PDF.

PDF API позволяет получать страницы, добавлять текст, изображения, таблицы, фигуры и диаграммы, а также работать с полями и аннотациями. Положение объекта задаётся в координатах страницы, поэтому любое изменение размера листа требует пересчёта. Перед массовым выпуском полезно создать эталон с направляющими, проверить его при масштабе 100 процентов и распечатать на реальном устройстве.

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

Аннотации включают текстовые заметки, подсветку, линии, фигуры, рукописные штрихи и другие типы. Для них задаются прямоугольник, цвет, непрозрачность, тема и дополнительные свойства, доступные конкретному классу. Поля формы разделяют модель данных и визуальный виджет: имя, значение и правила относятся к полю, а рамка и положение — к виджету. Это важно, когда одно логическое поле отображается на нескольких страницах.

При экспорте в PDF/A следует проверить, что выбранное значение формата действительно соответствует требуемому профилю процесса. Одного расширения .pdf недостаточно для архивного регламента. После сохранения файл проверяют специализированным валидатором, наличие встроенных шрифтов и корректность метаданных включают в отдельный контроль качества.

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

Изображения страниц и миниатюры

SaveFile умеет сохранять документ как JPG или PNG. Для первой страницы получается обычный файл изображения, а при выводе всех страниц — архив с отдельной картинкой для каждой страницы. Параметры передаются в XML-строке: формат изображения, сохранение пропорций, выбор первой или всех страниц, ширина и высота. Эта функция пригодна для миниатюр в системе документооборота, предпросмотра вложений и визуального контроля пакетной генерации.

Размер миниатюры выбирают по задаче. Картинка 200×280 пикселей подходит для списка файлов, но на ней невозможно проверить мелкий текст. Для автоматического сравнения страниц лучше сохранять PNG шириной около 1000 пикселей с сохранением пропорций. Если first=false, имя назначения должно соответствовать архиву изображений; ожидание одного PNG при выводе всех страниц приводит к путанице в последующей обработке.

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

Формы и заполнение шаблонов

Формы позволяют создавать текстовые поля, флажки, переключатели, списки, поля даты, изображения и другие элементы. Каждому полю присваивают стабильный ключ или имя, которое не зависит от подписи на странице. Подпись может измениться при переводе, а ключ остаётся частью контракта между документом и системой данных.

Для массового заполнения удобно сначала получить перечень полей шаблона, проверить обязательные ключи и только потом записывать значения. Если в шаблоне переименовано поле, сценарий должен завершиться понятной ошибкой до сохранения, а не выпускать документ с незаполненным местом. Значения списков проверяют по разрешённым вариантам; произвольная строка может визуально появиться, но нарушить ожидаемую логику формы.

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

При выпуске PDF проверяют, должны ли поля остаться интерактивными или превратиться в обычное содержимое. Для анкеты, которую продолжат заполнять, важны табуляция, виджеты и правила. Для финального договора чаще нужен неизменяемый визуальный результат. Выбор должен быть частью требований, потому что одинаково выглядящие страницы могут вести себя по-разному в просмотрщике.

Конвертация форматов

Поддерживаемый перечень охватывает текстовые DOCX, DOC, ODT, RTF, TXT, DOTX, OTT и HTML; презентационные PPTX, PPT, ODP, PPSX, POTX и OTP; табличные XLSX, XLS, ODS, CSV, XLTX и OTS; PDF, PDF/A, XPS и DjVu; изображения JPG, PNG и BMP, а также формат форм. Наличие формата в списке означает, что его можно передать соответствующим операциям, но точная сохранность конкретной функции зависит от содержимого и направления преобразования.

Для наилучшей редактируемости рабочим форматом выбирают DOCX, XLSX или PPTX. Старые бинарные DOC, XLS и PPT удобно принимать как входные файлы и переводить в современный формат до дальнейшего изменения. Если требуется только просмотр или отправка, применяют PDF. CSV не хранит шрифты, формулы в привычном виде, несколько листов и диаграммы, поэтому его используют как обмен данными, а не как замену полноценной книге XLSX.

Преобразование PDF в редактируемый текстовый формат следует проверять особенно внимательно. PDF описывает расположение объектов на страницах, а не логическую структуру документа, поэтому абзацы, таблицы и колонки приходится восстанавливать. Для сканированного PDF сначала требуется распознавание; сам факт открытия файла не означает, что текст станет доступен для редактирования. Результат сравнивают на нескольких типах страниц, включая таблицы и многостолбцовую верстку.

Конвертация в изображения полезна для предпросмотра, но необратима: текст, формы и ссылки превращаются в пиксели. JPEG подходит для фотографических страниц с допустимыми потерями, PNG — для текста, схем и интерфейсных миниатюр. BMP создаёт большие файлы и обычно нужен только для совместимости со специализированным процессом.

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

Интеграция с Python

Python-обёртка подходит для фоновых задач, ETL-процессов и небольших сервисов. Библиотеку устанавливают через pip, затем инициализируют Document Builder, создают экземпляр, открывают или создают файл и вызывают методы. Поддерживаемая среда требует Python 3.10–3.12. На Windows важно, чтобы нужный python.exe был доступен в PATH; на Linux и macOS обычно используются python3 и pip3.

Пути следует формировать через pathlib, а не склеивать обратными слешами. Временный каталог создают на каждое задание, чтобы параллельные процессы не писали в result.pdf одновременно. Конструкцию try/finally используют для закрытия файла и удаления временных данных даже при исключении. Исключение обогащают идентификатором задания и стадией, но не добавляют в журнал полный текст конфиденциального документа.

Данные из pandas или базы сначала преобразуют в обычные списки, числа и строки. Значения NaN, Decimal и datetime нельзя бездумно отправлять в JSON: для них задают явные правила. Десятичные суммы желательно передавать строкой или целым числом минимальных денежных единиц, а форматирование выполнять контролируемо, чтобы двоичная плавающая точка не добавила неожиданные копейки.

После генерации Python-код должен проверить выходной файл и только затем перемещать его в постоянное хранилище. Операция перемещения в пределах одного диска обычно атомарна, поэтому пользователь не увидит недописанный PDF. Для сетевого хранилища сначала загружают во временное имя, проверяют размер и хеш, затем переименовывают или публикуют объект.

Интеграция с C++, Java, COM и .NET

C++ предоставляет прямой доступ к CDocBuilder, CDocBuilderContext и CDocBuilderValue. Сначала вызывают статическую инициализацию, затем создают экземпляр, работают с документом и в конце освобождают общие ресурсы. Контекст даёт доступ к глобальному объекту Api и позволяет вызывать методы объектной модели без отдельного JavaScript-файла. Такой путь удобен, когда приложение уже написано на C++ и требуется тесный контроль жизненного цикла.

CDocBuilderValue представляет строку, число, логическое значение, массив или объект API. Перед вызовом метода нужно убедиться, что значение не пустое и имеет ожидаемый тип. Ошибка в имени метода проявляется во время выполнения, поэтому часто используемые имена полезно обернуть в функции собственного слоя. Это также изолирует бизнес-код от изменений в способе передачи параметров.

Java-интеграция использует docbuilder.jar. Для компиляции JAR добавляют в classpath, а при запуске указывают его вместе с каталогом классов; в Windows элементы разделяются точкой с запятой, в Linux и macOS — двоеточием. Требуется JDK 8 или новее. Нативные библиотеки должны находиться в ожидаемом каталоге, иначе класс загрузится, но первый вызов завершится ошибкой связывания.

COM предназначен для Windows-приложений, которым удобна компонентная модель. Он позволяет вызывать операции из языков и сред, умеющих работать с COM, но требует совпадения разрядности процесса и зарегистрированного компонента. Если 32-разрядное приложение пытается загрузить 64-разрядный компонент, проблему нельзя исправить изменением пути к документу — нужно согласовать архитектуру.

.NET-обёртка в готовом виде доступна для Windows. Для сборки примеров нужны Visual Studio и .NET SDK; целевой framework при необходимости меняют в свойствах проекта или файле csproj. В серверном приложении нужно контролировать освобождение объектов и не держать один документ одновременно в нескольких потоках. Для Linux или macOS не следует рассчитывать на готовую .NET-интеграцию: там выбирают CLI, Python, Java, C++ либо сервисный слой.

Параллельная и пакетная обработка

Библиотека допускает многопоточную работу при условии, что один документ обслуживается одним потоком. Разные потоки могут обрабатывать разные документы. Практически это означает очередь заданий с отдельным экземпляром рабочего состояния на файл, а не общий объект документа, к которому одновременно обращаются несколько обработчиков.

Число параллельных процессов определяют нагрузочным тестом. Генерация документа использует процессор, память, шрифты и файловую систему; увеличение числа рабочих процессов после насыщения диска только увеличивает задержку. Тест должен включать реальные шаблоны, изображения и экспорт в PDF, потому что пустой DOCX не отражает стоимость сложного отчёта.

Каждому заданию выделяют каталог вида job-id/input, job-id/work и job-id/output. Входные файлы копируются или монтируются только для чтения, промежуточные данные живут в work, а готовые результаты появляются в output после проверки. Такая структура исключает столкновение имён и позволяет безопасно повторить неудачное задание.

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

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

Шрифты, языки и точность верстки

Результат зависит от шрифтов, доступных процессу. Если в шаблоне указан отсутствующий шрифт, движок подберёт замену, изменятся ширина строк, переносы и число страниц. На тестовом компьютере документ может выглядеть правильно, а на сервере таблица перейдёт на следующую страницу. Набор корпоративных шрифтов нужно устанавливать одинаково во всех средах и учитывать их лицензию.

Для кириллицы выбирают шрифт с полным набором символов и проверяют полужирное, курсивное и обычное начертания. Искусственное имитирование отсутствующего начертания может отличаться при экспорте в PDF. Документы с арабским, ивритом и смешанным направлением текста требуют отдельного набора тестов: направление абзаца, порядок чисел, пунктуация и таблицы проверяются на реальных образцах.

Локаль влияет на представление дат, десятичных разделителей и формул. Источник данных не должен передавать уже отформатированное число, если требуется расчёт. Внутреннее значение хранят нейтрально, а внешний вид задают в документе. Для даты важно определить часовой пояс до форматирования: преобразование полуночи в другой зоне способно изменить календарный день.

Точность верстки проверяют не только на экране. PDF печатают с масштабом 100 процентов, измеряют поля и положение элементов на бланке. Если принтер автоматически вписывает страницу, ошибку макета легко не заметить. Для этикеток и форм с фиксированными полями отключают масштабирование и используют реальные размеры носителя.

Безопасная обработка входных файлов

Документы поступают из внешней среды, поэтому их рассматривают как недоверенные данные. Перед обработкой проверяют расширение, сигнатуру, размер и допустимый формат. Имя файла не используется как путь без очистки. Архивы и изображения ограничивают по распакованному объёму и размеру, чтобы один файл не исчерпал диск или память.

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

Внешние изображения и данные лучше загружать вызывающим сервисом, где настроены тайм-ауты, проверка адресов и ограничения размера. Затем Document Builder получает локальный файл или готовый JSON. Это предотвращает зависимость документа от временной сети и уменьшает риск обращения к внутренним адресам по пользовательской ссылке.

Журналы должны содержать стадию, длительность, формат, размер и технический код ошибки, но не полный текст договора, персональные данные и токены. Для диагностики достаточно хеша входного файла и идентификатора шаблона. Если требуется сохранить проблемный образец, его помещают в защищённое хранилище с ограниченным сроком хранения.

Лицензирование и водяной знак

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

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

Системные требования и совместимость

Готовые SDK-архивы предлагаются для Windows x64 и x86, Linux x86_64 и aarch64, macOS x86_64 и arm64. На Windows архив ZIP распаковывают в выбранный каталог; на Linux и macOS архив tar.xz извлекают командой tar xvJf. Архитектура пакета должна совпадать с системой и процессом, который загружает библиотеку.

Python-обёртка рассчитана на Python 3.10–3.12. Для C++ в Windows используется Visual Studio; в Linux нужен GCC не ниже 4.2.1 для x86/x64 и не ниже 8 для 64-разрядной ARM; для macOS указан GCC не ниже 4.2.1. Java требует JDK 8 или новее. Готовая .NET-интеграция ограничена Windows.

Свободное место оценивают с учётом входа, временных файлов, рабочего формата, PDF и изображений всех страниц. Пакетная задача может на короткое время занять в несколько раз больше размера исходного документа. На сервере устанавливают квоту на задание и общий порог, после которого очередь приостанавливает новые тяжёлые операции.

Совместимость формата проверяют на собственном наборе файлов. Даже при поддерживаемом расширении результат зависит от макросов, внедрённых объектов, шрифтов, диаграмм, сложных полей и особенностей генератора исходного документа. Минимальный набор должен включать простой файл, самый сложный рабочий шаблон, максимальное число строк и один ранее проблемный образец.

Практический сценарий: счёт и PDF

Для счёта исходные данные удобно разделить на реквизиты продавца, покупателя, массив позиций, налоги, условия оплаты и идентификатор документа. До запуска проверяют, что каждая позиция содержит название, количество, цену и ставку, а итог совпадает с суммой строк. Финансовую арифметику выполняет бизнес-система; сценарий отвечает за отображение, а не за повторный расчёт по строкам с округлениями.

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

Если строк много, шапку таблицы повторяют на каждой странице, а итоговый блок запрещают разрывать посередине. Для длинного названия товара включают перенос и задают минимальную ширину числовых колонок. Нулевое количество позиций обрабатывают как ошибку данных либо отдельный тип документа; пустой счёт с нулевым итогом не должен появляться из-за пропущенного массива.

Файл называют по внутреннему безопасному идентификатору, например invoice_84531.pdf, а отображаемый номер счёта помещают в метаданные и текст. После формирования вычисляют SHA-256 и сохраняют его вместе с версией шаблона и входным JSON. Это позволяет доказать, какой именно документ был отправлен, и повторно получить идентичный результат при тех же данных и окружении.

Практический сценарий: договор по шаблону

Договор чаще создают из заранее согласованного DOCX. Сценарий открывает шаблон, находит поля сторон, предмет, сроки, суммы и таблицу приложений, затем заполняет их. Для изменяемых абзацев лучше использовать структурированные маркеры, а не набор подчёркиваний. Подчёркивания визуально сдвигаются при длинном значении и не дают надёжно определить место вставки.

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

Нумерацию пунктов строят средствами списка, а не строками 1.1. в тексте. Тогда при удалении блока последующие пункты перенумеруются. Перекрёстные ссылки и оглавление проверяют после вставки всех частей. В финале документ сохраняют в DOCX и PDF, сравнивают обязательные фразы с контрольным списком и проверяют, что ни один технический маркер не остался в тексте.

Практический сценарий: отчёт XLSX и диаграмма

Для отчёта исходный массив нормализуют до одинакового набора колонок. Первый лист содержит подробные данные, второй — агрегаты, третий при необходимости — справочник. Сценарий записывает заголовки и массив значений блоками, задаёт числовые форматы, формулы итогов, автофильтр и закрепляет верхнюю строку.

Диаграмма строится по небольшому подготовленному диапазону, а не напрямую по тысячам строк. Категории сортируют в требуемом порядке и явно подписывают единицы. Если рядов слишком много, диаграмма становится нечитаемой; в таком случае оставляют несколько главных категорий и объединяют остальные в группу, причём правило агрегации выполняется до создания документа.

После сохранения XLSX дополнительно получают PDF для чтения и PNG первой страницы для карточки отчёта. PDF проверяют на разрывы таблиц и масштаб, а XLSX — на формулы и типы ячеек. Совпадение визуального итога в PDF не гарантирует, что ячейки книги остаются числами, поэтому эти проверки не взаимозаменяемы.

Обработка ошибок и способы устранения

Симптом	Вероятная причина	Что проверить
Команда не найдена	Каталог не добавлен в PATH	Указать полный путь к docbuilder.exe или documentbuilder и проверить разрядность пакета.
OpenFile не открывает файл	Неверный путь, права или формат	Вывести нормализованный путь, проверить сигнатуру и чтение от имени пользователя процесса.
SaveFile не создаёт результат	Папка недоступна или файл занят	Создать отдельный выходной каталог, проверить права и уникальность имени.
Вместо шрифта используется другой	Шрифт отсутствует в среде	Установить семейство и все нужные начертания, обновить кэш шрифтов и повторить.
Таблица ушла на следующую страницу	Ширина больше полезной области	Пересчитать ширины с учётом полей, переноса и границ.
Оглавление оказалось в начале	Курсор не перемещён	Перед AddTableOfContents установить позицию через MoveCursorToPos.
В ячейках числа стали текстом	Передана форматированная строка	Записать числовое значение и отдельно назначить формат.
Диаграмма пустая	Диапазон или массивы не совпадают	Проверить числа, категории, длину рядов и индексы.
PDF отличается по числу страниц	Замена шрифта или иные метрики	Сравнить набор шрифтов, поля, разрывы и размер страницы.
Java не загружает библиотеку	Неверный classpath или нативный путь	Проверить docbuilder.jar, разделитель путей и архитектуру JVM.
.NET пример не собирается	Не совпадает target framework	Установить SDK и скорректировать целевой framework в проекте.
Параллельные задания смешали файлы	Общий каталог или имя result	Создавать уникальный каталог и экземпляр на каждое задание.
Миниатюры сохраняются архивом	Запрошены все страницы	При first=false ожидать архив изображений; для одной страницы поставить true.
В документе виден водяной знак	Используется бесплатная лицензия	Применить подходящую коммерческую лицензию для чистого выпуска.
Сценарий зависает на одном файле	Повреждённый вход или тяжёлый объект	Задать тайм-аут, сохранить образец и изолировать его от общей очереди.

Диагностику начинают с самого маленького воспроизводимого сценария. Из проблемного файла удаляют бизнес-данные, оставляя один элемент, который вызывает сбой. Затем запускают его в той же среде и с теми же шрифтами. Если минимальный пример работает, части исходного документа возвращают по одной; так быстрее найти конкретную таблицу, изображение или поле, чем изучать тысячи строк журнала.

Для JavaScript-ошибок используют инспектор V8 и проверяют значения непосредственно перед вызовом метода. Для ошибок открытия и сохранения проверяют файловую систему вне Document Builder тем же пользователем процесса. Для различий верстки сравнивают перечень шрифтов и рендер страниц. Каждый класс проблемы требует своего инструмента; универсальный повтор запуска редко устраняет причину.

Архитектура сервиса генерации

Небольшая задача может вызывать CLI напрямую из приложения. Приложение создаёт рабочий каталог, записывает JSON, запускает процесс, ждёт завершения, проверяет выход и возвращает файл. Для высоконагруженной системы лучше использовать очередь и отдельные рабочие процессы. Веб-запрос тогда только создаёт задание, а пользователь получает статус и забирает результат после завершения.

Builder Framework выбирают, когда нужен тесный вызов методов из Python, C++, Java или .NET и обмен значениями без отдельного процесса на каждую операцию. CLI проще изолировать и перезапускать, но запуск процесса имеет накладные расходы. Решение принимают после измерений на реальных шаблонах, а не по предположению, что библиотечный вызов всегда быстрее и безопаснее.

Document Builder API через HTTP применяют в инфраструктуре с установленным ONLYOFFICE Docs. В этом случае сценарий отправляется сервису, а результат получается по протоколу API. Такой вариант переносит выполнение на выделенный узел, но требует настройки доступа, токенов, ограничений размера и мониторинга сервиса. Его не следует путать с прямым вызовом CLI: способ вызова и эксплуатационные риски различаются.

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

Контроль качества сформированных документов

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

Структурная проверка подтверждает формат, возможность открытия, число листов или слайдов, наличие обязательных текстов и отсутствие маркеров. В XLSX проверяют типы ключевых ячеек и формулы, в PDF — число страниц и доступность текста, в формах — поля и значения. Такая проверка выполняется автоматически и быстро отбрасывает явно неполные результаты.

Визуальная проверка рендерит страницы в PNG и сравнивает их с эталоном с допустимым порогом. Полное попиксельное совпадение слишком чувствительно к антиалиасингу, поэтому дополнительно сравнивают области интереса: заголовок, таблицу, итог и колонтитул. Значительное расхождение отправляют на ручной просмотр.

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

Для файлов, которые подписываются или архивируются, после проверки вычисляют хеш и запрещают дальнейшее изменение. Предпросмотр и пользовательское имя связывают с тем же хешем. Если PDF повторно сохранён сторонней программой, хеш изменится, даже если страницы выглядят одинаково; это важное различие между визуальной эквивалентностью и идентичностью файла.

Сравнение ONLYOFFICE Document Builder с аналогами

Программа	Лучше подходит для	Главное ограничение
ONLYOFFICE Document Builder	Автоматического создания и преобразования DOCX, XLSX, PPTX и PDF через единый Office API	Нет обычного пользовательского редактора; сценарии требуют разработки.
Aspose.Total	Глубокой серверной обработке многих офисных и издательских форматов из .NET, Java и других сред	Коммерческая модель и отдельные объектные модели для разных семейств документов.
LibreOffice UNO и headless	Автоматизации на базе офисного пакета и конвертации с открытым исходным кодом	Сложнее изолировать длительно работающий процесс и добиться стабильного параллелизма.
Syncfusion File Formats	Генерации документов в приложениях .NET, Java и JavaScript с библиотеками по типам форматов	Набор возможностей и лицензирование зависят от выбранных компонентов.
Microsoft Open XML SDK	Точного изменения внутренней структуры DOCX, XLSX и PPTX без рендеринга	Не выполняет полноценную визуальную верстку и экспорт в PDF сам по себе.
Gotenberg	Контейнерной конвертации офисных файлов и HTML в PDF через HTTP	Ориентирован на преобразование, а не на подробное редактирование объектной модели.
PDF Commander	Ручного редактирования, объединения и оформления PDF без написания кода	Не предназначен для серверной генерации DOCX, XLSX и PPTX по сценариям.

ONLYOFFICE Document Builder выбирают, когда один сценарий должен работать с текстами, таблицами, презентациями и PDF, а разработчикам подходит JavaScript-подобная объектная модель. Aspose.Total и Syncfusion рациональны в проектах, где уже используется их экосистема и нужны специализированные библиотеки. LibreOffice headless полезен для открытой инфраструктуры и конвертации, но требует осторожной эксплуатации процессов. Open XML SDK подходит для структурных правок OOXML, когда не нужен собственный рендер. Gotenberg удобен как готовый конвертационный сервис. PDF Commander практичнее для сотрудника, которому нужно визуально исправить отдельный PDF, а не строить автоматический конвейер.

Когда программа подходит лучше всего

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

Программа также полезна как слой конвертации внутри системы документооборота, когда нужно принять старый формат, получить современный OOXML, PDF и миниатюру. Единый журнал и одинаковые шрифты обеспечивают предсказуемость. Для разовой правки одного абзаца такой подход избыточен: написать, проверить и поддерживать сценарий дольше, чем открыть документ в редакторе.

Ещё один подходящий случай — встраивание генерации в CRM, ERP, портал или мобильное приложение. Бизнес-система передаёт нормализованные данные, а Document Builder отвечает за документ. Граница ответственности должна быть чёткой: расчёты и права доступа остаются в приложении, форматирование и сохранение — в сценарии.

Ограничения, которые важно учитывать

Главное ограничение для обычного пользователя — отсутствие привычного окна редактирования с лентой, панелью страниц и диалогами. Работа требует сценария или кода интеграции. Playground помогает изучать API, а готовые примеры ускоряют старт, но они не превращают инструмент в визуальный конструктор макетов.

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

Третье ограничение — водяной знак в свободно доступной сборке. Его нужно учитывать в оценке проекта и демонстрации заказчику. Кроме того, преобразование сложных документов не гарантирует идеального сохранения каждой нестандартной функции. Макросы, внедрённые объекты, редкие поля и необычные PDF требуют проверки на реальных файлах.

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

Частые практические вопросы

Можно ли изменить существующий DOCX и сохранить PDF?

Да. Сценарий открывает DOCX через OpenFile, получает документ, находит или добавляет элементы, затем вызывает SaveFile для DOCX и PDF. Исходник лучше оставлять неизменным и сохранять новую копию, особенно при пакетной обработке.

Можно ли создать PDF без промежуточного DOCX?

PDF API позволяет создавать PDF и добавлять на страницы текст, изображения, таблицы, фигуры, поля и аннотации. Для поточной верстки договора промежуточный DOCX нередко проще, а для фиксированного бланка удобнее координатная модель PDF.

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

Чаще всего отличаются шрифты, локаль, версия шаблона, рабочий каталог или архитектура пакета. Сравните перечень шрифтов, абсолютные пути, входной файл и параметры запуска. Затем отрендерите обе версии страниц и найдите место первого расхождения.

Как передать массив строк из приложения?

Небольшой массив сериализуют в JSON и передают как Argument либо через CDocBuilderValue в языковой обёртке. Для очень большого набора удобнее временный JSON-файл или непосредственная передача массивов через Framework, чтобы не упираться в длину команды.

Можно ли запускать несколько документов параллельно?

Да, если каждый документ обрабатывается одним потоком и имеет собственный экземпляр состояния и рабочий каталог. Разные потоки могут работать с разными документами. Число рабочих процессов подбирают нагрузочным тестом.

Как получить миниатюры всех страниц?

В SaveFile задают формат JPG или PNG и XML-параметры m_oThumbnail. При first=false все страницы сохраняются в архив изображений; при first=true создаётся миниатюра первой страницы. Размер и сохранение пропорций задаются отдельными параметрами.

Почему оглавление попадает не на ту страницу?

Оглавление вставляется в позицию курсора. Перед AddTableOfContents нужно переместить курсор к нужному элементу, например через MoveCursorToPos, и убедиться, что заголовкам назначены структурные стили.

Можно ли использовать HTML как основной шаблон?

HTML присутствует среди поддерживаемых форматов, но сложная офисная верстка, секции и поля не всегда переносятся так же, как в DOCX. Для договора или отчёта с точными страницами надёжнее подготовить DOCX-шаблон и проверить конвертацию HTML на конкретном содержимом.

Как убрать водяной знак?

Штатный способ — использовать коммерческую лицензию, покрывающую проект. Постобработка PDF с попыткой скрыть отметку не решает лицензионный вопрос и может повредить содержимое.

Что хранить для воспроизводимости?

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

Последовательность внедрения

1. Выбрать один типовой документ и описать обязательные элементы.
2. Подготовить минимальный шаблон без неоднозначных маркеров.
3. Собрать сценарий с одним набором тестовых данных.
4. Проверить рабочий формат, PDF и миниатюру.
5. Добавить валидацию входа и понятные ошибки.
6. Создать отдельные тесты для длинных строк, пустых полей и большого массива.
7. Зафиксировать шрифты и окружение.
8. Подключить очередь, уникальные рабочие каталоги и тайм-ауты.
9. Добавить структурные и визуальные проверки.
10. Только после этого расширять набор шаблонов и параллелизм.

Такой порядок уменьшает число переменных. Если сразу соединить базу, очередь, сетевое хранилище, десяток шаблонов и параллельный запуск, любой дефект выглядит как ошибка движка. Один проверенный документ создаёт эталон архитектуры: следующие шаблоны повторяют механизм запуска, журнал, проверку и публикацию результата.

Сценарии и шаблоны версионируют вместе. Изменение поля в DOCX без соответствующей правки кода должно обнаруживаться тестом. Выпуск новой версии начинают с небольшого процента заданий, сравнивают длительность, размер и визуальные контрольные точки, затем расширяют использование. При отклонении можно быстро вернуть прежнюю пару шаблона и сценария.

Поиск и изменение существующего содержимого

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

Простая замена текста должна учитывать регистр, пробелы, переносы и повторения. Если маркер встречается дважды, сценарий обязан знать, нужно заменить первое, последнее или все совпадения. Перед сохранением полезно повторно искать технический префикс маркеров, например двойные фигурные скобки, и завершать задание ошибкой, если хотя бы один остался. Это предотвращает отправку клиенту договора с незаполненным {{FIELD}}.

Удаление элемента выполняют вместе с окружающей структурой. Если необязательная строка таблицы не нужна, удаляют строку, а не только её текст; если не нужен раздел, удаляют абзацы и связанные разрывы. Иначе в документе остаются пустые рамки, лишние интервалы и пустые страницы. После удаления первого или последнего блока отдельно проверяют границы документа, потому что соседние абзацы могут унаследовать нежелательное форматирование.

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

Сравнение документов доступно как отдельный сценарий командной строки. Оно полезно для контроля шаблона и пользовательской копии, но результат нужно интерпретировать как набор изменений, а не как гарантию юридической эквивалентности. Изменение пробела, стиля или поля может считаться отдельной правкой. Для автоматического решения сначала отфильтровывают допустимые технические различия, а содержательные изменения отправляют на проверку.

Проектирование шаблонов для автоматизации

Хороший шаблон создаётся не как обычный документ с подчёркиваниями, а как интерфейс между данными и версткой. Каждое поле имеет уникальный ключ, тип, обязательность, максимально ожидаемую длину и правило форматирования. Таблица заранее предусматривает повтор заголовка и рост числа строк, а необязательные блоки изолированы так, чтобы их можно было удалить без нарушения пунктуации и нумерации.

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

Длинные значения проверяют до утверждения дизайна. Название организации, адрес и должность могут занимать в несколько раз больше места, чем тестовое слово. Для каждого поля определяют поведение: переносить, уменьшать шрифт в узком диапазоне, обрезать с ошибкой или переносить весь блок на следующую страницу. Молчаливое наложение текста на соседний элемент недопустимо.

Шаблон получает машинно читаемый идентификатор и ревизию. Сценарий проверяет, что открыта ожидаемая ревизия, например по служебному полю или контрольному набору ключей. Если дизайнер заменил шаблон и удалил обязательный маркер, генерация останавливается до выпуска файла. Название на диске само по себе недостаточно: файл с прежним именем может содержать другую структуру.

Изменения шаблона проверяют на одном и том же наборе эталонных данных. Сравнивают число страниц, расположение ключевых блоков, наличие всех обязательных фраз и визуальные изображения страниц. Изменение цвета заголовка не должно неожиданно сдвинуть подпись на следующую страницу. Такой контроль особенно важен, когда дизайнер редактирует DOCX вручную, а разработчик не видит каждое изменение.

Обновление среды без сбоев в выпуске

Перед заменой пакета Document Builder создают копию среды и прогоняют регрессионный набор. Сравнивают успешность открытия, время обработки, размеры файлов, число страниц, формулы, поля формы и изображения страниц. Новая сборка может исправить один формат и изменить рендер другого, поэтому проверка только простого DOCX не покрывает XLSX, PPTX и PDF.

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

Шрифты и системные зависимости обновляют отдельно от движка, чтобы при расхождении было понятно, что изменилось. Если одновременно заменить пакет, образ контейнера и набор шрифтов, источник новой разбивки страниц определить трудно. Для каждой среды сохраняют перечень шрифтов, архитектуру, контрольные суммы шаблонов и конфигурацию запуска.

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

После обновления журналы сравнивают по распределению длительности и типам ошибок. Рост среднего времени может быть незаметен на одном документе, но создать очередь под нагрузкой. Увеличение доли очень маленьких PDF часто означает пустой или неполный результат. Метрики позволяют обнаружить проблему до жалобы пользователя и временно направить задания на проверенную среду.

Итоговый рабочий подход

ONLYOFFICE Document Builder раскрывается не в единичном ручном редактировании, а в повторяемом конвейере: валидированные данные поступают в сценарий, объектная модель создаёт или изменяет документ, SaveFile формирует нужные представления, а автоматические проверки подтверждают структуру и вид страниц. Наиболее надёжный проект держит расчёты в бизнес-системе, оформление в шаблоне и API, а публикацию результата — в отдельной контролируемой стадии.

Начинать следует с малого файла и нескольких явных операций, затем добавлять стили, таблицы, изображения, формы и экспорт. Абсолютные пути, уникальные каталоги, одинаковые шрифты и проверка каждого результата устраняют большую часть эксплуатационных ошибок. Для сложного поведения доступен инспектор V8, а языковые обёртки позволяют встроить тот же механизм в Python, C++, Java, COM или Windows-проект на .NET.

Когда сценарии покрыты примерами и регрессионными тестами, выпуск документа становится предсказуемой операцией, а не ручной версткой. Пользователь получает DOCX, XLSX, PPTX, PDF или миниатюры в одинаковом оформлении, система сохраняет связь с исходными данными и шаблоном, а команда может безопасно масштабировать обработку на очередь независимых заданий.