Ferramentas de design de runtime XAML para WinUI 3

Visual Studio inclui um conjunto de ferramentas de runtime que permitem projetar, iterar e inspecionar o XAML do WinUI 3 enquanto o aplicativo está em execução. Usados juntos, eles fornecem um loop rápido de edição-recarga-inspeção que mostra sua interface do usuário real — estilos reais, modelos de dados reais, animações reais — em vez de uma aproximação estática.

Observação

O Visual Studio Designer XAML (a guia Design de arrastar e soltar) atualmente não dá suporte a projetos WinUI 3. Se você abriu um .xaml arquivo e vê apenas o editor XML, sua instalação não está interrompida. O designer não está disponível para WinUI 3. A solicitação de recurso é acompanhada na Developer Community: Adicionar suporte ao Designer XAML para aplicativos da área de trabalho do WinUI 3. Para obter informações sobre o esforço de engenharia, consulte a discussão do WindowsAppSDK nº 4710.

As ferramentas de runtime descritas neste artigo são valiosas se um designer está disponível ou não. Este artigo percorre o fluxo de trabalho.

O que você usará

Tool O que faz Como abri-lo
Recarga Dinâmica de XAML Aplica alterações de XAML ao aplicativo em execução sem reiniciá-lo Automático — editar qualquer arquivo .xaml durante a depuração
Árvore visual dinâmica Mostra a árvore de elementos de runtime completo e permite selecionar elementos no aplicativo Depuração>Windows>Árvore Visual Dinâmica
Gerenciador de Propriedades Dinâmicas Exibe e permite editar todas as propriedades no elemento selecionado em runtime Depuração>Windows>Explorador de Propriedades Dinâmicas
Visualização ao vivo do XAML Renderiza seu aplicativo em execução dentro de Visual Studio para que você possa inspecionar sem alternar janelas Depuração>Windows>Visualização Dinâmica do XAML

Tip

Acople Live Visual Tree e Live Property Explorer lado a lado. Juntos, eles oferecem uma exibição de inspeção detalhada que mostra valores reais de runtime.

