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`	در زمان پاسخ تولید صفحهٔ ناهمزمان/توزیعی با `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# به 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 نیز شامل کمک‌کننده‌های داخلی است. فقط متدهایی که توسط رابط کاربری مرجع استفاده می‌شوند و در اینجا یا در راهنمای ویژگی‌ها مستند شده‌اند، به‌عنوان نقاط یکپارچه‌سازی پایدار در نظر بگیرید.

تلاش مجدد در حالی که صفحه توزیع‌شده هنوز در حال رندر است

retryOn409 نام تاریخی خود را حفظ کرده است. این گزینه برای تولید صفحهٔ ناهمزمان است و پاسخ آماده‌سازی 202 Accepted فعلی را به‌همراه سیگنال قدیمی 409 Conflict دوباره تلاش می‌کند. وقتی فعال باشد، ویجت با این پیش‌فرض‌های JavaScript نظرسنجی می‌کند:

گزینه	پیش‌فرض
`retryInitialDelayMs`	`250`
`retryBackoffFactor`	`1.6`
`retryMaxDelayMs`	`2500`
`retryMaxAttempts`	`60`
`retryMaxTotalMs`	`120000`

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

چک‌لیست مسیر

DoconutOptions.MiddlewarePath باید شاخه‌ای را که واقعاً نگاشت می‌کنید توصیف کند.
BasePath باید به آن شاخه هدف‌گذاری شود.
DoconutOptions.ResourcesPath مسیر منبع توکار است.
ResPath معمولاً به زیرپوشهٔ /images آن هدف می‌گیرد.
ExtractHyperlinks باید در پیکربندی فرمت سرور فعال شود تا showHyperlinks بتواند چیزی نمایش دهد.