Udostępnij za pomocą

Widok sieci Web

Kontrolka widoku sieciowego osadza widok w twojej aplikacji, który renderuje zawartość internetową przy użyciu silnika renderowania Microsoft Edge Legacy. Hiperłącza mogą również być wyświetlane i działać w kontrolce widoku internetowego.

Ważne

Kontrolka WebView2 jest dostępna jako część interfejsu WinUI w zestawie SDK aplikacji systemu Windows. WebView2 używa przeglądarki Microsoft Edge (Chromium) jako aparatu renderowania do wyświetlania zawartości internetowej w aplikacjach. Więcej informacji znajdziesz w Wprowadzenie do programu Microsoft Edge WebView2, Pierwsze kroki z WebView2 w WinUI 3 (wersja zapoznawcza) i WebView2 w dokumentacji interfejsu API WinUI.

Czy jest to właściwa kontrola?

Za pomocą kontrolki widoku internetowego można wyświetlać sformatowaną zawartość HTML ze zdalnego serwera internetowego, dynamicznie generowanego kodu lub plików zawartości w pakiecie aplikacji. Zawartość bogata może również zawierać kod skryptu i komunikować się między skryptem a kodem aplikacji.

Rekomendacje

  • Upewnij się, że załadowana witryna internetowa jest poprawnie sformatowana dla urządzenia i używa kolorów, typografii i nawigacji, które są zgodne z resztą aplikacji.
  • Pola wejściowe powinny mieć odpowiedni rozmiar. Użytkownicy mogą nie zdawać sobie sprawy, że mogą powiększyć tekst.
  • Jeśli widok internetowy nie wygląda jak reszta aplikacji, rozważ alternatywne mechanizmy kontroli lub sposoby wykonywania odpowiednich zadań. Jeśli widok internetowy jest zgodny z resztą aplikacji, użytkownicy zobaczą to wszystko jako jedno bezproblemowe środowisko.

Tworzenie widoku internetowego

Modyfikowanie wyglądu widoku internetowego

Element WebView nie jest podklasą Kontrolka , więc nie ma szablonu kontrolki. Można jednak ustawić różne właściwości, aby kontrolować niektóre aspekty wizualne widoku internetowego.

  • Aby ograniczyć obszar wyświetlania, ustaw właściwości Width i Height .
  • Aby przetłumaczyć, skalować, pochylać i obracać widok sieciowy, użyj właściwości RenderTransform.
  • Aby kontrolować przezroczystość widoku internetowego, ustaw właściwość przezroczystości.
  • Aby określić kolor, który ma być używany jako tło strony internetowej, gdy zawartość HTML nie określa koloru, ustaw właściwość DefaultBackgroundColor .

Uzyskaj tytuł strony internetowej

Tytuł dokumentu HTML wyświetlany obecnie w widoku internetowym można uzyskać przy użyciu właściwości DocumentTitle .

Zdarzenia wejściowe i kolejność tabulacji

Mimo że element WebView nie jest podklasą Control, otrzyma fokus wejścia z klawiatury i weźmie udział w sekwencji tabulacji. Dostarcza metodę Focus oraz zdarzenia GotFocus i LostFocus, ale nie posiada właściwości związanych z tabulatorem. Jego pozycja w sekwencji tabulacji jest taka sama jak pozycja w kolejności dokumentu XAML. Sekwencja kart zawiera wszystkie elementy w zawartości widoku internetowego, które mogą odbierać fokus danych wejściowych.

Jak wskazano w tabeli Zdarzenia na stronie klasy WebView, WebView nie obsługuje większości zdarzeń wejściowych użytkownika dziedziczonych z elementu UIElement, takich jak KeyDown, KeyUpi PointerPressed. Zamiast tego można użyć InvokeScriptAsync wraz z funkcją eval z języka JavaScript, aby wykorzystywać procedury obsługi zdarzeń HTML, oraz zastosować window.external.notify z poziomu programu obsługi zdarzeń HTML do powiadamiania aplikacji przy użyciu WebView.ScriptNotify.

