ViewerConfig

Параметры клиентского виджета просмотрщика

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

Свойства 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Интерфейс аннотации закрыт.

Держите обратные вызовы быстрыми; отправляйте телеметрию асинхронно и не блокируйте рендеринг страницы.

Группы публичных методов

ГруппаОбщие методы
Жизненный цикл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 также содержит внутренние вспомогательные функции. Рассматривайте только методы, используемые референсным UI и задокументированные здесь или в руководствах по функциям, как стабильные точки интеграции.

Повторная попытка, пока распределённая страница всё ещё рендерится

retryOn409 сохраняет своё историческое название. Он предназначен для асинхронного создания страниц и повторно запрашивает текущий ответ готовности 202 Accepted, а также более старый сигнал 409 Conflict. При включении виджет опрашивает с этими JavaScript‑значениями по умолчанию:

ОпцияПо умолчанию
retryInitialDelayMs250
retryBackoffFactor1.6
retryMaxDelayMs2500
retryMaxAttempts150
retryMaxTotalMs300000

Оставьте его отключённым для обычного просмотрщика. Включение не может сделать неподдерживаемый синхронный рендер асинхронным.

Список проверок пути

  • DoconutOptions.MiddlewarePath должен описывать ветку, которую вы действительно сопоставляете.
  • BasePath должен указывать на эту ветку, записанную без начального / ('doconut', а не '/doconut': просмотрщик добавляет слеш, а //doconut/... — запрос к другому хосту).
  • DoconutOptions.ResourcesPath — это маршрут встроенного ресурса.
  • ResPath обычно указывает на его подпапку images, также без начального / ('doconut-res/images').
  • ExtractHyperlinks должен быть включён в конфигурации формата сервера, прежде чем showHyperlinks сможет что‑то отображать.

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