ViewerConfig
Опции клиентского виджета просмотра
ViewerConfig (namespace Doconut) описывает внешний вид и поведение браузерного просмотрщика. Он не влияет на качество отрисовки документа; для этого используйте конфигурацию формата. Класс C# и давно существующий JavaScript‑виджет имеют разные значения по умолчанию, поэтому сопоставляйте значения явно.
Два изменения на клиенте в этом выпуске завершаются без ошибок. Функции‑обработчики передаются как параметры — виджет больше не получает свои обратные вызовы событий из идентификатора контейнера — и
ResPathдолжен указывать префикс ресурсов, а не корень приложения. Оба оставляют сервер полностью работоспособным и ничего не выводят в консоль браузера. Если вы переносите страницу из предыдущей библиотеки, ознакомьтесь с Обратными вызовами и Контрольным списком путей прежде чем что‑либо ещё.
Свойства 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 для совместимости со старыми серверами. Не требуется обычному синхронному просмотрщику. |
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 должны явно установить его в соответствующую ветку middleware. |
ResPath | "" | Установить явно путь к встроенным изображениям. |
cacheEnabled / cacheCount / cacheDelay | false / 3 / 3 | Окно и задержка предзагрузки страниц в памяти. |
autoLoad | false | Рекомендуется явный поток токенов. |
largeDoc | true | Отличается от значения по умолчанию в C#. |
fixedZoom | false | Отличается от значения по умолчанию в C#. |
fixedZoomPercent / fixedZoomPercentMobile | 100 / 50 | Мобильное значение отличается от C# (75). |
showHyperlinks | true | Требует серверного извлечения для создания наложений. |
Установите все важные для поведения значения вместо того, чтобы полагаться на любой набор значений по умолчанию:
<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 | Интерфейс аннотации закрыт. |
Сделайте обратные вызовы быстрыми; отправляйте телеметрию асинхронно и не блокируйте рендеринг страницы.
Каждый из них является параметром в объекте инициализации. Предыдущий просмотрщик искал глобальные функции, имена которых он формировал из идентификатора контейнера — страница с <div id="div_ctlDoc"> должна была объявить только function ctlDoc_OnViewerReady(). Этот поиск исчез. Передайте функцию явно:
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:
| Опция | По умолчанию |
|---|---|
retryInitialDelayMs | 250 |
retryBackoffFactor | 1.6 |
retryMaxDelayMs | 2500 |
retryMaxAttempts | 150 |
retryMaxTotalMs | 300000 |
Оставьте его отключённым для обычного однопользовательского просмотрщика. Включение не может сделать неподдерживаемый синхронный рендер асинхронным.
Включите его, когда страницы обслуживаются из общего хранилища с FirstPagePriority, где более поздние страницы законно отвечают 202 Accepted, пока не будут записаны. Клиент, который не делает повторов, показывает повреждённые плитки для страниц, которые всё ещё рендерятся — см. Распределённые развертывания.
Список проверок пути
DoconutOptions.MiddlewarePathдолжен описывать ветку, которую вы действительно отображаете.BasePathдолжен указывать на эту ветку, записанную без начального/('doconut', а не'/doconut': просмотрщик добавляет слеш, а//doconut/...— запрос к другому хосту). Обычная конфигурация сохраняет историческую форму запросаDocImage.axdна веткеMapWhenи поэтому устанавливаетBasePath: '/'.DoconutOptions.ResourcesPath— это маршрут встроенного ресурса.ResPathобычно указывает на его подпапкуimages, без начального/—'doconut-res/images'с префиксом по умолчанию. ПустойResPathбыл корректен в предыдущей библиотеке, где ресурсы брались из корня приложения; здесь это некорректно, и приводит к сбою без сообщения об ошибке.ExtractHyperlinksдолжен быть включён в конфигурации формата сервера, прежде чемshowHyperlinksсможет что‑то отобразить.
Была ли эта страница полезной?