Web görünümü

Web görünümü denetimi, Microsoft Edge Eski işleme altyapısını kullanarak web içeriğini işleyen bir görünümü uygulamanıza ekler. Bağlantılar bir web görünümü kontrolünde de görüntülenebilir ve işlev görebilir.

Önemli

Denetim WebView2 , Windows Uygulama SDK'sında WinUI'nin bir parçası olarak kullanılabilir. WebView2 uygulamalarda web içeriğini görüntülemek için işleme altyapısı olarak Microsoft Edge 'i (Chromium) kullanır. Daha fazla bilgi için bkz. Microsoft Edge WebView2'ye Giriş, WinUI 3'te WebView2'yi kullanmaya başlama (Önizleme)ve WinUI API başvurusunda WebView2 .

Doğru kontrol bu mu?

Uygulama paketinizde uzak bir web sunucusundan, dinamik olarak oluşturulan koddan veya içerik dosyalarından zengin biçimlendirilmiş HTML içeriği görüntülemek için bir web görünümü denetimi kullanın. Zengin içerik ayrıca betik kodu içerebilir ve betik ile uygulamanızın kodu arasında karşılıklı iletişim kurabilir.

Recommendations

Yüklenen web sitesinin cihaz için doğru biçimlendirildiğinden ve uygulamanızın geri kalanıyla tutarlı renkler, tipografi ve gezinti kullandığından emin olun.
Giriş alanları uygun şekilde boyutlandırılmalıdır. Kullanıcılar metin girmek için yakınlaştırabileceklerinin farkında olmayabilir.
Web görünümü uygulamanızın geri kalanı gibi görünmüyorsa, ilgili görevleri yerine getirmenin alternatif denetimlerini veya yollarını göz önünde bulundurun. Web görünümünüz uygulamanızın geri kalanıyla eşleşiyorsa, kullanıcılar tüm bunları tek bir sorunsuz deneyim olarak görür.

Web görünümü oluşturma

UWP API'leri:WebView sınıfı
WinUI 2 Galeri uygulamasını açın ve WebView'un nasıl çalıştığını görün. WinUI 2 Galeri uygulaması çoğu WinUI 2 denetimi, özelliği ve işlevselliğine ilişkin etkileşimli örnekler içerir. Uygulamayı Microsoft Store'dan alın veya GitHub'dan kaynak kodunu alın.

Web görünümünün görünümünü değiştirme

WebView bir Denetim alt sınıfı olmadığından bir denetim şablonu yoktur. Ancak, web görünümünün bazı görsel yönlerini denetlemek için çeşitli özellikler ayarlayabilirsiniz.

Görüntüleme alanını kısıtlamak için Genişlik ve Yükseklik özelliklerini ayarlayın.
Web görünümünü çevirmek, ölçeklendirmek, eğmek ve döndürmek için RenderTransform özelliğini kullanın.
Web görünümünün opaklığını denetlemek için Opacity özelliğini ayarlayın.
HTML içeriği bir renk belirtmediğinde web sayfası arka planı olarak kullanılacak bir renk belirtmek için DefaultBackgroundColor özelliğini ayarlayın.

Web sayfası başlığını alma

DocumentTitle özelliğini kullanarak web görünümünde şu anda görüntülenen HTML belgesinin başlığını alabilirsiniz.

Giriş olayları ve sekme sırası

WebView bir Denetim alt sınıfı olmasa da, klavye giriş odağını alır ve sekme dizisine katılır. Bir Focus yöntemi sağlar ve GotFocus ve LostFocus olaylarını sunar, ancak sekmeyle ilgili özellikleri yoktur. Sekme dizisindeki konumu, XAML belge sırasındaki konumuyla aynıdır. Sekme dizisi, web görünümü içeriğindeki giriş odağını alabilen tüm öğeleri içerir.

