查看器
主要文档查看器类
Viewer (namespace 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 必须携带正确的扩展名——它决定格式检测 |
// 简单打开
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
void CloseDocument(string token)从缓存中移除会话(立即释放文档引擎),删除安全标记,并撤销访问授权。可选——滑动过期会执行相同的清理——但对大文档仍建议使用。
GetPageCount
int GetPageCount(string token)打开会话的总页数。如果令牌未知或已过期,则抛出 InvalidOperationException(Document session not found. Please re-open document.),空令牌则抛出 ArgumentException。
GetPageDimensions
(int Width, int Height) GetPageDimensions(string token, int page = 1)文档在 100% 缩放下的默认渲染页面尺寸——用于代码中构建注释的坐标空间。为兼容性接受 page;结果为文档默认尺寸。如果令牌未知或已过期,则抛出 InvalidOperationException(Document session not found. Please re-open document.),空令牌则抛出 ArgumentException。
GetWorksheetNames
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):
| 类型 | 属性 | 默认值 | 描述 |
|---|---|---|---|
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 | 已废弃 — 无效。 使用 DistributedDocumentPublisher.PublishAsync(或 IDistributedPublishQueue.EnqueueAsync)发布文档,并改为设置 FileShareConfig.RootPath。 |
string | WebFarmPath | "" | 已废弃 — 无效。 请改用 FileShareConfig.RootPath。 |
bool | EditMode | false | 保留用于单独分发的编辑器工作流;请为标准查看器保留 false。 |
自定义水印
DocOptions.Watermark 使用六个波浪号分隔的字段。可选的前导 ^ 请求全角布局:
^Text~Color~FontSize~FontName~Opacity~Anglestring 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(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 包 |
DICOM 元数据
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)此方法用于 API 对齐,但 .NET 6 DICOM 查看器无法提供技术标签。它为 DICOM 和非 DICOM 会话返回 null;在 DICOM 会话中,它还会写入一次性警告,解释平台限制。页面、帧和动画渲染仍受支持。
资源助手 — 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 (受注释限制), EmitFeatureFlags (默认 true: 还会写入内联 window.Doconut.features = { search, annotation, editor } 脚本;在阻止内联脚本的 Content-Security-Policy 下将其设为 false)。
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))此页面对您有帮助吗?