ViewerConfig – Doconut Документация

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

Свойства 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` также принимается для совместимости со старыми серверами. Не требуется для обычного синхронного просмотрщика.

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
`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`

Значения по умолчанию JavaScript

Виджет использует более старые значения по умолчанию, которые отличаются от класса 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`	JavaScript `maxZoom` отличается от C# (`300`).
`showToolTip` / `toolTipPageText`	`true` / `"Page "`	Всплывающая подсказка позиции страницы.
`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`	Требует извлечения на сервере для создания наложений.

Установите все важные для поведения значения явно, вместо того чтобы полагаться на любой набор значений по умолчанию:

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>

Обратные вызовы

Обратный вызов	Аргументы	Назначение
`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	Интерфейс аннотации закрыт.

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

Публичные группы методов

Группа	Общие методы
Жизненный цикл	`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 по умолчанию:

Опция	По умолчанию
`retryInitialDelayMs`	`250`
`retryBackoffFactor`	`1.6`
`retryMaxDelayMs`	`2500`
`retryMaxAttempts`	`60`
`retryMaxTotalMs`	`120000`

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

Чек‑лист пути

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