WebView sınıf sayfasındaki Olaylar tablosunda belirtildiği gibi, web görünümü KeyDown, KeyUp ve PointerPressed gibi UIElement'ten devralınan kullanıcı giriş olaylarının çoğunu desteklemez. Bunun yerine, HTML olay işleyicilerini kullanmak ve WEBView.ScriptNotify kullanarak uygulamayı bilgilendirmek için HTML olay işleyicisinden window.external.notify kullanmak için JavaScript eval işleviyle InvokeScriptAsync kullanabilirsiniz.

İçeriğe gezinme

Web görünümü temel gezinti için çeşitli API'ler sağlar: GoBack, GoForward, Stop, Refresh, CanGoBack ve CanGoForward. Bunları kullanarak uygulamanıza tipik web gözatma özellikleri ekleyebilirsiniz.

Web görünümünün ilk içeriğini ayarlamak için XAML'de Source özelliğini ayarlayın. XAML ayrıştırıcısı dizeyi otomatik olarak Uri'ye dönüştürür.

<!-- Source file is on the web. -->
<WebView x:Name="webView1" Source="http://www.contoso.com"/>

<!-- Source file is in local storage. -->
<WebView x:Name="webView2" Source="ms-appdata:///local/intro/welcome.html"/>

<!-- Source file is in the app package. -->
<WebView x:Name="webView3" Source="ms-appx-web:///help/about.html"/>

Source özelliği kodda ayarlanabilir, ancak bunu yapmak yerine genellikle koda içerik yüklemek için Navigate yöntemlerinden birini kullanırsınız.

Web içeriğini yüklemek için Http veya https düzenini kullanan bir Uri ile Navigate yöntemini kullanın.

webView1.Navigate(new Uri("http://www.contoso.com"));

POST isteği ve HTTP üst bilgileri içeren bir URI'ye gitmek için NavigateWithHttpRequestMessage yöntemini kullanın. Bu yöntem, HttpRequestMessage.Method özellik değeri için yalnızca HttpMethod.Post ve HttpMethod.Get destekler.

Uygulamanızın LocalFolder veya TemporaryFolder veri depolarından sıkıştırılmamış ve şifrelenmemiş içerik yüklemek için Navigate yöntemini ms-appdata şemasını kullanan bir Urikullanın. Bu düzen için web görünümü desteği, içeriğinizi yerel veya geçici klasörün altındaki bir alt klasöre yerleştirmenizi gerektirir. Bu, ms-appdata:///local/folder/file.html ve ms-appdata:///temp/folderfile.html gibi / gezintiyi etkinleştirir. (Sıkıştırılmış veya şifrelenmiş dosyaları yüklemek için bkz . NavigateToLocalStreamUri.)

Bu birinci düzey alt klasörlerin her biri, diğer birinci düzey alt klasörlerdeki içerikten yalıtılır. Örneğin, ms-appdata:///temp/folder1/file.htmladresine gidebilirsiniz, ancak bu dosyada ms-appdata:///temp/folder2/file.htmlbağlantısına sahip olamazsınız. Ancak, ms-appx-web şemasınıkullanarak uygulama paketindeki HTML içeriğine ve http ve https URI şemalarını kullanarak web içeriğine bağlanabilirsiniz.

webView1.Navigate(new Uri("ms-appdata:///local/intro/welcome.html"));

Uygulama paketinizden içerik yüklemek için,ms-appx-web düzenini kullanan bir Uri ile Navigate yöntemini kullanın.

webView1.Navigate(new Uri("ms-appx-web:///help/about.html"));

NavigateToLocalStreamUri yöntemini kullanarak özel bir çözümleyici aracılığıyla yerel içerik yükleyebilirsiniz. Bu, web tabanlı içeriği çevrimdışı kullanım için indirme ve önbelleğe alma veya sıkıştırılmış bir dosyadan içerik ayıklama gibi gelişmiş senaryolara olanak tanır.

Web görünümü denetimi, gezinti ve içerik yükleme durumlarına yanıt vermek için kullanabileceğiniz çeşitli olaylar sağlar. Olaylar kök web görünümü içeriği için şu sırada gerçekleşir: NavigationStarting, ContentLoading, DOMContentLoaded, NavigationCompleted

