查看器

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

Viewer 不持有每请求的状态，并且有意 不 实现 IDisposable：文档会话独立存在于会话缓存中，销毁服务永远无法关闭已打开的文档（参见 Core Concepts → How the Viewer Works）。

OpenDocumentAsync（打开文档）

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

// 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（关闭文档）

void CloseDocument(string token)

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

GetPageCount（获取页数）

int GetPageCount(string token)

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

DocOptions（文档选项）

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

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

自定义水印

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

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

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

许可证决策

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

注释 API

服务器端注释加载与导出。完整教程位于 Guides → Annotations；接口如下：

DICOM 元数据

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

返回通过 DICOM 插件打开的会话的 DICOM 标记元数据；非 DICOM 文档返回 null。

资源助手 — ReferenceCss / ReferenceScripts

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

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（受注释许可证限制）。

@inject Doconut.Viewer Viewer

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