Share via

Introducción y notas de la versión: biblioteca de la interfaz de usuario de Windows 3 - Project Reunion 0.8, versión preliminar (mayo de 2021)

  • Artículo

La biblioteca de interfaz de usuario de Windows (WinUI) 3 es un marco nativo de experiencia de usuario (UX) para crear aplicaciones de Windows modernas. Se distribuye independientemente del sistema operativo Windows, como parte de Project Reunion (ahora denominado Windows App SDK). La versión preliminar 0.8 proporciona plantillas de WinUI 3 en Visual Studio para ayudarle a empezar a compilar aplicaciones con una interfaz de usuario basada en WinUI 3.

WinUI 3 - Project Reunion 0.8, versión preliminar es una versión preliminar de WinUI 3 que incluye correcciones de errores, mejoras generales y características experimentales, algunas de las cuales se estabilizarán para la versión estable de Windows App SDK 0.8 en junio de 2021.

Importante

La versión preliminar se ha lanzado no solo para que se pueda realizar una evaluación temprana de la misma, sino también para recopilar comentarios de la comunidad de desarrolladores. No debe usarse para aplicaciones de producción.

Si quiere enviar una aplicación de producción con Project Reunion y WinUI 3, consulte Información general y notas de la versión: WinUI 3 - Project Reunion 0.5.

Use el repositorio de GitHub de WinUI para proporcionar comentarios y registrar sugerencias y problemas.

Nota

Project Reunion es el nombre de código anterior para el SDK para aplicaciones de Windows. Esta documentación sigue utilizando Project Reunion al hacer referencia a versiones anteriores que usaban este nombre de código.

Instalación de WinUI 3 - Project Reunion 0.8 versión preliminar

Esta versión de WinUI 3 está disponible como parte de Project Reunion 0.8, versión preliminar. Para instalarla, consulte:

Instalación de herramientas para canales experimentales y de versión preliminar del SDK de Aplicaciones para Windows

Puesto que WinUI se incluye como parte de Project Reunion, descargará la extensión de Visual Studio (VSIX) para Project Reunion, que incluye un conjunto de herramientas y componentes para desarrolladores. Para obtener más información sobre el paquete de Project Reunion, consulte Implementación de aplicaciones que usan el SDK de la aplicación de Windows. El VSIX del SDK de la aplicación de Windows incluye plantillas de WinUI 3 en Visual Studio que usará para compilar la aplicación para WinUI 3.

Nota

Para ver en acción los controles y las características de WinUI 3, puede clonar y compilar WinUI 3 Controls Gallery desde GitHub o descargarla de Microsoft Store.

Una vez que haya configurado el entorno de desarrollo, consulte las plantillas de WinUI 3 en Visual Studio para familiarizarse con las plantillas de proyectos y de elementos de Visual Studio disponibles.

Para obtener más información sobre cómo empezar a trabajar con la compilación de una aplicación para WinUI 3, consulte los siguientes artículos:

Además de las limitaciones y los problemas conocidos, compilar una aplicación con los proyectos WinUI es similar a compilar una aplicación para UWP con XAML y WinUI 2. Por lo tanto, se pueden aplicar la mayor parte de la documentación sobre las instrucciones de las aplicaciones para UWP y los espacios de nombres de WinRT de Windows.UI de Windows SDK.

La documentación de referencia de la API de WinUI 3 está disponible aquí: referencia de la API de WinUI 3.

WebView2

Para usar WebView2 con esta versión de WinUI 3, descargue Evergreen Bootstrapper o el instalador independiente de Evergreen que se encuentra en esta página si aún no tiene instalado el entorno de ejecución de WebView2.

Kit de la comunidad de Windows

Si usa Windows Community Toolkit, descargue la versión más reciente.

Compatibilidad de Visual Studio

Con el fin de aprovechar las características más recientes de las herramientas, agregadas a WinUI 3, como Recarga activa, Árbol visual dinámico y Explorador de propiedades dinámico, tiene que usar una versión preliminar de Visual Studio 2019, versión 16.10. Tenga en cuenta las versiones de Visual Studio Preview son productos en versión preliminar, por lo que puede encontrar errores y limitaciones al usar versiones preliminares de Visual Studio para compilar aplicaciones de WinUI 3.

