ViewerConfig – مستندات Doconut

ViewerConfig (فضای‌نام Doconut) ظاهر و رفتار نمایشگر مرورگر را توصیف می‌کند. این موارد بر کیفیت رندر سند تأثیری ندارند؛ برای آن از پیکربندی فرمت استفاده کنید. کلاس C# و ویجت جاوااسکریپت که مدت‌هاست وجود دارد، مقادیر پیش‌فرض متفاوتی دارند، بنابراین مقادیر را به‌صورت صریح نگاشت کنید.

دو تغییر سمت‌کلاینت در این نسخه به‌صورت ساکت شکست می‌خورند. توابع هندلر به‌عنوان گزینه‌ها پاس داده می‌شوند — ویجت دیگر نام توابع سراسری را از شناسهٔ کانتینر استخراج نمی‌کند — و ResPath باید به پیشوند منابع اشاره کند نه به ریشهٔ برنامه. هر دو باعث می‌شوند سرور به‌درستی کار کند و هیچ‌چیزی در کنسول مرورگر گزارش نشود. اگر صفحه‌ای را از کتابخانهٔ قبلی منتقل می‌کنید، ابتدا فراخوانی‌ها و فهرست بررسی مسیر را بخوانید.

ویژگی‌های C#

نوع	ویژگی	پیش‌فرض	توضیح
`bool`	`ShowThumbs`	`true`	نمایش پنل تصویر بندانگشتی.
`bool`	`AutoLoad`	`false`	بارگذاری خودکار پس از مقداردهی اولیه. جریان توکن معمولاً `View(token)` را به‌صورت صریح فراخوانی می‌کند.
`bool`	`AutoFocus`	`true`	جابه‌جایی تمرکز/اسکرول مرورگر به نمایشگر هنگام مقداردهی اولیه.
`bool`	`AutoPageFocus`	`true`	نگه داشتن تصویر بندانگشتی فعلی در حین تغییر صفحات.
`int`	`PageZoom`	`100`	درصد زوم اولیه.
`int`	`ZoomStep`	`10`	درصد افزوده یا حذف‌شده توسط دستورات زوم.
`int`	`MaxZoom`	`300`	حداکثر درصد زوم.
`bool`	`ShowToolTip`	`true`	نمایش راهنمای موقعیت صفحه هنگام اسکرول.
`string`	`ToolTipPageText`	`"Page "`	پیشوند استفاده‌شده در راهنمای صفحه.
`bool`	`CacheEnabled`	`false`	نگهداری یک پنجرهٔ متحرک از تصاویر صفحه در حافظهٔ مرورگر. از `localStorage` استفاده نمی‌کند.
`bool`	`LargeDoc`	`false`	افزودن عناصر صفحه به‌صورت دسته‌های زمان‌بندی‌شده برای اسناد بزرگ.
`bool`	`ShowHyperlinks`	`false`	رندر لایه‌های ابرلینک وقتی پیکربندی سرور آن‌ها را استخراج می‌کند.
`bool`	`FixedZoom`	`true`	استفاده از درصد زوم ثابت به‌جای محاسبهٔ واکنش‌گرا.
`int`	`FixedZoomPercent`	`100`	زوم ثابت برای دسکتاپ.
`int`	`FixedZoomPercentMobile`	`75`	زوم ثابت برای موبایل.
`string`	`BasePath`	`"/"`	مکانی که نمایشگر درخواست‌های صفحه را می‌فرستد. `"/"` در ریشهٔ سایت `DocImage.axd` است؛ در غیر این صورت شاخه‌ای که میزبان `UseDoconut()` را نگاشت می‌کند، بدون پیشوند `/` (`"doconut"` به معنای `/doconut/DocImage.axd`).
`string`	`ResPath`	`"doconut-res/images"` (26.9.0؛ قبل از `"doconut-res"`)	پوشه‌ای که ویجت تصاویر خود را از آن بارگذاری می‌کند: پوشهٔ `images` زیر `ResourcesPath`، بدون پیشوند `/`.
`string`	`FitType`	`"width"`	`"width"`، `"height"`، یا خالی برای عدم تناسب خودکار. `"page"` توسط ویجت فعلی پذیرفته نمی‌شود.
`bool`	`RetryOn409`	`false`	فعال‌سازی نظرسنجی وقتی تولید صفحهٔ ناهمزمان/توزیعی پاسخ می‌دهد `202 Accepted`؛ `409` نیز برای سازگاری با سرورهای قدیمی‌تر پذیرفته می‌شود. برای نمایشگر همزمان معمولی لازم نیست.

