快速入门

在几分钟内渲染您的第一份文档

本指南将一个空的 Program.cs ASP.NET Core 应用转变为在浏览器中渲染的文档:服务器注册、完整的 Viewer 包(Viewer 工具栏、Viewer 挂载以及可选的搜索/注释功能区)、资源引用、客户端初始化、文档打开以及执行。

宿主应用必须面向支持 netstandard2.1 的运行时——.NET Core 3.0 或更高版本。

服务器设置

AddDoconut() 注册服务;UseDoconutResources() 和 UseDoconut() 连接中间件。资源调用必须先进行。UseDoconut() 响应所有到达它的请求,因此使用 app.Map 将其挂载在独立的分支上。会话调用也必需——Doconut 的默认文档安全会根据 ASP.NET 会话状态验证每个页面请求。会话状态需要缓存:AddDistributedMemoryCache() 提供了一个。MVC 或 Razor Pages 应用已经注册了它,但最小化 API 应用没有,如果没有它,应用将在启动时因 Unable to resolve service for type 'IDistributedCache' 而停止。已经在安装期间注册了 Doconut?跳到下一节。

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // 会话状态需要缓存(MVC/Razor Pages 已经添加了一个)
builder.Services.AddSession(); // Doconut 文档安全依赖于 ASP.NET 会话状态

app.UseSession();          // 在调用 UseDoconut() 之前调用 UseSession()
app.UseDoconutResources(); // 必须在 UseDoconut() 之前注册
app.Map("/doconut", branch => branch.UseDoconut());

此设置保持了历史的 DocImage.axd 请求形状,并在匹配的分支上挂载文档中间件。这是向前迁移现有 .NET Standard 应用时需要复制的安排,因为客户端始终调用相同的 URL:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // 保持 Doconut 的会话检查启用
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // 会话状态需要缓存(MVC/Razor Pages 已经添加了一个)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// 在某些文档格式中需要多字节编码。
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // 在文档分支之前
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() 在此版本中不接受任何选项——所有内容都已迁移至 AddDoconut()。
MiddlewarePath 是一个协调值;它本身并不映射 ASP.NET Core 分支。
使用上面的 DocImage.axd 分支时,客户端使用 BasePath: '/';而在最小化设置中使用 app.Map("/doconut", ...) 时,客户端使用 BasePath: 'doconut'。
ResourcesPath 在 /doconut-res 提供嵌入式包,因此小部件的图像资源路径为 ResPath: 'doconut-res/images'。

将查看器添加到页面

Viewer 是页面所需的核心。其渲染表面使用两个嵌套的 div:

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

将工具栏、模块挂载和 Viewer 表面视为一个页面组合。搜索和注释会将其嵌入的功能区注入可选挂载点,但这些模块从不单独存在:它们始终附加在同一页面的 Viewer 上。

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- 查看器导航、缩放、搜索和注释按钮 -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

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

引用查看器资产

在 Razor 视图中,注入的 Viewer 服务按依赖顺序发出查看器的 <link> 和 <script> 标记 — 该小部件是 jQuery 插件,因此必须在查看器脚本之前加载 jQuery:

html
@inject Doconut.Viewer Viewer

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

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery        = true,
    IncludeBootstrap     = true,
    IncludeViewerScripts = true
}))

要获取完整的 Viewer 包,请一起请求 Viewer 和模块资源:

html
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeBootstrapCss  = true,
    IncludeViewerCss     = true,
    IncludeSearchCss     = true,
    IncludeAnnotationCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery            = true,
    IncludeBootstrap         = true,
    IncludeViewerScripts     = true,
    IncludeSearchScripts     = true,
    IncludeSearchBar         = true,
    IncludeAnnotationScripts = true,
    IncludeAnnotationBar     = true
}))

IncludeViewerCss 和 IncludeViewerScripts 是必需的核心标志。切勿在没有它们、Viewer 挂载以及 docViewer 实例的情况下发布搜索或注释功能区示例。当当前许可证未授予该功能时,ReferenceCss 和 ReferenceScripts 会省略可选模块的资源;核心 Viewer 仍会启动。

这些调用取代了手动复制的脚本文件。如果应用程序仍然加载其自己的 docViewer.js、documentLinks.js 或 docViewer.UI.js,在页面能够使用发出的资源正常工作后,请移除这些标签 — 请参阅 迁移指南。

初始化查看器

客户端小部件是 jQuery 插件。这是一组最小的真实初始化选项(非伪代码):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // DocImage.axd 分支;'doconut' 使用 app.Map("/doconut", ...)
    ResPath:    'doconut-res/images',
    onViewerReady: function () {
        // 页面已可见;此处安全地隐藏加载指示器
    },
    // 当嵌入式 ribbon 存在时,将注释生命周期事件转发给它
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

四个细节决定此页面是否能正常工作:

  • 回调是选项。 onViewerReady、onViewerBusy、onCopy 和 onAutoLoadStatus 通过选项对象传递。之前的查看器从容器 id 派生全局函数名并调用它们;而此版本不这样做。仅作为全局函数声明的处理程序永远不会运行,也不会有任何报告。
  • ResPath 指向资源前缀,而不是应用程序根目录。使用默认的 ResourcesPath 时,该值为 doconut-res/images。如果你更改了 ResourcesPath,请改用自己的前缀。图标位于资源根目录下一级文件夹:使用 'doconut-res' 时,所有图标都会返回 404,而文档本身仍能渲染。
  • BasePath 没有前导斜杠,除非是站点根值 '/'。'doconut' 请求 /doconut/DocImage.axd;'/doconut' 产生 //doconut/DocImage.axd,浏览器将其视为对另一个主机的请求。
  • 保留查看器,然后单独调用 View。 docViewer(...) 返回包含 Zoom、Next 和 FitType 的对象;View(...) 返回其他内容。var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) 渲染文档,然后在第一次工具栏点击时因 objViewer.Zoom is not a function 失败。

