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 |
// 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
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í InvalidOperationException (Document session not found. Please re-open document.), pokud je token neznámý nebo vypršel, a ArgumentException pro prázdný token.
GetPageDimensions
(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
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í
| Člen | Význam |
|---|---|
bool IsSearchEnabled | Aktuální licence uděluje Search |
bool IsAnnotationEnabled | Aktuá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):
| Typ | Vlastnost | Výchozí | Popis |
|---|---|---|---|
string | Password | "" | Heslo pro chráněné dokumenty (automaticky zkopírováno do konfigurace formátu). |
int | ImageResolution | 0 | Zastaralé. Uchováváno pouze pro kompatibilitu — místo toho nastavte ImageResolution v konfiguraci formátu. |
string | Watermark | "" | 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". |
int | TimeOut | 60 | Posuvná expirace relace v minutách. |
bool | IsSecured | true | V 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:
| Typ | Vlastnost | Výchozí | Popis |
|---|---|---|---|
bool | IsWebFarm | false | Zastaralé — nemá žádný efekt. Publikujte dokument s DistributedDocumentPublisher.PublishAsync (nebo IDistributedPublishQueue.EnqueueAsync) a místo toho nastavte FileShareConfig.RootPath. |
string | WebFarmPath | "" | Zastaralé — nemá žádný efekt. Použijte FileShareConfig.RootPath místo toho. |
bool | EditMode | false | Rezervová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~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Pole | Příklad | Význam |
|---|---|---|
Leading ^ | ^ | Volitelné rozvržení po všech rozích. Bez něj se používá normální umístění vodoznaku. |
| Text | Confidential | Text vykreslený na každé stránce. Nesmí být prázdný. |
| Color | Red | Pojmenovaná barva rozpoznaná kreslicí vrstvou. |
| FontSize | 24 | Velikost písma; neplatný číselný vstup se vrátí k výchozímu nastavení rendereru. |
| FontName | Verdana | Požadovaná rodina písma. Ujistěte se, že je nainstalována v prostředí nasazení. |
| Opacity | 80 | Hodnota bajtu od 0 do 255. Musí být úspěšně parsována. |
| Angle | -45 | Rotace 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 licence | Poskytnutá vlastní hodnota | Výsledek |
|---|---|---|
| Platná placená licence pro prohlížeč | Ne | Čistá stránka |
| Platná placená licence pro prohlížeč | Ano | Vlastní vodoznak |
| Aktivní dočasná/Demo základní verze prohlížeče | Ne | Čistá stránka základního prohlížeče |
| Aktivní dočasná/Demo základní verze prohlížeče | Ano | Vlastní 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énou | Libovolná | Vynucovací/evaluační vodoznak; vlastní hodnota jej nepřepíše |
| Renderování pluginu podle evaluačních pravidel | Libovolná | 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
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.
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).
@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á?