转换器插件

将文档转换为 45 种目标格式

Converter 插件将 Doconut 转变为文档转换服务。它提供了公共 DocumentConverter 外观背后的引擎,并且(可选)提供了带有自身 HTTP 合约的即插即用小部件,这样您可以从 C#、从小部件或从您自行编写的前端进行文档转换。

组件使用场景
DocumentConverter (C#)您在服务器上进行转换,不涉及浏览器
即插即用小部件 (doconutConverter.js)您希望在页面中拥有现成的上传、转换和下载界面
HTTP 端点 (?convert=open|run|download)您基于文档化的服务器合约构建自己的转换 UI

安装包

安装最新的稳定版 Converter 插件:

bash
dotnet add package Doconut.NET6.Converter

要将插件固定到本文档所描述的版本,请单独传递版本号:

bash
dotnet add package Doconut.NET6.Converter --version 26.10.0

保持 Converter 包与 Doconut.NET6 的版本一致。包 ID 为 Doconut.NET6.Converter;.<version> 仅出现在下载的 .nupkg 文件名中。

插件的许可证文件 Doconut.Viewer.Converter.lic 放在与 Doconut.Viewer.lic 相同的文件夹中;它会与查看器许可证一起读取。

平台。 插件可在 Doconut.NET6 运行的任何环境中运行:Windows,以及基于 glibc 的 x64 Linux(不支持 Alpine 或其他基于 musl 的发行版)。在 Linux 上,在打开第一个文档之前请先安装字体配置库:

bash
apt-get update && apt-get install -y libfontconfig1

在 RHEL、Fedora 及类似发行版上,包为 fontconfig。如果缺少它,打开文档会因 The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. 而失败

注册插件

没有 AddConverter() 方法——Doconut 的插件模型是统一的。每个插件,包括 Converter,都是以相同方式注册的:在 AddDoconut() 中调用 AddPlugin<TPlugin>()。ConverterPlugin 随其自己的 NuGet 包 Doconut.NET6.Converter 一起提供,安装在基础查看器包旁边。

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

这就是 C# 外观所需的全部。小部件及其 HTTP 端点是一个单独的可选项,AddConverterWidget()(参见 即插即用小部件)。

插件需要一个授予 Converter 能力的许可证。若没有许可证,AddDoconut() 会在启动时抛出 InvalidOperationException,在应用提供请求之前:

text
The Converter plugin is registered via AddPlugin but no active license grants Converter. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

它会因缺少许可证、旧版 TRIAL 文件、缺少 Converter 的许可证,以及在版本窗口之外使用的付费许可证而抛出异常。临时演示/非商业(Demo/NFR)许可证是被接受的。没有静默的免费层。请参见 许可证设置 了解许可证的加载方式。

许可与水印

许可证状态启动时转换输出
付费查看器许可证,授予 Converter,在其版本窗口内启动干净 — watermarked: false
有效的临时(Demo/NFR)许可证启动转换,带有评估水印 — watermarked: true
已过期的临时(Demo/NFR)许可证启动转换,带有评估水印 — watermarked: true
无许可证、旧版 TRIAL 文件、缺少 Converter 的许可证,或在版本窗口之外的付费许可证AddDoconut() 抛出—

两条调用路径都依据相同规则计算该标志:DocumentConverter C# 外观内部从许可证的 IsViewerLicensed 和 IsTemporary 状态推导出该标志,而小部件的 ?convert=run 处理程序进行等价检查(IsViewerLicensed && !IsTrial && !IsTemporary)以填充其返回的 watermarked 字段。可以在购买前使用评估许可证构建并端到端测试集成——唯一变化的是输出字节。

DICOM 源(.dcm,.ima)同样需要 Dicom 能力。若缺少该能力,ConvertAsync 会抛出 LicenseException(Converting '.dcm' requires the Dicom capability license.),而小部件的 open 则返回 403。

在 C# 中使用

每次转换都会返回一个可寻址的 MemoryStream,位置为 0,随时可以读取或复制。随时从 DI 中解析 DocumentConverter —— 它本身是无状态的,因此单个实例可以安全地在请求之间复用。

csharp
// 注入 DocumentConverter;其构造函数是 internal 的,所以永远不要 `new` 它。
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension 包含前导点。除非文档受保护,否则 password 为 null。
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// html: 一个 Stream,保存要转换回 Word 文档的 HTML,例如 WordToHtmlAsync 的结果。
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

两个容易出错的细节:流重载上的 sourceExtension 必须包含前导点(".xlsx",而不是 "xlsx")——转换器会将其与格式目录匹配,单独的扩展名无法解析。并且尽管名字如此,WordToHtmlAsync 返回的是 Task<Stream>,而不是 Task<string> —— 你会得到 HTML 文档(图像以 Base64 嵌入)作为流,和其他所有转换结果相同。

调用方拥有返回的流,并应在复制或返回其内容后进行释放。DocumentConverter 服务本身是通过依赖注入解析的;不要手动构造或释放它。

目标格式

ConversionTarget(命名空间 Doconut.Configs.Conversion)有 45 个成员:

text
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

并非所有源都能转换为所有目标——插件会将每种源的格式族(Word、Excel、PowerPoint、PDF、CAD、Image、Email、Diagram、Project/Task、PSD、web document、DICOM)映射到其固定的允许目标集合。将 DICOM 源(.dcm,.ima)转换还需要拥有授予 Dicom 能力的许可证;其目标包括 Pdf、Png、Jpeg、Bmp、Tiff 和 Gif。不要将此枚举硬编码为 UI 的目标列表:?convert=open 会返回刚上传文件的实际 allowedTargets,这才应该用于选择器。

即插即用小部件

启用端点

小部件的 ?convert=open|run|download 端点默认是可选且已禁用——默认安全。请在服务器端启用它们,并与插件注册一起进行:

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

AddConverterWidget() 在不传参的情况下会使用默认值(MaxUploadMb = 25)启用小部件。它本身并不会授予转换权限:需要 AddPlugin<ConverterPlugin>(),否则 AddDoconut() 会抛出异常:

text
AddConverterWidget() was called but the Converter plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() (the widget needs it), or remove the AddConverterWidget() call.

如果没有 AddConverterWidget(),这三个 ?convert= 端点会返回 404 —— 但 JS 文件本身仍会被提供(它是普通的嵌入式静态资源;只有它所调用的端点受到限制)。

嵌入它

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

Doconut.convert(selectorOrElement, options) 接受 CSS 选择器或元素,如果未找到挂载点则抛出异常,并返回一个句柄。小部件会上传文件,显示第 1 页的预览,让用户从 allowedTargets 中选择一个,进行转换,在可能的情况下预览结果,并提供下载。

选项

选项类型默认值备注
basePathstring/doconut?convert= 端点的基础路径;它必须与实际挂载 UseDoconut() 的 ASP.NET 分支匹配(通常通过 MiddlewarePath 协调)
resPathstring/doconut-res为与其他 Doconut 小部件的配置保持一致而接受;转换器小部件目前不会从中构建任何 URL
maxUploadMbnumber25仅在客户端进行预检查——在上传前拒绝超大文件。服务器会独立强制其自身的上限,并在超出时返回 413
licenseUrlstring | nullnull设置后,会将结果屏幕上的水印通知转换为指向此 URL 的链接
labelsobject{}覆盖小部件的任意子集英文默认字符串(拖拽文本、按钮、aria-live 通知、错误信息)

回调

回调触发时机负载
onReady()小部件已渲染其空闲/拖拽屏幕—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open 成功时源会话令牌、页数、源扩展名(无前导点)、允许的目标列表
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run 成功时与运行响应相同的字段,加上请求的 target
onDownload({ downloadName, downloadToken })用户点击下载链接时与浏览器原生下载同时触发——它不拦截或替代下载
onError({ phase, message })打开或运行请求失败时phase 为 'open' 或 'run';message 为已清理的服务器错误(或上传大小预检查的客户端消息)

抛出异常的回调会被捕获并记录;它永不会中断小部件的流程。

命令式句柄

Doconut.convert() 返回小部件实例本身——保留它以编程方式驱动小部件:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
const file = document.querySelector('#picker').files[0]; // 来自您自己的文件 <input type="file" id="picker">
conv.reset();         // 返回 idle/drop 屏幕;不会重新触发 onReady
conv.loadFile(file);  // 使用 File 对象启动流程;除非当前为空闲,否则不执行任何操作
conv.destroy();       // 移除监听器,清空 mount;此后实例不可用

标签

每个字符串都有英文默认值;labels 覆盖任意子集,其余保持英文。运行时会变化的片段使用 {placeholders},例如 uploading: 'Uploading {name}…' 和 pages: '{n} pages'。

键英文默认
dropPromptDrag & drop a document here
dropHintPDF, Word, Excel, PowerPoint, images and more
chooseFileChoose file
uploadingUploading {name}…
page / pages1 page / {n} pages
noTargetsNo conversion targets are available for this file.
convertTo / convertConvert to / Convert
convertingConverting to {target}…
readyToDownloadReady to download
download / convertAnotherDownload / Convert another
watermarkNoticeOutput is watermarked — get a license to remove it.
retryRetry
genericErrorSomething went wrong. Please try again.
sizeLimitThat file is larger than the {mb} MB upload limit. Please choose a smaller file.
serverErrorThe server could not process this request. Please try again.
networkErrorCould not reach the server. Please check your connection and try again.

进一步的键覆盖了拖拽区的 aria-label(dropAriaLabel),预览 alt 文本(previewAlt、resultAlt),与 licenseUrl 一起使用的水印通知的链接形式(watermarkNoticePrefix、watermarkNoticeLink、watermarkNoticeSuffix),不可读的响应(badResponse)以及 aria-live 通知(annReady、annUploading、annLoaded、annLoadedNoTargets、annConverting、annDone、annError)。

来自服务器的 JSON 错误会原样显示;serverError 仅在失败响应未携带 JSON 错误时使用,例如禁用小部件的 404。

主题化

小部件会向其挂载元素添加 dcw 类,并从 CSS 自定义属性读取颜色、圆角和字体,这样您无需触及内部即可对其进行主题化:

css
#doconut-convert.dcw {
  --dcw-accent: #6b46c1;
  --dcw-radius: 12px;
  --dcw-font: "Inter", system-ui, sans-serif;
}