csharp

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "doconut",           // بدون اسلش پیشرو '/' : نمایشگر آن را اضافه می‌کند ("/doconut" تبدیل به //doconut می‌شود، میزبان دیگر)
    ResPath = "doconut-res/images",
    ShowHyperlinks = true
};

نگاشت C# به جاوااسکریپت

از پاس دادن یک ViewerConfig به‌صورت مستقیم به docViewer(...) خودداری کنید. بیشتر کلیدهای ویجت به صورت camelCase هستند، در حالی که سه کلید مسیر/تناسب ثابت به صورت PascalCase هستند.

C#	جاوااسکریپت
`ShowThumbs`	`showThumbs`
`AutoLoad`	`autoLoad`
`AutoFocus`	`autoFocus`
`AutoPageFocus`	`autoPageFocus`
`PageZoom`	`pageZoom`
`ZoomStep`	`zoomStep`
`MaxZoom`	`maxZoom`
`ShowToolTip`	`showToolTip`
`ToolTipPageText`	`toolTipPageText`
`CacheEnabled`	`cacheEnabled`
`LargeDoc`	`largeDoc`
`ShowHyperlinks`	`showHyperlinks`
`FixedZoom`	`fixedZoom`
`FixedZoomPercent`	`fixedZoomPercent`
`FixedZoomPercentMobile`	`fixedZoomPercentMobile`
`BasePath`	`BasePath`
`ResPath`	`ResPath`
`FitType`	`FitType`
`RetryOn409`	`retryOn409`

پیش‌فرض‌های جاوااسکریپت

ویجت دارای پیش‌فرض‌های قدیمی‌تری است که با کلاس C# متفاوت هستند. مقادیر زیر از پیاده‌سازی فعلی docViewer.js می‌آیند.

گزینه	پیش‌فرض	نکات
`leftMinWidth` / `leftMaxWidth`	`220` / `800`	حدود عرض پنل تصویر بندانگشتی.
`showThumbs`	`true`	قابلیت مشاهده اولیه تصویر بندانگشتی.
`autoFocus` / `autoPageFocus`	`true` / `false`	`autoPageFocus` متفاوت از پیش‌فرض C# است.
`thumbWidth` / `thumbHeight` / `thumbPadding`	`150` / `200` / `10`	هندسه تصویر بندانگشتی به پیکسل.
`pageZoom` / `zoomStep` / `maxZoom`	`100` / `10` / `200`	JavaScript `maxZoom` متفاوت از C# (`300`) است.
`showToolTip` / `toolTipPageText`	`true` / `"Page "`	راهنمای موقعیت صفحه.
`format` / `doc` / `AccessToken`	`""` / `0` / `""`	مقادیر داخلی مقداردهی اولیه؛ معمولاً توسط `View(token)` پر می‌شوند.
`debugMode`	`false`	تشخیص‌های اضافی سمت کلاینت.
`FitType`	`""`	بدون تنظیم خودکار مگر اینکه ارائه شود.
`BasePath`	`"DocImage.axd"`	پیش‌فرض تاریخی کلاینت برای سازگاری حفظ شده است. میزبان‌های فعلی ASP.NET Core باید آن را به‌صورت صریح به شاخه میدل‌ورک نگاشته‌شده تنظیم کنند.
`ResPath`	`""`	به‌صورت صریح به مسیر تصاویر جاسازی‌شده تنظیم شود.
`cacheEnabled` / `cacheCount` / `cacheDelay`	`false` / `3` / `3`	پنجره پیش‌بارگذاری صفحه در حافظه و تأخیر.
`autoLoad`	`false`	جریان توکن صریح توصیه می‌شود.
`largeDoc`	`true`	با پیش‌فرض C# متفاوت است.
`fixedZoom`	`false`	با پیش‌فرض C# متفاوت است.
`fixedZoomPercent` / `fixedZoomPercentMobile`	`100` / `50`	مقدار موبایل متفاوت از C# (`75`) است.
`showHyperlinks`	`true`	نیاز به استخراج سمت سرور برای تولید پوشش‌ها دارد.

