查看器

主要文档查看器类

Viewer (namespace Doconut) 是用于从 MVC 控制器、Web Forms 页面和处理程序打开文档的公共入口点。它是由 DoconutHost.Initialize 组合的 瞬态 服务;在使用的地方解析它:

csharp
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() 也在 DoconutHost.Initialize 运行后工作 —— 它解析相同的服务 —— 这使得从经典包迁移的代码仍能编译。在 Initialize 之前,它会抛出 InvalidOperationException。

Viewer 不持有每请求的文档状态,并且有意 不 实现 IDisposable:文档会话独立于它存在,因此释放 Viewer 永远不会关闭已打开的文档(参见 查看器工作原理)。

OpenDocumentAsync(异步)

打开文档并返回小部件在后续每个请求中使用的会话令牌。当 UnsafeMode 为 false(默认)时,令牌会授予当前请求的 ASP.NET 会话 —— 请在具有会话状态的请求中调用它(参见 会话与安全)。

重载使用场景
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 });

// 来自上传 (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

需要处理的异常:

  • LicenseException — 找到许可证但被拒绝(消息包含原因),或者该格式需要许可证未授予的插件功能。
  • FormatNotSupportedException — 没有查看器能够处理该文件的扩展名。
  • InvalidDataException — 内容损坏或与其扩展名不匹配。

OpenDocument(同步)

用于 Web Forms 代码隐藏以及其他不使用异步页面的代码:

text
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

每个方法都会返回令牌并将其存储在 viewer.Token 中。fileName 必须携带正确的扩展名。这些包装器可以安全地从 Web Forms 页面调用:打开路径永远不会在 ASP.NET 请求上下文中恢复,因此等待它不会导致死锁。并非所有异步 Doconut API 都是 不 的——请参见 转换器插件 的 Web Forms 部分。

关闭文档

text
void CloseDocument(string token)

移除会话(立即释放文档引擎),从当前请求的 ASP.NET 会话中移除令牌的授权,并撤销该令牌。可选——滑动过期执行相同的清理——但建议在处理大文档时使用。

会话查询

成员返回值
int GetPageCount(string token)打开文档的总页数
(int Width, int Height) GetPageDimensions(string token, int page = 1)默认在 100% 缩放下渲染的页面大小——用于代码中构建注释的坐标空间
IReadOnlyList<string> GetWorksheetNames(string token)电子表格的渲染工作表,按工作簿顺序排列;其他文档为空

如果令牌未知或已过期,则抛出 InvalidOperationException(Document session not found. Please re-open document.);如果令牌为空,则抛出 ArgumentException。

文档选项

每次打开时的、与格式无关的选项(命名空间 Doconut):

类型属性默认值描述
stringPassword""受保护文档的密码(自动复制到格式配置中)。
stringWatermark""在渲染页面上绘制的自定义水印文本——见下文。
intTimeOut60会话滑动过期时间,单位为分钟。
stringBrowserId""Web 农场:签名票据绑定的浏览器。使用 DoconutFarmBinding.EnsureBrowserId 设置(参见 Sessions & Security)。
stringUserId""Web 农场:票据绑定的已登录用户,来源于 DoconutFarmBinding.ResolveUserId。
intImageResolution0已废弃。 请改为在格式配置上设置 ImageResolution。
boolIsSecuredtrue保留;不强制执行。访问控制为 DoconutOptions.UnsafeMode。
boolIsWebFarm / string WebFarmPathfalse / ""保留用于从经典包迁移的代码。它们不会打开农场模式——AddDoconutDistributed 会。
boolEditModefalse为单独分发的编辑器保留;请保留 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
    });
字段示例含义
Leading ^^可选的全角布局。如果不使用,则使用默认放置方式。
文本Confidential在每页上绘制的文本。不能为空。
颜色Red命名颜色。
字体大小24字体大小;无效的数值输入将回退到默认值。
字体名称Verdana字体族。必须已在服务器上安装——Windows Server 的字体比桌面少。
不透明度800 到 255。必须能够解析。
角度-45以度数表示的旋转角度;无效的数值输入将回退到默认值。

解析器在可选的 ^ 之后期望恰好六个字段。如果定义无效,将被可见的 Invalid Watermark 文本取代,而不是静默消失。

许可证决策

许可证状态提供的自定义值渲染结果
有效的付费查看器许可证否干净页面
有效的付费查看器许可证是自定义水印
有效的临时/演示许可证否干净页面
有效的临时/演示许可证是自定义水印
缺失、被拒绝、已过期、版本错误或域名无效的许可证任意评估水印;自定义值不会取代它

相同的决策适用于提供的页面和注释导出。自定义水印是已授权应用程序的功能,而不是替换评估水印的手段。

注释 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() 返回的编码信封
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 元数据

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

在此包中它始终返回 null,而小部件的元数据请求返回 501 Not Implemented:在 .NET Framework 上不支持读取 DICOM 标记。DICOM 渲染 — 页面、帧和动画 — 可正常工作。参见DICOM 插件。

资源帮助程序 — ReferenceCss / ReferenceScripts

为资源模块在 DoconutOptions.ResourcesPath 下提供的资源按依赖顺序发出 <link> 和 <script> 标记。对受许可证限制的功能(搜索、注释)的文件仅在许可证授予时才会发出 仅在许可证授予时。

text
string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // 许可证状态,用于保护 ribbon 初始化代码
bool IsAnnotationEnabled { get; }

CssConfig 标志: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss(搜索受限),IncludeAnnotationCss(注释受限)。

ScriptConfig 标志: IncludeJQuery(所有其他标志所需),IncludeBootstrap,IncludeViewerScripts(核心查看器脚本),IncludeSearchScripts 和 IncludeSearchBar(搜索受限),IncludeAnnotationScripts 和 IncludeAnnotationBar(注释受限),EmitFeatureFlags(默认 true:还会写入内联 window.Doconut.features = { search, annotation, editor } 脚本;在阻止内联脚本的 Content-Security-Policy 下将其设为 false)。

两者均返回 HTML:在 MVC 5 中使用 @Html.Raw(...) 编写它们(在控制器中生成——视图没有 @inject),或在 Web Forms 中使用 <%= %>。快速入门 展示了两种方式。

RenderViewer

text
string RenderViewer(string elementId, string token, ViewerConfig? config = null)

返回一个 <script> 块,在 id 为 elementId 的元素上初始化小部件并显示文档:由 ViewerConfig 构建的 docViewer({...})(默认:BasePath: '/',ResPath: 'doconut-res/images'),随后 .View(token)。将其写在查看器脚本之后。生成的脚本不保留对查看器对象的引用,因此拥有自定义工具栏的页面应手动初始化小部件。参见查看器配置。

Web 农场

string? AccessToken 保存最近一次打开时在分布式模式激活时签发的已签名票证,并且 UnsafeMode 为 false;在单服务器上它为 null。使用令牌将其发送给小部件:objViewer.View(token, accessToken).

此页面对您有帮助吗?