Painéis de layout

Os painéis de layout são contêineres que permitem organizar e agrupar elementos da interface do usuário no aplicativo. Os painéis de layout XAML internos incluem RelativePanel, StackPanel, Grid, VariableSizedWrapGrid e Canvas. Aqui, descrevemos cada painel e mostramos como usá-lo para fazer o layout de elementos da interface do usuário XAML.

Há várias coisas a considerar ao escolher um painel de layout:

• Como o painel posiciona seus elementos filho.
• Como o painel dimensiona seus elementos filho.
• Como os elementos filho sobrepostos são colocados em camadas uns sobre os outros (ordem z).
• O número e a complexidade dos elementos do painel aninhado necessários para criar o layout desejado.

Exemplos

Galeria WinUI 2
	Se você tiver o aplicativo Galeria do WinUI 2 instalado, consulte o RelativePanel, o StackPanel, o Grid, o VariableSizedWrapGrid e o Canvas em ação. Obtenha o aplicativo WinUI 2 Gallery (Microsoft Store) Obtenha o código-fonte (GitHub)

Propriedades do painel

Antes de falarmos sobre cada painel, abordaremos algumas propriedades comuns que todos eles têm.

Propriedades anexadas ao painel

A maioria dos painéis de layout XAML usa propriedades anexadas para permitir que seus elementos filho informem o painel pai sobre como eles devem ser posicionados na interface do usuário. As propriedades anexadas usam a sintaxe AttachedPropertyProvider.PropertyName. Se você tiver painéis aninhados dentro de outros painéis, as propriedades anexadas em elementos de interface do usuário que especificam características de layout para um pai serão interpretadas apenas pelo painel pai mais imediato.

Aqui está um exemplo de como você pode definir a propriedade anexada Canvas.Left em um controle Button em XAML. Isso informa ao Canvas pai que o Button deve ser posicionado a 50 pixels efetivos da borda esquerda do Canvas.

<Canvas>
  <Button Canvas.Left="50">Hello</Button>
</Canvas>

Para obter mais informações sobre propriedades anexadas, consulte Visão geral das propriedades anexadas.

Bordas do painel

Os painéis RelativePanel, StackPanel e Grid definem propriedades de borda que permitem desenhar uma borda ao redor do painel sem envolvê-las em um elemento Border adicional. As propriedades de borda são BorderBrush, BorderThickness, CornerRadius e Padding.

Aqui está um exemplo de como definir propriedades de borda em uma Grid.

<Grid BorderBrush="Blue" BorderThickness="12" CornerRadius="12" Padding="12">
    <TextBlock Text="Hello World!"/>
</Grid>

O uso das propriedades de borda internas reduz a contagem de elementos XAML, o que pode melhorar o desempenho da interface do usuário do seu aplicativo. Para obter mais informações sobre painéis de layout e desempenho da interface do usuário, consulte Otimizar seu layout XAML.

RelativePanel

RelativePanel permite dispor os elementos da interface do usuário especificando onde eles devem ficar em relação a outros elementos e em relação ao painel. Por padrão, um elemento é posicionado no canto superior esquerdo do painel. Use RelativePanel com VisualStateManager e AdaptiveTrigger para reorganizar a interface do usuário para diferentes tamanhos de janela.

Esta tabela mostra as propriedades anexadas que você pode usar para alinhar um elemento em relação ao painel e a outros elementos.

Alinhamento do painel	Alinhamento entre irmãos	Posição de irmão
AlignTopWithPanel	AlignTopWith	Above
AlignBottomWithPanel	AlignBottomWith	Below
AlignLeftWithPanel	AlignLeftWith	LeftOf
AlignRightWithPanel	AlignRightWith	RightOf
AlignHorizontalCenterWithPanel	AlignHorizontalCenterWith
AlignVerticalCenterWithPanel	AlignVerticalCenterWith

Este XAML mostra como organizar elementos em um RelativePanel.

<RelativePanel BorderBrush="Gray" BorderThickness="1">
    <Rectangle x:Name="RedRect" Fill="Red" Height="44" Width="44"/>
    <Rectangle x:Name="BlueRect" Fill="Blue"
               Height="44" Width="88"
               RelativePanel.RightOf="RedRect" />

    <Rectangle x:Name="GreenRect" Fill="Green" 
               Height="44"
               RelativePanel.Below="RedRect" 
               RelativePanel.AlignLeftWith="RedRect" 
               RelativePanel.AlignRightWith="BlueRect"/>
    <Rectangle Fill="Orange"
               RelativePanel.Below="GreenRect" 
               RelativePanel.AlignLeftWith="BlueRect" 
               RelativePanel.AlignRightWithPanel="True"
               RelativePanel.AlignBottomWithPanel="True"/>
</RelativePanel>

O resultado é assim.

Estes são alguns aspectos a serem observados sobre o dimensionamento dos retângulos:

