Delen via

Webweergave

Met een webview-besturingselement wordt een weergave in uw app opgenomen waarmee webinhoud wordt weergegeven met behulp van de verouderde rendering-engine van Microsoft Edge. Hyperlinks kunnen ook verschijnen en functioneren in een webweergave-element.

Belangrijk

Het WebView2 besturingselement is beschikbaar als onderdeel van WinUI in de Windows App SDK. WebView2 gebruikt Microsoft Edge (Chromium) als rendering-engine om webinhoud in apps weer te geven. Zie Inleiding tot Microsoft Edge WebView2, Aan de slag met WebView2 in WinUI 3 (preview) en WebView2 in de WinUI API-naslaginformatie voor meer informatie.

Is dit de juiste controle?

Gebruik een besturingselement voor webweergave om rijk opgemaakte HTML-inhoud weer te geven vanaf een externe webserver, dynamisch gegenereerde code of inhoudsbestanden in uw app-pakket. Uitgebreide inhoud kan ook scriptcode bevatten en communiceren tussen het script en de code van uw app.

Aanbevelingen

  • Zorg ervoor dat de geladen website correct is opgemaakt voor het apparaat en dat kleuren, typografie en navigatie worden gebruikt die consistent zijn met de rest van uw app.
  • Invoervelden moeten de juiste grootte hebben. Gebruikers beseffen mogelijk niet dat ze kunnen inzoomen om tekst in te voeren.
  • Als een webweergave er niet uitziet als de rest van uw app, kunt u alternatieve besturingselementen of manieren overwegen om relevante taken uit te voeren. Als uw webweergave overeenkomt met de rest van uw app, zien gebruikers het allemaal als één naadloze ervaring.

Een webweergave maken

Het uiterlijk van een webweergave wijzigen

WebView- is geen subklasse van Control, dus heeft het geen besturingselementsjabloon. U kunt echter verschillende eigenschappen instellen om bepaalde visuele aspecten van de webweergave te beheren.

  • Als u het weergavegebied wilt beperken, stelt u de eigenschappen Breedte en Hoogte in.
  • Als u een webweergave wilt vertalen, schalen, scheeftrekken en draaien, gebruikt u de eigenschap RenderTransform .
  • Als u de transparantie van de webweergave wilt beheren, stelt u de eigenschap transparantie in.
  • Als u een kleur wilt opgeven die moet worden gebruikt als de achtergrond van de webpagina wanneer de HTML-inhoud geen kleur opgeeft, stelt u de eigenschap DefaultBackgroundColor in.

Verkrijg de titel van de webpagina

U kunt de titel van het HTML-document ophalen dat momenteel in de webweergave wordt weergegeven met behulp van de eigenschap DocumentTitle .

Invoerevenementen en tabvolgorde

Hoewel WebView geen Control-subklasse is, krijgt deze focus op toetsenbordinvoer en neemt deel aan de tabvolgorde. Het biedt een focusmethode en GotFocus- en LostFocus-gebeurtenissen, maar heeft geen tabgerelateerde eigenschappen. De positie in de tabvolgorde is hetzelfde als de positie in de XAML-documentvolgorde. De tabreeks bevat alle elementen in de webweergave-inhoud die de invoerfocus kunnen ontvangen.

Zoals aangegeven in de tabel Gebeurtenissen op de webweergaveklassepagina , biedt de webweergave geen ondersteuning voor de meeste gebruikersinvoergebeurtenissen die zijn overgenomen van UIElement, zoals KeyDown, KeyUp en PointerPressed. In plaats daarvan kunt u InvokeScriptAsync gebruiken met de JavaScript-functie eval om de HTML-gebeurtenishandlers te gebruiken en om window.external.notify van de HTML-gebeurtenishandler te gebruiken om de applicatie te informeren met behulp van WebView.ScriptNotify.

Navigeren naar inhoud

Webweergave biedt verschillende API's voor basisnavigatie: GoBack, GoForward, Stop, Refresh, CanGoBack en CanGoForward. U kunt deze gebruiken om typische surfmogelijkheden toe te voegen aan uw app.

Als u de eerste inhoud van de webweergave wilt instellen, stelt u de eigenschap Bron in XAML in. De XAML-parser converteert de tekenreeks automatisch naar een 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"/>

De broneigenschap kan worden ingesteld in code, maar in plaats van dit te doen, gebruikt u meestal een van de navigate-methoden om inhoud in code te laden.

Als u webinhoud wilt laden, gebruikt u de methode Navigate met een URI die gebruikmaakt van het http- of https-schema.

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

Gebruik de methode NavigateWithHttpRequestMessage om naar een URI met een POST-aanvraag en HTTP-headers te navigeren. Deze methode ondersteunt alleen HttpMethod.Post en HttpMethod.Get voor de eigenschap HttpRequestMessage.Method .

