Görüntüleyici

Ana belge görüntüleyici sınıfı

Viewer (ad alanı Doconut) Razor sayfalarından, MVC denetleyicilerinden, Blazor bileşenlerinden veya minimal API'lerden belgeleri açmak için genel giriş noktasıdır. sealed, transient hizmet olarak AddDoconut() tarafından kaydedilir ve yapıcı enjeksiyonu yoluyla çözülür — asla doğrudan oluşturmayın.

Viewer hiçbir istek başına durum tutmaz ve kasıtlı olarak implement etmez IDisposable: belge oturumları oturum önbelleğinde bağımsız olarak yaşar, bu yüzden hizmeti yok etmek açık bir belgeyi asla kapatamaz (bkz. Temel Kavramlar → Görüntüleyicinin Nasıl Çalıştığı).

OpenDocumentAsync

Bir belge açar ve istemci widget'ının sonraki tüm isteklerde kullandığı oturum belirtecini döndürür.

Aşırı YüklemeNe zaman kullanılmalı
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Diskten otomatik format algılaması ve formatın varsayılan yapılandırmasıyla açma
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)Her format için render seçeneklerine ihtiyacınız var (PdfConfig, WordConfig, …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)Belge disk üzerinde bir dosya değil (yükleme, veritabanı, blob). fileInfo doğru uzantıyı taşımalıdır — bu, format algılamasını yönlendirir
csharp
// Basit aç
string token = await viewer.OpenDocumentAsync(path);

// Biçim başına yapılandırma ve seçeneklerle
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Yüklemeden
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Ele alınması gereken istisnalar:

  • LicenseException — bulunan bir lisans reddedilir (mesaj reddetme nedenini taşır) veya format artık sağlanmayan bir eklenti yeteneğine ihtiyaç duyar. Reddetme mesajı olmadan takvim süresi dolması, hata fırlatmak yerine su işaretiyle render'a düşer.
  • FormatNotSupportedException — Document format '<extension>' is not supported.
  • InvalidDataException — dosya içeriği bozuk veya uzantısıyla eşleşmiyor.

CloseDocument

text
void CloseDocument(string token)

Oturumu önbellekten kaldırır (belge motorunu hemen yok eder), güvenlik işaretçisini siler ve erişim iznini iptal eder. İsteğe bağlı — kayan süresi dolma aynı temizlik işlemini yapar — ancak büyük belgeler için önerilir.

GetPageCount

text
int GetPageCount(string token)

Açık oturumun toplam sayfa sayısı. Belirteç bilinmiyorsa veya süresi dolmuşsa InvalidOperationException (Document session not found. Please re-open document.) fırlatır ve boş bir belirteç için ArgumentException fırlatır.

GetPageDimensions

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

Belgenin %100 yakınlaştırmadaki varsayılan render edilmiş sayfa boyutu — kod içinde oluşturulan açıklamalar için koordinat alanı. Uyumluluk için page kabul edilir; sonuç belge varsayılanıdır. Belirteç bilinmiyorsa veya süresi dolmuşsa InvalidOperationException (Document session not found. Please re-open document.) fırlatır ve boş bir belirteç için ArgumentException fırlatır.

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

Açık bir elektronik tablonun çalışma sayfası adlarını, çalışma kitabı sırasına göre döndürür; açık belge bir elektronik tablo değilse boş bir liste döner.

Yalnızca render edilmiş çalışma sayfaları listelenir: gizli ve boş çalışma sayfaları dışlanır ve ExcelConfig.SheetNames render'ı kısıtladığında yalnızca o çalışma sayfaları görünür. Bir çalışma sayfası her zaman tek bir sayfa değildir — çok büyük bir sayfa birden fazla sayfaya render edilir. Belirteç bilinmiyorsa veya süresi dolmuşsa InvalidOperationException (Document session not found. Please re-open document.) fırlatır ve boş bir belirteç için ArgumentException fırlatır.

26.9.0'da eklendi.

Yetenek bayrakları

ÜyeAnlam
bool IsSearchEnabledMevcut lisans Search verir
bool IsAnnotationEnabledMevcut lisans Annotation verir

Bunları bir Razor görünümünde, yalnızca sunucu gerçekten hizmet verecekse lisanslı bir Şerit render etmek için kullanın — bkz. Hızlı Başlangıç.

DocOptions

Açılış başına, format bağımsız seçenekler (namespace Doconut):

TürÖzellikVarsayılanAçıklama
stringPassword""Korunan belgeler için şifre (format yapılandırmasına otomatik olarak kopyalanır).
intImageResolution0Eski. Yalnızca uyumluluk için tutulur — bunun yerine format yapılandırmasında ImageResolution ayarlayın.
stringWatermark""Render edilen sayfalara çizilen özel filigran metni. Biçim dizesi: "^Text~Color~FontSize~FontName~Opacity~Angle", ör. "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Dakika cinsinden oturum kayma süresi.
boolIsSecuredtrueŞu anda uygulanmıyor — ayrılmış. Token bağlama, DoconutOptions.UnsafeMode tarafından küresel olarak kontrol edilir (bkz. Core Concepts → Sessions & Security).

Sınıf ayrıca, normal tek‑sunucu görüntüleme akışının dışında kasıtlı olarak bulunan özel özellikler sunar:

TürÖzellikVarsayılanAçıklama
boolIsWebFarmfalseEski — etkisi yok. Belgeyi DistributedDocumentPublisher.PublishAsync (veya IDistributedPublishQueue.EnqueueAsync) ile yayınlayın ve bunun yerine FileShareConfig.RootPath ayarlayın.
stringWebFarmPath""Eski — etkisi yok. Bunun yerine FileShareConfig.RootPath kullanın.
boolEditModefalseAyrı dağıtılan Editor iş akışı için ayrılmıştır; standart görüntüleyici için false bırakın.

