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, phần gắn Viewer, và các ribbon Tìm kiếm/Chú thích tùy chọn), tham chiếu tài nguyên, khởi tạo client, mở tài liệu, và thực thi.

Cấu hình 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 đặt trước. UseDoconut() trả lời mọi yêu cầu đến, vì vậy hãy gắn nó vào một nhánh riêng 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 dựa trên trạng thái session của 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 thì không, và nếu không có nó ứng dụng sẽ dừng khi 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 và chuyển tới phần tiếp theo.

csharp
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(); // Bảo mật tài liệu Doconut 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());

Đối với bố cục đường dẫn kiểu sản xuất, ánh xạ middleware tài liệu tới một nhánh rõ ràng và giữ bốn cài đặt đường dẫn đồng bộ:

csharp
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 là một giá trị phối hợp; nó không tự mình ánh xạ một nhánh ASP.NET Core. Trong ví dụ này máy chủ ánh xạ /doconut, vì vậy client sử dụng BasePath: 'doconut'. ResourcesPath phục vụ bundle 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'. Viết cả hai không có dấu gạch chéo đầu: viewer sẽ tự thêm một dấu gạch chéo, vì vậy '/doconut' sẽ trở thành //doconut/DocImage.axd, mà trình duyệt sẽ đọc như một yêu cầu tới một host tên là doconut, và viewer sẽ thất bại với "The viewer handler could not be reached".

Thêm viewer vào 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:

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

Xem thanh công cụ, các phần gắn 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 phần gắn 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. Sử dụng thứ tự này:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Các nút điều hướng, thu phóng, 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 nguyên viewer

Trong một Razor view, dịch vụ Viewer được tiêm sẽ phát ra các thẻ <link> và <script> của viewer 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 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
}))

Đối với gói Viewer đầy đủ, yêu cầu các tài nguyên Viewer và module cùng nhau:

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 và IncludeViewerScripts là các cờ lõi bắt buộc. Không bao giờ công bố một ví dụ Ribbon Tìm kiếm hoặc Chú thích mà không có chúng, phần gắn Viewer, và một docViewer đối tượng. ReferenceCss và ReferenceScripts bỏ qua các tài nguyên của module tùy chọn khi giấy phép hiện tại không cho phép tính năng đó; Viewer lõi vẫn khởi động.

Khởi tạo trình xem

Widget phía máy khách 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 mã giả):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   'doconut',             // không có '/' ở đầu
    ResPath:    'doconut-res/images',  // không có '/' ở đầu
    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ó hiện diện.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Việc viết hoa chữ trong 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 kiểu chữ thì 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).

Bốn chi tiết nữa sẽ thất bại mà không có thông báo lỗi:

  • BasePath không có dấu gạch chéo đầu. 'doconut' yêu cầu /doconut/DocImage.axd; '/doconut' tạo ra //doconut/DocImage.axd, mà trình duyệt hiểu là một yêu cầu tới máy chủ khác.
  • ResPath: 'doconut-res/images' — các biểu tượng nằm một thư mục dưới thư mục gốc tài nguyên. Với 'doconut-res', mọi biểu tượng trả về 404: không có glyph trên thanh công cụ và không có biểu tượng tải, trong khi tài liệu vẫn được hiển thị. Một dấu gạch chéo đầu sẽ phá vỡ nó theo cùng cách như BasePath.
  • Callbacks là các tùy chọn. onViewerReady, onError và các phần còn lại được đặt trong đối tượng truyền cho docViewer(...). Một hàm toàn cục đặt tên theo trình xem, như ctlDoc_ViewerReady, sẽ không bao giờ được gọi.
  • Giữ lại trình xem, sau đó gọi View riêng biệt. docViewer(...) trả về đối tượng với Zoom, Next và 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ới objViewer.Zoom is not a function khi nhấp vào thanh công cụ lần đầu.

Tập hợp gói Viewer đầy đủ

Một trang Viewer đầy đủ sẽ cài đặt các phần sau cùng nhau:

Phần của góiYêu cầuCách kết nối
Tài nguyên Viewer, mount, và objViewerBắt buộcBộ render tài liệu cốt lõi
Thanh công cụ ViewerBắt buộc cho một trang đầy đủMarkup host; các nút gọi cùng objViewer
Ribbon tìm kiếmTùy chọn, mô-đun có giấy phépdoconutSearchBar(...).attach(objViewer)
Ribbon chú thíchTùy chọn, mô-đun có giấy phépdoconutAnnotationBar(...).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ữ cho bố cục, nhãn, biểu tượng và quy tắc ủy quyền của nó dưới quyền 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:

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>

Các trợ giúp xoay, thu nhỏ, in, toàn màn hình, bố cục và trạng thái nút nên nằm trong script thanh công cụ của bạn, script này gọi cùng objViewer. Tải nó sau Viewer.ReferenceScripts(...), và giữ nó cùng với markup <nav id="toolbar"> của nó.

Giữ thứ tự khởi tạo này:

  1. Phát CSS cho Viewer và các mô-đun có giấy phép.
  2. Render thanh công cụ Viewer, các mount Tìm kiếm/Chú thích, và mount Viewer cùng nhau.
  3. Phát script cho Viewer và các mô-đun có giấy phép.
  4. Tải script trợ giúp thanh công cụ riêng của ứng dụng host.
  5. Khởi tạo docViewer và giữ objViewer kết quả.
  6. Khởi tạo mỗi Ribbon Tìm kiếm hoặc Chú thích có giấy phép.
  7. Gọi attach(objViewer) trên mỗi Ribbon.
  8. Mở tài liệu và giữ token của nó cho các yêu cầu Viewer và mô-đun.

Trong triển khai phân tán, giá trị yêu cầu bổ sung access và các cài đặt thử lại render bất đồng bộ thuộc về lớp truyền tải; chúng không thay đổi cách Viewer, thanh công cụ, hoặc các Ribbon được lắp ráp.

Các biện pháp bảo vệ phía máy chủ rất quan trọng: khi một khả năng tùy chọn không khả dụng, script của nó sẽ không được phát, vì vậy hàm plugin jQuery của nó sẽ không tồn tại.

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>

Cả hai thành phần nhúng đều tạo ra DOM Ribbon riêng của chúng. Search chứa các nhóm Find, Options và Results. Annotation chứa các công cụ tạo nội dung, điều khiển kiểu, hành động lưu, và các hành động xuất/ảnh tùy chọn. Các thanh 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 Annotation để giữ việc khởi động tối thiểu. Xem Tìm kiếm và Chú thích để biết cấu hình đầy đủ cho từng tính năng, hoặc Giao diện 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.

csharp
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à chuyển nó cho widget bằng objViewer.View(token):

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

Đó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 cũng 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:

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

Xử 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ỉ chuyể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 bên trái. Nếu không, xem Khắc phục sự cố.

Những gì bạn nhận được khi 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?