Prohlížeč

Hlavní třída prohlížeče dokumentů

Viewer (namespace Doconut) je veřejným vstupním bodem pro otevírání dokumentů z Razor stránek, MVC kontrolerů, Blazor komponent nebo minimálních API. Je sealed, registrován jako transient služba pomocí AddDoconut() a získáván prostřednictvím injekce do konstruktoru — nikdy jej nekonstrukujte přímo.

Viewer neobsahuje žádný stav na požadavek a úmyslně neimplementuje IDisposable: relace dokumentů existují nezávisle v cache relací, takže uvolnění služby nikdy nemůže ukončit otevřený dokument (viz Core Concepts → How the Viewer Works).

OpenDocumentAsync

Otevře dokument a vrátí token relace, který klientský widget používá pro všechny následné požadavky.

PřetíženíPoužít když
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Otevření z disku s automatickým rozpoznáním formátu a výchozím nastavením formátu
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)Potřebujete renderovací možnosti pro každý formát (PdfConfig, WordConfig, …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)Dokument není soubor na disku (nahrání, databáze, blob). fileInfo musí nést správnou příponu — řídí rozpoznání formátu
csharp
// Jednoduché otevření
string token = await viewer.OpenDocumentAsync(path);

// S konfigurací a možnostmi pro každý formát
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Z nahrání
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Výjimky, které je třeba ošetřit:

  • LicenseException — nalezená licence je odmítnuta (zpráva nese důvod odmítnutí), nebo formát vyžaduje pluginovou schopnost, která již není udělena. Vypršení kalendáře bez zprávy o odmítnutí vede k renderování s vodoznakem místo vyhození výjimky.
  • FormatNotSupportedException — Document format '<extension>' is not supported.
  • InvalidDataException — obsah souboru je poškozený nebo neodpovídá jeho příponě.

CloseDocument

text
void CloseDocument(string token)

Odstraní relaci z cache (okamžitě uvolní dokumentový engine), smaže bezpečnostní značku a odvolá přístupové oprávnění. Volitelné — klouzavé vypršení provádí stejný úklid — ale je doporučeno pro velké dokumenty.

GetPageCount

text
int GetPageCount(string token)

Celkový počet stránek otevřené relace. Vyhodí InvalidOperationException (Document session not found. Please re-open document.), pokud je token neznámý nebo vypršel, a ArgumentException pro prázdný token.

GetPageDimensions

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

Výchozí velikost vykreslené stránky dokumentu při 100 % zoomu — souřadnicový prostor pro anotace vytvořené v kódu. page je přijímáno pro kompatibilitu; výsledek je výchozí nastavení dokumentu. Vyhodí InvalidOperationException (Document session not found. Please re-open document.), pokud je token neznámý nebo vypršel, a ArgumentException pro prázdný token.

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

Vrací názvy listů otevřené tabulky, v pořadí sešitu, nebo prázdný seznam, pokud otevřený dokument není tabulka.

Jsou uvedeny pouze vykreslené listy: skryté a prázdné listy jsou vyloučeny, a když ExcelConfig.SheetNames omezuje vykreslování, objeví se jen tyto listy. List není vždy jedna stránka — velmi velký list je vykreslen přes několik stránek. Vyhodí InvalidOperationException (Document session not found. Please re-open document.), pokud je token neznámý nebo vypršel, a ArgumentException pro prázdný token.

Přidáno ve verzi 26.9.0.

Příznaky schopností

ČlenVýznam
bool IsSearchEnabledAktuální licence uděluje Search
bool IsAnnotationEnabledAktuální licence uděluje Annotation

Použijte je v Razor pohledu k vykreslení licencovaného Ribbonu pouze tehdy, když server jej skutečně poskytne — viz Rychlý start.

DocOptions

Možnosti nezávislé na formátu, platné pro každé otevření (namespace Doconut):

TypVlastnostVýchozíPopis
stringPassword""Heslo pro chráněné dokumenty (automaticky zkopírováno do konfigurace formátu).
intImageResolution0Zastaralé. Uchováváno pouze pro kompatibilitu — místo toho nastavte ImageResolution v konfiguraci formátu.
stringWatermark""Vlastní text vodoznaku vykreslený na stránkách. Formátovací řetězec: "^Text~Color~FontSize~FontName~Opacity~Angle", např. "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Posuvná expirace relace v minutách.
boolIsSecuredtrueV současnosti nevymahatelné — rezervováno. Vazba tokenu je řízena globálně pomocí DoconutOptions.UnsafeMode (viz Základní koncepty → Relace a zabezpečení).

Třída také poskytuje specializované vlastnosti, které jsou úmyslně mimo běžný tok zobrazení pro jeden hostitel:

