ViewerConfig – Doconut 文档

ViewerConfig（命名空间 Doconut）描述了浏览器查看器的外观和行为。它不影响文档渲染质量；如需控制渲染，请使用 format 配置。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`	当异步/分布式页面请求返回 `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 映射

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 默认值

选项	默认值	备注
`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	注释界面已关闭。

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

公共方法组

组别	常用方法
生命周期	`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 使用并在此或功能指南中记录的方法视为稳定的集成点。

HTTP 409 后的重试

retryOn409 用于异步页面生成。启用后，小部件会使用以下 JavaScript 默认值进行轮询：

选项	默认值
`retryInitialDelayMs`	`250`
`retryBackoffFactor`	`1.6`
`retryMaxDelayMs`	`2500`
`retryMaxAttempts`	`60`
`retryMaxTotalMs`	`120000`

在普通查看器中保持禁用。启用它并不能将不支持的同步渲染转为异步。

路径检查清单

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