ONLYOFFICE DocumentBuilder 无头(headless)doc、xls、ppt文档生成、处理、转换 SDK 作者:马育民 • 2026-05-14 09:25 • 阅读:10000 # 介绍 **ONLYOFFICE DocumentBuilder** 是 ONLYOFFICE 官方提供的**服务端/无头(headless)文档生成与处理 SDK**,用来**不打开可视化编辑器,后台自动生成、修改、合并、转换 Word/Excel/PPT/PDF**,完全替代 Office COM、LibreOffice 无头、python-docx 硬写 XML 等方案。 - 产品形态:**独立可执行程序 + 多语言 SDK + REST API** - 运行模式:**无头/后台/无界面** - 核心价值:**模板+数据驱动生成企业级复杂格式文档**(合同、报表、红头、票据、PDF) - 一句话:**用代码/脚本控制 Office 排版,服务器批量生成高质量文档** --- # 定位与优势 ### ✅ 优势 1. **真 Office 内核排版**:和 ONLYOFFICE 编辑器完全一致,**100% 兼容 docx/xlsx/pptx,样式不跑版**(python-docx 经常排版错乱) 2. **模板驱动,零硬拼 XML**: - 先用 Word 画好模板(字体、颜色、表格、图片、页眉页脚) - 脚本只负责**填变量、循环表格、插入图片** 3. **跨平台无依赖**:Windows/Linux/macOS 都能跑,**不需要装 Office、不需要 LibreOffice**,单进程独立 4. **高性能+高并发**:单线程处理一个文档,内存可控,**支持批量生成、异步任务、负载均衡** 5. **全格式支持**: - 生成:**docx, xlsx, pptx, PDF, ODT, ODS, ODP** - 读取:doc, docx, rtf, odt, txt, xls, xlsx, csv, ppt, pptx… - 转换:25+格式互转(含 PDF/A、图片导出) ### ❌ 对比劣势 - **新版本不是免费开源商用**:**社区版仅限非商用,商用需授权** - 体积较大:依赖 Office 内核,比轻量库(如 python-docx)大 - 学习曲线:API 较丰富,复杂排版需熟悉 JS API # 典型应用场景 1. **企业合同生成**:模板 + 客户数据 → 自动生成盖章版 PDF 2. **财务报表**:Excel 模板 + 数据库数据 → 自动生成月报/季报 3. **红头文件**:固定红头模板 + 正文变量 → 政府/国企公文 4. **批量证书/票据**:循环生成学生证、发票、合格证 5. **PDF 表单填充**:生成带文本框/复选框的可填写 PDF 6. **文档转换服务**:用户上传 doc → 后台转 PDF 或图片 # 使用 ### 1)本地命令行(CLI)——最常用 - 下载安装 DocumentBuilder 包(Windows/Linux/macOS) - 写 **.docbuilder 脚本(JS)** - 命令行执行:`document-builder script.js` - 特点:**最简单、无依赖、直接跑脚本、适合自动化/定时任务** ### 2)SDK 集成(Python/Java/.NET/C++) - 各语言封装库,直接嵌入后端代码 - 例如 Python:`pip install document-builder`,然后 import 调用 - 特点:**深度集成业务代码、同步/异步、适合企业应用** ### 3)REST API(Web DocumentBuilder) - 依赖 **ONLYOFFICE DocumentServer(文档服务器)** - 发 POST 请求到 `/docbuilder`,传 JSON 参数和脚本 - 特点:**服务化、分布式、负载均衡、无需本地安装 DB** --- # 支持的文档类型与功能 ### ✅ 文档(Word,docx) - 文本、段落、字体、颜色、对齐、缩进、行距 - 表格(含合并单元格、边框、背景色) - 图片、形状、文本框、页眉页脚、页码 - 列表(有序/无序)、分栏、样式、目录 - **表单域**(文本框、复选框、下拉框)——可生成可填写 PDF ### ✅ 表格(Excel,xlsx) - 单元格、公式、样式、合并、边框、背景 - 行列插入删除、工作表管理 - 图表(柱状、折线、饼图等) - 数据透视表、条件格式 ### ✅ 演示(PPT,pptx) - 幻灯片、文本框、图片、形状、表格 - 版式、母版、动画(基础) ### ✅ PDF - 生成 PDF(从 docx/xlsx/pptx) - 打开/修改现有 PDF(含表单) - 导出页面为图片(PNG/JPG) # 8.2.0 是最后一个免费版 ### 1. 版本时间线 - **≤ 8.2.0**:**完全免费,无水印、无功能限制**,个人/商业均可自由使用(AGPL 开源+免费商业授权)。 - **≥ 8.3.0(2025 年 4 月后)**: - 免费版:生成文档**强制添加 ONLYOFFICE 水印** - 无水印:必须购买**商业授权**(按服务器/CPU 计费)。 ### 2. 官方确认 - ONLYOFFICE 社区论坛(2025-04-17):**8.2.0 是最后一个无水印免费版;8.3+ 免费版加水印,商业版需付费**。 - 下载限制:官网已**下架 8.2.0 直接下载链接**,仅提供最新版(带水印);需从 GitHub Releases 或第三方镜像获取 8.2.0 安装包。 ### 3. 8.2.0 免费版限制 - 无水印、无功能阉割 - 无商业使用限制(可用于企业生产环境) - 唯一约束:**禁止反编译、二次分发为付费产品**(遵循 AGPL 与商业授权协议)。 --- # 8.2.0 安装 GitHub官方下载: https://github.com/ONLYOFFICE/DocumentBuilder/releases 找 8.2.0 - Windows:`onlyoffice-documentbuilder-windows-x64-8.2.0.143.exe` - Linux:`.deb`/`.rpm` 包(8.2.0 版本) # JS API ### 1)全局入口:`builder` - `builder.OpenFile(path)`:打开模板 - `builder.SaveFile(format, path)`:保存为指定格式 - `builder.SetValue(key, value)`:设置变量(文本/数组/图片) - `builder.CloseFile()`:关闭文档 ### 2)文档对象:`api` - `api.GetDocument()` → 文本文档 - `api.GetWorksheet()` → 表格 - `api.GetPresentation()` → 演示 ### 3)文本文档:`ApiDocument` - `GetElement(index)`:获取段落/表格 - `CreateParagraph()`:新建段落 - `CreateTable(rows, cols)`:新建表格 - `InsertImage()`:插入图片 ### 4)表格:`ApiTable` - `GetCell(row, col)`:获取单元格 - `SetValue(text)`:设值 - `SetBorder()`:边框样式 ### 例子:.doc 转 .docx **注意:**文件路径必须是 **绝对路径**,否则报错 ``` builder.OpenFile("H:\1.doc"); builder.SaveFile("docx", "H:\1.docx"); builder.CloseFile(); ``` 转换命令: ``` docbuilder.exe "H:\convert_doc2docx.js" ``` ### 例子:.ppt 转 .pptx **注意:**文件路径必须是 **绝对路径**,否则报错 ``` builder.OpenFile("H:\1.ppt"); builder.SaveFile("pptx", "H:\1.pptx"); builder.CloseFile(); ``` 转换命令: ``` docbuilder.exe "H:\convert_ppt2pptx.js" ``` ### 例子:.xls 转 .xlsx **注意:**文件路径必须是 **绝对路径**,否则报错 ``` builder.OpenFile("H:\1.xls"); builder.SaveFile("xlsx", "H:\1.xlsx"); builder.CloseFile(); ``` 转换命令: ``` docbuilder.exe "H:\convert_xls2xlsx.js" ``` # Python 集成 两种方式: - 纯命令行调用:动态生成脚本,调用命令执行脚本**(推荐)** - 官方 Python SDK 调用:本质还是调用命令,而且又坑,不推荐 ### 例子 ```bash import subprocess import os def doc_to_docx(input_doc: str, output_docx: str) -> bool: """ 使用 ONLYOFFICE DocumentBuilder 将 doc 转 docx """ # 生成临时脚本(自动创建,不用手动写文件) script_content = f''' builder.OpenFile("{input_doc.replace('\\', '/')}"); builder.SaveFile("docx", "{output_docx.replace('\\', '/')}"); builder.CloseFile(); ''' # 写入临时 .js 脚本 script_path = "temp_convert.js" with open(script_path, "w", encoding="utf-8") as f: f.write(script_content) try: # 调用 DocumentBuilder result = subprocess.run( ["document-builder", script_path], check=True, capture_output=True, text=True ) print(f"✅ 转换成功:{output_docx}") return True except subprocess.CalledProcessError as e: print(f"❌ 转换失败:{e.stderr}") return False finally: # 删除临时脚本 if os.path.exists(script_path): os.remove(script_path) # ====================== 使用示例 ====================== if __name__ == "__main__": INPUT_DOC = "test.doc" # 你的旧格式文件 OUTPUT_DOCX = "test.docx" # 输出的新格式 doc_to_docx(INPUT_DOC, OUTPUT_DOCX) ``` # 替代方案 若需新功能且预算有限,可考虑 LibreOffice SDK、Apache POI 等免费工具。 --- # 总结 - **DocumentBuilder** 是 ONLYOFFICE 推出的**无界面、跨平台、高兼容**的文档自动化 SDK,适合服务器端批量生成/转换文档。 - **8.2.0 是最后一个完全免费(无水印、无功能限制)的版本**;8.3+ 免费版强制加水印,商业版需付费授权。 - 建议生产环境**留存 8.2.0 安装包并锁定版本**,以长期享受免费无水印的文档自动化能力。 需要我补充一份 8.2.0 版本在 Windows/Linux 下的离线安装包校验清单和静默部署脚本吗? 原文出处:http://malaoshi.top/show_1GW3JB2gtkFM.html