Plugin pro převod

Plugin Converter promění Doconut na službu pro převod dokumentů. Poskytuje jádro za veřejnou fasádou DocumentConverter a — volitelně — 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 napíšete sami.

Instalace balíčku

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 zvlášť:

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 jen v název staženého souboru .nupkg.

Registrace pluginu

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 součástí vlastního NuGet balíčku Doconut.NET6.Converter, nainstalovaného vedle základního balíčku vieweru.

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

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

// sourceExtension zahrnuje ú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);

Dva detaily, které se snadno přehlédnou: sourceExtension u přetížení se streamem musí obsahovat úvodní tečku (".xlsx", ne "xlsx" ) — konvertor ji porovnává s katalogem formátů a samotná přípona by se nevyhodnotila. A navzdory názvu WordToHtmlAsync vrací Task<Stream>, ne Task<string> — získáte HTML dokument (obrázky vložené jako Base64) jako stream, stejně jako výsledek každého jiného 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 dá převést na každý cíl — plugin mapuje rodinu formátu 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 přímo v UI: ?convert=open vrací skutečné allowedTargets pro právě nahraný soubor a to by mělo napájet výběrový seznam.

Vložitelný widget

Endpointy widgetu ?convert=open|run|download jsou volitelné a jsou ve výchozím nastavení zakázané — bezpečné z pohledu výchozí konfigurace. Povolit je můžete na serveru při registraci 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() vrací tři endpointy ?convert= chybu 404 — ale samotný JS soubor je i tak servírován (je to prostý vložený statický zdroj; pouze endpointy, ke kterým se odkazuje, jsou uzamčeny). AddConverterWidget() stále vyžaduje, aby byl plugin Converter zaregistrován a licence přidělující Converter — sama o sobě nepřiděluje práva k převodu.

Přizpůsobení widgetu

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

Callbacky:

Doconut.convert() vrací samotnou instanci widgetu — uchovejte ji, pokud chcete widget ovládat programově:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // zpět na nečinnou/drop obrazovku; nevyvolá znovu onReady
conv.loadFile(file);  // spustí tok s objektem File; neudělá nic, pokud není v idle stavu
conv.destroy();       // odstraní posluchače, vyprázdní mount; instance po tomto není použitelná

Vytvořte si vlastní frontend

Widget je jen klient pro tento HTTP kontrakt — postavte si vlastní frontend přímo proti němu pro odlišné UX. Všechny tři trasy leží pod větví ASP.NET, kde je UseDoconut() namontováno (obvykle /doconut):

Nahrané bajty zdroje jsou uloženy na serveru s TTL 30 minut; po uplynutí tohoto okna vrátí run chybu 404 a soubor je nutné znovu otevřít. Výsledek převodu žije ve stejném úložišti — downloadToken získá vlastní čerstvé 30‑minutové okno po dokončení převodu — zatímco resultToken je běžný token relace vieweru, jehož životnost následuje cache relace vieweru, nezávisle na úložišti.

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

Režimy selhání, rozdělené podle trasy

Vlastnictví zdrojů

Konvertor vrací seekovatelný MemoryStream nastavený na nulu. Volající vlastní tento stream a měl by jej po zkopírování nebo vrácení obsahu uvolnit. Služba DocumentConverter je stateless a získává se z dependency injection; nesnažte se ji ručně konstruovat ani uvolňovat.

U webového widgetu mají úložiště nahrávek a stažení nezávislé TTL 30 minut. Token resultToken vieweru následuje životnost relace vieweru. Uzavření výsledku vieweru nesmaže stále platné úložiště stažení a resetování widgetu v prohlížeči neprodlouží žádné TTL.

Odstraňování potíží

Vodoznakování

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

Oba cesty výpočtu flagu používají stejný pravidlo: C# fasáda DocumentConverter odvozuje ho interně ze stavu licence IsViewerLicensed a IsTemporary, a handler widgetu ?convert=run provádí ekvivalentní kontrolu (IsViewerLicensed && !IsTrial && !IsTemporary) pro naplnění pole watermarked ve své odpovědi. Integraci lze postavit a testovat end‑to‑end na evaluační licenci před zakoupením — mění se jen výstupní bajty.