ViewerConfig – مستندات Doconut

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

ویژگی‌های 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"` 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`

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

ویجت دارای پیش‌فرض‌های قدیمی‌تری است که با کلاس 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	رابط کاربری حاشیه‌نویسی بسته شد.

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

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

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

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

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

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