ViewerConfig – Doconut مستندات

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

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

پیش‌فرض‌های 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 "`	ابزارک موقعیت صفحه.
`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 باید به آن شاخه هدف بگیرد.
DoconutOptions.ResourcesPath مسیر منبع جاسازی‌شده است.
ResPath به‌طور معمول زیرپوشهٔ /images آن را هدف می‌گیرد.
ExtractHyperlinks باید در پیکربندی فرمت سرور فعال شود تا showHyperlinks بتواند چیزی نمایش دهد.