Sdílet prostřednictvím

Webové zobrazení

Ovládací prvek webového zobrazení vloží zobrazení do aplikace, která vykreslí webový obsah pomocí vykreslovacího modulu Microsoft Edge Legacy. Hypertextové odkazy se můžou také zobrazovat a fungovat v ovládacím prvku webového zobrazení.

Důležité

Ovládací WebView2 prvek je k dispozici jako součást WinUI v sadě Windows App SDK. WebView2 používá Microsoft Edge (Chromium) jako vykreslovací modul k zobrazení webového obsahu v aplikacích. Další informace naleznete v tématu Úvod do microsoft Edge WebView2, Začínáme s WebView2 ve WinUI 3 (Preview)a WebView2 v referenčních informacích k rozhraní API WinUI.

Je to správná kontrola?

Pomocí ovládacího prvku webového zobrazení můžete zobrazit bohatě formátovaný obsah HTML ze vzdáleného webového serveru, dynamicky generovaného kódu nebo souborů obsahu v balíčku aplikace. Bohatý obsah může také obsahovat kód skriptu a komunikovat mezi skriptem a kódem vaší aplikace.

Recommendations

  • Ujistěte se, že je načtený web správně naformátovaný pro zařízení a používá barvy, typografii a navigaci, které jsou konzistentní se zbytkem vaší aplikace.
  • Vstupní pole by měla mít odpovídající velikost. Uživatelé si nemusí uvědomit, že mohou přiblížit a zadat text.
  • Pokud webové zobrazení nevypadá jako zbytek aplikace, zvažte alternativní ovládací prvky nebo způsoby, jak provádět relevantní úlohy. Pokud se vaše webové zobrazení shoduje se zbytkem vaší aplikace, uživatelé uvidí vše jako jedno bezproblémové prostředí.

Vytvoření webového zobrazení

Úprava vzhledu webového zobrazení

WebView není podtřídou ovládacích prvků , takže nemá šablonu ovládacího prvku. Můžete ale nastavit různé vlastnosti pro řízení některých vizuálních aspektů webového zobrazení.

  • Chcete-li omezit oblast zobrazení, nastavte vlastnosti Šířka a Výška.
  • Chcete-li přeložit, škálovat, zkosit a otočit webové zobrazení, použijte vlastnost RenderTransform.
  • Pro nastavení průhlednosti webového zobrazení nastavte vlastnost Průhlednost.
  • Chcete-li zadat barvu, která se má použít jako pozadí webové stránky, pokud obsah HTML neurčí barvu, nastavte DefaultBackgroundColor vlastnost.

Získání názvu webové stránky

Název dokumentu HTML, který se aktuálně zobrazuje ve webovém zobrazení, můžete získat pomocí vlastnosti DocumentTitle.

Vstupní události a pořadí tabulátoru

I když WebView není podtřídou ovládacího prvku, bude přijímat zaměření vstupu z klávesnice a účastnit se tabulátorové sekvence. Poskytuje metodu Focus a události GotFocus a LostFocus, ale nemá žádné vlastnosti související s tabulátorem. Jeho pozice v sekvenci tabulátoru je stejná jako její pozice v pořadí dokumentu XAML. Sekvence karet obsahuje všechny prvky v obsahu webového zobrazení, které mohou přijímat vstupní fokus.

Jak je uvedeno v tabulce Events na stránce třídy WebView, webové zobrazení nepodporuje většinu událostí uživatelského vstupu zděděných z UIElement, jako je například KeyDown, KeyUpa PointerPressed. Místo toho můžete použít InvokeScriptAsync s funkcí JavaScript eval k použití obslužných rutin událostí HTML, a použijte window.external.notify z obslužných rutin událostí HTML pro upozornění aplikace pomocí WebView.ScriptNotify.

Přechod na obsah

Webové zobrazení poskytuje několik rozhraní API pro základní navigaci: goback, GoForward, Stop, Refresh, CanGoBacka CanGoForward. Pomocí těchto možností můžete do aplikace přidat typické možnosti procházení webu.

Chcete-li nastavit počáteční obsah webového zobrazení, nastavte vlastnost Zdroj v XAML. Analyzátor XAML automaticky převede řetězec na 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"/>

Vlastnost Source lze nastavit v kódu, ale místo toho, abyste to udělali, obvykle používáte jednu z metod Navigate k načtení obsahu v kódu.

