Plugin pro převod

Plugin Converter promění Doconut na službu pro převod dokumentů. Přispívá k enginu stojícímu za veřejnou DocumentConverter fasádou a — po opt-in — poskytuje vložitelný widget s vlastním HTTP kontraktem, takže můžete převádět dokumenty z C#, z widgetu nebo z frontendu, který si vytvoříte.

Nainstalujte balíček

Nainstalujte nejnovější stabilní plugin Converter:

dotnet add package Doconut.NET6.Converter

Pro připnutí pluginu k aktuálnímu vydání 26.7.0 předávejte verzi samostatně:

dotnet add package Doconut.NET6.Converter --version 26.7.0

Udržujte balíček Converter ve stejné verzi jako Doconut.NET6. ID balíčku je Doconut.NET6.Converter; .26.7.0 se objevuje pouze v názvu staženého souboru .nupkg.

Zaregistrujte plugin

Neexistuje metoda AddConverter() — model pluginů Doconut je jednotný. Každý plugin, včetně Converter, se registruje stejným způsobem: zavolejte AddPlugin<TPlugin>() uvnitř AddDoconut(). ConverterPlugin je dodáván ve svém vlastním NuGet balíčku, Doconut.NET6.Converter, nainstalovaném vedle základního balíčku vieweru.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Toto volání vyhodí výjimku při startu při chybějící licenci, starém souboru TRIAL nebo ne‑dočasné licenci, která nepřiděluje schopnost Converter — InvalidOperationException vyvolaná uvnitř AddDoconut(), předtím než aplikace začne obsluhovat požadavky. Dočasné registrace Demo/NFR jsou akceptovány; po jejich kalendářním vypršení zůstává převod dostupný s vodoznakovým výstupem. Tichý bezplatný tarif neexistuje. Viz License Setup pro způsob načítání licencí.

Převod z C#

Každý převod vrací vyhledávatelný MemoryStream nastavený na 0, připravený okamžitě číst nebo kopírovat. Získejte DocumentConverter z DI kdekoliv jej potřebujete — je navržen jako bezstavový, takže jedna instance je bezpečná pro opakované použití napříč požadavky.

// Injektujte DocumentConverter; jeho konstruktor je interní, takže jej nikdy `new` nevolejte.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension obsahuje úvodní tečku. password je null, pokud není dokument chráněn.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Dvě detaily, které se snadno špatně pochopí: sourceExtension u přetížení streamu musí obsahovat úvodní tečku (".xlsx", ne "xlsx") — převodník ji porovnává s katalogem formátů a samotná přípona se nevyřeší. A navzdory svému názvu, WordToHtmlAsync vrací Task<Stream>, ne Task<string> — získáte HTML dokument (obrázky vložené jako Base64) jako stream, stejně jako každý jiný výsledek převodu.

Cílové formáty

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Ne každý zdroj se převádí na každý cíl — plugin mapuje každou rodinu formátů zdroje (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, webový dokument) na vlastní pevně danou sadu povolených cílů. Není vhodné tuto výčtovou hodnotu zakódovat jako seznam cílů ve vašem UI: ?convert=open vrací skutečný allowedTargets pro jakýkoli právě nahraný soubor, a to by mělo řídit výběr.

Widget typu Drop‑in

Widgetova ?convert=open|run|download koncová místa jsou volitelná a jsou ve výchozím nastavení zakázaná — zabezpečené z výchozího nastavení. Povolit je na straně serveru spolu s registrací pluginu:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;
    });
});

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Bez AddConverterWidget() odpovídají tři koncová místa ?convert= s 404 — ale soubor JS je i tak stále poskytován (jedná se o prostý vložený statický zdroj; pouze koncová místa, ke kterým se připojuje, jsou omezená). AddConverterWidget() stále vyžaduje, aby byl registrován plugin Converter a licence, která poskytuje Converter — neposkytuje samotná práva ke konverzi.

Přizpůsobení widgetu

Inicializační možnosti předávané do Doconut.convert(selector, options):

Zpětné volání:

Doconut.convert() vrací samotnou instanci widgetu — uchovejte si ji pro programové ovládání widgetu:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // zpět na obrazovku idle/drop; nespouští znovu onReady
conv.loadFile(file);  // spustí tok s objektem File; no-op pokud není aktuálně idle
conv.destroy();       // odstraní posluchače, vyprázdní mount; instance po tomto není použitelná

Vytvořte si vlastní frontend

Widget je jen klient pro tuto HTTP smlouvu — vytvořte si vlastní frontend přímo proti ní pro odlišnou uživatelskou zkušenost. Všechny tři cesty jsou pod větví ASP.NET, kde je nasazeno UseDoconut() (obvykle /doconut):

Nahrané bajty zdroje jsou uloženy na serveru s TTL 30 minut; po uplynutí tohoto intervalu run odpovídá 404 a soubor je nutné znovu otevřít. Převod výsledku žije ve stejném úložišti — downloadToken získá své vlastní čerstvé 30‑minutové okno po dokončení konverze — zatímco resultToken je běžný token relace prohlížeče, jehož životnost následuje cache relace prohlížeče, nezávisle na úložišti.

sourceExt v odpovědi open nemá úvodní tečku (např. "docx") — opačná konvence oproti parametru sourceExtension na DocumentConverter.ConvertAsync, který tečku vyžaduje.

Režimy selhání, seskupené podle cesty:

Vlastnictví zdroje

Převodník vrací seekovatelný MemoryStream umístěný na nulu. Volající vlastní tento stream a měl by jej po kopírování nebo vrácení jeho obsahu uvolnit. Služba DocumentConverter je sama o sobě bezstavová a je získávána z injekce závislostí; nevyvíjejte ani neuvolňujte službu ručně.

Pro webový widget mají nahrávací a stahovací úložiště nezávislé TTL 30 minut. Viewer resultToken místo toho sleduje životnost relace vieweru. Uzavření výsledku vieweru neodstraní stále platné stahovací úložiště a resetování widgetu v prohlížeči neprodlouží žádné z TTL.

Odstraňování potíží

Vodoznakování

S registrovaným ConverterPlugin je licence hostitele v jednom ze tří stavů:

Obě volací cesty vypočítávají příznak podle stejného pravidla: facade DocumentConverter v C# jej interně odvozuje z IsViewerLicensed a IsTemporary stavu licence, a handler widgetu ?convert=run provádí ekvivalentní kontrolu (IsViewerLicensed && !IsTrial && !IsTemporary) pro vyplnění pole watermarked, které vrací. Integraci lze postavit a otestovat end-to-end na evaluační licenci před nákupem — mění se jen výstupní bajty.