• O retângulo vermelho recebe um tamanho explícito de 44x44. Ele é colocado no canto superior esquerdo do painel, que é a posição padrão.
• O retângulo verde recebe uma altura explícita de 44. Seu lado esquerdo está alinhado com o retângulo vermelho e seu lado direito está alinhado com o retângulo azul, que determina sua largura.
• O retângulo laranja não recebe um tamanho explícito. Seu lado esquerdo está alinhado com o retângulo azul. Suas bordas direita e inferior estão alinhadas com a borda do painel. Seu tamanho é determinado por esses alinhamentos e será redimensionado à medida que o painel for redimensionado.

StackPanel

StackPanel organiza os elementos filho em apenas uma linha que pode ser orientada horizontal ou verticalmente. Normalmente, O StackPanel é usado para organizar uma pequena subseção da interface do usuário em uma página.

Você pode usar a propriedade Orientation para especificar a direção dos elementos filho. A orientação padrão é Vertical.

O XAML a seguir mostra como criar um StackPanel vertical de itens.

<StackPanel>
    <Rectangle Fill="Red" Height="44"/>
    <Rectangle Fill="Blue" Height="44"/>
    <Rectangle Fill="Green" Height="44"/>
    <Rectangle Fill="Orange" Height="44"/>
</StackPanel>

O resultado é assim.

Em um StackPanel, se o tamanho de um elemento filho não for definido explicitamente, ele se estenderá para preencher a largura disponível (ou altura se a Orientação for Horizontal). Neste exemplo, a largura dos retângulos não é definida. Os retângulos se expandem para preencher toda a largura do StackPanel.

Grid

O painel Grid dá suporte a layouts fluidos e permite organizar controles em layouts com várias linhas e várias colunas. Especifique as linhas e colunas de um painel Grid usando as propriedades RowDefinitions e ColumnDefinitions.

Para posicionar objetos em células específicas do Grid, use as propriedades anexadas Grid.Column e Grid.Row.

Para distribuir o conteúdo em várias linhas e colunas, use as propriedades anexadas Grid.RowSpan e Grid.ColumnSpan.

Este exemplo XAML mostra como criar uma Grid com duas linhas e duas colunas.

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition/>
        <RowDefinition Height="44"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="Auto"/>
        <ColumnDefinition/>
    </Grid.ColumnDefinitions>
    <Rectangle Fill="Red" Width="44"/>
    <Rectangle Fill="Blue" Grid.Row="1"/>
    <Rectangle Fill="Green" Grid.Column="1"/>
    <Rectangle Fill="Orange" Grid.Row="1" Grid.Column="1"/>
</Grid>

O resultado é assim.

Neste exemplo, o dimensionamento funciona assim:

• A segunda linha tem uma altura explícita de 44 pixels efetivos. Por padrão, a altura da primeira linha preenche o espaço restante.
• A largura da primeira coluna é definida como Automático, portanto, é tão larga quanto necessário para seus filhos. Nesse caso, tem 44 pixels efetivos de largura para acomodar a largura do retângulo vermelho.
• Não há outras restrições de tamanho nos retângulos, então cada um se estende para preencher a célula da grade em que está.

Você pode distribuir o espaço dentro de uma coluna ou linha usando o dimensionamento automático ou em estrela. Use o dimensionamento automático para permitir que os elementos da interface do usuário sejam redimensionados para caber no conteúdo ou no contêiner pai. Você também pode usar o dimensionamento automático com as linhas e colunas de uma grade. Para usar o dimensionamento automático, defina a Altura e/ou Largura dos elementos da interface do usuário como Automático.

Você usa o dimensionamento proporcional, também chamado de dimensionamento em estrela, para distribuir o espaço disponível entre as linhas e colunas de uma grade por proporções ponderadas. Em XAML, os valores de estrela são expressos como * (ou n* para dimensionamento de estrela ponderado). Por exemplo, para especificar que uma coluna é 5 vezes mais larga que a segunda coluna em um layout de 2 colunas, use "5*" e "*" para as propriedades Width nos elementos ColumnDefinition.

Este exemplo combina dimensionamento fixo, automático e proporcional em uma Grid com 4 colunas.

Coluna	Dimensionamento	Descrição
Column_1	Auto	A coluna será dimensionada para caber em seu conteúdo.
Column_2	*	Depois que as colunas Auto são calculadas, a coluna obtém parte da largura restante. Column_2 terá metade da largura de Column_4.
Column_3	44	A coluna terá 44 pixels de largura.
Column_4	2*	Depois que as colunas Auto são calculadas, a coluna obtém parte da largura restante. Column_4 será duas vezes mais largo que Column_2.

A largura padrão da coluna é "*", portanto, você não precisa definir explicitamente esse valor para a segunda coluna.

<Grid>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="Auto"/>
        <ColumnDefinition/>
        <ColumnDefinition Width="44"/>
        <ColumnDefinition Width="2*"/>
    </Grid.ColumnDefinitions>
    <TextBlock Text="Column 1 sizes to its content." FontSize="24"/>
</Grid>

No designer XAML do Visual Studio, o resultado tem esta aparência.

