Visão geral e notas sobre a versão: Biblioteca de Interface do Usuário do Windows 3 – Project Reunion 0.8 Versão Prévia (maio de 2021)

  • Artigo

A Biblioteca WinUI (Interface do Usuário do Windows) 3 é uma estrutura de UX (experiência do usuário) nativa para criação de aplicativos do Windows modernos. Ela é fornecida de maneira independente do sistema operacional Windows como parte do Project Reunion (agora chamado de SDK de Aplicativo do Windows). A Versão Prévia 0.8 fornece modelos da WinUI 3 no Visual Studio para ajudar você a começar a criar aplicativos com uma interface do usuário baseada na WinUI 3.

O WinUI 3 – Project Reunion 0.8 Versão Prévia é uma versão de pré-lançamento do WinUI 3 que inclui correções de bug, aprimoramentos gerais e recursos experimentais, alguns dos quais serão estabilizados para a versão estável 0.8 do SDK de Aplicativo do Windows em junho de 2021.

Importante

A finalidade desta versão prévia é fazer uma avaliação inicial e reunir comentários da comunidade de desenvolvedores. Ele NÃO deve ser usado para aplicativos de produção.

Se você pretende enviar um aplicativo de produção usando o Project Reunion e o WinUI 3, confira Visão geral e notas sobre a versão: WinUI 3 – Project Reunion 0.5.

Use o repositório do GitHub do WinUI para fornecer comentários e registrar sugestões e problemas.

Observação

Project Reunion é o nome de código anterior do SDK do Aplicativo Windows. Esta documentação ainda usa o Project Reunion ao fazer referência a versões anteriores que usavam esse codinome.

Instalar o WinUI 3 – Project Reunion 0.8 Versão Prévia

Essa versão do WinUI 3 está disponível como parte do Project Reunion 0.8 Versão Prévia. Para instalar, confira:

Instalar ferramentas para canais experimentais e versão prévia do SDK do Aplicativo Windows

Como o WinUI é fornecido como parte do Project Reunion, para começar, você baixará o VSIX (Visual Studio Extension) do Project Reunion, que inclui um conjunto de ferramentas e componentes para desenvolvedores. Para saber mais sobre o pacote do Project Reunion, confira Implantar aplicativos que usam o SDK do Aplicativo do Windows. O VSIX do SDK do Aplicativo do Windows inclui os modelos da WinUI 3 no Visual Studio que serão usados na criação de um aplicativo WinUI 3.

Observação

Para ver os controles e recursos do WinUI 3 em ação, você pode clonar e criar a Galeria de Controles do WinUI 3 do GitHub ou baixá-la na Microsoft Store.

Depois de configurar o ambiente de desenvolvimento, confira Modelos da WinUI 3 no Visual Studio para se familiarizar com os modelos de projeto e de item do Visual Studio disponíveis.

Para obter mais informações sobre como começar a criar um aplicativo do WinUI 3, confira os seguintes artigos:

Exceto pelas limitações e pelos problemas conhecidos, criar um aplicativo usando os projetos do WinUI é semelhante a criar um aplicativo UWP com XAML e WinUI 2. Portanto, a maior parte da documentação de diretrizes de aplicativos UWP e dos namespaces WinRT do Windows.UI no SDK do Windows é aplicável.

A documentação de referência de API do WinUI 3 está disponível em: Referência de API do WinUI 3

WebView2

Para usar o WebView2 com esta versão do WinUI 3, caso ainda não tenha o WebView2 Runtime instalado, baixe o Evergreen Bootstrapper ou o Instalador Autônomo do Evergreen nesta página.

Windows Community Toolkit

Se você estiver usando o Kit de Ferramentas da Comunidade do Windows, baixe a versão mais recente.

Suporte ao Visual Studio

Para aproveitar os recursos mais recentes de ferramentas adicionados ao WinUI 3, como a Recarga Dinâmica, a Árvore Visual Dinâmica e o Explorador de Propriedades Dinâmicas, você precisa usar uma versão prévia do Visual Studio 2019 16.10. Observe que as versões prévias do Visual Studio são produtos de pré-lançamento, então você pode encontrar bugs e limitações ao usar essas versões prévias do Visual Studio para criar aplicativos WinUI 3.

