查看器配置 – Doconut 文档

ViewerConfig（命名空间 Doconut）描述了浏览器查看器的外观和行为。它不影响文档渲染质量；如需控制渲染，请使用格式配置。C# 类和历史悠久的 JavaScript 小部件默认值不同，需显式映射各值。

C# 属性

类型	属性	默认	描述
`bool`	`ShowThumbs`	`true`	显示缩略图面板。
`bool`	`AutoLoad`	`false`	初始化后自动加载。普通的 token 流程会显式调用 `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`	`"/"`	主机映射 `UseDoconut()` 的分支路径。
`string`	`ResPath`	`"doconut-res"`	小部件使用的资源基路径。正常设置时指向 `<ResourcesPath>/images`。
`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",
    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`	推荐使用显式 token 流程。
`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	注释 UI 已关闭。

保持回调执行快速；异步发送遥测数据，避免阻塞页面渲染。

公共方法组

组	常用方法
生命周期	`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`	`60`
`retryMaxTotalMs`	`120000`

普通查看器请保持禁用。启用后也不能将不支持的同步渲染变为异步渲染。

路径检查清单

DoconutOptions.MiddlewarePath 必须描述实际映射的分支。
BasePath 必须指向该分支。
DoconutOptions.ResourcesPath 是嵌入资源的路由。
ResPath 通常指向其 /images 子文件夹。
必须在服务器的格式配置中启用 ExtractHyperlinks，showHyperlinks 才能显示任何内容。