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