TsgcWebView2 to nowy wizualny komponent Delphi opakowujący Microsoft Edge WebView2, zapewniający nowoczesny silnik przeglądarki oparty na Chromium w dowolnej aplikacji VCL. Upuść go na formularz, ustaw URL i masz w pełni funkcjonalną wbudowaną przeglądarkę — z zarządzaniem cookies, kontrolą pobierania, integracją JavaScript, obsługą drukowania i nie tylko.
W odróżnieniu od wbudowanego TEdgeBrowser dołączanego do nowych wersji Delphi, TsgcWebView2 obsługuje każdą wersję Delphi od Delphi 7 do Delphi 13 — najszerszy zakres wersji spośród dostępnych wrapperów WebView2. Jest częścią biblioteki sgcWebSockets firmy eSeGeCe.
Ten artykuł opisuje zestaw funkcji, pokazuje praktyczne przykłady kodu, porównuje je bezpośrednio z TEdgeBrowser i wyjaśnia wewnętrzną architekturę.
Przegląd funkcji
TsgcWebView2 udostępnia szeroką powierzchnię SDK WebView2 przez przejrzyste zdarzenia i metody Delphi. Oto dwanaście głównych grup możliwości:
|
Nawigacja Navigate, GoBack, GoForward, Reload, Stop. Obsługuje nawigację POST z niestandardowymi nagłówkami i treścią żądania. |
Wykonanie JavaScript Uruchamia JavaScript asynchronicznie lub synchronicznie. Rejestruj skrypty inicjujące wykonywane automatycznie przy każdym załadowaniu strony. |
Zarządzanie cookies Pobierz, dodaj, zaktualizuj i usuń cookies programowo. Pełny dostęp do atrybutów cookies, w tym domeny, ścieżki i daty wygaśnięcia. |
|
Kontrola pobierania Zdarzenia dla rozpoczęcia, postępu i zakończenia pobierania. Przekieruj pobieranie na niestandardowe ścieżki lub całkowicie je anuluj. |
Zarządzanie profilami Obsługa wielu profili dla izolowanych sesji przeglądania. Wyczyść dane przeglądania (cache, cookies, historię) dla każdego profilu. |
Obsługa drukowania Drukuj bieżącą stronę do PDF lub pokaż systemowe okno drukowania. Kontroluj rozmiar papieru, orientację i marginesy. |
|
Kontrola audio / wyciszenia Wykrywaj, gdy dokument odtwarza audio. Przełącz stan wyciszenia programowo bez wpływu na głośność systemową. |
Obsługa certyfikatów Odpowiadaj na żądania certyfikatów klienta i błędy certyfikatów serwera przez dedykowane zdarzenia. |
Menu kontekstowe Przechwytuj i w pełni dostosowuj menu kontekstowe prawego przycisku myszy. Dodawaj, usuwaj lub zastępuj elementy menu własnymi akcjami. |
|
Dostęp do favicon Pobierz URI favicon bieżącej strony. Reaguj na zmiany favicon przez dedykowane zdarzenie. |
Mapowanie wirtualnych hostów Mapuj niestandardowe nazwy hostów na lokalne foldery. Serwuj lokalne pliki HTML/CSS/JS tak, jakby pochodziły z prawdziwego serwera WWW. |
Przechwytywanie zrzutów ekranu Zapisuj widoczną zawartość strony jako obraz PNG lub JPEG. Przydatne do miniatur, raportów lub automatycznego testowania. |
Pierwsze kroki
Najprostszy sposób użycia TsgcWebView2 to upuszczenie go na formularz VCL i wywołanie Navigate. Komponent obsługuje tworzenie środowiska WebView2, inicjalizację kontrolera i powiązanie widoku automatycznie.
// 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;Zdarzenie OnNavigationCompleted jest wywoływane po zakończeniu ładowania strony, informując o powodzeniu nawigacji i ewentualnym kodzie błędu. To naturalne miejsce do aktualizacji interfejsu — tytułu okna, paska statusu, stanu przycisków wstecz/dalej — na podstawie załadowanej strony.
Uwaga. Komponent tworzy środowisko WebView2 leniwie przy pierwszym użyciu. Jeśli chcesz skonfigurować opcje środowiska (folder przeglądarki, język, przełączniki wiersza poleceń), ustaw je przez właściwość EnvironmentOptions przed wywołaniem Navigate.
Zarządzanie cookies
Podobjekt CookieManager udostępnia pełne API cookies WebView2. Możesz wylistować cookies dla bieżącego URL, dodawać lub aktualizować cookies z określonymi atrybutami oraz usuwać poszczególne cookies lub czyścić je wszystkie naraz.
// 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', '/');Po wywołaniu GetCookies wyniki docierają asynchronicznie do zdarzenia OnCookiesReceived. Każdy cookie zawiera nazwę, wartość, domenę, ścieżkę, datę wygaśnięcia, flagę secure i flagę HTTP-only. Jest to jedna z funkcji, których TEdgeBrowser w ogóle nie udostępnia.
Wskazówka. Używaj AddOrUpdateCookie do wstrzykiwania tokenów uwierzytelniania przed nawigacją do chronionej strony. Eliminuje to potrzebę przepływu formularza logowania w scenariuszach z wbudowaną przeglądarką.
Integracja JavaScript
TsgcWebView2 zapewnia trzy podejścia do wykonania JavaScript, każde odpowiednie dla innego przypadku użycia:
Wykonanie asynchroniczne
Wywołaj ExecuteScript i obsługuj wynik w zdarzeniu OnScriptExecuted. To standardowe, nieblokujące podejście.
// 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;Wykonanie synchroniczne
Gdy potrzebujesz wyniku natychmiast, użyj ExecuteScriptSync. Blokuje wątek wywołujący do momentu zakończenia skryptu i zwraca wynik bezpośrednio.
var
vTitle: string;
begin
vTitle := sgcWebView2.ExecuteScriptSync('document.title');
Caption := vTitle;
end;Skrypty inicjujące
Skrypty inicjujące są rejestrowane raz i wykonują się automatycznie przy każdym załadowaniu strony. Uruchamiają się przed każdym JavaScript strony, co czyni je idealnymi do wstrzykiwania globalnej konfiguracji lub polyfilli.
// Runs on every page load, before any page scripts
sgcWebView2.AddInitScript('window.appVersion = "1.0";');Zarządzanie pobieraniem
Pobieranie jest obsługiwane przez model sterowany zdarzeniami. Gdy pobieranie się rozpoczyna, zdarzenie OnDownloadStarting pozwala przekierować plik na niestandardową ścieżkę, anulować je lub kontynuować z domyślnymi ustawieniami. Oddzielne zdarzenie OnDownloadCompleted jest wywoływane po zakończeniu pobierania.
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;Uwaga. Parametr aState w OnDownloadCompleted wskazuje, czy pobieranie się powiodło, zostało anulowane lub napotkało błąd. Sprawdź tę wartość przed przetworzeniem pobranego pliku.
Nawigacja POST i niestandardowe nagłówki
Standardowa nawigacja ładuje URL żądaniem GET. Do testowania API, wysyłania formularzy lub dowolnego scenariusza wymagającego innej metody HTTP, NavigateWithPostData pozwala określić metodę, treść i nagłówki w jednym wywołaniu.
// 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'
);Parametr nagłówków przyjmuje ciąg rozdzielony CRLF, w tym samym formacie co nagłówki HTTP. Jest to przydatne do wstrzykiwania tokenów autoryzacji, typów treści lub niestandardowych nagłówków oczekiwanych przez serwer.
Porównanie z TEdgeBrowser
Delphi dołącza TEdgeBrowser od Delphi 10.4 Sydney (dostępny przez GetIt dla XE7+). Zapewnia podstawowy wrapper WebView2, ale pozostawia wiele funkcji SDK nieudostępnionych. Poniższa tabela pokazuje dokładnie, gdzie TsgcWebView2 idzie dalej.
| Funkcja | TEdgeBrowser | TsgcWebView2 |
|---|---|---|
| Obsługa wersji Delphi | XE7+ only | D7 through D13 |
| Zarządzanie cookies | ✗ | ✓ Full API |
| Zdarzenia postępu pobierania | ✗ | ✓ Start / Progress / Complete |
| Profil / czyszczenie danych przeglądania | ✗ | ✓ |
| Kontrola audio / wyciszenia | ✗ | ✓ |
| Dostęp do favicon | ✗ | ✓ |
| Zdarzenia certyfikatów | ✗ | ✓ |
| Zdarzenia uwierzytelniania podstawowego | ✗ | ✓ |
| Tekst paska statusu | ✗ | ✓ |
| Mapowanie wirtualnych hostów | ✗ | ✓ |
| Współdzielony bufor | ✗ | ✓ |
| Synchroniczne ExecuteScript | ✓ | ✓ |
| Przechwytywanie zrzutów ekranu | ✓ | ✓ |
| Skrypt inicjujący | ✓ | ✓ |
| Nawigacja POST | ✓ | ✓ |
| Obsługa drukowania | ✓ | ✓ |
| Ustawienia projektowania | Rzuca wyjątek jeśli WebView nie jest utworzony | ✓ Bezpieczne właściwości TPersistent |
| Menu kontekstowe | Scalanie PopupMenu | Pełna kontrola przez zdarzenia |
| Degradacja łaskawa | ✗ | ✓ Sprawdzanie wersji dla każdej funkcji |
| Bezpośredni dostęp COM | ✓ | ✓ |
TsgcWebView2 obejmuje wszystko, co oferuje TEdgeBrowser, i dodaje dwanaście funkcji: zarządzanie cookies, zdarzenia pobierania, kontrolę profili, audio/wyciszenie, dostęp do favicon, obsługę certyfikatów, zdarzenia uwierzytelniania podstawowego, tekst paska statusu, mapowanie wirtualnych hostów, współdzielony bufor, pełną kontrolę menu kontekstowego i degradację łaskawą. Obsługuje też wersje Delphi sięgające aż do Delphi 7, podczas gdy TEdgeBrowser wymaga co najmniej XE7.
Ważne. TEdgeBrowser przechowuje ustawienia bezpośrednio w interfejsach COM. Ustawienie właściwości w czasie projektowania przed utworzeniem środowiska WebView2 powoduje naruszenie dostępu. TsgcWebView2 całkowicie tego unika, używając podobjektów TPersistent buforujących ustawienia i stosujących je po gotowości środowiska.
Zaawansowane funkcje
Drukowanie do PDF
Wygeneruj PDF bieżącej strony jednym wywołaniem metody. Plik wyjściowy jest tworzony asynchronicznie; rozmiar papieru, marginesy i orientację kontrolujesz przez parametry.
sgcWebView2.PrintToPdf('C:\output\page.pdf');Przechwytywanie zrzutów ekranu
Przechwyć widoczny obszar strony jako obraz PNG lub JPEG. Drugi parametr określa format obrazu: 0 dla PNG, 1 dla JPEG.
sgcWebView2.CapturePreviewToFile('C:\screenshots\page.png', 0); // 0 = PNGMapowanie wirtualnych hostów
Zamapuj niestandardową nazwę hosta na lokalny folder, aby wbudowana przeglądarka mogła ładować lokalne pliki za pomocą standardowych adresów HTTPS. Pozwala to uniknąć problemów CORS i sprawia, że lokalna zawartość zachowuje się dokładnie jak zdalna.
// Serve local files via https://app.local/
sgcWebView2.SetVirtualHostNameToFolderMapping(
'app.local', 'C:\MyApp\WebContent', 1);
sgcWebView2.Navigate('https://app.local/index.html');Wskazówka. Mapowanie wirtualnych hostów jest szczególnie przydatne dla aplikacji jednostronicowych. Dołącz HTML, CSS i JavaScript do aplikacji Delphi, a następnie ładuj je przez zamapowaną nazwę hosta, aby uzyskać pełny dostęp do webowych API wymagających bezpiecznego origin.
Kontrola audio i wyciszenia
Wykrywaj, gdy załadowany dokument odtwarza audio, i przełączaj wyciszenie bez wpływu na głośność systemową. Jest to przydatne dla aplikacji osadzających treści multimedialne.
sgcWebView2.IsMuted := True;
if sgcWebView2.IsDocumentPlayingAudio then
ShowMessage('Audio is playing');Architektura i projekt
TsgcWebView2 jest zbudowany na czystej trójwarstwowej architekturze, która rozdziela odpowiedzialności, zachowując proste API dla programisty:
- Warstwa API (interfejsy COM). Bezpośrednie tłumaczenia interfejsów COM Microsoft WebView2 na Delphi. Są to surowe elementy składowe — niskopoziomowe, specyficzne dla wersji i nieprzeznaczone do bezpośredniego użycia w kodzie aplikacji.
- Warstwa klas (wrappery). Natywne klasy wrapperów Delphi zarządzające czasami życia obiektów COM, obsługą routingu callbacków i zapewniające przejrzyste obiektowe API. Ta warstwa chroni przed instalacją COM.
- Warstwa komponentu (wizualna). Sam komponent
TsgcWebView2— descendant TWinControl, który upuszczasz na formularz. Publikuje właściwości, zdarzenia i metody mapowane do warstwy klas poniżej.
Dla zaawansowanych użytkowników potrzebujących dostępu do funkcji SDK jeszcze nieopakowanych przez komponent, surowe interfejsy COM są dostępne przez właściwości WebView, Controller i Environment. Możesz wywoływać dowolną metodę COM bezpośrednio, korzystając jednocześnie z zarządzania cyklem życia komponentu.
Degradacja łaskawa
Nie każda funkcja WebView2 jest dostępna w każdej wersji środowiska uruchomieniowego Edge. TsgcWebView2 sprawdza zainstalowaną wersję środowiska przy starcie i udostępnia metodę Supports(), dzięki której możesz sprawdzić dostępność funkcji przed jej wywołaniem. Zapobiega to błędom w czasie wykonania na komputerach ze starszymi wersjami Edge.
Bezpieczeństwo w czasie projektowania
Wszystkie konfigurowalne ustawienia są udostępnione jako podobjekty TPersistent. Możesz bezpiecznie konfigurować komponent w czasie projektowania w Inspektorze Obiektów bez uruchamiania inicjalizacji COM. Ustawienia są buforowane i stosowane automatycznie po utworzeniu środowiska WebView2 w czasie wykonania.
Wymagania
Aby użyć TsgcWebView2 w aplikacji, potrzebujesz:
- Środowisko uruchomieniowe Microsoft Edge WebView2. Dołączone do Windows 10 (wersja 1803+) i Windows 11. Dla starszych wersji Windows lub kontrolowanych wdrożeń pobierz Evergreen Bootstrapper lub Fixed Version runtime od Microsoft.
- WebView2Loader.dll. Dołączone do komponentu. Umieść je obok pliku wykonywalnego aplikacji. Ten mały DLL obsługuje wykrywanie i ładowanie środowiska uruchomieniowego.
- Tylko Windows. WebView2 to technologia Windows. Komponent celuje w aplikacje VCL na Windows 7 i nowszych (Windows 10/11 zalecany dla pełnej obsługi funkcji).
Uwaga. Możesz sprawdzić, czy środowisko uruchomieniowe WebView2 jest zainstalowane przed utworzeniem komponentu. Jeśli nie jest obecne, możesz skierować użytkownika do jego instalacji lub użyć alternatywnej kontrolki przeglądarki.
Podsumowanie
TsgcWebView2 to najkompletniejszy wrapper WebView2 dostępny dla Delphi. Jest ścisłym nadzbiorem TEdgeBrowser, dodającym dwanaście funkcji, których wbudowany komponent Embarcadero nie udostępnia: zarządzanie cookies, zdarzenia pobierania, kontrolę profili, wykrywanie audio, dostęp do favicon, obsługę certyfikatów, uwierzytelnianie podstawowe, tekst paska statusu, mapowanie wirtualnych hostów, współdzielony bufor, pełną kontrolę menu kontekstowego i degradację łaskawą.
Obsługuje najszerszy zakres wersji Delphi spośród wszystkich wrapperów WebView2, od Delphi 7 do Delphi 13. Niezależnie czy utrzymujesz aplikację legacy na starszym kompilatorze czy budujesz nowy projekt na najnowszym Delphi, ten sam komponent i to samo API działają wszędzie.
API zostało zaprojektowane tak, aby było łatwe do nauczenia — upuść komponent na formularz, wywołaj Navigate i obsługuj zdarzenia — a jednocześnie pozostaje wystarczająco potężne dla zaawansowanych scenariuszy przez bezpośredni dostęp COM i sprawdzanie wersji dla każdej funkcji. Dla programistów Delphi potrzebujących nowoczesnej wbudowanej przeglądarki TsgcWebView2 jest naturalnym wyborem.