En la tabla siguiente se muestra la compatibilidad de las versiones de Visual Studio 2019 con WinUI 3 - Project Reunion 0.5.

Versión de VS WinUI 3 - Project Reunion 0.5
16.8 No
16,9 Sí, pero sin Recarga activa, Árbol visual dinámico ni Explorador de propiedades dinámico
Versiones preliminares 16.10 Sí, con todas las herramientas de WinUI 3 (en versión preliminar)

Actualización de la aplicación para WinUI 3 existente

Si ha creado una aplicación con una versión preliminar o una versión anterior de WinUI 3, puede actualizar el proyecto para que use WinUI 3 - Project Reunion 0.8 versión preliminar. Para obtener instrucciones, consulte Actualización de los proyectos existentes a la versión más reciente de Project Reunion.

Principales cambios introducidos en esta versión

  • El control dinámico ya está disponible para su uso en esta versión.
  • La mayoría de las correcciones de errores críticos de las versiones de mantenimiento de Project Reunion v0.5.5, v0.5.6 y v0.5.7 también se incluyen en esta versión. Para ver las correcciones de mantenimiento que no se incluyen en esta versión preliminar, consulte Problemas conocidos.

Lista de errores corregidos en WinUI 3 - Project Reunion 0.8 versión preliminar

  • x:Bind no funciona en un elemento menuFlyoutItem personalizado (más generalmente, x:Bind en ControlTemplate no funciona si el ámbito de nombres primario también usa x:Bind)

  • Se ocultan las ventanas emergentes cuando se mueve la ventana de nivel superior (o isla)

  • La página StandardUICommand de WinUI 3 Controls Gallery no muestra todo

  • El clic con el botón derecho del mouse en TextBox bloquea la aplicación

  • El menú contextual se muestra en una ubicación incorrecta para EditableComboBox

  • Cambiar la selección de RichTextBlock con la función táctil hace que el indicador de selección desaparezca

  • Excepción de Microsoft C++: winrt::hresult_error en ubicación de memoria 0x... cuando se usa NavigationView

  • El mensaje de error WinUI 3 necesita reescribirse: "No se puede resolver 'Windows.metadata'. Instale el Kit de desarrollo de software de Windows. El Windows SDK se instala con Visual Studio".

  • La singularidad del establecedor de VSM de generar una excepción tiene la lógica al revés

  • Se quita el foco de WebView2 (si es necesario) cuando se bloquea el proceso del explorador

  • El elemento ProgressBar no muestra la diferencia entre las opciones En pausa y Error

  • El elemento PointerReplay está en ejecución constante

  • El elemento NavigationView provoca un bloqueo en UWP, Reunion 0.5 versión preliminar

  • AutoSuggestBox, ComboBox y CommandBarFlyout no establecen ShouldConstrainToRootBounds="false" en su ventana emergente

  • WinUI 3 - Project Reunion 0.5 genera excepciones de C++ para una aplicación administrada de C#

  • Se pierde el foco de la pestaña inicial de WebView2

  • WebView2 se bloquea cuando cambian los PPP después de Close()

  • Cambio en la apariencia de AppBarButton con control flotante en CommandBar en WinUI3

Características y funcionalidades introducidas en versiones preliminares anteriores de WinUI 3

Las siguientes características y funcionalidades se introdujeron en versiones preliminares anteriores de WinUI 3 y continúan siendo compatibles con WinUI 3 - Project Reunion 0.8 versión preliminar.

Nota

