نمایشگر

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

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

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

OpenDocumentAsync

یک سند را باز می‌کند و توکن نشست را که ویجت کلاینت برای تمام درخواست‌های بعدی استفاده می‌کند، برمی‌گرداند. هر باز کردن به صورت ناهمزمان است — هیچ 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 — محتوای فایل خراب است یا با پسوند آن مطابقت ندارد.

CloseDocument

void CloseDocument(string token)

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

GetPageCount

int GetPageCount(string token)

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

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

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

فقط شیت‌های رندر شده فهرست می‌شوند: شیت‌های مخفی و خالی حذف می‌شوند، و وقتی ExcelConfig.SheetNames رندر را محدود می‌کند، فقط همان شیت‌ها ظاهر می‌شوند. یک شیت همیشه یک صفحه نیست — شیت بسیار بزرگ در چند صفحه رندر می‌شود. اگر توکن ناشناخته یا منقضی باشد، استثنا پرتاب می‌کند.

Added in 26.9.0.

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

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

گزینه‌های سند

گزینه‌های مستقل از قالب برای هر باز کردن (فضای نام 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 کپی کرده‌اند، باید این نسخه‌های کپی‌شده را پس از رندر صفحه از برچسب‌های تولیدشده حذف کنند.