Özel filigran

DocOptions.Watermark altı tilde‑ayırıcı alan kullanır. İsteğe bağlı bir ön ^ tüm köşe düzenini talep eder:

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
    });
AlanÖrnekAnlam
Ön ^^İsteğe bağlı tüm köşe düzeni. Olmazsa, normal filigran konumu kullanılır.
MetinConfidentialHer sayfada render edilen metin. Boş olmamalıdır.
RenkRedÇizim katmanı tarafından anlaşılan adlandırılmış renk.
FontSize24Yazı tipi boyutu; geçersiz sayısal giriş renderlayıcı varsayılanına geri döner.
FontNameVerdanaİstenen yazı tipi ailesi. Dağıtım ortamına kurulu olduğundan emin olun.
Opacity800 ile 255 arasında bir byte değeri. Başarıyla ayrıştırılmalıdır.
Angle-45Derece cinsinden dönüş açısı; geçersiz sayısal giriş varsayılana geri döner.

Ayrıştırıcı, isteğe bağlı ^ sonrasında tam olarak altı alan bekler. Geçersiz bir tanım, sessizce kaybolmak yerine SDK'nın görülebilir Invalid Watermark yedek değeriyle değiştirilir.

Lisans kararı

Lisans durumuSağlanan özel değerRender edilen sonuç
Geçerli ücretli görüntüleyici lisansıHayırTemiz sayfa
Geçerli ücretli görüntüleyici lisansıEvetÖzel filigran
Etkin Geçici/Demo temel görüntüleyiciHayırTemiz temel‑görüntüleyici sayfası
Etkin Geçici/Demo temel görüntüleyiciEvetTemiz temel‑görüntüleyici yolu uygulandığında özel filigran
Eksik, reddedilmiş, süresi dolmuş, yanlış sürüm veya geçersiz‑alan lisansıHerhangi biriUygulama/değerlendirme filigranı; özel değer onu geçersiz kılmaz
Değerlendirme kuralları altında eklenti renderıHerhangi biriDeğerlendirme filigranı

Aynı karar, sunulan sayfa görüntülerine ve açıklama dışa aktarmalarına uygulanır. Hareketli GIF çıktısı kare kare damgalanır. Bu nedenle özel bir filigran, lisanslı bir uygulama özelliğidir, değerlendirme filigranını değiştirmek veya bastırmak için bir yol değildir.

Açıklamalar API'si

Sunucu tarafı açıklama yükleme ve dışa aktarma. Tam kılavuz Guides → Annotations içinde bulunur; yüzey şu şekildedir:

ÜyeAmaç
AnnotationManager GetAnnotationManager(string token)Açık oturumun sayfa boyutlarına bağlı yönetici
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Açık sayfa boyutlarıyla yönetici
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Oturumdan bağımsız yönetici
void LoadAnnotationData(string token, AnnotationManager manager)C#'ta oluşturulan açıklamaları oturuma yükle
void LoadAnnotationData(string token, string annotationData)AnnotationManager.GetAnnotationData() tarafından döndürülen kodlanmış sayfa/Base64 zarfından açıklamaları yükle
void LoadAnnotationXML(string token, XmlDocument annotationXml)XML'den açıklamaları yükle
XmlDocument GetAnnotationXML(string token)Oturumun açıklamalarını XML olarak dışa aktar
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)Açıklamaları içinde barındıran PDF
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)Sayfa başına bir PNG, açıklamaları içinde barındırır, directoryPath'a yazılır (eksikse oluşturulur); yazılan görüntü sayısını döndürür
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)Açıklamaları içinde barındıran sayfa başı PNG'lerin ZIP'i

DICOM meta verileri

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

Bu yöntem API uyumluluğu için mevcuttur, ancak .NET 6 DICOM görüntüleyicisi teknik etiketleri sağlayamaz. DICOM ve DICOM olmayan oturumlar için null döndürür; bir DICOM oturumunda ayrıca platform sınırlamasını açıklayan tek seferlik bir uyarı yazar. Sayfa, çerçeve ve animasyon renderlaması desteklenmeye devam eder.

Kaynak yardımcıları — ReferenceCss / ReferenceScripts

Gömülü kaynakları sunan UseDoconutResources() için <link>/<script> etiketlerini doğru bağımlılık sırasıyla oluşturun. Arama ve açıklama gibi lisans kısıtlamalı özellikler için paketler yalnızca lisans bunları etkinleştirdiğinde oluşturulur, böylece istemci UI'si sunucu davranışıyla tutarlı kalır.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + görüntüleyici + arama + açıklama
string ReferenceScripts(ScriptConfig? config = null)

CssConfig bayrakları: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (arama kısıtlamalı), IncludeAnnotationCss (açıklama kısıtlamalı).

ScriptConfig bayrakları: IncludeJQuery (diğer tümü tarafından gereklidir), IncludeBootstrap, IncludeViewerScripts (çekirdek: docViewer.js + ayırıcı + bağlantılar), IncludeSearchScripts ve IncludeSearchBar (arama kısıtlamalı), IncludeAnnotationScripts ve IncludeAnnotationBar (açıklama kısıtlamalı), EmitFeatureFlags (varsayılan true: ayrıca bir satır içi window.Doconut.features = { search, annotation, editor } betiği yazar; satır içi betiği engelleyen bir Content-Security-Policy altında false olarak ayarlayın).

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

Bu sayfa yardımcı oldu mu?