OfficeExcel — Word / Excel DLL 验证台功能介绍

一款基于 Electron + C++ DLL 架构的桌面验证工具，统一桥接 sdtech_docx（Word）与 sdtech_xlsx v3.1（Excel），通过可视化 API 面板、结构树与只读预览，快速验证 OOXML 读写能力与前后端全链路。

一款基于 Electron + C++ DLL 架构的桌面验证工具，统一桥接 sdtech_docx（Word）与 sdtech_xlsx v3.1（Excel），通过可视化 API 面板、结构树与只读预览，快速验证 OOXML 读写能力与前后端全链路。

一、软件概览

OfficeExcel 面向 Office 文档库开发 与 集成联调 场景：前端 React 通过 Koffi 调用 backend.dll，Backend 再链接 sdtech_docx.dll / sdtech_xlsx.dll，对外暴露稳定的 C ABI 与 JSON 结构预览。

核心能力：

双文档类型：顶部切换 Word (.docx) / Excel (.xlsx)
DLL 工作台：分组 API 按钮，一键调用并记录调用日志
打开并解析：拖放或浏览文件，网格/段落预览 + 读写一致性检查
xlsx v3.1：图表、透视表、公式扩展、SXSSF flush、Agile/Standard 加密

Word 工作台

Word 工作台：API 操作区、文档预览、结构树与调用日志

二、架构

Frontend (Electron + React + Koffi)
        ↓
backend.dll  (sdtech_officeexcel_*)
        ↓
   ┌────┴────┐
sdtech_docx.dll   sdtech_xlsx.dll  (v3.1.0)
   ↓                    ↓
 OOXML / Word        OOXML / Excel

| 层级 | 说明 | |------|------| | Frontend | 无边框 Electron 窗口，三视图：工作台 / 打开文件 / 设置 | | Backend | 会话句柄映射（doc_id / xlsx_id），不暴露 C 指针到 JS | | sdtech_docx | Word OOXML 子集读写（段落、表格、图片、样式等） | | sdtech_xlsx | Excel 工作簿建模，对标 Apache POI XSSF 能力演进 |

三、主要功能

3.1 导航与文档类型

工具栏左侧为文档类型标签，右侧为页面导航：

| 入口 | 说明 | |------|------| | Word (.docx) | docx API 工作台与解析 | | Excel (.xlsx) | xlsx API 工作台与解析 | | 工作台 | 创建 / 打开 / 保存 / 各类写操作 API | | 打开文件 | 只读解析预览 + consistency 检查 | | 设置 | 配置持久化（%APPDATA%\OfficeExcel\config.json） |

状态栏显示 Backend DLL 加载状态及当前模式（docx / xlsx API）。

3.2 Word (.docx) 工作台

适用于验证 sdtech_docx 写入与结构回读。

典型 API 分组：

文档生命周期：docx_create / docx_open / docx_save / docx_destroy
内容块：段落、标题、表格、图片
样式：粗体、斜体、字体名等
结构预览：左侧树形结构 + 中间「纸张」预览 + 右侧属性

点击「调用」后，底部 调用日志 记录 API 名、参数 JSON 与成功/失败，便于对照 GTest 与 C API 文档。

3.3 Excel (.xlsx) 工作台 · v3.1

适用于验证 sdtech_xlsx 全量能力；面板标题为 「API 操作区 · xlsx v3.1」。

Excel 工作台

Excel 工作台：workbook_create 后可见 PreviewGrid 与 Sheet 结构树

工作簿与 Sheet：

| 能力 | 说明 | |------|------| | 创建 / 打开 / 保存 | 标准 xlsx 生命周期 | | 单元格 | 文本、数值、布尔、日期、公式 | | 合并 / 样式 | 字体、对齐、背景色、边框、数字格式 | | 行列 | 列宽、行高、冻结、筛选 | | 富文本 / 批注 / 超链接 / 图片 | 单元格级扩展 |

v3.0 流式 / 懒加载：

workbook_create_streaming(windowRows) — SXSSF 风格窗口行
workbook_open_lazy + load_sheet — 按需加载大文件

v3.1 深化（新增）：

xlsx v3.1 能力

| 模块 | API 示例 | 说明 | |------|----------|------| | 图表 | add_chart / get_charts | 类别轴 + 数值系列，读写 chart part | | 透视表 | add_pivot_table / get_pivot_tables | 数据源区域与落位 | | 公式引擎 | VLOOKUP、DATE、TODAY、YEAR/MONTH/DAY、CONCAT | 常用函数扩展 | | 流式 flush | flush_streaming_rows | streaming 工作簿落盘中间态 | | 加密 | workbook_open_encrypted / workbook_save_encrypted | Agile / Standard 加密 |

