نمایشگر

Viewer (namespace Doconut) نقطهٔ ورودی عمومی برای باز کردن اسناد از صفحات Razor، کنترل‌کننده‌های MVC، کامپوننت‌های Blazor یا APIهای کمینه است. این کلاس قفل‌شده است، توسط AddDoconut() به عنوان سرویس موقت ثبت می‌شود و از طریق تزریق سازنده حل می‌شود — هرگز به‌صورت مستقیم آن را نمونه‌سازی نکنید.

کتابخانهٔ قبلی .NET Standard یک سازندهٔ عمومی ارائه می‌داد که حافظهٔ کش، دسترسی‌کنندهٔ زمینهٔ HTTP و یک یا چند مسیر مجوز را می‌گرفت. آن سازنده حذف شده است؛ گراف سرویس این وابستگی‌ها را فراهم می‌کند.

Viewer هیچ وضعیت درخواست‑محور نگه نمی‌دارد و عمداً اجرا نمی‌کند IDisposable: نشست‌های سند به‌صورت مستقل در کش نشست زندگی می‌کنند، بنابراین تخلیهٔ سرویس هرگز نمی‌تواند سند باز را از بین ببرد (به مفاهیم اصلی → نحوهٔ کار Viewer مراجعه کنید).

باز کردن سند به صورت ناهمزمان

یک سند را باز می‌کند و توکن نشست را که ویجت مشتری برای تمام درخواست‌های بعدی استفاده می‌کند، برمی‌گرداند. هر باز کردن به‌صورت ناهمزمان است — معادل همزمانی برای OpenDocument وجود ندارد.

// باز کردن ساده
string token = await viewer.OpenDocumentAsync(path);

// با پیکربندی و گزینه‌های هر فرمت
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// از یک بارگذاری
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

استثناهای قابل‌دسترس:

• LicenseException — یک مجوز یافت‌شده رد می‌شود (پیام شامل دلیل رد است)، یا فرمت به قابلیت افزونه‌ای نیاز دارد که دیگر اعطا نشده است. انقضای تقویم بدون پیام رد، به رندر با واترمارک تبدیل می‌شود به‌جای پرتاب استثنا.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — محتوای فایل خراب است یا با پسوند آن مطابقت ندارد.

بستن سند

void CloseDocument(string token)

نشست را از کش حذف می‌کند (موتور سند را بلافاصله تخلیه می‌کند)، نشان امنیتی را حذف می‌نماید و دسترسی اعطا شده را لغو می‌کند. این کار اختیاری است — انقضای لغزشی همان پاک‌سازی را انجام می‌دهد — اما برای اسناد بزرگ توصیه می‌شود.

دریافت تعداد صفحات

int GetPageCount(string token)

کل صفحات نشست باز را برمی‌گرداند. اگر توکن ناشناخته یا منقضی باشد، استثنا پرتاب می‌کند.

پرچم‌های قابلیت

از این‌ها در یک نمای Razor استفاده کنید تا Ribbon دارای مجوز فقط زمانی رندر شود که سرور واقعاً آن را سرویس‌دهی کند — به شروع سریع مراجعه کنید.

گزینه‌های DocOptions

گزینه‌های مستقل از فرمت برای هر باز کردن (namespace Doconut):

کلاس همچنین ویژگی‌های تخصصی را که عمداً خارج از جریان مشاهدهٔ تک‑هاست معمولی هستند، ارائه می‌دهد:

واترمارک سفارشی

DocOptions.Watermark از شش فیلد جدا شده با تیلده استفاده می‌کند. یک ^ پیش‌اختیاری درخواست چیدمان تمام‌گوشه‌ها را می‌کند:

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

پارسِر دقیقاً شش فیلد پس از ^ اختیاری انتظار دارد. یک تعریف نامعتبر با بازگشت پیش‌فرض قابل مشاهده Invalid Watermark SDK جایگزین می‌شود به‌جای این‌که به‌صورت ساکت ناپدید شود.

تصمیم‌گیری لایسنس

همان تصمیم برای تصاویر صفحات سرو‌شده و خروجی‌های حاشیه‌نویسی اعمال می‌شود. خروجی GIF انیمیشنی به‌صورت فریم به فریم مهر می‌شود. بنابراین واترمارک سفارشی یک ویژگی برنامه تحت لایسنس است، نه روشی برای جایگزینی یا سرکوب واترمارک ارزیابی.

API حاشیه‌نویسی

بارگذاری و صادرات حاشیه‌نویسی در سمت سرور. راهنمای کامل در راهنماها → حاشیه‌نویسی موجود است؛ سطح کار به این صورت است:

هر یک از این‌ها توکن جلسه را می‌گیرد. شکل GetAnnotationManager(pageWidth, pageHeight) بدون جلسه کتابخانه قبلی برای ساخت حاشیه‌نویسی‌ها خارج از جلسه باقی می‌ماند، اما بارگذاری آن‌ها همچنان به توکن نیاز دارد.

فراداده DICOM

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

این متد برای هم‌راستایی API وجود دارد، اما این بسته نمی‌تواند برچسب‌های فنی DICOM را فراهم کند: خواننده فراداده فقط یک نسخه .NET 8 را ارائه می‌دهد. برای جلسات DICOM و غیر‑DICOM مقدار null برمی‌گرداند؛ در یک جلسه DICOM همچنین یک هشدار یک‌بار مصرف می‌نویسد که محدودیت پلتفرم را توضیح می‌دهد. رندر صفحه، فریم و انیمیشن همچنان پشتیبانی می‌شود.

کمکی‌های منبع — ReferenceCss / ReferenceScripts

برچسب‌های <link>/<script> را برای منابع جاسازی‌شده‌ای که توسط UseDoconutResources() سرو می‌شوند، در ترتیب وابستگی صحیح تولید کنید. بسته‌ها برای ویژگی‌های تحت‌مجوز مانند جستجو و حاشیه‌نویسی فقط زمانی که مجوز آن‌ها را فعال می‌کند تولید می‌شوند، به‌طوری که رابط کاربری مشتری با رفتار سرور سازگار باشد.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + نمایشگر + جستجو + حاشیه‌نویسی
string ReferenceScripts(ScriptConfig? config = null)

پرچم‌های CssConfig: IncludeBootstrapCss، IncludeViewerCss، IncludeSearchCss (محدود به جستجو)، IncludeAnnotationCss (محدود به حاشیه‌نویسی).

پرچم‌های ScriptConfig: IncludeJQuery (نیازمند توسط همهٔ دیگران)، IncludeBootstrap، IncludeViewerScripts (هسته: docViewer.js + تقسیم‌کننده + پیوندها)، IncludeSearchScripts و IncludeSearchBar (محدود به جستجو)، IncludeAnnotationScripts و IncludeAnnotationBar (محدود به حاشیه‌نویسی).

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

این کمکی‌ها روش پشتیبانی‌شده برای تحویل منابع مرورگر هستند. برنامه‌هایی که
docViewer.js، documentLinks.js و docViewer.UI.js را به wwwroot کپی کرده‌اند، باید
این نسخه‌های کپی‌شده را پس از رندر شدن صفحه از برچسب‌های تولید‌شده حذف کنند.