نمایشگر
کلاس اصلی نمایشگر سند
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 باید پسوند صحیح را داشته باشد — این پسوند تشخیص قالب را هدایت میکند |
// باز کردن ساده
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)کل صفحات نشست باز. اگر توکن ناشناخته یا منقضی باشد، InvalidOperationException (Document session not found. Please re-open document.) پرتاب میشود، و برای توکن خالی، ArgumentException پرتاب میشود.
GetPageDimensions (دریافت ابعاد صفحه)
(int Width, int Height) GetPageDimensions(string token, int page = 1)اندازهٔ پیشفرض صفحهٔ رندر شدهٔ سند در زوم ۱۰۰٪ — فضای مختصاتی برای حاشیهنویسیهای ساختهشده در کد. page برای سازگاری پذیرفته میشود؛ نتیجه پیشفرض سند است. اگر توکن ناشناخته یا منقضی باشد، InvalidOperationException (Document session not found. Please re-open document.) پرتاب میشود، و برای توکن خالی، ArgumentException پرتاب میشود.
دریافت نامهای شیت
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):
| نوع | ویژگی | پیشفرض | توضیح |
|---|---|---|---|
string | Password | "" | رمز عبور برای اسناد محافظتشده (بهصورت خودکار به پیکربندی قالب کپی میشود). |
int | ImageResolution | 0 | منسوخ. فقط برای سازگاری نگه داشته شده — بهجای آن ImageResolution را در پیکربندی قالب تنظیم کنید. |
string | Watermark | "" | متن واترمارک سفارشی که بر روی صفحات رندر شده کشیده میشود. رشته قالب: "^Text~Color~FontSize~FontName~Opacity~Angle"، به عنوان مثال "^Sample Copy~Red~24~Verdana~80~-45". |
int | TimeOut | 60 | انقضای لغزشی جلسه بر حسب دقیقه. |
bool | IsSecured | true | در حال حاضر اعمال نمیشود — رزرو شده. بایندینگ توکن بهصورت سراسری توسط DoconutOptions.UnsafeMode کنترل میشود (به مفاهیم اصلی → جلسات و امنیت مراجعه کنید). |
کلاس همچنین ویژگیهای تخصصی را که عمداً خارج از جریان مشاهده تکسرور معمولی هستند، در دسترس قرار میدهد:
| نوع | ویژگی | پیشفرض | توضیح |
|---|---|---|---|
bool | IsWebFarm | false | منسوخ — بدون اثر. سند را با DistributedDocumentPublisher.PublishAsync (یا IDistributedPublishQueue.EnqueueAsync) منتشر کنید و بهجای آن FileShareConfig.RootPath را تنظیم کنید. به حروف توجه کنید — کتابخانه قبلی این را به صورت IsWebfarm نوشت. |
string | WebFarmPath | "" | منسوخ — بدون اثر. از FileShareConfig.RootPath استفاده کنید، همانطور که در استقرارهای توزیعشده توضیح داده شده است. قبلاً به صورت WebfarmPath نوشته میشد. |
bool | EditMode | false | رزرو شده برای یک جریان ویرایش توزیعشده جداگانه؛ برای نمایشگر استاندارد، false را رها کنید. |
واترمارک سفارشی
DocOptions.Watermark از شش فیلد جدا شده با تیلدا استفاده میکند. یک ^ پیشدرآمدی اختیاری درخواست چیدمان تمامگوشهها را میکند:
^Text~Color~FontSize~FontName~Opacity~Anglestring 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
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 + 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 را مسدود میکند).
@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 کپی کردهاند باید پس از رندر صفحه از برچسبهای صادرشده، آن نسخههای کپیشده را حذف کنند.
آیا این صفحه مفید بود؟