更新记录

1.0.0（2026-10-29）

首个版本：解析 docx 主文档（段落、标题层级、表格行列与合并单元格、字数统计）；表格抽取支持横向合并展开/紧凑两种模式、纵向合并向下填充、空行过滤；导出 CSV/TSV（引号转义、UTF-8 BOM）；字段映射支持表头名、#列序号、包含匹配三种方式；多份文档批量汇总并附来源文件名；正文与单元格全文检索带上下文；9 个具名错误码；纯逻辑零依赖、不申请存储权限。UTS→Kotlin 编译通过（index.kt 2091 行、86 个函数），68 项回归测试全部通过（含 python-docx 生成的真实 docx 主文档部件解析）；真机未执行（本轮无可用设备）。

平台兼容性

uni-app

szhzy-docx-read

把 Word（.docx）里的表格和正文抽成结构化数据：读骨架、抽表格、导 CSV、批量汇总、全文检索。 零三方依赖，纯本地解析，不联网、不上传。

适用场景：合同台账汇总、供应商报价单归集、点检/验收记录批量入库、单据归档前的字段核对。

验证状态

真机未验证的部分：Android 平台层的 zip 解包（ZipFile）、content:// 授权 URI 转缓存、CSV 落盘路径。 这三处只有编译期保证，接入前请在自己的设备上先跑一遍「选文件 → 抽表 → 导出 CSV」。

它不做什么

• 不解析老版 .doc（二进制格式），也不解析 .docm 里的宏；请在 Office/WPS 里另存为 .docx。
• 不抽取页眉、页脚、脚注、尾注、批注、文本框里的内容，只处理正文主体。
• 不做 OCR：扫描件 PDF/图片里的字读不出来。
• 不还原复杂版式（分栏、文本框绕排、艺术字），只关心文字与表格结构。
• 不写 Word，只读。要生成 docx 请用 szhzy-docx-report。

快速开始

import { inspect, readTable, exportCsv, batchExtract } from '@/uni_modules/szhzy-docx-read'

// 1) 先看这份文件里有什么（表格数量、每张表的行列、标题清单）
const info = inspect({ path: filePath })
if (!info.ok) {
  console.log(info.code, info.message) // NOT_DOCX / FILE_NOT_FOUND / NO_TABLE ...
}
console.log(info.stats.tables, info.tables.map((t) => t.header))

// 2) 抽第 2 张表（下标从 0 开始），首行当表头
const table = readTable({ path: filePath, tableIndex: 1, limit: 20 })
console.log(table.headers) // ['合同与供应商', '', '金额（元）', ...]
console.log(table.rows[0].cells)

// 3) 只导需要的列并改名，落成 CSV（带 BOM，Excel 双击不乱码）
const csv = exportCsv({
  path: filePath,
  tableIndex: 1,
  fileName: '合同台账-2026-09',
  mapping: [
    { target: '合同编号', source: '合同与供应商' },
    { target: '金额', source: '金额（元）' },
    { target: '交期', source: '交期' }
  ]
})
console.log(csv.path, csv.rows)

// 4) 多份单据一次汇总，带上来源文件名
const batch = batchExtract({
  paths: [p1, p2, p3],
  tableIndex: 0,
  sourceColumn: '来源文件',
  fileName: '点检汇总'
})
console.log(batch.files, batch.rows, batch.skipped)

选文件用系统选择器即可，返回的路径或 content:// 授权 URI 都能直接传进来：

uni.chooseFile({
  count: 10,
  extension: ['.docx'],
  success: (res) => {
    const paths = res.tempFilePaths
    const out = batchExtract({ paths, tableIndex: 0, fileName: '汇总' })
  }
})

API

所有方法返回统一信封 { ok, code, message, ... }，不抛异常。

抽表参数

mapping 的 source 支持三种写法：表头名精确匹配 → #列序号（从 1 开始）→ 包含匹配兜底。 一个都对不上时直接返回 MAPPING_EMPTY，不会导出一张空表。

能力边界

• 只解析主文档部件 word/document.xml；页眉页脚、脚注、批注、文本框不在范围内。
• 嵌套表格：内层文字并入外层单元格，并在 warnings 里留 NESTED_TABLE@<表序号>，不单独成表。
• 修订痕迹：被删除的文字（w:del / w:delText）不计入正文。
• 单元格内多段：合并成一个空格分隔的字符串，避免 CSV 里出现裸换行。
• 不保证版式：列宽、字号、颜色、缩进等格式信息不解析。

错误码

演示工程

demo-docx-read/ 两个页面：

• 合同台账：读一份已生成的采购合同台账 docx，展示识别到的标题、两张表的规模、合并单元格展开结果与导出的 CSV 行；
• 点检记录：说明批量汇总的形态——多份点检记录同一张表拼成一行一条，附来源文件名。

预览环境（H5）用固定样本数据走通页面流程，结果卡会明确标注「预览环境」；安装到 Android 后同一次操作读的是真实文件。

授权

购买授权后可在自己的产品（含为客户定制的项目）中不限项目数、不限安装量使用。 源码授权另允许阅读与二次开发，但不得把插件本身（含修改版）再次分发或销售。详见 license.md。