查看器 – Doconut 文档

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

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

Viewer 不持有每请求的状态，并且有意不实现 IDisposable：文档会话独立存放在会话缓存中，因此释放服务永远不会拆除已打开的文档（参见 Core Concepts → How the Viewer Works）。

OpenDocumentAsync

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

Overload	Use when
`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));

Exceptions to handle:

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

CloseDocument

text

void CloseDocument(string token)

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

GetPageCount

text

int GetPageCount(string token)

打开会话的总页数。如果令牌未知或已过期则抛出异常。

GetWorksheetNames

text

IReadOnlyList<string> GetWorksheetNames(string token)

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

仅列出已渲染的工作表：隐藏和空的工作表被排除；当 ExcelConfig.SheetNames 限制渲染时，仅显示这些工作表。工作表并不总是一页——非常大的工作表会跨多页渲染。如果令牌未知或已过期则抛出异常。

添加于 26.9.0。

功能标志

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

在 Razor 视图中使用这些，以仅在服务器实际提供时渲染已授权的功能区 — 请参阅快速入门。

DocOptions

每次打开时的、与格式无关的选项（命名空间 Doconut）：

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

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

类型	属性	默认	描述
`bool`	`IsWebFarm`	`false`	标记打开操作为共享存储场景。注意大小写——之前的库将其拼写为 `IsWebfarm`。
`string`	`WebFarmPath`	`""`	该工作流使用的共享路径。之前拼写为 `WebfarmPath`。在普通单主机查看器中为空，在分布式部署中描述的发布路径也不需要。
`bool`	`EditMode`	`false`	为单独分发的编辑工作流保留；请为标准查看器保留 `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`	请求的字体族。确保已在部署环境中安装。
不透明度	`80`	0 到 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(…)`	包含嵌入注释的 PNG 文件
`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（受搜索限制），IncludeAnnotationCss（受注释限制）。

ScriptConfig 标志: IncludeJQuery（所有其他标志所需），IncludeBootstrap, IncludeViewerScripts（核心：docViewer.js + splitter + links），IncludeSearchScripts 和 IncludeSearchBar（受搜索限制），IncludeAnnotationScripts 和 IncludeAnnotationBar（受注释限制）。

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 的应用程序应在页面从发出的标签渲染后删除这些副本。