默认值:--dcw-accent: #2b6cb0、--dcw-bg: #ffffff、--dcw-fg: #1a202c、--dcw-muted: #718096、--dcw-border: #cbd5e0、--dcw-radius: 8px,以及用于 --dcw-font 的系统 UI 字体。

构建您自己的前端

小部件只是此 HTTP 合约的客户端——直接针对它构建您自己的前端以获得不同的用户体验。所有三个路由都位于 ASP.NET 分支下,UseDoconut() 被挂载(通常为 /doconut),它们在调用 AddConverterWidget() 之前返回 404。错误会携带 JSON 正文,{ "error": "..." },除非表格中标注为 “仅状态”。未知的 ?convert= 值会返回 400。

路由目的成功响应
POST ?convert=open (multipart, one file)Upload and open a source document for preview200 — { token, pages, sourceExt, allowedTargets }
POST ?token=<token>&convert=run&target=<ext>Convert the stashed source to target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET ?convert=download&token=<downloadToken>Stream the converted file200 — file bytes, Content-Disposition: attachment, Cache-Control: no-store

sourceExt 在 open 响应中没有前导点(例如 "docx")——这与 DocumentConverter.ConvertAsync 上的 sourceExtension 参数相反,后者需要前导点。allowedTargets 列出小写的目标名称("pdf"、"html",…);将其中一个作为 target 传入,匹配时不区分大小写。open 使用 multipart 正文中的第一个文件。

