Microsoft Edge WebView2 Delphi

· Bileşenler

TsgcWebView2, Microsoft Edge WebView2'yi saran yeni bir görsel Delphi bileşenidir ve herhangi bir VCL uygulamasının içinde modern, Chromium tabanlı bir tarayıcı motoru sunar. Bir forma bırakın, bir URL ayarlayın ve çerez yönetimi, indirme kontrolü, JavaScript entegrasyonu, yazdırma desteği ve daha fazlasıyla tam özellikli bir gömülü tarayıcıya sahip olun.

Son Delphi sürümleriyle birlikte gelen yerleşik TEdgeBrowser'ın aksine, TsgcWebView2 Delphi 7'den Delphi 13'e kadar her Delphi sürümünü destekler; mevcut herhangi bir WebView2 sarmalayıcısının en geniş sürüm desteği. eSeGeCe tarafından sunulan sgcWebSockets kitaplığının bir parçasıdır.

Bu makale, bileşenin özellik setini ele alır, pratik kod örnekleri gösterir, TEdgeBrowser ile bire bir karşılaştırır ve dahili mimarisini açıklar.

Özelliklere Genel Bakış

TsgcWebView2, WebView2 SDK'sinin geniş bir yüzey alanını temiz Delphi olayları ve metotları aracılığıyla sunar. İşte on iki başlıca yetenek grubu:

Navigasyon
Navigate, GoBack, GoForward, Reload, Stop. Özel başlıklar ve istek gövdeleriyle POST navigasyonunu destekler. 		JavaScript Yürütme
JavaScript'i asenkron veya senkron olarak çalıştırın. Her sayfa yüklemesinde otomatik olarak çalışan başlatma betikleri kaydedin. 		Çerez Yönetimi
Çerezleri programatik olarak alın, ekleyin, güncelleyin ve silin. Etki alanı, yol ve son kullanma tarihi dahil olmak üzere çerez özniteliklerine tam erişim.
İndirme Kontrolü
İndirme başlangıcı, ilerlemesi ve tamamlanması için olaylar. İndirmeleri özel yollara yönlendirin veya tamamen iptal edin. 		Profil Yönetimi
Yalıtılmış tarama oturumları için çoklu profil desteği. Profil başına tarama verilerini (önbellek, çerezler, geçmiş) temizleyin. 		Yazdırma Desteği
Geçerli sayfayı PDF'e yazdırın veya sistem yazdırma iletişim kutusunu gösterin. Kağıt boyutunu, yönünü ve kenar boşluklarını kontrol edin.
Ses / Sessize Alma Kontrolü
Belgenin ne zaman ses çaldığını algılayın. Sistem ses düzeyini etkilemeden sessize alma durumunu programatik olarak değiştirin. 		Sertifika İşleme
Özel olaylar aracılığıyla istemci sertifikası isteklerine ve sunucu sertifikası hatalarına yanıt verin. 		Bağlam Menüsü
Sağ tık bağlam menüsünü yakalayın ve tamamen özelleştirin. Menü öğelerini kendi eylemlerinizle ekleyin, kaldırın veya değiştirin.
Favicon Erişimi
Geçerli sayfanın favicon URI'sini alın. Özel bir olay aracılığıyla favicon değişikliklerine tepki verin. 		Sanal Host Eşleme
Özel ana bilgisayar adlarını yerel klasörlere eşleyin. Yerel HTML/CSS/JS dosyalarını gerçek bir web sunucusundan geliyormuş gibi sunun. 		Ekran Görüntüsü Yakalama
Görünür sayfa içeriğini PNG veya JPEG görseli olarak kaydedin. Küçük resimler, raporlar veya otomatik test için kullanışlıdır.

Başlarken

TsgcWebView2'yi kullanmanın en basit yolu, onu bir VCL formuna bırakıp Navigate'i çağırmaktır. Bileşen, WebView2 ortamı oluşturmayı, denetleyici başlatmayı ve görünüm bağlamayı otomatik olarak yönetir.