Veja na tabela abaixo a compatibilidade das versões do Visual Studio 2019 com o WinUI 3 – Project Reunion 0.5.

Versão do VS WinUI 3 – Project Reunion 0.5
16.8 Não
16,9 Sim, mas sem a Recarga Dinâmica, a Árvore Visual Dinâmica ou o Explorador de Propriedades Dinâmicas
16.10 Versões prévias Sim, com todas as ferramentas do WinUI 3 (em versão prévia)

Atualizando seu aplicativo do WinUI 3 existente

Se você criou um aplicativo com uma versão prévia ou estável anterior do WinUI 3, poderá atualizar o projeto para usar o WinUI 3 – Project Reunion 0.8 Versão Prévia. Para obter instruções, consulte Atualizar projetos existentes para a versão mais recente do Project Reunion.

Principais alterações introduzidas nesta versão

  • O controle dinâmico agora está disponível para uso nesta versão.
  • A maioria das correções críticas de bugs das versões de manutenção do Project Reunion v0.5.5, v0.5.6 e v0.5.7 também está incluída nesta versão. Para correções de manutenção que não foram incluídas nesta versão prévia, confira Problemas conhecidos.

Lista de bugs corrigidos no WinUI 3 – Project Reunion 0.8 Versão Prévia

  • x:Bind não funcionava em um MenuFlyoutItem personalizado (de modo mais geral, x:Bind no ControlTemplate não funcionava se o namescope pai também usasse x:Bind)

  • Pop-ups em janelas eram ocultadas quando a janela (ou ilha) de nível superior era movida

  • A página StandardUICommand na Galeria de Controles do WinUI 3 não mostrava tudo

  • O aplicativo tinha uma falha quando o usuário clicava com o botão direito do mouse em TextBox

  • Menu de contexto era exibido no local errado para EditableComboBox

  • A alteração da seleção RichTextBlock com toque fazia o indicador de seleção desaparecer

  • Exceção do Microsoft C++: ocorria o erro winrt::hresult_error no local de memória 0x... quando NavigationView estava sendo usado

  • A mensagem de erro do WinUI 3 precisa ser reescrita: "Não é possível resolver 'Windows.metadata'. Instale o Software Development Kit do Windows. O SDK do Windows é instalado com o Visual Studio".

  • A peculiaridade do VSM Setter para gerar uma exceção tinha uma lógica reversa

  • O foco era tirado do WebView2 (se necessário) quando o processo do navegador falhava

  • ProgressBar não mostra a diferença entre as opções Pausa e Erro

  • PointerReplay estava em constante execução

  • NavigationView causava falha na UWP, no Reunion 0.5 Versão Prévia

  • AutoSuggestBox, ComboBox e CommandBarFlyout não estavam definindo ShouldConstrainToRootBounds="false" na respectiva pop-up

  • O WinUI 3 – Project Reunion 0.5 estava gerando exceções do C++ para um aplicativo gerenciado em C#

  • O foco na guia inicial do WebView2 era perdido

  • O WebView2 falhava quando o DPI era alterado após Close()

  • Alteração na aparência de AppBarButton com submenu em CommandBar no WinUI3

Recursos e funcionalidades introduzidos em versões prévias anteriores do WinUI 3

Os recursos e as funcionalidades a seguir foram introduzidos nas versões prévias anteriores do WinUI 3 e continuam tendo suporte no WinUI 3 – Project Reunion 0.8 Versão Prévia.

Observação

