查看器

主要文档查看器类

Viewer (namespace Doconut) 是用于从 Razor 页面、MVC 控制器、Blazor 组件或最小 API 打开文档的公共入口点。它是 sealed,由 AddDoconut() 注册为 transient 服务,并通过构造函数注入解析 —— 切勿直接实例化它。

之前的 .NET Standard 库公开了一个接受内存缓存、HTTP 上下文访问器以及一个或多个许可证路径的公共构造函数。该构造函数已被移除;服务图会提供这些依赖。

Viewer 不持有每请求的状态,并且有意 不 实现 IDisposable:文档会话独立存在于会话缓存中,因此释放服务永远不会拆除已打开的文档(参见 核心概念 → 查看器工作原理)。

OpenDocumentAsync

打开文档并返回客户端小部件用于所有后续请求的会话令牌。每次打开都是异步的 —— 没有同步的 OpenDocument。

重载使用场景
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)从磁盘打开并自动检测格式以及使用该格式的默认配置
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)需要每种格式的渲染选项(PdfConfig、WordConfig,…)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)文档不是磁盘上的文件(上传、数据库、Blob)。fileInfo 必须携带正确的扩展名 —— 它决定格式检测
csharp
// 简单打开
string token = await viewer.OpenDocumentAsync(path);

// 带有每种格式的配置和选项
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// 来自上传
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

需要处理的异常:

  • LicenseException — 找到的许可证被拒绝(消息包含拒绝原因),或者格式需要已不再授予的插件功能。日历过期且没有拒绝信息时,会降级为带水印的渲染,而不是抛异常。
  • FormatNotSupportedException — Document format '<extension>' is not supported.
  • InvalidDataException — 文件内容损坏或与其扩展名不匹配。

CloseDocument

text
void CloseDocument(string token)

从缓存中移除会话(立即释放文档引擎),删除安全标记,并撤销访问授权。可选 —— 滑动过期会执行相同的清理 —— 但对大文档仍建议使用此方法。

GetPageCount

text
int GetPageCount(string token)

打开会话的总页数。如果令牌未知或已过期,则抛出 InvalidOperationException(Document session not found. Please re-open document.),空令牌则抛出 ArgumentException。

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

文档在 100% 缩放下的默认渲染页面尺寸 —— 用于代码中构建注释的坐标空间。为兼容性接受 page;结果为文档默认尺寸。如果令牌未知或已过期,则抛出 InvalidOperationException(Document session not found. Please re-open document.),空令牌则抛出 ArgumentException。

获取工作表名称

text
IReadOnlyList<string> GetWorksheetNames(string token)

返回打开的电子表格的工作表名称,按工作簿顺序排列;如果打开的文档不是电子表格,则返回空列表。

仅列出已渲染的工作表:隐藏和空的工作表会被排除;当 ExcelConfig.SheetNames 限制渲染时,仅显示这些工作表。工作表不一定只占一页——非常大的工作表会跨越多页进行渲染。如果令牌未知或已过期,则抛出 InvalidOperationException (Document session not found. Please re-open document.);如果令牌为空,则抛出 ArgumentException。

已在 26.9.0 中添加。

能力标志

成员含义
bool IsSearchEnabled当前许可证授予 Search
bool IsAnnotationEnabled当前许可证授予 Annotation

在 Razor 视图中使用这些标志,仅在服务器实际提供时渲染受许可的功能区——参见 快速入门。

文档选项

每次打开的、与格式无关的选项(命名空间 Doconut):

类型属性默认值描述
stringPassword""受保护文档的密码(自动复制到格式配置中)。
intImageResolution0已废弃。 仅为兼容性保留——请改为在格式配置上设置 ImageResolution。
stringWatermark""在渲染页面上绘制的自定义水印文本。格式字符串:"^Text~Color~FontSize~FontName~Opacity~Angle",例如 "^Sample Copy~Red~24~Verdana~80~-45"。
intTimeOut60会话滑动过期时间(分钟)。
boolIsSecuredtrue当前未强制执行——保留。令牌绑定由 DoconutOptions.UnsafeMode 全局控制(参见核心概念 → 会话与安全)。

该类还公开了有意超出普通单主机查看流程的专用属性:

类型属性默认值描述
boolIsWebFarmfalse已废弃 — 无效。 使用 DistributedDocumentPublisher.PublishAsync(或 IDistributedPublishQueue.EnqueueAsync)发布文档,并改为设置 FileShareConfig.RootPath。注意大小写——之前的库将其拼写为 IsWebfarm。
stringWebFarmPath""已废弃 — 无效。 使用 FileShareConfig.RootPath,如在 分布式部署 中所述。之前拼写为 WebfarmPath。
boolEditModefalse为单独分发的编辑工作流保留;对标准查看器请保留 false。

自定义水印

DocOptions.Watermark 使用六个波浪号分隔的字段。可选的前置 ^ 请求全角布局:

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
字段示例含义
前置 ^^可选的全角布局。如果没有,则使用普通水印放置方式。
文本Confidential在每页上渲染的文字。不能为空。
颜色Red绘图层可识别的命名颜色。
字体大小24字体大小;无效的数值输入将回退到渲染器默认值。
字体名称Verdana请求的字体族。确保在部署环境中已安装。
不透明度800 到 255 的字节值。必须能够成功解析。
角度-45以度为单位的旋转角度;无效的数值输入将回退到默认值。

解析器在可选的 ^ 之后期望恰好六个字段。无效的定义会被 SDK 可见的 Invalid Watermark 回退替代,而不是静默消失。

许可证决定

许可证状态提供的自定义值渲染结果
有效的付费查看器许可证否干净页面
有效的付费查看器许可证是自定义水印
活跃的临时/演示基础查看器否干净的基础查看器页面
活跃的临时/演示基础查看器是当适用干净的基础查看器路径时的自定义水印
缺失、被拒绝、已过期、版本错误或域名无效的许可证任意强制/评估水印;自定义值不会覆盖它
插件在评估规则下渲染任意评估水印

相同的决定同样适用于提供的页面图像和注释导出。动画 GIF 输出会逐帧添加水印。因此,自定义水印是一项已授权的应用功能,而不是用于替代或抑制评估水印的手段。

注释 API

服务器端注释加载和导出。完整的操作指南位于 Guides → Annotations;以下为概览:

成员用途
AnnotationManager GetAnnotationManager(string token)绑定到打开会话页面尺寸的管理器
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)具有明确页面尺寸的管理器
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)会话无关的管理器
void LoadAnnotationData(string token, AnnotationManager manager)将用 C# 构建的注释加载到会话中
void LoadAnnotationData(string token, string annotationData)从 AnnotationManager.GetAnnotationData() 返回的编码页面/Base64 包中加载注释
void LoadAnnotationXML(string token, XmlDocument annotationXml)从 XML 加载注释
XmlDocument GetAnnotationXML(string token)将会话的注释导出为 XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)带有嵌入注释的 PDF
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)每页一个 PNG,嵌入注释,写入 directoryPath(如果不存在则创建);返回写入的图像数量
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)每页 PNG 带注释的 ZIP 包

这些方法均需要会话令牌。之前库的无会话 GetAnnotationManager(pageWidth, pageHeight) 形态仍可用于在会话外构建注释,但加载时仍需令牌。

DICOM 元数据

text
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

该方法仅用于 API 对齐,但此包无法提供技术性的 DICOM 标签:元数据读取器仅随 .NET 8 构建发布。它在 DICOM 和非 DICOM 会话中返回 null;在 DICOM 会话中还会写入一次性警告,说明平台限制。页面、帧和动画渲染仍受支持。

资源助手 — ReferenceCss / ReferenceScripts

为 UseDoconutResources() 提供的嵌入资源发出 <link>/<script> 标签,按正确的依赖顺序。搜索和注释等受许可证限制的功能的捆绑包 仅在许可证启用时 发出,保持客户端 UI 与服务器行为一致。

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + 查看器 + 搜索 + 注释
string ReferenceScripts(ScriptConfig? config = null)

CssConfig 标志: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

ScriptConfig 标志: IncludeJQuery (所有其他项所需), IncludeBootstrap, IncludeViewerScripts (核心: docViewer.js + splitter + links), IncludeSearchScripts 和 IncludeSearchBar (search-gated), IncludeAnnotationScripts 和 IncludeAnnotationBar (annotation-gated), EmitFeatureFlags (默认 true: 还会写入一个内联 window.Doconut.features = { search, annotation, editor } 脚本;在阻止内联脚本的 Content-Security-Policy 下将其设为 false)。

html
@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

这些助手是交付浏览器资源的受支持方式。已将 docViewer.js、documentLinks.js 和 docViewer.UI.js 复制到 wwwroot 的应用程序应在页面从发出的标签渲染后删除这些副本。

此页面对您有帮助吗?