// 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 olayı, sayfanın yüklenmesi tamamlandıktan sonra tetiklenir ve navigasyonun başarılı olup olmadığını ve varsa hata durum kodunu bildirir. Bu, yüklenen sayfaya göre kullanıcı arayüzünüzü (pencere başlığı, durum çubuğu, ileri/geri düğme durumu) güncellemek için doğal yerdir.

Not. Bileşen, WebView2 ortamını ilk kullanımda tembel (lazy) olarak oluşturur. Ortam seçeneklerini (tarayıcı klasörü, dil, komut satırı anahtarları) yapılandırmanız gerekiyorsa, bunları Navigate'i çağırmadan önce EnvironmentOptions özelliği aracılığıyla ayarlayın.

Çerez Yönetimi

CookieManager alt nesnesi, tam WebView2 çerez API'sini sunar. Geçerli URL için çerezleri listeleyebilir, belirli özniteliklerle çerezler ekleyebilir veya güncelleyebilir ve tek tek çerezleri silebilir ya da hepsini tek seferde temizleyebilirsiniz.

// 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'i çağırdığınızda, sonuçlar OnCookiesReceived olayında asenkron olarak gelir. Her çerez; adını, değerini, etki alanını, yolunu, son kullanma tarihini, secure bayrağını ve HTTP-only bayrağını içerir. Bu, TEdgeBrowser'ın hiç sunmadığı özelliklerden biridir.

İpucu. Korunan bir sayfaya gitmeden önce kimlik doğrulama token'ları enjekte etmek için AddOrUpdateCookie'yi kullanın. Bu, gömülü tarayıcı senaryolarında oturum açma formu akışına olan ihtiyacı ortadan kaldırır.

JavaScript Entegrasyonu

TsgcWebView2, her biri farklı bir kullanım senaryosuna uygun olan, JavaScript yürütmeye yönelik üç yaklaşım sunar:

Asenkron Yürütme

ExecuteScript'i çağırın ve sonucu OnScriptExecuted olayında işleyin. Bu, standart, engellemeyen yaklaşımdır.

// 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;

Senkron Yürütme

Sonuca hemen ihtiyacınız olduğunda ExecuteScriptSync'i kullanın. Bu, betik tamamlanana kadar çağıran thread'i engeller ve sonucu doğrudan döndürür.

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

Başlatma Betikleri

Başlatma betikleri bir kez kaydedilir ve her sayfa yüklemesinde otomatik olarak çalışır. Herhangi bir sayfa JavaScript'inden önce çalışır, bu da onları genel yapılandırma veya polyfill enjekte etmek için ideal hale getirir.

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

İndirme Yönetimi

İndirmeler olay tabanlı bir modelle işlenir. Bir indirme başladığında, OnDownloadStarting olayı dosyayı özel bir yola yönlendirmenize, iptal etmenize veya varsayılanlarla devam etmesine izin vermenize olanak tanır. İndirme bittiğinde ayrı bir OnDownloadCompleted olayı tetiklenir.

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;

Not. OnDownloadCompleted'daki aState parametresi, indirmenin başarılı olup olmadığını, iptal edilip edilmediğini veya bir hatayla karşılaşıp karşılaşmadığını gösterir. İndirilen dosyayı işlemeden önce bu değeri kontrol edin.

POST Navigasyonu ve Özel Başlıklar

Standart navigasyon, bir URL'yi GET isteğiyle yükler. API testi, form gönderimi veya farklı bir HTTP metodu gerektiren herhangi bir senaryo için NavigateWithPostData, metodu, gövdeyi ve başlıkları tek bir çağrıda belirtmenize olanak tanır.

// 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'
);

