Trình xem

Viewer (namespace Doconut) là điểm vào công cộng để mở tài liệu từ các controller MVC, trang Web Forms và các handler. Nó là một dịch vụ tạm thời được tạo bởi DoconutHost.Initialize; giải quyết nó ở nơi bạn sử dụng nó:

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 cổ điển 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 thực hiện 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 hoạt động của Trình xem).

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

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

// Với cấu hình và tùy chọn cho từng đị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ó trình xem 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 (đồng bộ)

Đối với code-behind Web Forms và các mã khác không sử dụng trang bất đồng bộ:

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.

Đóng tài liệu

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.

Truy vấn phiên

Mỗi phương thức sẽ ném lỗi nếu token không tồn tại hoặc đã hết hạn.

Tùy chọn tài liệu

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):

Watermark tùy chỉnh

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 tất cả các 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 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 văn bản Invalid Watermark hiển thị thay vì biến mất im lặng.

Quyết định giấy phép

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.

Siêu dữ liệu DICOM

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. DICOM kết xuất — các trang, khung và hoạt ảnh — hoạt động. Xem DICOM Plugin.

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 có giấy phép (Search, Annotation) chỉ được phát ra khi giấy phép cho phép chúng.

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 cờ: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

ScriptConfig cờ: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (the core viewer scripts), IncludeSearchScripts và IncludeSearchBar (search-gated), IncludeAnnotationScripts và IncludeAnnotationBar (annotation-gated).

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. Quick Start hiển thị cả hai.

RenderViewer

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 thay vì. Xem ViewerConfig.

Web farm

string? AccessToken chứa vé đã ký được phát hành 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, access).