ONLYOFFICE DocumentBuilder 无头（headless）doc、xls、ppt文档生成、处理、转换 SDK-马育民老师

# 介绍

**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