ViewerConfig

客户端查看器小部件选项

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

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

C# 属性

类型属性默认值描述
boolShowThumbstrue显示缩略图面板。
boolAutoLoadfalse初始化后自动加载。正常的令牌流会显式调用 View(token)。
boolAutoFocustrue在初始化期间将浏览器焦点/滚动移动到查看器。
boolAutoPageFocustrue页面切换时保持当前缩略图可见。
intPageZoom100初始缩放百分比。
intZoomStep10缩放命令添加或移除的百分比。
intMaxZoom300最大缩放百分比。
boolShowToolTiptrue滚动时显示页面位置工具提示。
stringToolTipPageText"Page "页面工具提示中使用的前缀。
boolCacheEnabledfalse在浏览器内存中保留页面图像的移动窗口。它不使用 localStorage。
boolLargeDocfalse为大型文档以定时批次追加页面元素。
boolShowHyperlinksfalse当服务器配置提取超链接时渲染覆盖层。
boolFixedZoomtrue使用固定的缩放百分比,而不是响应式重新计算。
intFixedZoomPercent100固定的桌面缩放。
intFixedZoomPercentMobile75固定的移动端缩放。
stringBasePath"/"查看器发送页面请求的位置。"/" 在站点根目录为 DocImage.axd;否则为主机映射 UseDoconut() 的分支,不带前导 /("doconut" 表示 /doconut/DocImage.axd)。
stringResPath"doconut-res/images" (26.9.0; "doconut-res" before)小部件加载其自身图像的文件夹:ResourcesPath 下的 images 文件夹,不带前导 /。
stringFitType"width""width"、"height" 或留空表示不自动适配。当前小部件不接受 "page"。
boolRetryOn409false当异步/分布式页面生成响应 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
ShowThumbsshowThumbs
AutoLoadautoLoad
AutoFocusautoFocus
AutoPageFocusautoPageFocus
PageZoompageZoom
ZoomStepzoomStep
MaxZoommaxZoom
ShowToolTipshowToolTip
ToolTipPageTexttoolTipPageText
CacheEnabledcacheEnabled
LargeDoclargeDoc
ShowHyperlinksshowHyperlinks
FixedZoomfixedZoom
FixedZoomPercentfixedZoomPercent
FixedZoomPercentMobilefixedZoomPercentMobile
BasePathBasePath
ResPathResPath
FitTypeFitType
RetryOn409retryOn409

JavaScript 默认

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

选项默认备注
leftMinWidth / leftMaxWidth220 / 800缩略图面板宽度范围。
showThumbstrue初始缩略图可见性。
autoFocus / autoPageFocustrue / falseautoPageFocus 与 C# 默认值不同。
thumbWidth / thumbHeight / thumbPadding150 / 200 / 10像素单位的缩略图几何尺寸。
pageZoom / zoomStep / maxZoom100 / 10 / 200JavaScript maxZoom 与 C# (300) 不同。
showToolTip / toolTipPageTexttrue / "Page "页面位置工具提示。
format / doc / AccessToken"" / 0 / ""内部初始化值;通常由 View(token) 填充。
debugModefalse额外的客户端诊断信息。
FitType""除非提供,否则不自动适配。
BasePath"DocImage.axd"保留历史客户端默认值以兼容。当前 ASP.NET Core 主机必须显式设置为映射的中间件分支。
ResPath""显式设置为嵌入图像路径。
cacheEnabled / cacheCount / cacheDelayfalse / 3 / 3内存中的页面预加载窗口和延迟。
autoLoadfalse建议使用显式令牌流。
largeDoctrue与 C# 默认值不同。
fixedZoomfalse与 C# 默认值不同。
fixedZoomPercent / fixedZoomPercentMobile100 / 50移动端值与 C# (75) 不同。
showHyperlinkstrue需要服务器端提取以生成覆盖层。

请设置所有行为重要的值,而不是依赖任一默认设置:

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>

回调

回调参数目的
onPageLoadingpageNum页面请求正在开始。
onPageLoadedpageNum页面图像加载完成。
onThumbnailClickedpageNum用户选择了缩略图。
onPageClickedpageNum用户选择了页面。
onDoubleClicknone查看器收到双击。
onViewerBusynone查看器进入忙碌状态。
onViewerReadynone初始化完成。
onViewerErrornone查看器进入错误状态。
onErrormessage操作返回错误信息。
onCopydata可获取文本复制数据。
onAutoLoadStatuspageNum自动加载已进展到页面。
onThumbsShownnone缩略图面板变为可见。
onAnnLoadednone注释数据已加载。
onAnnSavednone注释数据已保存。
onAnnSaveErrornone注释保存失败。
onAnnClosednone注释 UI 已关闭。

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

这些都是 init 对象上的选项。 旧的查看器会查找全局函数,其名称来源于容器 id —— 一个包含 <div id="div_ctlDoc"> 的页面只需声明 function ctlDoc_OnViewerReady()。此查找已不存在。请显式传递函数:

javascript
function ctlDoc_OnViewerBusy() { /* 显示忙碌指示器 */ }
function ctlDoc_OnViewerReady() { /* 隐藏它 */ }
function ctlDoc_Copy(text) { /* 使用复制的文本 */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* 报告进度 */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... 您现有的选项 ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // 已通过名称找到
    onViewerReady:    ctlDoc_OnViewerReady,     // 已通过名称找到
    onCopy:           ctlDoc_Copy,              // 是 ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // 是 ctlDoc_AutoLoadStatus(page)
});

旧的查找被包装在一个空的 catch 中,因此从未报告任何内容。此发布中,这些函数根本不会运行:常见的症状是忙碌指示器一直旋转不停止,因为隐藏它的处理程序是 onViewerReady。其背后的文档能够正确渲染。

仍然会按名称查找两个注释保存钩子:SaveAnnotations() 在存在时调用 <elementId>_BeforeAnnSave() 和 <elementId>_DeletedAnnotationIds(),并使用元素的完整 id(示例中的 div_ctlDoc_BeforeAnnSave)。

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

公共方法组

组常用方法
生命周期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 默认值进行轮询:

选项默认
retryInitialDelayMs250
retryBackoffFactor1.6
retryMaxDelayMs2500
retryMaxAttempts150
retryMaxTotalMs300000

对于普通的单节点查看器,请保持禁用状态。启用它并不能将不受支持的同步渲染转为异步。

当页面通过带有 FirstPagePriority 的共享存储提供时,请启用它,此时后续页面会合法地返回 202 Accepted 直至写入。未进行重试的客户端会在页面仍在渲染时显示损坏的瓦片 — 参见 Distributed Deployments。

路径检查清单

  • DoconutOptions.MiddlewarePath 必须描述您实际映射的分支。
  • BasePath 必须指向该分支,且写入时不带前导 /('doconut',而不是 '/doconut':查看器会添加斜杠,//doconut/... 是对另一个主机的请求)。常见的配置在 MapWhen 分支上保持历史的 DocImage.axd 请求形态,因此会设置 BasePath: '/'。
  • DoconutOptions.ResourcesPath 是嵌入式资源路径。
  • ResPath 通常指向其 images 子文件夹,不带前导 / — 使用默认前缀时为 'doconut-res/images'。在之前的库中,空的 ResPath 是正确的,因为资源来自应用根目录;但在此处不正确,并且会在没有错误提示的情况下失败。
  • ExtractHyperlinks 必须在服务器格式配置中启用,才能让 showHyperlinks 显示任何内容。

此页面对您有帮助吗?