转换插件

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

Converter 插件将 Doconut 转变为文档转换服务。它提供了公共 DocumentConverter 门面的引擎,并且 — opt-in — 一个带有自身 HTTP 合约的 Drop-in widget,使您可以从 C#、从该小部件或从自行编写的前端转换文档。

表面使用场景
DocumentConverter (C#)您在服务器上进行转换,不涉及浏览器
Drop-in widget (doconutConverter.js)您希望在页面中拥有现成的上传、转换和下载界面
HTTP endpoints (?convert=open|run|download)您根据文档化的服务器合约自行构建转换 UI

安装包

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

bash
dotnet add package Doconut.NET8.Converter

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

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

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

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

平台。 插件可在 Doconut.NET8 运行的任何环境中运行: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.NET8.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# 中使用

每次转换都会返回一个定位在 0 的可寻址 MemoryStream,可立即读取或复制。随时从 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();         // 返回空闲/拖放屏幕; 不会重新触发 onReady
conv.loadFile(file);  // 使用 File 对象启动流程; 除非当前空闲,否则不执行任何操作
conv.destroy();       // 移除监听器,清空挂载点; 此后实例不可用

标签

每个字符串都有英文默认值;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,单文件)上传并打开源文档以进行预览200 — { token, pages, sourceExt, allowedTargets }
POST ?token=<token>&convert=run&target=<ext>将已缓存的源转换为 target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET ?convert=download&token=<downloadToken>流式传输已转换的文件200 — 文件字节,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() 从未被调用)——在任何三个路由分发之前检查仅状态
任意405HTTP 方法错误(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.NET8.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,encrypt-then-MAC),且每个文件绑定到其令牌,因此任何令牌都无法读取其他文件。
  • 在共享存储上,上传或结果在写入后会保留 Ttl;读取它不会延长此时间窗口。
  • FarmKey 必须至少为 32 字节,并且在每个节点上保持一致。请从机密存储加载;切勿硬编码。注册时如果缺少 RootPath 或 FarmKey 短于 32 字节,会抛出 ArgumentException。
  • 将 RootPath 指向分布式查看器使用的相同共享位置。

API 参考

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

此页面对您有帮助吗?