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 bộ điều khiển MVC, các trang Web Forms và các handler. Nó là một dịch vụ transient được tạo bởi DoconutHost.Initialize; giải quyết nó ở nơi bạn sử dụng nó:

csharp
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() cũng hoạt động sau khi DoconutHost.Initialize đã chạy — nó giải quyết cùng các dịch vụ — điều này giữ cho mã được chuyển từ gói classic vẫn biên dịch. Trước Initialize, nó sẽ ném InvalidOperationException.

Viewer không giữ trạng thái tài liệu 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 với nó, vì vậy việc giải phóng một Viewer không bao giờ có thể đóng một tài liệu đang mở (xem Cách Viewer Hoạt Động).

OpenDocumentAsync

Mở một tài liệu và trả về token phiên mà widget sử dụng cho mọi yêu cầu sau này. Khi UnsafeMode là false (mặc định), token được cấp cho phiên ASP.NET của yêu cầu hiện tại — gọi nó từ một yêu cầu có trạng thái phiên (xem Phiên & Bảo mật).

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à một 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ó sẽ chọ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 theo đị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 (HttpPostedFileBase trong MVC; HttpPostedFile trong Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

Các ngoại lệ cần xử lý:

  • LicenseException — một giấy phép đã được tìm thấy nhưng bị từ chối (tin nhắn chứa lý do), hoặc định dạng cần một khả năng plugin mà giấy phép không cấp.
  • FormatNotSupportedException — không có viewer nào xử lý phần mở rộng của tệp.
  • InvalidDataException — nội dung bị hỏng hoặc không khớp với phần mở rộng của nó.

OpenDocument (synchronous)

Cho code-behind của Web Forms và các mã khác không sử dụng các trang bất đồng bộ:

text
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

Mỗi phương thức trả về token và cũng lưu nó trong viewer.Token. fileName phải mang phần mở rộng đúng. Những wrapper này an toàn để gọi từ một trang Web Forms: đường mở không bao giờ tiếp tục trên ngữ cảnh yêu cầu ASP.NET, vì vậy việc chờ nó không thể gây deadlock. Điều này không đúng với mọi API bất đồng bộ Doconut — xem phần Web Forms của Plugin Chuyển Đổi.

CloseDocument

text
void CloseDocument(string token)

Xóa phiên (giải phóng engine tài liệu ngay lập tức), xóa quyền cấp token khỏi phiên ASP.NET của yêu cầu hiện tại, và thu hồi token. 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.

Session queries

Thành viênGiá trị trả về
int GetPageCount(string token)Tổng số trang của tài liệu đang mở
(int Width, int Height) GetPageDimensions(string token, int page = 1)Kích thước trang được render mặc định ở mức phóng đại 100% — không gian tọa độ cho các chú thích được xây dựng trong mã
IReadOnlyList<string> GetWorksheetNames(string token)Các worksheet được render của bảng tính, theo thứ tự workbook; để trống cho các tài liệu khác

Mỗi trường hợp sẽ 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.

DocOptions

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ệ (được sao chép vào cấu hình định dạng tự động).
stringWatermark""Văn bản watermark tùy chỉnh được vẽ trên các trang đã render — xem bên dưới.
intTimeOut60Thời gian hết hạn trượt của phiên, tính bằng phút.
stringBrowserId""Web farms: trình duyệt mà vé đã ký được gắn vào. Đặt nó bằng DoconutFarmBinding.EnsureBrowserId (xem Phiên & Bảo mật).
stringUserId""Web farms: người dùng đã đăng nhập mà vé được gắn vào, từ DoconutFarmBinding.ResolveUserId.
intImageResolution0Lỗi thời. Thay vào đó, đặt ImageResolution trên cấu hình định dạng.
boolIsSecuredtrueDành riêng; không được thực thi. Kiểm soát truy cập là DoconutOptions.UnsafeMode.
boolIsWebFarm / string WebFarmPathfalse / ""Được giữ lại cho mã được di chuyển từ gói classic. Chúng không bật chế độ farm — AddDoconutDistributed làm như vậy.
boolEditModefalseDành riêng cho trình chỉnh sửa được phân phối riêng; để false.

Custom watermark

DocOptions.Watermark nhận 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 all-corners:

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 all-corners tùy chọn. Nếu không có, vị trí mặc định sẽ được sử dụng.
TextConfidentialVăn bản được vẽ trên mỗi trang. Nó không được để trống.
ColorRedMàu được đặt tên.
FontSize24Kích thước phông chữ; đầu vào số không hợp lệ sẽ quay lại mặc định.
FontNameVerdanaHọ phông chữ. Nó phải được cài đặt trên máy chủ — Windows Server có ít phông hơn máy để bàn.
Opacity800 đến 255. Nó phải được phân tích.
Angle-45Xoay 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 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 văn bản Invalid Watermark hiển thị thay vì biến mất im lặng.

License decision

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
Giấy phép Tạm thời/Demo đang hoạt độngKhôngTrang sạch
Giấy phép Tạm thời/Demo đang hoạt độngCóWatermark tùy chỉnh
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 đánh giá; giá trị tùy chỉnh không thay thế nó

Quyết định tương tự áp dụng cho các trang được phục vụ và cho việc xuất chú thích. Watermark tùy chỉnh là tính năng của ứng dụng có giấy phép, không phải cách để thay thế watermark đánh giá.

API chú thích

Tải và xuất chú thích phía máy chủ. Hướng dẫn chi tiết có trong Chú thích.

MemberPurpose
AnnotationManager GetAnnotationManager(string token)Trình quản lý ràng buộc 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ý độc lập 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 phong bì đã mã hoá đượ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 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 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 không tồn tại); 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 với chú thích được nhúng

