Erste Schritte mit WebView2 in WinUI 3 (Windows App SDK)

Beginnen Sie in diesem Artikel mit dem Erstellen Ihrer ersten WebView2-App, und erfahren Sie mehr über die Hauptfeatures von WebView2. Ihre erste WebView2-App verwendet WinUI 3. Für weitere Informationen zu einzelnen APIs navigieren Sie zur API-Referenz.

Schritt 0 – Einrichten der Entwicklungsumgebung

  1. Führen Sie die Schritte 1 bis 4 zum Einrichten der Entwicklungsumgebung aus, um Visual Studio zu installieren, die NuGet Paketquelle zu konfigurieren und die Windows App SDK-Erweiterung für Visual Studio zu installieren.
  2. Installieren Sie die WebView2-Runtime oder einen beliebigen Microsoft Edge nicht stabilen Kanal, der auf Windows 10 Version 1803 (Build 17134) oder höher installiert ist. For more information about Windows 10 or later, navigate to Windows Update: FAQ.
  3. Um auf alle entwicklerspezifischen Visual Studio Features zuzugreifen, aktivieren Sie den Entwicklermodus.

Schritt 1 : Erstellen Project

Beginnen Sie mit einem einfachen Desktopprojekt, das ein einzelnes Hauptfenster enthält.

  1. Wählen Sie in Visual Studio ein neues Projekt erstellenaus.

  2. Wählen Sie in der Projekt-Dropdownliste C#, Windowsund WinUI aus.

    Erstellen eines neuen WinUI-Projekts mit Visual Studio

  3. Wählen Sie leere App, verpackt (WinUI in Desktop) > weiter.

  4. Geben Sie einen Projektnamen ein.

  5. Wählen Sie nach Bedarf Optionen aus.

  6. Wählen Sie Erstellen aus.

  7. Wählen Sie in New Universal Windows Platform Projectdie folgenden Werte aus, und wählen Sie dann OKaus.

    • Zielversion: Windows 10, Version 1903 (Build 18362) oder höher
    • Mindestversion: Windows 10, Version 1803 (Build 17134)

    The New Universal Windows Platform Project dialog with chosen values for Target version and Minimum version.

  8. Im Projektmappen-Explorer werden zwei Projekte generiert.

    • Ihr Projektname (Desktop). Das Desktopprojekt enthält den Code für Ihre App. Die App.xaml.cs Datei definiert eine Application Klasse, die Ihre App-Instanz darstellt. Die MainWindow.xaml.cs Datei definiert eine MainWindow Klasse, die das hauptfenster darstellt, das von Ihrer App-Instanz angezeigt wird. Die Klassen werden von Typen im Microsoft.UI.Xaml Namespace von WinUI abgeleitet.
    • Ihr Projektname (Paket). Das Paketprojekt ist ein Windows Application Packaging-Project, das so konfiguriert ist, dass die App in ein MSIX-Paket für die Bereitstellung integriert wird. Das Projekt enthält das Paketmanifest für Ihre App und ist standardmäßig das Startprojekt für Ihre Lösung. For more information, navigate to Set up your desktop application for MSIX packaging in Visual Studio and Package manifest schema reference for Windows 10.
  9. Öffnen Sie im Projektmappen-Explorer die Datei, um den Code MainWindow.xaml anzuzeigen. Um Ihr Projekt auszuführen und ein Fenster mit einer Schaltfläche anzuzeigen, wählen Sie F5 .

Schritt 2: Hinzufügen eines WebView2-Steuerelements zu Ihrem Projekt

