ViewerConfig – مستندات Doconut

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

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

خصوصیات 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 "`	پیشوند `"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"` before)	پوشه‌ای که ویجت تصاویر خود را از آن بارگذاری می‌کند: پوشهٔ `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`

پیش‌فرض‌های JavaScript

این ویجت دارای پیش‌فرض‌های قدیمی‌تری است که با کلاس 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`	`maxZoom` در JavaScript با C# (`300`) متفاوت است.
`showToolTip` / `toolTipPageText`	`true` / `"Page "`	راهنما (tooltip) موقعیت صفحه.
`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 بود. سند پشت آن به‌درستی رندر می‌شود.

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

گروه	متدهای مشترک
دوره‌زندگی	`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)`

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

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

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

گزینه	پیش‌فرض
`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 بتواند چیزی نمایش دهد، در پیکربندی فرمت سرور فعال شود.