帆软 .cpt → sight-report 网格报表 转换器

把帆软(FineReport)的 .cpt 报表批量转换成 sight-report 网格报表 XML。结构/数据绑定/ 扩展分组/参数/样式走确定性转换;无法确定性翻译的公式、条件高亮会降级处理并写进转换报告,交人工复核。

纯 Python 标准库,无第三方依赖。也有桌面图形界面(见 desktop/), 打包成单个可执行文件,不用装 Python:

① 添加文件/文件夹 → 映射数据源 → 选项

② 一键转换,逐张报表看结果

截图里的文件名、连接名均为演示用虚构数据,不含任何真实客户信息。

下载(免装 Python)

打 tag 时 GitHub Actions 会自动构建 Windows / macOS 桌面版并发布到 Releases:

• Windows:帆软报表转换器-<版本>-windows-x64.exe,单文件,双击运行(需系统已装 WebView2 Runtime,Win11/多数 Win10 自带)
• macOS:帆软报表转换器-<版本>-mac.zip,解压后是 .app,双击运行(未签名,首次打开需右键→打开)
• Linux:不出桌面 GUI(pywebview 依赖的 WebKitGTK 在多数发行版版本太旧),直接用下面的 CLI

也可以自己动手打包,见 desktop/README.md。

用法(CLI)

# 单个文件
python3 convert.py 某报表.cpt -o out

# 整个目录(递归找 .cpt)
python3 convert.py /路径/报表目录 -o out

# 带数据源映射等配置
python3 convert.py /路径/报表目录 -o out -c config.json

# 多 sheet 拆成多张独立报表(默认合并为一个多页签报表)
python3 convert.py 某报表.cpt -o out --split-sheets

多 sheet 报表

一个 .cpt 含多个 sheet 时,默认合并成一个多页签(tab).mrg(各 sheet 一个页签, dataset/parameter 等报表级共享)。单 sheet 报表输出不受影响。

想每个 sheet 拆成独立报表(旧行为):加 --split-sheets,或配置 "merge_sheets": false, 或桌面应用取消勾选「合并为多页签报表」。

输出

文件	内容
<名称>.mrg(合并)/ <名称>__<sheet>.mrg(拆分)	sight-report 网格报表(可导入设计器)
<名称>.report.md	转换报告:概览 + ⚠️待人工 + 🔶已降级(合并时各 sheet 的网格问题以 [sheet名] 前缀标注)
_summary.md	批量汇总表(转多张时)

配置

复制 config.example.json 为 config.json 修改。最重要的是 connection_map (帆软连接名→Sight Report 数据连接名称,按名称解析无需 id)。未在此配置的连接默认直接 沿用帆软原始连接名作为 dataSourceName;仅当 Sight Report 里的连接名称与帆软不同时才需要配置。 另有 length_divisor(行高列宽换算)、font_size_divisor(字号换算)两个标定常数, 导入后觉得尺寸/字号不合适时调它们。详见配置文件内注释。

内容自适应(wrap_mode / auto_width)

帆软的「页面设置>根据单元格内容自动调整」有三档(否/行高/列宽),默认「行高」, 单元格「其他」可逐格覆盖。转换器 1.1.1 及以前把所有单元格写死成不换行(＝「否」那一档), 内容超长在帆软里会撑高行、转过来却被截断 —— 从 1.2.0 起默认改为换行撑高,与帆软默认档一致。

开关	默认	说明
wrap_mode / --wrap-mode	row	row=换行撑高行;none=截断(1.1.1 及以前的行为)
auto_width / --auto-width	关	给所有列标 widthMode="auto"(按内容定宽,需 Sight Report 2.0.25+)
auto_width_max / --auto-width-max	无	配合上一项:每列宽度上限(pt);不给则由引擎按设计宽度推导

⚠️ auto_width 是整表一刀切,不是按帆软的单元格设置驱动。原因:那个设置在 .cpt XML 里的元素名/属性名/取值编码没有公开文档,手头也没有样例可比对,猜错会静默产出错版面。 转换时若在模板里发现疑似属性(名字含 adjust),会原样列进转换报告的「🔍 自适应取证」一节 —— 把那一节反馈给维护者,就能把这两个开关升级成按单元格设置逐格驱动。

