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 se svým 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.NET8.Converter

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

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

Udržujte balíček Converter ve stejné verzi jako Doconut.NET8. ID balíčku je Doconut.NET8.Converter; .26.7.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.NET8.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í vyhodí výjimku při startu při chybějící licenci, starém souboru TRIAL nebo nečasově omezené 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á úroveň neexistuje. Viz Nastavení licence 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.

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

Dva 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 svůj vlastní pevně daný soubor povolených cílů. Nezakódujte tento výčet 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 jsou ve výchozím nastavení zakázány — zabezpečené z výroby. 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() odpovídají tři endpointy ?convert= kódem 404 — ale soubor JS je i tak poskytován (jedná se o prostý vložený statický zdroj; pouze endpointy, ke kterým se připojuje, jsou omezeny). AddConverterWidget() stále vyžaduje, aby byl registrován plugin Converter a licence, která poskytuje Converter — sama o sobě neuděluje práva na 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 nečinnosti/odhození; nespustí znovu onReady
conv.loadFile(file);  // spustí tok s objektem File; no-op, pokud není aktuálně nečinný
conv.destroy();       // odstraní posluchače, vyprázdní mount; instance po tomto není použitelná

Vytvořte si vlastní frontend

Widget je pouze klientem pro tuto HTTP smlouvu — vytvořte si přímo vlastní frontend pro odlišné uživatelské rozhraní. Všechny tři cesty jsou umístěny 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ídá 404 a soubor je nutné znovu otevřít. Převodní výsledek zůstává 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í vyhledávatelný MemoryStream nastavený na nulu. 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 injekce závislostí; nevyvíjejte ani neuvolňujte službu ručně.

Pro webový widget mají úložiště nahrávání a stahování nezávislé TTL 30 minut. Viewer resultToken místo toho sleduje životnost relace vieweru. Uzavření výsledku vieweru 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: C# fasáda DocumentConverter 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.