Prohlížeč

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

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 pomocí injekce do konstruktoru — nikdy jej nekonstrukujte přímo.

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

Viewer neobsahuje žádný stav specifický pro požadavek a úmyslně neimplementuje IDisposable: relace dokumentů žijí nezávisle v mezipaměti 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.

PřetíženíPoužít když
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Otevření z disku s automatickou detekcí 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í detekci 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 k ošetření:

  • LicenseException — nalezená licence je odmítnuta (zpráva nese důvod odmítnutí), nebo formát vyžaduje pluginovou schopnost, která již není poskytována. 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 mezipaměti (okamžitě uvolní dokumentový engine), smaže bezpečnostní značku a odvolá přístupové oprávnění. Volitelné — posuvná expirace provádí stejný úklid — ale je doporučena 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 % přiblížení — souřadnicový prostor pro anotace vytvořené v kódu. page je akceptová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í tabulkou.

Uvedeny jsou pouze vykreslené listy: skryté a prázdné listy jsou vyloučeny a když ExcelConfig.SheetNames omezuje vykreslování, zobrazí se jen tyto listy. List není vždy jedna stránka — velmi velký list je vykreslen přes několik stránek. Vyvolá 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 poskytuje Search
bool IsAnnotationEnabledAktuální licence poskytuje Annotation

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

DocOptions

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

TypVlastnostVýchozíPopis
stringPassword""Heslo pro chráněné dokumenty (automaticky zkopírováno do konfigurace formátu).
intImageResolution0Zastaralé. Uchovává se 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 nevyžadováno — rezervováno. Vazba tokenu je řízena globálně pomocí DoconutOptions.UnsafeMode (viz Core Concepts → Sessions & Security).

Třída také poskytuje specializované vlastnosti, které jsou úmyslně mimo běžný jednojádrový tok prohlížení:

TypVlastnostVýchozíPopis
boolIsWebFarmfalseZastaralé — nemá žádný efekt. Publikujte dokument s DistributedDocumentPublisher.PublishAsync (nebo IDistributedPublishQueue.EnqueueAsync) a místo toho nastavte FileShareConfig.RootPath. Všimněte si zápisu — předchozí knihovna tuto hodnotu psala jako IsWebfarm.
stringWebFarmPath""Zastaralé — nemá žádný efekt. Použijte FileShareConfig.RootPath, jak je popsáno v Distribuovaných nasazeních. Dříve psáno jako WebfarmPath.
boolEditModefalseRezervováno pro samostatně distribuovaný editační workflow; 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
Úvodní ^^Volitelné rozvržení po všech rozích. Bez něj se používá běžné umístění vodoznaku.
TextConfidentialText vykreslený na každé stránce. Nesmí být prázdný.
BarvaRedPojmenovaná barva rozpoznaná vykreslovací vrstvou.
Velikost písma24Velikost písma; neplatný číselný vstup se vrátí k výchozímu nastavení rendereru.
Název písmaVerdanaPožadovaná rodina písma. Ujistěte se, že je nainstalována v prostředí nasazení.
Průhlednost80Hodnota bajtu od 0 do 255. Musí být úspěšně parsována.
Úhel-45Rotace v 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 Invalid Watermark SDK místo tichého zmizení.

Rozhodnutí o licenci

Stav licencePoskytnutá vlastní hodnotaVykreslený vý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í prohlížečNeČistá stránka základního prohlížeče
Aktivní dočasný/demo základní prohlížečAnoVlastní 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í/výkonnostní vodoznak; vlastní hodnota jej nepřepíše
Rendering pluginu podle pravidel hodnoceníLibovolnáVodoznak hodnocení

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 vodoznak hodnocení.

API anotací

Načítání a export anotací na straně serveru. 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é stránky/obálky Base64 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 vkloučenými anotacemi
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)Jeden PNG na stránku, anotace vklouč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 soubor s PNG pro každou stránku s vkloučenými anotacemi

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

Metadata DICOM

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

Metoda je zde pro sladění API, ale tento balíček nemůže poskytovat technické DICOM tagy: čtečka metadat je distribuována pouze s verzí .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 řízené 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.

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 (řízené vyhledáváním), IncludeAnnotationCss (řízené anotacemi).

ScriptConfig příznaky: IncludeJQuery (vyžadováno všemi ostatními), IncludeBootstrap, IncludeViewerScripts (jádro: docViewer.js + splitter + odkazy), IncludeSearchScripts a IncludeSearchBar (řízené vyhledáváním), IncludeAnnotationScripts a IncludeAnnotationBar (řízené anotacemi), EmitFeatureFlags (výchozí true: také zapisuje vložený skript window.Doconut.features = { search, annotation, editor }; nastavte na false při 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 }))

Tito pomocníci jsou podporovaným způsobem doručování zdrojů 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í pomocí vygenerovaných značek.

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