Alguns recursos a seguir continuarão fazendo parte das versões prévias do WinUI 3, mas talvez não façam parte da próxima versão com suporte. Esses recursos são marcados como experimentais e emitirão um aviso quando usados em um aplicativo. As APIs que fazem parte da versão de pré-lançamento do WinUI 2.6 também são marcadas como experimentais nesta versão.

  • Capacidade de criar aplicativos da área de trabalho com a WinUI, incluindo .NET para aplicativos Win32
  • Suporte em nível de versão prévia para a criação de aplicativos UWP
  • RadialGradientBrush
  • Atualizações de TabView
  • Atualizações do tema escuro
  • Melhorias e atualizações de WebView2
    • Suporte para DPI Alto
    • Suporte para redimensionamento e movimentação de janela
    • Atualizado para ter como destino a versão mais recente do Edge
    • Deixou de ser necessário fazer referência a um pacote NuGet específico do WebView2
  • SwapChainPanel
  • Suporte ao MRT Core
    • Isso torna os aplicativos mais rápidos e mais leves para a inicialização e fornece uma pesquisa de recursos mais rápida.
  • Suporte ao ARM64
  • Arrastar e soltar dentro e fora dos aplicativos
  • RenderTargetBitmap (no momento, somente conteúdo XAML – nenhum conteúdo SwapChainPanel)
  • Suporte a cursores personalizado
  • Entrada fora do thread
  • Aprimoramentos em nossa experiência de ferramentas/desenvolvedores:
    • Árvore Visual Dinâmica, Recarga Dinâmica, Gerenciador de Propriedades Dinâmicas e ferramentas semelhantes
    • Intellisense para WinUI 3
  • Melhorias necessárias para a migração de software livre
  • Funcionalidades da barra de título personalizada: novas APIs Window.ExtendsContentIntoTitleBar e Window.SetTitleBar que permitem aos desenvolvedores criar barras de título personalizadas em aplicativos de área de trabalho.
  • Suporte a VirtualSurfaceImageSource
  • Acrílico do aplicativo
  • Suporte a várias janelas em aplicativos da área de trabalho
  • Validação de entrada

Fornecer comentários e sugestões

Seus comentários são bem-vindos no repositório do WinUI no GitHub.

Limitações e problemas conhecidos

O WinUI 3 – Project Reunion Versão Prévia 0.8 é somente isso, uma versão prévia. Saiba que pode haver bugs, limitações e outros problemas.

Os itens a seguir são alguns dos problemas conhecidos do WinUI 3 – Project Reunion 0.8. Se encontrar algum problema que não está listado abaixo, informe-nos contribuindo com um problema existente ou criando um por meio do Repositório GitHub do WinUI.

Suporte para plataformas e SOs

O WinUI 3 – Project Reunion 0.8 Versão Prévia é compatível com computadores que executam a Atualização de outubro de 2018 para o Windows 10 (versão 1809 – build 17763) e versões mais recentes.

Ferramentas para desenvolvedores

  • Há suporte apenas para os aplicativos C# e C++/WinRT.
  • Os aplicativos da área de trabalho têm suporte no .NET 6 (e posterior) e C# 9 e devem ser empacotados em um aplicativo MSIX.
  • Não há suporte para Designer XAML.
  • Não há suporte para novos aplicativos C++/CX, mas os aplicativos existentes continuarão funcionando (mude para o C++/WinRT assim que possível).
  • Não há suporte para implantação na área de trabalho não empacotada.
  • Ao executar um aplicativo da área de trabalho usando o F5, verifique se você está usando o projeto de empacotamento. Pressionar F5 no projeto de aplicativo executará um aplicativo não empacotado, ao qual o WinUI 3 ainda não dá suporte.

Recursos de plataforma ausentes

  • Suporte ao Xbox

  • Suporte ao HoloLens

  • Pop-ups em janelas

    • Mais especificamente, a propriedade ShouldConstrainToRootBounds sempre funciona como se ela tivesse sido definida como true, independentemente do valor da propriedade.

  • Suporte para escrita à tinta, incluindo:

  • Acrílico de fundo

  • MediaElement e MediaPlayerElement

  • MapControl

  • SwapChainPanel não tem suporte para transparência

  • A amostra de AcrylicBrush e outros efeitos que usam um CompositionBackdropBrush não pode ser feita com base em um SwapChainPanel ou WebView2.

  • A Revelação Global usa comportamento de fallback, um pincel sólido

  • Não há suporte para Ilhas XAML nesta versão

  • O uso do WinUI 3 diretamente em um aplicativo da área de trabalho existente que não é do WinUI traz a seguinte limitação: o caminho disponível atualmente para migrar um aplicativo existente é adicionar um novo projeto do WinUI 3 à solução e ajustar ou refatorar a lógica conforme necessário.

  • Application.Suspending não é chamado em aplicativos da área de trabalho. Confira a documentação de referência de API sobre o Evento Application.Suspending para obter mais detalhes.

  • O evento UISettings.ColorValuesChanged e o evento AccessibilitySettings.HighContrastChanged não têm mais suporte em aplicativos da área de trabalho. Isso poderá causar problemas se você estiver usando-o para detectar alterações em temas do Windows.

  • Anteriormente, para obter uma instância de CompositionCapabilities, você chamaria CompositionCapabilites.GetForCurrentView(). No entanto, as funcionalidades retornadas dessa chamada não eram dependentes da exibição. Para resolver e refletir isso, excluímos o GetForCurrentView() estático nesta versão, portanto, agora você pode criar um objeto CompositionCapabilties diretamente.

  • Não há suporte para CoreWindow, ApplicationView, CoreApplicationView, CoreDispatcher e as dependências deles em aplicativos da área de trabalho (confira abaixo)

