使用OnlyOffice进行文件格式转换
前言
在现代应用开发中，文档的处理和转换是非常常见的需求。OnlyOffice提供了强大的API，可以将Docx文档转换为多种格式，如PDF、PPTX、XLSX等。通过OnlyOffice API，我们可以轻松实现文档转换功能，满足不同应用场景的需求。本文将详细介绍如何使用OnlyOffice API将Docx文档转换为其他格式文件，并提供实际的代码示例。
一、OnlyOffice API简介
ONLYOFFICE 提供了一个强大的文档转换服务，可以将多种文档格式转换为目标格式。常见的目标格式包括 PDF、ODT、PNG 等。通过调用 ONLYOFFICE 的转换服务接口，用户可以高效地处理文档格式转换任务。
官方文档：https://api.onlyoffice.com/docs
二、转换流程概述
OnlyOffice文档转换的流程可以分为以下几个步骤：
- 构建请求参数：需要提供文件类型、输出类型、文件唯一标识、文件标题、文件下载链接等信息。
- 生成JWT令牌：通过JWT工具生成令牌，用于身份验证。
- 创建HTTP请求：使用OkHttp发送POST请求到OnlyOffice的服务端。
- 处理转换请求：接收响应，检查转换状态，获取最终文件URL。
- 轮询转换进度：在转换过程中保持活跃，直到转换完成或超时。
三、请求参数详解
OnlyOffice API转换请求需要以下参数：
1. 基本参数
- filetype（输入文件类型）
- 描述：指定需要转换的文件的输入格式。
- 支持值：
docx：文档文件（Word文档）xlsx：电子表格文件（Excel文件）pptx：演示文稿文件（PowerPoint文件）txt：文本文件csv：逗号分隔值文件html：超文本标记语言文件pdf：PDF文件etc.：其他文件格式
- 示例：filetype: “docx” 表示将Word文档转换为其他格式。
- outputtype（输出文件类型）
- 描述：指定转换后的文件格式。
- 支持值：
pdf：将文档转换为PDFpptx：将文档转换为PowerPoint格式xlsx：将文档转换为Excel格式odf：将文档转换为开放文档格式bmp：将文档转换为位图文件gif：将文档转换为GIF图像文件jpg：将文档转换为JPEG图像文件png：将文档转换为PNG图像文件etc.：其他文件格式
- 示例：outputtype: “pdf” 表示将文档转换为PDF。
- key（文件唯一标识）
- 描述：用于标识文件，确保请求的唯一性。
- 示例：key: “Khirz6zTPdfd7” 表示文件的唯一标识为documentKey。
- title（文件标题）
- 描述：用于返回转换结果的文件标题，便于管理和显示。
- 示例：title: “Example Document Title.docx” 表示文件标题为Example Document Title.docx。
- url（文件下载链接）
- 描述：提供文件的完整URL，用于获取原始文件。
- 示例：url:
https://example.com/url-to-example-document.docx表示文件的下载链接为https://example.com/url-to-example-document.docx。
2. 高级参数
- shardkey（分片标识）
- 描述：用于负载均衡，推荐从版本8.1开始在URL QueryString中添加。
- 示例：?shardkey=documentKey。
- documentLayout（文档布局）
- 描述：定义文档布局，用于设置打印形式或表单布局。
- 子参数：
drawPlaceHolders：布局占位符绘制状态。drawFormHighlight：表单高亮状态。isPrint：打印模式状态（仅适用于将docx/docxf转换为pdf时）。
- documentRenderer（文档渲染设置）
- 描述：定义文档渲染设置，用于控制文本呈现方式。
- 子参数：
textAssociation：文本呈现模式（blockChar、blockLine、plainLine、plainParagraph）。
- pdf（PDF转换设置）
- 描述：定义PDF转换的设置，包括是否为表单PDF、是否添加水印等。
- 子参数：
form：是否为表单PDF（true或false）。watermark：水印设置，包括位置、颜色、透明度等。
- spreadsheetLayout（电子表格布局设置）
- 描述：定义电子表格转换为PDF的布局设置。
- 子参数：
ignorePrintArea：忽略打印区域状态。orientation：页面方向（portrait或landscape）。fitToWidth、fitToHeight：适应页面宽度和高度。scale：PDF缩放比例。headings：是否显示页眉页脚。gridLines：是否显示表格格线。pageSize：页面尺寸设置。margins：页面边距设置。
- thumbnail（缩略图设置）
- 描述：定义生成缩略图的设置。
- 子参数：
aspect：缩略图的比例模式（0、1、2）。first：是否只生成首页缩略图。height、width：缩略图的高度和宽度（像素）。
- watermark（水印设置）
- 描述：定义在PDF或图片中添加的水印设置。
- 子参数：
align：水印的对齐方式（0、1、2、4）。fill：水印的填充颜色（RGB格式）。height、width：水印的高度和宽度（毫米）。rotate：水印的旋转角度。transparent：水印的透明度。type：水印的形状类型（rect、ellipse等）。stroke-width：水印的边框宽度。stroke：水印的边框颜色。
四、具体转换流程
1. 生成JWT令牌
JWT令牌用于身份验证，确保请求的合法性。
- 基本参数：async、filetype、key、title、url。
- 高级参数：根据需求添加shardkey（负载均衡）、documentLayout、documentRenderer、pdf、spreadsheetLayout、thumbnail、watermark等参数。
- 生成JWT令牌：使用API密钥和请求参数生成JWT令牌，用于身份验证。
2. 创建HTTP请求
使用OkHttp创建HTTP POST 请求，发送JSON格式的请求参数。
- 构建请求对象：使用OkHttp或其他HTTP客户端库，构建包含必要参数的HTTP POST请求。
- 添加请求头：设置Content-Type为application/json，Accept为application/json。
- 发送请求体：将生成的JSON请求参数作为请求体发送到OnlyOffice服务端。
3. 处理转换请求
接收响应后，检查转换状态。
- 检查响应状态：确认响应是否成功，处理成功或失败的状态码。
- 解析JSON响应：提取转换结果，获取最终文件的URL或状态信息。
- 处理转换进度：如果转换是异步的，定期轮询转换状态，直到转换完成或超时。
以下是处理响应的示例代码：
public String handleConversionRequest(OkHttpClient okHttpClient, Request request) {
// 用于存储转换后的文件URL，初始值为null
String fileUrl = null;
// 尝试发送HTTP请求并接收响应
try (Response response = okHttpClient.newCall(request).execute()) {
// 判断响应是否成功
if (!response.isSuccessful()) {
log.error("转换失败: " + response);
return null;
}
// 获取响应体的字符串内容
String result = response.body().string();
// 使用JSON工具将响应字符串解析成JSON对象
JSONObject jsonObject = JSONUtil.parseObj(result);
// 获取“endConvert”字段的值，判断文档是否已经转换完成
Boolean endConvert = jsonObject.getBool("endConvert");
// 如果转换完成，获取文件URL并赋值给fileUrl
if (endConvert) {
fileUrl = jsonObject.get("fileUrl", String.class);
} else {
// 如果转换未完成，调用轮询方法检查转换进度
fileUrl = pollForConversionProgress(okHttpClient, request);
}
} catch (Exception e) {
// 捕获任何异常并记录错误日志
log.error("文件转换过程中出错: ", e);
}
// 返回最终获取的文件URL，或者如果失败返回null
return fileUrl;
}
4. 轮询转换进度
在转换过程中，可能需要轮询检查转换进度以避免长时间等待。
- 设置轮询间隔：在转换过程中，保持对服务器的连接，定期发送请求以获取最新的转换进度。
- 处理进度信息：解析返回的进度数据，更新UI或日志，显示转换进度。
- 终止轮询：当转换完成或达到超时限制时，停止轮询，获取最终结果。
五、转换示例
public static void main(String[] args) {
// 输入文件类型为Docx
String fileType = "docx";
// 输出文件类型为Pdf
String outputType = "pdf";
// 文件的唯一标识符
String key = "documentKey";
// 文件标题
String fileName = "Example Document Title.docx";
// 文件的下载链接
String downloadUrl = "https://example.com/url-to-example-document.docx";
// 构建请求参数
Map<String, Object> params = buildRequestParams(fileType, outputType, key, fileName, downloadUrl);
// 生成JWT令牌用于身份验证
String token = generateJwtToken(params);
// convertUrl 为 onlyOffice的转换api完整接口地址
// onlyOfficeUrl 为 onlyOffice服务地址 例如：https://documentserver
String convertUrl = onlyOfficeUrl + "/converter";
// 使用OkHttp创建HTTP POST请求
Request request = buildHttpRequest(convertUrl, token);
// 发送请求并处理响应
String fileUrl = handleConversionRequest(okHttpClient, request);
// 打印转换完成后的文件URL
System.out.println("转换完成，文件URL: " + fileUrl);
}
- DOCX 转 PDF： 发送一个包含 DOCX 文件信息的 JSON 请求，指定输出为 PDF 格式。
{
"async": false,
"filetype": "docx",
"key": "documentKey",
"outputtype": "pdf",
"title": "Example Document Title.docx",
"url": "https://example.com/url-to-example-document.docx"
}
- XLSX 转 PPTX： 发送一个包含 XLSX 文件信息的 JSON 请求，指定输出为 PPTX 格式。
{
"async": false,
"filetype": "xlsx",
"key": "documentKey",
"outputtype": "pptx",
"title": "Example Spreadsheet Title.xlsx",
"url": "https://example.com/url-to-example-spreadsheet.xlsx"
}
- 带水印的 DOCX 转 PDF： 如果需要在转换后的文件中添加水印，可以在请求中加入 watermark 字段，设置水印样式。
{
"async": false,
"filetype": "docx",
"key": "documentKey",
"outputtype": "pdf",
"title": "Example Document Title.docx",
"url": "https://example.com/url-to-example-document.docx",
"watermark": {
"align": 1,
"fill": [255, 0, 0],
"height": 100,
"margins": [10, 10, 10, 10],
"paragraphs": [
{
"align": 2,
"fill": [255, 0, 0],
"linespacing": 1,
"runs": [
{
"bold": true,
"font-family": "Arial",
"font-size": 40,
"text": "Watermark"
}
]
}
],
"rotate": -45,
"transparent": 0.3,
"type": "rect",
"stroke-width": 1,
"stroke": [0, 0, 255],
"width": 100
}
}
总结
通过上述步骤，我们可以轻松实现文档格式转换。ONLYOFFICE 提供的 API 使得转换过程更加高效和灵活，支持多种文档格式以及详细的自定义选项，如水印、页面布局等。
在实际应用中，我们可以根据需求进行更加细致的配置，满足不同场景的需要。