Als u niet-gecomprimeerde en niet-versleutelde inhoud wilt laden uit de LocalFolder - of TemporaryFolder-gegevensarchieven van uw app, gebruikt u de methode Navigate met een URI die gebruikmaakt van het ms-appdata-schema. Voor de webweergaveondersteuning voor dit schema moet u uw inhoud in een submap onder de lokale of tijdelijke map plaatsen. Hierdoor kunt u navigeren naar URI's zoals ms-appdata:///local/folder/file.html en ms-appdata:///temp/folder/file.html. (Als u gecomprimeerde of versleutelde bestanden wilt laden, raadpleegt u NavigateToLocalStreamUri.)

Elk van deze submappen op het eerste niveau is geïsoleerd van de inhoud in andere submappen op het eerste niveau. U kunt bijvoorbeeld naar ms-appdata:///temp/folder1/file.htmlnavigeren, maar u kunt geen koppeling in dit bestand hebben naar ms-appdata:///temp/folder2/file.html. U kunt echter nog steeds een koppeling maken naar HTML-inhoud in het app-pakket met behulp van het ms-appx-webschema en naar webinhoud met behulp van de http- en https-URI-schema's.

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

Als u inhoud uit het app-pakket wilt laden, gebruikt u de methode Navigate met een URI die gebruikmaakt van het ms-appx-webschema.

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

U kunt lokale inhoud laden via een aangepaste resolver met behulp van de methode NavigateToLocalStreamUri . Dit maakt geavanceerde scenario's mogelijk, zoals het downloaden en opslaan van webinhoud in de cache voor offlinegebruik of het extraheren van inhoud uit een gecomprimeerd bestand.

Reageren op navigatie-gebeurtenissen

Het besturingselement voor de webweergave biedt verschillende gebeurtenissen die u kunt gebruiken om te reageren op de status van navigatie en het laden van inhoud. De gebeurtenissen vinden plaats in de volgende volgorde voor de hoofdwebweergave-inhoud: NavigationStarting, ContentLoading, DOMContentLoaded, NavigationCompleted

Navigatiestart: vindt plaats voordat de webweergave naar nieuwe inhoud navigeert. U kunt navigatie in een handler voor deze gebeurtenis annuleren door de eigenschap WebViewNavigationStartingEventArgs.Cancel in te stellen op 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 : treedt op wanneer de webweergave nieuwe inhoud heeft geladen.

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 : vindt plaats wanneer de webweergave klaar is met het parseren van de huidige HTML-inhoud.

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 : treedt op wanneer de webweergave klaar is met het laden van de huidige inhoud of als de navigatie is mislukt. Als u wilt bepalen of navigatie is mislukt, controleert u de eigenschappen IsSuccess en WebErrorStatus van de klasse 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();
    }
}

Soortgelijke gebeurtenissen vinden plaats in dezelfde volgorde voor elk iframe in de inhoud van de webweergave:

  • FrameNavigationStarting : vindt plaats voordat een frame in de webweergave naar nieuwe inhoud navigeert.
  • FrameContentLoading : treedt op wanneer een frame in de webweergave is begonnen met het laden van nieuwe inhoud.
  • FrameDOMContentLoaded : treedt op wanneer een frame in de webweergave klaar is met het parseren van de huidige HTML-inhoud.
  • FrameNavigationCompleted - treedt op wanneer een frame in de webweergave klaar is met het laden van de inhoud.

Reageren op potentiële problemen

U kunt reageren op mogelijke problemen met de inhoud, zoals langlopende scripts, inhoud die webweergave niet kan laden en waarschuwingen over onveilige inhoud.

Uw app reageert mogelijk niet terwijl scripts worden uitgevoerd. De gebeurtenis LongRunningScriptDetected vindt periodiek plaats terwijl de webweergave JavaScript uitvoert en een mogelijkheid biedt om het script te onderbreken. Als u wilt bepalen hoe lang het script wordt uitgevoerd, controleert u de eigenschap ExecutionTime van de WebViewLongRunningScriptDetectedEventArgs. Als u het script wilt stoppen, stel de event args StopPageScriptExecution eigenschap op true. Het gestopte script wordt niet opnieuw uitgevoerd, tenzij het opnieuw wordt geladen tijdens een volgende navigatie in de webweergave.

Het besturingselement voor webweergave kan geen willekeurige bestandstypen hosten. Wanneer er een poging wordt gedaan om inhoud te laden die niet door de webweergave kan worden gehost, vindt de gebeurtenis UnviewableContentIdentified plaats. U kunt deze gebeurtenis afhandelen en de gebruiker waarschuwen of de launcherklasse gebruiken om het bestand om te leiden naar een externe browser of een andere app.