Pokud chcete načíst webový obsah, použijte metodu Navigate s identifikátorem URI , který používá schéma http nebo https.

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

Pro přechod na URI s použitím POST požadavku a HTTP hlaviček použijte metodu NavigateWithHttpRequestMessage. Tato metoda podporuje pouze HttpMethod.Post a HttpMethod.Get pro hodnotu vlastnosti HttpRequestMessage.Method.

Chcete-li načíst nekomprimovaný a nešifrovaný obsah z úložiště dat vaší aplikace ve složce LocalFolder nebo TemporaryFolder, použijte metodu Navigate s identifikátorem URI, který používá schématem ms-appdata. Podpora webového zobrazení pro toto schéma vyžaduje, abyste obsah umístili do podsložky pod místní nebo dočasnou složku. To umožňuje navigaci k identifikátorům URI, jako jsou ms-appdata:///local/ složka/soubor.html a ms-appdata:///temp/ složka/soubor.html . (Pro načtení komprimovaných nebo šifrovaných souborů viz NavigateToLocalStreamUri.)

Každá z těchto podsložek první úrovně je izolovaná od obsahu v jiných podsložkách první úrovně. Můžete například přejít na ms-appdata:///temp/folder1/file.html, ale v tomto souboru nemůžete mít odkaz na ms-appdata:///temp/folder2/file.html. Pomocí schématu ms-appx-web můžete ale stále odkazovat na obsah HTML v balíčku aplikace a pomocí schémat URI http a https na webový obsah.

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

Pokud chcete načíst obsah z balíčku aplikace, použijte metodu Navigate s identifikátorem Uri, který používá schéma ms-appx-web.

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

Místní obsah můžete načíst pomocí vlastního řešitele pomocí metody NavigateToLocalStreamUri. To umožňuje pokročilé scénáře, jako je stahování a ukládání webového obsahu do mezipaměti pro použití offline nebo extrahování obsahu z komprimovaného souboru.

Reakce na události navigace

Ovládací prvek webového zobrazení poskytuje několik událostí, které můžete použít k reakci na stavy navigace a načítání obsahu. Události se vyskytují v následujícím pořadí pro obsah kořenového webového zobrazení: NavigationStarting, ContentLoading, DOMContentLoaded, NavigationCompleted

NavigationStarting – nastane před přechodem webového zobrazení na nový obsah. Navigaci v obslužné rutině pro tuto událost můžete zrušit nastavením Vlastnosti WebViewNavigationStartingEventArgs.Cancel na hodnotu 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 – nastane, když webové zobrazení začalo načítat nový obsah.

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 – nastane, když webové zobrazení dokončilo analýzu aktuálního obsahu 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 – nastane, když webové zobrazení dokončilo načítání aktuálního obsahu nebo pokud se navigace nezdařila. Pokud chcete zjistit, jestli se navigace nezdařila, zkontrolujte vlastnosti IsSuccess a WebErrorStatus třídy 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();
    }
}

Podobné události se vyskytují ve stejném pořadí pro každý prvek iframe v obsahu webového zobrazení:

Reakce na potenciální problémy

Můžete reagovat na potenciální problémy s obsahem, jako jsou dlouhotrvající skripty, obsah, který webové zobrazení nemůže načíst, a upozornění na nebezpečný obsah.

Aplikace může během spouštění skriptů přestat reagovat. Událost LongRunningScriptDetected probíhá pravidelně, zatímco webové zobrazení spouští JavaScript a poskytuje příležitost přerušit skript. Chcete-li zjistit, jak dlouho byl skript spuštěn, zkontrolujte ExecutionTime vlastnost WebViewLongRunningScriptDetectedEventArgs. Chcete-li zastavit skript, nastavte vlastnost argumentů události StopPageScriptExecution na pravda. Zastavený skript se znovu nespustí, pokud se znovu nenačte při dalším prohlížení webového prohlížeče.

Ovládací prvek webového zobrazení nemůže hostovat libovolné typy souborů. Při pokusu o načtení obsahu, který webové zobrazení nemůže hostovat, dojde k události UnviewableContentIdentified. Tuto událost můžete zpracovat a upozornit uživatele nebo pomocí třídy Launcher přesměrovat soubor do externího prohlížeče nebo jiné aplikace.

