查看器配置

ViewerConfig (namespace 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>

回调

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

这些都是 init 对象上的选项。 之前的查看器会查找全局函数，其名称来源于容器 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 显示任何内容。