Algunas de las siguientes características seguirán formando parte de las versiones preliminares de WinUI 3, pero no formará parte de la próxima versión compatible. Estas características se marcan como experimentales y lanzarán una advertencia cuando se usen en una aplicación. Las API que forman parte de la versión previa de WinUI 2.6 también se marcan como experimentales en esta versión.

  • Capacidad para crear aplicaciones de escritorio con WinUI, incluido .NET para aplicaciones Win32
  • Compatibilidad del nivel de versión preliminar para crear aplicaciones para UWP
  • RadialGradientBrush
  • Actualizaciones de TabView
  • Actualizaciones de temas oscuros
  • Mejoras y actualizaciones para WebView2
    • Compatibilidad con valores altos de PPP
    • Compatibilidad con el cambio de tamaño y desplazamiento de ventanas
    • Actualizado para poder usar una versión más reciente de Edge
    • Desaparece la necesidad de hacer referencia a un paquete NuGet específico de WebView2
  • SwapChainPanel
  • Compatibilidad con MRT Core
    • Esto hace que las aplicaciones sean más rápidas y ligeras en el inicio y proporciona una búsqueda de recursos más rápida.
  • Compatibilidad con ARM64
  • Arrastrar y colocar dentro y fuera de las aplicaciones
  • RenderTargetBitmap (actualmente solo contenido XAML, sin contenido SwapChainPanel)
  • Compatibilidad con cursores personalizados
  • Entrada fuera de subproceso
  • Mejoras en nuestra experiencia del desarrollador o herramientas:
    • Árbol visual dinámico, recarga activa, explorador de propiedades dinámico y herramientas similares
    • IntelliSense para WinUI 3
  • Mejoras necesarias para la migración del código abierto
  • Funcionalidades de barra de título personalizadas: nuevas API Window.ExtendsContentIntoTitleBar y Window.SetTitleBar, que permiten a los desarrolladores crear barras de título personalizadas en aplicaciones de escritorio.
  • Compatibilidad con VirtualSurfaceImageSource
  • Acrílico en la aplicación
  • Compatibilidad con varias ventanas en aplicaciones de escritorio
  • Validación de la entrada

Comentarios y sugerencias

Agradecemos todos los comentarios que dejéis en el repositorio de WinUI de GitHub.

Limitaciones y problemas conocidos

La versión preliminar de WinUI 3 - Project Reunion 0.8 es solo eso, una versión preliminar. por lo que puedes encontrar errores, limitaciones y problemas.

Estos son algunos de los problemas conocidos que pueden aparecer en WinUI 3 - Project Reunion 0.8. Si encuentra algún problema que no se muestra a continuación, háganoslo saber colaborando en un problema existente o presentando un nuevo problema en el repositorio de WinUI de GitHub.

Compatibilidad con la plataforma y el sistema operativo

WinUI 3 - Project Reunion 0.8 versión preliminar es compatible con equipos en los que se ejecuta la Actualización de octubre de 2018 de Windows 10 (versión 1809, compilación 17763), o cualquier versión más reciente.

Herramientas para desarrolladores

  • Solo se admiten las aplicaciones C# y C++/WinRT.
  • Las aplicaciones de escritorio admiten .NET 6 (y versiones posteriores) y C# 9, y se deben empaquetar en una aplicación MSIX.
  • No existe compatibilidad con el Diseñador XAML.
  • No se admiten las nuevas aplicaciones escritas en C++/CX. Sin embargo, las aplicaciones existentes seguirán funcionando (es aconsejable empezar a usar C++/WinRT lo antes posible).
  • No se admite la implementación de escritorio sin empaquetar.
  • Al ejecutar una aplicación de escritorio con F5, asegúrese de que está ejecutando el proyecto de empaquetado. Si presiona F5 en el proyecto de aplicación, se ejecutará una aplicación sin empaquetar, que ya no es compatible con WinUI 3.

Faltan características de la plataforma

  • Compatibilidad con Xbox

  • Compatibilidad con HoloLens

  • Elementos emergentes con ventanas

    • Más concretamente, la propiedad ShouldConstrainToRootBounds siempre actúa como si estuviera establecida en true, independientemente del valor de la propiedad.

  • Compatibilidad con entrada de lápiz, lo que incluye:

  • Acrílico en el fondo

  • MediaElement y MediaPlayerElement

  • MapControl

  • SwapChainPanel no admite la transparencia

  • AcrylicBrush y otros efectos que usan CompositionBackdropBrush no se pueden probar desde SwapChainPanel o WebView2.

  • Global Reveal usa el comportamiento de reserva, que es un pincel sólido

  • XAML Islands no se admite en esta versión

  • El uso de WinUI 3 directamente en una aplicación de escritorio existente que no es para WinUI tiene la siguiente limitación: la ruta de acceso disponible actualmente para migrar una aplicación existente es agregar un nuevo proyecto de WinUI 3 a la solución, y ajustar o refactorizar la lógica según sea necesario.

  • No se llama a Application.Suspending en aplicaciones de escritorio. Consulte la documentación de la referencia de API en el Evento Application.Suspending para obtener más detalles.

  • El evento UISettings.ColorValuesChanged y el evento AccessibilitySettings.HighContrastChanged ya no se admiten en las aplicaciones de escritorio. Esto puede generar problemas si los usa para detectar cambios en los temas de Windows.

  • Anteriormente, para obtener una instancia de CompositionCapabilities, llamaría a CompositionCapabilites.GetForCurrentView(). Sin embargo, las funcionalidades devueltas por esta llamada no dependían de la vista. Para abordar y reflejar esto, hemos eliminado el método estático GetForCurrentView() en esta versión, por lo que ahora puede crear un objeto CompositionCapabilties directamente.

  • CoreWindow, ApplicationView, CoreApplicationView, CoreDispatcher y sus dependencias no se admiten en aplicaciones de escritorio (consulte a continuación).

