Introducción a WebView2 en WinUI 3 (versión preliminar)

En este artículo, empieza a crear tu primera aplicación WebView2 y obtén información sobre las características principales de WebView2. La primera aplicación WebView2 usa WinUI3. Para obtener más información sobre las API individuales, vaya a la referencia de la API.

Requisitos previos

Asegúrese de instalar la siguiente lista de requisitos previos antes de continuar.

  • WebView2 Runtime o cualquier canal no estable de Microsoft Edge (Chromium) instalado en Windows 10 versión 1803 (compilación 17134) o posterior. Para obtener más información sobre Windows 10, ve a Windows Update: Preguntas más frecuentes.

    Nota

    El equipo de WebView recomienda usar el canal Canary y la versión mínima necesaria es 82.0.488.0.

  • Visual Studio 2019, versión 16.9 Preview. Para obtener más información, ve a la Biblioteca de interfaz de usuario de Windows 3 Preview 3.

    • Incluya las siguientes cargas de trabajo al instalar Visual Studio.
      • Desarrollo de escritorio .NET (el instalador también instala .NET 5)
      • Desarrollo de la Plataforma universal de Windows
    • Para crear aplicaciones de C++, también debes incluir las siguientes cargas de trabajo.
      • Desarrollo de escritorio con C++
      • El componente opcional de las herramientas de la Plataforma universal de Windows C++ (v142) para la carga de trabajo de la Plataforma universal de Windows. Para obtener más información, ve a Detalles de instalación en la sección desarrollo de la Plataforma universal de Windows, en el panel derecho.

Paso 0: configuración Visual Studio configuración

  1. Asegúrese de que el sistema tiene un origen de paquete NuGet habilitado para nuget.org. Para obtener más información, vaya a configuraciones de NuGet comunes y a Windows Community Toolkit.

  2. Descarga e instala el paquete VSIX de WinUI 3 Preview 3. El instalador agrega las plantillas de proyecto WinUI 3 y el paquete NuGet que contiene las bibliotecas de WinUI 3 a Visual Studio 2019.

    Para obtener instrucciones sobre cómo agregar el paquete a Visual Studio, vaya a Buscar y VSIX usar Visual Studio extensiones.

  3. Para obtener acceso a todas las características de Visual Studio específicas del desarrollador, activa el modo de desarrollador.

Paso 1: Crear proyecto

Comience con un proyecto de escritorio básico que contenga una sola ventana principal.

  1. En Visual Studio, elija Crear un nuevo proyecto.

  2. En la lista desplegable del proyecto, elija C#, Windowsy WinUI respectivamente.

    Crear un nuevo proyecto de WinUI con Visual Studio

  3. Choose Blank App, Packaged (WinUI in Desktop) > Next.

  4. Escriba un nombre de proyecto.

  5. Elija las opciones según sea necesario.

  6. Elija Crear.

  7. En Nuevo proyecto de plataforma universal de Windows, elija los siguientes valores y, a continuación, elija Aceptar.

    • Versión dedestino: Windows 10, versión 1903 (compilación 18362) o posterior
    • Versión mínima: Windows 10, versión 1803 (compilación 17134)

    Cuadro de diálogo Nuevo proyecto de plataforma universal de Windows con los valores elegidos para la versión de destino y la versión mínima.

  8. En el Explorador de soluciones, se generan dos proyectos.

    • El nombre del proyecto (escritorio). El proyecto de escritorio contiene el código de la aplicación. El App.xaml.cs archivo define una clase que representa la instancia de la Application aplicación. El MainWindow.xaml.cs archivo define una clase que representa la ventana principal que muestra la instancia de la MainWindow aplicación. Las clases derivan de tipos en el Microsoft.UI.Xaml espacio de nombres de WinUI.
    • El nombre del proyecto (paquete). El proyecto de paquete es un proyecto de empaquetado de aplicaciones de Windows que está configurado para compilar la aplicación en un paquete MSIX para su implementación. El proyecto contiene el manifiesto del paquete de la aplicación y es el proyecto de inicio de la solución de forma predeterminada. Para obtener más información, ve a Configurar la aplicación de escritorio para el empaquetado MSIX en Visual Studio y la referencia del esquema del manifiesto del paquete para Windows 10.
  9. En el Explorador de soluciones, para mostrar el código, abra el MainWindow.xaml archivo. Para ejecutar el proyecto y mostrar una ventana con un botón, seleccione F5 .

Paso 2: Agregar un control WebView2 al proyecto

