转换插件
将文档转换为 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 插件:
dotnet add package Doconut.NET8.Converter若要将插件固定到本文档所描述的版本,请单独传递版本号:
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 上,在打开第一个文档之前请安装字体配置库:
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 一起提供,安装在基础查看器包旁边。
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});这就是 C# 门面所需的全部。小部件及其 HTTP 端点是另一个可选的 AddConverterWidget(),(参见 内嵌小部件)。
插件需要一个授予 Converter 能力的许可证。若没有,AddDoconut() 会在启动时抛出 InvalidOperationException,在应用提供请求之前:
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 —— 它在设计上是无状态的,因此单个实例在多个请求之间安全复用。
// 注入 DocumentConverter;其构造函数是 internal 的,所以永远不要 `new` 它。
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);// sourceExtension 包含前导点。除非文档受保护,否则 password 为 null。
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// 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 个成员:
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 端点默认是可选且已禁用——默认安全。请在服务器端启用它们,并与插件注册一起进行:
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() 会抛出异常:
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 文件本身仍会被提供(它是普通的嵌入式静态资源;只有它所调用的端点受到限制)。
嵌入使用
<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 中选择一个,进行转换,在可能的情况下预览结果,并提供下载。
选项
| 选项 | 类型 | 默认值 | 备注 |
|---|---|---|---|
basePath | string | /doconut | ?convert= 端点的基础路径;它必须与实际挂载 UseDoconut() 的 ASP.NET 分支匹配(通常通过 MiddlewarePath 协调) |
resPath | string | /doconut-res | 为与其他 Doconut 小部件的配置保持一致而接受;转换器小部件目前不会从中构建任何 URL |
maxUploadMb | number | 25 | 仅在客户端进行预检查——在上传前拒绝超大文件。服务器独立强制其自身上限,并在超出时返回 413 |
licenseUrl | string | null | null | 设置后,将结果屏幕上的水印通知转换为指向此 URL 的链接 |
labels | object | {} | 覆盖小部件的英文默认字符串的任意子集(拖拽文字、按钮、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() 返回小部件实例本身——保留它以编程方式驱动小部件:
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'。
| 键 | 英文默认值 |
|---|---|
dropPrompt | Drag & drop a document here |
dropHint | PDF, Word, Excel, PowerPoint, images and more |
chooseFile | Choose file |
uploading | Uploading {name}… |
page / pages | 1 page / {n} pages |
noTargets | No conversion targets are available for this file. |
convertTo / convert | Convert to / Convert |
converting | Converting to {target}… |
readyToDownload | Ready to download |
download / convertAnother | Download / Convert another |
watermarkNotice | Output is watermarked — get a license to remove it. |
retry | Retry |
genericError | Something went wrong. Please try again. |
sizeLimit | That file is larger than the {mb} MB upload limit. Please choose a smaller file. |
serverError | The server could not process this request. Please try again. |
networkError | Could 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 自定义属性读取颜色、圆角和字体,因此您可以在不触及内部实现的情况下进行主题定制:
#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> | 将已缓存的源转换为 target | 200 — { 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() 从未被调用)——在任何三个路由分发之前检查 | 仅状态 |
| 任意 | 405 | HTTP 方法错误(open/run 需要 POST;download 需要 GET) | 仅状态 |
open | 400 | 不是 multipart 上传 | Expected a multipart file upload. |
open | 400 | 没有文件,或文件为空 | No file uploaded. |
open | 400 | 无法转换的源扩展名 | This file type cannot be converted. |
open | 403 | 文件类型需要许可证未授予的功能(缺少 Dicom 的 DICOM 文件) | Converting this file type requires the Dicom capability license. |
open | 413 | 上传的文件超过 MaxUploadMb,在检查 Content-Length 以及读取上传时进行检查 | File is too large. |
run | 400 | 令牌格式错误(不是 GUID) | Invalid token. |
run | 400 | 一个无法解析为 ConversionTarget 的 target | Unknown target format. |
run | 400 | target 不在源的 allowedTargets 中 | That target format is not available for this file. |
run | 404 | 已缓存的上传已过期或令牌从未被打开 | Upload expired — please re-open the file. |
open, run | 500 | 内部处理失败 | 一条已清理的消息——以与所有其他 Doconut 错误路径相同的方式清理;永不泄露内部细节 |
download | 400 | 令牌格式错误(不是 GUID) | 仅状态 |
download | 404 | 未知或已过期的下载令牌 | 仅状态 |
使用 fetch 的完整往返过程:
// 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 路径(中间件路径和资源路径)进行反向代理。
生产环境
- 安装插件 紧邻核心包,使用相同版本:
dotnet add package Doconut.NET8.Converter。 - 添加许可证文件。 将
Doconut.Viewer.Converter.lic放在与Doconut.Viewer.lic相同的文件夹中。 - 设置服务器上限。
MaxUploadMb在AddConverterWidget中是服务器强制的限制;小部件的maxUploadMb仅是客户端检查。保持两者相等。 - 从相同来源提供 UI,与 Doconut 端点保持一致,或对其进行反向代理(参见构建您自己的前端)。
- 释放转换结果。
ConvertAsync返回的流是池化的;释放它会将其缓冲区返回到池中。
Web 农场
小部件将每个上传及其结果保存在为 open 提供服务的节点内存中。若负载均衡器未使用粘性会话,后续的 run、download 或预览请求可能会到达另一节点而找不到该上传。请在 AddDoconut() 之后仅注册一次共享的加密小部件存储:
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
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
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 的付费许可证 |
小部件加载但其请求返回 404 | AddConverterWidget() 未被调用,或 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 |
此页面对您有帮助吗?