简介面向Delphi/BCB XE开发者的水晶报表11 VCL控件包对应11 R2版本由国外开发者基于原版修改适用于在Delphi/C Builder环境中集成水晶报表的报表设计、数据导出与打印功能。压缩包共710个文件约5.43MB包含127个pas源码、101个hpp头文件、113个dcu编译单元以及dfm窗体、bmp位图、rpt报表模板、exe演示程序与帮助文档可完整支撑控件安装、界面定制和二次开发。另有DLL、DPK、BPK等工程与动态库文件便于编译安装到IDE。已有416人学习下载。需要留意的是该控件包与Embarcadero Sample Components中的TCalendar控件存在冲突可在Install Packages菜单中取消勾选相关采样组件后再行安装若你愿意动手修改冲突原作者也期待交流改进版本。资源整体结构紧凑适合需要快速集成报表能力的中级Delphi/BCB开发者。1. CrystalReport VCL 水晶报表 11维护老 Delphi 项目的报表引擎需要什么如果你还在维护十年前写的 Delphi/CBuilder 项目大概率遇到过这个场景客户电脑换了新运行时原来打印正常的单据突然报“找不到报表引擎”。CrystalReport VCL 水晶报表 11 就是一套面向 Delphi/BCB XE 的 VCL 封装组件它把水晶报表 11 的加载、数据库连接、参数传递、打印和导出能力收拢成一组控件让老代码可以在 IDE 里直接用 RPT 模板不必把全部报表重写。它适合两类人一类是从别人手里接管了包含大量 RPT 文件的老系统另一类是想用 Delphi 快速做单据打印又不想碰 HTML 报表。需要先说清楚它不做报表设计模板布局仍要回到水晶报表设计器里改。2. 安装与最小集成方案XE 下先跑通第一个模板2.1 组件包在 IDE 里的组装顺序拿到组件资源后第一步不是急着往项目里塞文件而是先在 Delphi/CBuilder XE 里把包编译安装一遍。常见做法是解压后找到CrystalReportVCL11目录里面有一个CrystalReportVCL.dpkDelphi 包或同名的.bpkCBuilder 包。在 IDE 菜单里打开File Open Project选中对应包文件右键项目管理器里的包节点执行Compile再执行Install。安装成功后组件面板里会出现一个新的标签页里面有报表控件入口。我一般会在虚拟机里先装一次干净的 XE把组件包编译通过再导入真实业务工程。这类 VCL 组件与 IDE 版本绑定非常紧直接拿旧工程里的文件复制到新机器会各种报错。组件包主要产物如下文件作用常见缺失表现CrystalReportVCL.dpk/.bpk编译源码包打开工程提示找不到包CrystalReportVCL.dcu编译后单元编译代码时无法解析TCrystalReport示例工程目录最小 RPT 预览例子没有它安装后不知道 API 调用顺序如果你用的是 BCB XE也就是 CBuilder XE编译.bpk时要注意链接模式。建议把运行时包设为“动态链接”不要静态链进 EXE。否则最后链接阶段会报一堆找不到的 BPL 符号实际都是静态编译造成的。2.2 最小 VCL 项目预览一个 RPT安装完成后打开 Delphi XE新建一个 VCL Forms 应用放一个按钮在按钮事件里写下面这段代码。这是整个集成的骨架后面所有动态传参、导出 PDF 都建立在它上面。procedure TForm1.Button1Click(Sender: TObject); var rpt: TCrystalReport; begin rpt : TCrystalReport.Create(nil); try rpt.ReportFileName : ExtractFilePath(Application.ExeName) templates/order.rpt; rpt.LogonServer : db-server\sqlexpress; rpt.DatabaseName : erpdb; rpt.UserName : report_user; rpt.Password : Report2024; rpt.PreviewWindow : True; finally // 注意在 PreviewWindow 关闭后rpt 对象才允许释放 rpt.Free; end; end;这段代码里有几个参数值得解释。ReportFileName是绝对路径很多人在这里用相对路径程序一旦用不同工作目录启动报表文件就找不到了。LogonServer和DatabaseName不是报表显示标题而是运行时数据库连接的服务器名和库名这两个值会覆盖 RPT 文件里保存的旧连接。UserName和Password建议单独做一个配置项不要硬编码在源码里因为报表维护时第一件事经常就是改账号。在 CBuilder XE 里写法只是语法不同对象模型完全一致TCrystalReport *rpt new TCrystalReport(NULL); try { rpt-ReportFileName ExtractFilePath(Application-ExeName) templates/order.rpt; rpt-LogonServer db-server\\sqlexpress; rpt-DatabaseName erpdb; rpt-UserName report_user; rpt-Password Report2024; rpt-PreviewWindow true; } __finally { delete rpt; }你可能会问为什么不在设计期把数据源配好非要运行时再传一遍因为老项目里的 RPT 文件经常被不同开发人员打开过文件里存储的连接信息可能指向一个已经不存在的测试库。运行时强制指定可以有效避免“同一套代码有人机器上正常有人机器上报表空白”的问题。2.3 数据库登录参数三处不统一就会出怪错搞懂数据库登录是水晶报表 VCL 集成里最磨人的一环。很多“报表打开后没有数据”“弹窗要输密码”“导出全是空页”的问题根源不是代码而是三处配置没对齐。第一处是 RPT 文件本身保存的连接信息。在水晶报表设计器里数据库专家里看到的服务器名、数据库名、表结构就是这一处。第二处是组件运行时传入的LogonServer、DatabaseName、UserName、Password。第三处是应用程序所在机器的 ODBC 或原生驱动配置。三处必须指向同一套数据否则运行时组件会尝试用文件里的默认连接去连连不上就弹数据库登录框。配置项存放位置常见错误服务器名/库名RPT 文件内 运行时赋值只改了运行时文件里还指向旧库登录账号/密码运行时赋值账号有权限但默认库不同导致表找不到驱动/字符集客户端 ODBC 或驱动配置缺少对应版本驱动报“无法定位数据库驱动程序”排查时可以这样先用水晶报表设计器打开 RPT确认它能正常预览再用 VCL 方式同样连接一次两者都成功再回到代码里传参。如果设计器能出数代码里报错重点检查运行时字符串是否有多余空格或反斜杠转义。业务系统里最经典的问题是把db-server\sqlexpress写成了db-server/sqlexpress组件当成了另一种协议连接自然失败。建议在做最小预览时不要急着把代码接到真实业务表单里。先建一个独立测试窗体把 RPT 路径、服务器名、库名做成输入框跑通一遍。等到报表能看到数据再去集成正式界面。这样后续排错时你就知道问题到底出在组件安装还是出在业务数据连接。3. 动态传参与公式字段让一张报表跑多种业务口径3.1 参数字段绑定三种传值方式的边界水晶报表模板里可以定义参数字段比如日期范围、仓库编码、客户分组。在 VCL 封装里运行时传参的接口各家封装稍有差异但常见做法是下面这种结构rpt.ParameterFields.Clear; rpt.ParameterFields.Add(StartDate, 2024-11-01); rpt.ParameterFields.Add(EndDate, 2024-11-30); rpt.ParameterFields.Item(WarehouseCode).Value : WH01;这里第一个坑就是Clear。如果你在代码里调用Clear它会清空报表里所有参数。后续Add又没把全部参数补上报表打开时会提示“缺少参数”或者直接用空值跑数据。我的习惯是只设置需要变化的参数不调Clear。报表里写死的参数保持文件默认值只有业务上会被外部指定的参数才运行时赋值。第二种传值方式是直接给Item索引赋值前提是参数已经在 RPT 文件里定义好rpt.ParameterFields.Item(StartDate).Value : FormatDateTime(yyyy-mm-dd, DatePicker1.Date);第三种是利用存储过程参数名对应。如果报表的数据源是存储过程传参方式更严格下一节单独说。德尔福代码里有一个容易忽略的点Value属性赋进去的是字符串还是日期类型。很多旧版封装内部会把值转成字符串传给水晶报表引擎中文系统下日期格式就变成2024-11-30或2024年11月30日。如果数据库字段是datetime字符串解析失败报表就可能查不出数据。稳妥做法是统一传yyyy-mm-dd字符串并让数据库端理解这种字面量格式。3.2 公式字段与存储过程配合参数顺序决定结果老系统里大量报表直接用存储过程作为数据源这时候传参不能走ParameterFields而要走到存储过程参数集合上。常见接口类似这样rpt.ReportFileName : ExtractFilePath(Application.ExeName) reports/sales_summary.rpt; rpt.StoredProcName : usp_SalesSummary; rpt.StoredProcParams.Add(BeginDate, 2024-11-01); rpt.StoredProcParams.Add(EndDate, 2024-11-30); rpt.StoredProcParams.Add(OrgID, 1001);这里有一条教科书不会告诉你的规则存储过程参数顺序必须和 RPT 文件里定义的数据库字段顺序一致。很多时候报表能打开但数据为空就是因为OrgID放在了BeginDate前面而 RPT 文件里的 SQL 命令是按旧顺序传入的。遇到参数顺序问题我一般会把存储过程改成这样给每个参数都提供默认值并且只返回一个公认的结果集。CREATE PROCEDURE usp_SalesSummary BeginDate DATETIME NULL, EndDate DATETIME NULL, OrgID INT -1 AS BEGIN SET NOCOUNT ON; SELECT ... WHERE SaleDate ISNULL(BeginDate, 1900-01-01) AND SaleDate DATEADD(DAY, 1, ISNULL(EndDate, GETDATE())) AND (OrgID -1 OR OrgID OrgID); END这样做的目的是让 RPT 文件在预览模式下也有数据。设计器里如果直接运行存储过程不填参数会报错填了空值又查不到数据有了默认值报表文件至少能在设计器里先出一次数确认字段绑定没问题。再回到 VCL 里动态修改参数业务侧只传真正要过滤的条件。需要警惕的是存储过程返回多个结果集时水晶报表只认第一个结果集。如果你在存储过程里先做了一个SELECT xx打印日志再查正式数据报表拿到的数据源就会错位。处理办法是严格保持第一个SELECT就是业务数据集所有变量计算放到前面或者用SET语句完成。3.3 多层嵌套子报表的传参顺序子报表是水晶报表里最容易让人踩坑的地方。主报表有一个参数子报表也有一个参数甚至子报表里还嵌套了子报表。VCL 封装通常提供子报表集合访问入口var i: Integer; begin for i : 0 to rpt.SubreportCount - 1 do begin rpt.Subreport[i].ParameterFields.Item(OrgID).Value : CurrentOrgID; end; end;这段代码表面上会循环所有子报表把每个子报表里的OrgID都改掉。实际运行中如果某个子报表里并没有定义OrgID访问Item(OrgID)可能直接抛异常。更稳妥的做法是先判断字段是否存在if rpt.Subreport[i].ParameterFields.IndexOf(OrgID) 0 then rpt.Subreport[i].ParameterFields.Item(OrgID).Value : CurrentOrgID;给子报表传参的另一个注意点是执行顺序。子报表的数据查询发生在主报表渲染到对应区域时所以必须在PreviewWindow调用之前把所有子报表参数都设置完。如果你在报表已经开始预览后再修改子报表参数界面往往不会刷新。个别封装提供Refresh接口但刷新后主报表也会重新查询页眉页脚状态会被重置。还有一点是关于子报表文件路径。很多 RPT 的子报表是以链接方式引用的运行时组件只传SubreportName不传路径。如果你把主报表从开发机复制到服务器子报表却还在原来目录运行时就会提示找不到子报表。解决这种问题没有太好的技巧只能把主报表和所有子报表放在同一目录并且在代码里建立一张子报表名到路径的映射表。后续加新报表时先把子报表文件放进发布目录再改映射表。4. 避坑指南水晶报表 VCL 最常见的 5 个翻车现场4.1 报表里改了数据但导出没变缓存和连接复用的锅现象代码逻辑没有变化参数也确实传了新值但导出到 PDF 里的数据还是上一次查询的结果。原因很多 VCL 封装在第一次加载 RPT 后会缓存记录集。水晶报表引擎本身有“使用已保存数据”的选项如果 RPT 文件里勾选了这一项每次打开会直接显示设计器预览时的旧快照而不是重新查库。另一种情况是组件对象复用你在同一窗体里反复使用同一个TCrystalReport实例旧记录集没有释放。解决在每次读取数据前强制调用一次刷新接口并把 RPT 文件里的“保存时使用已缓存数据”选项关掉。代码里我会写rpt.Reset; rpt.LogonServer : ...; rpt.DatabaseName : ...; rpt.PreviewWindow : True;Reset会断开旧连接并清掉内存中的数据集代价是每次预览都重新执行一次查询。对大型报表来说第一次打开会比较慢但换取的是数据一定是最新的。如果性能压力大可以只在数据改变时调用Reset其他时候复用同一个连接。4.2 64 位编译下加载模板直接崩溃组件位宽不匹配现象原来 32 位编译运行正常某一版把主程序切到 64 位编译后只要加载 RPT 就崩溃错误信息类似“内存访问冲突”但日志里看不到更多提示。原因水晶报表 VCL 11 年代较早多数封装只提供 32 位 DCU 和运行库。64 位 Delphi 编译器虽然能编译你的代码但底层调用的 DLL 还是 32 位加载后直接被系统拒绝或者函数入口错位。解决最省事的办法是保持主程序为 32 位编译。这不是技术后退而是报表引擎本身没有 64 位支持。如果你的程序必须 64 位就单独建一个 32 位报表服务进程主程序和它之间用文件或内存映射传参主程序(64位) -- 写参数文件 -- 报表服务(32位) -- 导出PDF -- 主程序读取这种方案多一层进程通信但隔离了崩溃。我曾经把一个报表模块从主程序里拆出来做成独立 EXE用命令行参数调用。这样主程序随便 64 位报表服务始终保持 32 位。4.3 打印输出空白页纸张类型和默认打印机设置冲突现象同一份 RPT在 A 电脑打印正常在 B 电脑打印出一张白纸。原因RPT 文件里设计的纸张是自定义尺寸但 B 电脑默认打印机不支持该纸型。VCL 组件在打印时没有主动设置纸张跟随系统默认打印机系统自动把纸型改成 A4报表内容被推到第二页。解决在代码里显式指定纸张规格不要依赖打印机默认值rpt.PrinterName : \\\\print-server\\laser-01; rpt.PaperSize : 9; // 对应 A4 rpt.Orientation : 1; // 纵向 rpt.PreviewWindow : True;如果你不知道目标打印机的纸型编号可以先在 VCL 界面预览里切换纸张看预览右下角状态栏显示的尺寸再把这些值填回代码。这样做的副作用是换打印机后可能需要重新调整坐标。实践经验是对单据类报表尽量在设计器里把纸张设成 A4页边距控制在打印机的可打印区域内。这样做能减少大部分环境差异。4.4 中文字段名称乱码AnsiString 到 Unicode 的转换损失现象RPT 里字段名是中文VCL 代码里读取字段值或传参时中文变成乱码数据查不到。原因水晶报表 11 的设计器普遍使用 Unicode但 VCL 封装早期版本某些属性还是AnsiString。Delphi 的String类型在 2009 以后变成了UnicodeString和旧 DLL 之间传递时如果没有指定字符集系统按当前代码页转换中文字段名就丢了。解决所有传入字段名的字符串确保在编译单元顶部声明{$WARN SYMBOL_PLATFORM OFF}没有用关键是在调用接口前做一次显式转换rpt.ParameterFields.Item(Utf8ToAnsi(客户编码)).Value : C001;更彻底的做法是把 RPT 文件里的中文字段名全部改成英文字段别名。比如数据库列叫“客户编码”在水晶报表设计器里把字段标题改成显示中文但内部字段名保留英文。这样 VCL 传参始终用英文显示标题仍是中文两边都不受影响。4.5 导出 PDF 时字体被替换嵌入字体的开关没打开现象在开发机导出的 PDF 字体正常到服务器上导出的 PDF 里中文变成方框或者字体被替换成宋体。原因服务器没有安装设计时使用的字体导出时水晶报表引擎用 PDF 查看器内嵌字体。如果 RPT 里指定了某种特殊字体而服务器缺失导出的 PDF 就会用替代字体。严重时替代字体没有对应字形直接显示方框。解决导出 PDF 前显示指定嵌入字体选项rpt.ExportOptions.PDFEmbedFonts : True; rpt.ExportOptions.PDFUseTrueTypeFonts : True;如果是中文字体必须同时确认服务器上安装了同名字体。不要相信开发机上的字体已经在服务器上存在。发布时把报表涉及的字体文件一起放入部署包或者用安装脚本检查服务器字体目录。5. 无界面导出 PDF 的批处理玩法顺便验证报表完整性如果只是偶尔预览一张报表直接调用PreviewWindow就够了。但老项目往往有几十个 RPT 模板每次发布新版本都要逐个检查数据是否正常手动打开窗口效率太差。我会把组件封装成一个命令行导出工具调用方式类似ReportExporter.exe order.rpt output.pdf BeginDate2024-11-01 EndDate2024-11-30核心导出函数可以这样写function ExportRptToPdf(const AReportFile, APdfFile: string; Params: TStringList): Boolean; var rpt: TCrystalReport; i: Integer; paramName, paramValue: string; begin Result : False; rpt : TCrystalReport.Create(nil); try rpt.ReportFileName : AReportFile; rpt.LogonServer : db-server\sqlexpress; rpt.DatabaseName : erpdb; rpt.UserName : report_user; rpt.Password : Report2024; for i : 0 to Params.Count - 1 do begin paramName : Params.Names[i]; paramValue : Params.ValueFromIndex[i]; if rpt.ParameterFields.IndexOf(paramName) 0 then rpt.ParameterFields.Item(paramName).Value : paramValue; end; rpt.ExportOptions.Format : efPDF; rpt.ExportOptions.FileName : APdfFile; rpt.ExportOptions.Destination : edToFile; rpt.Export; Result : FileExists(APdfFile) and (GetFileSize(APdfFile) 0); finally rpt.Free; end; end;这个函数把参数名和值放在一个TStringList里循环判断报表中是否存在对应参数字段避免因为缺参数导致导出失败。GetFileSize只判断文件有没有生成还不能证明数据是完整的。我一般会在导出后追加一道验证打开 PDF 文件统计页数和设计器预览时的页数做对比。页数差距大说明某个过滤条件没生效。更细的办法是在报表页脚放一个总页码字段和一个记录数合计字段导出后用 PDF 文本提取工具检查这两个字段。这个方法不需要额外报表引擎只要 PDF 库能读取文本就行。我的习惯是每接一个老报表先写一条导出命令加进批处理脚本里。等到交付时把当天导出的 PDF 文件名和页数打印到日志截图留存。从那以后我每次改动报表模板都会强制走一遍这个命令行导出流程确认页数和合计都对再告诉业务部门可以联调。希望帮到你。本文还有配套的精品资源点击获取