ViewerConfig

گزینه‌های ویجت نمایش‌گر سمت‌کاربر

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

دو تغییر سمت‌کلاینت در این نسخه به‌صورت ساکتانه شکست می‌خورند. توابع هندلر به‌عنوان گزینه‌ها پاس داده می‌شوند — ویجت دیگر فراخوانی‌های رویداد خود را از شناسهٔ کانتینر استخراج نمی‌کند — و ResPath باید به پیشوند منابع اشاره کند نه ریشهٔ برنامه. هر دو باعث می‌شوند سرور به‌درستی کار کند و هیچ‌چیزی در کنسول مرورگر گزارش نشود. اگر صفحه‌ای را از کتابخانهٔ قبلی منتقل می‌کنید، قبل از هر چیز، بازخوانی‌ها و فهرست مسیرها را بخوانید.

ویژگی‌های C#

نوعویژگیپیش‌فرضتوضیح
boolShowThumbstrueنمایش پنل تصویر بندانگشتی.
boolAutoLoadfalseبه‌صورت خودکار پس از مقداردهی اولیه بارگذاری می‌شود. جریان توکن معمولی صراحتاً View(token) را فراخوانی می‌کند.
boolAutoFocustrueدر طول مقداردهی اولیه، تمرکز/اسکرول مرورگر را به نمایشگر منتقل کنید.
boolAutoPageFocustrueدر حین تغییر صفحات، تصویر بندانگشتی جاری را قابل مشاهده نگه دارید.
intPageZoom100درصد زوم اولیه.
intZoomStep10درصدی که توسط دستورات زوم افزوده یا حذف می‌شود.
intMaxZoom300حداکثر درصد زوم.
boolShowToolTiptrueنمایش راهنمای موقعیت صفحه هنگام اسکرول.
stringToolTipPageText"Page "پیشوند مورد استفاده در راهنمای صفحه.
boolCacheEnabledfalseیک پنجره متحرک از تصاویر صفحه را در حافظه مرورگر نگه می‌دارد. از localStorage استفاده نمی‌کند.
boolLargeDocfalseعناصر صفحه را به‌صورت دسته‌های زمان‌بندی‌شده برای اسناد بزرگ اضافه می‌کند.
boolShowHyperlinksfalseپوشش‌های پیوندهای فرامتن را زمانی که پیکربندی سرور آن‌ها را استخراج کرده است، رندر می‌کند.
boolFixedZoomtrueبه‌جای محاسبهٔ واکنش‌گرا، از درصد زوم ثابت استفاده کنید.
intFixedZoomPercent100زوم ثابت دسکتاپ.
intFixedZoomPercentMobile75زوم ثابت موبایل.
stringBasePath"/"محل ارسال درخواست‌های صفحه توسط نمایشگر. "/" در ریشهٔ سایت DocImage.axd است؛ در غیر این صورت شاخه‌ای که میزبان UseDoconut() را نگاشت می‌کند، بدون پیشوند / ("doconut" به معنی /doconut/DocImage.axd است).
stringResPath"doconut-res/images" (26.9.0; "doconut-res" before)پوشه‌ای که ویجت تصاویر خود را از آن بارگذاری می‌کند: پوشهٔ images زیر ResourcesPath، بدون پیشوند /.
stringFitType"width""width"، "height"، یا خالی برای عدم تناسب خودکار. "page" توسط ویجت فعلی پذیرفته نمی‌شود.
boolRetryOn409falseدر زمان پاسخ تولید صفحهٔ ناهمزمان/پراکندگی، اگر 202 Accepted پاسخ دهد، نظرسنجی فعال شود؛ 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#جاوااسکریپت
ShowThumbsshowThumbs
AutoLoadautoLoad
AutoFocusautoFocus
AutoPageFocusautoPageFocus
PageZoompageZoom
ZoomStepzoomStep
MaxZoommaxZoom
ShowToolTipshowToolTip
ToolTipPageTexttoolTipPageText
CacheEnabledcacheEnabled
LargeDoclargeDoc
ShowHyperlinksshowHyperlinks
FixedZoomfixedZoom
FixedZoomPercentfixedZoomPercent
FixedZoomPercentMobilefixedZoomPercentMobile
BasePathBasePath
ResPathResPath
FitTypeFitType
RetryOn409retryOn409

پیش‌فرض‌های جاوااسکریپت

ابزارک دارای پیش‌فرض‌های قدیمی‌تری است که با کلاس C# متفاوت هستند. مقادیر زیر از پیاده‌سازی فعلی docViewer.js آمده‌اند.

