Конвеєр рендерингу

Між OpenDocumentAsync і PNG, який потрапляє в браузер, існує два окремі етапи: визначення переглядача (який движок завантажує документ, визначається один раз при відкритті) і обробка сторінки (що відбувається з кожним зображенням сторінки при кожному запиті). Знання обох пояснює, чому формат рендериться так, як він рендериться — і що насправді перемикає DefaultRender.

Етап 1 — Визначення переглядача формату

Фабрика зіставляє розширення файлу з переглядачем через каталог форматів, використовуючи три рівні пріоритету:

1. Спочатку користувацькі переглядачі. Все, що ви зареєстрували за допомогою DoconutOptions.RegisterViewer(extension, factory, defaultConfig?), переважає будь-які вбудовані.
2. Вбудовані переглядачі сімейства. Каталог зіставляє кожне розширення, яке можна переглянути, з сімейством переглядачів — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — кожне має свій адаптер движка. Якщо ліцензований плагін додає переглядач для того ж розширення, переглядач плагіна замінює вбудований. AddDoconut() перевіряє зареєстровані права плагінів під час запуску; резервний варіант фабрики до вбудованого переглядача є захисним правилом виконання.
3. Формати лише з плагінами. Деякі розширення зовсім не мають вбудованого переглядача — 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 = типове для формату) є основним регулятором якості/пам'яті; типове значення для кожного формату задокументовано на його сторінці конфігурації.

Де налаштовувати що