Agrega un control WebView2 al proyecto.

  1. En el MainWindow.xaml archivo, para agregar el espacio de nombres XAML WebView2, inserta la siguiente línea dentro de la <Window/> etiqueta.

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

    Asegúrese de que el código MainWindow.xaml es similar al siguiente fragmento de código.

    <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. Para agregar el control WebView2, reemplace las <StackPanel> etiquetas por el siguiente fragmento de código. La Source propiedad establece el URI inicial que se muestra en el control WebView2.

    <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. En el MainWindow.xaml.cs archivo, comente la siguiente línea.

        // myButton.Content = "Clicked";     
    
  4. Para compilar y ejecutar el proyecto, seleccione F5 . Asegúrese de que se muestra el control WebView2 [https://www.microsoft.com][|::ref1::|Main] .

    El control WebView2 muestra microsoft.com

Paso 3: Agregar controles de navegación

Para permitir a los usuarios controlar la página web que se muestra en el control WebView2, agrega una barra de direcciones a la aplicación.

  1. En el archivo, copie y pegue el siguiente fragmento de código MainWindow.xaml dentro del elemento que contiene el <Grid> WebView2 elemento.

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

    Asegúrese de <Grid> que el elemento del archivo es similar al siguiente fragmento de MainWindow.xaml código.

    <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. En el archivo, copie el siguiente fragmento de código en , que navega por el control WebView2 a la dirección URL especificada MainWindow.xaml.cs en la barra de myButton_Click direcciones.

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

    Para compilar y ejecutar el proyecto, seleccione F5 . Escriba una nueva dirección URL en la barra de direcciones y, a continuación, elija Ir. Por ejemplo, escriba https://www.bing.com .

    Nota

    Asegúrese de escribir direcciones URL completas en la barra de direcciones. ArgumentException se inician excepciones si la dirección URL no comienza con http:// o https:// .

    bing.com

Paso 4: Eventos de navegación

Las aplicaciones que hospedan controles WebView2 escuchan los siguientes eventos que los controles WebView2 genera durante la navegación de la página web.

  • NavigationStarting
  • SourceChanged
  • ContentLoading
  • HistoryChanged
  • NavigationCompleted

Nota

Si se produce un redireccionamiento HTTP, hay varios NavigationStarting eventos en una fila.

Para obtener más información, vaya a Eventos de navegación.

Cuando se producen errores, se producen los siguientes eventos y pueden navegar a una página web de error.

  • SourceChanged
  • ContentLoading
  • HistoryChanged

Como ejemplo de cómo usar los eventos, registre un controlador para que cancele las solicitudes que no NavigationStarting son HTTPS. In MainWindow.xaml.cs , modify the constructor to register , and add the function so that it matches the following EnsureHttps code EnsureHttps snippet.

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

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

Para compilar y ejecutar el proyecto, seleccione F5 . Asegúrese de que la navegación está bloqueada en sitios HTTP y permitida para los sitios HTTPS.

Paso 5: Scripting

Puedes usar aplicaciones host para insertar código JavaScript en controles WebView2 en tiempo de ejecución. Puede hacer que WebView ejecute JavaScript arbitrario o agregue scripts de inicialización. El JavaScript insertado se aplica a todos los nuevos documentos de nivel superior y a todos los fotogramas secundarios hasta que se quite el JavaScript. El JavaScript inyectado se ejecuta con intervalos específicos.

  • Ejecutarlo después de la creación del objeto global.
  • Ejecutarlo antes de ejecutar cualquier otro script incluido en el documento HTML.

Por ejemplo, agregue scripts que envíen una alerta cuando un usuario navegue a sitios que no son HTTPS. Modifique la EnsureHttps función para insertar un script en el contenido web que usa ExecuteScriptAsync.

private void EnsureHttps(WebView2 sender, WebView2NavigationStartingEventArgs 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;
    }
}

Para compilar y ejecutar el proyecto, seleccione F5 . Asegúrate de que la aplicación muestra una alerta cuando navegas a cualquier sitio web que no sea HTTPS.

El control WebView2 muestra un cuadro de diálogo de alerta

Enhorabuena, has creado tu primera aplicación WebView2.

Pasos siguientes

Para continuar con el aprendizaje sobre WebView2, vaya a los siguientes recursos.

Consulte también

  • Para obtener un ejemplo completo de las capacidades de WebView2, vaya a WebView2Samples.

  • Para obtener más información acerca de WebView2, vaya a Recursos de WebView2.

    Nota

    Es posible que el objeto WinRT CoreWebView2 no esté disponible con la versión de la API de WebView2. Para comprender qué API están disponibles para los controles WebView2, ve a WebView2 Spec para obtener una lista de las API que están disponibles.

  • Para obtener información detallada acerca de la API de WebView2, vaya a la especificación de WebView2.

Introducción al equipo de Microsoft Edge WebView

Comparte tus comentarios para ayudar a crear experiencias de WebView2 más ricas. Para enviar solicitudes de características o errores, o buscar problemas conocidos, vea el repositorio de comentarios de WebView de Microsoft Edge .