Prerequisites

  • Visual Studio 2022 versão 17.0 ou posterior (XAML Recarga Dinâmica e Live Visual Tree estão incluídos).
  • Um projeto WinUI 3 usando o SDK do Aplicativo Windows. Consulte Criar e executar um projeto WinUI 3 para criar um.
  • Seu projeto deve ter como destino o .NET 6 ou posterior (C#) ou usar C++/WinRT.

Etapa 1: Iniciar seu aplicativo no depurador

Pressione F5 (ou Depurar>Iniciar Depuração). O Recarga Dinâmica XAML é ativado automaticamente quando o depurador se conecta.

A barra de ferramentas Recarga Dinâmica XAML é exibida na sobreposição no aplicativo. Se você não vir isso, confira se a configuração está ativada:

  1. Vá até Ferramentas>>>.
  2. Confirme se Habilitar Recarga Dinâmica do XAML está marcada.

Importante

O XAML Recarga Dinâmica requer o depurador. A execução sem depuração (Ctrl+F5) desabilita Recarga Dinâmica, Árvore Visual Dinâmica e Gerenciador de Propriedades Dinâmicas.

Etapa 2: Editar XAML e ver as alterações instantaneamente

Com o aplicativo em execução, mude para qualquer arquivo .xaml no editor e faça uma alteração — por exemplo, mude uma cor Background ou adicione um novo Button. O aplicativo em execução é atualizado em um ou dois segundos, sem reiniciar.

O que Recarga Dinâmica pode ou não fazer

Recarga Dinâmica manipula as edições mais comuns:

  • Adicionar, remover ou reordenar elementos
  • Alterando valores de propriedades (cores, margens, texto, tamanhos)
  • Adicionando ou modificando estilos e dicionários de recursos
  • Alterando o conteúdo do modelo de dados

Algumas alterações exigem uma reinicialização:

  • Adicionando novas classes, manipuladores de eventos no code-behind ou alterações em x:Class
  • Modificando App.xaml dicionários mesclados (às vezes)
  • Alterando x:Bind expressões que fazem referência a novas propriedades

Quando Recarga Dinâmica não pode aplicar uma alteração, a barra de ferramentas mostra uma notificação. Basta reiniciar o aplicativo para pegar essas alterações.

Para obter mais informações, consulte Recarga Dinâmica XAML.

Etapa 3: Inspecionar a árvore visual e as propriedades

Abra a janela Live Visual Tree (Debug>Windows>Live Visual Tree). Esta janela mostra todos os elementos na árvore da interface do usuário do seu aplicativo em execução, organizados por relações pai-filho.

Selecionar elementos visualmente

  1. Na barra de ferramentas Árvore Visual Dinâmica, habilite Selecionar Elemento no Aplicativo em Execução (o botão de mira).
  2. Clique em qualquer elemento em seu aplicativo em execução – a árvore navega até esse elemento e o Gerenciador de Propriedades Dinâmicas mostra suas propriedades.

Este é o equivalente, em tempo de execução, a clicar em um elemento em uma superfície de design, com a diferença de que ele reflete exatamente o que seu aplicativo renderiza, incluindo elementos criados dinamicamente no código.

Editar propriedades em runtime

No Gerenciador de Propriedades Dinâmicas, você pode alterar valores de propriedade em tempo real. Por exemplo:

  • Altere um Margin para ajustar o espaçamento e ver o efeito imediatamente.
  • Defina Visibility para Collapsed testar o que acontece quando um elemento está oculto.
  • Ajuste Width ou Height para testar layouts responsivos.

Essas edições de runtime não são salvas de volta no arquivo XAML. Elas são para experimentação. Depois de encontrar valores que você gosta, digite-os em seu .xaml arquivo (em que Recarga Dinâmica os pega e os torna permanentes).

Etapa 4: Usar o XAML Live Preview

O XAML Live Preview renderiza seu aplicativo em execução dentro de uma guia Visual Studio, para que você possa exibir o aplicativo e sua origem XAML lado a lado sem alternar janelas.

Para abri-lo: Depurar>Windows>XAML Live Preview.

Isso é especialmente útil em configurações de monitor único em que Alt-Tabbing entre o aplicativo e Visual Studio é inconveniente.

Para obter mais informações, consulte XAML Live Preview.

Recomendado: criar uma página de playground de interface do usuário

Crie uma página de playground dedicada em seu projeto , uma página cuja única finalidade é permitir que você experimente controles, estilos e layouts. Isso oferece um scratchpad que está sempre pronto para iteração visual e combina especialmente bem com as ferramentas de runtime acima.

Configurar o playground

  1. Clique com o botão direito do mouse no seu projeto no Gerenciador de Soluções e selecione Adicionar>Novo Item>Página em Branco (WinUI 3). Nomeie como UIPlayground.xaml.

  2. In UIPlayground.xaml, adicione um ScrollViewer com seções para cada controle ou padrão que você deseja experimentar:

    <Page
    x:Class="MyApp.UIPlayground"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <ScrollViewer Padding="24">
        <StackPanel Spacing="24">

            <!-- Section: Buttons -->
            <TextBlock Text="Buttons" Style="{StaticResource SubtitleTextBlockStyle}"/>
            <StackPanel Orientation="Horizontal" Spacing="8">
                <Button Content="Standard"/>
                <Button Content="Accent" Style="{StaticResource AccentButtonStyle}"/>
                <ToggleButton Content="Toggle"/>
                <HyperlinkButton Content="Link" NavigateUri="https://learn.microsoft.com"/>
            </StackPanel>

            <!-- Section: Text input -->
            <TextBlock Text="Text input" Style="{StaticResource SubtitleTextBlockStyle}"/>
            <TextBox PlaceholderText="Type here..." Width="300" HorizontalAlignment="Left"/>
            <PasswordBox PlaceholderText="Password" Width="300" HorizontalAlignment="Left"/>

            <!-- Add more sections as needed -->

        </StackPanel>
    </ScrollViewer>
</Page>

  3. Torne o playground fácil de alcançar. Durante o desenvolvimento, defina-o como a página de inicialização em App.xaml.cs:

    // In App.xaml.cs, OnLaunched method — swap in for quick playground access:
// rootFrame.Navigate(typeof(UIPlayground));

    Ou, se o seu app usar um NavigationView, adicione um item de menu que apareça apenas em compilações de depuração. Por exemplo, no code-behind da janela principal:

    // In your main window or shell page constructor, after InitializeComponent():
#if DEBUG
    NavView.MenuItems.Add(new NavigationViewItem
    {
        Content = "UI Playground",
        Tag = typeof(UIPlayground)
    });
#endif

    onde NavView é o x:Name do seu controle NavigationView.

Como usar o playground

  1. Pressione F5 para iniciar o aplicativo e navegue até a página do playground.
  2. Abra o arquivo .xaml ao lado do aplicativo em execução (ou use o XAML Live Preview).
  3. Adicionar ou modificar controles no editor XAML — Recarga Dinâmica envia alterações por push instantaneamente.
  4. Use a Árvore Visual Dinâmica para clicar em controles renderizados e inspecionar seus valores reais de layout no Live Property Explorer.
  5. Quando estiver satisfeito com a aparência de um controle, copie o XAML para sua página real.

Esse padrão proporciona um ciclo de "type-reload-inspect" e, como executa código real, você vê templates de dados reais, estilos reais e animações reais.

Comparando abordagens em tempo de design e em tempo de execução

Veja como as tarefas comuns de design da interface do usuário são mapeadas para as ferramentas de runtime:

Task Ferramenta de runtime
Adicionar um controle à página Digite o elemento XAML — o IntelliSense completa a tag e as propriedades obrigatórias
Visualizar o controle Veja isso em tempo real no aplicativo em execução com o Recarga Dinâmica
Selecione um elemento para inspecionar Use Live Visual Tree> (mira)
Exibir ou editar propriedades Usar Live Property Explorer
Ajustar tamanho ou posição Editar Width, Height, Margin em XAML ou no Explorador de Propriedades Dinâmicas

Dicas para um fluxo de trabalho eficiente

  • Use o aplicativo Da Galeria do WinUI 3. Instale-o do Microsoft Store ou compile-o de GitHub. Ele mostra todos os controles WinUI 3 com exemplos interativos e XAML pronto para cópia. Pense nele como um catálogo visual que você pode procurar antes de escrever XAML.
  • Mantenha a página do playground aberta. Trate-o como um guia de estilo de vida para seu aplicativo.
  • Use d:DesignHeight e d:DesignWidth. Mesmo sem o designer, esses atributos ajudam o IntelliSense e mantêm suas páginas em um tamanho consistente quando você as abre no editor.
  • Combinar com a janela de Falhas de Vinculação do XAML. Abra-o de Depurar>Windows>Falhas de AssociaçãoXAML para detectar erros de associação que o designer nunca teria mostrado a você.
  • Use o kit de ferramentas da comunidade. O Kit de Ferramentas da Comunidade Windows fornece controles e auxiliares que reduzem a quantidade de layout que você precisa para codificar manualmente.

Conteúdo relacionado

  • Last updated on