Przechodzenie do zawartości

Przeglądarka udostępnia kilka interfejsów API do nawigacji podstawowej: GoBack, GoForward, Stop, Refresh, CanGoBacki CanGoForward. Można ich użyć do dodawania typowych funkcji przeglądania internetowego do aplikacji.

Aby ustawić początkową zawartość widoku sieciowego, ustaw właściwość Source w języku XAML. Analizator XAML automatycznie konwertuje ciąg na identyfikator Uri .

<!-- 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"/>

Właściwość Source można ustawić w kodzie, ale zamiast tego używać jednej z metod Navigate do ładowania zawartości w kodzie.

Aby załadować zawartość internetową, użyj metody Navigate z identyfikatorem Uri, który korzysta ze schematu http lub https.

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

Aby przejść do identyfikatora URI z żądaniem POST i nagłówkami HTTP, użyj metody NavigateWithHttpRequestMessage. Ta metoda obsługuje tylko HttpMethod.Post i HttpMethod.Get dla wartości właściwości HttpRequestMessage.Method .

Aby załadować nieskompresowaną i niezaszyfrowaną zawartość z LocalFolder lub TemporaryFolder magazynów danych, użyj metody Navigate z Uri używającym schematu ms-appdata. Aby zapewnić obsługę widoku internetowego dla tego schematu, należy umieścić zawartość w podfolderze w folderze lokalnym lub tymczasowym. Dzięki temu można nawigować po identyfikatorach URI, takich jak ms-appdata:///local/ folder/plik.html i ms-appdata:///temp/ folder/.html . (Aby załadować skompresowane lub zaszyfrowane pliki, zobacz NavigateToLocalStreamUri).

Każdy z tych podfolderów pierwszego poziomu jest odizolowany od zawartości w innych podfolderach pierwszego poziomu. Na przykład możesz przejść do folderu ms-appdata:///temp/folder1/file.html, ale nie możesz mieć linku do pliku ms-appdata:///temp/folder2/file.html. Można jednak nadal łączyć się z zawartością HTML w pakiecie aplikacji przy użyciu schematu ms-appx-weboraz z zawartością internetową przy użyciu schematów http i https URI.

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

Aby załadować zawartość z pakietu aplikacji, użyj metody Navigate z identyfikatorem URI korzystającym ze schematu ms-appx-web.

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

Zawartość lokalną można załadować za pomocą niestandardowego resolvera przy użyciu metody NavigateToLocalStreamUri. Umożliwia to korzystanie z zaawansowanych scenariuszy, takich jak pobieranie i buforowanie zawartości internetowej do użycia w trybie offline lub wyodrębnianie zawartości ze skompresowanego pliku.

Reagowanie na zdarzenia nawigacji

Kontrolka widoku internetowego udostępnia kilka zdarzeń, których można użyć do reagowania na stany nawigacji i ładowania zawartości. Zdarzenia występują w następującej kolejności dla głównej zawartości widoku sieci Web: NavigationStarting, ContentLoading, DOMContentLoaded, NavigationCompleted

NavigationStarting — występuje przed przejściem widoku internetowego do nowej zawartości. Możesz anulować nawigację w programie obsługi dla tego zdarzenia, ustawiając właściwość WebViewNavigationStartingEventArgs.Cancel na true.

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 — występuje, gdy widok internetowy rozpoczął ładowanie nowej zawartości.

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 — występuje, gdy widok internetowy zakończył analizowanie bieżącej zawartości HTML.

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 — występuje, gdy widok internetowy zakończył ładowanie bieżącej zawartości lub jeśli nawigacja nie powiodła się. Aby ustalić, czy nawigacja nie powiodła się, sprawdź właściwości IsSuccess i WebErrorStatus klasy WebViewNavigationCompletedEventArgs.

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();
    }
}

