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(), если они существуют, используя полный идентификатор элемента (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 сможет что‑то отобразить.

Была ли эта страница полезной?