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, controller MVC, component Blazor, hoặc minimal APIs. Nó được sealed, đăng ký như một dịch vụ transient bởi AddDoconut(), và được giải quyết thông qua constructor injection — không bao giờ tạo trực tiếp.

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 cache phiên, vì vậy việc giải phóng dịch vụ sẽ không bao giờ hủy một tài liệu đang mở (xem Các khái niệm cốt lõi → Cách hoạt động của Viewer).

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.

// 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 mà 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.
• 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ó.

CloseDocument

void CloseDocument(string token)

Xóa phiên khỏi 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 quá trình dọn dẹp — nhưng được khuyến nghị cho tài liệu lớn.

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.

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 cũng cung cấp các thuộc tính chuyên biệt được cố ý đặt ngoài luồng xem đơn máy bình thường:

Watermark tùy chỉnh

DocOptions.Watermark sử dụng sáu trường ngăn cách bằng dấu ~. Một ^ đầ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
    });

Trình phân tích mong đợi đúng sáu trường sau ^ tùy chọn. Định nghĩa không hợp lệ sẽ được thay thế bằng fallback Invalid Watermark có thể nhìn thấy của SDK thay vì biến mất im lặng.

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 động được dán dấu từng khung. Do đó, watermark tùy chỉnh là tính năng ứng dụng có giấy phép, không phải cách để thay thế hoặc ẩn watermark đá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; giao diện là:

Siêu dữ liệu DICOM

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

Trả về siêu dữ liệu thẻ DICOM cho các phiên được mở qua plugin DICOM; null cho tài liệu không phải DICOM.

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 đúng thứ tự phụ thuộc. Các bundle 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 khi giấy phép cho phép, giữ giao diện người dùng client nhất quán với hành vi server.

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

Cờ CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (được bật khi có tính năng tìm kiếm), IncludeAnnotationCss (được bật khi có tính năng chú thích).

Cờ ScriptConfig: IncludeJQuery (bắt buộc cho tất cả các cờ khác), IncludeBootstrap, IncludeViewerScripts (cốt lõi: docViewer.js + splitter + links), IncludeSearchScripts và IncludeSearchBar (được bật khi có tính năng tìm kiếm), IncludeAnnotationScripts và IncludeAnnotationBar (được bật khi có tính năng chú thích).

@inject Doconut.Viewer Viewer

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