Ferramentas de design em tempo de execução XAML para WinUI 3

O Visual Studio inclui um conjunto de ferramentas de execução que lhe permitem desenhar, iterar e inspecionar o seu XAML do WinUI 3 enquanto a sua aplicação está a correr. Usados em conjunto, dão-lhe um ciclo rápido de edição-recarga-inspeção que mostra a sua interface real — estilos reais, modelos de dados reais, animações reais — em vez de uma aproximação estática.

Nota

O Visual Studio XAML Designer (o separador de Design de arrastar e largar) não suporta atualmente projetos WinUI 3. Se abriu um .xaml ficheiro e só vê o editor XML, a sua instalação não está avariada — o designer não está disponível para o WinUI 3. O pedido de funcionalidade é acompanhado no Developer Community: Adicionar suporte ao XAML Designer para aplicações desktop do WinUI 3. Para obter contexto relativamente ao esforço de engenharia, consulte a discussão #4710 do WindowsAppSDK.

As ferramentas de execução descritas neste artigo são valiosas, esteja ou não disponível um designer. Este artigo explica o fluxo de trabalho.

O que vais usar

Tool O que faz Como abrir
XAML Hot Reload Aplica alterações XAML na aplicação em execução sem reiniciar Automático — editar qualquer ficheiro .xaml ao depurar
Árvore Visual em Tempo Real Mostra a árvore completa de elementos em tempo de execução e permite selecionar elementos na aplicação Depuração>Windows>
Explorador de Propriedades Vivas Mostra e permite editar todas as propriedades do elemento selecionado em tempo de execução Depurar>Windows>
Pré-visualização em direto do XAML Apresenta a tua aplicação em execução no Visual Studio para que a possas inspecionar sem alternar entre janelas Depuração>Windows>

Gorjeta

Dock Live Visual Tree e Live Property Explorer lado a lado. Em conjunto, dão-lhe uma vista de inspeção detalhada que mostra os valores reais em tempo de execução.