所有这些都会静默失败 — 请参阅 故障排除 和 迁移指南。

选项的大小写确实混杂 — showThumbs、autoLoad 和 pageZoom 使用 camelCase,而 FitType、BasePath 和 ResPath 使用 PascalCase。没有统一的规则;大小写写错后,选项会被静默忽略(小部件会回退到默认值,而不是抛出错误)。

组装完整的 Viewer 包

完整的 Viewer 页面将以下部分一起安装:

包的组成部分需求连接方式
Viewer 资源、挂载和 objViewer必需核心文档渲染器
Viewer 工具栏完整页面所需宿主标记;按钮调用相同的 objViewer
搜索功能区可选,授权模块doconutSearchBar(...).attach(objViewer)
批注功能区可选,授权模块doconutAnnotationBar(...).attach(objViewer)

虽然主要的 Viewer 工具栏是宿主标记,但它与 Viewer 一起安装,且绝不能被记录为独立控件。这样可以让其布局、标签、图标和授权规则保持在你的应用程序控制之下,同时每个按钮驱动相同的 Viewer 实例:

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.GotoPage(objViewer.TotalPages())">Last</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>
    <button type="button" onclick="objViewer.FitType('height')">Fit height</button>
    <button type="button" id="openSearch">Search</button>
    <button type="button" id="openAnnotations">Annotations</button>
</nav>

保持以下初始化顺序:

  1. 为 Viewer 和授权模块输出 CSS。
  2. 一起渲染 Viewer 工具栏、Search/Annotation 挂载点以及 Viewer 挂载点。
  3. 为 Viewer 和授权模块输出脚本。
  4. 加载宿主应用程序自己的工具栏辅助脚本。
  5. 初始化 docViewer 并保留生成的 objViewer。
  6. 初始化每个授权的 Search 或 Annotation 功能区。
  7. 在每个功能区上调用 attach(objViewer)。
  8. 打开文档并保留其令牌,以供 Viewer 和模块请求使用。

服务器端的保护很重要:当可选功能不可用时,其脚本不会被输出,因此其 jQuery 插件函数不存在。

html
<script>
    let token = '';

    const refitViewer = () =>
        requestAnimationFrame(() => objViewer.Refit());

    @if (Viewer.IsSearchEnabled)
    {
        <text>
    searchBar = $('#searchBarMount').doconutSearchBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    searchBar.attach(objViewer);
        </text>
    }

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    annBar.attach(objViewer);
        </text>
    }

    document.getElementById('openSearch').addEventListener('click', () => {
        if (!searchBar) return;
        searchBar.isOpen() ? searchBar.close() : searchBar.open();
    });

    document.getElementById('openAnnotations').addEventListener('click', () => {
        if (!annBar) return;
        annBar.isOpen() ? annBar.close() : annBar.open();
    });
</script>

两个嵌入式组件都会生成各自的功能区 DOM。Search 包含 Find、Options 和 Results 组。Annotation 包含其创作工具、样式控制、保存操作以及可选的导出/图像操作。这些栏位公开 open()、close()、reset() 和 isOpen();创建后始终调用一次 attach(objViewer)。

上面的示例省略了可选的宿主回调和 Annotation 导出/图像端点,以保持启动最小化。请参阅搜索和批注了解完整的特定功能设置,或查看自定义主题以为宿主拥有的 Viewer 工具栏设置样式或替换它。

打开文档

服务器端只有一个端点:注入的 Viewer 服务打开文档并返回会话令牌。此版本中,打开操作是异步的。

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // 令牌是不可见的 — 将其交给 widget,切勿记录或持久化它。
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

客户端获取该令牌并使用 objViewer.View(token) 将其交给小部件:

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

首次打开之前无需预热。如果你在迁移应用程序,请删除所有 InitCache() 调用以及其保护标志——该方法已不再存在。

关闭文档

当用户离开查看器或打开替换文档时调用 objViewer.Close(true):它会清除小部件并向服务器发送关闭请求。objViewer.Close() 在没有参数的情况下仅清除小部件。在服务器驱动的工作流中,viewer.CloseDocument(token) 会立即移除缓存的会话,释放渲染引擎,删除其安全标记,并撤销令牌。滑动过期最终会执行相同的清理,但对于大型文档建议显式关闭。

完整的请求流程如下:

text
AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

将令牌视为持有者凭证:绝不要记录它,绝不要持久化它,只交给小部件。它标识服务器上的活跃文档会话,并在会话过期后失效——重新打开文档即可获取新的令牌。

运行它

将 PDF 放置在 wwwroot/files/Sample.pdf,运行 dotnet run,然后打开承载小部件的页面。第一页会在查看器中渲染,左侧显示缩略图面板。如果未渲染,请参阅 故障排除。

未获得许可证时的功能

缺少许可证不会抛出错误。查看器仍会正常渲染,但每页都会带有评估水印。请参阅 许可证设置 了解 Doconut 如何查找许可证以及找到后会有哪些变化。

此页面对您有帮助吗?