帆软 .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
