ONLYOFFICE DocumentBuilder 无头（headless）doc、xls、ppt文档生成、处理、转换 SDK

作者：马育民 • • 阅读：10081

介绍

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 调用：本质还是调用命令，而且又坑，不推荐

例子

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 下的离线安装包校验清单和静默部署脚本吗？

原文出处：/show_1GW3JB2gtkFM.html

吉ICP备15003043号