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

Між 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

• Watermark — застосовується на основі стану ліцензії (відсутня ліцензія, закінчилась тимчасова або підписка, недійсний домен, неправильна версія) та з DocOptions.Watermark для вашого власного тексту. Правильно ліцензований додаток — або активна тимчасова ліцензія — без власного водяного знака пропускає цей крок.
• Rotate/flip — стан кожної сторінки, який користувач встановлює у віджеті (90°/180°/270°, горизонтальні/вертикальні відзеркалення), зберігається у сесії та застосовується при кожному наступному рендерингу цієї сторінки.
• Scale — мініатюри та рівні масштабування створюються шляхом масштабування відрендереної сторінки до запитаного розміру; 0 означає подачу у оригінальному розмірі.
• Annotation burn — збережені анотації накладаються на растрове зображення, щоб експорти та зображення сторінок їх відображали.
• Encoding — результат кодується у PNG за допомогою пулу потоків пам'яті та записується безпосередньо у HTTP‑відповідь.

Помилки всередині проміжного програмного забезпечення повертаються як PNG‑зображення помилок (червоний текст на білому), а не як HTTP‑сторінки помилок, щоб віджет міг відображати їх у області сторінки.

Кешування сторінок

BaseConfig.CachePages (за замовчуванням true) зберігає відрендерені зображення сторінок у пам'яті протягом всього сеансу документа, тому повторне відкриття сторінки не виконує повторний рендеринг. BaseConfig.ImageResolution (25–300 DPI, 0 = типове для формату) — головний регулятор якості/пам'яті; типове значення для кожного формату задокументовано на його сторінці конфігурації.

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