CoreWindow, ApplicationView, CoreApplicationView e CoreDispatcher em aplicativos da área de trabalho

Novidade no WinUI 3 Versão Prévia 4 que será padrão daqui por diante: CoreWindow, ApplicationView, CoreApplicationViewCoreDispatcher e as dependências deles não estão disponíveis em aplicativos da área de trabalho. Por exemplo, a propriedade Window.Dispatcher é sempre nula, mas a propriedade Window.DispatcherQueue pode ser usada como alternativa.

Essas APIs só funcionam em aplicativos UWP. Nas versões prévias anteriores, elas funcionavam parcialmente em aplicativos da área de trabalho também, mas na Versão Prévia 4, foram desabilitadas totalmente. Essas APIs foram criadas para o caso da UWP em que há apenas uma janela por thread, e um dos recursos do WinUI 3 é habilitar várias delas no futuro.

Há APIs que dependem internamente da existência dessas APIs, o que, consequentemente, não tem suporte em um aplicativo da área de trabalho. Essas APIs geralmente têm um método GetForCurrentView estático. Por exemplo, UIViewSettings.GetForCurrentView.

Para saber mais sobre as APIs afetadas, bem como soluções alternativas e substituições para elas, confira APIs do Windows Runtime sem suporte em aplicativos da área de trabalho.

Problemas conhecidos

  • Você poderá receber um erro de build devido a versões incompatíveis do SDK do .NET e do winrt.runtime.dll. Para solucionar esse problema, tente o seguinte:

    Defina explicitamente o SDK do .NET para a versão correta. Para determinar a versão correta do seu aplicativo, localize a marca <TargetFramework> no arquivo de projeto. Usando o número de build do SDK do Windows que seu aplicativo aponta como o destino na marca <TargetFramework> (como 18362 ou 19041), adicione o seguinte item ao arquivo de projeto e salve o projeto:

    <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>

    Observe que essa solução alternativa é necessária para o SDK do .NET 5.0.203 e anterior, mas não será necessária para o SDK do .NET 5.0.204 ou 5.0.300.

  • Durante o uso do Visual Studio 2019 16.10 Preview 2, a Árvore Visual Dinâmica pode causar uma falha. Para evitar isso, atualize para a versão mais recente do Visual Studio 2019 16.10 Versão Prévia.

  • Os botões de legenda do Windows podem estar no local errado quando SetTitleBar não está definido ou está definido como nulo

Confira na Galeria de Controles do WinUI 3 (chamada anteriormente de Galeria de Controles XAML – versão WinUI 3) um aplicativo de exemplo que inclui todos os controles e recursos que fazem parte do WinUI 3 – Project Reunion 0.8 Versão Prévia.

WinUI 3 Controls Gallery app
Exemplo do aplicativo da Galeria de Controles do WinUI 3

O aplicativo da Galeria de Controles do WinUI 3 está disponível por meio da Microsoft Store.

Você também pode baixar o exemplo clonando o repositório do GitHub. Para fazer isso, clone o branch winui3 usando o seguinte comando:

Observação

Também há um branch winui3preview neste repositório do GitHub que fornece uma versão da Galeria de Controles do WinUI 3 que está usando o WinUI 3 – Project Reunion 0.8 Versão Prévia.

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

Após a clonagem, mude para o branch winui3 no ambiente do Git local:

git checkout winui3

Confira também