Podobně událost UnsupportedUriSchemeIdentified nastane, když se ve webovém obsahu vyvolá schéma identifikátoru URI, které není podporováno, například fbconnect:// nebo mailto://. Tuto událost můžete zpracovat tak, aby poskytovala vlastní chování místo toho, aby výchozí spouštěcí modul systému spustil identifikátor URI.

K události UnsafeContentWarningDisplayingevent dojde, když zobrazení webového prohlížeče ukáže varovnou stránku pro obsah, který byl filtrem SmartScreen nahlášen jako nebezpečný. Pokud se uživatel rozhodne pokračovat v navigaci, následná navigace na stránku nezobrazí upozornění ani aktivuje událost.

Zpracování speciálních případů pro obsah webového zobrazení

Pomocí vlastnosti ContainsFullScreenElement a události ContainsFullScreenElementChanged můžete zjistit, reagovat na, a povolit zážitky na celé obrazovce v rámci webového obsahu, například přehrávání videa na celé obrazovce. Můžete například použít událost ContainsFullScreenElementChanged ke změně velikosti webového zobrazení tak, aby zabírala celé zobrazení aplikace, nebo, jak je znázorněno v následujícím příkladu, umístěte aplikaci s oknem do režimu zobrazení na celou obrazovku, když je potřeba webové prostředí na celé obrazovce.

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

Událost NewWindowRequested můžete použít ke zpracování případů, kdy hostovaný webový obsah požaduje, aby se zobrazilo nové okno, například automaticky otevírané okno. K zobrazení obsahu požadovaného okna můžete použít jiný ovládací prvek WebView.

Pomocí události PermissionRequested povolte webové funkce, které vyžadují speciální možnosti. Patří mezi ně geografická poloha, úložiště IndexedDB a zvuk a video uživatele (například z mikrofonu nebo webové kamery). Pokud vaše aplikace přistupuje k umístění uživatele nebo k mediálnímu obsahu uživatele, musíte tuto funkci deklarovat v manifestu aplikace. Například aplikace, která používá geografickou polohu, potřebuje minimálně následující deklarace schopností v Package.appxmanifest:

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

Kromě aplikace, která zpracovává událost PermissionRequested, bude muset uživatel schválit standardní systémové dialogy pro aplikace, které požadují umístění nebo možnosti médií, aby tyto funkce byly povolené.

Zde je příklad toho, jak by aplikace umožnila geolokaci na mapě z Bingu:

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

Pokud vaše aplikace vyžaduje zadání uživatele nebo jiné asynchronní operace, aby reagovala na žádost o oprávnění, použijte metodu DeferWebViewPermissionRequest k vytvoření WebViewDeferredPermissionRequest, na které lze reagovat později. Viz WebViewPermissionRequest.Defer.

Pokud se uživatelé musí bezpečně odhlásit z webu hostovaného ve webovém zobrazení nebo v jiných případech, pokud je zabezpečení důležité, zavolejte statickou metodu ClearTemporaryWebDataAsync vymazat veškerý místně uložený obsah v mezipaměti z relace webového zobrazení. Zabráníte tak uživatelům se zlými úmysly v přístupu k citlivým datům.

Interakce s obsahem webového zobrazení

S obsahem webového zobrazení můžete pracovat pomocí metody InvokeScriptAsync k vyvolání nebo vložení skriptu do obsahu webového zobrazení a události ScriptNotify získat informace zpět z obsahu webového zobrazení.

K vyvolání JavaScriptu uvnitř obsahu webového zobrazení použijte metodu InvokeScriptAsync. Vyvolaný skript může vracet pouze řetězcové hodnoty.

Pokud například obsah webového zobrazení s názvem webView1 obsahuje funkci s názvem setDate, která přijímá 3 parametry, můžete ji vyvolat takto.

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

K vložení obsahu do webové stránky můžete použít funkci eval jazyka JavaScript s InvokeScriptAsync.

Zde se text textového pole XAML (nameTextBox.Text) zapíše na div na stránce HTML hostované v 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 });
}

Skripty v obsahu webového zobrazení můžou použít window.external.notify s řetězcovým parametrem k odeslání informací zpět do vaší aplikace. Chcete-li přijímat tyto zprávy, zpracujte událost ScriptNotify.

