Trình xem

Viewer (namespace Doconut) là điểm vào công cộng để mở tài liệu từ các trang Razor, bộ điều khiển MVC, thành phần Blazor, hoặc API tối thiểu. Nó được sealed, đăng ký như một dịch vụ transient bởi AddDoconut(), và được giải quyết thông qua tiêm constructor — không bao giờ tạo nó trực tiếp.

Thư viện .NET Standard trước đây đã công khai một constructor công cộng nhận bộ nhớ cache, bộ truy cập ngữ cảnh HTTP, và một hoặc nhiều đường dẫn giấy phép. Constructor đó đã bị loại bỏ; đồ thị dịch vụ cung cấp các phụ thuộc đó.

Viewer không giữ trạng thái per-request và cố ý không triển khai IDisposable: các phiên tài liệu tồn tại độc lập trong bộ nhớ cache phiên, vì vậy việc giải phóng dịch vụ không bao giờ có thể đóng một tài liệu đang mở (xem Khái niệm cốt lõi → Cách hoạt động của Viewer).

Mở tài liệu bất đồng bộ (OpenDocumentAsync)

Mở một tài liệu và trả về token phiên mà widget client sử dụng cho tất cả các yêu cầu tiếp theo. Mỗi lần mở đều bất đồng bộ — không có OpenDocument đồng bộ.

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Các ngoại lệ cần xử lý:

• LicenseException — một giấy phép được tìm thấy bị từ chối (tin nhắn chứa lý do từ chối), hoặc định dạng cần một khả năng plugin không còn được cấp. Hết hạn lịch mà không có tin nhắn từ chối sẽ chuyển sang render có watermark thay vì ném ngoại lệ.
• FormatNotSupportedException — Document format '<extension>' is not supported. — Định dạng tài liệu '' không được hỗ trợ.
• InvalidDataException — nội dung tệp bị hỏng hoặc không khớp với phần mở rộng của nó.

Đóng tài liệu (CloseDocument)

void CloseDocument(string token)

Xóa phiên khỏi bộ nhớ cache (giải phóng engine tài liệu ngay lập tức), xóa dấu bảo mật, và thu hồi quyền truy cập. Tùy chọn — thời gian hết hạn trượt thực hiện cùng một việc dọn dẹp — nhưng được khuyến nghị cho tài liệu lớn.

Lấy số trang (GetPageCount)

int GetPageCount(string token)

Tổng số trang của phiên đang mở. Ném ngoại lệ nếu token không tồn tại hoặc đã hết hạn.

Cờ khả năng

Sử dụng chúng trong Razor view để hiển thị Ribbon có giấy phép chỉ khi máy chủ thực sự phục vụ nó — xem Bắt đầu nhanh.

Tùy chọn tài liệu (DocOptions)

Các tùy chọn không phụ thuộc vào định dạng, áp dụng cho mỗi lần mở (namespace Doconut):

Lớp này cũng cung cấp các thuộc tính chuyên biệt nằm ngoài luồng xem bình thường trên một máy chủ duy nhất:

Đánh dấu tùy chỉnh

DocOptions.Watermark sử dụng sáu trường được ngăn cách bằng dấu ~. Một dấu ^ đầu tùy chọn yêu cầu bố cục ở mọi góc:

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

Bộ phân tích cú pháp yêu cầu đúng sáu trường sau dấu ^ tùy chọn. Định nghĩa không hợp lệ sẽ bị thay thế bằng giá trị dự phòng Invalid Watermark của SDK thay vì biến mất một cách âm thầm.

Quyết định giấy phép

Quyết định tương tự được áp dụng cho các hình ảnh trang được phục vụ và xuất chú thích. Đầu ra GIF hoạt hình được dán dấu từng khung. Do đó, dấu nước tùy chỉnh là một tính năng có giấy phép, không phải cách để thay thế hoặc ẩn dấu nước đánh giá.

API chú thích

Tải và xuất chú thích phía máy chủ. Hướng dẫn đầy đủ nằm trong Guides → Annotations; phần tổng quan như sau:

Mỗi phương thức trong số này đều nhận token phiên. Hình thức GetAnnotationManager(pageWidth, pageHeight) không cần phiên của thư viện trước vẫn tồn tại để xây dựng chú thích ngoài một phiên, nhưng việc tải chúng vẫn yêu cầu token.

siêu dữ liệu DICOM

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

Phương thức này tồn tại để đồng bộ API, nhưng gói này không thể cung cấp các thẻ DICOM kỹ thuật: bộ đọc siêu dữ liệu chỉ có bản dựng .NET 8. Nó trả về null cho các phiên DICOM và không DICOM; trong một phiên DICOM nó cũng ghi một cảnh báo một lần giải thích giới hạn nền tảng. Việc render trang, khung và hoạt hình vẫn được hỗ trợ.

Trợ giúp tài nguyên — ReferenceCss / ReferenceScripts

Phát ra các thẻ <link>/<script> cho các tài nguyên nhúng được phục vụ bởi UseDoconutResources(), theo thứ tự phụ thuộc đúng. Các gói cho các tính năng có giấy phép như tìm kiếm và chú thích chỉ được phát ra khi giấy phép cho phép, giúp giao diện người dùng phía client nhất quán với hành vi phía server.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

Các cờ CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

Các cờ ScriptConfig: IncludeJQuery (cần thiết cho tất cả các cờ khác), IncludeBootstrap, IncludeViewerScripts (cốt lõi: docViewer.js + splitter + links), IncludeSearchScripts và IncludeSearchBar (search-gated), IncludeAnnotationScripts và IncludeAnnotationBar (annotation-gated).

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

Các trợ giúp này là cách được hỗ trợ để cung cấp các tài nguyên cho trình duyệt. Các ứng dụng đã sao chép docViewer.js, documentLinks.js và docViewer.UI.js vào wwwroot nên xóa các bản sao đó sau khi trang được render từ các thẻ đã phát ra.