Конвеєр рендерингу
Від документа до зображень сторінок
Між 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 |
Чи була ця сторінка корисною?