NavigationStarting - Web görünümü yeni içeriğe gitmeden önce gerçekleşir. WebViewNavigationStartingEventArgs.Cancel özelliğini true olarak ayarlayarak bu olay için bir işleyicide gezintiyi iptal edebilirsiniz.

webView1.NavigationStarting += webView1_NavigationStarting;

private void webView1_NavigationStarting(object sender, WebViewNavigationStartingEventArgs args)
{
    // Cancel navigation if URL is not allowed. (Implementation of IsAllowedUri not shown.)
    if (!IsAllowedUri(args.Uri))
        args.Cancel = true;
}

ContentLoading - Web görünümü yeni içerik yüklemeye başladığında gerçekleşir.

webView1.ContentLoading += webView1_ContentLoading;

private void webView1_ContentLoading(WebView sender, WebViewContentLoadingEventArgs args)
{
    // Show status.
    if (args.Uri != null)
    {
        statusTextBlock.Text = "Loading content for " + args.Uri.ToString();
    }
}

DOMContentLoaded - Web görünümü geçerli HTML içeriğini ayrıştırma işlemini tamamladığında gerçekleşir.

webView1.DOMContentLoaded += webView1_DOMContentLoaded;

private void webView1_DOMContentLoaded(WebView sender, WebViewDOMContentLoadedEventArgs args)
{
    // Show status.
    if (args.Uri != null)
    {
        statusTextBlock.Text = "Content for " + args.Uri.ToString() + " has finished loading";
    }
}

NavigationCompleted - Web görünümü geçerli içeriği yüklemeyi bitirdiğinde veya gezinti başarısız olduğunda gerçekleşir. Gezintinin başarısız olup olmadığını belirlemek için WebViewNavigationCompletedEventArgs sınıfının IsSuccess ve WebErrorStatus özelliklerini denetleyin.

webView1.NavigationCompleted += webView1_NavigationCompleted;

private void webView1_NavigationCompleted(WebView sender, WebViewNavigationCompletedEventArgs args)
{
    if (args.IsSuccess == true)
    {
        statusTextBlock.Text = "Navigation to " + args.Uri.ToString() + " completed successfully.";
    }
    else
    {
        statusTextBlock.Text = "Navigation to: " + args.Uri.ToString() +
                               " failed with error " + args.WebErrorStatus.ToString();
    }
}

Benzer olaylar web görünümü içeriğindeki her iframe için aynı sırada gerçekleşir:

FrameNavigationStarting - Web görünümündeki bir çerçeve yeni içeriğe yönelmeden önce gerçekleşir.
FrameContentLoading - Web görünümünde bir çerçeve yeni içerik yüklemeye başladığında gerçekleşir.
FrameDOMContentLoaded - Web görünümündeki bir çerçevenin geçerli HTML içeriğini ayrıştırma işlemi tamamlandığında gerçekleşir.
FrameNavigationCompleted - Web görünümündeki bir çerçeve içeriğini yüklemeyi bitirdiğinde gerçekleşir.

Olası sorunlara yanıt verme

Uzun süre çalışan betikler, web görünümünün yükleyemediği içerikler ve güvensiz içerik uyarıları gibi olası sorunlara yanıt verebilirsiniz.

Betikler çalışırken uygulamanız yanıt vermiyor gibi görünebilir. LongRunningScriptDetected olayı, web görünümü JavaScript'i yürütür ve betiği kesme fırsatı sağlarken düzenli aralıklarla gerçekleşir. Betiğin ne kadar süredir çalıştığını belirlemek için ExecutionTime özelliğini WebViewLongRunningScriptDetectedEventArgsiçinde denetleyin. Betiği durdurmak için, StopPageScriptExecution özelliğini event args değerini trueolarak ayarlayın. Durdurulan betik, sonraki bir web görünümü gezintisi sırasında yeniden yüklenmediği sürece yeniden yürütülmeyecektir.

