Files
java-word-pdf/docs/library/getting-started.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

73 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` из транзитивных зависимостей.