Plugin pro převod

Plugin Converter promění Doconut na službu pro převod dokumentů. Přispívá k enginu 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.

Instalace balíčku

Nainstalujte nejnovější stabilní plugin Converter:

dotnet add package Doconut.NETStandard.Converter

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

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

Udržujte balíček Converter ve stejné verzi jako Doconut.NETStandard. ID balíčku je Doconut.NETStandard.Converter; .26.8.0 se objevuje pouze v názvu 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.NETStandard.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>();
});

Toto volání vyvolá výjimku při spuštění 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 vodoznakem ve výstupu. Tichý bezplatný tarif neexistuje. Viz Nastavení licence pro způsob načítání licencí.

Převod z C#

Každý převod vrací hledatelný 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.

viewer.Converter.GetConverter() zde neexistuje. Převod již není dosažitelný prostřednictvím instance vieweru: místo toho injektujte Doconut.DocumentConverter.

// Vložte DocumentConverter; jeho konstruktor je interní, takže jej nikdy ne`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);

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 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

ConversionTarget (namespace Doconut.Configs.Conversion) má 45 členů:

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

Toto enum pokrývá každou zdrojovou rodinu. Předchozí knihovna měla pro každou rodinu *ConfigConverter typ — WordConfigConverter, ExcelConfigConverter, a tak dále — každý s vlastním vnořeným enumem EnTargetFormat, plus enum SourceFormatConverter pro vstup. Všechny jsou odstraněny; viz průvodce migrací.

Ne každý zdroj se převádí na každý cíl — plugin mapuje každou formátovou rodinu zdroje (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, webový dokument) na vlastní pevnou sadu povolených cílů. Není vhodné hardcodovat toto enum 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.

Vkládací widget

Widgetové ?convert=open|run|download endpointy jsou volitelné a ve výchozím nastavení jsou zakázané — zabezpečené z defaultu. Povolit je na 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(), tři ?convert= endpointy odpovídají 404 — ale samotný soubor JS je stále poskytován (je to prostý vložený statický zdroj; pouze endpointy, 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 konverzní práva sama o sobě.

Přizpůsobení widgetu

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

Callbacky:

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

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // zpět na obrazovku nečinnosti/odhození; nespustí onReady znovu
conv.loadFile(file);  // spustí tok s objektem File; žádná operace, pokud není aktuálně nečinný
conv.destroy();       // odstraní posluchače, vyprázdní mount; instance je po tomto nepouž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 nasazen UseDoconut() (obvykle /doconut):

Nahrané bajty zdroje jsou uloženy na serveru s TTL 30 minut; po uplynutí tohoto intervalu run odpoví 404 a soubor musí být znovu otevřen. Převodní výsledek žije ve stejném úložišti — downloadToken získá 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 nule. Volající vlastní tento stream a měl by jej po zkopírování nebo vrácení jeho obsahu uvolnit. Služba DocumentConverter je sama o sobě bezstavová a je získávána z dependency injection; nesmí se služba vytvářet ani ručně uvolňovat.

Pro webový widget mají úložiště nahrávání a stahování nezávislé TTL 30 minut. Prohlížeč resultToken se řídí životností relace prohlížeče místo toho. Uzavření výsledku prohlížeče nesmaže stále platné úložiště stahování 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 ze stejného pravidla: rozhraní DocumentConverter v C# jej interně odvozuje z IsViewerLicensed a stavu IsTemporary licence, a obslužná rutina widgetu ?convert=run provádí ekvivalentní kontrolu (IsViewerLicensed && !IsTrial && !IsTemporary) pro vyplnění pole watermarked, které vrací. Integraci lze postavit a otestovat kompletně na evaluační licenci před nákupem — mění se jen výstupní bajty.