تمام مقادیر مهم رفتاری را تنظیم کنید به‌جای تکیه بر هر یک از پیش‌فرض‌ها:

html

<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

<script>
const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    autoFocus: true,
    autoPageFocus: true,
    pageZoom: 100,
    zoomStep: 10,
    maxZoom: 300,
    FitType: 'width',
    cacheEnabled: false,
    largeDoc: false,
    showHyperlinks: true,
    fixedZoom: true,
    fixedZoomPercent: 100,
    fixedZoomPercentMobile: 75,
    BasePath: 'doconut',
    ResPath: 'doconut-res/images',
    onViewerReady: function () {},
    onError: function (message) { console.error('DocViewer:', message); }
});
</script>

فراخوانی‌ها

فراخوانی	آرگومان‌ها	هدف
`onPageLoading`	`pageNum`	درخواست صفحه در حال شروع است.
`onPageLoaded`	`pageNum`	بارگذاری تصویر صفحه تکمیل شد.
`onThumbnailClicked`	`pageNum`	کاربر یک تصویر بندانگشتی را انتخاب کرد.
`onPageClicked`	`pageNum`	کاربر یک صفحه را انتخاب کرد.
`onDoubleClick`	none	نمایشگر یک دوبار کلیک دریافت کرد.
`onViewerBusy`	none	نمایشگر به حالت مشغول رفت.
`onViewerReady`	none	مقداردهی اولیه تکمیل شد.
`onViewerError`	none	نمایشگر به حالت خطا رفت.
`onError`	`message`	یک عملیات پیام خطا برگرداند.
`onCopy`	`data`	داده‌های کپی متن در دسترس هستند.
`onAutoLoadStatus`	`pageNum`	بارگذاری خودکار به صفحه‌ای پیشرفت کرد.
`onThumbsShown`	none	پنل تصویر بندانگشتی قابل مشاهده شد.
`onAnnLoaded`	none	داده‌های حاشیه‌نویسی بارگذاری شد.
`onAnnSaved`	none	داده‌های حاشیه‌نویسی ذخیره شد.
`onAnnSaveError`	none	ذخیره‌سازی حاشیه‌نویسی ناموفق بود.
`onAnnClosed`	none	رابط کاربری حاشیه‌نویسی بسته شد.

بازخوانی‌ها را سریع نگه دارید؛ تله‌متری را به‌صورت ناهمزمان ارسال کنید و از مسدود کردن رندر صفحه خودداری کنید.

هر یک از این‌ها یک گزینه در شیء init است. نمایشگر قبلی توابع سراسری را که نام‌هایشان را از شناسهٔ container استخراج می‌کرد، جستجو می‌کرد — صفحه‌ای که <div id="div_ctlDoc"> داشت فقط کافی بود function ctlDoc_OnViewerReady() را اعلام کند. آن جستجو حذف شده است. تابع را به‌صورت صریح پاس دهید:

javascript

objctlDoc = $('#div_ctlDoc').docViewer({
    // ... گزینه‌های موجود شما ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // با نام یافت شد
    onViewerReady:    ctlDoc_OnViewerReady,     // با نام یافت شد
    onCopy:           ctlDoc_Copy,              // بود ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // بود ctlDoc_AutoLoadStatus(page)
});

جستجوی قدیمی در یک catch خالی بسته‌بندی شده بود، بنابراین هیچ‌چیز گزارش نمی‌شد. در این نسخه توابع به‌سادگی اجرا نمی‌شوند: علامت معمول یک نشانگر مشغول است که هرگز متوقف نمی‌شود، زیرا هندلری که آن را مخفی می‌کرد onViewerReady بود. سند پشت آن به‌درستی رندر می‌شود.

هیچ بازخوانی کلیک لینک وجود ندارد — مدیریت پیوندها به‌صورت داخلی ساخته شده و توسط showHyperlinks هدایت می‌شود.

گروه‌های متدهای عمومی