Siêu dữ liệu DICOM

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

Trong gói này nó luôn trả về null, và yêu cầu siêu dữ liệu của widget trả lời 501 Not Implemented: việc đọc các thẻ DICOM không khả dụng trên .NET Framework. Kết xuất DICOM — các trang, khung và hoạt ảnh — hoạt động. Xem Plugin DICOM.

Trợ giúp tài nguyên — ReferenceCss / ReferenceScripts

Phát ra các thẻ <link> và <script> cho các tài nguyên mà mô-đun tài nguyên cung cấp dưới DoconutOptions.ResourcesPath, theo thứ tự phụ thuộc. Các tệp cho các tính năng bị giới hạn bằng giấy phép (Search, Annotation) chỉ được phát ra khi giấy phép cho phép.

text
string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // trạng thái giấy phép, để bảo vệ ribbon init code
bool IsAnnotationEnabled { get; }

CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (được giới hạn tìm kiếm), IncludeAnnotationCss (được giới hạn chú thích).

ScriptConfig flags: IncludeJQuery (cần thiết cho tất cả các phần còn lại), IncludeBootstrap, IncludeViewerScripts (các script trình xem cốt lõi), IncludeSearchScripts và IncludeSearchBar (được giới hạn tìm kiếm), IncludeAnnotationScripts và IncludeAnnotationBar (được giới hạn chú thích), EmitFeatureFlags (mặc định true: cũng ghi một script window.Doconut.features = { search, annotation, editor } nội tuyến; đặt nó thành false dưới một Content-Security-Policy chặn script nội tuyến).

Cả hai trả về HTML: viết chúng bằng @Html.Raw(...) trong MVC 5 (tạo chúng trong controller — các view không có @inject) hoặc <%= %> trong Web Forms. Bắt đầu nhanh hiển thị cả hai.

Trình hiển thị

text
string RenderViewer(string elementId, string token, ViewerConfig? config = null)

Trả về một khối <script> khởi tạo widget trên phần tử có id elementId và hiển thị tài liệu: docViewer({...}) được xây dựng từ ViewerConfig (mặc định: BasePath: '/', ResPath: 'doconut-res/images'), sau đó .View(token). Viết nó sau các script của viewer. Script được tạo không giữ tham chiếu tới đối tượng viewer, vì vậy một trang có thanh công cụ riêng nên khởi tạo widget bằng tay. Xem Cấu hình Viewer.

Môi trường web farm

string? AccessToken chứa vé đã ký được cấp bởi lần mở gần nhất khi chế độ phân tán đang hoạt động và UnsafeMode là false; nó là null trên một máy chủ đơn. Gửi nó tới widget cùng với token: objViewer.View(token, accessToken).

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