Delphi中用TPaintBox生成显示二维码，并保存为PNG回读Image的完整实践

1. 从画布到文件为什么用PaintBox而不是直接放Image最近在做桌面端工具时遇到一个挺典型的交互需求界面某处要根据数据动态生成二维码当场显示给用户看同时提供一个“保存图片”的按钮把二维码落盘。等下次软件启动还要能从之前保存的文件里把二维码重新读出来填进界面的图片控件里。很多刚接触Delphi的人第一反应是那我用一个TImage生成完直接给它赋值不就行了表面看确实简单但实际做下来会发现TImage在频繁动态生成、反复刷新时并不理想。因为TImage本质上是把图片当作组件的一个属性在管理每次改Picture都会触发整个控件的重绘和状态变更高频操作时会有闪烁和内存重分配的开销。而且如果后续要在这个区域叠加绘制状态提示、临时遮罩或者边框TImage的灵活性也不够。这时候改用TPaintBox就是更合理的选择。PaintBox是一个纯粹的绘图画板它不持有图片数据只负责在OnPaint事件里把内容画出来。换句话说你可以把二维码的生成逻辑和界面显示解耦二维码以位图数据的形式存在内存里PaintBox只是那个把位图呈现出来的“显示器”。需要保存时直接把内存里的位图写文件操作对象始终是同一份数据不存在控件和文件之间的歧义。我在实际项目里就是这么干的。二维码生成后保存到一个TBitmap变量里PaintBox的OnPaint里从变量取图绘制保存按钮直接操作这个TBitmap。这样既避免了TImage“既当数据容器又当显示控件”的双重身份带来的混乱也让后续替换、缩放、加logo这些扩展变得很容易。这篇文章就把整条链路拆开讲清楚从库选型、绘制逻辑、文件保存到回读进Image控件每一步都附上可直接落地的代码和我在实际项目里踩过的坑。适合谁来参考如果你正在用Delphi 7到Delphi 10.4之间的某个版本做桌面工具恰好需要“动态生成二维码、在界面上展示、保存成文件、再加载回控件”这一串功能这篇文章应该能帮你省下不少试错时间。2. 二维码生成库的选型好用的库不止一个关键是匹配Delphi版本先说一个容易卡住新手的地方Delphi的跨版本兼容性并不是无缝的。你在网上搜“Delphi 二维码”会发现好几个不同的开源库它们适用的编译器版本差别很大。选错了库光编译报错就够折腾半天。我把常见的几个方案捋了一遍结合自己的使用经历说下取舍。我最后固定下来用的是DelphiZXingQRCode这个老牌开源库。这个库不需要额外安装第三方依赖纯Delphi代码实现从古老的Delphi 6、7到新版本的RAD Studio基本上都能编译通过。它的核心只有两个单元文件QRCode.pas和ZXingQRCode.pas跟着你的工程一起走就行部署极其省事。生成二维码时只需要调用一个encodeQRCode函数传入文本、宽高、纠错等级这几个参数返回的就是一个二维布尔数组标记着哪些点是黑色。除了DelphiZXingQRCode我在开发过程中也研究过另外两个方向一个是自己生成格式并手动实现RS纠错编码另一个是直接调用第三方SDK或者系统库。自己生成的方式对二维码编码规范不熟悉的人不建议碰因为Reed-Solomon纠错编码的计算细节很多一个字节的疏忽整个码就扫不出来调用系统库的方式在不同Windows版本上表现也不一致跨平台发布时容易出幺蛾子。相比之下DelphiZXingQRCode这种“源码拿进来直接用”的方式最稳妥编译进exe里就完全不依赖外部文件了。提示如果界面用到的二维码要打印或者贴到对外资料上生成尺寸不要低于256像素最好设成512。二维码太小了被喷绘出来根本扫不动。这个我后面还会再提。这个库的使用方式大致是这样uses QRCode, ZXingQRCode; var data: T2DIntArray; // 二维点阵数据 begin encodeQRCode(https://example.com, data, 256, 256, qrBoostEcc); end;这个函数会返回一个二维整数数组data表示生成的二维码黑点矩阵。q rBoostEcc是纠错等级参数类似的还有qrAuto、qrLow、qrMedium、qrHigh几个取值。需要说明的是它们返回的是布尔语义的点阵信息画图的工作其实还没开始。这是理解后续流程的关键生成二维码和绘制二维码是两件事中间夹着一层“怎么把点阵变成图像”的转换逻辑。3. 绘制环节的两条路控件上画图和位图里画图是两回事二维码的点阵数据拿到手之后接下来的核心动作是绘制。很多第一次接触的人会以为直接在PaintBox上画就行但实际上这里有两层绘制逻辑必须分开理解。3.1 为什么必须先把点阵画进TBitmapPaintBox的OnPaint事件里确实可以画二维码比如给Canvas赋色、FillRect填充一格一格的黑色方块。但如果只在OnPaint里画那这份“画出来的东西”只存在于屏幕上是临时的窗口一刷新就没了。更麻烦的是它本身不构成一张可保存的图片数据。正确的做法是先在内存里创建一个TBitmap把二维码逐格绘入其中产生一张实实在在的位图然后屏幕上显示把TBitmap画到PaintBox的Canvas上保存文件把TBitmap直接保存为PNG或BMP一个数据源两种用途。这样整个项目里二维码的绘制逻辑只写一遍所有环节都复用它。别把屏幕绘制和文件生成拆成两套代码否则改一次尺寸或者换一次纠错等级就要同步改两个地方迟早漏掉一个。3.2 逐格绘制的具体实现这一步的核心思想是把二维码点阵看成一张稀疏的网格每个黑色方块对应一个矩形填充。网上的很多示例代码都是三层循环新手容易看晕我拆开讲一下procedure DrawQRCodeToBitmap(Bitmap: TBitmap; const Data: T2DIntArray); var cellSize, i, j: Integer; x, y: Integer; begin Bitmap.PixelFormat : pf24bit; Bitmap.Width : 256; Bitmap.Height : 256; cellSize : 256 div Length(Data); // 白底 Bitmap.Canvas.Brush.Color : clWhite; Bitmap.Canvas.FillRect(Rect(0, 0, Bitmap.Width, Bitmap.Height)); // 按点阵画黑格 for i : 0 to Length(Data) - 1 do for j : 0 to Length(Data[i]) - 1 do begin if Data[i][j] 1 then begin x : j * cellSize; y : i * cellSize; Bitmap.Canvas.Brush.Color : clBlack; Bitmap.Canvas.FillRect(Rect(x, y, x cellSize, y cellSize)); end; end; end;注意一个细节cellSize的计算是把生成尺寸除以点阵边长。二维码点阵通常是37x37、41x41这类不规则数字不是整数倍也没关系取整后让最外圈留一点白边反而有利于扫码识别。如果你做过实物二维码印刷应该知道留白边专业说法叫“静区”是扫码器能够定位的重要前提。这套绘制逻辑里还有一个容易被忽略的点BitBlt方式还是FillRect方式性能差距在静态生成场景里并不明显但如果你做的工具要批量生成成百上千张二维码FillRect方式就显得笨重了。那时候可以改用Scanline直接操作像素字节速度提升明显。但对于界面交互场景逐格FillRect完全够用代码简单、不容易出错别为了炫技过早优化。4. PaintBox的真实定位缓存呈现与交互区域的平衡术DrawQRCodeToBitmap把二维码画进了TBitmap这一步完成后下一步是怎么把它呈现在PaintBox上。PaintBox的OnPaint事件会在窗口需要重绘的任意时机触发——包括窗口移动、遮挡恢复、尺寸变化等等。如果你的OnPaint处理写得不好就会看到二维码一闪一闪地重画那就是常见的闪烁问题。我的做法是procedure TPaintBoxForm.PaintBox1Paint(Sender: TObject); begin if Assigned(FBitmap) then begin PaintBox1.Canvas.Brush.Color : clWhite; PaintBox1.Canvas.FillRect(PaintBox1.Canvas.ClipRect); PaintBox1.Canvas.Draw(0, 0, FBitmap); end; end;这个FBitmap是窗体类的成员变量一旦生成二维码就存一份。每次OnPaint从缓存里取图仅仅是Draw不重新计算点阵、不重新逐格填充性能开销非常小。这个设计思路本质是“缓存呈现”——用TBitmap保存绘制结果用PaintBox做呈现层。你可能会问那屏幕尺寸变化怎么办PaintBox尺寸拉伸时Draw是按原始大小贴上去的不会自动缩放。如果需要自适应可以在Draw之前对Canvas进行缩放变换PaintBox1.Canvas.SetStretchBltMode(PaintBox1.Canvas.Handle, STRETCH_HALFTONE); StretchBlt( PaintBox1.Canvas.Handle, 0, 0, PaintBox1.Width, PaintBox1.Height, FBitmap.Canvas.Handle, 0, 0, FBitmap.Width, FBitmap.Height, SRCCOPY );这段代码会把FBitmap拉伸到PaintBox的客户区大小配合STRETCH_HALFTONE插值模式缩放后的二维码边缘质量比默认模式要光滑不少。但注意这类拉伸只适合屏幕展示保存文件时还是要基于原始尺寸做别把拉伸后的效果直接写进文件里否则会得到一张边缘糊掉的二维码。还有一点比较复杂双击交互往往也在PaintBox上做。常见做法是给PaintBox设置一个OnMouseDown或OnDblClick事件用户点击二维码区域时可以弹出菜单、放大预览、或者触发重新生成。这时候PaintBox作为一个“交互层”的价值就体现出来了——你可以在事件里精确判断鼠标按下位置是否在二维码有效区域内再决定是否响应用户动作。相比TImage这种可定制性要灵活得多。我在实际项目里的界面布局是左侧放一个导航菜单右侧中部放PaintBox作为二维码展示区下方放一个按钮“生成新码”、一个按钮“保存图片”。用户填好文本点“生成新码”二维码立即画到PaintBox上点“保存图片”弹出保存对话框文件落盘。整个交互流程非常干净用户不需要关心内部的技术细节。5. 保存本地文件的关键格式选择和血泪坑——PNG与BMP的取舍二维码绘制成TBitmap后保存文件这一环相对机械但坑一点都不少。我最早用Delphi 7做版本时TBitmap自带的SaveToFile只能存BMP那会儿还没意识到这是个问题。直到有一次把生成的BMP发到一个文档里发现体积竟然有200多KB而同样的二维码存成PNG只要几KB这对我这种经常要把二维码嵌入报告、文档、邮件的人来说体验差距太大了。如果要存PNG在Delphi较新版本如XE系列以上里可以直接用TPNGImage类在Delphi 7里就得靠第三方PNG库或者用“BMP转PNG”的工具类。建议直接判断自己手头版本的RTL和第三方库支持情况优先选PNG因为二维码这种黑白分明的图形用PNG压缩率非常高而且支持透明背景。我常用的保存代码如下uses PNGImage; procedure SaveQRCodeAsPNG(ABitmap: TBitmap; const AFileName: string); var png: TPNGImage; begin png : TPNGImage.Create; try png.Assign(ABitmap); png.SaveToFile(AFileName); finally png.Free; end; end;实际操作中可以做一层封装让函数直接接收点阵数据内部完成“创建位图→逐格绘制→保存PNG→释放位图”一整条流程这样调用方不需要关心TBitmap的生命周期也有利于在后台线程里批量生成。procedure GenerateQRCodeFile(const Text: string; const FileName: string; Size, ECCLevel: Integer); var data: T2DIntArray; bmp: TBitmap; begin encodeQRCode(Text, data, Size, Size, ECCLevel); bmp : TBitmap.Create; try DrawQRCodeToBitmap(bmp, data); // 上文实现 SaveQRCodeAsPNG(bmp, FileName); finally bmp.Free; end; end;注意保存PNG时如果发现文件打不开先检查TBitmap的PixelFormat。PNGImage内部对位图格式是有要求的如果PixelFormat设成了pfDevice在某些机器上会生成空白图像。显式指定pf24bit或pf32bit可以避开这个坑。还有一个很容易踩的坑是中文文件名路径。如果你用TFileStream或者SaveToFile时FileName参数里带中文某些老版本的Delphi会出现编码混乱导致保存失败或者文件名乱码。最省心的方案是统一用TEncoding.UTF8转换一下路径字符串或者直接让用户在保存对话框里选路径借助对话框内部的编码处理来规避。6. 回灌Image控件从文件读取到赋值的完整链路与高清失真问题保存好了PNG另一个需求接踵而至软件重启后要从之前保存的本地文件里把二维码重新读出来显示到界面某个TImage控件上。这一条链路看起来就两行代码但我在测试中发现了一个很值得说的细节Image控件默认缩放模式会导致二维码变糊的视觉问题。6.1 标准加载方式先把加载代码列出来uses PNGImage; procedure LoadPNGIntoImage(const AFileName: string; AImage: TImage); var png: TPNGImage; begin if not FileExists(AFileName) then Exit; png : TPNGImage.Create; try png.LoadFromFile(AFileName); AImage.Picture.Graphic : png; finally png.Free; end; end;TImage的Picture.Graphic在赋值时会自动持有这个Graphic对象所以这里png.Free是安全的。有人可能会担心赋值后释放会出问题其实TPNGImage被赋给AImage.Picture.Graphic之后Picture会维护自己的引用计数释放原对象不会导致显示异常。这在Delphi里是正常行为。如果你更喜欢让Image自己管理图像数据也可以用AImage.Picture.LoadFromFile(AFileName)这样省一步手动创建。但两种写法在遇到文件损坏时处理不一致我在项目中更喜欢显式创建PNG对象因为能在加载失败时捕获更精确的异常信息。6.2 高清失真的真凶与解法Image控件读取图片后如果它比图片大Delphi默认会进行拉伸显示而拉伸的默认插值模式比较粗糙会造成明显的锯齿二维码的边缘看起来“毛刺”感很重。特别是当原始PNG是256x256、Image控件显示区域是300x300甚至更大的时候这个问题几乎必现。最简单的解法是给Image设置合适的Stretch属性和保持比例Image1.Stretch : True; Image1.Proportional : True;Stretch True让图片可以跟随控件尺寸变化Proportional True让缩放时保持纵横比避免二维码被拉成矩形。但这样只能解决比例问题并不能彻底解决模糊。要让二维码在控件的不同尺寸下都保持清晰更靠谱的思路是让加载时保持原始尺寸或者让Image控件的大小与图片像素尺寸尽量一致。如果你对清晰度有更高要求可以绕开TImage的自动缩放能力用自定义绘制的方式显示二维码。比如放一个TPaintBox加载完PNG后把位图设为FBitmap在OnPaint里用StretchBlt拉伸绘制并设置STRETCH_HALFTONE模式。这样的显示效果比TImage的默认拉伸要细腻。在二维码这类边缘锐利的图形上差的其实不是尺寸而是插值算法这个细节很多人没注意。// OnPaint 里采用高质量拉伸 PaintBox1.Canvas.SetStretchBltMode(PaintBox1.Canvas.Handle, STRETCH_HALFTONE); StretchBlt( PaintBox1.Canvas.Handle, 0, 0, PaintBox1.Width, PaintBox1.Height, FBitmap.Canvas.Handle, 0, 0, FBitmap.Width, FBitmap.Height, SRCCOPY );这段代码可以和本文前面第4小节里PaintBox显示二维码的方案统一起来只要FBitmap是从本地PNG加载进来的PaintBox既能显示动态生成的二维码也能显示本地文件里读回来的二维码。一个控件、一套事件逻辑同时覆盖两种来源工程上非常省事。我还试过一个更简单的替代方案干脆让Image控件在启动时用代码置为原始图片像素尺寸或者把窗体的界面布局做成固定尺寸。许多桌面工具的二维码展示区本来就是固定大小这种情况下并不需要复杂的缩放逻辑直接把Image按图片原始尺寸摆放即可。但放到通用的工程框架里仍然建议用PaintBox StretchBlt的方案毕竟控件的尺寸在你的软件里大概率不是永远不变的。7. 集成代码全貌与后续扩展从单张二维码到批量生成流程把整条链路串起来的完整示例代码我整理了一份这个版本做了适度精简但核心结构完整。代码里我删减了菜单和事件绑定部分只留下关键的业务逻辑方便你在自己的工程里移植unit QRCodeDemo; interface uses Windows, Graphics, ExtCtrls, Classes, Controls, Dialogs, QRCode, ZXingQRCode, PNGImage; type TQRCodeForm class(TForm) PaintBox1: TPaintBox; Image1: TImage; procedure FormCreate(Sender: TObject); procedure FormDestroy(Sender: TObject); procedure PaintBox1Paint(Sender: TObject); private FBitmap: TBitmap; procedure GenerateQRProc(const AText: string; ASize: Integer); procedure SaveCurrentQR(const AFileName: string); procedure LoadQRToImage(const AFileName: string); public end; implementation procedure TQRCodeForm.FormCreate(Sender: TObject); begin FBitmap : TBitmap.Create; FBitmap.PixelFormat : pf24bit; GenerateQRProc(示例文本, 256); end; procedure TQRCodeForm.FormDestroy(Sender: TObject); begin FBitmap.Free; end; procedure TQRCodeForm.GenerateQRProc(const AText: string; ASize: Integer); var data: T2DIntArray; cellSize, i, j: Integer; begin encodeQRCode(AText, data, ASize, ASize, qrBoostEcc); FBitmap.Width : ASize; FBitmap.Height : ASize; cellSize : ASize div Length(data); FBitmap.Canvas.Brush.Color : clWhite; FBitmap.Canvas.FillRect(Rect(0, 0, ASize, ASize)); for i : 0 to Length(data) - 1 do for j : 0 to Length(data[i]) - 1 do if data[i][j] 1 then begin FBitmap.Canvas.Brush.Color : clBlack; FBitmap.Canvas.FillRect(Rect( j * cellSize, i * cellSize, (j 1) * cellSize, (i 1) * cellSize )); end; PaintBox1.Invalidate; end; procedure TQRCodeForm.SaveCurrentQR(const AFileName: string); var png: TPNGImage; begin png : TPNGImage.Create; try png.Assign(FBitmap); png.SaveToFile(AFileName); finally png.Free; end; end; procedure TQRCodeForm.LoadQRToImage(const AFileName: string); begin if FileExists(AFileName) then Image1.Picture.LoadFromFile(AFileName); end; procedure TQRCodeForm.PaintBox1Paint(Sender: TObject); begin if Assigned(FBitmap) then begin PaintBox1.Canvas.Brush.Color : clWhite; PaintBox1.Canvas.FillRect(PaintBox1.Canvas.ClipRect); PaintBox1.Canvas.Draw(0, 0, FBitmap); end; end; end.代码里我保留了最原始的实现没有加StretchBlt缩放这是为了阅读方便。实际项目中请按第3、6小节的方案在需要自适应时替换为StretchBlt方式。这套方案的扩展空间也很大我简单说两个方向第一个是批量生成。应付“一批数据各生成一张二维码”的场景时只要把GenerateQRProc里的绘制核心抽成函数在后台线程里循环处理再按数据编号命名文件即可。注意Delphi中的VCL组件访问不是线程安全的后台线程里不要直接操作TBitmap和PaintBox建议线程只负责生成点阵数据把结果通过Synchronize或者Queue转回主线程再绘制。第二个是添加Logo。二维码中央可以贴一个小图整体辨识度会高很多。实现上就是在DrawQRCodeToBitmap全部填充完之后在Bitmap的中央区域再画一张小图var LogoBitmap: TBitmap; Cx, Cy, LogoSize: Integer; begin Cx : (FBitmap.Width - LogoSize) div 2; Cy : (FBitmap.Height - LogoSize) div 2; FBitmap.Canvas.Draw(Cx, Cy, LogoBitmap); end;但这一步要谨慎Logo过大会遮挡过多编码区域导致扫码失败。一般建议Logo边长不超过二维码总边长的四分之一也就是占比控制在25%以内。而且生成时用的纠错等级要优先选qrHigh因为高纠错等级能在中间被遮挡一块的情况下依然正确解码。8. 关于显示比例和DPI缩放我踩过的最后一个大坑最后提一个屏幕显示相关的问题同一个二维码在100%缩放的电脑上显示正常在缩放到125%或150%的电脑上PaintBox里的二维码边缘会明显发虚或者像素格出现大小不均匀。这背后的原因是不同DPI设置下Delphi窗体和控件的坐标、Canvas的缩放规则会变。特别是启用PerMonitorV2 DPI感知之后某些旧版本VCL的绘制代码没有适配这种缩放。表现就是你在绘制时用的尺寸是逻辑像素但实际显示在物理像素上两者不一致导致拉伸错位。我目前的应对策略是界面高DPI适配优先用TForm的ScaleForCurrentDpi或TForm.ScaleBy让整个窗体统一缩放PaintBox的尺寸定义成逻辑值绘制时以PaintBox的实际Width、Height为准动态计算二维码绘制区域如果项目还在使用不支持高DPI的Delphi老版本建议关闭PerMonitorV2或者手动在工程文件里写入SetProcessDPIAware以保持兼容如果二维码只是展示和保存其实这样已经足够。真正追求像素级完美的场景就得在绘制的坐标系里乘上Screen.PixelsPerInch / 96这个比例系数但这是另一个深度话题了普通业务需求用不到。我把这套流程完整跑过好几轮从生成、显示、保存到回读整个链路里最容易翻车的是PNG格式处理和DPI缩放其余部分Delphi基础控件事先都帮你兜住了。希望这篇文章能让你少走一段弯路直接跑通自己项目里的二维码功能。