نمایشگر

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

Viewer (namespace Doconut) نقطهٔ ورودی عمومی برای باز کردن اسناد از کنترلرهای MVC، صفحات Web Forms و هندلرها است. این یک سرویس موقتی است که توسط DoconutHost.Initialize ترکیب شده؛ آن را در جایی که استفاده می‌کنید حل کنید:

csharp
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() همچنین پس از اجرای DoconutHost.Initialize کار می‌کند — سرویس‌های یکسان را حل می‌کند — که باعث می‌شود کد منتقل‌شده از بستهٔ کلاسیک همچنان کامپایل شود. قبل از Initialize، استثنای InvalidOperationException را پرتاب می‌کند.

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

OpenDocumentAsync

یک سند را باز می‌کند و توکن نشست را که ویجت برای هر درخواست بعدی استفاده می‌کند، برمی‌گرداند. وقتی UnsafeMode برابر با false باشد (پیش‌فرض)، توکن به نشست ASP.NET درخواست فعلی اعطا می‌شود — آن را از درخواستی که وضعیت نشست دارد فراخوانی کنید (به جلسات و امنیت مراجعه کنید).

بارگذاریزمان استفاده
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)سند یک فایل روی دیسک نیست (یک بارگذاری، یک پایگاه داده، یک بلاب). fileInfo باید پسوند صحیح را داشته باشد — آن فرمت را انتخاب می‌کند
csharp
// باز کردن ساده
string token = await viewer.OpenDocumentAsync(path);

// با پیکربندی و گزینه‌های هر فرمت
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// از یک بارگذاری (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

استثناهایی که باید مدیریت شوند:

  • LicenseException — یک مجوز پیدا شد اما رد شد (پیام دلیل را حمل می‌کند)، یا فرمت به قابلیت افزونه‌ای نیاز دارد که مجوز آن را اعطا نمی‌کند.
  • FormatNotSupportedException — هیچ نمایشگری پسوند فایل را پشتیبانی نمی‌کند.
  • InvalidDataException — محتوا خراب است یا با پسوند آن مطابقت ندارد.

OpenDocument (synchronous)

برای کد‑پشت Web Forms و سایر کدهایی که از صفحات ناهمزمان استفاده نمی‌کنند:

text
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

هر کدام توکن را برمی‌گردانند و همچنین آن را در viewer.Token ذخیره می‌کنند. fileName باید پسوند صحیح را داشته باشد. این wrapperها برای فراخوانی از یک صفحه Web Forms ایمن هستند: مسیر باز کردن هرگز در زمینهٔ درخواست ASP.NET ادامه نمی‌یابد، بنابراین انتظار برای آن نمی‌تواند منجر به بن‌بست شود. این موضوع برای تمام APIهای ناهمزمان Doconut نه صادق است — به بخش Web Forms از افزونه مبدل مراجعه کنید.

CloseDocument

text
void CloseDocument(string token)

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

پرس‌و‌جوهای جلسه

عضوبازمی‌گرداند
int GetPageCount(string token)کل صفحات سند باز
(int Width, int Height) GetPageDimensions(string token, int page = 1)اندازه صفحه پیش‌فرض رندر شده با زوم ۱۰۰٪ — فضای مختصات برای حاشیه‌نویسی‌ها که در کد ساخته شده‌اند
IReadOnlyList<string> GetWorksheetNames(string token)ورق‌های کاری رندر شده یک صفحه‌گسترده، به ترتیب کتاب کار؛ برای سایر اسناد خالی است

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

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

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

