Prohlížeč

Viewer (namespace Doconut) je veřejný vstupní bod 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 injekcí do konstruktoru — nikdy jej neinstanciujte přímo.

Předchozí knihovna .NET Standard poskytovala veřejný konstruktor přijímající paměťovou cache, přístup k HTTP kontextu a jeden nebo více cest k licencím. Tento konstruktor byl odstraněn; graf služeb poskytuje tyto závislosti.

Viewer neuchovává žádný stav na požadavek a úmyslně neimplementuje IDisposable: relace dokumentů žijí nezávisle v cache relací, takže uvolnění služby by nikdy nemohlo 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. Každé otevření je asynchronní — neexistuje synchronní OpenDocument.

// Jednoduché otevření
string token = await viewer.OpenDocumentAsync(path);

// S konfigurací a volbami 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 k ošetření:

• LicenseException — nalezená licence je odmítnuta (zpráva nese důvod odmítnutí), nebo formát vyžaduje plugin, který již není poskytován. 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

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

int GetPageCount(string token)

Celkový počet stránek otevřené relace. Vyhodí výjimku, pokud je token neznámý nebo vypršel.

GetWorksheetNames

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.

Zobrazeny jsou pouze vykreslené listy: skryté a prázdné listy jsou vyloučeny a když ExcelConfig.SheetNames omezuje renderování, zobrazí se jen tyto listy. List není vždy jedna stránka — velmi velký list je vykreslen přes několik stránek. Vyhodí výjimku, pokud je token neznámý nebo vypršel.

Přidáno ve verzi 26.9.0.

Příznaky schopností

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

Možnosti dokumentu

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

Třída také poskytuje specializované vlastnosti, které jsou úmyslně mimo běžný jednojmenný prohlížečový tok:

Vlastní vodoznak

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

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

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

Rozhodnutí o licenci

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

API anotací

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

Každý z nich vyžaduje token relace. Tvar GetAnnotationManager(pageWidth, pageHeight) z předchozí knihovny, který nevyžaduje relaci, přežívá pro vytváření anotací mimo relaci, ale jejich načítání stále vyžaduje token.

DICOM metadata

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

Metoda je zde pro sladění API, ale tento balíček nemůže poskytovat technické DICOM značky: čtečka metadata je dostupná jen ve verzi .NET 8. Vrací null pro DICOM i ne‑DICOM relace; v DICOM relaci také zapisuje 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é pomocí 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 umožňuje jejich použití, aby uživatelské rozhraní klienta odpovídalo chování serveru.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
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 + splitter + odkazy), IncludeSearchScripts a IncludeSearchBar (omezené vyhledáváním), IncludeAnnotationScripts a IncludeAnnotationBar (omezené anotací).

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

Tito pomocníci jsou podporovaným způsobem doručování zdrojů do prohlížeče. Aplikace, které zkopírovaly docViewer.js, documentLinks.js a docViewer.UI.js do wwwroot, by měly tyto kopie odstranit, jakmile se stránka vykreslí ze vygenerovaných značek.