Bắt đầu nhanh
Hiển thị tài liệu đầu tiên của bạn trong vài phút
Hướng dẫn này đưa một ứng dụng ASP.NET Core từ một Program.cs trống tới một tài liệu được hiển thị trong trình duyệt: đăng ký máy chủ, gói Viewer đầy đủ (thanh công cụ Viewer, mount Viewer, và các ribbon Tìm kiếm/Chú thích tùy chọn), tham chiếu tài sản, khởi tạo client, mở tài liệu, và thực thi.
Ứng dụng máy chủ phải nhắm tới môi trường chạy hỗ trợ netstandard2.1 — .NET Core 3.0 trở lên.
Cài đặt máy chủ
AddDoconut() đăng ký các dịch vụ; UseDoconutResources() và UseDoconut() kết nối middleware. Lệnh gọi tài nguyên phải được thực hiện trước. UseDoconut() trả lời mọi yêu cầu đến, vì vậy hãy mount nó trên nhánh riêng của nó với app.Map. Các lệnh gọi session cũng cần thiết — bảo mật tài liệu mặc định của Doconut xác thực mọi yêu cầu trang đối với trạng thái session ASP.NET. Trạng thái session cần một bộ nhớ đệm: AddDistributedMemoryCache() cung cấp một. Ứng dụng MVC hoặc Razor Pages đã đăng ký nó, nhưng một ứng dụng minimal-API không, và nếu không có nó ứng dụng sẽ dừng khởi động với Unable to resolve service for type 'IDistributedCache'. Đã đăng ký Doconut trong quá trình Cài đặt chưa? Bỏ qua tới phần tiếp theo.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // trạng thái phiên cần một bộ nhớ đệm (MVC/Razor Pages đã thêm sẵn một)
builder.Services.AddSession(); // Doconut bảo mật tài liệu dựa trên trạng thái phiên ASP.NET
app.UseSession(); // gọi UseSession() trước UseDoconut()
app.UseDoconutResources(); // phải được đăng ký trước UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());Cấu hình này giữ nguyên dạng yêu cầu lịch sử DocImage.axd và mount middleware tài liệu trên một nhánh phù hợp. Đây là cách sắp xếp để sao chép khi bạn đang chuyển tiếp một ứng dụng .NET Standard hiện có, vì client vẫn gọi cùng một URL như trước đây:
builder.Services.AddDoconut(options =>
{
options.UnsafeMode = false; // giữ kiểm tra phiên của Doconut được bật
options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // trạng thái phiên cần một bộ nhớ đệm (MVC/Razor Pages đã thêm sẵn một)
builder.Services.AddSession(options =>
{
options.IdleTimeout = TimeSpan.FromSeconds(3600);
options.Cookie.HttpOnly = true;
options.Cookie.IsEssential = true;
});
// Cần thiết cho mã hoá đa byte trong một số định dạng tài liệu.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources(); // TRƯỚC nhánh tài liệu
app.MapWhen(
context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconut() không nhận bất kỳ tùy chọn nào trong phiên bản này — mọi thứ đã được chuyển sang AddDoconut().
MiddlewarePath là một giá trị phối hợp; nó không tự mình ánh xạ một nhánh ASP.NET Core. Với nhánh DocImage.axd ở trên, client sử dụng BasePath: '/'; với app.Map("/doconut", ...) từ cấu hình tối thiểu, nó sử dụng BasePath: 'doconut'.
ResourcesPath cung cấp gói nhúng tại /doconut-res, và đường dẫn tài nguyên hình ảnh của widget do đó là ResPath: 'doconut-res/images'.
Thêm trình xem vào một trang
Viewer là lõi bắt buộc của trang. Bề mặt render của nó sử dụng hai div lồng nhau:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Xem thanh công cụ, các mount module, và bề mặt Viewer như một thành phần trang duy nhất. Tìm kiếm và Chú thích chèn các ribbon nhúng của chúng vào các mount tùy chọn, nhưng các module đó không bao giờ độc lập: chúng luôn gắn vào Viewer trên cùng một trang.
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Các nút điều hướng, phóng to/thu nhỏ, Tìm kiếm và Ghi chú của Viewer -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Tham chiếu tài sản trình xem
Trong một Razor view, dịch vụ Viewer được tiêm vào phát ra các thẻ <link> và <script> của trình xem theo thứ tự phụ thuộc — widget là một plugin jQuery, vì vậy jQuery phải được tải trước các script của trình xem:
@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
}))Đối với gói Viewer đầy đủ, yêu cầu tài nguyên Viewer và các mô-đun cùng nhau:
@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 và IncludeViewerScripts là các cờ lõi bắt buộc. Không bao giờ công bố ví dụ Search hoặc Annotation Ribbon mà không có chúng, phần gắn Viewer, và một thể hiện docViewer. ReferenceCss và ReferenceScripts bỏ qua tài nguyên của mô-đun tùy chọn khi giấy phép hiện tại không cho phép tính năng đó; core Viewer vẫn khởi động.
Các lời gọi này thay thế các file script được sao chép thủ công. Nếu ứng dụng vẫn tải docViewer.js, documentLinks.js, hoặc docViewer.UI.js của riêng mình, hãy xóa các thẻ đó một khi trang hoạt động từ các tài nguyên được phát ra — xem hướng dẫn di chuyển.
Khởi tạo trình xem
Widget phía client là một plugin jQuery. Đây là một tập hợp tối thiểu các tùy chọn khởi tạo thực (không phải pseudocode):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: '/', // nhánh DocImage.axd; 'doconut' với app.Map("/doconut", ...)
ResPath: 'doconut-res/images',
onViewerReady: function () {
// các trang hiển thị; an toàn để ẩn spinner tải ở đây
},
// Chuyển tiếp các sự kiện vòng đời chú thích tới ribbon nhúng khi nó có mặt.
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});Bốn chi tiết quyết định liệu trang này có hoạt động hay không:
- Callbacks là các tùy chọn.
onViewerReady,onViewerBusy,onCopy, vàonAutoLoadStatusđược truyền vào đối tượng tùy chọn. Trình xem trước đây suy ra tên hàm toàn cục từ id của container và gọi chúng; phiên bản này không làm như vậy. Một handler được khai báo chỉ dưới dạng hàm toàn cục sẽ không bao giờ chạy, và không có gì được báo cáo. ResPathchỉ đến tiền tố tài nguyên, không phải gốc của ứng dụng. VớiResourcesPathmặc định, giá trị đó làdoconut-res/images. Nếu bạn đã thay đổiResourcesPath, hãy sử dụng tiền tố riêng của bạn. Các biểu tượng nằm một thư mục dưới gốc tài nguyên: với'doconut-res', mọi biểu tượng trả về 404 trong khi tài liệu vẫn được hiển thị.BasePathkhông có dấu slash đầu ngoại trừ giá trị gốc site'/'.'doconut'yêu cầu/doconut/DocImage.axd;'/doconut'tạo ra//doconut/DocImage.axd, mà trình duyệt đọc như một yêu cầu tới máy chủ khác.- Giữ lại trình xem, sau đó gọi
Viewriêng biệt.docViewer(...)trả về đối tượng vớiZoom,NextvàFitType;View(...)trả về một thứ khác.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)hiển thị tài liệu, sau đó thất bại vớiobjViewer.Zoom is not a functionkhi nhấn lần đầu vào thanh công cụ.
Tất cả các trường hợp này sẽ thất bại một cách im lặng — xem Khắc phục sự cố và hướng dẫn di chuyển.
Việc viết hoa/viết thường của các tùy chọn thực sự hỗn hợp — showThumbs, autoLoad và pageZoom là camelCase, nhưng FitType, BasePath và ResPath là PascalCase. Không có quy tắc nhất quán; nếu viết sai case, tùy chọn sẽ bị bỏ qua một cách im lặng (widget sẽ quay lại giá trị mặc định thay vì ném lỗi).
Tập hợp gói Viewer hoàn chỉnh
Một trang Viewer hoàn chỉnh sẽ cài đặt các phần sau cùng nhau:
| Phần của gói | Yêu cầu | Cách kết nối |
|---|---|---|
Tài nguyên Viewer, mount, và objViewer | Bắt buộc | Bộ render tài liệu lõi |
| Thanh công cụ Viewer | Bắt buộc cho một trang hoàn chỉnh | Markup của host; các nút gọi cùng objViewer |
| Thanh Ribbon Tìm kiếm | Tùy chọn, mô-đun có giấy phép | doconutSearchBar(...).attach(objViewer) |
| Thanh Ribbon Ghi chú | Tùy chọn, mô-đun có giấy phép | doconutAnnotationBar(...).attach(objViewer) |
Mặc dù thanh công cụ Viewer chính là markup của host, nó được cài đặt cùng với Viewer và không bao giờ được tài liệu hoá như một điều khiển riêng lẻ. Điều này giữ bố cục, nhãn, biểu tượng và các quy tắc ủy quyền của nó dưới sự kiểm soát của ứng dụng của bạn trong khi mỗi nút điều khiển cùng một thể hiện 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>Giữ thứ tự khởi tạo này:
- Phát ra CSS cho Viewer và các mô-đun có giấy phép.
- Hiển thị thanh công cụ Viewer, các mount Search/Annotation, và mount Viewer cùng nhau.
- Phát ra các script cho Viewer và các mô-đun có giấy phép.
- Tải script trợ giúp thanh công cụ của ứng dụng host.
- Khởi tạo
docViewervà giữobjViewerkết quả. - Khởi tạo mỗi Ribbon Tìm kiếm hoặc Ghi chú có giấy phép.
- Gọi
attach(objViewer)trên mỗi Ribbon. - Mở tài liệu và giữ token của nó cho các yêu cầu Viewer và mô-đun.
Các bảo vệ phía máy chủ là quan trọng: khi một khả năng tùy chọn không khả dụng, script của nó không được phát ra, vì vậy hàm plug‑in jQuery của nó không tồn tại.
<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>Cả hai thành phần nhúng đều tạo ra DOM Ribbon riêng của chúng. Tìm kiếm chứa các nhóm Tìm, Tùy chọn và Kết quả. Ghi chú chứa các công cụ tạo nội dung, điều khiển kiểu dáng, hành động lưu và các hành động xuất/ảnh tùy chọn. Các thanh này cung cấp open(), close(), reset() và isOpen(); luôn gọi attach(objViewer) một lần sau khi tạo chúng.
Ví dụ trên bỏ qua các callback tùy chọn của host và các endpoint xuất/ảnh của Ghi chú để giữ khởi động tối thiểu. Xem Tìm kiếm và Ghi chú để biết cấu hình đầy đủ cho từng tính năng, hoặc Chủ đề tùy chỉnh để tạo kiểu hoặc thay thế thanh công cụ Viewer thuộc sở hữu của host.
Mở tài liệu
Phía máy chủ có một điểm cuối: dịch vụ Viewer được tiêm mở tài liệu và trả về một token phiên. Việc mở là bất đồng bộ trong phiên bản này.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// Token là không trong suốt — chuyển nó cho widget, không bao giờ ghi log hoặc lưu trữ nó.
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});Máy khách lấy token đó và truyền nó cho widget bằng objViewer.View(token):
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});Không có gì cần khởi động trước lần mở đầu tiên. Nếu bạn đang chuyển tiếp một ứng dụng, hãy xóa bất kỳ lời gọi InitCache() nào và cờ bảo vệ nó — phương thức này không còn tồn tại.
Đóng tài liệu
Gọi objViewer.Close(true) khi người dùng rời khỏi trình xem hoặc mở một tài liệu thay thế: nó sẽ xóa widget và gửi yêu cầu đóng tới máy chủ. objViewer.Close() không có đối số chỉ xóa widget. Trong quy trình làm việc do máy chủ điều khiển, viewer.CloseDocument(token) ngay lập tức loại bỏ phiên được lưu trong bộ nhớ đệm, giải phóng engine render, xóa dấu bảo mật của nó và thu hồi token. Thời gian hết hạn trượt cuối cùng sẽ thực hiện cùng một quá trình dọn dẹp, nhưng việc đóng rõ ràng được khuyến nghị cho các tài liệu lớn.
Luồng yêu cầu đã hoàn thành là:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentXử lý token như một chứng chỉ mang: không bao giờ ghi log nó, không bao giờ lưu trữ nó, chỉ truyền nó cho widget. Nó xác định một phiên tài liệu đang hoạt động trên máy chủ và sẽ ngừng hoạt động khi phiên đó hết hạn — mở lại tài liệu để nhận một token mới.
Chạy nó
Đặt một tệp PDF tại wwwroot/files/Sample.pdf, chạy dotnet run, và mở trang chứa widget. Trang đầu tiên sẽ được hiển thị trong trình xem, với một bảng thu nhỏ ở phía trái. Nếu không, xem Khắc phục sự cố.
Những gì bạn nhận được mà không có giấy phép
Thiếu giấy phép không gây lỗi. Trình xem vẫn hiển thị bình thường, nhưng mỗi trang sẽ có dấu nước đánh giá. Xem Cài đặt giấy phép để biết cách Doconut tìm giấy phép và những gì sẽ thay đổi khi nó được tìm thấy.
Trang này có hữu ích không?