Fügen Sie Ihrem Projekt ein WebView2-Steuerelement hinzu.

  1. Um MainWindow.xaml den WebView2-XAML-Namespace hinzuzufügen, fügen Sie in der Datei die folgende Zeile in das <Window/> Tag ein.

    xmlns:controls="using:Microsoft.UI.Xaml.Controls"
    

    Stellen Sie sicher, dass ihr Code in MainWindow.xaml dem folgenden Codeausschnitt ähnelt.

    <Window
          x:Class="WinUI_Sample.MainWindow"
          xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
          xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
          xmlns:local="using:WinUI_Sample"
          xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
          xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
          mc:Ignorable="d"
          xmlns:controls="using:Microsoft.UI.Xaml.Controls"
          >
    
          <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center">
            <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
          </StackPanel>
    
    </Window>
    
  2. Um das WebView2-Steuerelement hinzuzufügen, ersetzen Sie die <StackPanel> Tags durch den folgenden Codeausschnitt. Die Eigenschaft legt den anfänglichen URI fest, Source der im WebView2-Steuerelement angezeigt wird.

    <Grid>
    
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="*" />
            <ColumnDefinition Width="Auto" />
        </Grid.ColumnDefinitions>
    
        <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
            Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch" />
    
    </Grid>
    
  3. Kommentieren Sie in der MainWindow.xaml.cs Datei die folgende Zeile aus.

        // myButton.Content = "Clicked";
    
  4. Um Ihr Projekt zu erstellen und auszuführen, wählen Sie F5 . Stellen Sie sicher, dass das WebView2-Steuerelement angezeigt [https://www.microsoft.com][|::ref1::|Main] wird.

    WebView2-Steuerelement zeigt microsoft.com

Schritt 3: Hinzufügen von Navigationssteuerelementen

Damit Benutzer die Webseite steuern können, die in Ihrem WebView2-Steuerelement angezeigt wird, fügen Sie Ihrer App eine Adressleiste hinzu.

  1. Kopieren Sie in der MainWindow.xaml Datei den folgenden Codeausschnitt, und fügen Sie ihn in das Element <Grid> ein, das das Element WebView2 enthält.

        <TextBox Name="addressBar" Grid.Column="0"/>
        <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>
    

    Stellen Sie sicher, dass <Grid> das Element in der Datei dem folgenden MainWindow.xaml Codeausschnitt ähnelt.

    <Grid>
    
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="*" />
            <ColumnDefinition Width="Auto" />
        </Grid.ColumnDefinitions>
    
        <TextBox Name="addressBar" Grid.Column="0"/>
        <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>
    
        <WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
            Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch" />
    
    </Grid>
    
  2. Kopieren Sie in der MainWindow.xaml.cs Datei den folgenden Codeausschnitt in , in myButton_Click den das WebView2-Steuerelement zu der in der Adressleiste eingegebenen URL navigiert.

    private void myButton_Click(object sender, RoutedEventArgs e)
    {
        try
        {
            Uri targetUri = new Uri(addressBar.Text);
            MyWebView.Source = targetUri;
        }
        catch (FormatException ex)
        {
            // Incorrect address entered.
        }
    }
    

    Um Ihr Projekt zu erstellen und auszuführen, wählen Sie F5 . Geben Sie eine neue URL in die Adressleiste ein, und klicken Sie dann auf "Los". Geben Sie beispielsweise https://www.bing.com .

    Hinweis

    Stellen Sie sicher, dass Sie vollständige URLs in der Adressleiste eingeben. ArgumentException Ausnahmen werden ausgelöst, wenn die URL nicht mit http:// oder https:// beginnt.

    bing.com

Schritt 4: Navigationsereignisse

Für diesen Schritt müssen wir die WebView2 Core-Bibliothek importieren.

Fügen Sie oben die folgende Zeile MainWindow.xaml.cs hinzu:

using Microsoft.Web.WebView2.Core;

Apps, die WebView2-Steuerelemente hosten, überwachen die folgenden Ereignisse, die von WebView2-Steuerelementen während der Webseitennavigation ausgelöst werden.

  • NavigationStarting
  • SourceChanged
  • ContentLoading
  • HistoryChanged
  • NavigationCompleted

Hinweis

Wenn eine HTTP-Umleitung erfolgt, gibt es mehrere NavigationStarting Ereignisse in einer Zeile.

Navigieren Sie zu Navigationsereignissen,um weitere Informationen zu erfahren.

Wenn Fehler auftreten, werden die folgenden Ereignisse ausgelöst und können zu einer Fehlerwebseite navigieren.

  • SourceChanged
  • ContentLoading
  • HistoryChanged

Als Beispiel für die Verwendung der Ereignisse registrieren Sie einen Handler dafür, der NavigationStarting alle Nicht-HTTPS-Anforderungen abbricht. MainWindow.xaml.csÄndern Sie in den Konstruktor, um ihn zu EnsureHttps registrieren, und fügen Sie die Funktion EnsureHttps so hinzu, dass sie dem folgenden Codeausschnitt entspricht.

public MainWindow()
{
    InitializeComponent();
    MyWebView.NavigationStarting += EnsureHttps;
}

private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args)
{
    String uri = args.Uri;
    if (!uri.StartsWith("https://"))
    {
        args.Cancel = true;
    }
    else
    {
        addressBar.Text = uri;
    }
}

Um Ihr Projekt zu erstellen und auszuführen, wählen Sie F5 . Stellen Sie sicher, dass die Navigation zu HTTP-Websites blockiert und für HTTPS-Websites zulässig ist.

Hinweis

Das WinRT-Objekt CoreWebView2 ist möglicherweise nicht mit der Veröffentlichung der WebView2-API verfügbar. Die WebView2-Spezifikation listet auf, welche der APIs für WebView2 verfügbar sind.

Schritt 5 – Skripting

Sie können Host-Apps verwenden, um JavaScript-Code zur Laufzeit in WebView2-Steuerelemente einzufügen. Sie können WebView zum Ausführen beliebigen JavaScripts oder zum Hinzufügen von Initialisierungsskripts verwenden. Das eingefügte JavaScript gilt für alle neuen Dokumente der obersten Ebene und alle untergeordneten Frames, bis javaScript entfernt wird. Das eingefügte JavaScript wird mit einem bestimmten Timing ausgeführt.

  • Führen Sie es nach der Erstellung des globalen Objekts aus.
  • Führen Sie es aus, bevor ein anderes im HTML-Dokument enthaltenes Skript ausgeführt wird.

Fügen Sie beispielsweise Skripts hinzu, die eine Warnung senden, wenn ein Benutzer zu Nicht-HTTPS-Websites navigiert. Ändern Sie die EnsureHttps Funktion, um ein Skript in den Webinhalt einzufügen, der ExecuteScriptAsync verwendet.

private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args)
{
    String uri = args.Uri;
    if (!uri.StartsWith("https://"))
    {
        MyWebView.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
        args.Cancel = true;
    }
    else
    {
        addressBar.Text = uri;
    }
}

Um Ihr Projekt zu erstellen und auszuführen, wählen Sie F5 . Stellen Sie sicher, dass Ihre App eine Warnung anzeigt, wenn Sie zu websites navigieren, die keine HTTPS-Websites sind.

WebView2-Steuerelement zeigt ein Warnungsdialogfeld an

Herzlichen Glückwunsch, Sie haben Ihre erste WebView2-App erstellt!

Weitere Informationen