简介EmbeddedWB-D5-XE12-SRC.7z是为Delphi 12.3用户提供的EmbeddedWB控件源码包面向需要内嵌网页浏览功能或希望深入控件底层机制的开发者。该组件基于WebBrowser技术适合在桌面程序中集成网页展示、与页面交互等场景。压缩包共226个文件体积仅2.44MB包含126个dcu编译单元、65个pas源码文件、22个dpk工程文件以及res资源、inc包含文件、dproj项目配置等既有可直接使用的编译产物也有完整源码便于学习和按需修改。目前已有87人学习下载。通过分析这些源码开发者可以弄清EmbeddedWB的工作机制掌握网页交互的封装思路并能针对特定Delphi版本或业务需求进行定制优化是控件应用与二次开发的高价值参考资料。1. Delphi 12.3 还在用 IE 内核EmbeddedWB 源码包到底解决了什么也许你刚接手一个维护了五六年的老进销存项目业务方天天抱怨内嵌的网页白屏、打印按钮失效碰上只认 IE 的 OA 门户和网银页面一到新系统就翻车。这个标题里的 EmbeddedWB-D5-XE12-SRC.7z就是能在 Delphi 12.3 上继续使用的 EmbeddedWB 控件源码包。它本质上是把系统里的 IE WebBrowser ActiveX 封装了一层帮你接管弹窗、下载、脚本错误、右键菜单和新窗口老项目只要把它挂上去很多 IE 兼容问题能在控件层兜住。这个包适合手上有 Delphi 5 到 XE12 之间历史代码、想往新 IDE 迁移、又不想把整套浏览器架构换成 CEF 或 WebView2 的团队。想清楚这个前提后面每一步都是围绕“最小改动让老网页在新环境跑起来”来做的。2. 拿到 EmbeddedWB-D5-XE12-SRC.7z 后先做三件事解压、路径与 IDE 注册解压这一步没什么好说的但真正让人翻车的是第二步。很多人喜欢把 .pas 和 .dcu 随便塞到一个目录然后在 IDE 里点 Install 装 Dpk结果编译时报找不到某个单元。原因很简单EmbeddedWB 源码包设计上就是让 D5 到 XE12 共用的目录里按版本放了不少条件编译文件你不先把源码路径喂给工具链IDE 就不知道去检索 SRC 目录。我一般会在 D 盘建一个固定目录比如D:\Components\EmbeddedWB-SRC整个解压进去然后按下面的顺序做三件事。2.1 源码包的目录结构怎么看别急着双击 Dpk先给个提醒别看到.dpk就双击那是给设计时包用的我们更常遇到的是运行时包和设计时包打在一起。解压后先看有没有.dpk文件、有没有.inc或.def这类配置文件。通常包会自带一个说明文本里面写了支持范围 D5-XE12但真到了 Delphi 12.3 时IDE 的编译器版本变了默认的签名和 IFDEF 分支可能走不到编译器新版本对应的路线。这时候你就要检查项目的 Delphi 版本宏常见做法是打开.dpk文件源码确认有没有把版本号常量映射到编译器的条件编译符上。; 在 .dpr / .dpk 顶部检查或补上 {$I EmbeddedWB.inc}看这个名字就知道它把所有版本的差异都收进一个公共头文件。像 Delphi 12.3 这种新版本靠的是编译器版本常量比如VER360这类如果.inc里没有对应分支代码就容易编译成老的默认分支轻则少功能重则报错。所以第一步不是安装而是确认 EmbeddedWB.inc 里是否有对应的版本判断。这段代码的逻辑是$I是 Delphi 的 include 指令运行时把公共宏注入到各单元避免每个文件都改一遍。参数说明宏名和实际编译器常量以包内版本文件为准如果你解压的版本比较旧可以手动补一段{$IFDEF VER360}但更稳妥的是去找新版源码包因为新版会对齐新系统 API。2.2 在 Delphi 12.3 里加 Library Path把源码交给 IDE 的必要步骤Delphi 在编译组件时除了当前打开的.dpr/.dpk还要去全局 Library Path 找.pas。很多人只把路径加进当前工程结果换一个项目又变成“找不到单元”。正确姿势是把源码目录加到 IDE 的全局库搜索路径中。操作路径是Tools - Options - Language - Delphi - Library - Library Path。点开编辑框在末尾加一行D:\Components\EmbeddedWB-SRC或者具体指向存放核心.pas的子目录。加之后点保存IDE 会重新建立单元索引。接着做一次 Build看看 Output 里还有没有声称找不到 EmbeddedWB 相关单元的提示。注意这里不要为了省事把整个包目录全加进去包里有 Demo 等示例那些不是库的一部分。加太宽反而会让同名单元冲突这属于老 Delphi 用户“血泪经验”。另外如果你用 Git 管理工程库路径不要写死到工程文件里放在全局 IDE 配置更利于团队成员各自适配。2.3 编译安装 Dpk从源码到控件面板路径就绪后第二步是打开设计时包.dpk文件点右键菜单 Compile 或 Install。这里有个坑当前机器如果有其他版本的 EmbeddedWB 或旧 WebBrowser 残留IDE 会加载两个同名的包导致控件面板上出现两个TEmbeddedWB。所以安装前建议先搜索系统里是否已有EmbeddedWB.dcu/bpl如果有先到 IDE 的 Packages 列表里移除旧的。如果命令行操作我一般这样打包:: 先编译运行时包 msbuild EmbeddedWB.dproj /t:Build /p:ConfigRelease /p:PlatformWin32 :: 再编译设计时包需要管理员权限 msbuild DclEmbeddedWB.dproj /t:Build /p:ConfigRelease /p:PlatformWin32逻辑说明EmbeddedWB 的源码包一般分成 run-time package 和 design-time package 两个 dproj运行时包是纯业务代码设计时包负责往 IDE 组件面板注册。你不编译运行时包直接编译设计时包IDE 会报“找不到 EmbeddedWB.dcu”。参数说明/t:Build告诉 msbuild 执行 Build 目标如果只用 IDE可以直接右键 dproj 选择 Build。/p:ConfigRelease指定 Release 版本避免带调试信息的老 DCU 干扰。/p:PlatformWin32在 Delphi 12.3 里 Win64 和 Win32 都建议各编译一次如果只在 32 位工程里用Win32 足够。编译成功后组件面板应该出现TEmbeddedWB、TEmbeddedWBPrint等条目。记住这一步之后必须重启一下 IDE不然新装的包有时不会刷新到组件面板。3. EmbeddedWB 的核心属性与事件把 IE 内核调教成自己人装好只是开始真正的难点在于让 IE 内核听话。EmbeddedWB 和原生TWebBrowser最大的区别就是暴露了大量接口属性让你能控制浏览器的每一个动作。但属性多也意味着陷阱多我见过同事把Silent设为 True 后网页里的脚本错误确实没了但所有 window.confirm 对话框也没了业务操作直接被跳过。所以要用好这些属性你得先理解它们的层次。3.1 接管新建窗口与弹窗Silent、NewWindow3老网页最常见的需求是点击链接后window.open一个新窗口。原生 TWebBrowser 通常直接弹出一个 IE 窗口这既难看又难控制。EmbeddedWB 提供了OnNewWindow3事件比老旧的OnNewWindow2更可靠能拿到发起窗口的 URL、特征字符串和请求结果。procedure TForm1.EmbeddedWB1NewWindow3(Sender: TObject; var ppDisp: IDispatch; var Cancel: WordBool; const Flags: Cardinal; const URLContext, URL: WideString); begin // 用一个 TabSheet 里的另一个 EmbeddedWB 打开而不是新开 IE if Assigned(SecondaryWB) then begin ppDisp : SecondaryWB.Application; SecondaryWB.Navigate(URL); Cancel : True; end; end;逻辑说明ppDisp是新的浏览器对象接口你在事件里赋给另一个 EmbeddedWB 的Application属性它就会接管新窗口内容Cancel : True可以阻止 IE 再创建独立窗口。参数说明Flags是浏览器新窗口的特征标志来自 IE 的NEW_WINDOW_FLAGS一般不用改URLContext是发起者的页面地址URL是目标地址用来做弹窗拦截的过滤逻辑最方便。Silent属性要谨慎。我一般只在无人值守的自动化抓取场景里开Silent : True正常让用户操作页面时保持 False否则像onbeforeunload这种确认提示也会被一起吞掉用户关了页面直接无感操作业务数据没保存都还不知道。3.2 拦截下载与文件类型OnDownload、OnBeforeNavigate2做进销存系统的人最怕网页里放一个 Excel 导出按钮点击后 IDE 没反应其实文件已经被 IE 下载到临时目录了。EmbeddedWB 提供OnBeforeNavigate2事件你可以在导航发生前判断 URL 后缀或 MIME 类型决定是让页面跳转还是自己接管文件流。配合OnDownload事件可以阻止用户把文件存到默认目录转而弹出自定义的保存路径对话框。procedure TForm1.EmbeddedWB1BeforeNavigate2(Sender: TObject; const pDisp: IDispatch; const URL, Headers: OleVariant; var Cancel: WordBool); begin if ExtractFileExt(URL) .xlsx then begin // 自己处理下载保存 SaveFromURL(URL); Cancel : True; end; end;逻辑说明Cancel设为 True 后IE 内核不会继续执行导航页面不会跳转适合拦截下载链接和外部协议。参数说明Headers里常带着 Referer 和 Cookie如果你要在服务器端做文件访问权限校验务必把这个值转交给下载模块否则会拿不到带鉴权的文件。3.3 让嵌入的网页不白屏RegisterAsBrowser、FeatureBrowsers新版 Windows 对 IE 内核的兼容模式越来越严格经常出现“网页空白但不报错”的怪事。EmbeddedWB 提供了RegisterAsBrowser : True和FeatureBrowsers属性前者是告诉系统当前进程是浏览器进程后者能禁用 IE 的某些新特性比如FEATURE_BROWSER_EMULATION。// 在 FormCreate 里导航之前设置 EmbeddedWB1.FeatureBrowsers : [fbEmulateIE7, fbDisableScriptDebugger]; EmbeddedWB1.RegisterAsBrowser : True;逻辑说明FeatureBrowsers是一个集合把 IE 内核的渲染模式限制在指定优先级fbEmulateIE7会强制页面按 IE7 标准渲染适合老 OA 系统。参数说明如果你要做的页面是现代化 HTML5不要开fbEmulateIE7改成fbEmulateDefault或fbEmulateIE11否则 CSS 全乱。RegisterAsBrowser这个属性在进程内部只能设置一次一般放在主窗体创建的最前面切换太晚会失效。4. 在 Delphi 12.3 上让 EmbeddedWB 播放 PPT 与本地 HTML三个必调项网上搜“Delphi webbrowser 播放 PPT”会发现一堆人问为什么嵌入了空白。传统做法是在网页里嵌 Office Web Viewer或者直接把 PPT 转成 HTML。但如果你必须面对一个老旧的内部课件系统EmbeddedWB 这几个设置项能大幅提高成功率。本章给出一套我在实际项目里用过的配置适用场景是本地或内网 HTML 文件、包含 Flash 或 Office 控件的老页面。4.1 设置文档模式与使用环境让 IE 不至于退回怪癖模式现在的 Windows 对浏览器模式有默认值但老页面经常依赖 IE8/IE9 的渲染逻辑。我一般会在导航前一锤定音EmbeddedWB1.ProfileName : MyAppProfile; EmbeddedWB1.UseProfile : True; EmbeddedWB1.Silent : False; EmbeddedWB1.AllowActiveX : True; // 如果页面里使用 window.open 播放 Flash这里必须开着 EmbeddedWB1.Allow downloads : True; EmbeddedWB1.Show3DBorder : False;逻辑说明UseProfile让嵌入式 WebBrowser 使用独立注册表配置区避免污染全局 IE 设置。AllowActiveX是 IE 安装 ActiveX 插件的前提很多播放 PPT 的控件依赖它。参数说明Show3DBorder只是外观关掉它能让控件融入面板不影响功能。4.2 关闭脚本错误提示DebugScripting老页面里经常有一两处无关紧要的 JS 错误弹出来会挡住后续操作。嵌入式浏览器最直接的解法是禁用脚本调试器EmbeddedWB1.FeatureBrowsers : EmbeddedWB1.FeatureBrowsers [fbDisableScriptDebugger]; EmbeddedWB1.Silent : True; // 但此时 confirm/alert 也会被吞注意Silent : True是双刃剑播放 PPT 时如果页面需要用户点击“允许”或者确认弹窗这个设置会把操作全部静默掉。所以更精细的做法是保留Silent : False只在OnScriptError事件里返回 Trueprocedure TForm1.EmbeddedWB1ScriptError(Sender: TObject; const ErrorLine, ErrorChar, ErrorCode, ErrorMsg: WideString; const Url: WideString); begin // 记录错误但不中断页面 ShowMessage(Format(脚本错误%s 行 %s, [Url, ErrorLine])); // 返回 True 表示已经处理IE 不再显示对话框 end;逻辑说明OnScriptError触发频率很高如果你的页面本身没问题建议只在调试阶段打开这个事件。参数说明ErrorCode是错误编号ErrorMsg是描述文本生产环境不要弹窗写日志就行。4.3 带参数加载本地 HTML解决相对路径与 flash 白名单播放本地 PPT 时最常见的是 Flash 或第三方控件被“未签名 ActiveX”拦截。这时要检查AllowActiveX : True并确保 URL 是file://或内网 HTTP而不是直接传一个不带协议的本地路径。我通常会写一个工具函数procedure TForm1.LoadLocalHTML(const APath: string); var URL: string; begin URL : StringReplace(APath, \, /, [rfReplaceAll]); URL : file:/// URL; EmbeddedWB1.Navigate(URL); end;逻辑说明将 Windows 路径转成file:///形式IE 内核才能正确解析相对路径里的 css/js 文件。参数说明如果页面引用了http://的外部脚本内网环境最好提前下载到本地或部署到同源服务器否则会出现部分功能可用、部分不可用的“薛定谔”状态。这套配置组合我在一个装订生产线上跑了一年多最大的体会是不要迷信某一个属性要按页面实际请求去调。你可以在OnBeforeNavigate2里记录 URL在OnDocumentComplete后再看页面渲染结果逐项排查。5. EmbeddedWB 的避坑指南我踩过的 5 个坑玩 EmbeddedWB 越久越明白它就像一个黑匣子很多问题不是代码逻辑问题而是 IE 内核和 Windows 版本之间的兼容阴影。下面这 5 个坑是按出现频率排序的每一条都按“现象 → 原因 → 解决”写你可以直接对着排查。5.1 控件面板上出现两个 TEmbeddedWB现象安装后组件面板里找到两个同名控件拖一个出来代码里有时绑定到旧版本。 原因机器上残留了旧版 EmbeddedWB 的 BPL/DCUIDE 同时加载了新老包。这种坑最常见于从 D5 时代就一直在用老控件的团队。 解决到 IDE 的 Component Install Packages 列表里逐个查找 EmbeddedWB 相关包全部卸载在源码目录里搜索所有*.bpl和*.dcu并删除重新编译运行时包和设计时包再安装。5.2 页面显示正常但鼠标滚轮失效现象嵌入的网页可以滚动但鼠标滚轮滚不动页面只有拖动滚动条才行。 原因现代 Windows 的鼠标滚轮消息默认发给焦点窗口EmbeddedWB 的文档窗口没有正确接收WM_MOUSEWHEEL部分老版本源码在 Delphi 12.3 下没触发消息映射。 解决在窗体的OnMouseWheel里手动把滚轮消息转发给 EmbeddedWBprocedure TForm1.FormMouseWheel(Sender: TObject; Shift: TShiftState; WheelDelta: Integer; MousePos: TPoint; var Handled: Boolean); begin if Assigned(EmbeddedWB1.Document) then begin EmbeddedWB1.Browser.SendMouseWheelEvent(WheelDelta); Handled : True; end; end;逻辑说明SendMouseWheelEvent是 EmbeddedWB 暴露给外部调用的辅助接口。参数说明WheelDelta为正表示向上滚为负表示向下滚如果窗体上还有输入框建议先判断鼠标位置是否在控件范围内避免影响其他组件。5.3 卸载窗体时崩溃 Access Violation现象关闭带 EmbeddedWB 的主窗体时随机崩溃返回错误地址在OleUninitialize或FreeObject附近。 原因浏览器对象是异步工作的窗体销毁时 ActiveX 还在处理事件回调先释放了窗体的内部对象回调再访问就崩了。 解决释放顺序必须反来先在FormDestroy里停止控制procedure TForm1.FormClose(Sender: TObject; var Action: TCloseAction); begin EmbeddedWB1.Stop; EmbeddedWB1.ExecWB(OLECMDID_STOP, OLECMDEXECOPT_DODEFAULT); // 断开事件接收器 EmbeddedWB1.SetFocus; // 然后交给窗体释放 end;逻辑说明先停止导航和一切活动脚本再用SetFocus让 ActiveX 退出编辑状态最后再释放窗体会稳定很多。参数说明OLECMDID_STOP是 IE 命令集合里的停止导航OLECMDEXECOPT_DODEFAULT表示按默认方式执行。5.4 HTTPS 页面里的下载按钮点了没反应现象从https://页面下载附件点击后没有任何提示也没有文件生成。 原因IE 内核默认对混合内容比较敏感尤其是网页在 HTTPS 下加载了非安全域的下载链接浏览器直接拦截。EmbeddedWB 的默认配置并没有把这种拦截完全关闭。 解决在导航之前检查 URL把 HTTPS 和 HTTP 混用情况单独处理if (pos(https://, URL) 0) and (pos(http://, URL) 0) then ShowMessage(页面同时引用 HTTP 和 HTTPS 资源请确认安全设置) else EmbeddedWB1.Navigate(URL);逻辑说明这种拦截不是 EmbeddedWB 故意做死而是 IE 自身的安全策略。参数说明如果你的内网系统全部是 HTTPS可以额外设置EmbeddedWB1.UseFeatureBrowserFolder、EmbeddedWB1.FeatureBrowsers来适配但最省事的还是引导页面把所有资源切到 HTTPS。5.5 源文件有 SRC 但编译出来的工具不干活现象代码里EmbeddedWB1.Src明明赋了值但页面不显示。 原因Src属性在早期版本里只是个描述符必须在Navigate之后才能用或者赋值时机不对。很多老代码把Src当成 URL 直接用新版本里行为变了。 解决使用SetUrl或Navigate明确加载EmbeddedWB1.Src : about:blank; EmbeddedWB1.Navigate2(https://example.com/);逻辑说明先让浏览器进入一个干净的文档对象状态再导航新地址可以避开文档未就绪时赋值的问题。参数说明Navigate2和Navigate的区别在于是否重新创建文档对象如果你要加载的是动态生成的内存 HTML建议用Write(html)而不是Src。6. 从源码包到自用浏览器控件验证安装与三个进阶技巧装好控件、躲过坑之后最后一步是花一个小时做验证否则你不敢把它交到业务手里。我的验证方法是建一个空白工程拖一个TEmbeddedWB和一个TButton按钮事件里写EmbeddedWB1.Navigate(https://www.example.com/)看页面是否正常加载再右键页面查看属性确认注册表和渲染模式生效。验证通过后可以从三个方向往下压榨价值。第一个进阶技巧是使用 Interposer 模式。把你自己的类挂在 VCL 的默认控件名上type TEmbeddedWB class(EmbeddedWB.TEmbeddedWB) public procedure LoadFromStream(AStream: TMemoryStream); end;这样老工程里已有的TEmbeddedWB自动升级成你的扩展版本不需要改一个界面。第二个技巧是让一个窗口挂多个 EmbeddedWB配合TabSheet实现多标签页同时共享同一个 Cookie 目录。第三个技巧是如果你要嵌入的内容已经改成 HTML5不要再让 EmbeddedWB 硬扛它毕竟只是 IE 内核的安全壳此时用 WebView2 做渐进替换更合适。我见过有人非要让 EmbeddedWB 跑现代前端项目结果各种玄学崩溃最后还得回头迁内核。这里还要提醒一句如果你在用 Delphi 12.3 的 FireMonkey 方式做跨平台界面EmbeddedWB 是 VCL 控件不能直接拖到 FMX 窗体里。常见的做法是 VCL 窗体里放一个嵌入的 TPanel再Winapi.Windows做窗口句柄托管。用LoadLibrary加载 WebBrowser 对象的接口但这套方案维护成本高能不用就不用。我自己的习惯是把 EmbeddedWB 的所有操作都包在一个独立业务类里控件只负责显示业务模块负责导航、下载、日志。这样即使那天要换 WebView2业务代码也不用重写。希望这些踩坑记录能让你在 Delphi 12.3 里用这个 SRC 包时少走几趟夜路也希望你手头的老项目能借着 EmbeddedWB 再稳稳跑上几年然后从容地迁到新内核。本文还有配套的精品资源点击获取