如何利用 onlyoffice 实现文档格式转换

前言

日常生活和工作中，文档格式转换应该是很常见的需求。面对这样的需求，我们技术男有没有属于自己的好方法呢？答案是有的，它就是 onlyoffice，今天就来介绍如何利用 onlyoffice 实现文档格式转换。

正文

启动 onlyoffice 服务

首先，我们以容器的方式启动一个 onlyoffice 服务，服务端口映射 9080。

服务地址：http://127.0.0.1:9080/ConvertService.ashx

API 接口介绍

官方的 onlyoffice 版本在 4.2 之前使用的请求是 Get 类型，之后的版本使用的请求类型是 Post，这一点需要我们特别注意。下面的表格是关于格式转换 API 参数的详细介绍。

属性参数	描述	数据类型	存在类型
Async	定义转换请求类型：异步与否。 支持的值： true false 当使用异步请求类型时，立即形成响应。 在这种情况下，要获得结果，必须在转换完成之前发送不更改参数的请求。 默认值为false。	boolean	可选
codePage	定义从csv或txt格式转换时的文件编码。 主要支持的值： 932 - 日语（Shift-JIS） 950 - 中国繁体（Big5） 1250 - 中欧（视窗） 1251 - 西里尔文（视窗） 65001 - Unicode (UTF-8)。 您可以在此文件中找到所有支持的值。	integer	可选
Delemiter	定义从csv格式转换时用于分隔值的分隔符。 支持的值： 0 - 没有分隔符 1 - 标签 2 - 分号 3 - 冒号 4 - 逗号 5 - 空间。	integer	可选
fileType*	定义要转换的文档文件的类型。	string	必需
Key	定义用于明确标识文档文件的文档标识符。	string	必需
outputtype*	定义生成的转换文档类型。	string	必需
password	如果文档文件受密码保护，则定义该文件的密码。	string	可选
region	定义从电子表格格式转换为pdf时货币和日期和时间的默认显示格式。使用四个字母（en-US、fr-FR等）语言代码进行设置。默认值为en-US。	string	可选
spreadsheetLayout	定义用于将电子表格转换为 pdf 的设置。	object	可选
spreadsheetLayout.fitToHeight	设置转换区域的高度，以页数为单位。默认值为0。	integer	可选
spreadsheetLayout.fitToWidth	设置转换区域的宽度，以页数为单位。默认值为0。	integer	可选
spreadsheetLayout.gridLines	允许在输出 PDF 文件中包含或不包含网格线。默认值为false。	boolean	可选
spreadsheetLayout.headings	允许在输出 PDF 文件中包含或不包含标题。默认值为false。	boolean	可选
spreadsheetLayout.ignorePrintArea	确定是否忽略为电子表格文件选择的打印区域。默认值为true。	boolean	可选
spreadsheetLayout.margins	设置输出 PDF 文件的边距。	object	可选
spreadsheetLayout.margins.bottom	设置输出 PDF 文件的下边距。默认值为19.1 毫米。	string	可选
spreadsheetLayout.margins.left	设置输出 PDF 文件的左边距。默认值为17.8 毫米。	string	可选
spreadsheetLayout.margins.right	设置输出 PDF 文件的右边距。默认值为17.8 毫米。	string	可选
spreadsheetLayout.margins.top	设置输出 PDF 文件的上边距。默认值为19.1 毫米。	string	可选
spreadsheetLayout.orientation	设置输出 PDF 文件的方向。可能是landscape，portrait。默认值为portrait。	string	可选
spreadsheetLayout.pageSize	设置输出 PDF 文件的页面大小。	object	可选
spreadsheetLayout.pageSize.height	设置输出 PDF 文件的页面高度。默认值为297 毫米。	string	可选
spreadsheetLayout.pageSize.width	设置输出 PDF 文件的页面宽度。默认值为210 毫米。	string	可选
spreadsheetLayout.scale	允许设置输出 PDF 文件的比例。默认值为100。	integer	可选
thumbnail	将图像格式（bmp、gif、jpg、png）指定为outputtype时，定义缩略图的设置。	object	可选
thumbnail.aspect	定义使图像适合指定的高度和宽度的模式。 支持的值： 0 - 拉伸文件以适应高度和宽度 1 - 保持图像的方面 2 - 在这种情况下，不使用宽度和高度设置。取而代之的是，页面的公制尺寸转换为 96dpi 的像素。例如，A4 (210x297mm) 页面将变成尺寸为 794x1123pix 的图片。 默认值为:2。	integer	可选
thumbnail.first	定义是仅为第一页还是为所有文档页面生成缩略图。 如果为 false，则将创建包含所有页面缩略图的 zip 存档。 默认值为true，	boolean	可选
thumbnail.height	以像素为单位定义缩略图高度。默认值为100。	integer	可选
thumbnail.width	以像素为单位定义缩略图宽度。默认值为100。	integer	可选
title	定义转换后的文件名。	string	可选
token	定义以令牌形式添加到文件服务器配置的加密签名。	string	依赖配置
url	定义要转换的文档的绝对 URL。使用本地链接时请务必添加令牌。否则会出现错误。	string	必需

转换列表

下面是文本文档文件格式可以转换成其他格式的列表，第一列是源格式，从第二列到最后一列是可以转换成的其他格式，其中深色圆点表示支持，浅色圆点表示不支持。

下面是电子表格文件格式可以转换成其他格式的列表，第一列是源格式，从第二列到最后一列是可以转换成的其他格式，其中深色圆点表示支持，浅色圆点表示不支持。

下面是演示文稿格式可以转换成其他格式的列表，第一列是源格式，从第二列到最后一列是可以转换成的其他格式，其中深色圆点表示支持，浅色圆点表示不支持。

请求示例

接下来介绍一个把 docx 格式的文件转成 pdf 格式文件的请求示例：

{"async": false,"filetype": "docx","key": "Khirz6zTPdfd7","outputtype": "pdf","title": "test.docx","url": "https://example.com/url-to-example-document.docx"
}

返回结果：

<?xml version="1.0" encoding="utf-8"?>
<FileResult><FileUrl>http://101.200.154.81:9080/cache/files/conv_Kheirdze1d6zdT3dePedfd78_pdf/output.pdf/test.pdf?md5=RlFbt79mXSUBieoAbPrylw&amp;expires=1644924337&amp;disposition=attachment&amp;ooname=output.pdf</FileUrl><Percent>100</Percent><EndConvert>True</EndConvert>
</FileResult>

结尾

好了，如何利用 onlyoffice 实现文档格式转换的方法就介绍完了，是不是很简单。需要注意的是所有的转换请求参数都是 JSON 格式，但是返回结果是 XML 格式，这一点我们需要特别注意，避免解析失败。

参考链接：api.onlyoffice.com/editors/con…