TsgcWebView2는 Microsoft Edge WebView2를 감싸는 새 시각적 Delphi 컴포넌트예요. 모든 VCL 애플리케이션 안에서 최신 Chromium 기반 브라우저 엔진을 사용할 수 있어요. 폼에 올려놓고 URL을 설정하면 쿠키 관리, 다운로드 제어, JavaScript 통합, 인쇄 지원 등 모든 기능을 갖춘 내장 브라우저를 바로 사용할 수 있어요.
최근 Delphi 버전에 포함된 내장 TEdgeBrowser와 달리 TsgcWebView2는 Delphi 7부터 Delphi 13까지 모든 Delphi 버전을 지원해요 — 사용 가능한 WebView2 래퍼 중 가장 넓은 버전 지원 범위예요. eSeGeCe의 sgcWebSockets 라이브러리의 일부예요.
이 글에서는 기능 세트를 소개하고, 실용적인 코드 예제를 보여 주며, TEdgeBrowser와 직접 비교하고, 내부 아키텍처를 설명해요.
기능 개요
TsgcWebView2는 깔끔한 Delphi 이벤트와 메서드를 통해 WebView2 SDK의 넓은 기능 영역을 노출해요. 다음은 12가지 주요 기능 그룹이에요:
|
내비게이션 Navigate, GoBack, GoForward, Reload, Stop. 사용자 지정 헤더와 요청 본문을 사용한 POST 내비게이션을 지원해요. |
JavaScript 실행 JavaScript를 비동기 또는 동기로 실행할 수 있어요. 페이지 로드마다 자동으로 실행되는 초기화 스크립트를 등록할 수 있어요. |
쿠키 관리 쿠키를 프로그래밍 방식으로 가져오고, 추가하고, 업데이트하고, 삭제할 수 있어요. 도메인, 경로, 만료일을 포함한 쿠키 속성에 완전히 접근할 수 있어요. |
|
다운로드 제어 다운로드 시작, 진행 상태, 완료에 대한 이벤트가 있어요. 다운로드를 사용자 지정 경로로 리디렉션하거나 완전히 취소할 수 있어요. |
프로필 관리 격리된 브라우징 세션을 위한 다중 프로필 지원이에요. 프로필별로 브라우징 데이터(캐시, 쿠키, 기록)를 지울 수 있어요. |
인쇄 지원 현재 페이지를 PDF로 인쇄하거나 시스템 인쇄 대화 상자를 표시할 수 있어요. 용지 크기, 방향, 여백을 제어할 수 있어요. |
|
오디오 / 음소거 제어 문서가 오디오를 재생 중인지 감지해요. 시스템 볼륨에 영향을 주지 않고 프로그래밍 방식으로 음소거 상태를 전환할 수 있어요. |
인증서 처리 전용 이벤트를 통해 클라이언트 인증서 요청과 서버 인증서 오류에 응답할 수 있어요. |
컨텍스트 메뉴 오른쪽 클릭 컨텍스트 메뉴를 가로채고 완전히 사용자 지정할 수 있어요. 메뉴 항목을 추가하거나 제거하거나 고유한 동작으로 교체할 수 있어요. |
|
파비콘 접근 현재 페이지 파비콘 URI를 가져올 수 있어요. 전용 이벤트를 통해 파비콘 변경에 반응할 수 있어요. |
가상 호스트 매핑 사용자 지정 호스트명을 로컬 폴더에 매핑할 수 있어요. 로컬 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 속성을 통해 설정하세요.
쿠키 관리
CookieManager 하위 객체는 전체 WebView2 쿠키 API를 노출해요. 현재 URL의 쿠키를 나열하고, 특정 속성을 가진 쿠키를 추가하거나 업데이트하고, 개별 쿠키를 삭제하거나 한번에 모두 지울 수 있어요.
// 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 이벤트를 통해 비동기적으로 전달돼요. 각 쿠키에는 이름, 값, 도메인, 경로, 만료일, 보안 플래그, HTTP 전용 플래그가 포함돼요. 이는 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보다 먼저 실행되므로 글로벌 설정이나 폴리필을 주입하는 데 이상적이에요.
// 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;참고. OnDownloadCompleted의 aState 매개변수는 다운로드가 성공했는지, 취소되었는지, 오류가 발생했는지를 나타내요. 다운로드된 파일을 처리하기 전에 이 값을 확인하세요.
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'
);헤더 매개변수는 HTTP 헤더에서 사용하는 것과 동일한 형식의 CRLF로 구분된 문자열을 받아요. 권한 부여 토큰, 콘텐츠 유형, 또는 서버가 기대하는 사용자 지정 헤더를 주입하는 데 유용해요.
TEdgeBrowser와의 비교
Delphi는 Delphi 10.4 Sydney부터 TEdgeBrowser를 제공해요(XE7 이상에서는 GetIt을 통해 사용 가능). 기본적인 WebView2 래퍼를 제공하지만 많은 SDK 기능을 노출하지 않아요. 아래 표는 TsgcWebView2가 어디에서 더 나아가는지를 정확하게 보여 줘요.
| 기능 | TEdgeBrowser | TsgcWebView2 |
|---|---|---|
| Delphi 버전 지원 | XE7+ only | D7 through D13 |
| 쿠키 관리 | ✗ | ✓ Full API |
| 다운로드 진행 이벤트 | ✗ | ✓ Start / Progress / Complete |
| 프로필 / 브라우징 데이터 지우기 | ✗ | ✓ |
| 오디오 / 음소거 제어 | ✗ | ✓ |
| 파비콘 접근 | ✗ | ✓ |
| 인증서 이벤트 | ✗ | ✓ |
| 기본 인증 이벤트 | ✗ | ✓ |
| 상태 표시줄 텍스트 | ✗ | ✓ |
| 가상 호스트 매핑 | ✗ | ✓ |
| 공유 버퍼 | ✗ | ✓ |
| 동기 ExecuteScript | ✓ | ✓ |
| 스크린샷 캡처 | ✓ | ✓ |
| 초기화 스크립트 | ✓ | ✓ |
| POST 내비게이션 | ✓ | ✓ |
| 인쇄 지원 | ✓ | ✓ |
| 디자인 타임 설정 | WebView가 생성되지 않으면 예외 발생 | ✓ 안전한 TPersistent 속성 |
| 컨텍스트 메뉴 | PopupMenu 병합 | 완전한 이벤트 제어 |
| 점진적 성능 저하 | ✗ | ✓ 기능별 버전 검사 |
| 원시 COM 접근 | ✓ | ✓ |
TsgcWebView2는 TEdgeBrowser가 제공하는 모든 것을 포함하면서 열두 가지 기능을 추가로 제공해요 — 쿠키 관리, 다운로드 이벤트, 프로필 제어, 오디오/음소거, 파비콘 접근, 인증서 처리, 기본 인증 이벤트, 상태 표시줄 텍스트, 가상 호스트 매핑, 공유 버퍼, 완전한 컨텍스트 메뉴 제어, 점진적 성능 저하. 또한 Delphi 7까지 거슬러 올라가는 Delphi 버전을 지원하지만 TEdgeBrowser는 최소 XE7이 필요해요.
중요. TEdgeBrowser는 설정을 COM 인터페이스에 직접 저장해요. WebView2 환경이 생성되기 전에 디자인 타임에 속성을 설정하면 액세스 위반이 발생해요. TsgcWebView2는 설정을 버퍼링하고 환경이 준비되면 적용하는 TPersistent 하위 객체를 사용해 이 문제를 완전히 방지해요.
고급 기능
PDF로 인쇄
단일 메서드 호출로 현재 페이지의 PDF를 생성할 수 있어요. 출력 파일은 비동기적으로 생성되며, 매개변수를 통해 용지 크기, 여백, 방향을 제어할 수 있어요.
sgcWebView2.PrintToPdf('C:\output\page.pdf');스크린샷 캡처
페이지의 보이는 영역을 PNG 또는 JPEG 이미지로 캡처할 수 있어요. 두 번째 매개변수가 이미지 형식을 지정해요: 0은 PNG, 1은 JPEG예요.
sgcWebView2.CapturePreviewToFile('C:\screenshots\page.png', 0); // 0 = PNG가상 호스트 매핑
사용자 지정 호스트명을 로컬 폴더에 매핑해서 내장 브라우저가 표준 HTTPS URL을 사용해 로컬 파일을 로드할 수 있어요. 이렇게 하면 CORS 문제를 방지하고 로컬 콘텐츠가 원격 콘텐츠처럼 동작하게 해요.
// Serve local files via https://app.local/
sgcWebView2.SetVirtualHostNameToFolderMapping(
'app.local', 'C:\MyApp\WebContent', 1);
sgcWebView2.Navigate('https://app.local/index.html');팁. 가상 호스트 매핑은 단일 페이지 애플리케이션에 특히 유용해요. HTML, CSS, JavaScript를 Delphi 애플리케이션과 함께 번들로 제공하고, 매핑된 호스트명을 통해 로드하면 보안 오리진이 필요한 웹 API에 완전히 접근할 수 있어요.
오디오 및 음소거 제어
로드된 문서가 오디오를 재생 중인지 감지하고 시스템 볼륨에 영향을 주지 않고 음소거를 전환할 수 있어요. 미디어가 많은 콘텐츠를 내장하는 애플리케이션에 유용해요.
sgcWebView2.IsMuted := True;
if sgcWebView2.IsDocumentPlayingAudio then
ShowMessage('Audio is playing');아키텍처 및 설계
TsgcWebView2는 개발자 대면 API를 단순하게 유지하면서 관심사를 분리하는 깔끔한 3계층 아키텍처로 구축되어 있어요:
- API 계층(COM 인터페이스). Microsoft WebView2 COM 인터페이스를 Delphi로 직접 변환한 것이에요. 이것들은 원시 구성 요소로 — 저수준, 버전별로 다르며, 애플리케이션 코드에서 직접 사용하기 위한 것이 아니에요.
- 클래스 계층(래퍼). COM 객체 수명을 관리하고, 콜백 라우팅을 처리하며, 깔끔한 객체 지향 API를 제공하는 Delphi 네이티브 래퍼 클래스예요. 이 계층이 COM 배관 작업을 숨겨 줘요.
- 컴포넌트 계층(시각적).
TsgcWebView2컴포넌트 자체 — 폼에 올려놓는 TWinControl 파생 클래스예요. 아래 클래스 계층에 매핑되는 속성, 이벤트, 메서드를 게시해요.
컴포넌트가 아직 래핑하지 않은 SDK 기능에 접근해야 하는 고급 사용자를 위해, 원시 COM 인터페이스는 WebView, Controller, Environment 속성을 통해 사용할 수 있어요. 컴포넌트의 수명 주기 관리의 혜택을 받으면서도 COM 메서드를 직접 호출할 수 있어요.
점진적 성능 저하
모든 WebView2 기능이 Edge 런타임의 모든 버전에서 사용 가능한 것은 아니에요. TsgcWebView2는 시작 시 설치된 런타임 버전을 확인하고 Supports() 메서드를 노출해서 호출 전에 기능 사용 가능 여부를 조회할 수 있어요. 이렇게 하면 오래된 Edge 버전의 머신에서 런타임 오류를 방지해요.
디자인 타임 안전성
모든 설정 가능한 설정은 TPersistent 하위 객체로 노출돼요. COM 초기화를 트리거하지 않고 Object Inspector에서 디자인 타임에 안전하게 컴포넌트를 설정할 수 있어요. 설정은 버퍼링되고 런타임에 WebView2 환경이 생성될 때 자동으로 적용돼요.
요구 사항
TsgcWebView2를 애플리케이션에서 사용하려면 다음이 필요해요:
- Microsoft Edge WebView2 Runtime. Windows 10(버전 1803 이상) 및 Windows 11에 포함되어 있어요. 이전 Windows 버전이나 제어된 배포의 경우 Microsoft에서 Evergreen Bootstrapper 또는 Fixed Version 런타임을 다운로드하세요.
- WebView2Loader.dll. 컴포넌트에 포함되어 있어요. 애플리케이션 실행 파일 옆에 놓으세요. 이 작은 DLL이 런타임 감지와 로딩을 처리해요.
- Windows 전용. WebView2는 Windows 기술이에요. 컴포넌트는 Windows 7 이상의 VCL 애플리케이션을 대상으로 해요(전체 기능 지원에는 Windows 10/11 권장).
참고. 컴포넌트를 생성하기 전에 WebView2 런타임이 설치되어 있는지 확인할 수 있어요. 설치되어 있지 않으면 사용자에게 설치를 안내하거나 대안 브라우저 컨트롤로 대체할 수 있어요.
결론
TsgcWebView2는 Delphi용으로 사용 가능한 가장 완전한 WebView2 래퍼예요. TEdgeBrowser의 엄격한 상위 집합으로, Embarcadero의 내장 컴포넌트가 노출하지 않는 열두 가지 기능을 추가해요 — 쿠키 관리, 다운로드 이벤트, 프로필 제어, 오디오 감지, 파비콘 접근, 인증서 처리, 기본 인증, 상태 표시줄 텍스트, 가상 호스트 매핑, 공유 버퍼, 완전한 컨텍스트 메뉴 제어, 점진적 성능 저하.
Delphi 7부터 Delphi 13까지 어느 WebView2 래퍼보다 넓은 Delphi 버전 범위를 지원해요. 이전 컴파일러에서 레거시 애플리케이션을 유지하든 최신 Delphi에서 새 프로젝트를 구축하든 동일한 컴포넌트와 동일한 API가 어디서나 작동해요.
API는 배우기 쉽게 설계되어 있어요 — 컴포넌트를 폼에 올려놓고, Navigate를 호출하고, 이벤트를 처리하면 돼요 — 동시에 원시 COM 접근과 기능별 버전 검사를 통한 고급 시나리오에도 충분히 강력해요. 최신 내장 브라우저가 필요한 Delphi 개발자에게 TsgcWebView2는 자연스러운 선택이에요.