نمایشگر
کلاس اصلی نمایشگر سند
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 باید پسوند صحیح را داشته باشد — که تشخیص قالب را هدایت میکند |
// باز کردن ساده
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— محتوای فایل خراب است یا با پسوند آن مطابقت ندارد.
بستن سند
void CloseDocument(string token)نشست را از کش حذف میکند (موتور سند را بلافاصله تخلیه میکند)، علامت امنیتی را حذف مینماید و دسترسی اعطا شده را لغو میکند. این کار اختیاری است — انقضای لغزان همان پاکسازی را انجام میدهد — اما برای اسناد بزرگ توصیه میشود.
دریافت تعداد صفحات
int GetPageCount(string token)تعداد کل صفحات نشست باز. اگر توکن ناشناخته یا منقضی باشد، InvalidOperationException (Document session not found. Please re-open document.) پرتاب میشود و برای توکن خالی، ArgumentException پرتاب میشود.
دریافت ابعاد صفحه
(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 دارای مجوز فقط زمانی رندر شود که سرور واقعاً آن را سرو کند — ببینید شروع سریع.
گزینههای DocOptions
گزینههای مستقل از قالب، برای هر باز کردن (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 کنترل میشود (به Core Concepts → Sessions & Security مراجعه کنید). |
کلاس همچنین ویژگیهای تخصصی را که عمداً خارج از جریان مشاهده تکمیزبان عادی هستند، افشا میکند:
| نوع | ویژگی | پیشفرض | توضیح |
|---|---|---|---|
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
});| فیلد | مثال | معنی |
|---|---|---|
پیشرو ^ | ^ | چیدمان تمامگوشهای اختیاری. بدون آن، مکانگذاری معمولی واترمارک استفاده میشود. |
| متن | Confidential | متن رندر شده در هر صفحه. نباید خالی باشد. |
| رنگ | Red | رنگ نامگذاریشدهای که لایه رسم آن را میفهمد. |
| FontSize | 24 | اندازه فونت؛ ورودی عددی نامعتبر به پیشفرض رندر کننده باز میگردد. |
| FontName | Verdana | خانواده فونت درخواستشده. اطمینان حاصل کنید که در محیط استقرار نصب شده است. |
| Opacity | 80 | مقدار بایت از 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
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)متادیتای برچسب 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 }))آیا این صفحه مفید بود؟