Officia 文档处理套件

主题

快速开始 ​

3 分钟把第一个文档转成 PDF。

💡 想先看效果、不想动代码？ 打开 Officia 能力测试台， 直接上传你自己的 doc/docx/xlsx/pptx/pdf/图片/eml 当场跑一遍（评估版：带水印、限 30 页； 上传件只在内存、重启即清，勿传涉密文档）。

环境要求 ​

  • JDK 17+（Officia 以 Java 17 为基线）
  • Maven 或 Gradle

1. 引入依赖 ​

引入聚合包 officia-all 即获得全部能力（对标 hutool-all）：

xml
<dependency>
  <groupId>plus.ruoyi</groupId>
  <artifactId>officia-all</artifactId>
  <version>1.1.3</version>
</dependency>
groovy
implementation 'plus.ruoyi:officia-all:1.1.3'

这是唯一需要引的依赖。 officia-all 是聚合了全部能力的单一 jar，授权客户端 （OfficiaLicense）也已内置，不需要再单独引 officia-license 或任何 officia-* 子模块—— Maven Central 上只发布 officia-all 这一个构件，引其它坐标会解析失败。

它也不带任何第三方传递依赖：mvn dependency:tree 下只有它自己。

2. 第一个 PDF ​

java
import plus.ruoyi.officia.words.OfficiaWords;
import java.nio.file.Files;
import java.nio.file.Path;

public class Demo {
    public static void main(String[] args) throws Exception {
        byte[] docx = Files.readAllBytes(Path.of("hello.docx"));
        byte[] pdf  = OfficiaWords.toPdf(docx);          // Word → PDF
        Files.write(Path.of("hello.pdf"), pdf);
        System.out.println("生成成功，大小 " + pdf.length + " 字节");
    }
}

运行后得到 hello.pdf。若未加载授权，输出会带评估水印并限制页数 —— 这是正常的评估态。

3. 加载授权（可选，去水印） ​

购买后你会得到一个 officia.lic 文件。放到约定位置即可，零代码自动加载：

  • 放进 classpath：src/main/resources/officia.lic
  • 或放工作目录：./officia.lic
  • 或设环境变量：OFFICIA_LICENSE=<路径或令牌>

Officia 首次使用能力时自动查找并离线验签，加载成功即去除水印、解锁全部授权模块。详见 授权与加载。

4. 更多能力 ​

java
// Excel → PDF
byte[] pdf = OfficiaCells.toPdf(Files.readAllBytes(Path.of("report.xlsx")));

// Word → 图片，一页一张（文档在线预览）
List<byte[]> pages = OfficiaWords.toImages(docx);

// 合并多个 PDF
byte[] merged = OfficiaPdf.merge(List.of(pdfA, pdfB));

// 生成二维码 PNG
byte[] qr = OfficiaBarCode.qrPng("https://officia.ruoyi.plus");

// PDF 加 AES-256 加密
byte[] enc = OfficiaPdf.encryptAes256(pdf, "openpwd", "ownerpwd");

扫描件识别成文字（OCR） ​

图片或扫描件 PDF 没有文字层，OfficiaPdf.toWord 读不出内容，走 OCR 入口：

java
import plus.ruoyi.officia.ocr.OfficiaOcr;
import plus.ruoyi.officia.ocr.OcrOptions;
import plus.ruoyi.officia.ocr.scan.ScannedPdfConverter;
import plus.ruoyi.officia.ocr.recog.BuiltinModels.Language;

// 图片 → 文字
String text = OfficiaOcr.recognize(imageBytes,
        OcrOptions.defaults().setLanguage(Language.CHINESE));

// 扫描件 PDF → 可编辑 Word
byte[] docx = new ScannedPdfConverter()
        .language(Language.CHINESE)          // 必填，不填直接抛异常
        .toWord(pdfBytes);

语种必须显式指定

默认语种是英文，而中文扫描件走英文模型不会报错，只会吐出满篇拉丁噪声、 置信度反而更高。识别器在固定字符集上永远给出某个类别，没有「认不出」这一档—— 所以宁可在你不表态时响亮地失败。详见 Officia.OCR。

在浏览器里编辑 Word / Excel ​

要让用户在页面上直接改内容再存回文件，用 OfficiaEditor——不需要部署任何 Document Server。 （Officia.Editor 是 1.1.3 之后新增的模块，早于它的版本引不到，见 Officia.Editor。）

java
import plus.ruoyi.officia.editor.OfficiaEditor;
import plus.ruoyi.officia.editor.EditorDocument;
import plus.ruoyi.officia.editor.EditorFormat;

// 打开：交给前端的 officia-doc/1 JSON
EditorDocument doc = OfficiaEditor.open(docxBytes);
String json = doc.getJson();

// 保存：前端交回 JSON
byte[] saved = OfficiaEditor.save(json, EditorFormat.DOCX);   // 或 EditorFormat.PDF

// 工作簿是另一条闭环
String wbJson = OfficiaEditor.openWorkbook(xlsxBytes);
byte[] xlsx   = OfficiaEditor.saveWorkbook(OfficiaEditor.recalc(wbJson));

前端产物 officia-editor.js 随同一个 jar 分发，Servlet 3.0+ 容器自动暴露，直接引用即可：

html
<script src="/officia-editor/officia-editor.js"></script>
<script>
  const view = OfficiaEditor.mountEditable(document.getElementById('host'), json);
</script>

详见 Officia.Editor。

每个模块的完整方法见左侧「能力模块」。