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`	هنگامی که درخواست صفحهٔ ناهمزمان/توزیعی به `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)`

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

تلاش مجدد پس از HTTP 409

retryOn409 برای تولید صفحه به‌صورت ناهمزمان است. وقتی فعال باشد، ویجت با این مقادیر پیش‌فرض JavaScript پرسش می‌کند:

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