CoreWindow, ApplicationView, CoreApplicationView y CoreDispatcher en aplicaciones de escritorio

Novedades de WinUI 3, versión preliminar 4, y de serie a partir de este momento, CoreWindow, ApplicationView, CoreApplicationView,CoreDispatcher y sus dependencias no están disponibles en aplicaciones de escritorio. Por ejemplo, la propiedad Window.Dispatcher siempre es NULL, pero se puede usar la propiedad Window.DispatcherQueue como alternativa.

Estas API solo funcionan en aplicaciones para UWP. En las versiones preliminares anteriores, también funcionaban parcialmente en aplicaciones de escritorio, pero desde la versión preliminar 4 se deshabilitaron por completo. Estas API están diseñadas para el caso de UWP donde solo hay una ventana por subproceso, y una de las características futuras de WinUI 3 es habilitar varias.

Hay API que dependen internamente de la existencia de estas API que, por tanto, no se admiten en una aplicación de escritorio. En general, estas API tienen un método GetForCurrentView estático. Por ejemplo UIViewSettings.GetForCurrentView.

Para obtener más información sobre las API afectadas, así como las soluciones alternativas y los reemplazos de dichas API, consulte Las API de Windows Runtime no se admiten en aplicaciones de escritorio.

Problemas conocidos

  • Es posible que reciba un error de compilación debido a versiones no coincidentes del SDK de .NET y winrt.runtime.dll. Como alternativa, intente una de estas opciones:

    Establezca explícitamente el SDK de .NET en la versión correcta. Para determinar la versión correcta de la aplicación, busque la etiqueta <TargetFramework> en el archivo del proyecto. Con el número de compilación de Windows SDK que la aplicación tiene como destino en la etiqueta <TargetFramework> (por ejemplo, 18362 o 19041), agregue el siguiente elemento al archivo de proyecto y guarde el proyecto:

    <ItemGroup>            
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.{Target Windows SDK Build Number}.16" />
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.{Target Windows SDK Build Number}.16" />
</ItemGroup>

    Tenga en cuenta que esta solución alternativa es necesaria para el SDK de .NET 5.0.203 y versiones anteriores, pero no será necesaria para el SDK de .NET 5.0.204 o 5.0.300.

  • Al usar Visual Studio 2019, versión 16.10, Preview 2, Árbol visual dinámico puede provocar un bloqueo. Para evitarlo, actualice a Visual Studio 2019, versión 16.10 Preview más reciente.

  • Los botones de la leyenda de la ventana pueden estar mal colocados cuando SetTitleBar no se ha establecido o es NULL

Consulte WinUI 3 Controls Gallery (anteriormente denominada XAML Controls Gallery - versión de WinUI 3) para obtener una aplicación de ejemplo que incluya todos los controles y características que forman parte de WinUI 3 - Project Reunion 0.8 versión preliminar.

WinUI 3 Controls Gallery app
Ejemplo de aplicación WinUI 3 Controls Gallery

La aplicación WinUI 3 Controls Gallery está disponible a través de Microsoft Store.

También puede clonar el repositorio de GitHub para descargar el ejemplo. Para ello, clone la rama winui3 con el siguiente comando:

Nota

También hay una rama winui3preview en este repositorio de GitHub que proporciona una versión de WinUI 3 Controls Gallery que usa WinUI 3 - Project Reunion 0.8 versión preliminar.

git clone --single-branch --branch winui3 https://github.com/microsoft/Xaml-Controls-Gallery.git

Después de la clonación, asegúrese de cambiar a la rama winui3 en su entorno de GIT local:

git checkout winui3

Consulte también