Конвейер рендеринга
От документа к изображениям страниц
Между 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 = значение по умолчанию формата) является основным регулятором качества/памяти; значение по умолчанию каждого формата задокументировано на его странице конфигурации.
Рендеринг на одном узле vs. на многих
Всё выше описывает рендеринг на одном узле по запросу для сессии, которая открыла документ. Развёртывание, где один узел рендерит и публикует весь набор артефактов, а другие узлы обслуживают эти страницы из общего хранилища, использует иной путь чтения — см. Распределённые развертывания.
Шрифты в 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 |
Была ли эта страница полезной?