Podobne zdarzenia występują w tej samej kolejności dla każdego elementu iframe w zawartości widoku internetowego:

  • FrameNavigationStarting — występuje przed przejściem ramki w widoku internetowym do nowej zawartości.
  • FrameContentLoading — występuje, gdy ramka w widoku internetowym zaczęła ładować nową zawartość.
  • FrameDOMContentLoaded — występuje, gdy ramka w widoku internetowym zakończyła analizowanie bieżącej zawartości HTML.
  • FrameNavigationCompleted — występuje po zakończeniu ładowania zawartości przez ramkę w widoku internetowym.

Reagowanie na potencjalne problemy

Możesz odpowiedzieć na potencjalne problemy z zawartością, takie jak długotrwałe skrypty, zawartość, której nie można załadować w widoku internetowym, oraz ostrzeżenia o niebezpiecznej zawartości.

Aplikacja może nie odpowiadać, gdy skrypty są uruchomione. Zdarzenie LongRunningScriptDetected występuje okresowo, gdy widok internetowy wykonuje kod JavaScript i umożliwia przerwanie działania skryptu. Aby określić, jak długo skrypt jest uruchomiony, sprawdź właściwość ExecutionTime z WebViewLongRunningScriptDetectedEventArgs. Aby zatrzymać skrypt, ustaw właściwość args StopPageScriptExecution na true. Zatrzymany skrypt nie zostanie wykonany ponownie, chyba że zostanie ponownie załadowany podczas kolejnej nawigacji w widoku internetowym.

Kontrolka widoku sieci Web nie może hostować dowolnych typów plików. Gdy zostanie podjęta próba załadowania zawartości, która nie może hostować widoku internetowego, wystąpi zdarzenie UnviewableContentIdentified . To zdarzenie można obsługiwać i powiadomić użytkownika albo użyć klasy Launcher, aby przekierować plik do zewnętrznej przeglądarki lub innej aplikacji.

Podobnie zdarzenie UnsupportedUriSchemeIdentified występuje, gdy schemat identyfikatora URI, który nie jest obsługiwany, jest wywoływany w zawartości internetowej, na przykład fbconnect:// lub mailto://. Zdarzenie to można obsłużyć, aby zapewnić zachowanie niestandardowe, zamiast pozwalać domyślnemu programowi uruchamiającemu systemu na uruchamianie identyfikatora URI.

UnsafeContentWarningDisplayingevent występuje, gdy w widoku przeglądarki zostanie wyświetlona strona ostrzegawcza dotycząca zawartości, która została zgłoszona jako niebezpieczna przez filtr SmartScreen. Jeśli użytkownik zdecyduje się kontynuować nawigację, kolejne przejście do strony nie spowoduje wyświetlenia ostrzeżenia ani wyzwolenia zdarzenia.

Obsługa przypadków specjalnych dla zawartości widoku internetowego

Możesz użyć właściwości ContainsFullScreenElement i zdarzenia ContainsFullScreenElementChanged, aby wykrywać, reagować i włączać pełnoekranowe doświadczenia w treści internetowej, takie jak pełnoekranowe odtwarzanie wideo. Na przykład możesz użyć zdarzenia ContainsFullScreenElementChanged, aby zmienić rozmiar widoku internetowego tak, aby zajmował cały widok aplikacji lub, jak pokazano w poniższym przykładzie, umieść aplikację w trybie pełnoekranowym, gdy wymagane jest pełne środowisko internetowe.

// 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();
    }
}

Możesz użyć zdarzenia NewWindowRequested do zarządzania sytuacjami, gdy hostowana zawartość internetowa żąda nowego okna do wyświetlenia, na przykład okienka podręcznego. Możesz użyć innej kontrolki WebView, aby wyświetlić zawartość żądanego okna.

