Carbone превращает данные JSON и привычные офисные шаблоны в PDF, DOCX, XLSX, PPTX и другие документы: в шаблоне расставляют теги, в Studio проверяют подстановки и предпросмотр, а затем тот же макет используют для счетов, договоров, актов, отчетов, этикеток и массовой генерации через API.

Рабочий процесс строится вокруг двух областей: слева размещаются тестовые данные и параметры рендеринга, справа показывается шаблон, история сохранений и PDF-предпросмотр. Макет при этом остается обычным документом Word, Excel, PowerPoint, LibreOffice, HTML или Markdown, поэтому шрифты, таблицы, колонтитулы и сетку оформляют знакомыми средствами, а Carbone отвечает за повторения, условия, вычисления и подстановку содержимого.

Главная практическая особенность состоит в разделении данных и оформления. Один и тот же JSON можно прогнать через несколько макетов, а один шаблон — наполнить тысячами наборов данных без ручного копирования. Это удобно там, где форма документа стабильна, но строки, суммы, адреса, даты, фотографии, диаграммы и языковые варианты меняются от клиента к клиенту.

Как устроена работа с шаблоном

Новый документ начинают не с рисования формы в отдельном конструкторе, а с готового макета. Для счета можно взять фирменный DOCX с таблицей товаров, для аналитического отчета — XLSX с формулами и диаграммами, для коммерческого предложения — PPTX, для письма — HTML. В местах, куда должны попасть данные, вводят теги в фигурных скобках. Например, поле имени связывают с {d.customer.name}, номер заказа — с {d.order.number}, а итог — с {d.total}. После загрузки макета Studio показывает редактор JSON и область предпросмотра, поэтому соответствие путей проверяется до подключения к рабочей системе.

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

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

Интерфейс Studio и первый запуск

На стартовом экране видны команды создания, список недавних шаблонов и галерея примеров. Кнопка Start from Scratch открывает рабочее пространство с тремя ключевыми зонами: редактор данных, панель шаблона и предпросмотр. В левой вертикальной панели находятся переходы к домашней странице, созданию и списку шаблонов. Центральная часть меняется в зависимости от выбранной вкладки, но логика остается одинаковой: данные задают контекст, шаблон определяет структуру, предпросмотр показывает фактический файл.

При создании пустого проекта Studio просит перетащить документ или выбрать его через диалог. Поддерживаемый файл не преобразуется в закрытый внутренний формат: его можно скачать обратно, исправить в исходном редакторе и загрузить повторно. Для простого теста достаточно DOCX с одной строкой {d.firstname} и JSON вида {"firstname":"Ирина"}. После загрузки справа появляется страница предпросмотра, а слева — значение, которое можно менять без повторной подготовки макета.

Интерфейс рассчитан на частое чередование двух действий: изменение данных и изменение шаблона. При включенной автоматической загрузке Studio отслеживает локальный файл, поэтому сохранение в Word или LibreOffice запускает новое отображение. Если автоматическое обновление мешает при серии правок, его можно остановить и вернуться к ручному обновлению. Важный практический прием — не проверять сразу большой документ. Сначала полезно добиться корректного вывода одной переменной, затем одной строки массива, после этого условий и только потом добавлять изображения, диаграммы и конвертацию в PDF.

Загрузка файла и проверка типа шаблона

Диалог выбора файла принимает офисные документы и другие поддерживаемые типы, но возможности зависят от структуры конкретного формата. DOCX и ODT подходят для договоров, счетов и многостраничных отчетов; XLSX и ODS удобны для табличных расчетов; PPTX и ODP — для презентаций; HTML и Markdown — для документов, которые формируются из веб-разметки; PDF используют прежде всего как форму с полями или аннотациями. Перед загрузкой полезно закрыть файл в редакторе, чтобы облачное хранилище или офисная программа не оставили незавершенную запись.