Prerequisites

  • Visual Studio 2022 versão 17.0 ou posterior (XAML Hot Reload e Live Visual Tree estão incluídos).
  • Um projeto WinUI 3 usando o SDK de Aplicações Windows. Veja Criar e executar um projeto WinUI 3 para criar um.
  • O seu projeto deve direcionar-se para .NET 6 ou posterior (C#) ou usar C++/WinRT.

Passo 1: Inicie a sua aplicação sob o depurador

Pressiona F5 (ou Debug>Start Debug). O XAML Hot Reload ativa-se automaticamente quando o depurador se liga.

A barra de ferramentas XAML Hot Reload aparece na sobreposição dentro da aplicação. Se não o vires, verifica se a definição está ativada:

  1. Aceda a Ferramentas>Opções>>XAML Hot Reload.
  2. Confirme que Enable XAML Hot Reload está selecionada.

Importante

O XAML Hot Reload necessita do depurador. Executar sem depuração (Ctrl+F5) desativa o Hot Reload, o Live Visual Tree e o Live Property Explorer.

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

Com a sua aplicação a funcionar, mude para qualquer .xaml ficheiro no editor e faça uma alteração — por exemplo, altere uma Background cor ou adicione uma nova Button. A aplicação de corrida atualiza em um ou dois segundos, sem reiniciar.

O que o Hot Reload pode e não pode fazer

O Hot Reload trata das edições mais comuns:

  • Adicionar, remover ou reordenar elementos
  • Alterar valores de propriedades (cores, margens, texto, tamanhos)
  • Adição ou modificação de estilos e dicionários de recursos
  • Alteração do conteúdo dos modelos de dados

Algumas alterações exigem um reinício:

  • Adicionar novas classes, processadores de eventos no código subjacente ou alterações x:Class
  • Modificação App.xaml de dicionários fundidos (por vezes)
  • Alterar x:Bind expressões que referenciam novas propriedades

Quando o Hot Reload não consegue aplicar uma alteração, a barra de ferramentas mostra uma notificação. Basta reiniciar a aplicação para detetar essas alterações.

Para mais informações, consulte XAML Hot Reload.

Passo 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 da árvore de interface da sua aplicação em execução, organizados por relações pai-filho.

Selecionar elementos visualmente

  1. Na barra de ferramentas Live Visual Tree , ativa Select Element na Aplicação em Execução (o botão da mira).
  2. Clique em qualquer elemento da sua aplicação em execução — a árvore navega para esse elemento e o Live Property Explorer mostra as respetivas propriedades.

Isto é o equivalente em tempo de execução a clicar num elemento numa superfície de design, exceto que reflete exatamente o que a sua aplicação renderiza, incluindo elementos criados dinamicamente em código.

Editar propriedades em tempo de execução

No Live Property Explorer, pode alterar os valores das propriedades em tempo real. Por exemplo:

  • Muda a Margin para ajustar o espaçamento e vê o efeito imediatamente.
  • Define Visibility para Collapsed testar o que acontece quando um elemento está oculto.
  • Ajuste Width ou Height para testar layouts responsivos.

Estas edições em tempo de execução não são guardadas no teu ficheiro XAML — são para experimentação. Quando encontrares valores de que gostas, escreve-os no teu .xaml ficheiro (onde o Hot Reload os detém e os torna permanentes).

Passo 4: Usar a Pré-visualização ao Vivo de XAML

XAML Live Preview apresenta a sua aplicação em execução num separador do Visual Studio, para que possa ver a aplicação e o seu código XAML lado a lado sem ter de alternar entre janelas.

Para o abrir: Debug>Windows>XAML Live Preview.

Isto é especialmente útil em configurações com um único monitor, em que alternar com Alt+Tab entre a aplicação e o Visual Studio é pouco prático.

Para mais informações, consulte a Pré-visualização ao Vivo de XAML.

Recomendado: Criar uma página de UI playground

Crie uma página dedicada ao playground no seu projeto — uma página cujo único propósito é permitir-lhe experimentar controlos, estilos e layouts. Isto dá-te um scratchpad que está sempre pronto para iteração visual, e combina especialmente bem com as ferramentas de runtime acima.

Montar o parque infantil

  1. Clique com o botão direito do seu projeto no Explorador de Soluções e selecione Adicionar>Novo Item>Página em Branco (WinUI 3). Dê-lhe o nome de UIPlayground.xaml.

  2. Em UIPlayground.xaml, adicione um ScrollViewer com secções para cada controlo ou padrão que queira 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. Torna o parque infantil fácil de alcançar. Durante o desenvolvimento, defina-o como a página de arranque em App.xaml.cs:

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

    Ou, se a tua aplicação usar um NavigationView, adiciona um item de menu que só aparece nas compilações de depuração. Por exemplo, no code-behind da sua 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 controlo NavigationView.

Como usar o parque infantil

  1. Prima F5 para iniciar a aplicação e navegue até à página do playground.
  2. Abra o ficheiro .xaml a par da aplicação em execução (ou utilize a Pré-visualização Dinâmica de XAML).
  3. Adicione ou modifique controlos no editor XAML — o Hot Reload envia alterações instantaneamente.
  4. Use o Live Visual Tree para clicar nos controlos renderizados e inspecionar os seus valores reais de layout no Live Property Explorer.
  5. Quando estiveres satisfeito com o aspeto de um controlo, copia o XAML para a tua página real.

Este padrão dá-te um ciclo de "escrever-recarregar-inspecionar" — e como corre código real, vês modelos de dados reais, estilos reais e animações reais.

Comparação entre abordagens de tempo de projeto e de execução

Aqui está como as tarefas comuns de design de interface se mapeiam para as ferramentas de runtime:

Task Ferramenta de execução
Adicionar um controlo à página Digite o elemento XAML — O IntelliSense completa a etiqueta e as propriedades necessárias
Pré-visualizar o controlo Vê-o em direto na aplicação em execução com Hot Reload
Selecione um elemento a inspecionar Utilize a Live Visual Tree> (retículo)
Visualizar ou editar propriedades Utilize Live Property Explorer
Ajustar tamanho ou posição Editar Width, Height, Margin no XAML ou no Live Property Explorer

Dicas para um fluxo de trabalho eficiente

  • Use a aplicação WinUI 3 Gallery. Instala-o a partir da Microsoft Store ou compila-o a partir do GitHub. Mostra todos os controlos do WinUI 3 com exemplos interativos e XAML pronto para cópia. Pensa nele como um catálogo visual que podes consultar antes de escrever XAML.
  • Mantém a tua página de playground aberta. Trata isto como um guia de estilo vivo para a tua aplicação.
  • Usar d:DesignHeight e d:DesignWidth. Mesmo sem o designer, estes atributos ajudam a IntelliSense e mantêm as suas páginas com um tamanho consistente quando as abre no editor.
  • Combinar com a janela de falhas de associações XAML. Abra-o em DebugWindows>> para detetar erros de associação que o designer nunca lhe teria mostrado.
  • Usa o kit de ferramentas da comunidade. O Windows Community Toolkit fornece controlos e ajudantes que reduzem a quantidade de layout que precisa de programar manualmente.

Conteúdo relacionado

  • Última atualização a