پیکربندی‌نمایشگر – مستندات Doconut

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

ویژگی‌های C#

Type	Property	Default	Description
`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` در ریشهٔ سایت است. برای برنامه‌ای در یک دایرکتوری مجازی، نام دایرکتوری را بدون پیشوند `/` استفاده کنید (`"myapp"` به معنای `/myapp/DocImage.axd` است).
`string`	`ResPath`	`"doconut-res/images"`	پوشه‌ای که ویجت تصاویر خود را از آن بارگذاری می‌کند: پوشهٔ `images` زیر `ResourcesPath`، بدون پیشوند `/`.
`string`	`FitType`	`"width"`	`"width"`، `"height"`، یا خالی برای عدم تناسب خودکار. `"page"` توسط ویجت فعلی پذیرفته نمی‌شود.
`bool`	`RetryOn409`	`false`	درخواست‌های صفحه‌ای که پاسخ «هنوز در حال رندر» می‌دهند را دوباره تلاش می‌کند. `DocImage.axd` به‌صورت همزمان رندر می‌شود و هرگز این سیگنال را ارسال نمی‌کند؛ آن را `false` بگذارید.

csharp

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "/",                 // "/" = هندلر DocImage.axd در ریشه سایت (Web.config)
    ResPath = "doconut-res/images", // پوشه images زیر ResourcesPath، بدون '/' پیش‌رو
    ShowHyperlinks = true
};
// با viewer.RenderViewer("viewerEl", token, config) آن را صادر کنید - به مرجع Viewer مراجعه کنید.

تولید ViewerConfig با RenderViewer

Viewer.RenderViewer(elementId, token, config) یک ViewerConfig را به اسکریپت مقداردهی اولیهٔ ویجت تبدیل می‌کند. این مورد شش تا از ویژگی‌های بالا را می‌نویسد — BasePath، ResPath، ShowThumbs، AutoLoad، PageZoom و FitType — و سپس View(token) را فراخوانی می‌کند. سایر ویژگی‌ها نوشته نمی‌شوند: برای MaxZoom، ShowHyperlinks، تنظیمات زوم یا هر فراخوانی، خودتان ویجت را با گزینه‌های JavaScript زیر مقداردهی کنید. برای RenderViewer به نمایشگر مراجعه کنید.

نگاشت C# به JavaScript

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

C#	JavaScript
`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"`	پیش‌فرض قدیمی. به‌صورت صریح تنظیم کنید: `'/'` برای هندلر در ریشه سایت.
`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: '/',
    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 و تنظیمات بازگشت آن (retryInitialDelayMs، retryBackoffFactor، retryMaxDelayMs، retryMaxAttempts، retryMaxTotalMs) را می‌پذیرد. این‌ها برای استقرارهایی که صفحاتشان به‌صورت پس‌زمینه تولید می‌شود، کاربرد دارند. DocImage.axd هر صفحه را در طول درخواست رندر می‌کند، بنابراین retryOn409 را خاموش بگذارید.

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

BasePath زمانی که هندلر DocImage.axd در ریشه سایت باشد، '/' است — ویژگی path هندلر در Web.config تعیین می‌کند که کجا پاسخ می‌دهد. در یک دایرکتوری مجازی، از نام دایرکتوری بدون پیشوند / استفاده کنید ('myapp'، نه '/myapp': نمایشگر اسلش را اضافه می‌کند، و //myapp/... یک درخواست به میزبان دیگر است).
DoconutOptions.ResourcesPath جایی است که ماژول منبع فایل‌های جاسازی‌شده را سرو می‌کند (/doconut-res به‌صورت پیش‌فرض).
ResPath به زیرپوشه images خود هدف می‌گیرد، همچنین بدون پیشوند / ('doconut-res/images'). اشاره به 'doconut-res' باعث می‌شود تمام آیکون‌ها 404 شوند در حالی که سند همچنان رندر می‌شود.
در MVC، اگر آن را تغییر دهید، routes.IgnoreRoute("doconut-res/{*pathInfo}") باید پس از ResourcesPath باشد.
قبل از اینکه showHyperlinks بتواند چیزی نمایش دهد، باید ExtractHyperlinks در تنظیمات فرمت سرور فعال باشد.