Мы рады объявить о выпуске GroupDocs.Assembly for Java 26.11, доступном с ноября 2026. Этот релиз переносит функции и исправления GroupDocs.Assembly for .NET 26.11 на Java:
- шаблоны могут проверяться по JSON Schema;
- страницы шаблонов и отчетов могут преобразовываться в изображения;
- загрузка внешних ресурсов находится под контролем приложения;
REMOVE_EMPTY_PARAGRAPHSработает для таблиц и обычного текста шаблонов;- теги
<<image>>работают в ячейках таблиц презентаций и разрешают относительные пути относительно папки шаблона; - теги цвета принимают hex-строки.
В комплекте движки Aspose переходят с их ранних версий 2026 года на 26.10, а ряд исправлений охватывает лицензирование, кодировку отчетов, штрихкоды и HTML‑контент. Java 8 остаётся базовой версией.
Что нового в этом выпуске
| Ключ | Описание | Категория |
|---|---|---|
| ASSEMBLYNET-145 | JsonDataSource принимает JSON Schema: члены, объявленные в схеме, могут быть использованы даже если они null, пусты или отсутствуют в данных, а типы значений берутся из схемы |
Функция |
| ASSEMBLYNET-8 | DocumentAssembler.generatePreview преобразует страницы шаблонов, собранных отчетов и других документов в изображения PNG, JPEG или BMP |
Функция |
| ASSEMBLYNET-36, ASSEMBLYNET-37 | DocumentAssemblyOptions.REMOVE_EMPTY_PARAGRAPHS работает для шаблонов таблиц и обычных текстовых документов |
Функция |
| ASSEMBLYNET-140 | Внешние ресурсы, на которые ссылаются шаблоны и данные, находятся под контролем приложения; ресурсы, ссылки на которые приходят из данных, по умолчанию пропускаются | Безопасность |
| ASSEMBLYJAVA-353 | В комплект включены Aspose.Words 26.10.1, Aspose.Cells 26.10, Aspose.Slides 26.10, Aspose.Email 26.9 и Aspose.BarCode 26.10 | Обновление |
| ASSEMBLYJAVA-353 | Штрихкоды GS1 (EAN‑14, SCC‑14, SSCC‑18 и DataBar) сохраняют авто‑коррекцию текста кода с Aspose.BarCode 26.10 | Исправление |
| ASSEMBLYNET-52 | Тег <<image>> работает в ячейке таблицы презентации, а теги в фигурах групповых фигур обрабатываются |
Улучшение |
| ASSEMBLYNET-62 | Относительный путь к изображению из данных разрешается относительно папки шаблона | Улучшение |
| ASSEMBLYNET-25 | Цвет, заданный строкой, может быть hex‑значением в тегах backColor и цветах диаграмм |
Улучшение |
| ASSEMBLYNET-155 | Отсутствующее логическое значение в JSON, XML или CSV считается false в операторе ?: и в предикатах where, count, any, all и first, вместо ошибки |
Исправление |
| ASSEMBLYNET-157 | groupBy и distinct по вложенным объектам объединяют одинаковые объекты; поддерживаются ссылки $id/$ref в JSON‑данных |
Исправление |
| ASSEMBLYNET-142 | License.setLicense(InputStream) читает поток, который уже был прочитан, с начала |
Исправление |
| ASSEMBLYNET-143 | Потребление лицензии с учётом метра фиксируется, когда операция завершается | Исправление |
| ASSEMBLYNET-158 | Текстовые и HTML‑отчёты шаблонов, содержащих только ASCII, записываются в UTF‑8, поэтому нелатинские данные больше не теряются | Исправление |
| ASSEMBLYNET-160 | Штрихкоды больше не вызывают NullPointerException, когда шрифт их текстового поля не установлен |
Исправление |
| ASSEMBLYNET-159 | Теги в теме разговора MSG‑шаблона собираются так же, как теги в его предмете | Исправление |
| ASSEMBLYNET-152 | Тег <<doc>> в шаблоне таблицы, презентации или текста выдаёт чёткое сообщение об ошибке; при неудачном assembleDocument не остаётся пустого выходного файла |
Исправление |
| ASSEMBLYJAVA-354 | Тег‑выражение -html, завершающий абзац, больше не оставляет пустой абзац после HTML, заканчивающегося блочным элементом |
Исправление |
Изменения поведения, которые следует проверить перед обновлением
- Внешние ресурсы из данных пропускаются по умолчанию. Например,
<<image [item.PhotoUrl]>>, гдеPhotoUrl— URI http или https, теперь даёт пустое изображение. Добавьте хосты вLoadSaveOptions.getWhitelistedResources()или вызовитеLoadSaveOptions.setSkipExternalResources(false), чтобы сохранить прежнее поведение. Ресурсы, на которые ссылается сам шаблон, и локальные пути файлов работают как раньше. - Неоднозначный вызов
JsonDataSource.new JsonDataSource(path, null)с литеральнымnullвторым аргументом больше не компилируется. Приведите тип аргумента:new JsonDataSource(path, (JsonDataLoadOptions) null). Скомпилированные приложения не затронуты. - Отчёты в UTF‑8 для текста и HTML. Отчёты шаблонов только с ASCII‑текстом и HTML без маркера порядка байтов теперь записываются в UTF‑8 вместо windows‑1252. Чтобы сохранить однобайтовую кодовую страницу, укажите её в шаблоне (
<meta charset>в HTML). groupByиdistinctпо вложенным объектам JSON, XML и DataSet теперь объединяют одинаковые объекты вместо создания отдельной группы для каждой строки.- Нет лишнего абзаца после HTML. Тег
-html, завершающий абзац, больше не оставляет пустой абзац после HTML, заканчивающегося блочным элементом. Чтобы оставить пустую строку, завершите HTML тегом<p> </p>. - Штрихкоды DataBar Expanded. Штрихкод DataBar Expanded или DataBar Expanded Stacked с текстом кода, состоящим только из цифр, теперь кодируется как GTIN с идентификатором приложения (01), как и остальные типы DataBar.
- Изменён текст исключения для тега
<<doc>>в шаблонах таблиц, презентаций и текста; тип исключения остаётся тем же. - Удалён API.
ICustomFontsHandler.resetFontSources()удалён; вместо него вызывайтеFontSettings.resetFontSources().
Новые возможности
Поддержка JSON Schema для JsonDataSource
Шаблон проверяется на соответствие структуре своих данных до оценки любого <<if>>. При работе с JSON структура обычно выводилась из самих данных, поэтому ссылка внутри ветки, которая никогда не отрисовывается, приводила к ошибке, если данные за ней были null, пустым массивом или отсутствовали.
JsonDataSource теперь принимает JSON Schema, так же как XmlDataSource принимает XML Schema, и шаблон проверяется по схеме:
- члены, объявленные в схеме, могут быть использованы даже если они null, пусты или отсутствуют в данных;
- члены, не объявленные в схеме, всё равно вызывают ошибку, поэтому опечатки обнаруживаются как и раньше;
- типы значений берутся из схемы, поэтому булево значение будет
Boolean, а строка, содержащая цифры, останется строкой.
Пример данных клиента без платёжных карт и без программы лояльности, где номер счёта — строка цифр:
{ "Name": "Quayside Bistro", "Account": "00042", "Cards": [], "Loyalty": null }
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"Name": { "type": "string" },
"Account": { "type": "string" },
"Cards": {
"type": "array",
"items": { "type": "object", "properties": { "Type": { "type": "string" }, "Last4": { "type": "string" } } }
},
"Loyalty": { "type": ["object", "null"], "properties": { "Level": { "type": "string" } } }
}
}
и шаблон:
Customer: <<[customer.Name]>>
Account number: <<[customer.Account]>>
<<if [customer.Cards.count() > 0]>>Payment card: <<[customer.Cards.first().Type]>> ending in <<[customer.Cards.first().Last4]>><<else>>No payment card on file.<</if>>
Loyalty program: <<[customer.Loyalty?.Level]>>
передайте схему рядом с данными:
JsonDataSource dataSource = new JsonDataSource("Customer.json", "Customer.schema.json");
DocumentAssembler assembler = new DocumentAssembler();
assembler.assembleDocument("Json schema.docx", "output.docx", new DataSourceInfo(dataSource, "customer"));
Результат — No payment card on file. с номером счёта 00042. Без схемы тот же шаблон падает на customer.Cards.first().Type, а номер счёта читается как число 42.
Схему можно указать как путь к файлу или InputStream, с JsonDataLoadOptions или без него. Поддерживаемые ключевые слова: type (включая nullable‑типы), properties, items, format (date-time и date), enum, const, allOf и локальные указатели $ref. Не поддерживаются oneOf, anyOf, not, удалённые или рекурсивные $ref, items в виде кортежа и массивы массивов.
Предпросмотр документа
DocumentAssembler.generatePreview преобразует страницы документа в изображения PNG, JPEG или BMP: шаблон, документ, собранный GroupDocs.Assembly, или любой другой документ поддерживаемого формата, из файла или потока. Преобразуются страницы текстовых процессоров, текстовых и HTML‑документов, печатные страницы таблиц, слайды презентаций и сообщения электронной почты вместе с их заголовком.
DocumentAssembler assembler = new DocumentAssembler();
ByteArrayOutputStream report = new ByteArrayOutputStream();
try (InputStream template = new FileInputStream("Customer orders.docx"))
{
assembler.assembleDocument(template, report,
new DataSourceInfo(new JsonDataSource("Customers.json"), "customers"));
}
// A stream is created for every page and released when the page is written.
PreviewOptions options = new PreviewOptions(
pageNumber -> new FileOutputStream("page" + pageNumber + ".png"),
(pageNumber, pageStream) -> pageStream.close());
options.setPreviewFormat(PreviewFormats.PNG);
options.setResolution(120); // dots per inch; 96 by default
// options.setPageNumbers(new int[] { 1, 2 }); // all pages by default
assembler.generatePreview(new ByteArrayInputStream(report.toByteArray()), options);
Когда одновременно задаются setWidth и setHeight, страницы масштабируются до указанного размера, сохраняя соотношение сторон. Предпросмотры генерируются без загрузки внешних ресурсов, а созданные изображения учитываются в лицензировании с учётом метра, как и собранные документы.
REMOVE_EMPTY_PARAGRAPHS для шаблонов таблиц и обычного текста
DocumentAssemblyOptions.REMOVE_EMPTY_PARAGRAPHS теперь работает и для шаблонов таблиц, и для обычных текстовых документов. Здесь абзац — это строка текста: строка текста ячейки или текстового документа, которая становится пустой после обработки тегов шаблона, удаляется вместе с переводом строки. Теги вроде <<if>> и <<foreach>>, записанные на отдельных строках, больше не оставляют пустых строк.
DocumentAssembler assembler = new DocumentAssembler();
assembler.setOptions(DocumentAssemblyOptions.REMOVE_EMPTY_PARAGRAPHS);
assembler.assembleDocument("Empty paragraph.txt", "result.txt", new DataSourceInfo("dummy", "dummy"));
Шаблон:
Prefix
<<if [false]>>
Text to be removed
<</if>>
Suffix
Результат:
Prefix
Suffix
Тот же текст шаблона в ячейке таблицы даёт такой же результат внутри ячейки. HTML и XML‑документы остаются без изменений.
Безопасность: контроль внешних ресурсов
Тег <<image>> или <<doc>> может оцениваться в URI, полученный из данных, и ранее GroupDocs.Assembly без возможности предотвратить его загрузку. Сервер, собирающий документы из данных, предоставленных сторонними пользователями, мог бы таким образом запрашивать внутренние адреса.
GroupDocs.Assembly теперь указывает, откуда берётся каждая ссылка на внешний ресурс (ExternalResourceOrigin):
TEMPLATE— сам шаблон ссылается на ресурс, включая буквальный URI в теге, например<<image ["https://example.com/logo.png"]>>;DATA— ссылка берётся из данных, например URI, полученный в результате вычисления выражения тега.
По умолчанию ресурсы, на которые ссылается шаблон, загружаются как прежде, а ресурсы, ссылки на которые приходят из данных, пропускаются. Управляют этим четыре свойства LoadSaveOptions:
setSkipExternalResources(trueпо умолчанию) — внешние ресурсы не загружаются;setTrustTemplateResources(trueпо умолчанию) — ресурсы, на которые ссылается шаблон, загружаются даже при включённом пропуске; установитеfalse, если шаблоны поступают из ненадёжных источников;getWhitelistedResources— имена хостов или абсолютные префиксы URI, разрешённые даже при включённом пропуске;setExternalResourceHandler—ExternalResourceHandler, вызываемый для каждого внешнего ресурса перед запросом, позволяющий разрешить, пропустить или предоставить его содержимое.
final String photoUri = "https://images.example.com/photos/no-photo.jpg";
DocumentAssembler assembler = new DocumentAssembler();
// Default options: the URI comes from data, so the image is skipped and left empty.
assembler.assembleDocument("Inserting image.docx", "Skipped.docx", new DataSourceInfo(photoUri, "expression"));
// Allow a trusted host and see every decision. The handler can also provide the content itself.
LoadSaveOptions options = new LoadSaveOptions();
options.getWhitelistedResources().add("images.example.com");
options.setExternalResourceHandler(new LocalImageHandler("no-photo.jpg"));
assembler.assembleDocument("Inserting image.docx", "Provided.docx", options, new DataSourceInfo(photoUri, "expression"));
public class LocalImageHandler extends ExternalResourceHandler
{
private final String mImagePath;
public LocalImageHandler(String imagePath) { mImagePath = imagePath; }
@Override
public void onLoading(ExternalResourceLoadingArgs args)
{
System.out.println(ExternalResourceOrigin.toString(args.getOrigin()) + " resource " + args.getUri() + ": "
+ (args.isSkipped() ? "skipped" : "allowed"));
// Provide the content instead of requesting it.
if (!args.isSkipped() && args.getUri().toLowerCase().startsWith("https://images.example.com/"))
{
try
{
args.setData(Files.readAllBytes(Paths.get(mImagePath)));
}
catch (IOException e)
{
throw new UncheckedIOException(e);
}
}
}
}
Внешние ресурсы — это ресурсы, требующие сетевого доступа: URI http, https и ftp, UNC‑пути и URI файлов с удалённым хостом. Локальные файловые пути не затрагиваются. Пропущенное изображение в документе заменяется прозрачным изображением; пропущенное значение <<image>> или <<doc>> рассматривается как пустое.
Улучшения
Изображения в ячейках таблиц и групповых фигурах презентаций
В шаблоне презентации тег <<image>> ранее можно было разместить только в текстовом поле. Теперь ячейка таблицы также служит контейнером для изображения: изображение заполняет ячейку, включая ячейки строк, повторяемых с помощью <<foreach>>, так что можно построить таблицу со списком элементов и их картинками. С параметром -fitHeight строка увеличивается, чтобы показать изображение с сохранением пропорций. Теги в фигурах групповых фигур, включая вложенные группы, теперь обрабатываются как в остальных фигурах.
Относительные пути к изображениям, разрешаемые относительно папки шаблона
Тег <<image>>, получающий относительный путь к файлу из данных, например Images/photo.png, теперь сначала разрешает его относительно папки шаблона, аналогично связанным ресурсам документов Microsoft Office. Для шаблона, загруженного из потока, задайте папку с помощью LoadSaveOptions.setResourceLoadBaseUri:
DocumentAssembler assembler = new DocumentAssembler();
// A template loaded from a stream has no folder: set it with setResourceLoadBaseUri.
LoadSaveOptions options = new LoadSaveOptions();
options.setResourceLoadBaseUri("C:\\Reports\\Templates");
try (InputStream template = new FileInputStream("C:\\Reports\\Templates\\Inserting image.docx");
OutputStream report = new FileOutputStream("output-from-stream.docx"))
{
assembler.assembleDocument(template, report, options, new DataSourceInfo("../Images/no-photo.jpg", "expression"));
}
Если файл по указанному пути не существует, используется текущий каталог, как и раньше.
Hex-строки цветов
Цвет, заданный строкой, теперь может быть hex‑значением — "#RRGGBB", "#RGB" или "#AARRGGBB" — помимо имени цвета и ARGB‑целого, в тегах backColor и цветах диаграмм. Например, <<backColor [item.Color]>> с "#FF0000" из данных теперь применит красный цвет.
Исправления
- Отсутствующие логические значения в JSON, XML и CSV теперь считаются
falseв условном операторе?:и в предикатахwhere,count,any,allиfirst, вместо ошибкиNullPointerException. groupByиdistinctпо вложенным объектам JSON и XML сравнивают объекты по значению, поэтому одинаковые клиенты образуют одну группу. Поддерживаются JSON‑данные с сохранёнными ссылками ($id/$ref).License.setLicense(InputStream)читаетByteArrayInputStreamс его отметки иFileInputStreamс позиции 0, поэтому поток, уже использованный для лицензирования другого продукта GroupDocs, больше не приводит к ошибке «Unexpected EOF in prolog».- Учёт потребления лицензии фиксируется, когда сборка документа или генерация превью завершается, а не позже из фонового потока.
- Текстовые и HTML‑отчёты шаблонов, содержащих только ASCII, записываются в UTF‑8, поэтому данные вроде
CaféилиПриветбольше не теряются при кодировке windows‑1252. - Штрихкоды, текст которых рисуется движком (QR, DataMatrix, Aztec и др.), больше не падают, если шрифт их текстового поля не установлен — обычно Calibri на Linux. Вместо него используется резервный шрифт.
- MSG‑шаблоны: теги в теме разговора обрабатываются как теги в предмете, поэтому Outlook правильно формирует ветку сообщений.
<<doc>>в шаблонах таблиц, презентаций и текста выдаёт сообщение о том, что тег не поддерживается для данного формата, а неудачныйassembleDocumentбольше не оставляет пустой выходной файл.- HTML‑контент: тег‑выражение
-html, завершающий абзац, больше не оставляет лишний пустой абзац после HTML, заканчивающегося блочным элементом (ASSEMBLYJAVA-354). - Штрихкоды GS1: GroupDocs.Assembly теперь самостоятельно корректирует тексты кодов, состоящие только из цифр, для штрихкодов EAN‑14, SCC‑14, SSCC‑18 и DataBar, поскольку Aspose.BarCode 26.10 перестал это делать, поэтому эти штрихкоды остаются такими же, как в версии 26.10.1.
Обновление движков Aspose до версии 26.10
GroupDocs.Assembly for Java 26.10.1 включал библиотеки Aspose из начала 2026 года, поэтому уязвимости, исправленные в них после этого, были обнаружены сканерами безопасности. Теперь в комплекте:
| Движок | 26.10.1 | 26.11 |
|---|---|---|
| Aspose.Words for Java | 26.3 | 26.10.1 |
| Aspose.Cells for Java | 26.3 | 26.10 |
| Aspose.Slides for Java | 26.2 | 26.10 |
| Aspose.Email for Java | 26.1 | 26.9 |
| Aspose.BarCode for Java | 26.6 | 26.10 |
Опубликованный POM по‑прежнему не объявляет зависимостей. Поскольку движки были обновлены, сгенерированные документы могут различаться на уровне байтов, оставаясь визуально и функционально эквивалентными. Если вы сравниваете байты вывода с сохранёнными базовыми версиями, обновите эти базовые версии после обновления.
Примечания для пользователей Java
- Даты с
Zили смещением в JSON или CSV представляются как значенияjava.util.Dateточного момента, а шаблон формата выводит их в часовом поясе JVM по умолчанию. Чтобы вывод не зависел от сервера, запустите JVM с фиксированным часовым поясом, например-Duser.timezone=UTC. ExternalResourceOriginиPreviewFormats— классы с константамиint, как и остальные перечисления Java‑API.CreatePageStreamиReleasePageStream— функциональные интерфейсы, поэтому их можно реализовать лямбда‑выражениями.
Как получить обновление
Maven
Добавьте репозиторий GroupDocs и зависимость в ваш pom.xml:
<repositories>
<repository>
<id>groupdocs-artifacts-repository</id>
<name>GroupDocs Artifacts Repository</name>
<url>https://releases.groupdocs.com/java/repo/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-assembly</artifactId>
<version>26.11</version>
</dependency>
</dependencies>
Прямое скачивание
Скачайте JAR со страницы загрузки GroupDocs.Assembly for Java 26.11.