b3511f8b74
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
# wordpdf-core: первые шаги
|
||
|
||
`wordpdf-core` — Java-библиотека конвертации `.docx`/`.doc` → PDF. Без LibreOffice,
|
||
без Aspose, без системных шрифтов: все TTF упакованы в jar.
|
||
|
||
## Подключение
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>ru.pjandro</groupId>
|
||
<artifactId>wordpdf-core</artifactId>
|
||
<version>1.0.0</version>
|
||
</dependency>
|
||
```
|
||
|
||
Требуется **Java 17**. Единственный обязательный аспект интеграции — версия
|
||
`commons-compress` (см. [Зависимости](dependencies.md)).
|
||
|
||
## Минимальный пример
|
||
|
||
```java
|
||
import ru.pjandro.wordpdf.WordPdfConverter;
|
||
import java.nio.file.Files;
|
||
import java.nio.file.Path;
|
||
|
||
byte[] docx = Files.readAllBytes(Path.of("doc.docx"));
|
||
byte[] pdf = WordPdfConverter.convert(docx, "doc",
|
||
new ru.pjandro.wordpdf.ConvertOptions(false, false, false, 5, 100));
|
||
Files.write(Path.of("out.pdf"), pdf);
|
||
```
|
||
|
||
Второй аргумент — заголовок PDF (пустой/`null` — без заголовка). Работа с файлами —
|
||
забота вызывающего: ядро пути не принимает, только байты.
|
||
|
||
Формат входа определяется **по сигнатуре байтов**, расширение имени файла ядру
|
||
неизвестно:
|
||
|
||
|Сигнатура|Маршрут|
|
||
|---|---|
|
||
|`PK\x03\x04`|zip → OOXML-путь (docx4j)|
|
||
|`D0 CF 11 E0 A1 B1 1A E1`|CFB → мост .doc → .docx в памяти → тот же конвейер|
|
||
|
||
## Опции конвертации
|
||
|
||
`ConvertOptions` — record из пяти полей (детали в [API библиотеки](api.md)):
|
||
error-флаги диаграмм/SmartArt/OLE и лимиты размера/страниц. Дефолтов в ядре нет —
|
||
все пять значений задаёт вызывающий:
|
||
|
||
```java
|
||
// отменить конвертацию, если в документе есть диаграммы; лимиты 10 МБ / 200 страниц
|
||
var opts = new ConvertOptions(true, false, false, 10, 200);
|
||
byte[] pdf = WordPdfConverter.convert(bytes, "Отчёт", opts);
|
||
```
|
||
|
||
## Прогрев
|
||
|
||
Первая конвертация после старта JVM стоит ~1,3–1,7 с (инициализация JAXB/XSLT/FOP).
|
||
`WordPdfConverter.warmup()` прогоняет весь конвейер на минимальном встроенном docx
|
||
и идемпотентен (повторные вызовы — no-op); бросать не должен никогда — решение
|
||
о реакции на сбой прогревает код. Вызывайте на старте приложения, если не хотите,
|
||
чтобы первый пользователь платил за инициализацию:
|
||
|
||
```java
|
||
WordPdfConverter.warmup(); // ~1,5–2,5 с, один раз при старте
|
||
```
|
||
|
||
## Провайдер логов
|
||
|
||
В classpath потребителя **обязан быть SLF4J-провайдер**. Без него docx4j пишет
|
||
предупреждение «TO HIDE THESE MESSAGES…» **прямо в выходной PDF**. В jar `wordpdf-core`
|
||
для этого включён `slf4j-simple`; если ваше приложение приносит свой провайдер
|
||
(logback и т.п.) — исключите `slf4j-simple` из транзитивных зависимостей.
|