快速入门

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

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

服务器设置

AddDoconut() 注册服务；UseDoconutResources() 和 UseDoconut() 连接中间件。资源调用必须先于其他调用。会话调用也是必需的 —— Doconut 的默认文档安全会对每个页面请求进行 ASP.NET 会话状态验证。已经在安装期间注册了 Doconut？请直接跳到下一节。

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddSession(); // Doconut document security rides on ASP.NET session state

app.UseSession();          // call UseSession() before UseDoconut()
app.UseDoconutResources(); // must be registered before UseDoconut()
app.UseDoconut();

对于生产环境的路径布局，将文档中间件映射到显式分支并保持四个路径设置一致：

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "Doconut.Viewer.lic");
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath 是一个协调值；它本身并不会映射 ASP.NET Core 分支。在本例中，宿主映射了 /doconut，因此客户端必须使用 BasePath: '/doconut'。ResourcesPath 在 /doconut-res 提供嵌入式包，而小部件的图像资源路径因此为 ResPath: '/doconut-res/images'。

将查看器添加到页面

Viewer 是页面必需的核心。它的渲染表面使用两个嵌套的 div：

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

将工具栏、模块挂载点和 Viewer 表面视为同一页面组合。搜索和注释会将其嵌入的功能区注入可选挂载点，但这些模块从不单独存在：它们始终附加在同一页面的 Viewer 上。使用与 Doconut.TestApp 和 Doconut.TestApp.Distributed 相同的顺序：

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer navigation, zoom, Search, and Annotation buttons -->
</nav>

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

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

引用查看器资源

在 Razor 视图中，注入的 Viewer 服务按依赖顺序输出 Viewer 的 <link> 和 <script> 标签 —— 小部件是 jQuery 插件，因此必须先加载 jQuery 再加载 Viewer 脚本：

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 仍会启动。

初始化查看器

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

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/doconut',
    ResPath:    '/doconut-res/images',
    onViewerReady: function () {
        // pages are visible; safe to hide a loading spinner here
    },
    // Forward annotation lifecycle events to the embedded ribbon when it is present.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

选项的大小写确实混合——showThumbs、autoLoad、pageZoom 为 camelCase，而 FitType、BasePath、ResPath 为 PascalCase。没有统一规则；大小写写错会导致选项被静默忽略（小部件会回退到默认值而不是抛异常）。

组装完整的查看器包

两个 .NET 8 参考应用在同一页面上一起安装以下部件：

包的部分需求连接方式
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>

完整的参考工具栏还会将 wwwroot/js/viewerToolbar.js 复制到宿主应用中，用于旋转、缩略图、打印、全屏、布局以及按钮状态的帮助函数。请在 Viewer.ReferenceScripts(...) 之后加载该宿主文件。复制完整示例实现时，请将帮助函数及其 <nav id="toolbar"> 标记一起保留。

保持两套参考应用使用的包初始化顺序：

  1. 一起发出 Viewer、Search 和 Annotation 资源。
  2. 一起渲染 Viewer 工具栏、功能区挂载点和 Viewer 挂载点。
  3. 首先初始化 docViewer。
  4. 创建每个已授权的功能区并将其附加到同一个 objViewer。
  5. 打开文档并保留其令牌以供模块请求。

Doconut.TestApp.Distributed 保持完全相同的 UI 组合和相同的 Viewer‑toolbar 帮助函数。其额外的 access 请求值以及异步渲染重试设置属于分布式传输；它们不会改变 Viewer、工具栏或功能区的组装方式。

服务器端的防护很重要：当可选功能不可用时，其脚本不会被输出，从而其 jQuery 插件函数不存在。

html
<script>
    let currentToken = '';

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

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

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        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 包含“查找”“选项”“结果”组；Annotation 包含其创作工具、样式控制、保存操作以及可选的导出/图像操作。功能区公开 open()、close()、reset() 与 isOpen()；创建后务必一次性调用 attach(objViewer)。

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

打开文档

服务器端只有一个端点：注入的 Viewer 服务打开文档并返回会话令牌。

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // The token is opaque — hand it to the widget, never log or persist it.
    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 => {
        currentToken = data.token;
        objViewer.View(currentToken);
    });

关闭文档

当用户离开查看器或打开替换文档时调用 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

请将令牌视为持有者凭证：绝不要记录、持久化，仅交给小部件使用。它标识服务器上活跃的文档会话，会在会话过期后失效——此时需要重新打开文档以获取新的令牌。

运行它

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

未授权时的表现

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

此页面有帮助吗？