转换器插件

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

Converter 插件将 Doconut 转变为文档转换服务。它提供公共 DocumentConverter 门面背后的引擎,并且(可选)提供一个带有自身 HTTP 合约的内嵌小部件,使您可以从 C#、从小部件或从自行编写的前端转换文档。

组件使用场景
DocumentConverter (C#)您在服务器上进行转换,且不涉及浏览器
内嵌小部件 (doconutConverter.js)您想在页面中拥有一个现成的上传、转换和下载界面
HTTP 端点 (?convert=open|run|download)您想基于已记录的服务器合约自行构建转换 UI

安装包

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

bash
dotnet add package Doconut.NETStandard.Converter

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

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

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

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

注册插件

没有 AddConverter() 方法——Doconut 的插件模型是统一的。每个插件,包括 Converter,都是以相同方式注册:在 AddDoconut() 中调用 AddPlugin<TPlugin>()。ConverterPlugin 随其自己的 NuGet 包 Doconut.NETStandard.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: 一个包含 HTML 的 Stream,用于将其转换回 Word 文档,例如 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();       // 移除监听器,清空 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": "..." },除非表格中标注为 “status only”。未知的 ?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 不在源的 allowedTargetsThat 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.NETStandard.Converter。
  2. 添加许可证文件。 将 Doconut.Viewer.Converter.lic 放在与 Doconut.Viewer.lic 相同的文件夹中。
  3. 设置服务器上限。 MaxUploadMb 在 AddConverterWidget 中是服务器强制的限制;widget 的 maxUploadMb 仅是客户端检查。保持两者相等。
  4. 从相同来源提供 UI,与 Doconut 端点保持一致,或对其进行反向代理(参见构建您自己的前端)。
  5. 处理转换结果。 流 ConvertAsync 返回的是池化的;处理它会将其缓冲区返回到池中。

Web 农场

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

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

外观和 widget 选项位于 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.widget 已启用但未加载其插件添加 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 的许可证
输出带有水印许可证为临时(演示/NFR)使用授予 Converter 的付费许可证
widget 加载但其请求返回 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;widget 的 maxUploadMb 仅是客户端检查
run 返回 400 That target format is not available for this file.目标不是源的 allowedTargets 之一仅提供来自 open 的 allowedTargets
run 或 download 返回 404(来自 run 的 Upload expired — please re-open the file.)30 分钟窗口已过,或 web-farm 节点没有该上传重新打开文件;在农场中,注册 AddDoconutDistributedWidgets
当 UI 位于其他来源时 widget 失败端点未提供 CORS 支持从相同来源提供 UI,或对 Doconut 路径进行反向代理
主题未生效变量设置在祖先或挂载内部的元素上;widget 自身的 .dcw 规则在挂载上设置它们直接针对挂载本身:#doconut-convert.dcw 或 #doconut-convert

框架说明

  • viewer.Converter.GetConverter() 在此不存在。转换不再通过 viewer 实例实现:改为注入 Doconut.DocumentConverter。
  • 这个 ConversionTarget 枚举覆盖了所有源族。之前的库为每个族都有一个 *ConfigConverter 类型——WordConfigConverter、ExcelConfigConverter 等——每个都有自己的嵌套 EnTargetFormat 枚举,另外还有一个用于输入的 SourceFormatConverter 枚举。它们全部已移除;请参阅 迁移指南。
  • 仅限 Windows,与 .NET Standard 包的其余部分相同。

此页面对您有帮助吗?