headers parametresi, HTTP başlıklarının kullandığı biçimle aynı olan, CRLF ile ayrılmış bir dize kabul eder. Bu; yetkilendirme token'ları, içerik türleri veya sunucunuzun beklediği özel başlıkları enjekte etmek için kullanışlıdır.

TEdgeBrowser ile Karşılaştırma

Delphi, Delphi 10.4 Sydney'den başlayarak TEdgeBrowser ile birlikte gelir (XE7+ için GetIt aracılığıyla kullanılabilir). Temel bir WebView2 sarmalayıcısı sağlar, ancak birçok SDK özelliğini sunulmamış halde bırakır. Aşağıdaki tablo, TsgcWebView2'nin tam olarak nerede daha ileri gittiğini gösterir.

Özellik TEdgeBrowser TsgcWebView2
Delphi Sürüm Desteği Yalnızca XE7+ D7'den D13'e
Çerez Yönetimi ✗ ✓ Tam API
İndirme İlerleme Olayları ✗ ✓ Başlangıç / İlerleme / Tamamlanma
Profil / Tarama Verilerini Temizleme ✗ ✓
Ses / Sessize Alma Kontrolü ✗ ✓
Favicon Erişimi ✗ ✓
Sertifika Olayları ✗ ✓
Basic Auth Olayları ✗ ✓
Durum Çubuğu Metni ✗ ✓
Sanal Host Eşleme ✗ ✓
Paylaşılan Arabellek ✗ ✓
Senkron ExecuteScript ✓ ✓
Ekran Görüntüsü Yakalama ✓ ✓
Başlatma Betiği ✓ ✓
POST Navigasyonu ✓ ✓
Yazdırma Desteği ✓ ✓
Tasarım Zamanı Ayarları WebView oluşturulmadıysa hata verir ✓ Güvenli TPersistent özellikleri
Bağlam Menüsü PopupMenu birleştirme Tam olay kontrolü
Zarif Düşüş (Graceful Degradation) ✗ ✓ Özellik başına sürüm kontrolleri
Ham COM Erişimi ✓ ✓

TsgcWebView2, TEdgeBrowser'ın sunduğu her şeyi kapsar ve üstüne on iki özellik ekler: çerez yönetimi, indirme olayları, profil kontrolü, ses/sessize alma, favicon erişimi, sertifika işleme, basic auth olayları, durum çubuğu metni, sanal host eşleme, paylaşılan arabellek, tam bağlam menüsü kontrolü ve zarif düşüş. Ayrıca Delphi 7'ye kadar geri giden Delphi sürümlerini destekler; TEdgeBrowser ise en az XE7 gerektirir.

Önemli. TEdgeBrowser, ayarlarını doğrudan COM arayüzlerinde saklar. WebView2 ortamı oluşturulmadan önce tasarım zamanında bir özellik ayarlarsanız, bir erişim ihlali (access violation) oluşturur. TsgcWebView2, ayarları arabelleğe alan ve ortam hazır olduğunda uygulayan TPersistent alt nesneleri kullanarak bunu tamamen önler.

Gelişmiş Özellikler

PDF'e Yazdırma

Tek bir metot çağrısıyla geçerli sayfanın bir PDF'ini oluşturun. Çıktı dosyası asenkron olarak oluşturulur ve kağıt boyutunu, kenar boşluklarını ve yönü parametreler aracılığıyla kontrol edebilirsiniz.

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

Ekran Görüntüsü Yakalama

Sayfanın görünür alanını PNG veya JPEG görseli olarak yakalayın. İkinci parametre görsel biçimini belirtir: PNG için 0, JPEG için 1.

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

Sanal Host Eşleme

Gömülü tarayıcınızın yerel dosyaları standart HTTPS URL'leri kullanarak yükleyebilmesi için özel bir ana bilgisayar adını yerel bir klasöre eşleyin. Bu, CORS sorunlarını önler ve yerel içeriğin tam olarak uzak içerik gibi davranmasını sağlar.

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