Użyj zdarzenia PermissionRequested, aby włączyć funkcje internetowe wymagające specjalnych możliwości. Obecnie obejmuje to geolokalizację, przechowywanie IndexedDB oraz dźwięk i wideo użytkownika (na przykład z mikrofonu lub kamery internetowej). Jeśli aplikacja uzyskuje dostęp do lokalizacji użytkownika lub nośnika użytkownika, nadal musisz zadeklarować tę funkcję w manifeście aplikacji. Na przykład aplikacja korzystająca z geolokalizacji wymaga co najmniej następujących deklaracji możliwości w pliku Package.appxmanifest:

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

Oprócz aplikacji obsługującej zdarzenie PermissionRequested użytkownik będzie musiał zatwierdzić standardowe okna dialogowe systemu dla aplikacji żądających lokalizacji lub funkcji multimedialnych w celu włączenia tych funkcji.

Oto przykład sposobu włączania geolokalizacji na mapie z usługi Bing przez aplikację:

// 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();
    }
}

Jeśli aplikacja wymaga danych wejściowych użytkownika lub innych operacji asynchronicznych, aby odpowiedzieć na żądanie uprawnień, użyj metody Odrocz w WebViewPermissionRequest do utworzenia WebViewDeferredPermissionRequest, które można wykorzystać później. Zobacz WebViewPermissionRequest.Defer.

Jeśli użytkownicy muszą bezpiecznie wylogować się z witryny internetowej hostowanej w widoku internetowym lub w innych przypadkach, gdy bezpieczeństwo jest ważne, wywołaj metodę statyczną ClearTemporaryWebDataAsync , aby wyczyścić całą lokalnie buforowane zawartość z sesji widoku internetowego. Zapobiega to uzyskiwaniu dostępu do poufnych danych przez złośliwych użytkowników.

Interakcja z zawartością widoku internetowego

Możesz wchodzić w interakcje z zawartością widoku internetowego przy użyciu metody InvokeScriptAsync w celu wywołania lub wstrzyknięcia skryptu do zawartości widoku internetowego oraz zdarzenia ScriptNotify , aby uzyskać informacje z zawartości widoku internetowego.

Aby wywołać kod JavaScript wewnątrz zawartości widoku internetowego, użyj metody InvokeScriptAsync . Wywołany skrypt może zwracać tylko wartości ciągu.

Na przykład, jeśli zawartość widoku internetowego o nazwie webView1 zawiera funkcję o nazwie setDate, która przyjmuje 3 parametry, możesz ją wywołać w ten sposób.

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

Możesz użyć InvokeScriptAsync z funkcją eval języka JavaScript, aby umieścić zawartość na stronie internetowej.

Tutaj tekst pola tekstowego XAML (nameTextBox.Text) jest zapisywany w elemencie div na stronie HTML hostowanej w webView1.

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 });
}

Skrypty w zawartości widoku internetowego mogą używać window.external.notify jako argumentu tekstowego, aby przesłać informacje z powrotem do aplikacji. Aby odbierać te komunikaty, obsłuż zdarzenie ScriptNotify.