Если Studio не принимает документ, сначала проверяют расширение и целостность. Файл с расширением DOCX фактически является ZIP-контейнером с XML; поврежденный контейнер, защита паролем или нестандартный экспорт могут помешать разбору. Надежный способ диагностики — открыть документ в Word или LibreOffice и сохранить копию под новым именем. Для таблиц важно удалить внешние связи и убедиться, что формулы пересчитываются. Для презентаций лучше не использовать объекты, которые существуют только как внедренные элементы сторонних приложений.

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

Теги данных и вложенные пути

Основной префикс d обращается к объекту data. Путь читается слева направо: {d.company.address.city} извлекает поле city из address внутри company. Такой синтаксис удобен, пока названия ключей стабильны и не содержат неожиданных символов. Если данные приходят из нескольких систем, лучше преобразовать их в единую структуру до рендеринга, чем вставлять в шаблон длинные цепочки обхода и множество проверок на отсутствие значений.

Дополнительный объект complement доступен через c. Его применяют для сведений, которые сопровождают основной набор, но не являются частью бизнес-объекта: словари, служебные подписи, параметры организации, карта кодов и другие значения, общие для серии документов. Отдельные псевдонимы объявляют специальным тегом {#...}, чтобы сократить повторяющиеся длинные пути. Псевдоним полезен в таблице, где один и тот же вложенный массив используется десятки раз, однако его имя должно быть ясным, иначе сопровождение шаблона становится труднее.

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

Редактор JSON и тестовые наборы данных

Левая область Studio использует редактор кода с нумерацией строк, подсветкой структуры и поиском. JSON должен быть синтаксически корректным: строки заключаются в двойные кавычки, элементы разделяются запятыми, после последнего элемента запятая не ставится. Частая ошибка — вставить объект из JavaScript с одинарными кавычками или комментариями. Перед поиском проблемы в шаблоне следует убедиться, что редактор не показывает синтаксическую ошибку и что фигурные и квадратные скобки закрыты.

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

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

Предпросмотр, обновление и поиск ошибок

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

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

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

Повторение строк и блоков по массиву

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

Например, в строке счета используют {d.items[i].name}, {d.items[i].qty} и {d.items[i].price}, а в следующей строке помещают один маркер {d.items[i+1].name}. Если массив пуст, обе строки удаляются. Это удобно, но подпись Товары или заголовок таблицы могут остаться без содержимого. Чтобы скрыть весь раздел, добавляют отдельное условие по длине массива или формируют блок так, чтобы заголовок входил в удаляемую область.

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

Сортировка, фильтрация, группировка и уникальные значения

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

Фильтрация позволяет исключить элементы без отдельного копирования массива. Типичный случай — показать только оплаченные счета, товары с ненулевым количеством или события выбранного периода. Условие размещают в маркере цикла; в современных шаблонах достаточно корректно задать его на границе повторения, но при переносе старых макетов необходимо проверять синтаксис. Фильтр не исправляет неверный тип данных: строка false и логическое false — разные значения.

Группировка нужна для многоуровневых отчетов: продажи по менеджерам, позиции по категориям, операции по месяцам. После группировки структура массива меняется, поэтому пути внутри цикла отличаются от исходных. Сначала полезно вывести название группы и количество элементов, а затем строить вложенную таблицу. Операция distinct удаляет повторы по выбранному ключу, а lookup помогает найти связанное значение в другом массиве. Это снижает объем подготовительного кода, но чрезмерное количество преобразований внутри макета усложняет диагностику.

Форматирование текста, чисел и валют

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

Числовой формат зависит от локали и типа файла. formatN выводит разделители тысяч и нужную точность, а функции round, ceil, floor, add, sub, mul и div выполняют базовые операции. В электронных таблицах число желательно оставлять числом и задавать отображение стилем ячейки; если превратить его в строку, формулы и сортировка могут перестать работать. Для PDF или DOCX текстовое форматирование обычно безопасно.

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

Даты, интервалы, часовые пояса и локаль

formatD преобразует дату в нужный шаблон и учитывает язык. Дополнительные операции прибавляют и вычитают периоды, находят начало или конец единицы времени и вычисляют разницу. Перед форматированием важно знать, что приходит в JSON: дата без времени, строка ISO с часовым поясом или локальная строка. Неоднозначные значения вроде 03/04/2026 лучше не использовать, потому что порядок дня и месяца зависит от договоренности.

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

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

Условия и скрытие пустых фрагментов

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

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

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

Вычисления, суммы и промежуточные значения

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

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

Функции set и преобразование данных внутри шаблона позволяют сохранить промежуточный результат, создать новый массив или объединить элементы. Это полезно для компактного макета, но порядок выполнения учитывается в пределах раздела документа. Значение, заданное в теле, не следует без проверки использовать в колонтитуле, поскольку эти части могут обрабатываться отдельно. Для сложной бизнес-логики надежнее подготовить итоговый JSON заранее и оставить шаблону только отображение.

Динамические изображения и галереи

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

Для серии фотографий объект должен быть встроен в строку текста, а не плавать поверх страницы. В Word режим In Line with Text позволяет повторять изображения в цикле; другие варианты обтекания подходят для одиночной замены, но не для галереи. Перед массовой генерацией проверяют вертикальные и горизонтальные снимки, прозрачный PNG, очень большое изображение и отсутствующий файл.

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

Диаграммы, цвета, штрихкоды и QR-коды

Carbone поддерживает два подхода к диаграммам. Нативную диаграмму создают в Word, Excel, PowerPoint или LibreOffice и связывают ее набор данных с тегами. Такой вариант сохраняет стиль офисного документа. Альтернативный механизм использует ECharts и формирует изображение по JSON-конфигурации; он дает больше типов и настроек, но требует точной структуры данных.

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

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

HTML, Markdown и данные из визуальных редакторов

HTML может быть как шаблоном, так и динамическим содержимым внутри офисного документа. В первом случае Carbone подставляет данные, выполняет циклы и условия, после чего Chromium формирует PDF с поддержкой современных CSS, JavaScript и веб-шрифтов. Этот путь подходит для макетов, которые уже существуют как веб-страница и должны сохранять похожее отображение.

Для HTML, полученного из WYSIWYG-редактора или системы искусственного интеллекта, применяется специальный рендеринг внутрь DOCX, ODT или PDF. Не весь CSS одинаково переносится в офисные форматы, поэтому сложную сетку, позиционирование и интерактивные элементы упрощают. Безопасность тоже важна: непроверенный HTML может содержать внешние ресурсы или нежелательные конструкции, поэтому его очищают до передачи.

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

Заполнение существующих PDF-форм

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

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

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

Формы, подписи и интерактивные поля

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

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

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

Локализация и один шаблон для нескольких языков

Статический текст переводят специальным тегом {t(...)}, а динамическое значение — форматтером перевода. Словарь передают вместе с параметрами. Если ключ отсутствует, в документе остается сам ключ, поэтому перед выпуском полезно собрать список всех меток и проверить полноту словаря.

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

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

Шаблоны Excel и расчетные таблицы

XLSX и ODS позволяют формировать не только PDF, но и редактируемую таблицу. Теги размещают в ячейках, циклы повторяют строки или столбцы, а формулы можно сохранить для последующей работы пользователя. Формат ячейки задает число знаков, валюту, дату и выравнивание. Если тег возвращает текст вместо числа, формула SUM может игнорировать значение, поэтому тип результата проверяют отдельно.

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

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

Презентации и повторение слайдов

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

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

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

Получение PDF и выбор конвертера

При запросе можно указать выходной тип. Для PDF доступны разные движки. LibreOffice дает широкий набор настроек и хорошо подходит для офисных шаблонов; OnlyOffice бывает полезен для DOCX, XLSX и PPTX; Chromium предназначен прежде всего для HTML. Выбор влияет на шрифты, переносы, диаграммы и поддерживаемые параметры.

Не следует менять движок только из-за одной визуальной ошибки, не зафиксировав пример. Сначала сохраняют исходный шаблон и JSON, затем получают файлы каждым подходящим конвертером и сравнивают конкретные элементы. Если Chromium используется для HTML, CSS должен быть рассчитан на печать: задаются размеры страниц, поля, разрывы и правила для таблиц.

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

Вывод изображений, CSV и других типов

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

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

Большое число поддерживаемых преобразований не означает одинаковое качество каждой пары. Надежнее выбирать близкий путь: DOCX в PDF, XLSX в PDF, HTML в PDF. Экзотические старые форматы сначала открывают и пересохраняют современным редактором, затем используют как шаблон.

Сохранение, комментарии и развертывание шаблонов

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

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

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

Развернутый шаблон и безопасный откат

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

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

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

Загрузка результата из Studio

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

Перед выдачей файла проверяют расширение и Content-Type ответа. Если приложение ожидает PDF, а сервер вернул JSON с описанием ошибки, сохранение ответа под именем report.pdf создаст поврежденный файл. При автоматизации код должен сначала проверить статус, поле success или тип содержимого, а затем записывать результат.

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

Проверка загруженного PDF

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

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

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

Контроль финального файла

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

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

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

Автоматизация через HTTP API

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

Заголовок авторизации передают как Bearer-токен, а требуемую главную версию API — отдельным заголовком. Токен нельзя помещать в клиентский HTML, журнал или шаблон. Если вызов выполняется из браузерного приложения, используют серверный посредник или SDK с подходящей моделью доступа.

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

Управление шаблонами через API

API позволяет загружать файл, перечислять шаблоны, читать метаданные, добавлять новое сохранение, менять имя, комментарий, теги, дату развертывания и срок хранения. Файл передают multipart/form-data или base64. Для больших документов multipart экономичнее, потому что base64 увеличивает объем примерно на треть.

Постоянный идентификатор связывает несколько сохранений, а идентификатор конкретного файла основан на SHA-256. При обновлении необходимо явно указать, к какому шаблону относится новый файл. Ошибка между двумя типами ID приводит к тому, что приложение либо не находит объект, либо создает отдельный шаблон.

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

Встраивание Studio в собственную систему

Studio доступен как веб-компонент. Его добавляют в страницу, задают режим, адрес backend и параметры отображения, затем открывают шаблон по ID, URL или data URI. Компонент совместим с обычным JavaScript и популярными фреймворками, потому что взаимодействие строится через методы и события.

Режим embedded оставляет сохранение приложению: Studio показывает редактор данных, загрузку шаблона и предпросмотр, а код перехватывает события template:updated и template:saved. Режим embedded-versioning подключает управление сохранениями и развертыванием, для чего нужен backend с хранением метаданных.

Метод setRenderOptions передает тестовые данные и параметры, openTemplateId открывает шаблон вместе с сохранениями, openTemplateURL загружает файл по адресу, reset очищает состояние. События connected, options:updated, template:updated, template:saved и template:deployed позволяют синхронизировать интерфейс с правами, журналом и собственными кнопками.

Интеграции с no-code и рабочими процессами

Carbone подключают к n8n, Make, Zapier, Airtable, Bubble, Odoo и другим системам. Типовая цепочка получает запись, формирует JSON, вызывает генерацию, сохраняет файл и отправляет его по почте или на подпись. Самая частая ошибка в такой цепочке — передать не объект, а строку с JSON внутри строки. Перед вызовом проверяют структуру на предыдущем шаге.

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

В Odoo или CRM шаблон должен получать устойчивую схему, а не все поля записи без отбора. Промежуточный слой преобразует названия, вычисляет суммы и удаляет лишние данные. Это защищает макет от изменений внутренней модели и уменьшает риск передать ненужные персональные сведения.

Ограничения, с которыми сталкиваются на практике

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

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

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

Типовые ошибки и способы исправления

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

Повторяется одна строка или пропадает таблица — проверяют расположение [i] и [i+1]. Оба маркера должны находиться в последовательных элементах того контейнера, который повторяется. Скрытый тег, разбитый форматированием Word на несколько XML-фрагментов, иногда перестает распознаваться; его удаляют и набирают заново без смены стиля внутри фигурных скобок.

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

Ошибка авторизации означает неверный или просроченный токен, отсутствие Bearer или вызов не того адреса. Ошибка формата ответа часто возникает, когда приложение сохраняет JSON ошибки как PDF. В журнале нужно фиксировать HTTP-статус, код ошибки, шаблон ID и время, но не полный токен и не чувствительные данные.

Безопасность данных и шаблонов

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

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

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

Производительность и устойчивость массовой генерации

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

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

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

Практические сценарии

Счет: DOCX содержит реквизиты и таблицу, массив items повторяет строки, агрегатор считает итог, formatC оформляет валюту, условие скрывает скидку при нуле. После проверки PDF отправляется клиенту, а DOCX при необходимости остается для согласования.

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

Отчет: XLSX или DOCX принимает показатели по периодам, группирует их по подразделениям, строит диаграммы и локализует даты. Для руководителя генерируется PDF, для аналитика — XLSX. Один набор данных используется в двух шаблонах с разным уровнем детализации.

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

Сравнение Carbone с аналогами

Программа	Лучше подходит для	Главное ограничение
Carbone	Шаблоны Office, LibreOffice и HTML с JSON, предпросмотром и API	Дизайн макета выполняется во внешнем редакторе
Docmosis	Серверная генерация DOCX, ODT и PDF по офисным шаблонам	Для сложной логики нужно изучить собственные теги и развертывание
Windward Core	Корпоративные отчеты с дизайнером в Microsoft Office	Ориентирован на разработчиков и корпоративную инфраструктуру
Formstack Documents	No-code процессы с формами, CRM и доставкой документов	Меньше контроля над самостоятельным размещением движка
Docupilot	Быстрая генерация договоров и счетов из интеграций	Сложные офисные макеты и вычисления требуют тщательной проверки
PDF Generator API	Веб-шаблоны, визуальный дизайнер и генерация через REST API	Основной рабочий процесс привязан к фирменному конструктору

Carbone лучше выбирать, когда организация уже использует DOCX, XLSX, PPTX, ODT или HTML и хочет отделить оформление от JSON без переноса макета в закрытый визуальный редактор. Docmosis близок по подходу с офисными файлами; Windward Core удобен для крупных корпоративных проектов и глубокого дизайна в Office; Formstack Documents и Docupilot проще включить в готовые no-code цепочки; PDF Generator API подходит командам, которым нужен веб-конструктор шаблонов. PDF Commander решает другую задачу: ручное редактирование готового PDF, поэтому он полезен как инструмент разовой правки, но не заменяет автоматическую генерацию серии документов.

Как подготовить надежный шаблон

Начинают с утвержденного макета без тегов. Затем фиксируют схему JSON и добавляют подстановки по разделам. Каждый раздел проверяют на минимальных и максимальных данных. Циклы не смешивают с бизнес-расчетами, пока простая подстановка не работает.

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

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

Шрифты, символы и печатная стабильность

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

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

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

Водяные знаки, пароли и ограничения PDF

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

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

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

Пагинация, разрывы страниц и большие таблицы

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

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

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

Колонтитулы, нумерация и оглавление

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

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

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

Гиперссылки и кликабельные реквизиты

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

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

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

Объединение файлов и приложения к документу

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

Порядок приложений задают явно. Имена файлов не гарантируют правильную сортировку, особенно для чисел 1, 2 и 10. Перед объединением проверяют размер и количество страниц, а после — закладки, нумерацию и положение подписей. При добавлении очень большого приложения ограничения по числу и суммарному размеру могут остановить рендер.

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

Пользовательские форматтеры и граница логики

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

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

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

Проверка схемы JSON до рендеринга

Схема описывает обязательные поля, типы, вложенность и допустимые значения. Для счета она может требовать строковый номер, дату ISO, объект customer и массив items, где quantity и price являются числами. Проверка до отправки дает понятную ошибку нет customer.name, а не пустое место в готовом файле.

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

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

Автоматические тесты шаблонов

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

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

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

Диагностика по минимальному примеру

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

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

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

Организация командной работы

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

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

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

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

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

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

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