能转什么

• 单元格网格:坐标、合并(colspan/rowspan)、从属隐藏格
• 数据列绑定、扩展方向(纵/横)
• 父格绑定:显式父格 → magic 单元格 left/top(小计行、交叉表的父子关系自动还原)
• 分组、汇总(sum/count/avg/max/min)
• 条件高亮(公式条件):背景色/字体色/加粗,含 cell/row/column scope;「满足条件后显示为某值」(ValueHighlightAction)→ newValue 规则(如空值显示 0)
• SQL 数据集:参数语法翻译(含动态 SQL ${if})、连接名→数据源映射
• 报表参数:名/默认值/类型推断/必填
• 查询面板:各类控件、下拉选项(含字典数据集)—— 详见 query-form-mapping.md
• 单元格字典(DictPresent:代码→名称)→ 值映射 facade;钻取/网页超链接 → <links>; 数据列过滤(字段=单元格/常量)→ filterCondition;内嵌图表(柱/折线/面积/饼)→ ECharts 图表(样式需核对)
• 查询面板 Year 年份控件 → 年份选择器
• 样式:字体、颜色、加粗、边框、行高列宽
• 公式翻译:帆软表达式 → MagicScript,同名同参数直接映射,改名/改写按语义处理, 参数不一致的函数(如 FIND 的 0/1-based 不同)故意不转,标红交人工,避免静默出错

📄 完整函数对照、参数核对依据、未映射清单,见 function-mapping.md。

转不了 / 需人工(转换报告会逐条标出)

• 含未映射函数的公式:逐格标 🔶,交人工/AI 处理
• 结构化条件高亮(靠 op 码比较):语义不确定,不硬猜,标 ⚠️ 交人工在设计器配;公式条件已自动转
• 未在 connection_map 显式配置的数据源:默认沿用帆软原始连接名(报告标 ⚠️ 提示核对); 若 Sight Report 里的连接名称不同,需在 connection_map 里配置对应关系
• 富文本/斜线表头:仅提取纯文本
• .frm 决策报表 → 仪表盘 .mrs(convert_frm.py,语义化转换而非 1:1 搬运,每张旁生成 .report.md 列出做了哪些优化/哪些要人工): 仪表盘图→KPI 指标卡;柱/线/面积/饼/雷达/区间图→chart 区块(组合图取带数据的系列、钻取地图→省级 map 区块)(单行多指标宽表自动反透视、类别字典并进 SQL); 报表块→table 区块(字典翻译/公式列并进 SQL、隐藏列与序号列去掉、合计行改合计数据集让占比列算对); 查询面板→过滤栏;控件坐标→行/列版面(KPI 行高 108、表格行自适应)。 结构自检 python3 test_frm_dashboard.py,单元测试 python3 test_frm_units.py。 数据取自隐藏报表块单元格的图表/仪表盘(=report0~H3、=sum(B4)、=D3/C3)会翻成 SQL 数据集;不可见的图表/报表块不再显示。 限制:内嵌静态数据集(加密)、仪表盘取值于报表块单元格、报表块内嵌图表单元格、数据取自报表块单元格的图表、 控件联动 JS 需人工;服务器数据集按同名引用,需在仪表盘里「引用公共数据集」。frm_mode:"off" 可恢复旧行为(只列为未转换)。
• 内嵌图表仅覆盖 柱/折线/面积/饼;仪表盘、地图、雷达、组合图等 → 占位文本 + 待人工
• 引用「服务器数据集」(NameTableData 但定义不在 .cpt 内)的字典/下拉/图表:给 --server-datasets (帆软 WEB-INF/resources/datasource.xml)才能解析,否则标待人工
• 钻取链接目标报表的 fileId 要导入后才有:只带 fileName+参数;可用配置 link_file_map 预置
• 子报表 / 填报:不处理

版本

版本号见 version.py(python3 convert.py --version)。桌面版启动时会检查更新清单, 有新版会在界面顶部提示,网络失败静默忽略。

已知局限

• 复杂分组小计的父格绑定靠位置自动推断,建议人工核对

License

MIT