库版本常量：SDTECH_XLSX_VERSION_MAJOR/MINOR/PATCH = 3 / 1 / 0。

3.4 打开并解析

「打开文件」页提供只读解析链路，与写入工作台分离，便于对比「磁盘文件 ↔ 内存模型 ↔ UI 预览」是否一致。

打开 xlsx

界面分区：

左侧：拖放区 / 浏览文件，已解析文件信息
中间：docx 段落块预览或 xlsx 网格预览（PreviewGrid）
右侧：读写一致性检查（checks 列表）
底部：本页独立调用日志

支持 .docx 与 .xlsx；切换顶部文档类型标签即可更换过滤器与预览组件。

3.5 设置

设置页集中管理应用级选项（路径、显示等），写入 %APPDATA%\OfficeExcel\config.json，重启后保持。

四、使用流程示例

示例 1：快速验证 docx 写入

保持 Word (.docx) 标签选中，进入「工作台」
点击 docx_create 对应「调用」
依次调用 add_paragraph、add_heading 等 API
填写保存路径，点击「保存」或「另存为…」
切换到「打开文件」，浏览同一文件，查看预览与 consistency

示例 2：xlsx 图表与透视表（v3.1）

切换到 Excel (.xlsx)，workbook_create()
写入表头与数据单元格
展开 「v3.1 图表 / 透视表」，填写系列区域后调用 add_chart / add_pivot_table
保存 xlsx，在「打开文件」中重新打开验证结构树与预览

示例 3：加密工作簿

创建或打开工作簿
展开 「v3.1 流式 flush / 加密」
设置密码，调用 workbook_save_encrypted
使用 workbook_open_encrypted 重新打开验证

五、开发与构建

5.1 快速开始

cd Frontend
npm install
npm run sync-docx    # 同步 prebuilt/docx
npm run sync-xlsx    # 同步 prebuilt/xlsx
npm run backend      # 编译 backend.dll 并拷贝到 Frontend/dll
npm run dev          # 开发模式

5.2 打包桌面程序

cd Frontend
npm run backend
npm run dist
# 输出: Frontend/release/win-unpacked/OfficeExcel.exe

5.3 库层测试（GTest）

cd Libs/sdtech_xlsx
cmake --preset win-release
cmake --build build/win-release --config Release
ctest --test-dir build/win-release -C Release

XlsxPhaseDeepeningTest 等用例覆盖图表、透视、公式、加密、flush 等 v3.1 能力。

5.4 博文配图自动生成

pip install -r scripts/requirements-screenshot.txt

# 推荐：开发模式
python scripts/auto_screenshot.py --dev

# 或打包版
python scripts/auto_screenshot.py

# 已手动打开应用
python scripts/auto_screenshot.py --attach

截图保存至 Content/posts/2026/officeexcel-feature-intro/。详见源码 scripts/auto_screenshot.py。

六、技术特点

Electron + React：现代化桌面 UI，Hash 路由切换视图
Koffi 桥接：JS 直接加载 backend.dll，低延迟 API 调用
双库合一：同一壳层验证 docx / xlsx，减少重复工具链
JSON 预览协议：结构树、网格、consistency 统一由 Backend 序列化
prebuilt 协作：协作者可只检出含 prebuilt/ 的源码包，无需本地编译 docx/xlsx 库
版本对齐：Frontend → Backend → sdtech_xlsx C API 全链路已桥接 v3.1 新接口

七、目录结构（摘要）

OfficeExcel/
├── Frontend/           Electron + React 验证台
├── Backend/            sdtech_officeexcel → backend.dll
├── Libs/
│   ├── sdtech_docx/    Word 库 + gtest
│   └── sdtech_xlsx/    Excel 库 v3.1 + gtest
├── prebuilt/           SDK / docx / xlsx 预编译（打包用）
├── Content/posts/      功能介绍博文与配图
└── scripts/            auto_screenshot.py

八、系统要求

操作系统：Windows 10 及以上（64 位）
开发：Node.js 18+、CMake、MSVC、Windows SDK
运行：打包版已内置 Electron 运行时；开发版需先 npm run backend 生成 DLL

九、结语

OfficeExcel 将 Word / Excel 原生库能力 收敛到同一验证桌面：开发库时跑 GTest，联调 UI 时点按钮看预览与日志，发布前用「打开并解析」做一致性回归。若在使用中遇到问题或有 API 需求，欢迎反馈。