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 qua tiêm constructor — không bao giờ tạo trực tiếp nó.

Thư viện .NET Standard trước đây đã cung cấp 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ể 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 khách hàng 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ộ.

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 cho từng đị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 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

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

GetPageCount

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 tồn tại hoặc đã hết hạn, và ArgumentException cho token trống.

GetPageDimensions

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 code. 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 tồn tại hoặc đã hết hạn, và ArgumentException cho token trống.

Lấy Tên Trang Tính

text
IReadOnlyList<string> GetWorksheetNames(string token)

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

Chỉ các trang tính đã được render mới được liệt kê: các trang tính ẩn và trống bị loại bỏ, và khi ExcelConfig.SheetNames hạn chế việc render, chỉ những trang tính đó xuất hiện. Một trang tính không luôn luôn là một trang — một trang tính 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.

Tùy chọn Doc

Các tùy chọn độc lập đị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ệ (tự động sao chép vào cấu hình định dạ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 không đượ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 Khái niệm Cốt lõi → Phiên & Bảo mật).

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 chủ bình thường:

KiểuThuộc tínhMặc địnhMô tả
boolIsWebFarmfalseLỗi thời — không có hiệu lực. Xuất bản tài liệu với DistributedDocumentPublisher.PublishAsync (hoặc IDistributedPublishQueue.EnqueueAsync) và thay vào đó đặt FileShareConfig.RootPath. Lưu ý cách viết — thư viện trước đây viết nó là IsWebfarm.
stringWebFarmPath""Lỗi thời — không có hiệu lực. Sử dụng FileShareConfig.RootPath, như mô tả trong Triển khai phân tán. Trước đây viết là WebfarmPath.
boolEditModefalseDành riêng cho quy trình chỉnh sửa được phân phối riêng; để lại 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 ^ tùy chọn ở đầu yêu cầu bố cục toàn 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
Tiền tố ^^Bố cục toàn góc tùy chọn. Nếu không có, vị trí watermark bình thường sẽ được sử dụng.
Văn bảnConfidentialVăn bản được render trên mỗi trang. Không được để trống.
MàuRedMàu được đặt tên mà lớp vẽ hiểu.
KíchThướcPhông24Kích thước phông chữ; nếu nhập số không hợp lệ sẽ quay lại mặc định của renderer.
TênPhôngVerdanaHọ phông chữ yêu cầu. Đảm bảo nó đã được cài đặt trong môi trường triển khai.
ĐộTrongSuốt80Giá trị byte từ 0 đến 255. Phải phân tích thành công.
Góc-45Góc quay tính bằng độ; nếu nhập số không hợp lệ sẽ quay lại mặc định.

Trình phân tích mong đợi 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 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ả hiển thị
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óHình mờ tùy chỉnh
Trình xem cơ bản tạm thời/đánh demo đang hoạt độngKhôngTrang trình xem cơ bản sạch
Trình xem cơ bản tạm thời/đánh demo đang hoạt độngCóHình mờ tùy chỉnh khi đường dẫn trình xem cơ bản sạch được áp dụng
Giấy phép bị 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ỳHình mờ 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ỳHình mờ đá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 hình. Do đó, hình mờ tùy chỉnh là một tính năng ứng dụng có giấy phép, không phải cách để thay thế hoặc loại bỏ hình mờ đá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 Hướng dẫn → Chú thích; phần tổng quan là:

Thành viênMục đích
AnnotationManager GetAnnotationManager(string token)Quản lý liên kết với kích thước trang của phiên mở
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Quản lý với kích thước trang rõ ràng
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Quản lý không phụ thuộc vào phiên
void LoadAnnotationData(string token, AnnotationManager manager)Tải chú thích được xây dựng bằng C# vào phiên
void LoadAnnotationData(string token, string annotationData)Tải chú thích từ trang đã mã hoá/Base64 envelope được trả về bởi AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Tải chú thích từ XML
XmlDocument GetAnnotationXML(string token)Xuất chú thích của phiên dưới dạng XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF 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, 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 mỗi trang có chú thích được nhúng

Mỗi mục trong số này đều nhận token phiên. Kiểu 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 bên ngoài phiên, nhưng việc tải chúng vẫn yêu cầu token.

siêu dữ liệu DICOM

text
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 bản .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 kết xuất 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ữ 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 (được kiểm soát bởi tìm kiếm), IncludeAnnotationCss (được kiểm soát bởi chú thích).

ScriptConfig cờ: 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 (được kiểm soát bởi tìm kiếm), IncludeAnnotationScripts và IncludeAnnotationBar (được kiểm soát 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 dưới 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 }))

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.

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