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 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 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.

Phiên bảnKhi nào sử dụng
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Mở từ đĩa với việc tự động phát hiện định dạ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 một 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 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

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

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

Trả về danh sách tên worksheet của một bảng tính đang mở, theo thứ tự workbook, hoặc một danh sách rỗng khi tài liệu đang 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à trố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.

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. Giữ lại chỉ để 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. Phát hành 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ó hiệu lực. 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; để 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
Leading ^^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.
TextConfidentialVăn bản được render trên mỗi trang. Nó không được để trống.
ColorRedMàu được đặt tên mà lớp vẽ hiểu.
FontSize24Kích thước phông chữ; đầu vào số không hợp lệ sẽ quay lại mặc định của bộ render.
FontNameVerdanaHọ phông chữ đượ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. Nó phải được 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.

Bộ phân tích cú pháp 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 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 trình xem cơ bản sạch
Trình xem cơ bản tạm thời/đánh giá đang hoạt độngCóWatermark tùy chỉnh khi đường dẫn trình xem cơ bản sạch được áp dụng
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 Ghi chú

Tải và xuất ghi 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 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ý không phụ thuộc vào phiên
void LoadAnnotationData(string token, AnnotationManager manager)Tải các ghi chú được xây dựng bằng C# vào phiên
void LoadAnnotationData(string token, string annotationData)Tải các ghi chú từ envelope trang đã mã hoá/Base64 được trả về bởi AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Tải các ghi chú từ XML
XmlDocument GetAnnotationXML(string token)Xuất các ghi 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 ghi 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 ghi 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ó ghi chú được nhúng

Siêu dữ liệu DICOM

text
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 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à ghi 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 flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (bị giới hạn bởi tìm kiếm), IncludeAnnotationCss (bị giới hạn bởi ghi chú).

ScriptConfig flags: 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 (bị giới hạn bởi tìm kiếm), IncludeAnnotationScripts và IncludeAnnotationBar (bị giới hạn bởi ghi chú), EmitFeatureFlags (mặc định true: cũng ghi một script inline window.Doconut.features = { search, annotation, editor }; đặt 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?