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 |
// 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
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
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 % 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
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í
| Člen | Význam |
|---|---|
bool IsSearchEnabled | Aktuální licence poskytuje Search |
bool IsAnnotationEnabled | Aktuá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):
| 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á se 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 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í:
| 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. Všimněte si zápisu — předchozí knihovna tuto hodnotu psala jako IsWebfarm. |
string | WebFarmPath | "" | Zastaralé — nemá žádný efekt. Použijte FileShareConfig.RootPath, jak je popsáno v Distribuovaných nasazeních. Dříve psáno jako WebfarmPath. |
bool | EditMode | false | Rezervová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~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 |
|---|---|---|
Úvodní ^ | ^ | Volitelné rozvržení po všech rozích. Bez něj se používá běžné umístění vodoznaku. |
| Text | Confidential | Text vykreslený na každé stránce. Nesmí být prázdný. |
| Barva | Red | Pojmenovaná barva rozpoznaná vykreslovací vrstvou. |
| Velikost písma | 24 | Velikost písma; neplatný číselný vstup se vrátí k výchozímu nastavení rendereru. |
| Název písma | Verdana | Požadovaná rodina písma. Ujistěte se, že je nainstalována v prostředí nasazení. |
| Průhlednost | 80 | Hodnota bajtu od 0 do 255. Musí být úspěšně parsována. |
| Úhel | -45 | Rotace 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 licence | Poskytnutá vlastní hodnota | Vykreslený 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í prohlížeč | Ne | Čistá stránka základního prohlížeče |
| Aktivní dočasný/demo základní prohlíž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í/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
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.
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).
@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á?