Trình xem

Lớp trình xem tài liệu chính

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.

Viewer không giữ trạng thái theo yêu cầu 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 Core Concepts → How the Viewer Works).

OpenDocumentAsync (Mở Tài Liệu Bất Đồng Bộ)

Mở một tài liệu và trả về token phiên mà widget khách hàng sử dụng cho tất cả các yêu cầu tiếp theo.

Quá tảiKhi nào sử dụng
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Mở từ đĩa với phát hiện định dạng tự động và cấu hình mặc định của định dạng
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)Bạn cần các tùy chọn render theo định dạng (PdfConfig, WordConfig, …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)Tài liệu không phải là tệp trên đĩa (tải lên, cơ sở dữ liệu, blob). fileInfo phải mang phần mở rộng đúng — nó quyết định việc phát hiện định dạng
csharp
// 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 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ó dấu nước 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 (Đóng Tài Liệu)

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

GetPageCount (Lấy Số Trang)

text
int GetPageCount(string token)

Tổng số trang của phiên đang mở. Ném InvalidOperationException (Document session not found. Please re-open document.) nếu token không xác định hoặc đã hết hạn, và ArgumentException cho token trống.

GetPageDimensions (Lấy Kích Thước Trang)

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

Kích thước trang mặc định được render của tài liệu ở mức phóng đại 100% — không gian tọa độ cho các chú thích được xây dựng trong mã. page được chấp nhận để tương thích; kết quả là mặc định của tài liệu. Ném InvalidOperationException (Document session not found. Please re-open document.) nếu token không xác định hoặc đã hết hạn, và ArgumentException cho token trống.

GetWorksheetNames (Lấy Tên Worksheet)

text
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 InvalidOperationException (Document session not found. Please re-open document.) nếu token không xác định hoặc đã hết hạn, và ArgumentException cho token trống.

Được thêm trong 26.9.0.

Cờ khả năng

Thành viênÝ nghĩa
bool IsSearchEnabledGiấy phép hiện tại cấp Search
bool IsAnnotationEnabledGiấy phép hiện tại cấp Annotation

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 không phụ thuộc vào định dạng, áp dụng cho mỗi lần mở (namespace Doconut):

KiểuThuộc tínhMặc địnhMô tả
stringPassword""Mật khẩu cho tài liệu được bảo vệ (được sao chép vào cấu hình định dạng tự động).
intImageResolution0Lỗi thời. Chỉ giữ lại để tương thích — thay vào đó đặt ImageResolution trên cấu hình định dạng.
stringWatermark""Văn bản watermark tùy chỉnh được vẽ trên các trang đã render. Chuỗi định dạng: "^Text~Color~FontSize~FontName~Opacity~Angle", ví dụ "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Thời gian hết hạn trượt của phiên tính bằng phút.
boolIsSecuredtrueHiện chưa được thực thi — dành riêng. Ràng buộc token được kiểm soát toàn cầu bởi DoconutOptions.UnsafeMode (xem Các khái niệm cốt lõi → Phiên & Bảo mật).

Lớp này cũng cung cấp các thuộc tính chuyên biệt được đặt cố ý ngoài luồng xem đơn máy chủ bình thường:

KiểuThuộc tínhMặc địnhMô tả
boolIsWebFarmfalseLỗi thời — không có tác dụng. Xuất bản tài liệu với DistributedDocumentPublisher.PublishAsync (hoặc IDistributedPublishQueue.EnqueueAsync) và thay vào đó đặt FileShareConfig.RootPath.
stringWebFarmPath""Lỗi thời — không có tác dụng. Sử dụng FileShareConfig.RootPath thay thế.
boolEditModefalseDành riêng cho quy trình làm việc Editor được phân phối riêng; để false cho trình xem tiêu chuẩn.

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 tất cả các góc:

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
TrườngVí dụÝ nghĩa
Leading ^^Bố cục tất cả các góc tùy chọn. Nếu không có, sẽ sử dụng vị trí watermark bình thường.
TextConfidentialVăn bản được render trên mỗi trang. Không được để trống.
ColorRedMàu được đặt tên mà lớp vẽ hiểu.
FontSize24Kích thước phông; đầu vào số không hợp lệ sẽ quay lại mặc định của renderer.
FontNameVerdanaHọ phông được yêu cầu. Đảm bảo nó được cài đặt trong môi trường triển khai.
Opacity80Giá trị byte từ 0 đến 255. Phải phân tích thành công.
Angle-45Góc quay tính bằng độ; đầu vào số không hợp lệ sẽ quay lại mặc định.

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

Trạng thái giấy phépGiá trị tùy chỉnh được cung cấpKết quả render
Giấy phép xem trả phí hợp lệKhôngTrang sạch
Giấy phép xem trả phí hợp lệCóWatermark tùy chỉnh
Trình xem cơ bản tạm thời/đánh giá đang hoạt độngKhôngTrang cơ bản trình xem sạch
Trình xem cơ bản tạm thời/đánh giá đang hoạt độngCóWatermark tùy chỉnh khi áp dụng đường dẫn trình xem cơ bản sạch
Giấy phép thiếu, bị từ chối, hết hạn, phiên bản sai, hoặc miền không hợp lệBất kỳWatermark thực thi/đánh giá; giá trị tùy chỉnh không ghi đè lên nó
Kết xuất plugin theo quy tắc đánh giáBất kỳWatermark đánh giá

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 đủ có trong Guides → Annotations; giao diện là:

Thành viênMục đích
AnnotationManager GetAnnotationManager(string token)Trình quản lý gắn với kích thước trang của phiên đang mở
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Trình quản lý với kích thước trang rõ ràng
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Trình quản lý độc lập với phiên
void LoadAnnotationData(string token, AnnotationManager manager)Tải các chú thích được xây dựng bằng C# vào phiên
void LoadAnnotationData(string token, string annotationData)Tải các chú thích từ trang đã mã hoá / phong bì Base64 được trả về bởi AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Tải các chú thích từ XML
XmlDocument GetAnnotationXML(string token)Xuất các chú thích của phiên dưới dạng XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF với các chú thích được nhúng
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)Một PNG cho mỗi trang, các chú thích được nhúng, ghi vào directoryPath (tạo nếu thiếu); trả về số lượng hình ảnh đã ghi
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ZIP các PNG theo trang có các chú thích được nhúng

Siêu dữ liệu DICOM

text
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 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 của 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 đúng thứ tự phụ thuộc. Các gói cho các tính năng bị giới hạn bằng 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 phía client nhất quán với hành vi phía server.

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

CssConfig cờ: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (bị giới hạn bởi tìm kiếm), IncludeAnnotationCss (bị giới hạn bởi chú thích).

ScriptConfig cờ: IncludeJQuery (được yêu cầu bởi tất cả các cờ khác), IncludeBootstrap, IncludeViewerScripts (cốt lõi: docViewer.js + splitter + links), IncludeSearchScripts và IncludeSearchBar (bị giới hạn bởi tìm kiếm), IncludeAnnotationScripts và IncludeAnnotationBar (bị giới hạn bởi chú thích), EmitFeatureFlags (mặc định true: cũng ghi một script inline window.Doconut.features = { search, annotation, editor }; đặt nó thành false trong một Content-Security-Policy chặn script inline).

html
@inject Doconut.Viewer Viewer

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

Trang này có hữu ích không?