resultToken 为 null,当结果无法预览时,resultPages 为 0。downloadName 是带有目标扩展名的源文件名。

预览图像使用标准查看器图像路由 {basePath}?token={token}&page=1&thumb=1&width={px},并使用来自 open 的 token 或来自 run 的 resultToken。小部件请求 width=240。

上传的源字节被服务器端暂存,并在最后一次读取后保留 30 分钟;一旦该窗口结束,run 返回 404,必须重新打开文件。转换后的结果也存放在同一暂存区——转换完成后,downloadToken 获得其自己的 30 分钟新窗口——而 resultToken 是用于预览结果的普通查看器会话令牌。当结果可以预览时,downloadToken 与 resultToken 为相同的值。关闭查看器结果不会删除仍然有效的下载暂存区,重置浏览器小部件也不会延长任一窗口。

失败模式,按路由分组:

路由状态何时正文
任意404小部件未启用(AddConverterWidget() 从未被调用)——在任何三个路由分发之前检查仅状态
任意405错误的 HTTP 方法(open/run 需要 POST;download 需要 GET)仅状态
open400不是 multipart 上传Expected a multipart file upload.
open400没有文件,或文件为空No file uploaded.
open400无法转换的源扩展名This file type cannot be converted.
open403文件类型需要许可证未授予的功能(缺少 Dicom 的 DICOM 文件)Converting this file type requires the Dicom capability license.
open413上传的文件超过 MaxUploadMb,在检查 Content-Length 以及读取上传时进行验证File is too large.
run400令牌格式错误(不是 GUID)Invalid token.
run400无法解析为 ConversionTarget 的 targetUnknown target format.
run400target 不在源的 allowedTargets 中That target format is not available for this file.
run404暂存的上传已过期或令牌从未被打开Upload expired — please re-open the file.
open, run500内部处理失败已清理的消息——以与其他所有 Doconut 错误路径相同的方式清理;永不泄露内部细节
download400令牌格式错误(不是 GUID)仅状态
download404未知或已过期的下载令牌仅状态