İpucu. Sanal host eşleme, özellikle tek sayfalı uygulamalar için kullanışlıdır. HTML, CSS ve JavaScript'inizi Delphi uygulamanızla paketleyin, ardından güvenli bir köken gerektiren web API'lerine tam erişim için bunu eşlenmiş bir ana bilgisayar adı aracılığıyla yükleyin.

Ses ve Sessize Alma Kontrolü

Yüklenen belgenin ne zaman ses çaldığını algılayın ve sistem ses düzeyini etkilemeden sessize almayı değiştirin. Bu, medya açısından yoğun içerik gömen uygulamalar için kullanışlıdır.

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

Mimari ve Tasarım

TsgcWebView2, geliştiriciye yönelik API'yi basit tutarken sorumlulukları ayıran temiz, üç katmanlı bir mimari üzerine kuruludur:

Bileşen tarafından henüz sarmalanmamış SDK özelliklerine erişmesi gereken ileri düzey kullanıcılar için, ham COM arayüzleri WebView, Controller ve Environment özellikleri aracılığıyla kullanılabilir. Bileşenin yaşam döngüsü yönetiminden yararlanmaya devam ederken herhangi bir COM metodunu doğrudan çağırabilirsiniz.

Zarif Düşüş (Graceful Degradation)

Her WebView2 özelliği, Edge çalışma zamanının her sürümünde mevcut değildir. TsgcWebView2, başlangıçta kurulu çalışma zamanı sürümünü kontrol eder ve bir özelliği çağırmadan önce kullanılabilirliğini sorgulayabilmeniz için bir Supports() metodu sunar. Bu, eski Edge sürümlerine sahip makinelerde çalışma zamanı hatalarını önler.

Tasarım Zamanı Güvenliği

Yapılandırılabilir tüm ayarlar TPersistent alt nesneleri olarak sunulur. Bileşeni, COM başlatmayı tetiklemeden Object Inspector'da tasarım zamanında güvenle yapılandırabilirsiniz. Ayarlar arabelleğe alınır ve WebView2 ortamı çalışma zamanında oluşturulduğunda otomatik olarak uygulanır.

Gereksinimler

Uygulamanızda TsgcWebView2'yi kullanmak için şunlara ihtiyacınız vardır:

Not. Bileşeni oluşturmadan önce WebView2 çalışma zamanının kurulu olup olmadığını kontrol edebilirsiniz. Mevcut değilse, kullanıcıyı onu kurmaya yönlendirebilir veya alternatif bir tarayıcı denetimine geri dönebilirsiniz.

Sonuç

TsgcWebView2, Delphi için mevcut en eksiksiz WebView2 sarmalayıcısıdır. TEdgeBrowser'ın kesin bir üst kümesidir ve Embarcadero'nun yerleşik bileşeninin sunmadığı on iki özellik ekler: çerez yönetimi, indirme olayları, profil kontrolü, ses algılama, favicon erişimi, sertifika işleme, basic kimlik doğrulama, durum çubuğu metni, sanal host eşleme, paylaşılan arabellek, tam bağlam menüsü kontrolü ve zarif düşüş.

Herhangi bir WebView2 sarmalayıcısının en geniş Delphi sürümü yelpazesini, Delphi 7'den Delphi 13'e kadar destekler. Daha eski bir derleyicide eski bir uygulamayı sürdürüyor ya da en son Delphi'de yeni bir proje oluşturuyor olun, aynı bileşen ve aynı API her yerde çalışır.

API; bir bileşeni forma bırakmak, Navigate'i çağırmak ve olayları işlemek gibi öğrenmesi kolay olacak şekilde tasarlanmıştır; aynı zamanda ham COM erişimi ve özellik başına sürüm kontrolü aracılığıyla gelişmiş senaryolar için yeterince güçlü kalır. Modern bir gömülü tarayıcıya ihtiyaç duyan Delphi geliştiricileri için TsgcWebView2 doğal seçimdir.