Op dezelfde manier vindt de gebeurtenis UnsupportedUriSchemeIdentified plaats wanneer een URI-schema dat niet wordt ondersteund, wordt aangeroepen in de webinhoud, zoals fbconnect:// of mailto://. U kunt deze gebeurtenis afhandelen om aangepast gedrag te bieden in plaats van het standaardsysteemstartprogramma toe te staan de URI te starten.

De OnveiligeContentWarningDisplayingevent vindt plaats wanneer in de webweergave een waarschuwingspagina wordt weergegeven voor inhoud die door het SmartScreen-filter is gerapporteerd als onveilig. Als de gebruiker ervoor kiest om door te gaan met de navigatie, zal bij de volgende navigatie naar de pagina de waarschuwing niet worden weergegeven en zal het evenement niet worden geactiveerd.

Speciale gevallen voor webweergave-inhoud verwerken

U kunt de eigenschap ContainsFullScreenElement en de gebeurtenis ContainsFullScreenElementChanged gebruiken om ervaringen op volledig scherm in webinhoud te detecteren, erop te reageren en in te schakelen, zoals het afspelen van video in volledig scherm. U kunt bijvoorbeeld de gebeurtenis ContainsFullScreenElementChanged gebruiken om de webweergave aan te passen om de volledige app-weergave in te nemen, of, zoals geïllustreerd in het volgende voorbeeld, een venster-app in de modus Volledig scherm plaatsen wanneer een volledig scherm webervaring gewenst is.

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

U kunt de gebeurtenis NewWindowRequested gebruiken om zaken af te handelen waarbij gehoste webinhoud een nieuw venster aanvraagt dat moet worden weergegeven, zoals een pop-upvenster. U kunt een ander WebView-besturingselement gebruiken om de inhoud van het aangevraagde venster weer te geven.

Gebruik de gebeurtenis PermissionRequested om webfuncties in te schakelen waarvoor speciale mogelijkheden zijn vereist. Deze omvatten momenteel geolocatie, IndexedDB-opslag en audio en video van gebruikers (bijvoorbeeld vanaf een microfoon of webcam). Als uw app toegang heeft tot gebruikerslocatie of gebruikersmedia, moet u deze mogelijkheid nog steeds declareren in het app-manifest. Een app die gebruikmaakt van geolocatie heeft bijvoorbeeld minimaal de volgende mogelijkheidsdeclaraties nodig in Package.appxmanifest:

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

Naast de app die de gebeurtenis PermissionRequested verwerkt, moet de gebruiker standaardsysteemdialoogvensters goedkeuren voor apps die locatie- of mediamogelijkheden aanvragen om deze functies in te schakelen.

Hier volgt een voorbeeld van hoe een app geolocatie zou inschakelen in een kaart vanuit Bing:

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

Als voor uw app gebruikersinvoer of andere asynchrone bewerkingen nodig zijn om te reageren op een machtigingsaanvraag, gebruikt u de methode Defer van WebViewPermissionRequest om een WebViewDeferredPermissionRequest te maken waarop op een later tijdstip actie kan worden ondernomen. Zie WebViewPermissionRequest.Defer.

Als gebruikers zich veilig moeten afmelden bij een website die wordt gehost in een webweergave, of in andere gevallen wanneer de beveiliging belangrijk is, roept u de statische methode ClearTemporaryWebDataAsync aan om alle lokaal in de cache opgeslagen inhoud uit een webweergavesessie te wissen. Dit voorkomt dat kwaadwillende gebruikers toegang krijgen tot gevoelige gegevens.

Interactie met webweergave-inhoud

U kunt communiceren met de inhoud van de webweergave met behulp van de methode InvokeScriptAsync om script aan te roepen of in te voeren in de inhoud van de webweergave en de gebeurtenis ScriptNotify om informatie terug te krijgen van de inhoud van de webweergave.

Als u JavaScript wilt aanroepen in de inhoud van de webweergave, gebruikt u de methode InvokeScriptAsync . Het aangeroepen script kan alleen tekenreekswaarden retourneren.

Als de inhoud van een webweergave met de naam webView1 bijvoorbeeld een functie setDate bevat met drie parameters, kunt u deze als volgt aanroepen.

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

U kunt InvokeScriptAsync gebruiken met de JavaScript-functie eval om inhoud in een webpagina te injecteren.

Hier wordt de tekst van een XAML-tekstvak (nameTextBox.Text) geschreven naar een div in een HTML-pagina die wordt gehost in 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 });
}

