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 API. Nó được sealed, đăng ký như một dịch vụ transient bởi AddDoconut(), và được giải quyết qua injection trong constructor — 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 Core Concepts → How the Viewer Works).

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 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 việc 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:

Custom watermark

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 toàn 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 yêu cầu chính xác 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 hiển thị của SDK thay vì biến mất im lặng.

License decision

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 watermark từng khung. Do đó watermark tùy chỉnh là tính năng có giấy phép, không phải cách để thay thế hoặc ẩn watermark đánh giá.

Annotations API

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à:

DICOM metadata

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

Phương thức này tồn tại để đồng bộ API, nhưng trình xem DICOM .NET 6 không thể cung cấp các thẻ kỹ thuật. Nó trả về null cho các phiên DICOM và không DICOM; trên 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ợ.

Resource helpers — 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 ra khi giấy phép cho phép, giữ giao diện 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ác cờ CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (có giấy phép tìm kiếm), IncludeAnnotationCss (có giấy phép chú thích).

Các 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ó giấy phép tìm kiếm), IncludeAnnotationScripts và IncludeAnnotationBar (có giấy phép 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 }))