Конвейер рендеринга
От документа к изображениям страниц
Между OpenDocumentAsync и PNG, который попадает в браузер, есть два отдельных этапа: разрешение просмотрщика (какой движок загружает документ, решается один раз при открытии) и обработка страниц (что происходит с каждым изображением страницы при каждом запросе). Понимание обоих объясняет, почему формат отображается так, как он отображается, — и что действительно переключает DefaultRender.
Этап 1 — Разрешение просмотрщика формата
Фабрика сопоставляет расширение файла с просмотрщиком через каталог форматов, с тремя уровнями приоритета:
- Сначала пользовательские просмотрщики. Всё, что вы зарегистрировали с помощью
DoconutOptions.RegisterViewer(extension, factory, defaultConfig?), выигрывает у всех встроенных. - Встроенные семейные просмотрщики. Каталог сопоставляет каждое расширение, которое можно просматривать, с семейством просмотрщиков — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — каждый со своим адаптером движка. Если лицензированный плагин предоставляет просмотрщик для того же расширения, просмотрщик плагина заменяет встроенный.
AddDoconut()проверяет зарегистрированные права плагина при запуске; резервный вариант фабрики к встроенному просмотрщику является защитным правилом выполнения. - Только плагины форматы. Некоторые расширения не имеют встроенного просмотрщика вообще — DICOM (
.dcm) существует только через плагин DICOM. Открытие без требуемой возможности вызывает:
LicenseException: This document type requires the 'Dicom' plugin license.Если ни один просмотрщик не заявляет поддержку расширения, возникает:
FormatNotSupportedException: Document format '<extension>' is not supported.После разрешения конфигурация фиксируется: ваш явный объект конфигурации, если вы его передали, иначе конфигурация по умолчанию формата из каталога. DocOptions.Password копируется в конфигурацию для защищённых документов.
Этап 1b — Режим перенаправления (DefaultRender = false)
Большинство конфигураций по формату раскрывают флаг DefaultRender. Он выбирает между двумя принципиально разными путями:
DefaultRender = true— документ рендерится нативно, напрямую в изображения страниц.DefaultRender = false— документ сначала конвертируется в PDF в памяти, исходный движок освобождается, и PDF‑просмотрщик берёт управление. Сгенерированный PDF содержит реальный текст, поэтому полнотекстовый поиск получает пиксельно‑точные нативные подсветки; конвейер принудительно включаетAllowSearchиAllowCopyдля перенаправленного PDF, поскольку конверсия невидима пользователю.
XPS и значение по умолчанию каталога для MHT используют путь перенаправления. PDF‑проекция может обеспечить нативный поиск для форматов, таких как HTML и Microsoft Project. Если полученный PDF содержит изображения без текстового слоя, стандартный просмотрщик не может искать по этим пикселям.
Используйте режим перенаправления, когда вам нужна PDF‑проекция с текстом — ценой является предварительная конверсия при открытии документа.
Этап 2 — Конвейер изображений страниц
Отрисованные страницы обрабатываются по запросу через фиксированную последовательность:
raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response- Водяной знак — применяется из состояния лицензии (отсутствующая лицензия, истёкшая временная или подписка, недействительный домен, неверная версия) и из
DocOptions.Watermarkдля вашего собственного пользовательского текста. Правильно лицензированное приложение — или активная временная лицензия — без пользовательского водяного знака пропускает этот шаг. - Поворот/отражение — состояние каждой страницы, которое пользователь задаёт в виджете (90°/180°/270°, горизонтальные/вертикальные отражения), хранится в сессии и применяется при каждом последующем рендере этой страницы.
- Масштаб — миниатюры и уровни масштабирования создаются путём масштабирования отрисованной страницы до требуемого целевого размера;
0означает обслуживать в оригинальном размере. - Встраивание аннотаций — сохранённые аннотации накладываются на растровое изображение, чтобы экспорты и изображения страниц отображали их.
- Кодирование — результат кодируется в PNG с использованием пулов потоков памяти и записывается напрямую в HTTP‑ответ.
Ошибки внутри промежуточного слоя возвращаются как PNG‑изображения ошибок (красный текст на белом), а не как HTTP‑страницы ошибок, чтобы виджет мог отображать их в области страницы.
Кеширование страниц
BaseConfig.CachePages (по умолчанию true) хранит отрисованные изображения страниц в памяти в течение всей сессии документа, поэтому повторный переход к странице не приводит к её повторному рендеру. BaseConfig.ImageResolution (25–300 DPI, 0 = значение по умолчанию формата) является основным регулятором качества/памяти; значение по умолчанию каждого формата задокументировано на его странице конфигурации.
Рендеринг на одном узле против множества
Всё выше описывает рендеринг на одном узле по запросу для сессии, которая открыла документ. Развёртывание, где один узел рендерит и публикует весь набор артефактов, а другие узлы обслуживают эти страницы из общего хранилища, использует иной путь чтения — см. Распределённые развертывания.
Шрифты в Linux
Страницы отрисовываются шрифтами, установленными на сервере. В Linux установите библиотеку конфигурации шрифтов перед первым открытием документа (fontconfig на RHEL и Fedora):
apt-get update && apt-get install -y libfontconfig1Без неё открытие документа завершается ошибкой с The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.. Это единственный системный пакет, необходимый Doconut; libgdiplus не требуется.
Её зависимости предоставляют базовый набор шрифтов (DejaVu), поэтому документы отрисовываются сразу. Документ, запрашивающий шрифт, которого нет на сервере — Calibri, Arial или Times New Roman в типичном образе Linux — получает ближайший установленный шрифт, поэтому текст может иметь другую ширину, а разрывы строк могут отличаться от Windows. Для вывода, ближе к Windows, установите метрически совместимые заменители fonts-liberation, fonts-crosextra-carlito и fonts-crosextra-caladea; добавьте fonts-noto-core или fonts-noto-cjk для других скриптов, либо скопируйте свои файлы .ttf/.otf в /usr/share/fonts/ и запустите fc-cache -f.
Alpine и другие дистрибутивы на основе musl не поддерживаются.
Где что настраивать
| Что нужно | Как настроить |
|---|---|
| Чёткие страницы | ImageResolution в конфигурации формата |
| Точный поиск текста в HTML/EPUB/email/MHT/MPP | DefaultRender = false в конфигурации формата |
| Меньше памяти для огромных документов | CachePages = false, явно закрывайте сессии |
| Свой штамп на каждой странице | DocOptions.Watermark |
Была ли эта страница полезной?