Microsoft Edge WebView2 与 Delphi

TsgcWebView2 是一个新的可视化 Delphi 组件，封装了 Microsoft Edge WebView2，让您可以在任何 VCL 应用程序中嵌入基于 Chromium 的现代浏览器引擎。将其拖放到窗体上，设置 URL，即可获得功能完整的嵌入式浏览器——支持 Cookie 管理、下载控制、JavaScript 集成、打印支持等更多功能。

与 Delphi 近期版本内置的 TEdgeBrowser 不同，TsgcWebView2 支持从 Delphi 7 到 Delphi 13 的所有版本——这是目前所有 WebView2 封装中最广泛的版本支持。它是 eSeGeCe 公司 sgcWebSockets 库的一部分。

本文介绍其功能集、提供实用代码示例、与 TEdgeBrowser 进行对比，并说明其内部架构。

功能概览

TsgcWebView2 通过清晰的 Delphi 事件和方法公开了 WebView2 SDK 的广泛接口。以下是十二个主要功能组：

导航 Navigate、GoBack、GoForward、Reload、Stop。支持带自定义请求头和请求体的 POST 导航。

JavaScript 执行 异步或同步执行 JavaScript。注册在每次页面加载时自动执行的初始化脚本。

Cookie 管理 以编程方式获取、添加、更新和删除 Cookie。完整访问 Cookie 属性，包括域名、路径和过期时间。

下载控制 提供下载开始、进度和完成事件。将下载重定向到自定义路径或完全取消下载。

配置文件管理 支持多配置文件以实现独立的浏览会话。可按配置文件清除浏览数据（缓存、Cookie、历史记录）。

打印支持 将当前页面打印为 PDF 或显示系统打印对话框。控制纸张大小、方向和页边距。

音频/静音控制 检测文档是否正在播放音频。以编程方式切换静音状态，不影响系统音量。

证书处理 通过专用事件响应客户端证书请求和服务器证书错误。

上下文菜单 拦截并完全自定义右键菜单。使用您自己的操作添加、删除或替换菜单项。

Favicon 访问 获取当前页面的 Favicon URI。通过专用事件响应 Favicon 变更。

虚拟主机映射 将自定义主机名映射到本地文件夹。像真实 Web 服务器一样提供本地 HTML/CSS/JS 文件。

截图捕获 将可见页面内容保存为 PNG 或 JPEG 图像，适用于缩略图、报告或自动化测试。

快速入门

使用 TsgcWebView2 最简单的方式是将其拖放到 VCL 窗体上并调用 Navigate。组件会自动处理 WebView2 环境创建、控制器初始化和视图绑定。

// Drop TsgcWebView2 on your form, then:
procedure TForm1.FormCreate(Sender: TObject);
begin
  sgcWebView2.Navigate('https://www.example.com');
end;
procedure TForm1.sgcWebView2NavigationCompleted(Sender: TObject;
  aIsSuccess: Boolean; aWebErrorStatus: Integer);
begin
  if aIsSuccess then
    Caption := sgcWebView2.DocumentTitle;
end;

OnNavigationCompleted 事件在页面加载完成后触发，报告导航是否成功及任何错误状态码。这是更新 UI（窗口标题、状态栏、前进/后退按钮状态）的最佳时机。

注意：组件在首次使用时懒加载创建 WebView2 环境。如需配置环境选项（浏览器文件夹、语言、命令行开关），请在调用 Navigate 之前通过 EnvironmentOptions 属性进行设置。

Cookie 管理

CookieManager 子对象公开了完整的 WebView2 Cookie API。您可以列出当前 URL 的 Cookie，添加或更新具有特定属性的 Cookie，以及删除单个 Cookie 或一次性清除所有 Cookie。

// List cookies for the current page
sgcWebView2.CookieManager.GetCookies(sgcWebView2.URL);
// Delete all cookies
sgcWebView2.CookieManager.DeleteAllCookies;
// Add a cookie
sgcWebView2.CookieManager.AddOrUpdateCookie(
  'session', 'abc123', '.example.com', '/');

调用 GetCookies 后，结果将异步通过 OnCookiesReceived 事件返回。每个 Cookie 包含名称、值、域名、路径、过期时间、Secure 标志和 HttpOnly 标志。这是 TEdgeBrowser 完全未公开的功能之一。

提示：在导航到受保护页面之前使用 AddOrUpdateCookie 注入认证令牌，从而避免嵌入式浏览器场景中的登录表单流程。

JavaScript 集成

TsgcWebView2 提供三种 JavaScript 执行方式，各适用于不同场景：

异步执行

调用 ExecuteScript，在 OnScriptExecuted 事件中处理结果。这是标准的非阻塞方式。

// Async execution - result arrives in OnScriptExecuted event
sgcWebView2.ExecuteScript('document.title');
procedure TForm1.sgcWebView2ScriptExecuted(Sender: TObject;
  const aResult: string; aErrorCode: Integer);
begin
  if aErrorCode = 0 then
    ShowMessage('Title: ' + aResult);
end;

同步执行

当需要立即获取结果时，使用 ExecuteScriptSync。该方法会阻塞调用线程直到脚本完成并直接返回结果。

