نمایشگر

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

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

OpenDocumentAsync

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

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
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 — محتوای فایل خراب است یا با پسوند آن مطابقت ندارد.

CloseDocument

void CloseDocument(string token)

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

GetPageCount

int GetPageCount(string token)

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

DocOptions

گزینه‌های مستقل از قالب برای هر باز‑کردن (فضای‌نام 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 حاشیه‌نویسی

بارگذاری و خروجی‌گیری حاشیه‌نویسی در سمت سرور. راهنمای کامل در Guides → Annotations موجود است؛ سطحی که در اینجا ارائه می‌شود عبارت است از:

متادیتای DICOM

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

متادیتای برچسب DICOM را برای جلساتی که از افزونه DICOM باز شده‌اند برمی‌گرداند؛ برای اسناد غیر‑DICOM null برمی‌گرداند.

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

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

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

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

پرچم‌های ScriptConfig: IncludeJQuery (برای همه دیگرها ضروری)، IncludeBootstrap، IncludeViewerScripts (هسته: docViewer.js + splitter + links)، 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 }))