نمایشگر

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

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

OpenDocumentAsync

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

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

CloseDocument

void CloseDocument(string token)

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

GetPageCount

int GetPageCount(string token)

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

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 حاشیه‌نویسی

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

فراداده DICOM

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

متادیتای برچسب 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 }))

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

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

اضافه شده در 26.9.0.