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ự 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, trình 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 nào 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ể 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. Mỗi lần mở đều bất đồng bộ — không có OpenDocument đồng bộ.

// Mở đơn giản
string token = await viewer.OpenDocumentAsync(path);

// Với cấu hình và tùy chọn cho mỗi định dạng
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Từ một tải lên
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 khả năng plugin mà hiện không đượ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 lỗi.
• 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 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 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 lỗi nếu token không xác định hoặc đã hết hạn.

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

Trả về tên các worksheet của một bảng tính đang mở, theo thứ tự workbook, hoặc danh sách rỗng khi tài liệu mở không phải là bảng tính.

Chỉ các worksheet đã được render mới được liệt kê: các worksheet ẩn và rỗng bị loại bỏ, và khi ExcelConfig.SheetNames hạn chế việc render, chỉ những worksheet đó xuất hiện. Một worksheet không luôn luôn là một trang — một worksheet rất lớn sẽ được render trên nhiều trang. Ném lỗi nếu token không xác định hoặc đã hết hạn.

Thêm trong 26.9.0.

Cờ khả năng

Sử dụng chúng trong một 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.

DocOptions

Các tùy chọn độc lập định 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 được cố ý nằm ngoài luồng xem đơn máy chủ bình thường:

Đánh dấu 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 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 Invalid Watermark dự phòng hiển thị của SDK thay vì biến mất im lặng.

Quyết định cấp 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 đó, đánh dấu 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 đánh dấu đánh giá.

API chú thích

Tải và xuất chú thích phía máy chủ. Hướng dẫn đầy đủ có trong Guides → Annotations; giao diện là:

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

Siêu dữ liệu DICOM

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

Phương thức này có mặt để đồng bộ API, nhưng gói này không thể cung cấp các thẻ DICOM kỹ thuật: trình đọc siêu dữ liệu chỉ đi kèm với bản .NET 8. Nó trả về null cho các phiên DICOM và không DICOM; trên 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 hiển thị 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 đúng thứ tự phụ thuộc. 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ữ cho giao diện người dùng phía client nhất quán với hành vi của server.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + trình xem + tìm kiếm + chú thích
string ReferenceScripts(ScriptConfig? config = null)

cờ CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (được kiểm soát bởi tìm kiếm), IncludeAnnotationCss (được kiểm soát bởi chú thích).

cờ ScriptConfig: IncludeJQuery (cần thiết cho tất cả các cái khác), IncludeBootstrap, IncludeViewerScripts (cốt lõi: docViewer.js + splitter + links), IncludeSearchScripts và IncludeSearchBar (được kiểm soát bởi tìm kiếm), IncludeAnnotationScripts và IncludeAnnotationBar (được kiểm soát bởi 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 }))

Các trợ giúp này là cách được hỗ trợ để cung cấp 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 hiển thị từ các thẻ đã phát ra.