نوعویژگیپیش‌فرضتوضیح
stringPassword""رمز عبور برای اسناد محافظت‌شده (به‌صورت خودکار به پیکربندی قالب کپی می‌شود).
stringWatermark""متن علامت آب سفارشی که بر روی صفحات رندر شده کشیده می‌شود — به زیر مراجعه کنید.
intTimeOut60انقضای لغزشی جلسه، به دقیقه.
stringBrowserId""مزارع وب: مرورگری که بلیت امضا شده به آن متصل است. آن را با DoconutFarmBinding.EnsureBrowserId تنظیم کنید (به جلسات و امنیت مراجعه کنید).
stringUserId""مزارع وب: کاربری که وارد شده است و بلیت به او متصل است، از DoconutFarmBinding.ResolveUserId.
intImageResolution0منسوخ. به جای آن ImageResolution را در پیکربندی قالب تنظیم کنید.
boolIsSecuredtrueرزرو شده؛ اعمال نمی‌شود. کنترل دسترسی DoconutOptions.UnsafeMode است.
boolIsWebFarm / string WebFarmPathfalse / ""برای کدی که از بسته کلاسیک مهاجرت کرده نگهداری می‌شود. آن‌ها حالت مزرعه را فعال نمی‌کنند — AddDoconutDistributed این کار را انجام می‌دهد.
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خانوادهٔ قلم. باید بر روی سرور نصب باشد — Windows Server فونت‌های کمتری نسبت به دسکتاپ دارد.
Opacity80۰ تا ۲۵۵. باید تجزیه شود.
Angle-45چرخش به درجه؛ ورودی عددی نامعتبر به پیش‌فرض باز می‌گردد.

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

تصمیم‌گیری لایسنس

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

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

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

در این بسته همیشه null را برمی‌گرداند، و درخواست متادیتای ویجت پاسخ می‌دهد 501 Not Implemented: خواندن برچسب‌های DICOM در .NET Framework در دسترس نیست. رندرینگ DICOM — صفحات، فریم‌ها و انیمیشن — کار می‌کند. ببینید افزونه DICOM.

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

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

text
string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // وضعیت license، برای محافظت از کد init ribbon
bool IsAnnotationEnabled { get; }

پرچم‌های CssConfig: IncludeBootstrapCss، IncludeViewerCss، IncludeSearchCss (محدود به جستجو)، IncludeAnnotationCss (محدود به حاشیه‌نویسی).

پرچم‌های ScriptConfig: IncludeJQuery (نیازمند توسط همهٔ دیگران)، IncludeBootstrap، IncludeViewerScripts (اسکریپت‌های اصلی نمایشگر)، IncludeSearchScripts و IncludeSearchBar (محدود به جستجو)، IncludeAnnotationScripts و IncludeAnnotationBar (محدود به حاشیه‌نویسی)، EmitFeatureFlags (پیش‌فرض true: همچنین یک اسکریپت inline window.Doconut.features = { search, annotation, editor } می‌نویسد؛ آن را به false تنظیم کنید تحت یک Content‑Security‑Policy که اسکریپت‌های inline را مسدود می‌کند).

هر دو HTML برمی‌گردانند: آن‌ها را با @Html.Raw(...) در MVC 5 بنویسید (در کنترلر تولید می‌شوند — نماها هیچ @inject ندارند) یا با <%= %> در Web Forms. شروع سریع هر دو را نشان می‌دهد.

RenderViewer

text
string RenderViewer(string elementId, string token, ViewerConfig? config = null)

یک بلوک <script> برمی‌گرداند که ویجت را بر روی عنصری با شناسهٔ elementId مقداردهی اولیه می‌کند و سند را نشان می‌دهد: docViewer({...}) ساخته‌شده از ViewerConfig (پیش‌فرض: BasePath: '/'، ResPath: 'doconut-res/images')، سپس .View(token). آن را پس از اسکریپت‌های نمایشگر بنویسید. اسکریپت تولید شده هیچ ارجاعی به شیء نمایشگر نگه نمی‌دارد، بنابراین صفحه‌ای که نوار ابزار خود را دارد باید به‌صورت دستی ویجت را مقداردهی کند. ببینید پیکربندی‌نمایشگر.

مزرعه وب

string? AccessToken بلیت امضاشده‌ای را نگه می‌دارد که توسط آخرین باز کردن هنگام فعال بودن حالت توزیع‌شده صادر شده و UnsafeMode برابر با false است؛ در یک سرور واحد null است. آن را با توکن به ویجت بفرستید: objViewer.View(token, accessToken).

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