ViewerConfig – مستندات Doconut

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

دو تغییر سمت‌کلاینت در این نسخه به‌صورت ساکن شکست می‌خورند. توابع هندلر به‌عنوان گزینه‌ها پاس داده می‌شوند — ویجت دیگر نام توابع سراسری را از شناسهٔ کانتینر استخراج نمی‌کند — و 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 "`	پیشوند مورد استفاده در نکته‌نمای صفحه.
`bool`	`CacheEnabled`	`false`	یک پنجره متحرک از تصاویر صفحه را در حافظه مرورگر نگه می‌دارد. از `localStorage` استفاده نمی‌کند.
`bool`	`LargeDoc`	`false`	عناصر صفحه را به صورت دسته‌های زمانی برای اسناد بزرگ اضافه می‌کند.
`bool`	`ShowHyperlinks`	`false`	پوشش‌های پیوندهای فرامتن را زمانی که پیکربندی سرور آن‌ها را استخراج کرده است، رندر می‌کند.
`bool`	`FixedZoom`	`true`	از درصد بزرگ‌نمایی ثابت به جای محاسبهٔ واکنش‌گرا استفاده می‌کند.
`int`	`FixedZoomPercent`	`100`	بزرگ‌نمایی ثابت برای دسکتاپ.
`int`	`FixedZoomPercentMobile`	`75`	بزرگ‌نمایی ثابت برای موبایل.
`string`	`BasePath`	`"/"`	شاخه‌ای که میزبان `UseDoconut()` را به آن نگاشت می‌کند.
`string`	`ResPath`	`"doconut-res"`	پایهٔ منبع مورد استفاده توسط ویجت. در تنظیمات عادی آن را به `<ResourcesPath>/images` اشاره کنید.
`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",
    ResPath = "/doconut-res/images",
    ShowHyperlinks = true
};

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

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`	جاوااسکریپت `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 هستند. نمایشگر قبلی توابع سراسری را که نامشان از شناسهٔ کانتینر استخراج می‌شد جستجو می‌کرد — صفحه‌ای با <div id="div_ctlDoc"> فقط کافی بود function ctlDoc_OnViewerReady() را تعریف کند. این جستجو حذف شده است. تابع را به‌صورت صریح پاس دهید:

javascript

objctlDoc = $('#div_ctlDoc').docViewer({
    // ... your existing options ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // was found by name
    onViewerReady:    ctlDoc_OnViewerReady,     // was found by name
    onCopy:           ctlDoc_Copy,              // was ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // was 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 باید به آن شاخه هدف‌گذاری شود. برنامهٔ مرجع شکل درخواست تاریخی DocImage.axd را بر روی شاخهٔ MapWhen حفظ می‌کند و بنابراین BasePath: '/' تنظیم می‌شود.
DoconutOptions.ResourcesPath مسیر منبع توکار است.
ResPath معمولاً به زیرپوشهٔ /images خود اشاره می‌کند — 'doconut-res/images' با پیشوند پیش‌فرض. یک ResPath خالی در کتابخانهٔ قبلی صحیح بود، جایی که منابع از ریشهٔ برنامه می‌آمدند؛ اینجا صحیح نیست و بدون خطا شکست می‌خورد.
ExtractHyperlinks باید در پیکربندی فرمت سرور فعال شود تا showHyperlinks بتواند چیزی نمایش دهد.