OfficeReadCpp 是一个 C++20 Office 文档内容提取库，同时提供命令行工具。项目直接读取 OOXML ZIP 包与 OLE Compound File，不依赖 Microsoft Office、LibreOffice、COM 自动化或外部文档转换器。
它可从 Word、PowerPoint 和 Excel 文档中提取文本、Markdown 与嵌入图片，适合文档预览、归档、搜索索引以及 AI/RAG 预处理。
本项目是
OfficeRead_newGo 项目的 C++ 移植版。目前提供可构建、可运行的功能性移植基线；原项目中针对罕见损坏文件和特殊 Office 行为的全部边界用例，仍需持续做差分兼容。
- 支持
.docx、.pptx、.xlsx、.doc、.ppt、.xls。 - 提取清洗后的用户可见文本。
- 为 OOXML 和 legacy Excel 内容生成 Markdown。
- 提取包内媒体图片，并生成稳定、安全的输出文件名。
- 可选包含文档元数据。
- 提供严格 Office 内容与图片语义开关。
- 同时提供静态 C++ 库和
officeread命令行程序。
| 格式 | 容器/解析方式 | 当前提取内容 |
|---|---|---|
| DOCX | OOXML ZIP/XML | 正文、页眉页脚、脚注、尾注、批注、AltChunk HTML、媒体图片 |
| PPTX | OOXML ZIP/XML | 幻灯片、备注、母版/布局文本、图表文本、媒体图片 |
| XLSX | OOXML ZIP/XML | 工作表名称、shared/inline strings、单元格、Markdown 表格、批注/图表、媒体图片 |
| DOC | OLE CFB | WordDocument/Table 流的文本恢复、可识别图片 |
| PPT | OLE CFB | PowerPoint Document 流的文本恢复、可识别图片 |
| XLS | OLE CFB | Workbook/Book 流的文本恢复、简化 Markdown、可识别图片 |
- 支持 C++20 的编译器：MSVC、GCC 或 Clang。
- CMake 3.20 或更高版本。
- Ninja、Visual Studio 或其他 CMake 生成器。
- 首次配置时需要网络连接；CMake 会通过
FetchContent获取 miniz。
使用 Ninja：
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failure使用 Visual Studio：
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure安装到指定目录：
cmake --install build --prefix install基本用法：
officeread [options] file
| 参数 | 说明 |
|---|---|
-images DIR |
将提取的图片写入 DIR |
-metadata |
包含文档属性等元数据 |
-markdown |
输出 Markdown；未指定图片目录时默认使用 images |
-text-only |
不在标准错误中输出图片数量 |
-strict-office-images |
启用严格 Office 图片语义选项 |
-strict-office-content |
限制 OOXML 文本为主要文档内容 |
-h, --help |
显示帮助 |
示例：
build\officeread.exe sample.docx
build\officeread.exe -markdown -images images sample.xlsx > sample.md
build\officeread.exe -metadata sample.pptx
build\officeread.exe -strict-office-content sample.docx文本写入标准输出；诊断信息和图片数量写入标准错误。成功时退出码为 0，参数错误为 2，读取或解析失败为 1。
#include <officeread/officeread.hpp>
#include <iostream>
int main() {
officeread::Options options;
options.image_dir = "images";
options.include_metadata = false;
try {
const auto result = officeread::extract("sample.docx", options);
std::cout << result.text << '\n';
std::cout << result.markdown("images") << '\n';
std::cout << "images: " << result.images.size() << '\n';
} catch (const std::exception& error) {
std::cerr << error.what() << '\n';
return 1;
}
}完整的类型、字段、异常和使用约定见 API 文档。
add_subdirectory(path/to/OfficeReadCpp)
target_link_libraries(your_target PRIVATE officeread)然后在代码中包含：
#include <officeread/officeread.hpp>仓库提供抽样脚本，可将 C++ 结果与本机的 Go 原项目比较：
powershell -ExecutionPolicy Bypass -File tools/differential.ps1 `
-Source D:\workprj\OfficeRead_new `
-PerFormat 10脚本覆盖六种格式，并在 Go 输出非空而 C++ 输出为空时返回失败。
include/officeread/ 公开 C++ 头文件
src/ OOXML、OLE、文本和图片实现
cmd/ officeread 命令行程序
tests/ CTest 测试
testdata/ 本地回归样本、异常样本和 Go 测试参考文件
tools/ 差分验证脚本
docs/ API 文档
testdata/samples 含六种 Office 格式的核心回归语料，testdata/negative
含损坏或异常输入，testdata/web-samples-smoke 含小规模网络样本冒烟集合。
testdata/reference 保存原 Go 项目的测试源码与基线报告，供后续逐项移植断言；
这些 .go 文件仅作为参考，不参与 C++ 构建。完整的多 GB web-samples 大语料未纳入本仓库。
- 不解密密码保护的 Office 文档。
- 不还原完整 Office 对象模型、布局、样式、公式计算或宏行为。
- Legacy DOC/PPT/XLS 采用 OLE 流和安全字符串恢复；复杂二进制记录的语义覆盖低于 OOXML。
strict_office_images已保留在兼容 API 中；当前实现并非对所有格式都能完整复刻 Microsoft Office Picture Shape 计数。- XML、ZIP、OLE 流设置了大小与链遍历约束，但仍应把不可信文件放在资源受限的进程中处理。
- 图片文件会写入
Options::image_dir；调用者应选择有权限且不会覆盖重要文件的目录。
仓库当前未包含许可证文件。在明确许可证前，请勿假设拥有分发或再授权权利。