使用 fetch 的完整往返:

javascript
// file: 要转换的文件,例如来自 <input type="file">。
async function convertFile(file) {
  const base = '/doconut';

  // 1. open: 上传文件
  const form = new FormData();
  form.append('file', file, file.name);
  const openResp = await fetch(base + '?convert=open', { method: 'POST', body: form });
  if (!openResp.ok) throw new Error((await openResp.json()).error);
  const opened = await openResp.json();

  // 2. run: 在允许时转换为 PDF,否则转换为第一个允许的目标
  const target = opened.allowedTargets.includes('pdf') ? 'pdf' : opened.allowedTargets[0];
  const runResp = await fetch(base + '?token=' + encodeURIComponent(opened.token) +
    '&convert=run&target=' + target, { method: 'POST' });
  if (!runResp.ok) throw new Error((await runResp.json()).error);
  const converted = await runResp.json();

  // 3. download: 一个浏览器可以直接跟随的普通 GET 请求
  window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}

端点是 同源:此版本不支持 CORS。将您的 UI 和小部件脚本从与 Doconut 相同的源提供,或在您的 UI 源下对两个 /doconut 路径(中间件路径和资源路径)进行反向代理。

生产环境

  1. 安装插件 在核心包旁边,使用相同的版本:dotnet add package Doconut.NET6.Converter。
  2. 添加许可证文件。 将 Doconut.Viewer.Converter.lic 放在与 Doconut.Viewer.lic 相同的文件夹中。
  3. 设置服务器上限。 MaxUploadMb 在 AddConverterWidget 中是服务器强制的限制;小部件的 maxUploadMb 仅是客户端检查。保持两者相等。
  4. 从相同来源提供 UI,与 Doconut 端点相同,或对其进行反向代理(参见构建您自己的前端)。
  5. 处理转换结果。 流 ConvertAsync 返回的是池化的;处理它会将其缓冲区返回池中。

Web 农场

小部件在提供 open 的节点上将每个上传及其结果保存在内存中。 在没有粘性会话的负载均衡器后面,后续的 run、download 或预览请求可能会到达另一节点,从而找不到该上传。 在 AddDoconut() 之后,只需注册一次共享的加密小部件存储:

