ViewerConfig

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

此版本中的两个客户端更改会静默失败。 处理函数作为选项传递——小部件不再从容器 id 派生全局函数名——且 ResPath 必须指向资源前缀而不是应用根目录。这两点都不会影响服务器的正常工作，也不会在浏览器控制台中报告任何信息。如果您从之前的库迁移页面，请先阅读回调函数和路径检查清单。

C# 属性

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。

JavaScript 默认值

该小部件拥有与 C# 类不同的旧默认值。以下数值来源于当前的 docViewer.js 实现。

请设置所有行为关键的值，而不是依赖任一套默认值：

<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>

回调函数

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

这些都是初始化对象上的选项。 之前的查看器会根据容器 id 推导全局函数名——例如 <div id="div_ctlDoc"> 只需声明 function ctlDoc_OnViewerReady()。这种查找方式已被移除。请显式传入函数：

objctlDoc = $('#div_ctlDoc').docViewer({
    // ... 你的其他选项 ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // 以前是通过名称查找
    onViewerReady:    ctlDoc_OnViewerReady,     // 以前是通过名称查找
    onCopy:           ctlDoc_Copy,              // 以前是 ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // 以前是 ctlDoc_AutoLoadStatus(page)
});

旧的查找被包装在一个空的 catch 中，导致任何错误都未被报告。在此版本中，这些函数根本不会被调用：常见症状是忙碌指示器一直旋转不止，因为隐藏指示器的处理函数是 onViewerReady。文档本身已经正确渲染。

没有链接点击回调——超链接处理已内置并由 showHyperlinks 驱动。

公共方法组

JavaScript 文件还包含内部帮助函数。仅将本文档或功能指南中列出的、供参考 UI 使用的方法视为稳定的集成点。

在分布式页面仍在渲染时重试

retryOn409 保留其历史名称。它用于异步页面生成，并在 202 Accepted 就绪响应以及较早的 409 Conflict 信号时进行重试。启用后，组件会使用以下 JavaScript 默认值进行轮询：

在普通单节点查看器下请保持禁用。启用它不会使不受支持的同步渲染变为异步。

当页面从带有 FirstPagePriority 的共享存储提供时，请启用此功能，因为后续页面在写入之前会合法返回 202 Accepted。如果客户端不进行重试，仍在渲染的页面会出现破碎的瓦片——参见分布式部署。

路径检查清单

• DoconutOptions.MiddlewarePath 必须描述您实际映射的分支。
• BasePath 必须指向该分支，且不要以 / 开头（例如 'doconut' 而不是 '/doconut'：查看器会自行添加斜杠，//doconut/... 会被视为对其他主机的请求）。参考应用在 MapWhen 分支上保持了历史的 DocImage.axd 请求形态，因此将 BasePath 设置为 '/'。
• DoconutOptions.ResourcesPath 是嵌入式资源路由。
• ResPath 通常指向其 images 子文件夹，且不要以 / 开头——例如使用默认前缀时为 'doconut-res/images'。在之前的库中，空的 ResPath 是正确的，因为资源来自应用根目录；在此处则不正确，会在没有错误提示的情况下失败。
• 必须在服务器格式配置中启用 ExtractHyperlinks，随后 showHyperlinks 才能显示任何内容。