ViewerConfig – Doconut 文档

ViewerConfig（命名空间 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)	小部件加载其自身图像的文件夹：`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",           // 不带前导 '/'：查看器会自行添加（"/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	注释 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 文件也包含内部辅助函数。仅将本文档或功能指南中记录、参考 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 才能显示任何内容。