ViewerConfig

Параметри віджета переглядача клієнта

ViewerConfig (namespace Doconut) описує вигляд та поведінку переглядача в браузері. Це не впливає на якість рендерингу документа; для цього використовуйте конфігурацію формату. Клас C# та давно існуючий JavaScript віджет мають різні значення за замовчуванням, тому явно зіставляйте значення.

Дві зміни на боці клієнта в цьому випуску не повідомляються про помилки.
Функції-обробники передаються як параметри — віджет більше не отримує свої зворотні виклики подій з ідентифікатора контейнера — і 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# у JavaScript

Не передавайте безпосередньо серіалізований ViewerConfig у docViewer(...). Більшість ключів віджета записані у camelCase, тоді як три встановлених ключі шляху/підгонки — у PascalCase.

C#JavaScript
ShowThumbsshowThumbs
AutoLoadautoLoad
AutoFocusautoFocus
AutoPageFocusautoPageFocus
PageZoompageZoom
ZoomStepzoomStep
MaxZoommaxZoom
ShowToolTipshowToolTip
ToolTipPageTexttoolTipPageText
CacheEnabledcacheEnabled
LargeDoclargeDoc
ShowHyperlinksshowHyperlinks
FixedZoomfixedZoom
FixedZoomPercentfixedZoomPercent
FixedZoomPercentMobilefixedZoomPercentMobile
BasePathBasePath
ResPathResPath
FitTypeFitType
RetryOn409retryOn409

Типові значення JavaScript

Віджет має старі типові значення, які відрізняються від класу C#. Наступні значення походять з поточної реалізації docViewer.js.

ПараметрТиповеПримітки
leftMinWidth / leftMaxWidth220 / 800Межі ширини панелі мініатюр.
showThumbstrueПочаткова видимість мініатюр.
autoFocus / autoPageFocustrue / falseautoPageFocus відрізняється від типового значення C#.
thumbWidth / thumbHeight / thumbPadding150 / 200 / 10Геометрія мініатюр у пікселях.
pageZoom / zoomStep / maxZoom100 / 10 / 200JavaScript maxZoom відрізняється від C# (300).
showToolTip / toolTipPageTexttrue / "Page "Підказка позиції сторінки.
format / doc / AccessToken"" / 0 / ""Внутрішні значення ініціалізації; зазвичай заповнюються View(token).
debugModefalseДодаткова діагностика клієнта.
FitType""Немає автоматичного підгонки, якщо не вказано.
BasePath"DocImage.axd"Історичне типове значення клієнта збережено для сумісності. Поточні хости ASP.NET Core повинні явно встановити його у відповідну гілку middleware.
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Інтерфейс анотацій закрито.

Тримайте зворотні виклики швидкими; надсилайте телеметрію асинхронно і не блокуйте рендеринг сторінки.

Кожен з них — це параметр у об’єкті ініціалізації. Попередній переглядач шукав глобальні функції, імена яких він отримував з ідентифікатора контейнера — сторінка з <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(), якщо вони існують, використовуючи повний id елемента (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 зможе щось відобразити.

Чи була ця сторінка корисною?