Aby umożliwić zewnętrznej stronie internetowej uruchamianie zdarzenia ScriptNotify podczas wywoływania window.external.notify, należy dołączyć identyfikator URI strony w sekcji ApplicationContentUriRules manifestu aplikacji. (Możesz to zrobić w programie Microsoft Visual Studio na karcie Identyfikatory URI zawartości w projektancie Package.appxmanifest). Identyfikatory URI na tej liście muszą używać protokołu HTTPS i mogą zawierać symbole wieloznaczne poddomeny (na przykład https://*.microsoft.com), ale nie mogą zawierać symboli wieloznacznych domeny (na przykład https://*.com i https://*.*). Wymaganie manifestu nie dotyczy zawartości pochodzącej z pakietu aplikacji, która używa identyfikatora URI ms-local-stream:// lub jest ładowana przy użyciu NavigateToString.

Uzyskiwanie dostępu do środowiska uruchomieniowego systemu Windows w widoku internetowym

Możesz użyć metody AddWebAllowedObject , aby wstrzyknąć wystąpienie klasy natywnej ze składnika Środowiska uruchomieniowego systemu Windows do kontekstu JavaScript widoku internetowego. Umożliwia to pełny dostęp do natywnych metod, właściwości i zdarzeń tego obiektu w zawartości języka JavaScript tego widoku internetowego. Klasa musi być oznaczona atrybutem AllowForWeb.

Na przykład ten kod wprowadza wystąpienie MyClass zaimportowane ze składnika Środowiska uruchomieniowego systemu Windows do widoku internetowego.

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

Aby uzyskać więcej informacji, zobacz WebView.AddWebAllowedObject.

Ponadto zaufana zawartość języka JavaScript w widoku internetowym może mieć bezpośredni dostęp do interfejsów API środowiska uruchomieniowego systemu Windows. Zapewnia to zaawansowane możliwości natywne dla aplikacji internetowych hostowanych w widoku internetowym. Aby włączyć tę funkcję, identyfikator URI zaufanej zawartości musi być umieszczony na białej liście w ApplicationContentUriRules aplikacji w pliku Package.appxmanifest, przy czym WindowsRuntimeAccess musi być specjalnie ustawiony na wartość "all".

W tym przykładzie przedstawiono sekcję manifestu aplikacji. W tym miejscu lokalny identyfikator URI uzyskuje dostęp do środowiska uruchomieniowego systemu Windows.

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

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

Opcje hostingu zawartości internetowej

Możesz użyć właściwości WebView.Settings (typu WebViewSettings), aby kontrolować, czy są włączone języki JavaScript i IndexedDB. Jeśli na przykład używasz widoku internetowego do wyświetlania ściśle statycznej zawartości, możesz wyłączyć język JavaScript w celu uzyskania najlepszej wydajności.

Przechwytywanie zawartości widoku internetowego

Aby włączyć udostępnianie zawartości widoku internetowego innym aplikacjom, użyj metody CaptureSelectedContentToDataPackageAsync , która zwraca wybraną zawartość jako element DataPackage. Ta metoda jest asynchroniczna, więc należy użyć odroczenia, aby zapobiec przedwczesnemu zakończeniu procedury obsługi zdarzenia DataRequested przed ukończeniem wywołania asynchronicznego.

Aby uzyskać obraz podglądu bieżącej zawartości widoku internetowego, użyj metody CapturePreviewToStreamAsync. Ta metoda tworzy obraz bieżącej zawartości i zapisuje go w określonym strumieniu.

Zachowanie wątkowe

Domyślnie zawartość widoku internetowego jest hostowana w wątku interfejsu użytkownika na urządzeniach w rodzinie urządzeń stacjonarnych i poza wątkiem interfejsu użytkownika na wszystkich innych urządzeniach. Możesz użyć właściwości statycznej WebView.DefaultExecutionMode , aby wykonać zapytanie dotyczące domyślnego zachowania wątkowego bieżącego klienta. W razie potrzeby możesz użyć konstruktora WebView(WebViewExecutionMode), aby zastąpić to zachowanie.

Uwaga Podczas hostowania zawartości w wątku UI na urządzeniach mobilnych mogą wystąpić problemy z wydajnością, dlatego podczas zmiany DefaultExecutionMode pamiętaj o przetestowaniu na wszystkich urządzeniach docelowych.

Widok internetowy hostujący zawartość poza wątkiem interfejsu użytkownika nie jest zgodny z kontrolkami nadrzędnymi, które wymagają propagowania gestów z kontrolki widoku internetowego do elementu nadrzędnego, takiego jak FlipView, ScrollVieweri inne powiązane kontrolki. Te kontrolki nie będą mogły odbierać gestów inicjowanych w widoku internetowym poza wątkiem. Ponadto drukowanie zawartości sieci Web poza wątkiem nie jest bezpośrednio obsługiwane — zamiast tego należy wydrukować element z Wypełnienie WebViewBrush.

Pobieranie przykładowego kodu

  • Last updated on