نمایشگر

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

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

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

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

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

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

بارگذاریزمان استفاده
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 پرتاب می‌شود.

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

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

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

گزینه‌های مستقل از قالب برای هر باز کردن (فضای نام 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 را تنظیم کنید. به حروف توجه کنید — کتابخانه قبلی این را به صورت IsWebfarm نوشت.
stringWebFarmPath""منسوخ — بدون اثر. از FileShareConfig.RootPath استفاده کنید، همان‌طور که در استقرارهای توزیع‌شده توضیح داده شده است. قبلاً به صورت WebfarmPath نوشته می‌شد.
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 ^^چیدمان تمام‌گوشه‌ای اختیاری. بدون آن، مکان‌گذاری معمولی واترمارک استفاده می‌شود.
متنConfidentialمتنی که بر هر صفحه رندر می‌شود. نباید خالی باشد.
رنگRedرنگ نام‌گذاری شده‌ای که لایه رسم آن را می‌فهمد.
اندازه‌فونت24اندازه فونت؛ ورودی عددی نامعتبر به پیش‌فرض رندرر باز می‌گردد.
نام‌فونتVerdanaخانواده فونت درخواست‌شده. اطمینان حاصل کنید که در محیط استقرار نصب شده باشد.
شفافیت80مقدار بایتی از ۰ تا ۲۵۵. باید به‌درستی تجزیه شود.
زاویه-45زاویه چرخش بر حسب درجه؛ ورودی عددی نامعتبر به پیش‌فرض باز می‌گردد.

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

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

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

همان تصمیم برای تصاویر صفحات سرو شده و خروجی‌های حاشیه‌نویسی اعمال می‌شود. خروجی 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های هر صفحه با حاشیه‌نویسی‌های تعبیه‌شده

هر یک از این‌ها توکن جلسه را می‌گیرد. شکل بدون‌جلسهٔ کتابخانهٔ قبلی GetAnnotationManager(pageWidth, pageHeight) برای ساخت حاشیه‌نویسی‌ها خارج از جلسه باقی می‌ماند، اما بارگذاری آن‌ها همچنان به توکن نیاز دارد.

فراداده DICOM

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

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

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

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

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
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 }))

این کمک‌کننده‌ها روش پشتیبانی‌شده برای تحویل منابع مرورگر هستند. برنامه‌هایی که docViewer.js، documentLinks.js و docViewer.UI.js را به wwwroot کپی کرده‌اند باید پس از رندر صفحه از برچسب‌های صادرشده، آن نسخه‌های کپی‌شده را حذف کنند.

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