گروه	متدهای مشترک
دوره‌زندگی	`View(token, accessToken?)`, `Close(server?)`, `Token()`, `Init()`, `IsLoaded()`
ناوبری	`GotoPage(page)`, `ShowPage(page, focus?)`, `Next(next)`, `CurrentPage()`, `TotalPages()`
بزرگ‌نمایی و تناسب	`Zoom(zoomIn)`, `CurrentZoom()`, `FitType(value)`, `Refit()`
جهت‌گیری	`Rotate(page, angle)`, `Flip(page, flipType)`
تصاویر بندانگشتی	`HideThumbs(hide)`, `ThumbSize(size)`, `ReloadThumbs(width)`, `ScrollToThumb(thumb)`
جستجو	`CanSearch()`, `Search(...)`, `SearchMatchCount()`, `SearchSummary(...)`, `GotoSearchMatch(...)`
حاشیه‌نویسی	`SaveAnnotations()`, `GetAnnotations()`, `PushAnnotations(...)`, `CloseAnnotations(...)`, `ShowAnnotations(...)`
کپی	`Copy(...)`, `CopyPage(pageNumber)`, `CopyMode(enabled)`

فایل جاوااسکریپت همچنین شامل کمک‌کننده‌های داخلی است. فقط متدهایی که توسط رابط کاربری مرجع استفاده می‌شوند و در اینجا یا در راهنمای ویژگی‌ها مستند شده‌اند را به‌عنوان نقاط یکپارچه‌سازی ثابت در نظر بگیرید.

تلاش مجدد در حالی که صفحه توزیع‌شده هنوز در حال رندر است

retryOn409 نام تاریخی خود را حفظ می‌کند. این برای تولید صفحه به‌صورت ناهمزمان است و پاسخ آمادگی 202 Accepted فعلی را به‌همراه سیگنال قدیمی‌تر 409 Conflict دوباره تلاش می‌کند. هنگامی که فعال باشد، ویجت با این پیش‌فرض‌های جاوااسکریپت نظرسنجی می‌کند:

گزینه	پیش‌فرض
`retryInitialDelayMs`	`250`
`retryBackoffFactor`	`1.6`
`retryMaxDelayMs`	`2500`
`retryMaxAttempts`	`60`
`retryMaxTotalMs`	`120000`

برای نمایشگر تک‌نودی معمولی آن را غیرفعال بگذارید. فعال‌سازی آن نمی‌تواند رندر همزمانی که پشتیبانی نمی‌شود را به‌صورت ناهمزمان تبدیل کند.

آن را زمانی فعال کنید که صفحات از ذخیره‌سازی مشترک با FirstPagePriority سرو می‌شوند، جایی که صفحات بعدی به‌صورت مشروع تا زمان نوشتن پاسخ 202 Accepted می‌دهند. کلاینتی که دوباره تلاش نمی‌کند، کاشی‌های خراب برای صفحاتی که هنوز در حال رندر هستند نشان می‌دهد — ببینید استقرارهای توزیع‌شده.

فهرست بررسی مسیر

DoconutOptions.MiddlewarePath باید شاخه‌ای که در واقع نقشه می‌کنید را توصیف کند.
BasePath باید آن شاخه را هدف بگیرد، به‌صورت نوشته‌شده بدون پیشوند / ('doconut'، نه '/doconut': نمایشگر اسلش را اضافه می‌کند، و //doconut/... یک درخواست به میزبان دیگر است). برنامه مرجع شکل تاریخی درخواست DocImage.axd را بر روی شاخهٔ MapWhen حفظ می‌کند و بنابراین BasePath: '/' را تنظیم می‌کند.
DoconutOptions.ResourcesPath مسیر منبع جاسازی‌شده است.
ResPath به‌طور معمول زیرپوشهٔ images خود را هدف می‌گیرد، بدون پیشوند / — 'doconut-res/images' با پیشوند پیش‌فرض. یک ResPath خالی در کتابخانهٔ قبلی صحیح بود، جایی که منابع از ریشهٔ برنامه می‌آمدند؛ اینجا صحیح نیست و بدون خطا شکست می‌خورد.
ExtractHyperlinks باید در پیکربندی فرمت سرور فعال شود قبل از اینکه showHyperlinks بتواند چیزی نمایش دهد.