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 đến một tài liệu được hiển thị trong trình duyệt: đăng ký máy chủ, gói Trình xem đầy đủ (Thanh công cụ Trình xem, phần gắn Trình xem, 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à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 nó, vì vậy hãy gắn nó vào một nhánh riêng bằng 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 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 khởi động với Unable to resolve service for type 'IDistributedCache'. Đã đăng ký Doconut trong quá trình Cài đặt? Bỏ qua và chuyển đến 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 ASP.NET session state

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ữ cho bốn cài đặt đường dẫn được đồ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 host ánh xạ /doconut, vì vậy client sử dụng BasePath: 'doconut'. ResourcesPath phục vụ 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'. Viết cả hai không có dấu gạch chéo đầu: Trình xem sẽ tự thêm một, 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 host có tên doconut, và Trình xem sẽ thất bại với "Trình xử lý Trình xem không thể được truy cập".

Thêm Trình xem vào một trang

Trình xem 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 Trình xem 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 Trình xem 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, 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 các tài nguyên Trình xem

Trong một Razor view, dịch vụ Viewer được tiêm sẽ 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 Trình xem:

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 Trình xem đầy đủ, yêu cầu tài nguyên Trình xem và các 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 Trình xem, và một instance docViewer. ReferenceCss và ReferenceScripts bỏ qua tài nguyên của một module tùy chọn khi giấy phép hiện tại không cho phép tính năng đó; Trình xem 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 pseudocode):

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ó dấu '/' ở đầu
    ResPath:    'doconut-res/images',  // không có dấu '/' ở đầu
    onViewerReady: function () {
        // các trang hiển thị; an toàn để ẩn biểu tượng 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);
    }
});

Kiểu viết hoa 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 kiểu, 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 đọc như 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 gốc tài nguyên. Khi dùng 'doconut-res', mọi biểu tượng trả về 404: không có glyph 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ị. Dấu gạch chéo đầu sẽ phá vỡ nó tương tự như BasePath.
  • Callbacks là các tùy chọn. onViewerReady, onError và các phần còn lại được đưa vào đối tượng truyền cho docViewer(...). Một hàm toàn cục có tên giống với viewer, chẳng hạn như ctlDoc_ViewerReady, sẽ không bao giờ được gọi.
  • Giữ lại viewer, 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ấn nút thanh công cụ đầu tiên.

Lắp rá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ó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 lõi
Thanh công cụ ViewerBắt buộc cho một trang hoàn chỉnhMarkup 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 host, nó được cài đặt cùng với Viewer và không bao giờ nên đượ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à các quy tắc ủy quyền của nó nằm dưới sự kiểm soát của ứng dụng của bạn trong khi mọi nút đều đ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. Hiển thị thanh công cụ Viewer, các mount Search/Annotation, 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ữ lại objViewer kết quả.
  6. Khởi tạo mỗi Ribbon Search hoặc Annotation có giấy phép.
  7. Gọi attach(objViewer) trên mỗi Ribbon.
  8. Mở tài liệu và giữ lại 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ài đặt retry 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, do đó hàm plug‑in jQuery của nó 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 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 Annotation để giữ khởi động tối thiểu. Xem Search và Annotations để biết cấu hình đầy đủ cho từng tính năng, hoặc Custom Themes để tạo kiểu hoặc thay thế thanh công cụ Viewer do host sở hữu.

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à truyề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ở 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 đã 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 một cách 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à:

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ỉ 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 Troubleshooting.

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 đều có dấu nước đánh giá. Xem License Setup để 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?