Pokud chcete externí webové stránce povolit aktivaci události ScriptNotify při volání window.external.notify, je nutné zahrnout identifikátor URI stránky do ApplicationContentUriRules části manifestu aplikace. (To můžete udělat v sadě Microsoft Visual Studio na kartě Identifikátory URI obsahu návrháře souboru Package.appxmanifest.) Identifikátory URI v tomto seznamu musí používat protokol HTTPS a mohou obsahovat zástupné znaky subdomény (například https://*.microsoft.com), ale nesmí obsahovat zástupné znaky domény (například https://*.com a https://*.*). Požadavek manifestu se nevztahuje na obsah, který pochází z balíčku aplikace, používá URI ve formátu ms-local-stream:// nebo je načten pomocí NavigateToString.

Přístup k prostředí Windows Runtime ve webovém zobrazení

Metodu AddWebAllowedObject můžete použít k vložení instance nativní třídy z komponenty prostředí Windows Runtime do kontextu JavaScriptu webového zobrazení. To umožňuje úplný přístup k nativním metodám, vlastnostem a událostem tohoto objektu v javascriptovém obsahu tohoto webového zobrazení. Třída musí být označena atributem AllowForWeb.

Tento kód například vloží instanci MyClass importované z komponenty prostředí Windows Runtime do webového zobrazení.

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

Další informace naleznete v tématu WebView.AddWebAllowedObject.

Kromě toho může důvěryhodný javascriptový obsah ve webovém zobrazení povolit přímý přístup k rozhraním API prostředí Windows Runtime. To poskytuje výkonné nativní funkce pro webové aplikace hostované ve webovém zobrazení. Chcete-li tuto funkci povolit, musí být identifikátor URI důvěryhodného obsahu přidán na seznam povolených v části ApplicationContentUriRules aplikace v souboru Package.appxmanifest, s WindowsRuntimeAccess konkrétně nastaveným na "all".

Tento příklad ukazuje část manifestu aplikace. V této části je místnímu identifikátoru URI udělen přístup k prostředí Windows Runtime.

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

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

Možnosti hostování webového obsahu

Pomocí vlastnosti WebView.Settings (typu WebViewSettings) můžete určit, zda jsou povoleny JavaScript a IndexedDB. Pokud například používáte webové zobrazení k zobrazení výhradně statického obsahu, můžete zakázat JavaScript pro zajištění nejlepšího výkonu.

Zachycení obsahu webového zobrazení

Pokud chcete povolit sdílení obsahu webového zobrazení s jinými aplikacemi, použijte metodu CaptureSelectedContentToDataPackageAsync, která vrátí vybraný obsah jako DataPackage . Tato metoda je asynchronní, takže musíte použít odložení operace, abyste zabránili tomu, aby se obslužná rutina události DataRequested nevrátila dříve, než bude asynchronní volání dokončeno.

Pokud chcete získat náhled obrázku aktuálního obsahu webového zobrazení, použijte metodu CapturePreviewToStreamAsync. Tato metoda vytvoří obrázek aktuálního obsahu a zapíše ho do zadaného datového proudu.

Chování vláken

Ve výchozím nastavení je obsah webového zobrazení hostovaný ve vlákně uživatelského rozhraní na zařízeních v rodině stolních zařízení, a mimo vlákno uživatelského rozhraní na všech ostatních zařízeních. Můžete použít statickou vlastnost WebView.DefaultExecutionMode k dotazování na výchozí chování vláken aktuálního klienta. V případě potřeby můžete k přepsání tohoto chování použít konstruktor WebView(WebViewExecutionMode).

Poznámka Při hostování obsahu ve vlákně uživatelského rozhraní na mobilních zařízeních může dojít k problémům s výkonem, proto při změně defaultExecutionMode nezapomeňte testovat na všech cílových zařízeních.

Webové zobrazení, které hostuje obsah mimo vlákno uživatelského rozhraní, není kompatibilní s nadřazenými ovládacími prvky, které vyžadují gesta k šíření z ovládacího prvku webového zobrazení do nadřazeného objektu, například FlipView, ScrollViewera dalších souvisejících ovládacích prvků. Tyto ovládací prvky nebudou moci přijímat gesta iniciovaná ve webovém zobrazení mimo vlákno. Kromě toho není podpora pro tisk webového obsahu mimo hlavní vlákno – místo toho byste měli vytisknout prvek s výplní pomocí WebViewBrush.

Získání ukázkového kódu

  • Last updated on