查看器 – Doconut 文档

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

Viewer 不持有每请求的状态，并且有意不实现 IDisposable：文档会话独立存放在会话缓存中，因此释放服务永远无法关闭已打开的文档（参见 核心概念 → 查看器工作原理）。

OpenDocumentAsync（打开文档）

打开文档并返回客户端小部件用于后续所有请求的会话令牌。

重载	使用场景
`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

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
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)

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

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`	将打开操作标记为 Web 农场场景。仅在对应的共享存储/会话架构下使用。
`string`	`WebFarmPath`	`""`	专用 Web 农场工作流使用的共享路径。普通单机查看器中为空。
`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
    });

字段	示例	含义
前导 `^`	`^`	可选的全角布局。若省略，则使用普通水印位置。
Text	`Confidential`	每页渲染的文字。不能为空。
Color	`Red`	绘图层能够识别的颜色名称。
FontSize	`24`	字体大小；数值无效时回退到渲染器默认值。
FontName	`Verdana`	请求的字体族。请确保在部署环境中已安装。
Opacity	`80`	0~255 之间的字节值，必须能够成功解析。
Angle	`-45`	以度为单位的旋转角度；数值无效时回退到默认值。

解析器要求在可选 ^ 之后恰好有六个字段。若定义无效，SDK 会使用可见的 Invalid Watermark 作为回退，而不是静默消失。

许可证决策

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

相同的决策同样适用于返回的页面图像和注释导出。动画 GIF 输出会逐帧加盖水印。自定义水印因此是受许可证约束的功能，而非替代或抑制评估水印的手段。

注释 API

服务器端注释加载与导出。完整教程位于 指南 → 注释；对外表面如下：

成员	用途
`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 包，注释已烧录

DICOM 元数据

text

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

该方法仅为 API 对齐而存在，但 .NET 6 DICOM 查看器无法提供技术标签。对 DICOM 与非 DICOM 会话均返回 null；在 DICOM 会话中还会一次性写入警告，说明平台限制。页面、帧以及动画渲染仍受支持。

资源帮助程序 — ReferenceCss / ReferenceScripts

为 UseDoconutResources() 提供的嵌入资源生成 <link>/<script> 标签，按正确的依赖顺序输出。搜索、注释等受许可证控制的功能仅在许可证启用时才会输出对应的 bundle，保持客户端 UI 与服务器行为一致。

text

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
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 }))