Viewer – Doconut 文档

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

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

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

// 简单打开
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)

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

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` 全局控制（参见 Core Concepts → Sessions & Security）。

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

类型	属性	默认值	描述
`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
    });

字段	示例	含义
前置 `^`	`^`	可选的全角布局。若未使用，则使用普通水印放置方式。
文本	`Confidential`	在每页渲染的文本。不能为空。
颜色	`Red`	绘图层可识别的命名颜色。
字体大小	`24`	字体大小；无效的数值输入将回退到渲染器默认值。
字体名称	`Verdana`	请求的字体族。确保已在部署环境中安装。
不透明度	`80`	0 到 255 的字节值。必须能够成功解析。
角度	`-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> 标签，按正确的依赖顺序。针对搜索和批注等受许可证限制的功能的捆绑包仅在许可证启用时才会发出 仅在许可证启用时，保持客户端 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 }))

获取工作表名称

text

IReadOnlyList<string> GetWorksheetNames(string token)

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

已在 26.9.0 中添加。