Web görünümü denetimi rastgele dosya türlerini barındıramaz. Web görünümünün barındıramayacağı içerik yüklenmeye çalışıldığında, UnviewableContentIdentified olayı gerçekleşir. Bu olayı işleyebilir ve kullanıcıya bildirebilir veya Launcher sınıfını kullanarak dosyayı bir dış tarayıcıya veya başka bir uygulamaya yönlendirebilirsiniz.

Benzer şekilde, DesteklenmeyenUriSchemeIdentified olayı, fbconnect:// veya mailto:// gibi web içeriğinde desteklenmeyen bir URI şeması kullanıldığında oluşur. Varsayılan sistem başlatıcının URI'yi başlatmasına izin vermek yerine özel davranış sağlamak için bu olayı işleyebilirsiniz.

UnsafeContentWarningDisplayingevent, web görünümünde SmartScreen Filtresi tarafından güvenli olmayan olarak bildirilen içerik için bir uyarı sayfası görüntülendiğinde oluşur. Kullanıcı gezintiye devam etmeyi seçerse, sayfaya yapılan sonraki gezinti uyarıyı görüntülemez veya olayı tetikler.

Web görünümü içeriği için özel durumları işleme

Web içeriklerinde tam ekran video oynatma gibi tam ekran deneyimlerini algılamak, yanıtlamak ve etkinleştirmek için ContainsFullScreenElement özelliğini ve ContainsFullScreenElementChanged olayını kullanabilirsiniz. Örneğin, uygulama görünümünüzün tamamını kaplarken web görünümünü yeniden boyutlandırmak için ContainsFullScreenElementChanged olayını kullanabilir veya aşağıdaki örnekte gösterildiği gibi, tam ekran web deneyimi istendiğinde pencereli bir uygulamayı tam ekran moduna alabilirsiniz.

// Assume webView is defined in XAML
webView.ContainsFullScreenElementChanged += webView_ContainsFullScreenElementChanged;

private void webView_ContainsFullScreenElementChanged(WebView sender, object args)
{
    var applicationView = ApplicationView.GetForCurrentView();

    if (sender.ContainsFullScreenElement)
    {
        applicationView.TryEnterFullScreenMode();
    }
    else if (applicationView.IsFullScreenMode)
    {
        applicationView.ExitFullScreenMode();
    }
}

Barındırılan web içeriğinin açılan pencere gibi yeni bir pencere görüntülenmesini istediği durumları işlemek için NewWindowRequested olayını kullanabilirsiniz. İstenen pencerenin içeriğini görüntülemek için başka bir WebView denetimi kullanabilirsiniz.

Özel özellikler gerektiren web özelliklerini etkinleştirmek için PermissionRequested olayını kullanın. Bunlar şu anda coğrafi konum, IndexedDB depolama alanı ve kullanıcı ses ve videosunu (örneğin, bir mikrofondan veya web kamerasından) içerir. Uygulamanız kullanıcı konumuna veya kullanıcı medyasına erişiyorsa, yine de uygulama bildiriminde bu özelliği bildirmeniz gerekir. Örneğin, coğrafi konum kullanan bir uygulamanın Package.appxmanifest dosyasında en az aşağıdaki yetenek bildirimlerine ihtiyacı vardır:

  <Capabilities>
    <Capability Name="internetClient" />
    <DeviceCapability Name="location" />
  </Capabilities>

PermissionRequested olayını işleyen uygulamaya ek olarak, kullanıcının bu özelliklerin etkinleştirilmesi için konum veya medya özellikleri isteyen uygulamalar için standart sistem iletişim kutularını onaylaması gerekir.

Bir uygulamanın Bing'den bir haritada coğrafi konumu nasıl etkinleştireceğini gösteren bir örnek aşağıda verilmiştir:

// Assume webView is defined in XAML
webView.PermissionRequested += webView_PermissionRequested;

private void webView_PermissionRequested(WebView sender, WebViewPermissionRequestedEventArgs args)
{
    if (args.PermissionRequest.PermissionType == WebViewPermissionType.Geolocation &&
        args.PermissionRequest.Uri.Host == "www.bing.com")
    {
        args.PermissionRequest.Allow();
    }
}

