ViewerConfig – 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`	`"/"`	查看器发送页面请求的路径。`"/"` 是站点根目录下的 `DocImage.axd` 处理程序。对于位于虚拟目录的应用，请使用目录名称不带前导 `/`（`"myapp"` 表示 `/myapp/DocImage.axd`）。
`string`	`ResPath`	`"doconut-res/images"`	小部件加载自身图像的文件夹：`ResourcesPath` 下的 `images` 文件夹，不带前导 `/`。
`string`	`FitType`	`"width"`	`"width"`、`"height"` 或空字符串表示不自动适配。当前小部件不接受 `"page"`。
`bool`	`RetryOn409`	`false`	重试返回 “still rendering” 的页面请求。`DocImage.axd` 同步渲染，从不发送该信号；保持 `false`。

csharp

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "/",                 // "/" = the DocImage.axd handler at the site root (Web.config)
    ResPath = "doconut-res/images", // the images folder under ResourcesPath, no leading '/'
    ShowHyperlinks = true
};
// Emit it with viewer.RenderViewer("viewerEl", token, config) - see the Viewer reference.

使用 RenderViewer 发出 ViewerConfig

Viewer.RenderViewer(elementId, token, config) 将 ViewerConfig 转换为小部件的初始化脚本。它会写入上述六个属性——BasePath、ResPath、ShowThumbs、AutoLoad、PageZoom 和 FitType——随后调用 View(token)。其余属性不会写入：对于 MaxZoom、ShowHyperlinks、缩放设置或任何回调，请自行使用下面的 JavaScript 选项初始化小部件。参见查看器中的 RenderViewer。

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"`	传统默认值。若需显式设置，请使用 `'/'` 作为站点根目录的处理程序。
`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: '/',
    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 以及其退避设置（retryInitialDelayMs、retryBackoffFactor、retryMaxDelayMs、retryMaxAttempts、retryMaxTotalMs）。它们用于页面在后台生成的部署场景。DocImage.axd 在请求期间渲染每一页，因此请关闭 retryOn409。

路径检查清单

BasePath 在 DocImage.axd 处理程序位于站点根目录时为 '/' —— Web.config 中处理程序的 path 属性决定它响应的路径。在虚拟目录中，使用不带前导 / 的目录名（'myapp'，而不是 '/myapp'：查看器会自行添加斜杠，//myapp/... 会请求到另一个主机）。
DoconutOptions.ResourcesPath 是资源模块提供嵌入文件的路径（默认是 /doconut-res）。
ResPath 指向其 images 子文件夹，同样不带前导 /（'doconut-res/images'）。如果将其指向 'doconut-res'，则所有图标都会返回 404，而文档仍然可以渲染。
在 MVC 中，如果更改了 ResourcesPath，则必须在其后添加 routes.IgnoreRoute("doconut-res/{*pathInfo}")。
必须在服务器格式配置中启用 ExtractHyperlinks，showHyperlinks 才能显示任何内容。