ViewerConfig
گزینههای ویجت نمایشگر سمتکاربر
ViewerConfig (namespace Doconut) ظاهر و رفتار نمایشگر مرورگر را توصیف میکند. این بر کیفیت رندر سند تأثیری ندارد؛ برای آن از یک پیکربندی فرمت استفاده کنید. کلاس C# و ویجت جاوااسکریپت که مدت طولانی وجود دارد، پیشفرضهای متفاوتی دارند، بنابراین مقادیر را بهصورت صریح نگاشت کنید.
دو تغییر سمتکلاینت در این نسخه بهصورت ساکتانه شکست میخورند. توابع هندلر بهعنوان گزینهها پاس داده میشوند — ویجت دیگر فراخوانیهای رویداد خود را از شناسهٔ کانتینر استخراج نمیکند — و
ResPathباید به پیشوند منابع اشاره کند نه ریشهٔ برنامه. هر دو باعث میشوند سرور بهدرستی کار کند و هیچچیزی در کنسول مرورگر گزارش نشود. اگر صفحهای را از کتابخانهٔ قبلی منتقل میکنید، قبل از هر چیز، بازخوانیها و فهرست مسیرها را بخوانید.
ویژگیهای 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 نیز برای سازگاری با سرورهای قدیمیتر پذیرفته میشود. برای نمایشگر همزمان معمولی نیازی به آن نیست. |
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 | جاوااسکریپت maxZoom متفاوت از C# است (300). |
showToolTip / toolTipPageText | true / "Page " | راهنما (tooltip) موقعیت صفحه. |
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 | نیاز به استخراج سمت سرور برای تولید لایههای پوششی دارد. |
تمام مقادیر مهم رفتاری را تنظیم کنید بهجای تکیه بر هر یک از مجموعه پیشفرضها:
<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 | رابط کاربری حاشیهنویسی بسته شد. |
فراخوانیها را سریع نگه دارید؛ تلهمتری را بهصورت ناهمزمان ارسال کنید و از مسدود کردن رندر صفحه خودداری کنید.
هر یک از اینها یک گزینه در شیء init است. نمایشگر قبلی توابع سراسری را که نامهایشان را از شناسهٔ container استخراج میکرد جستجو میکرد — صفحهای که فقط <div id="div_ctlDoc"> داشت باید function ctlDoc_OnViewerReady() را اعلام میکرد. آن جستجو حذف شد. تابع را بهصورت صریح پاس دهید:
function ctlDoc_OnViewerBusy() { /* نمایش نشانگر مشغولیت خود را */ }
function ctlDoc_OnViewerReady() { /* پنهان کن */ }
function ctlDoc_Copy(text) { /* از متن کپیشده استفاده کنید */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* گزارش پیشرفت */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... گزینههای موجود شما ...
onViewerBusy: ctlDoc_OnViewerBusy, // بر اساس نام پیدا شد
onViewerReady: ctlDoc_OnViewerReady, // بر اساس نام پیدا شد
onCopy: ctlDoc_Copy, // بود ctlDoc_Copy(text)
onAutoLoadStatus: ctlDoc_AutoLoadStatus // بود ctlDoc_AutoLoadStatus(page)
});جستجوی قدیمی در یک catch خالی بستهبندی شده بود، بنابراین هیچچیزی گزارش نمیشد. در این نسخه توابع بهسادگی اجرا نمیشوند: علامت معمول یک چرخدندهٔ مشغول است که هرگز متوقف نمیشود، زیرا هندلری که آن را مخفی میکرد onViewerReady بود. سند پشت آن بهدرستی رندر میشود.
دو هوک ذخیرهٔ حاشیهنویسی هنوز بر اساس نام جستجو میشوند: SaveAnnotations()، هنگام وجود، <elementId>_BeforeAnnSave() و <elementId>_DeletedAnnotationIds() را فراخوانی میکند، با استفاده از شناسهٔ کامل عنصر (div_ctlDoc_BeforeAnnSave برای نمونهٔ بالا).
فراخوانی کلیک لینک وجود ندارد — مدیریت پیوندها بهصورت داخلی ساخته شده و توسط showHyperlinks هدایت میشود.
گروههای متدهای عمومی
| گروه | متدهای مشترک |
|---|---|
| دورهزندگی | 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 | 150 |
retryMaxTotalMs | 300000 |
آن را برای نمایشگر تکگرهای معمولی غیرفعال بگذارید. فعالسازی آن نمیتواند رندر همزمانی که پشتیبانی نمیشود را بهصورت ناهمزمان تبدیل کند.
آن را زمانی فعال کنید که صفحات از ذخیرهسازی مشترک با FirstPagePriority سرویس میشوند، جایی که صفحات بعدی بهطور مشروع تا زمان نوشتن پاسخ 202 Accepted میدهند. کلاینتی که تلاش مجدد نمیکند، کاشیهای خراب برای صفحاتی که هنوز در حال رندر هستند نشان میدهد — ببینید استقرارهای توزیعشده.
فهرست بررسی مسیر
DoconutOptions.MiddlewarePathباید شاخهای که واقعاً نقشه میکنید را توصیف کند.BasePathباید به آن شاخه هدف بگیرد، بهصورت نوشتهشده بدون پیشوند/('doconut'، نه'/doconut': نمایشگر اسلش را اضافه میکند، و//doconut/...یک درخواست به میزبان دیگر است). یک تنظیم رایج شکل درخواست تاریخیDocImage.axdرا بر روی شاخهMapWhenحفظ میکند و بنابراینBasePath: '/'را تنظیم میکند.DoconutOptions.ResourcesPathمسیر منبع توکار است.ResPathبهطور معمول زیرپوشهimagesخود را هدف میگیرد، بدون پیشوند/—'doconut-res/images'با پیشوند پیشفرض. یکResPathخالی در کتابخانه قبلی صحیح بود، جایی که منابع از ریشه برنامه میآمدند؛ اینجا صحیح نیست و بدون خطا شکست میخورد.ExtractHyperlinksباید در پیکربندی فرمت سرور فعال شود قبل از اینکهshowHyperlinksبتواند چیزی نمایش دهد.
آیا این صفحه مفید بود؟