گزینهپیش‌فرضیادداشت‌ها
leftMinWidth / leftMaxWidth220 / 800حدود عرض پنل تصویر بندانگشتی.
showThumbstrueقابلیت مشاهده اولیه تصویر بندانگشتی.
autoFocus / autoPageFocustrue / falseautoPageFocus متفاوت از پیش‌فرض C# است.
thumbWidth / thumbHeight / thumbPadding150 / 200 / 10ژئومتری تصویر بندانگشتی بر حسب پیکسل.
pageZoom / zoomStep / maxZoom100 / 10 / 200جاوااسکریپت maxZoom متفاوت از C# است (300).
showToolTip / toolTipPageTexttrue / "Page "راهنما (tooltip) موقعیت صفحه.
format / doc / AccessToken"" / 0 / ""مقادیر داخلی مقداردهی اولیه؛ معمولاً توسط View(token) پر می‌شوند.
debugModefalseتشخیص‌های اضافی سمت کاربر.
FitType""بدون تنظیم خودکار مگر اینکه فراهم شود.
BasePath"DocImage.axd"پیش‌فرض تاریخی سمت کاربر برای سازگاری حفظ شده است. میزبان‌های فعلی ASP.NET Core باید آن را به‌صورت صریح به شاخه میدل‌ورک نگاشته تنظیم کنند.
ResPath""به‌صورت صریح به مسیر تصاویر جاسازی‌شده تنظیم شود.
cacheEnabled / cacheCount / cacheDelayfalse / 3 / 3پنجره پیش‌بارگذاری صفحه در حافظه و تأخیر.
autoLoadfalseجریان توکن صریح توصیه می‌شود.
largeDoctrueمتفاوت با پیش‌فرض C# است.
fixedZoomfalseمتفاوت با پیش‌فرض C# است.
fixedZoomPercent / fixedZoomPercentMobile100 / 50مقدار موبایل متفاوت از C# است (75).
showHyperlinkstrueنیاز به استخراج سمت سرور برای تولید لایه‌های پوششی دارد.

تمام مقادیر مهم رفتاری را تنظیم کنید به‌جای تکیه بر هر یک از مجموعه پیش‌فرض‌ها:

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>

فراخوانی‌ها

فراخوانیآرگومان‌هاهدف
onPageLoadingpageNumدرخواست صفحه در حال شروع است.
onPageLoadedpageNumبارگذاری تصویر صفحه تکمیل شد.
onThumbnailClickedpageNumکاربر یک تصویر بندانگشتی را انتخاب کرد.
onPageClickedpageNumکاربر یک صفحه را انتخاب کرد.
onDoubleClicknoneنمایشگر یک دوبار کلیک دریافت کرد.
onViewerBusynoneنمایشگر به وضعیت مشغول رفت.
onViewerReadynoneمقداردهی اولیه تکمیل شد.
onViewerErrornoneنمایشگر به وضعیت خطا رفت.
onErrormessageیک عملیات پیام خطا برگرداند.
onCopydataداده‌های کپی متن در دسترس هستند.
onAutoLoadStatuspageNumبارگذاری خودکار به صفحه‌ای پیشرفت کرد.
onThumbsShownnoneپنل تصویر بندانگشتی قابل مشاهده شد.
onAnnLoadednoneداده‌های حاشیه‌نویسی بارگذاری شد.
onAnnSavednoneداده‌های حاشیه‌نویسی ذخیره شد.
onAnnSaveErrornoneذخیره حاشیه‌نویسی ناموفق بود.
onAnnClosednoneرابط کاربری حاشیه‌نویسی بسته شد.

فراخوانی‌ها را سریع نگه دارید؛ تله‌متری را به‌صورت ناهمزمان ارسال کنید و از مسدود کردن رندر صفحه خودداری کنید.

هر یک از این‌ها یک گزینه در شیء init است. نمایشگر قبلی توابع سراسری را که نام‌هایشان را از شناسهٔ container استخراج می‌کرد جستجو می‌کرد — صفحه‌ای که فقط <div id="div_ctlDoc"> داشت باید function ctlDoc_OnViewerReady() را اعلام می‌کرد. آن جستجو حذف شد. تابع را به‌صورت صریح پاس دهید:

javascript
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 نظرسنجی می‌کند:

گزینهپیش‌فرض
retryInitialDelayMs250
retryBackoffFactor1.6
retryMaxDelayMs2500
retryMaxAttempts150
retryMaxTotalMs300000

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

آن را زمانی فعال کنید که صفحات از ذخیره‌سازی مشترک با FirstPagePriority سرویس می‌شوند، جایی که صفحات بعدی به‌طور مشروع تا زمان نوشتن پاسخ 202 Accepted می‌دهند. کلاینتی که تلاش مجدد نمی‌کند، کاشی‌های خراب برای صفحاتی که هنوز در حال رندر هستند نشان می‌دهد — ببینید استقرارهای توزیع‌شده.

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

  • DoconutOptions.MiddlewarePath باید شاخه‌ای که واقعاً نقشه می‌کنید را توصیف کند.
  • BasePath باید به آن شاخه هدف بگیرد، به‌صورت نوشته‌شده بدون پیشوند / ('doconut'، نه '/doconut': نمایشگر اسلش را اضافه می‌کند، و //doconut/... یک درخواست به میزبان دیگر است). یک تنظیم رایج شکل درخواست تاریخی DocImage.axd را بر روی شاخه MapWhen حفظ می‌کند و بنابراین BasePath: '/' را تنظیم می‌کند.
  • DoconutOptions.ResourcesPath مسیر منبع توکار است.
  • ResPath به‌طور معمول زیرپوشه images خود را هدف می‌گیرد، بدون پیشوند / — 'doconut-res/images' با پیشوند پیش‌فرض. یک ResPath خالی در کتابخانه قبلی صحیح بود، جایی که منابع از ریشه برنامه می‌آمدند؛ اینجا صحیح نیست و بدون خطا شکست می‌خورد.
  • ExtractHyperlinks باید در پیکربندی فرمت سرور فعال شود قبل از اینکه showHyperlinks بتواند چیزی نمایش دهد.

آیا این صفحه مفید بود؟