Prohlížeč
Hlavní třída prohlížeče dokumentů
Viewer (namespace Doconut) je veřejný vstupní bod pro otevírání dokumentů z MVC kontrolerů, stránek Web Forms a handlerů. Jedná se o transient službu složenou z DoconutHost.Initialize; získáte ji tam, kde ji používáte:
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();new Viewer() také funguje, jakmile DoconutHost.Initialize běží — řeší stejné služby — což umožňuje, aby kód migrovaný z klasického balíčku byl kompilovatelný. Před Initialize vyhodí InvalidOperationException.
Viewer neuchovává žádný stav dokumentu na požadavek a úmyslně neimplementuje IDisposable: relace dokumentů existují nezávisle na ní, takže uvolnění Viewer by nikdy neuzavřelo otevřený dokument (viz Jak funguje prohlížeč).
OpenDocumentAsync
Otevře dokument a vrátí token relace, který widget používá pro každé následné volání. Když je UnsafeMode false (výchozí), token je přidělen ASP.NET relaci aktuálního požadavku — zavolejte jej z požadavku, který má stav relace (viz Relace a zabezpečení).
| Přetížení | Použít když |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Otevírání 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í mít správnou příponu — výběr 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í (HttpPostedFileBase v MVC; HttpPostedFile ve Web Forms)
using (var ms = new MemoryStream())
{
await file.InputStream.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}Výjimky k ošetření:
LicenseException— licence byla nalezena, ale odmítnuta (zpráva obsahuje důvod), nebo formát vyžaduje pluginovou funkci, kterou licence neposkytuje.FormatNotSupportedException— žádný prohlížeč nezpracovává příponu souboru.InvalidDataException— obsah je poškozený nebo neodpovídá své příponě.
OpenDocument (synchronní)
Pro kód-behind Web Forms a další kód, který nepoužívá asynchronní stránky:
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)Každý vrací token a také jej ukládá do viewer.Token. fileName musí mít správnou příponu. Tyto obálky jsou bezpečné volat z Web Forms stránky: cesta otevření se nikdy nevrací do kontextu ASP.NET požadavku, takže čekání na ni nemůže způsobit deadlock. To neplatí pro každé asynchronní Doconut API — viz sekce Web Forms v Plugin převodníku.
CloseDocument
void CloseDocument(string token)Odstraní relaci (okamžitě uvolní dokumentový engine), odstraní přidělení tokenu z ASP.NET relace aktuálního požadavku a token zruší. Volitelné — posuvná expirace provádí stejný úklid — ale je doporučena pro velké dokumenty.
Dotazy na relaci
| Člen | Vrací |
|---|---|
int GetPageCount(string token) | Celkový počet stránek otevřeného dokumentu |
(int Width, int Height) GetPageDimensions(string token, int page = 1) | Výchozí velikost vykreslené stránky při 100 % přiblížení — souřadnicový prostor pro anotace vytvořené v kódu |
IReadOnlyList<string> GetWorksheetNames(string token) | Vykreslené listy tabulky, v pořadí sešitu; prázdné pro ostatní dokumenty |
Každý vyvolá InvalidOperationException (Document session not found. Please re-open document.), pokud je token neznámý nebo vypršel, a ArgumentException pro prázdný token.
DocOptions
Možnosti nezávislé na formátu 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). |
string | Watermark | "" | Vlastní text vodoznaku vykreslený na stránkách — viz níže. |
int | TimeOut | 60 | Posuvná expirace relace, v minutách. |
string | BrowserId | "" | Webové farmy: prohlížeč, ke kterému je podepsaný tiket vázán. Nastavte jej pomocí DoconutFarmBinding.EnsureBrowserId (viz Relace a zabezpečení). |
string | UserId | "" | Webové farmy: přihlášený uživatel, ke kterému je tiket vázán, z DoconutFarmBinding.ResolveUserId. |
int | ImageResolution | 0 | Zastaralé. Nastavte ImageResolution v konfiguraci formátu místo toho. |
bool | IsSecured | true | Rezervováno; nevyžadováno. Řízení přístupu je DoconutOptions.UnsafeMode. |
bool | IsWebFarm / string WebFarmPath | false / "" | Uchováváno pro kód migrovaný ze starého balíčku. Nepřepínají režim farmy — AddDoconutDistributed ano. |
bool | EditMode | false | Rezervováno pro samostatně distribuovaný editor; ponechte false. |
Vlastní vodoznak
DocOptions.Watermark přijímá šest polí oddělených vlnovkou. Volitelný úvodní ^ požaduje rozlož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é rozložení po všech rozích. Bez něj se používá normální umístění. |
| Text | Confidential | Text vykreslený na každé stránce. Nesmí být prázdný. |
| Color | Red | Pojmenovaná barva. |
| FontSize | 24 | Velikost písma; neplatný číselný vstup se vrátí na výchozí. |
| FontName | Verdana | Rodina písma. Musí být nainstalována na serveru — Windows Server má méně fontů než desktop. |
| Opacity | 80 | 0 až 255. Musí být parsovatelná. |
| Angle | -45 | Rotace ve stupních; neplatný číselný vstup se vrátí na výchozí. |
Parser očekává přesně šest polí po volitelném ^. Neplatná definice je nahrazena viditelným textem Invalid Watermark 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 licence | Ne | Čistá stránka |
| Aktivní dočasná/demo licence | Ano | Vlastní vodoznak |
| Chybějící, odmítnutá, vypršená, špatná verze nebo licence s neplatnou doménou | Libovolná | Evaluační vodoznak; vlastní hodnota jej nenahrazuje |
Stejné rozhodnutí platí pro poskytované stránky i pro exporty anotací. Vlastní vodoznak je funkcí licencované aplikace, nikoli způsobem, jak nahradit evaluační vodoznak.
API anotací
Načítání a export anotací na straně serveru. Průvodce je v Anotace.
| Č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 kódovaný obálku vrácenou 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) | Jedno 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 soubory po stránkách, vkloučenými anotacemi |
DICOM metadata
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)V tomto balíčku vždy vrací null a požadavek widgetu na metadata odpovídá 501 Not Implemented: čtení DICOM značek není k dispozici v .NET Framework. DICOM rendering — stránky, snímky a animace — funguje. Viz DICOM plugin.
Pomocníci zdrojů — ReferenceCss / ReferenceScripts
Vygenerujte značky <link> a <script> pro zdroje, které modul zdrojů poskytuje pod DoconutOptions.ResourcesPath, v pořadí závislostí. Soubory pro funkce omezené licencí (Search, Annotation) jsou generovány pouze když licence umožňuje.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + prohlížeč + vyhledávání + anotace
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; } // stav licence, pro ochranu kódu inicializace ribbon
bool IsAnnotationEnabled { get; }CssConfig příznaky: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (omezené vyhledáváním), IncludeAnnotationCss (omezené anotacemi).
ScriptConfig příznaky: IncludeJQuery (vyžadováno všemi ostatními), IncludeBootstrap, IncludeViewerScripts (základní skripty prohlížeče), IncludeSearchScripts a IncludeSearchBar (omezené vyhledáváním), IncludeAnnotationScripts a IncludeAnnotationBar (omezené anotacemi), EmitFeatureFlags (výchozí true: také zapisuje inline skript window.Doconut.features = { search, annotation, editor }; nastavte na false pod Content-Security-Policy, která blokuje inline skripty).
Obě vrací HTML: zapište je pomocí @Html.Raw(...) v MVC 5 (vytvořte je v kontroleru — pohledy nemají @inject) nebo pomocí <%= %> ve Web Forms. Rychlý start ukazuje obojí.
RenderViewer
string RenderViewer(string elementId, string token, ViewerConfig? config = null)Vrací blok <script>, který inicializuje widget na elementu s id elementId a zobrazí dokument: docViewer({...}) vytvořený z ViewerConfig (výchozí: BasePath: '/', ResPath: 'doconut-res/images'), pak .View(token). Zapište jej po skriptech prohlížeče. Vygenerovaný skript neuchovává žádnou referenci na objekt prohlížeče, takže stránka s vlastní lištou by měla widget inicializovat ručně. Viz ViewerConfig.
Webová farma
string? AccessToken obsahuje podepsaný tiket vydaný posledním otevřením, když je aktivní distribuovaný režim a UnsafeMode je false; na jediném serveru je null. Odešlete jej do widgetu s tokenem: objViewer.View(token, accessToken).
Byla tato stránka užitečná?