快速入门
在几分钟内渲染您的第一份文档
本指南将一个空的 Program.cs ASP.NET Core 应用转换为在浏览器中渲染的文档:服务器注册、完整的 Viewer 包(Viewer 工具栏、Viewer 挂载点以及可选的搜索/注释功能区)、资源引用、客户端初始化、文档打开以及执行。
服务器设置
AddDoconut() 注册服务;UseDoconutResources() 和 UseDoconut() 连接中间件。资源调用必须首先执行。UseDoconut() 响应所有到达它的请求,因此使用 app.Map 将其挂载在单独的分支上。会话调用也是必需的——Doconut 的默认文档安全会根据 ASP.NET 会话状态验证每个页面请求。会话状态需要缓存:AddDistributedMemoryCache() 提供一个。MVC 或 Razor Pages 应用已经注册了它,但最小 API 应用没有,没有它时应用会在启动时因 Unable to resolve service for type 'IDistributedCache' 而停止。已经在安装期间注册了 Doconut?跳到下一节。
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());对于生产环境的路径布局,将文档中间件映射到显式分支,并保持四个路径设置对齐:
builder.Services.AddDoconut(options =>
{
options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
options.MiddlewarePath = "/doconut";
options.ResourcesPath = "/doconut-res";
options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
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 会自行添加一个,所以 '/doconut' 将变为 //doconut/DocImage.axd,浏览器会将其读取为对名为 doconut 的主机的请求,导致 viewer 报错 "The viewer handler could not be reached"。
将 viewer 添加到页面
Viewer 是页面所需的核心。其渲染表面使用两个嵌套的 div:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>将工具栏、模块挂载点和 Viewer 表面视为一个页面组合。搜索和注释将其嵌入式功能区注入可选挂载点,但这些模块从不单独存在:它们始终附加在同一页面的 Viewer 上。使用以下顺序:
<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>引用 viewer 资源
在 Razor 视图中,注入的 Viewer 服务按依赖顺序输出 viewer 的 <link> 和 <script> 标记——该组件是 jQuery 插件,因此必须在 viewer 脚本之前加载 jQuery:
@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.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 插件。这是一组最小的真实初始化选项(非伪代码):
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 () {
// 页面已可见;此处可以安全地隐藏加载指示器
},
// 当嵌入式功能区存在时,将注释生命周期事件转发给它。
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。没有统一的规则;如果大小写写错,选项会被悄悄忽略(小部件会回退到默认值,而不是抛出错误)。
还有四个细节会在没有错误信息的情况下失效:
BasePath没有前导斜杠。'doconut'请求/doconut/DocImage.axd;'/doconut'产生//doconut/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失败。
组装完整的 Viewer 包
完整的查看器页面会一起安装以下部件:
| 包的组成部分 | 需求 | 连接方式 |
|---|---|---|
Viewer 资源、挂载以及 objViewer | 必需 | 核心文档渲染器 |
| Viewer 工具栏 | 完整页面所必需 | 主机标记;按钮调用相同的 objViewer |
| 搜索功能区 | 可选,授权模块 | doconutSearchBar(...).attach(objViewer) |
| 注释功能区 | 可选,授权模块 | doconutAnnotationBar(...).attach(objViewer) |
虽然主 Viewer 工具栏是主机标记,但它与 Viewer 一起安装,绝不能被文档化为独立控件。这使得其布局、标签、图标和授权规则由你的应用程序控制,同时每个按钮都驱动同一个 Viewer 实例:
<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>旋转、缩略图、打印、全屏、布局以及按钮状态的辅助功能应放在你自己的工具栏脚本中,该脚本调用相同的 objViewer。在 Viewer.ReferenceScripts(...) 之后加载,并与其 <nav id="toolbar"> 标记一起保留。
保持以下初始化顺序:
- 为 Viewer 和授权模块输出 CSS。
- 渲染 Viewer 工具栏、搜索/注释挂载点以及 Viewer 挂载点。
- 为 Viewer 和授权模块输出脚本。
- 加载主机应用程序自己的工具栏辅助脚本。
- 初始化
docViewer并保留生成的objViewer。 - 初始化每个授权的搜索或注释功能区。
- 对每个功能区调用
attach(objViewer)。 - 打开文档并保留其令牌,以供 Viewer 和模块请求使用。
在分布式部署中,额外的 access 请求值和异步渲染重试设置属于传输层;它们不会改变 Viewer、工具栏或功能区的组装方式。
服务器端的防护很重要:当可选功能不可用时,其脚本不会被输出,从而其 jQuery 插件函数不存在。
<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。搜索功能区包含“查找、选项和结果”组。注释功能区包含其创作工具、样式控制、保存操作以及可选的导出/图像操作。这些栏公开 open()、close()、reset() 和 isOpen();创建后务必调用一次 attach(objViewer)。
上面的示例省略了可选的主机回调和注释的导出/图像端点,以保持启动最小化。请参阅 搜索 和 注释 获取完整的功能特定设置,或查看 自定义主题 来为主机拥有的 Viewer 工具栏设置样式或替换它。
打开文档
服务器端只有一个端点:注入的 Viewer 服务打开文档并返回会话令牌。
app.MapPost("/api/open", async (Viewer viewer) =>
{
// token 是不透明的 — 将其交给 widget,切勿记录或持久化它。
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});客户端获取该令牌并使用 objViewer.View(token) 将其传递给小部件:
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});关闭文档
当用户离开查看器或打开替换文档时调用 objViewer.Close(true):它会清除小部件并向服务器发送关闭请求。objViewer.Close() 在没有参数的情况下仅清除小部件。在服务器驱动的工作流中,viewer.CloseDocument(token) 会立即移除缓存的会话,释放渲染引擎,删除其安全标记,并撤销令牌。滑动过期最终会执行相同的清理,但对于大文档建议显式关闭。
完整的请求流程如下:
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 如何查找许可证以及找到后会有哪些变化。
此页面对您有帮助吗?