نمایشگر

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

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

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

باز کردن سند به صورت ناهمزمان

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

بستن سند

text
void CloseDocument(string token)

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

دریافت تعداد صفحات

text
int GetPageCount(string token)

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

دریافت ابعاد صفحه

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

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

دریافت نام‌های شیت

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 استفاده کنید تا نوار Ribbon دارای مجوز فقط زمانی رندر شود که سرور واقعاً آن را سرو کند — ببینید شروع سریع.

گزینه‌های DocOptions

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

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

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

نوعویژگیپیش‌فرضتوضیح
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
    });
فیلدمثالمعنی
پیش‌رو ^^چیدمان تمام‌گوشه‌ای اختیاری. بدون آن، مکان‌گذاری معمولی واترمارک استفاده می‌شود.
متنConfidentialمتن رندر شده در هر صفحه. نباید خالی باشد.
رنگRedرنگ نام‌گذاری‌شده‌ای که لایه رسم آن را می‌فهمد.
FontSize24اندازه فونت؛ ورودی عددی نامعتبر به پیش‌فرض رندر کننده باز می‌گردد.
FontNameVerdanaخانواده فونت درخواست‌شده. اطمینان حاصل کنید که در محیط استقرار نصب شده است.
Opacity80مقدار بایت از 0 تا 255. باید به‌درستی تجزیه شود.
Angle-45زاویه چرخش بر حسب درجه؛ ورودی عددی نامعتبر به مقدار پیش‌فرض باز می‌گردد.

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

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

وضعیت مجوزمقدار سفارشی ارائه‌شدهنتیجه رندر شده
مجوز نماینده پرداخت‌شده معتبرخیرصفحه تمیز
مجوز نماینده پرداخت‌شده معتبربلهواترمارک سفارشی
نماینده پایه موقت/دموی فعالخیرصفحه پایه‌نمایشگر تمیز
نماینده پایه موقت/دموی فعالبلهواترمارک سفارشی وقتی مسیر پایه‌نمایشگر تمیز اعمال می‌شود
مجوز گمشده، رد شده، منقضی‌شده، نسخه نادرست یا دامنه نامعتبرهر کدامواترمارک اعمال/ارزیابی؛ مقدار سفارشی آن را بازنویسی نمی‌کند
رندر افزونه تحت قوانین ارزیابیهر کدامواترمارک ارزیابی

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

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

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

عضوهدف
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)

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

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