TypVlastnostVýchozíPopis
boolIsWebFarmfalseZastaralé — nemá žádný efekt. Publikujte dokument s DistributedDocumentPublisher.PublishAsync (nebo IDistributedPublishQueue.EnqueueAsync) a místo toho nastavte FileShareConfig.RootPath.
stringWebFarmPath""Zastaralé — nemá žádný efekt. Použijte FileShareConfig.RootPath místo toho.
boolEditModefalseRezervováno pro samostatně distribuovaný workflow Editoru; ponechte false pro standardní prohlížeč.

Vlastní vodoznak

DocOptions.Watermark používá šest polí oddělených vlnovkou. Volitelný úvodní ^ požaduje rozvržení po všech rozích:

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
    });
PolePříkladVýznam
Leading ^^Volitelné rozvržení po všech rozích. Bez něj se používá normální umístění vodoznaku.
TextConfidentialText vykreslený na každé stránce. Nesmí být prázdný.
ColorRedPojmenovaná barva rozpoznaná kreslicí vrstvou.
FontSize24Velikost písma; neplatný číselný vstup se vrátí k výchozímu nastavení rendereru.
FontNameVerdanaPožadovaná rodina písma. Ujistěte se, že je nainstalována v prostředí nasazení.
Opacity80Hodnota bajtu od 0 do 255. Musí být úspěšně parsována.
Angle-45Rotace ve stupních; neplatný číselný vstup se vrátí k výchozímu.

Parser očekává přesně šest polí po volitelném ^. Neplatná definice je nahrazena viditelným záložním řešením SDK Invalid Watermark místo tichého zmizení.

Rozhodnutí o licenci

Stav licencePoskytnutá vlastní hodnotaVýsledek
Platná placená licence pro prohlížečNeČistá stránka
Platná placená licence pro prohlížečAnoVlastní vodoznak
Aktivní dočasná/Demo základní verze prohlížečeNeČistá stránka základního prohlížeče
Aktivní dočasná/Demo základní verze prohlížečeAnoVlastní vodoznak, když se použije čistá cesta základního prohlížeče
Chybějící, odmítnutá, vypršená, nesprávná verze nebo licence s neplatnou doménouLibovolnáVynucovací/evaluační vodoznak; vlastní hodnota jej nepřepíše
Renderování pluginu podle evaluačních pravidelLibovolnáEvaluační vodoznak

Stejné rozhodnutí se aplikuje na poskytované obrázky stránek a exporty anotací. Výstup animovaného GIFu je opatřen vodoznakem po jednotlivých snímcích. Vlastní vodoznak je tedy licencovanou funkcí aplikace, nikoli způsobem, jak nahradit nebo potlačit evaluační vodoznak.

API anotací

Na straně serveru načítání a export anotací. Kompletní průvodce je v Průvodcích → Anotace; rozhraní je:

ČlenÚčel
AnnotationManager GetAnnotationManager(string token)Správce vázaný na rozměry stránky otevřené relace
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Správce s explicitními rozměry stránky
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Správce nezávislý na relaci
void LoadAnnotationData(string token, AnnotationManager manager)Načíst anotace vytvořené v C# do relace
void LoadAnnotationData(string token, string annotationData)Načíst anotace z kódovaného page/Base64 obálky vrácené pomocí AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Načíst anotace z XML
XmlDocument GetAnnotationXML(string token)Exportovat anotace relace jako XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF s vypečenými anotacemi
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)Jeden PNG na stránku, anotace vypečené, zapsané do directoryPath (vytvořeno, pokud chybí); vrací počet zapsaných obrázků
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ZIP s PNG soubory po stránkách s vypečenými anotacemi

Metadata DICOM

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

Metoda je přítomna pro sladění API, ale prohlížeč DICOM .NET 6 nemůže poskytnout technické značky. Vrací null pro DICOM i ne‑DICOM relace; v DICOM relaci také zapíše jednorázové varování vysvětlující omezení platformy. Vykreslování stránek, snímků a animací zůstává podporováno.

Pomocníci zdrojů — ReferenceCss / ReferenceScripts

Vygenerujte značky <link>/<script> pro vložené zdroje poskytované UseDoconutResources(), ve správném pořadí závislostí. Balíčky pro funkce omezené licencí, jako je vyhledávání a anotace, jsou generovány pouze když licence povolí, aby uživatelské rozhraní klienta zůstalo v souladu s chováním serveru.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + prohlížeč + vyhledávání + anotace
string ReferenceScripts(ScriptConfig? config = null)

CssConfig příznaky: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (omezené vyhledáváním), IncludeAnnotationCss (omezené anotací).

ScriptConfig příznaky: IncludeJQuery (vyžadováno všemi ostatními), IncludeBootstrap, IncludeViewerScripts (jádro: docViewer.js + rozdělovač + odkazy), IncludeSearchScripts a IncludeSearchBar (omezené vyhledáváním), IncludeAnnotationScripts a IncludeAnnotationBar (omezené anotací), EmitFeatureFlags (výchozí true: také zapisuje vložený skript window.Doconut.features = { search, annotation, editor }; nastavte na false pod Content-Security-Policy, která blokuje vložené skripty).

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

Byla tato stránka užitečná?