var
  vTitle: string;
begin
  vTitle := sgcWebView2.ExecuteScriptSync('document.title');
  Caption := vTitle;
end;

初始化脚本

初始化脚本注册一次，在每次页面加载时自动执行，且在任何页面 JavaScript 之前运行，非常适合注入全局配置或 polyfill。

// Runs on every page load, before any page scripts
sgcWebView2.AddInitScript('window.appVersion = "1.0";');

下载管理

下载通过事件驱动模型处理。下载开始时，OnDownloadStarting 事件允许您将文件重定向到自定义路径、取消下载或按默认方式继续。下载完成时触发 OnDownloadCompleted 事件。

procedure TForm1.sgcWebView2DownloadStarting(Sender: TObject;
  const aURI, aResultFilePath: string;
  var aCancel: Boolean;
  var aHandled: Boolean;
  var aFilePath: string);
begin
  // Redirect download to custom folder
  aFilePath := 'C:\Downloads' + ExtractFileName(aResultFilePath);
  aHandled := True;
end;
procedure TForm1.sgcWebView2DownloadCompleted(Sender: TObject;
  const aFilePath: string; aState: Integer);
begin
  ShowMessage('Download complete: ' + aFilePath);
end;

POST 导航与自定义请求头

标准导航使用 GET 请求加载 URL。对于 API 测试、表单提交或需要不同 HTTP 方法的场景，NavigateWithPostData 允许在单次调用中指定方法、请求体和请求头。

// Navigate with POST data and custom headers
sgcWebView2.NavigateWithPostData(
  'https://api.example.com/submit',
  'POST',
  '{"key":"value"}',
  'Content-Type: application/json' + #13#10 +
  'Authorization: Bearer token123'
);

与 TEdgeBrowser 的对比

Delphi 从 10.4 Sydney 起内置了 TEdgeBrowser（XE7+ 版本可通过 GetIt 获取）。它提供了基本的 WebView2 封装，但许多 SDK 功能未公开。下表展示了 TsgcWebView2 的优势所在。

功能	TEdgeBrowser	TsgcWebView2
Delphi 版本支持	仅 XE7+	D7 至 D13
Cookie 管理	✗	✓ 完整 API
下载进度事件	✗	✓ 开始/进度/完成
配置文件/清除浏览数据	✗	✓
音频/静音控制	✗	✓
Favicon 访问	✗	✓
证书事件	✗	✓
基本认证事件	✗	✓
状态栏文本	✗	✓
虚拟主机映射	✗	✓
共享缓冲区	✗	✓
同步 ExecuteScript	✓	✓
截图捕获	✓	✓
初始化脚本	✓	✓
POST 导航	✓	✓
打印支持	✓	✓
设计时设置	WebView 未创建时抛出异常	✓ 安全的 TPersistent 属性
上下文菜单	PopupMenu 合并	完整事件控制
优雅降级	✗	✓ 按功能版本检查
原始 COM 访问	✓	✓

高级功能

打印为 PDF

sgcWebView2.PrintToPdf('C:\output\page.pdf');

截图捕获

sgcWebView2.CapturePreviewToFile('C:\screenshots\page.png', 0); // 0 = PNG

虚拟主机映射

// Serve local files via https://app.local/
sgcWebView2.SetVirtualHostNameToFolderMapping(
  'app.local', 'C:\MyApp\WebContent', 1);
sgcWebView2.Navigate('https://app.local/index.html');

音频与静音控制

sgcWebView2.IsMuted := True;
if sgcWebView2.IsDocumentPlayingAudio then
  ShowMessage('Audio is playing');

架构与设计

TsgcWebView2 基于清晰的三层架构构建，在保持开发者 API 简洁的同时实现关注点分离：

• API 层（COM 接口）：Microsoft WebView2 COM 接口的直接 Delphi 转换。这些是底层构建块——低级、特定版本，不适合在应用代码中直接使用。
• 类层（封装器）：原生 Delphi 封装类，管理 COM 对象生命周期、处理回调路由并提供简洁的面向对象 API。此层屏蔽了 COM 底层细节。
• 组件层（可视）：TsgcWebView2 组件本身——一个可拖放到窗体上的 TWinControl 后代，公开属性、事件和映射到下层类的方法。

要求

• Microsoft Edge WebView2 Runtime：Windows 10（1803 及以上版本）和 Windows 11 已内置。对于旧版 Windows 或受控部署，请从 Microsoft 下载 Evergreen 引导程序或固定版本运行时。
• WebView2Loader.dll：随组件附带。将其放置在应用程序可执行文件旁边。
• 仅限 Windows：WebView2 是 Windows 技术，组件面向 Windows 7 及以上版本的 VCL 应用程序（推荐 Windows 10/11 以获得完整功能支持）。

总结

TsgcWebView2 是 Delphi 中最完整的 WebView2 封装。它是 TEdgeBrowser 的严格超集，新增了 Embarcadero 内置组件未公开的十二项功能，并支持从 Delphi 7 到 Delphi 13 的最广泛版本范围，是 Delphi 开发者嵌入现代浏览器的首选方案。