更新记录

1.0.0（2026-10-30）

首个版本：多份 CSV/TSV 纵向合并，表头按列名对齐，列顺序不同也能合；union 取列并集（缺列补空并报出）与 strict 严格一致两种策略；主键去重支持保留首条/末条，重复与空主键分别计数；来源列插在最前，与已有列重名时自动加后缀；数值列自动合计（求和/条数/平均/最小/最大，金额两位小数）；合并报告列出每份表行数、并入行数、缺列、只在部分表出现的列；结果导出 5 列以上 CSV 带 BOM；读文件支持 GBK 等指定编码。UTS→Kotlin 编译通过（index.kt 1148 行、classes.dex 44,596 字节），71 项回归测试全部通过；真机未执行（测试机安全锁屏，未提供解锁口令），市场截图为 H5 渲染并标注示例数据。

平台兼容性

uni-app

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
×	√	×	×	√	×	√	×	×

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
×	×	×	×	×	×	×	×	×	×	×	×

多表合并汇总（多份 CSV 并一张）

给做月度汇总、多分公司台账、多批导出的你：几份 CSV / TSV 进来，一张总表出去。表头按列名对齐，列顺序不一样也能合；缺的列自动补空并单独报出来，不静默丢列。

给谁用

财务/仓储：深圳仓、江门仓、东莞仓各交一份月报，要并成一张交上去；
采购：三家供应商的报价表列名不完全一样，先并起来再统一看；
实施：客户分批导出、每次只有几千行，攒几批合成一份再导入；
开发：多个接口分页导出的 CSV，合成一份做数据核对。

能做什么

能力	说明
按列名对齐	列顺序不同也能合，不按位置硬拼（按位置拼是“看起来对了但数据错位”的典型事故）
两种表头策略	`union` 取列并集，缺列补空并报出；`strict` 要求列完全一致，不一致直接报错并指出缺哪列
主键去重	指定主键列，重复行保留先出现或后出现，重复数与空主键数分别计数
来源列	插一列记录每行来自哪份表，主键重复时能回溯原始文件
数值合计	整列都能当数字才统计，输出求和/条数/平均/最小/最大，金额保留两位
合并报告	每份表行数、并入行数、缺列、多出列、只在部分表出现的列
导出	合并结果写 CSV，带 BOM，Excel 双击不乱码
编码	读文件可指定编码，GBK 报表直接传 `GBK`

快速接入

import { mergeTexts, mergeFiles } from '@/uni_modules/szhzy-table-merge'

// 1. 几段表文本直接合
const r = mergeTexts({
  texts: [szCsv, jmCsv, dgCsv],
  names: ['深圳仓-10月.csv', '江门仓-10月.csv', '东莞仓-10月.csv'],
  headerMode: 'union',      // 默认取列并集
  sourceColumn: '来源',      // 插入来源列（不需要就传空串）
  summarize: true            // 统计数值列
})
// r.headers  合并后的列名
// r.rows     合并后的数据行（二维数组，与 headers 一一对应）
// r.tables   每份表的贡献：rows / merged / missing / extra / duplicated / emptyKeys
// r.sums     数值列汇总：column / sum / count / avg / min / max
// r.summary  给人看的报告文本

// 2. 选几个文件合，顺手把总表写出去
const f = mergeFiles({
  paths: [path1, path2, path3],
  charset: 'UTF-8',
  sourceColumn: '来源',
  keyColumn: '编号',      // 按编号去重，重复保留第一条
  writeCsv: true,
  fileName: '三仓合并-10月.csv'
})

所有接口返回统一信封 { ok, code, message, ... }，不抛异常。code 取值：SUCCESS、EMPTY、NO_HEADER、HEADER_MISMATCH、KEY_NOT_FOUND、TOO_LARGE、READ_FAILED 等。

参数

参数	类型	默认	说明
`headerMode`	string	`union`	`union` 取并集；`strict` 要求所有表列一致
`keyColumn`	string	空	去重主键列名，空则表示不去重
`keep`	string	`first`	主键重复时保留 `first`（先出现）或 `last`（后出现）
`sourceColumn`	string	空	来源列名，空表示不加这一列
`summarize`	boolean	`true`	是否统计数值列
`delimiter`	string	`,`	输出分隔符，TSV 传 `\t`
`charset`	string	`UTF-8`	读文件时使用的编码
`writeCsv`	boolean	`false`	是否写出 CSV
`bom`	boolean	`true`	写 CSV 时是否带 UTF-8 BOM

和同系列插件怎么分工

插件	输入 → 输出
本插件多表合并	N 份表 → 1 张表（纵向追加）
表格差异比对	2 份表 → 差异清单（按主键找不同）
Excel 导入	1 份表 → 校验后的结构化数据
Excel 导出	结构化数据 → 1 份 Excel

常见链路：多批导出 → 合并 → 两版对比 → 差异清单。

购买前必读

只做纵向追加，不做横向关联（按主键 join）。要两边字段拼一起、或按主键比对，用表格差异比对；
列对齐只做「精确（去空白）→ 忽略大小写」两级，不做包含匹配。这是刻意的：合并时按包含匹配会把「单价」错配到「不含税单价」，宁可不合也不能合错；
数值合计只认「整列都能当数字」的列。一列里混了「合计」「小计」这类文字就不统计，避免算出一个看着像真的假数；
单份表超过 50,000 行、单文件超过 16 MB 会报错，请先分片；
主键为空的行不参与去重（保留并计数），不会因为空键把不同记录合成一条。

验证状态

项	结果
UTS → Kotlin 编译	通过（`项目 demo-table-merge 编译成功`，index.kt 1148 行，classes.dex 44,596 字节）
纯逻辑回归测试	71 项全部通过（`dev-tools-uts/verify/table-merge/run-tests.mjs`）
真机运行	未执行。本版开发时测试机处于安全锁屏且未提供解锁口令，无法操作界面，文件选择、`content://` 读取、写出目录三条链路只有编译期保证
真机截图	未取得。市场截图为 H5 渲染（同一份演示工程、同一份示例数据），页面标注「示例数据」

未验证的部分不会写成「已支持」：文件读写链路请在自定义基座上自行验收一次再上线。

平台支持

uni-app（Vue3）+ Android 6.0 及以上：支持
iOS / 鸿蒙 / 小程序 / H5：不支持（本版只有 Android 平台实现）
需要打自定义基座：标准基座不含 UTS 插件

权限与隐私

不申请任何系统权限，不联网，不上传，不写日志。读取走调用方用系统文件选择器交过来的路径或 content:// 授权；写出默认落应用外部私有目录（Android/data/<包名>/files/documents）。

常见问题

Q：两份表列名一样但顺序不同，会合错吗？ A：不会。按列名建立映射后再逐列取值，与列的位置无关。

Q：某份表没有「备注」列，合并后那几行是什么？ A：补空。报告里会把这份表的缺列列出来（tables[i].missing），不会悄悄吞掉。

Q：为什么不分页处理超大文件？ A：单份超过 5 万行建议先在服务端分片。移动端内存有限，硬扛大文件最后是闪退，不是慢。