Uygulamanız bir izin isteğini yanıtlamak için kullanıcı girişi veya diğer asenkron işlemler gerektiriyorsa, Defer yöntemini kullanarak WebViewPermissionRequest nesnesi üzerinde daha sonra işleme alınabilecek bir WebViewDeferredPermissionRequest oluşturun. Bkz . WebViewPermissionRequest.Defer.

Kullanıcıların web görünümünde barındırılan bir web sitesinde güvenli bir şekilde oturumunu kapatması gerekiyorsa veya güvenlik önemliyse, bir web görünümü oturumundan yerel olarak önbelleğe alınmış tüm içeriği temizlemek için ClearTemporaryWebDataAsync statik yöntemini çağırın. Bu, kötü amaçlı kullanıcıların hassas verilere erişmesini engeller.

Web görünümü içeriğiyle etkileşim kurma

Web görünümü içeriğine betik çağırmak veya eklemek için InvokeScriptAsync yöntemini ve web görünümü içeriğinden bilgi almak için ScriptNotify olayını kullanarak web görünümünün içeriğiyle etkileşim kurabilirsiniz.

Web görünümü içeriğinin içinde JavaScript'i çağırmak için InvokeScriptAsync yöntemini kullanın. Çağrılan betik yalnızca dize değerlerini döndürebilir.

Örneğin, adlı webView1 bir web görünümünün içeriği 3 parametre alan adlı setDate bir işlev içeriyorsa, bunu şu şekilde çağırabilirsiniz.

string[] args = {"January", "1", "2000"};
string returnValue = await webView1.InvokeScriptAsync("setDate", args);

Web sayfasına içerik eklemek için JavaScript eval işleviyle InvokeScriptAsync kullanabilirsiniz.

Burada, XAML metin kutusunun (nameTextBox.Text) metni, webView1 içinde barındırılan bir HTML sayfasındaki div'e yazılır.

private async void Button_Click(object sender, RoutedEventArgs e)
{
    string functionString = String.Format("document.getElementById('nameDiv').innerText = 'Hello, {0}';", nameTextBox.Text);
    await webView1.InvokeScriptAsync("eval", new string[] { functionString });
}

Web görünümü içeriğindeki betikler, uygulamanıza geri bilgi göndermek için bir dize parametresiyle window.external.notify kullanabilir. Bu iletileri almak için ScriptNotify olayını işleyin.