csharp
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // 每个节点都可以读取和写入的文件夹
    store.FarmKey = farmKey;                   // 至少 32 字节,在每个节点上相同
    // store.Ttl = TimeSpan.FromMinutes(30);   // 上传保留多长时间(默认)
});
  • 单个服务器不需要任何操作:如果不调用此方法,将使用内存存储。
  • 上传和结果在共享存储上静态加密(AES-256,先加密后 MAC),并且每个文件绑定到其令牌,因此一个令牌永远无法读取其他令牌的文件。
  • 在共享存储上,上传或结果在写入后会保留 Ttl;读取它不会延长该时间窗口。
  • FarmKey 必须至少 32 字节,并且在每个节点上保持一致。从机密存储加载;切勿硬编码。注册时如果缺少 RootPath 或 FarmKey 短于 32 字节会抛出 ArgumentException。
  • 将 RootPath 指向分布式查看器使用的相同共享位置。

API 参考

Facade 和小部件选项位于 Doconut 命名空间;ConversionTarget 位于 Doconut.Configs.Conversion。ConverterPlugin 位于 Doconut.Plugins.Converter。

DocumentConverter

csharp
public sealed class DocumentConverter
{
    public Task<Stream> ConvertAsync(
        string filePath, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> ConvertAsync(
        Stream source, string sourceExtension, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> WordToHtmlAsync(string filePath, CancellationToken ct = default);

    public Task<Stream> HtmlToWordAsync(
        Stream htmlSource, ConversionTarget outputFormat = ConversionTarget.Docx,
        CancellationToken ct = default);
}

通过依赖注入解析;构造函数是 internal。sourceExtension 包含前导点。HtmlToWordAsync 在 outputFormat 为 ConversionTarget.Doc 时写入 .doc 文件,其他值则写入 .docx 文件。

ConversionTarget

在目标格式中列出的 45 种输出格式。

ConverterWidgetOptions

csharp
public sealed class ConverterWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
}

通过 DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null) 设置,它返回 DoconutOptions,以便可以链式调用。

故障排除

症状原因解决方案
AddDoconut() throws The Converter plugin is registered via AddPlugin but no active license grants Converter.没有许可证,TRIAL 文件,许可证缺少 Converter,或付费许可证超出其版本窗口安装授予 Converter 的许可证,或移除 AddPlugin<ConverterPlugin>()
AddDoconut() throws AddConverterWidget() was called but the Converter plugin is not registered.小部件已启用但缺少其插件添加 options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>()
Resolving DocumentConverter throws No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().ConverterPlugin 未注册在 AddDoconut() 中添加 AddPlugin<ConverterPlugin>()
流转换提示格式不受支持sourceExtension 没有前导点传入 ".xlsx",而不是 "xlsx"
ConvertAsync throws Converting '.dcm' requires the Dicom capability license.DICOM 源,且许可证未授予 Dicom使用授予 Dicom 的许可证
输出带有水印许可证是临时的(演示/NFR)使用授予 Converter 的付费许可证
小部件加载成功,但其请求返回 404AddConverterWidget() 未被调用,或 basePath 与挂载 UseDoconut() 的分支不匹配调用 AddConverterWidget();修复 basePath
open answers 403 Converting this file type requires the Dicom capability license.DICOM 上传,且许可证未授予 Dicom使用授予 Dicom 的许可证
open answers 413 File is too large.上传超过了 MaxUploadMb在 AddConverterWidget 中抛出 MaxUploadMb;小部件的 maxUploadMb 仅是客户端检查
run answers 400 That target format is not available for this file.目标不是源的 allowedTargets 之一仅提供来自 open 的 allowedTargets
run or download answers 404 (Upload expired — please re-open the file. from run)30 分钟窗口已过,或 Web 农场节点没有该上传再次打开文件;在农场中,注册 AddDoconutDistributedWidgets
当 UI 位于不同来源时,小部件失败端点不支持 CORS从相同来源提供 UI,或对 Doconut 路径进行反向代理
主题未生效变量设置在祖先元素或挂载内部的元素上;小部件自己的 .dcw 规则将其设置在挂载上直接定位挂载本身:#doconut-convert.dcw 或 #doconut-convert

此页面对您有帮助吗?