快速入门

在 MVC 5 或 Web Forms 中渲染您的第一个文档

本指南将一个基于 .NET Framework 4.7.2 的 ASP.NET 应用程序,从已安装的包转化为在浏览器中渲染的文档:Global.asax、一个打开端点、查看器的资源、部件以及连接它们的令牌。它假设已完成来自安装的Web.config 注册——如果缺少DocImage.axd 处理程序和资源模块,下面的内容将无法访问服务器。

在 Global.asax 中组合 Doconut

针对 MVC 5 应用程序的完整 Application_Start:

csharp
// Global.asax.cs - 每个工作进程仅构建一次,关闭时释放。
protected void Application_Start()
{
    Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.UnsafeMode  = false; // 页面仅提供给打开文档的会话
    });

    // MVC only: 保持两个 Doconut 端点不被路由。
    RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}
  • Encoding.RegisterProvider 使某些文档格式使用的传统代码页对进程可用。请在打开第一个文档之前调用一次。
  • UnsafeMode = false 是默认设置,明确写出以防止有人意外更改:DocImage.axd 仅向打开文档的 ASP.NET 会话提供页面。
  • 两个 IgnoreRoute 调用 将 MVC 路由从 DocImage.axd 和 /doconut-res/* 中排除,这些由处理程序和模块提供。Web Forms 应用程序没有 MVC 路由,因此不需要此行。
  • DoconutHost.Shutdown 在应用程序池回收时停止 Doconut 的后台工作并释放其服务。即使 Initialize 从未运行,调用它也是安全的。

打开文档

打开文档会返回一个不透明的令牌。部件在每个页面请求中都会发送该令牌。

在 MVC 5 中,控制器操作从 DoconutHost.Services 解析 Viewer 服务——MVC 5 不支持构造函数注入:

csharp
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

    // 令牌是不透明的 - 将其交给查看器,绝不记录或持久化它。
    string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
    return Json(new { token });
}

文档必须在具有会话状态的请求内部打开,因为打开文档会授予当前 ASP.NET 会话访问其页面的权限。MVC 控制器和 Web Forms 页面默认具有会话状态。自定义 IHttpHandler 没有会话状态,除非它实现了 System.Web.SessionState.IRequiresSessionState。如果在没有会话状态的处理程序中打开文档,查看器将在每个页面上显示 “您无权查看此页面。”。

在 Web Forms 中,页面本身可以在其代码隐藏文件中打开文档。OpenDocument 是 OpenDocumentAsync 的同步形式,适用于不使用异步页面的代码隐藏文件:

csharp
// Default.aspx.cs
protected string Token;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    Token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
}

将令牌视为持有者凭证:切勿记录或持久化它;仅交给部件使用。当文档会话过期时,它将失效——请重新打开文档以获取新的令牌。

引用查看器资源

Viewer.ReferenceCss 和 Viewer.ReferenceScripts 发出 <link> 和 <script> 标签,用于嵌入的资源,按依赖顺序指向 /doconut-res/。该小部件是一个 jQuery 插件,所以 jQuery 必须先加载。

MVC 5. 视图没有 @inject,因此在控制器中生成这些标签并通过 ViewBag 传递它们:

csharp
public ActionResult Index()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
    {
        IncludeBootstrapCss = true,
        IncludeViewerCss    = true
    });
    ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
    {
        IncludeJQuery        = true,
        IncludeBootstrap     = true,
        IncludeViewerScripts = true
    });
    return View();
}
html
@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)

将这些工作保留在控制器中。MVC 5 在首次提供时编译视图,如果没有额外的编译器包,该编译器只能理解 C# 5 —— 没有 ?.,没有 $"...",没有 nameof。使用这些标签的视图在 Visual Studio 中能够顺利编译,然后在浏览器中返回一个空的 500。

Web Forms. 从代码隐藏文件中公开相同的字符串,并使用 <%= %> 写入它们:

html
<head>
    <%= ViewerCss %>
</head>
<body>
    ...
    <%= ViewerScripts %>
</body>

IncludeViewerCss 和 IncludeViewerScripts 是必需的核心。要添加搜索和注释功能区,还需设置 IncludeSearchCss、IncludeAnnotationCss、IncludeSearchScripts、IncludeSearchBar、IncludeAnnotationScripts 和 IncludeAnnotationBar。当许可证未授予相应功能时,这两种方法都会省略相应功能区的文件;查看器本身仍会启动。

将查看器添加到页面

渲染表面是两个嵌套的 div:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

为外层 div 设置真实的高度 —— 查看器会填满其容器并在启动时进行测量。查看器不会绘制自己的工具栏:GotoPage、Next、Zoom、FitType,其余的都是页面绑定到自己按钮上的方法,这些按钮放在查看器旁边:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <button type="button" onclick="objViewer.GotoPage(1)">First</button>
    <button type="button" onclick="objViewer.Next(false)">Previous</button>
    <button type="button" onclick="objViewer.Next(true)">Next</button>
    <button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
    <button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
    <button type="button" onclick="objViewer.FitType('width')">Fit width</button>
</nav>

初始化查看器并显示文档

在加载查看器脚本后,创建小部件,然后将令牌交给它:

javascript
var objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // '/' 表示站点根目录下的 DocImage.axd
    ResPath:    'doconut-res/images',  // 没有前导 '/'
    onViewerReady: function () {
        // 页面已可见; 在此隐藏加载指示器
    },
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

fetch('/Document/Open', { method: 'POST' })
    .then(function (resp) { return resp.json(); })
    .then(function (data) { objViewer.View(data.token); });

在 Web Forms 中,如果页面本身打开文档,则最后三行会变成 objViewer.View('<%= Token %>');。

以下四个细节会在没有错误信息的情况下失败:

  • BasePath: '/' 在站点根目录定位 DocImage.axd。对于位于虚拟目录中的应用程序,请使用不带斜杠的名称('myapp' 请求 /myapp/DocImage.axd)。前导斜杠('/myapp')会产生 //myapp/DocImage.axd,浏览器会将其视为对另一个主机的请求。
  • ResPath: 'doconut-res/images' —— 图标位于资源根目录下一级文件夹。使用 'doconut-res' 时,所有图标都会返回 404:没有工具栏图标,也没有加载指示器,而文档本身仍然渲染。前导斜杠会像 BasePath 那样导致同样的问题。
  • 回调是选项。 onViewerReady、onError 以及其他回调应放在传递给 docViewer(...) 的对象中。像 ctlDoc_ViewerReady 这样的全局函数(以查看器命名)永远不会被调用。
  • 保留查看器实例,然后单独调用 View。 docViewer(...) 返回包含 Zoom、Next 和 FitType 的对象;View(...) 返回其他内容。var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) 渲染文档,但在第一次点击工具栏时会因 objViewer.Zoom is not a function 而失败。

选项名称混合了 camelCase(showThumbs、autoLoad、pageZoom)和 PascalCase(FitType、BasePath、ResPath)。拼写错误的选项会被忽略,小部件会使用默认值。

单行替代方案

对于只需要显示文档且没有自定义工具栏的页面,Viewer.RenderViewer 会编写完整的初始化脚本 —— docViewer(...) 与 BasePath: '/' 和 ResPath: 'doconut-res/images',随后 .View(token)。它仅在此包中存在:

csharp
// Default.aspx.cs
protected string ViewerInit;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    string token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
    ViewerInit = viewer.RenderViewer("div_ctlDoc", token);
}
html
<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>

将 ViewerConfig 作为第三个参数传入,以更改缩放、适配或缩略图面板。由于生成的脚本不保留对查看器的引用,当页面需要自己的工具栏时,请使用上面手写的初始化代码。

关闭文档

当用户离开查看器或打开替代文档时,调用 objViewer.Close(true):它会清除小部件并向 DocImage.axd 发送关闭请求。objViewer.Close() 在不带参数的情况下仅清除小部件。在服务器端,viewer.CloseDocument(token) 会立即移除文档会话,释放其渲染资源,并撤销会话对页面的访问。滑动过期最终会产生相同效果,但显式关闭大型文档可以更快释放内存。

运行它

将 PDF 放置在 ~/files/Sample.pdf,在 IIS Express 中启动站点(在 Visual Studio 中按 F5),并打开承载小部件的页面。首个页面会渲染,左侧显示缩略图。如果未渲染,请参阅 故障排除。

未授权时的功能

缺少许可证不会抛出错误。查看器仍会正常渲染,但每页都会带有评估水印。请参阅 许可证设置 了解 Doconut 在何处查找您的许可证。

此页面对您有帮助吗?