نمایشگر

کلاس اصلی نمایشگر سند

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

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

OpenDocumentAsync

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

OverloadUse when
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)باز کردن از دیسک با تشخیص خودکار فرمت و پیکربندی پیش‌فرض فرمت
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)به گزینه‌های رندرینگ برای هر فرمت نیاز دارید (PdfConfig، WordConfig، …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)سند یک فایل روی دیسک نیست (بارگذاری، پایگاه‌داده، blob). fileInfo باید پسوند صحیح را داشته باشد — این پسوند تشخیص فرمت را هدایت می‌کند
csharp
// باز کردن ساده
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

text
void CloseDocument(string token)

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

GetPageCount

text
int GetPageCount(string token)

کل صفحات نشست باز. اگر توکن ناشناخته یا منقضی باشد، InvalidOperationException (Document session not found. Please re-open document.) پرتاب می‌شود، و برای توکن خالی ArgumentException پرتاب می‌شود.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

اندازه صفحه پیش‌فرض رندر شده سند در زوم ۱۰۰٪ — فضای مختصاتی برای حاشیه‌نویسی‌های ساخته‌شده در کد. page برای سازگاری پذیرفته می‌شود؛ نتیجه پیش‌فرض سند است. اگر توکن ناشناخته یا منقضی باشد، InvalidOperationException (Document session not found. Please re-open document.) پرتاب می‌شود، و برای توکن خالی ArgumentException پرتاب می‌شود.

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

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

فقط شیت‌های رندر شده فهرست می‌شوند: شیت‌های مخفی و خالی حذف می‌شوند، و وقتی ExcelConfig.SheetNames رندر را محدود می‌کند، تنها همان شیت‌ها ظاهر می‌شوند. یک شیت همیشه یک صفحه نیست — شیت بسیار بزرگ در چند صفحه رندر می‌شود. اگر توکن ناشناخته یا منقضی باشد، InvalidOperationException (Document session not found. Please re-open document.) پرتاب می‌شود، و برای توکن خالی ArgumentException پرتاب می‌شود.

در نسخه ۲۶.۹.۰ اضافه شده است.

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

عضومعنی
bool IsSearchEnabledمجوز فعلی Search را اعطا می‌کند
bool IsAnnotationEnabledمجوز فعلی Annotation را اعطا می‌کند

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

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

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

نوعویژگیپیش‌فرضتوضیح
stringPassword""گذرواژه برای اسناد محافظت‌شده (به‌صورت خودکار در پیکربندی قالب کپی می‌شود).
intImageResolution0منسوخ. فقط برای سازگاری نگه داشته شده — به‌جای آن ImageResolution را در پیکربندی قالب تنظیم کنید.
stringWatermark""متن آب‌نشان سفارشی که بر روی صفحات رندر شده کشیده می‌شود. رشته قالب: "^Text~Color~FontSize~FontName~Opacity~Angle"، به عنوان مثال "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60انقضای لغزشی جلسه بر حسب دقیقه.
boolIsSecuredtrueدر حال حاضر اجرا نمی‌شود — رزرو شده. بایندینگ توکن به‌صورت سراسری توسط DoconutOptions.UnsafeMode کنترل می‌شود (به مفاهیم اصلی → جلسات و امنیت مراجعه کنید).

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

نوعویژگیپیش‌فرضتوضیح
boolIsWebFarmfalseمنسوخ — بدون اثر. سند را با DistributedDocumentPublisher.PublishAsync (یا IDistributedPublishQueue.EnqueueAsync) منتشر کنید و به‌جای آن FileShareConfig.RootPath را تنظیم کنید.
stringWebFarmPath""منسوخ — بدون اثر. به‌جای آن از FileShareConfig.RootPath استفاده کنید.
boolEditModefalseبرای جریان کاری ویرایشگر توزیع‌شده جداگانه رزرو شده؛ برای نمایشگر استاندارد false را رها کنید.

آب‌نشان سفارشی

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

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
فیلدمثالمعنی
Leading ^^چیدمان تمام‑گوشه‌های اختیاری. بدون آن، مکان‌گذاری معمولی آب‌نشان استفاده می‌شود.
TextConfidentialمتنی که بر هر صفحه رندر می‌شود. نباید خالی باشد.
ColorRedرنگ نام‌گذاری‌شده‌ای که لایه رسم آن را می‌شناسد.
FontSize24اندازه قلم؛ ورودی عددی نامعتبر به پیش‌فرض رندر بازمی‌گردد.
FontNameVerdanaخانواده قلم درخواست‌شده. اطمینان حاصل کنید که در محیط استقرار نصب شده باشد.
Opacity80مقدار بایت از ۰ تا ۲۵۵. باید به‌درستی تجزیه شود.
Angle-45زاویه چرخش بر حسب درجه؛ ورودی عددی نامعتبر به پیش‌فرض بازمی‌گردد.

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

تصمیم‌گیری مجوز

وضعیت مجوزمقدار سفارشی ارائه‌شدهنتیجه رندر
Valid paid viewer licenseNoصفحهٔ تمیز
Valid paid viewer licenseYesآب‌نشان سفارشی
Active Temporary/Demo base viewerNoصفحهٔ تمیز نمایشگر پایه
Active Temporary/Demo base viewerYesآب‌نشان سفارشی وقتی مسیر نمایشگر پایهٔ تمیز اعمال می‌شود
Missing, rejected, expired, wrong-version, or invalid-domain licenseEitherآب‌نشان اجرای/ارزیابی؛ مقدار سفارشی آن را بازنویسی نمی‌کند
Plugin rendering under evaluation rulesEitherآب‌نشان ارزیابی

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

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

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

عضوهدف
AnnotationManager GetAnnotationManager(string token)مدیر مرتبط با ابعاد صفحهٔ جلسهٔ باز
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)مدیر با ابعاد صفحهٔ صریح
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)مدیر مستقل از جلسه
void LoadAnnotationData(string token, AnnotationManager manager)بارگذاری حاشیه‌نویسی‌های ساخته‌شده در C# به داخل جلسه
void LoadAnnotationData(string token, string annotationData)بارگذاری حاشیه‌نویسی‌ها از صفحهٔ رمزگذاری‌شده/پاکت Base64 که توسط AnnotationManager.GetAnnotationData() برگردانده می‌شود
void LoadAnnotationXML(string token, XmlDocument annotationXml)بارگذاری حاشیه‌نویسی‌ها از XML
XmlDocument GetAnnotationXML(string token)صادرات حاشیه‌نویسی‌های جلسه به صورت XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF با حاشیه‌نویسی‌های تعبیه‌شده
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)یک PNG برای هر صفحه، حاشیه‌نویسی‌های تعبیه‌شده، نوشته شده به directoryPath (در صورت عدم وجود ساخته می‌شود)؛ تعداد تصاویر نوشته‌شده را برمی‌گرداند
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)فایل ZIP شامل PNGهای هر صفحه با حاشیه‌نویسی‌های تعبیه‌شده

فراداده DICOM

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

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

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

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

text
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 (محدود به حاشیه‌نویسی)، EmitFeatureFlags (پیش‌فرض true: همچنین یک اسکریپت inline window.Doconut.features = { search, annotation, editor } می‌نویسد؛ آن را به false تنظیم کنید تحت یک Content‑Security‑Policy که اسکریپت‌های inline را مسدود می‌کند).

html
@inject Doconut.Viewer Viewer

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

آیا این صفحه مفید بود؟