نمایشگر Doconut یک کتابخانه .NET برای مشاهده اسناد است که برای قرار دادن PDF، Office، CAD، تصویر و سایر خانوادههای اسناد پشتیبانیشده در داخل یک برنامه طراحی شده است. یک یکپارچهسازی صحیح Doconut کمتر به یافتن کوتاهترین قطعه کد مربوط میشود و بیشتر به انتخاب یک مرز واضح بین برنامه شما، نمایشگر و مرورگر.
مرکز مستندات Doconut مسیرهای راهاندازی نگهداریشده برای انواع پروژههای .NET پشتیبانیشده را لینک میکند. راهنمایی را که با نسخه نصبشده در برنامه شما مطابقت دارد استفاده کنید، سپس صفحهٔ اطراف، بررسیهای هویت و جریان کاری دسترسی را بهعنوان کد برنامهای که تیم شما مالک آن است در نظر بگیرید.
شروع با مرز یکپارچهسازی
سه روش رایج برای قرار دادن پیشنمایش سند در یک محصول وجود دارد. انتخاب صحیح بستگی به این دارد که چه کسی ناوبری، احراز هویت و چرخه حیات نمایشگر را مالک است.
| الگو | بهترین تطبیق | معامله اصلی |
|---|---|---|
| نمایش برنامه | یک صفحه .NET که نمایشگر را در کنار کنترلهای محصول رندر میکند | یکپارچهسازی سفت و سخت، اما چرخه حیات صفحه و نمایشگر به هم پیوستهاند |
| iframe متعلق به برنامه | یک پورتال که به جداسازی بین رابط کاربری میزبان و مسیر پیشنمایش نیاز دارد | مرز واضح، اما ارتباط باید بهصورت صریح طراحی شود |
| کامپوننت چارچوب دور مسیر سرور | یک شل React، Angular یا Vue که توسط یک برنامه .NET پشتیبانی میشود | ترکیب فرانتاند آشنا، با حالتهای چرخه حیات بیشتری برای مدیریت |
الگوی iframe لازم نیست به یک URL سند عمومی اشاره کند. میتواند به یک مسیر احراز هویتشده در برنامهٔ خود شما اشاره کند. آن مسیر میتواند دسترسی را تأیید کرده و صفحهٔ نمایشگر را بدون افشای مسیر ذخیرهسازی به صفحهٔ میزبان رندر کند.
ساخت سطح پیشنمایش پایدار و واکنشگرا
از بازسازی مارکاپ یا مقداردهی اولیهٔ نمایشگر از یک قطعه کد نمونهٔ بلاگی خودداری کنید. Doconut فایلها، مراحل میانیافزار، فضای نامها و تنظیمات نمایشگر مناسب برای هر خط .NET پشتیبانیشده را منتشر میکند. برای مثال، راهنمای رسمی راهنمای راهاندازی .NET 6 یا بالاتر سرور میانیافزار، شیء نمایشگر، گزینههای سند، پیکربندی رندر و داراییهای مورد نیاز کلاینت را توضیح میدهد.
از این مواد نسخهبندیشده برای ایجاد نمایشگر استفاده کنید، سپس ناحیهٔ میزبان آن را با عرض و ارتفاع ثابت در طرح خود تنظیم کنید. پیش از بارگذاری فضای کافی رزرو کنید تا صفحهٔ اطراف پرش نکند و نوار ابزار و صفحهٔ اول را در نقاط شکست واقعی که محصول شما پشتیبانی میکند، آزمایش کنید.
قبل از نهاییسازی ترکیب، آن را با دموهای زنده Doconut رسمی مقایسه کنید. این دموها سبکهای مختلف یکپارچهسازی .NET و فرانتاند را شامل یک مثال اختصاصی iframe پوشش میدهند و به تشخیص مسیر رسمی پشتیبانیشده از یک قطعه کد ظاهراً قابل قبول کمک میکنند.
نگهداری تصمیمات دسترسی در سرور
صفحهٔ میزبان هرگز نباید تصمیم بگیرد که آیا کاربر میتواند سندی را مشاهده کند یا نه. پیش از رندر مسیر پیشنمایش، برنامه باید:
- درخواست را احراز هویت کنید.
- کاربر را برای سند درخواستشده و مستأجر موردنظر مجاز کنید.
- سند را از طریق یک شناسه کنترلشده توسط سرور حل کنید.
- پس از عبور این بررسیها، آن را از طریق نمایشگر باز کنید.
- وضعیت عمومی «یافت نشد» یا «ممنوع» را بدون افشای جزئیات ذخیرهسازی برگردانید.
یک شناسهٔ مبهم به بهبود بهداشت URL کمک میکند، اما خود مجوز نیست. همان بررسیها را برای درخواستهای صفحه، تصویر بندانگشتی، جستجو، حاشیهنویسی، خروجی و چاپ که در دسترس قرار میدهید، اعمال کنید.
تصمیمگیری درباره نحوه ارتباط میزبان و نمایشگر
یک نمایش برنامه میتواند مؤلفههای خود را مستقیماً فراخوانی کند. یک iframe به قرارداد باریکتری نیاز دارد. فقط رویدادهایی را تعریف کنید که میزبان واقعاً به آنها نیاز دارد، مانند:
- پیشنمایش آماده
- سند باز نشد
- صفحه فعلی تغییر کرد
- جلسه منقضی شد
- کاربر درخواست بسته شدن پیشنمایش را داد
اگر از postMessage استفاده میکنید، هم event.origin و هم شکل پیام را اعتبارسنجی کنید. در محیط تولید مبداهای عامالمنطقی را نپذیرید و هرگز اعتبارنامهها، مکانهای ذخیرهسازی یا محتوای خام سند را از طریق پیامها عبور ندهید.
در نظر گرفتن محدودیتهای مرورگر به عنوان دفاع لایهای
یک iframe بهصورت خودکار ایزوله نیست. ویژگی sandbox میتواند قابلیتها را کاهش دهد، اما مقدار بیش از حد سخت میتواند اسکریپتهای نمایشگر، دانلودها یا رفتار همانمنشا را نیز خراب کند. از کوچکترین مجموعهٔ قابلیتهای مستند شده برای یکپارچهسازی خود شروع کنید و آن را با سیاست امنیت محتوا (CSP) خود آزمایش کنید.
همچنین بازبینی کنید:
frame-ancestorsیاX-Frame-Optionsبرای مسیر پیشنمایشframe-srcبرای صفحه میزبان- رفتار کوکیهای همانسایت اگر iframe به جلسه نیاز دارد
- سیاست ارجاع برای URLهایی که شامل شناسههای مسیریابی هستند
- سرآیندهای کش برای صفحاتی که محتوای حساس نمایش میدهند
این کنترلها متعلق به برنامهٔ اطراف و زیرساختها هستند. یک مؤلفهٔ نمایشگر نمیتواند سیاست صحیح را برای مستأجر و مدل تهدید شما انتخاب کند.
طراحی حالتهای بارگذاری، خطا و انقضا
یک مستطیل خالی پیام خطای مفیدی نیست. برای صفحهٔ میزبان حالتهای صریحی برای شکست احراز هویت، ورودی پشتیبانینشده، فایلهای خراب، زمانسنجیها و جلسات منقضیشده فراهم کنید. متن را قابل اقدام نگه دارید بدون اینکه مسیرهای داخلی یا جزئیات استثناها فاش شوند.
برای اسناد طولانی، محفظهٔ نمایشگر را در حالی که صفحهٔ اول آماده میشود، حفظ کنید. اگر کاربران میتوانند بدون ترک صفحه اسناد را تغییر دهند، درخواستهای منقضیشده را لغو کنید و عنوان قابل مشاهده، شمارش صفحات و فوکوس را پیش از بارگذاری مورد بعدی بازنشانی کنید.
دسترسپذیری و رفتار صفحهکلید
به هر iframe یک title مفید بدهید. پیشنمایش را با صفحهکلید قابل دسترس کنید، راهی قابل مشاهده برای بازگرداندن فوکوس به صفحهٔ میزبان فراهم کنید و فوکوس را داخل لایههای سفارشی قفل نکنید. اگر نمایشگر دارای میانبرهای صفحهکلید خود است، تضادها را با میانبرهای استفادهشده در پوستهٔ محصول خود مستند کنید.
یک گزینهٔ جایگزین دسترسپذیر میتواند دانلود کنترلشده یا نمایشی جایگزین ارائه دهد وقتی قوانین تجاری شما اجازه میدهد. تنها به عنوان جایگزین، لینک فایل عمومی اضافه نکنید.
چکلیست تأیید عملی
قبل از انتشار، مسیر کامل درخواست را بهجای فقط بارگذاری اولیهٔ صفحه تأیید کنید:
- یک کاربر مجاز میتواند سند مجاز را باز کند.
- کاربری از مستأجر دیگر نمیتواند URL پیشنمایش را دوباره استفاده کند.
- درخواستهای مستقیم به نقاط انتهایی مرتبط با نمایشگر همان بررسیهای مجوز را دریافت میکنند.
- تازهسازی، ناوبری بازگشت و انقضای جلسه حالتهای قابلدرک تولید میکنند.
- پیشنمایش در اندازههای نمای پشتیبانیشده و سطوح زوم قابل استفاده باقی میماند.
- خطاهای کنسول مرورگر و درخواستهای شبکه ناموفق در مانیتورینگ قابل مشاهده هستند.
- لاگهای ذخیرهسازی و برنامه اسرار یا URLهای کامل سند را ثبت نمیکنند.
نتیجهگیری
قابلنگهداریترین یکپارچهسازی Doconut همان است که قرارداد کوچک و صریحی داشته باشد. بگذارید Doconut نقش مشاهدهگر سند را که در مستندات نسخهبندیشدهاش توصیف شده، بر عهده بگیرد، در حالی که برنامهٔ شما هویت، احراز هویت، مسیریابی، نگهداری، سیاست مرورگر و بازخورد کاربر را مالک است. وقتی آمادهٔ ارزیابی مثالهای بستهبندیشده بهصورت محلی هستید، به جای کپی کردن منبع از مقالهای نامرتبط، از منابع دانلود Doconut رسمی استفاده کنید.