Scripts in de webweergave-inhoud kunnen window.external.notify gebruiken met een tekenreeksparameter om informatie terug te sturen naar uw app. Als u deze berichten wilt ontvangen, moet u de gebeurtenis ScriptNotify afhandelen.

Als u een externe webpagina wilt inschakelen om de gebeurtenis ScriptNotify te activeren bij het aanroepen van window.external.notify, moet u de URI van de pagina opnemen in de sectie ApplicationContentUriRules van het app-manifest. (U kunt dit doen in Microsoft Visual Studio op het tabblad Inhouds-URI's van de designer Package.appxmanifest.) De URI's in deze lijst moeten HTTPS gebruiken en kunnen jokertekens voor subdomeinen bevatten (bijvoorbeeld https://*.microsoft.com) maar ze kunnen geen domein-jokertekens bevatten (bijvoorbeeld https://*.com en https://*.*). De manifestvereiste is niet van toepassing op inhoud die afkomstig is van het app-pakket, gebruikt een ms-local-stream:// URI of wordt geladen met NavigateToString.

Toegang tot Windows Runtime in een webweergave

U kunt de methode AddWebAllowedObject gebruiken om een exemplaar van een systeemeigen klasse uit een Windows Runtime-onderdeel in te voeren in de JavaScript-context van de webweergave. Hiermee hebt u volledige toegang tot de systeemeigen methoden, eigenschappen en gebeurtenissen van dat object in de JavaScript-inhoud van die webweergave. De klasse moet worden gedecoreerd met de eigenschap AllowForWeb.

Deze code injecteert bijvoorbeeld een exemplaar van MyClass geïmporteerd uit een Windows Runtime-onderdeel in een webweergave.

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

Zie WebView.AddWebAllowedObject voor meer informatie.

Daarnaast kan vertrouwde JavaScript-inhoud in een webweergave rechtstreeks toegang krijgen tot Windows Runtime-API's. Dit biedt krachtige systeemeigen mogelijkheden voor web-apps die worden gehost in een webweergave. Als u deze functie wilt inschakelen, moet de URI voor vertrouwde inhoud worden toegestaan in de ApplicationContentUriRules van de app in Package.appxmanifest, waarbij WindowsRuntimeAccess specifiek is ingesteld op 'all'.

In dit voorbeeld ziet u een sectie van het app-manifest. Hier krijgt een lokale URI toegang tot 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>

Opties voor webhosting

U kunt de eigenschap WebView.Settings (van het type WebViewSettings) gebruiken om te bepalen of JavaScript en IndexedDB zijn ingeschakeld. Als u bijvoorbeeld een webweergave gebruikt om strikt statische inhoud weer te geven, kunt u JavaScript uitschakelen voor de beste prestaties.

Inhoud van webweergave vastleggen

Als u het delen van webweergave-inhoud met andere apps wilt inschakelen, gebruikt u de methode CaptureSelectedContentToDataPackageAsync , waarmee de geselecteerde inhoud wordt geretourneerd als een DataPackage. Deze methode is asynchroon, dus u moet een uitstel gebruiken om te voorkomen dat uw DataRequested-gebeurtenis-handler terugkeert voordat de asynchrone aanroep is voltooid.

Als u een voorbeeldafbeelding van de huidige inhoud van de webweergave wilt ophalen, gebruikt u de methode CapturePreviewToStreamAsync . Met deze methode maakt u een afbeelding van de huidige inhoud en schrijft u deze naar de opgegeven stream.

Thread-gedrag

Webweergave-inhoud wordt standaard gehost op de UI-thread op apparaten in de bureaubladapparaatfamilie en buiten de UI-thread op alle andere apparaten. U kunt de statische eigenschap WebView.DefaultExecutionMode gebruiken om een query uit te voeren op het standaardgedrag voor threading voor de huidige client. Indien nodig kunt u de constructor WebView(WebViewExecutionMode) gebruiken om dit gedrag te overschrijven.

Notitie Er kunnen prestatieproblemen optreden bij het hosten van inhoud op de UI-thread op mobiele apparaten. Test daarom op alle doelapparaten wanneer u DefaultExecutionMode wijzigt.

Een webweergave die inhoud buiten de UI-thread host, is niet compatibel met bovenliggende besturingselementen die vereisen dat bewegingen worden doorgegeven van het webweergave-besturingselement naar het bovenliggende besturingselement, zoals FlipView-, ScrollViewer-en andere gerelateerde besturingselementen. Deze besturingselementen kunnen geen bewegingen ontvangen die zijn geïnitieerd in de webweergave buiten thread. Bovendien wordt het afdrukken van webinhoud buiten threads niet rechtstreeks ondersteund. U moet in plaats daarvan een element afdrukken met WebViewBrush-opvulling .

De voorbeeldcode halen

  • Last updated on