VariableSizedWrapGrid

VariableSizedWrapGrid é um painel de layout em estilo de grade no qual as linhas ou as colunas são encapsuladas automaticamente em uma nova linha ou coluna quando o valor MaximumRowsOrColumns é atingido.

A propriedade Orientation especifica se a grade adiciona seus itens em linhas ou colunas antes de quebrar. A orientação padrão é Vertical, o que significa que a grade adiciona itens de cima para baixo até que uma coluna esteja cheia e, em seguida, quebra em uma nova coluna. Quando o valor é Horizontal, a grade adiciona itens da esquerda para a direita e, em seguida, quebra em uma nova linha.

As dimensões da célula são especificadas por ItemHeight e ItemWidth. Cada célula tem o mesmo tamanho. Se ItemHeight ou ItemWidth não for especificado, a primeira célula será dimensionada para ajustar seu conteúdo e todas as outras células terão o tamanho da primeira célula.

Você pode usar as propriedades anexadas VariableSizedWrapGrid.ColumnSpan e VariableSizedWrapGrid.RowSpan para especificar quantas células adjacentes um elemento filho deve preencher.

Veja como usar um VariableSizedWrapGrid em XAML.

<VariableSizedWrapGrid MaximumRowsOrColumns="3" ItemHeight="44" ItemWidth="44">
    <Rectangle Fill="Red"/>
    <Rectangle Fill="Blue" 
               VariableSizedWrapGrid.RowSpan="2"/>
    <Rectangle Fill="Green" 
               VariableSizedWrapGrid.ColumnSpan="2"/>
    <Rectangle Fill="Orange" 
               VariableSizedWrapGrid.RowSpan="2" 
               VariableSizedWrapGrid.ColumnSpan="2"/>
</VariableSizedWrapGrid>

O resultado é assim.

Neste exemplo, o número máximo de linhas em cada coluna é 3. A primeira coluna contém apenas 2 itens (os retângulos vermelho e azul) porque o retângulo azul se estende por 2 linhas. O retângulo verde então se enrola no topo da próxima coluna.

Tela

O painel Tela posiciona os elementos filho usando pontos de coordenada fixos e não dá suporte a layouts fluidos. Você especifica os pontos em elementos filho individuais definindo as propriedades Canvas.Left e Canvas.Top anexadas em cada elemento. A tela pai lê os valores dessas propriedades anexadas de seus filhos durante o cálculo do layout Arrange.

Os objetos em uma tela podem se sobrepor, onde um objeto é desenhado em cima de outro objeto. Por padrão, o Canvas renderiza objetos filho na ordem em que são declarados, de modo que o último filho é renderizado na parte superior (cada elemento tem um z-index padrão de 0). Isso é o mesmo que outros painéis embutidos. No entanto, o Canvas também dá suporte à propriedade anexada Canvas.ZIndex que você pode definir em cada um dos elementos filho. Você pode definir essa propriedade no código para alterar a ordem de desenho dos elementos durante o tempo de execução. O elemento com o valor Canvas.ZIndex mais alto é desenhado por último e, portanto, desenha sobre quaisquer outros elementos que compartilham o mesmo espaço ou se sobrepõem de alguma forma. Observe que o valor alfa (transparência) é respeitado, portanto, mesmo que os elementos se sobreponham, o conteúdo mostrado nas áreas de sobreposição pode ser mesclado se o superior tiver um valor alfa não máximo.

O Canvas não faz nenhum dimensionamento de seus filhos. Cada elemento deve especificar seu tamanho.

Aqui está um exemplo de um Canvas em XAML.

<Canvas Width="120" Height="120">
    <Rectangle Fill="Red" Height="44" Width="44"/>
    <Rectangle Fill="Blue" Height="44" Width="44" Canvas.Left="20" Canvas.Top="20"/>
    <Rectangle Fill="Green" Height="44" Width="44" Canvas.Left="40" Canvas.Top="40"/>
    <Rectangle Fill="Orange" Height="44" Width="44" Canvas.Left="60" Canvas.Top="60"/>
</Canvas>

O resultado é assim.

Use o painel Canvas com discrição. Embora seja conveniente poder controlar com precisão as posições dos elementos na interface do usuário para alguns cenários, um painel de layout posicionado fixo faz com que essa área da interface do usuário seja menos adaptável às alterações gerais de tamanho da janela do aplicativo. O redimensionamento da janela do aplicativo pode vir de alterações de orientação do dispositivo, janelas de aplicativos divididas, alteração de monitores e vários outros cenários de usuário.

Painéis para ItemsControl

Há vários painéis de finalidade especial que podem ser usados apenas como um ItemsPanel para exibir itens em um ItemsControl. Eles são ItemsStackPanel, ItemsWrapGrid, VirtualizingStackPanel e WrapGrid. Você não pode usar esses painéis para layout geral da interface do usuário.

Obter o código de exemplo

• Amostra de WinUI 2 Gallery: veja todos os controles XAML em um formato interativo.