Window.external.notify çağrılırken dış web sayfasının ScriptNotify olayını tetikleebilmesi için, sayfanın URI'sini uygulama bildiriminin ApplicationContentUriRules bölümüne eklemeniz gerekir. (Bunu Microsoft Visual Studio'da Package.appxmanifest tasarımcısının İçerik URI'leri sekmesinde yapabilirsiniz.) Bu listedeki URI'ler HTTPS kullanmalıdır ve alt etki alanı joker karakterlerini (örneğin, https://*.microsoft.com) içerebilir, ancak etki alanı joker karakterlerini (örneğin ve https://*.comhttps://*.*) içeremezler. Bildirim gereksinimi uygulama paketinden kaynaklanan, ms-local-stream:// URI'sini kullanan veya NavigateToString kullanılarak yüklenen içeriğe uygulanmaz.

Web görünümünde Windows Çalışma Zamanı'na erişme

AddWebAllowedObject yöntemini kullanarak bir Windows Çalışma Zamanı bileşeninden web görünümünün JavaScript bağlamı içine yerel bir sınıf örneği ekleyebilirsiniz. Bu, web görünümünün JavaScript içeriğinde söz konusu nesnenin yerel yöntemlerine, özelliklerine ve olaylarına tam erişim sağlar. Sınıfın AllowForWeb özniteliğiyle donatılması gerekir.

Örneğin, bu kod, bir Windows Çalışma Zamanı bileşeninden içeri aktarılan MyClass örneğini bir web görünümüne enjekte eder.

private void webView_NavigationStarting(WebView sender, WebViewNavigationStartingEventArgs args)
{
    if (args.Uri.Host == "www.contoso.com")
    {
        webView.AddWebAllowedObject("nativeObject", new MyClass());
    }
}

Daha fazla bilgi için bkz. WebView.AddWebAllowedObject.

Ayrıca, web görünümündeki güvenilen JavaScript içeriğinin Windows Çalışma Zamanı API'lerine doğrudan erişmesine izin verilebiliyor. Bu, web görünümünde barındırılan web uygulamaları için güçlü yerel özellikler sağlar. Bu özelliği etkinleştirmek için, güvenilen içeriğin URI'sinin Package.appxmanifest içindeki uygulamanın ApplicationContentUriRules içinde izin verilenler listesine eklenmesi ve WindowsRuntimeAccess'in özel olarak "tümü" olarak ayarlanması gerekir.

Bu örnekte uygulama bildiriminin bir bölümü gösterilmektedir. Burada, yerel bir URI'ye Windows Çalışma Zamanı erişimi verilir.

  <Applications>
    <Application Id="App"
      ...

      <uap:ApplicationContentUriRules>
        <uap:Rule Match="ms-appx-web:///Web/App.html" WindowsRuntimeAccess="all" Type="include"/>
      </uap:ApplicationContentUriRules>
    </Application>
  </Applications>

Web içeriği barındırma seçenekleri

JavaScript ve IndexedDB'nin etkinleştirilip etkinleştirilmediğini denetlemek için WebView.Settings özelliğini ( WebViewSettings türünde) kullanabilirsiniz. Örneğin, kesin olarak statik içerik görüntülemek için bir web görünümü kullanıyorsanız, en iyi performans için JavaScript'i devre dışı bırakmak isteyebilirsiniz.

Web görünümü içeriğini yakalama

Web görünümü içeriğini diğer uygulamalarla paylaşmayı etkinleştirmek için, seçili içeriği DataPackage olarak döndüren CaptureSelectedContentToDataPackageAsync yöntemini kullanın. Bu yöntem zaman uyumsuz olduğundan, zaman uyumsuz çağrı tamamlanmadan önce DataRequested olay işleyicinizin geri dönmesini önlemek için bir öteleme nesnesi kullanmanız gerekir.

Web görünümünün geçerli içeriğinin önizleme görüntüsünü almak için CapturePreviewToStreamAsync yöntemini kullanın. Bu yöntem geçerli içeriğin görüntüsünü oluşturur ve belirtilen akışa yazar.

İş parçacığı oluşturma davranışı

Varsayılan olarak, masaüstü cihaz ailesindeki cihazlarda web görünümü içeriği kullanıcı arabirimi iş parçacığında, diğer tüm cihazlarda ise kullanıcı arabirimi iş parçacığının dışında barındırılır. Geçerli istemci için varsayılan iş parçacığı davranışını sorgulamak için WebView.DefaultExecutionMode statik özelliğini kullanabilirsiniz. Gerekirse, bu davranışı geçersiz kılmak için WebView(WebViewExecutionMode) oluşturucuyu kullanabilirsiniz.

Not Mobil cihazlarda kullanıcı arabirimi iş parçacığında içerik barındırırken performans sorunları olabilir, bu nedenle DefaultExecutionMode'yi değiştirdiğinizde tüm hedef cihazlarda test ettiğinizden emin olun.

ui iş parçacığının dışında içerik barındıran bir web görünümü, web görünümü denetiminden üst öğeye hareketlerin iletilmesini gerektiren üst denetimlerle uyumlu değildir, örneğin FlipView, ScrollViewerve diğer ilgili denetimler. Bu denetimler iş parçacığı dışı web görünümünde başlatılan hareketleri alamaz. Ayrıca, iş parçacığı dışı web içeriğini yazdırma doğrudan desteklenmez; bunun yerine WebViewBrush dolgu içeren bir öğe yazdırmanız gerekir.

Örnek kodunu alma

WinUI 2 Galeri örneği - Tüm XAML denetimlerini etkileşimli biçimde görün.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-11-25