نمایشگر

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

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

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

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

متادیتای DICOM

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

این متد برای هم‌راستایی API وجود دارد، اما نمایشگر DICOM .NET 6 نمی‌تواند برچسب‌های فنی را فراهم کند. برای جلسات 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 }))

دریافت نام‌های کاربرگ‌ها

IReadOnlyList<string> GetWorksheetNames(string token)

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

اضافه شده در ۲۶.۹.۰.