Doconut Viewer — це .NET бібліотека для перегляду документів, створена для розміщення PDF, Office, CAD, зображень та інших підтримуваних типів документів у вашому застосунку. Якісна інтеграція Doconut — це не просто найкоротший фрагмент коду, а правильний вибір чіткої межі між вашим застосунком, переглядачем та браузером.
Центр документації Doconut містить актуальні шляхи налаштування для підтримуваних типів .NET‑проєктів. Використовуйте посібник, який відповідає версії, встановленій у вашому застосунку, а навколишню сторінку, перевірки ідентифікації та процес доступу розглядайте як код застосунку, яким керує ваша команда.
Почніть з меж інтеграції
Існує три поширені способи розміщення попереднього перегляду документа у продукті. Правильний вибір залежить від того, хто відповідає за навігацію, аутентифікацію та життєвий цикл переглядача.
| Шаблон | Найкраще підходить | Головний компроміс |
|---|---|---|
| Перегляд застосунку | .NET‑сторінка, що рендерить переглядач поруч із елементами продукту | Тісна інтеграція, проте сторінка та переглядач мають спільний життєвий цикл |
| Iframe, яким керує застосунок | Портал, що потребує ізоляції між UI‑хостом та маршрутом попереднього перегляду | Чітка межа, проте комунікація має бути спроектована явно |
| Компонент фреймворку навколо серверного маршруту | Shell на React, Angular або Vue, підкріплений .NET‑застосунком | Звичний фронтенд‑композит, але з більшою кількістю станів життєвого циклу для керування |
Шаблон iframe не обов’язково має вказувати на публічний URL документа. Він може вказувати на автентифікований маршрут у вашому власному застосунку. Цей маршрут може перевіряти доступ і рендерити сторінку переглядача, не розкриваючи шлях до сховища хост‑сторінці.
Створіть стабільну, адаптивну поверхню попереднього перегляду
Не відтворюйте розмітку чи ініціалізацію переглядача на основі прикладів з блогу. Doconut постачає файли, проміжне ПЗ, простори імен та налаштування переглядача, що відповідають кожній підтримуваній .NET‑лінії. Наприклад, офіційний посібник з налаштування .NET 6 та вище описує серверне ПЗ, об’єкт переглядача, параметри документа, конфігурацію рендерингу та необхідні клієнтські ресурси.
Використовуйте ці версійні матеріали для створення переглядача, а потім задайте його контейнеру стабільну ширину та висоту у вашій розмітці. Зарезервуйте достатньо простору перед завантаженням, щоб навколишня сторінка не «підстрибувала», і протестуйте панель інструментів і першу сторінку на реальних точках перелому, підтримуваних вашим продуктом.
Перш ніж остаточно обрати композицію, порівняйте її з офіційними демо‑версіями Doconut. Демонстрації охоплюють різні стилі інтеграції .NET та фронтенду, включаючи окремий приклад iframe, і допомагають розрізнити офіційно підтримуваний шлях від виглядаючого правдоподібно фрагмента коду.
Тримайте рішення про доступ на сервері
Хост‑сторінка ніколи не повинна вирішувати, чи може користувач переглянути документ. Перед рендерингом маршруту попереднього перегляду застосунок має:
- Аутентифікувати запит.
- Авторизувати користувача для запитаного документа та орендаря.
- Отримати документ через ідентифікатор, контрольований сервером.
- Відкрити його у переглядачі лише після успішних перевірок.
- Повернути загальний статус «не знайдено» або «заборонено», не розкриваючи деталі сховища.
Непрозорий ідентифікатор покращує чистоту URL, але не замінює авторизацію. Застосовуйте ті ж перевірки до запитів сторінок, мініатюр, пошуку, анотацій, експорту та друку, які ви відкриваєте.
Визначте, як хост і переглядач будуть спілкуватися
Перегляд застосунку може викликати власні компоненти напряму. Для iframe потрібен більш вузький контракт. Визначте лише ті події, які дійсно потрібні хосту, наприклад:
- Попередній перегляд готовий
- Не вдалося відкрити документ
- Змінено поточну сторінку
- Сесія завершилася
- Користувач запросив закрити попередній перегляд
Якщо ви використовуєте postMessage, перевіряйте як event.origin, так і структуру повідомлення. Не допускайте використання підстановочних символів у продакшн‑середовищі та ніколи не передавайте облікові дані, шляхи до сховища чи сирий вміст документа через повідомлення.
Розгляньте обмеження браузера як додатковий захист
Iframe не ізольований автоматично. Атрибут sandbox може обмежити можливості, проте надмірно суворе значення може порушити скрипти переглядача, завантаження чи поведінку same‑origin. Починайте з найменшого набору можливостей, задокументованого для вашої інтеграції, і тестуйте його разом із вашою політикою Content Security Policy.
Також перевірте:
frame-ancestorsабоX-Frame-Optionsдля маршруту попереднього переглядуframe-srcдля хост‑сторінки- Поведінку cookie same‑site, якщо iframe потребує сесії
- Політику referrer для URL‑ів, що містять ідентифікатори маршруту
- Заголовки кешування для сторінок, що відображають конфіденційний матеріал
Ці налаштування належать до навколишнього застосунку та інфраструктури. Компонент переглядача не може самостійно вибрати правильну політику для вашої оренди та моделі загроз.
Розробіть стани завантаження, помилок та закінчення терміну
Порожній прямокутник не є корисним повідомленням про помилку. Забезпечте хост‑сторінку явними станами для відмови в авторизації, непідтримуваного вводу, пошкоджених файлів, тайм‑аутів та закінчення сесії. Формулюйте повідомлення так, щоб вони підказували дію, не розкриваючи внутрішніх шляхів чи деталей виключень.
Для довгих документів залишайте контейнер переглядача, доки не буде готова перша сторінка. Якщо користувачі можуть перемикатися між документами без переходу зі сторінки, скасуйте застарілі запити та скиньте видимий заголовок, кількість сторінок і фокус перед завантаженням наступного елементу.
Доступність та поведінка клавіатури
Надайте кожному iframe змістовний title. Забезпечте можливість навігації до попереднього перегляду за допомогою клавіатури, передбачте видимий спосіб повернення фокусу до хост‑сторінки та уникайте «захоплення» фокусу всередині кастомних накладок. Якщо у переглядача є власні клавіатурні скорочення, задокументуйте конфлікти з клавіатурними комбінаціями вашого продукту.
Доступна альтернатива може пропонувати контрольоване завантаження або інше представлення, коли це дозволяють ваші бізнес‑правила. Не додавайте публічне посилання на файл лише як запасний варіант.
Практичний чек‑лист перевірки
Перед випуском перевірте повний шлях запиту, а не лише початкове завантаження сторінки:
- Авторизований користувач може відкрити дозволений документ.
- Користувач з іншого орендаря не може повторно використати URL попереднього перегляду.
- Прямі запити до кінцевих точок переглядача проходять ті ж перевірки авторизації.
- Оновлення, навігація назад та закінчення сесії генерують зрозумілі стани.
- Попередній перегляд залишається працездатним при підтримуваних розмірах вікна та рівнях масштабування.
- Помилки в консолі браузера та невдалі мережеві запити видно у моніторингу.
- Журнали сховища та застосунку не містять секретів або повних URL‑ів документів.
Висновок
Найбільш підтримуване вбудовування Doconut — це те, що має невеликий, чітко визначений контракт. Нехай Doconut відповідає за роль переглядача документів, описану у його версійній документації, а ваш застосунок керує ідентифікацією, авторизацією, маршрутизацією, зберіганням, політикою браузера та зворотним зв’язком користувача. Коли будете готові протестувати готові приклади локально, скористайтеся офіційними ресурсами завантаження Doconut замість копіювання коду з несуміжних статей.