نمایشگر
کلاس اصلی نمایشگر سند
Viewer (namespace Doconut) نقطه ورودی عمومی برای باز کردن اسناد از صفحات Razor، کنترلرهای MVC، کامپوننتهای Blazor یا APIهای مینیمال است. این کلاس sealed است، توسط AddDoconut() به عنوان سرویس transient ثبت میشود و از طریق تزریق سازنده حل میشود — هرگز بهصورت مستقیم آن را ساخت نکنید.
Viewer هیچ وضعیت درخواست‑به‑درخواست نگه نمیدارد و عمداً پیادهسازی IDisposable نمیکند: نشستهای سند بهصورت مستقل در کش نشست زندگی میکنند، بنابراین تخلیه سرویس هرگز نمیتواند سند باز را از بین ببرد (به مفاهیم اصلی → نحوه کار نمایشگر مراجعه کنید).
OpenDocumentAsync
یک سند را باز میکند و توکن نشست را که ویجت مشتری برای تمام درخواستهای بعدی استفاده میکند، برمیگرداند.
| Overload | Use 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 باید پسوند صحیح را داشته باشد — این پسوند تشخیص فرمت را هدایت میکند |
// باز کردن ساده
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 پرتاب میشود.
GetWorksheetNames
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):
| نوع | ویژگی | پیشفرض | توضیح |
|---|---|---|---|
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 را تنظیم کنید. |
string | WebFarmPath | "" | منسوخ — بدون اثر. بهجای آن از FileShareConfig.RootPath استفاده کنید. |
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 ^ | ^ | چیدمان تمام‑گوشههای اختیاری. بدون آن، مکانگذاری معمولی آبنشان استفاده میشود. |
| Text | Confidential | متنی که بر هر صفحه رندر میشود. نباید خالی باشد. |
| Color | Red | رنگ نامگذاریشدهای که لایه رسم آن را میشناسد. |
| FontSize | 24 | اندازه قلم؛ ورودی عددی نامعتبر به پیشفرض رندر بازمیگردد. |
| FontName | Verdana | خانواده قلم درخواستشده. اطمینان حاصل کنید که در محیط استقرار نصب شده باشد. |
| Opacity | 80 | مقدار بایت از ۰ تا ۲۵۵. باید بهدرستی تجزیه شود. |
| Angle | -45 | زاویه چرخش بر حسب درجه؛ ورودی عددی نامعتبر به پیشفرض بازمیگردد. |
تجزیهکننده دقیقاً شش فیلد پس از ^ اختیاری انتظار دارد. یک تعریف نامعتبر به جای آن توسط fallback قابل مشاهده SDK یعنی Invalid Watermark جایگزین میشود و بهصورت ساکت ناپدید نمیشود.
تصمیمگیری مجوز
| وضعیت مجوز | مقدار سفارشی ارائهشده | نتیجه رندر |
|---|---|---|
| Valid paid viewer license | No | صفحهٔ تمیز |
| Valid paid viewer license | Yes | آبنشان سفارشی |
| Active Temporary/Demo base viewer | No | صفحهٔ تمیز نمایشگر پایه |
| Active Temporary/Demo base viewer | Yes | آبنشان سفارشی وقتی مسیر نمایشگر پایهٔ تمیز اعمال میشود |
| Missing, rejected, expired, wrong-version, or invalid-domain license | Either | آبنشان اجرای/ارزیابی؛ مقدار سفارشی آن را بازنویسی نمیکند |
| Plugin rendering under evaluation rules | Either | آبنشان ارزیابی |
همان تصمیم برای تصاویر صفحهٔ سروشده و خروجیهای حاشیهنویسی اعمال میشود. خروجی 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
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)این متد برای همراستایی API وجود دارد، اما نمایشگر DICOM در .NET 6 نمیتواند برچسبهای فنی را فراهم کند. برای جلسات DICOM و غیر‑DICOM مقدار null را برمیگرداند؛ در یک جلسه DICOM همچنین یک هشدار یکبار مصرف مینویسد که محدودیت پلتفرم را توضیح میدهد. رندر صفحه، فریم و انیمیشن همچنان پشتیبانی میشود.
کمککنندههای منبع — ReferenceCss / ReferenceScripts
برچسبهای <link>/<script> را برای منابع جاسازیشدهای که توسط UseDoconutResources() سرو میشوند، به ترتیب وابستگی صحیح تولید کنید. بستهها برای ویژگیهای محدودشده توسط لایسنس مانند جستجو و حاشیهنویسی فقط زمانی که لایسنس آنها را فعال میکند تولید میشوند، بهطوری که رابط کاربری مشتری با رفتار سرور سازگار باشد.
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 را مسدود میکند).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))آیا این صفحه مفید بود؟