版面配置面板

版面配置面板是允許您在應用程式中排列和群組 UI 元素的容器。 內建的 XAML 配置面板包括 RelativePanel、StackPanel、Grid、VariableSizedWrapGrid 和 Canvas。 在這裡，我們說明每個面板，並示範如何使用這些面板來配置 XAML UI 元素。

選擇配置面板時需要考慮以下幾點：

• 面板如何放置其子專案。
• 面板如何調整其子元素的大小。
• 重疊的子元素如何分層 (z 順序)。
• 建立配置所需之嵌套面板元素的數量和複雜度。

範例

WinUI 2 Gallery
	如果您已安裝 WinUI 2 資源庫 應用程式，請參閱 RelativePanel、StackPanel、Grid、VariableSizedWrapGrid、Canvas 實際操作。 取得 WinUI 2 資源庫應用程式 (Microsoft Store) 取得原始程式碼 (GitHub)

面板屬性

討論個別面板之前，先看看所有面板都會有的一些常見屬性。

面板附加屬性

大多數 XAML 配置面板會使用附加屬性，讓其子元素告知父面板它們應如何如何放置在 UI 中。 附加屬性使用語法 AttachedPropertyProvider.PropertyName。 如果您的面板嵌套在其他面板中，則 UI 元素上指定父系配置特性的附加屬性僅由最直接的父面板解釋。

以下範例說明如何在 XAML 的 Button 控制項上設定 Canvas.Left 附加屬性。 這會通知父 Canvas 該 Button 應放置在距 Canvas 左邊緣 50 個有效像素的位置。

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

有關附加屬性的詳細資訊，請參閱附加屬性概觀。

面板框線

relativePanel、StackPanel 和 Grid 面板定義框線屬性，讓您可以在面板周圍繪製框線，而無需將它們包裝在額外的 Border 元素中。 框線屬性包括 BorderBrush、BorderThickness、CornerRadius 和 Padding。

以下是如何在 Grid 上設定框線屬性的範例。

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

使用內建框線屬性可以減少 XAML 元素數量，從而提高應用程式的 UI 效能。 有關配置面板和 UI 效能的詳細資訊，請參閱最佳化 XAML 配置。

RelativePanel \(英文\)

RelativePanel 可讓您藉由為 UI 元素指定相對於其他元素和相對於面板的位置，為其進行版面配置。 預設情況下，元素會位於面板的左上角。 您可以使用 RelativePanel 搭配 VisualStateManager 和 AdaptiveTrigger，針對不同的視窗大小重新排列 UI。

下表顯示的附加屬性可用來將元素與面板或其他元素對齊。

面板對齊方式	同層級對齊	同層級位置
AlignTopWithPanel	AlignTopWith	Above
AlignBottomWithPanel	AlignBottomWith	Below
AlignLeftWithPanel	AlignLeftWith	LeftOf
AlignRightWithPanel	AlignRightWith	RightOf
AlignHorizontalCenterWithPanel	AlignHorizontalCenterWith
AlignVerticalCenterWithPanel	AlignVerticalCenterWith

此 XAML 示範如何排列 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>

結果如下所示。

以下是調整矩形大小時應注意的一些事項：

• 紅色矩形的明確大小為 44x44。 它會放在面板的左上角，這是預設位置。
• 綠色矩形的明確高度為 44。 其左側會與紅色矩形對齊，右側與藍色矩形對齊，以決定其寬度。
• 並未針對橘色矩形指定明確的大小。 其左側會與藍色矩形對齊。 其右邊緣和下邊緣與面板的邊緣對齊。 其大小由這些對齊方式決定，並且會隨著面板調整大小而進行調整。

StackPanel \(英文\)

StackPanel 將其子元素按水平或垂直方向排列到單行中。 StackPanel 通常用來排列頁面上 UI 的小型子區段。

您可以使用 Orientation 屬性來指定子元素的方向。 預設方向為垂直。

以下 XAML 顯示如何建立項目的垂直 StackPanel。

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

結果如下所示。

在 StackPanel 中，如果未明確設定子元素的大小，它會延展以填滿可用寬度 (如果方向為水平，則填滿高度)。 在此範例中，未設定矩形的寬度。 矩形將延展以填滿 StackPanel 的整個寬度。

方格

Grid 面板支援可變式版面配置並允許您在多列與多欄版面配置中排列控制項。 使用 RowDefinitions 和 ColumnDefinitions 屬性指定 Grid 的列與欄。

使用 Grid.Column 和 Grid.Row 附加屬性，將物件放置在 Grid 的特定儲存格中。

使用 Grid.RowSpan 和 Grid.ColumnSpan 附加屬性將內容延伸到多個列與欄。

此 XAML 範例示範如何建立具有兩列和兩欄的方格。

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

結果如下所示。

在此範例中，大小調整的運作方式如下：

• 第二列的明確高度為 44 個有效像素。 預設情況下，第一列的高度會填滿剩餘的空間。
• 第一欄的寬度設定為 Auto，因此其寬度會根據其子系的需要而定。 在本例中，其寬度為 44 個有效像素，以容納紅色矩形的寬度。
• 這些矩形沒有其他大小限制，因此每個矩形都會延展以填滿其所在的方格資料格。

您可以使用自動或星形調整大小來指派欄或列內的空間。 您可以使用自動調整大小來調整 UI 元素的大小，以符合其內容或父容器。 您也可以使用格線的列和欄自動調整大小。 若要使用自動調整大小，請將 UI 元素的高度和/或寬度設為自動。

您可以使用比例調整 (也稱為星號調整) 來依照加權比例，在方格的列和欄之間分配可用空間。 在 XAML 中，星號值的表示方法為 * (加權星號調整則為 n *)。 例如，若要在 2 欄的版面配置中，將某一欄的寬度設定為第二欄的 5 倍，請使用 "5*" 與 "*" 來表示 ColumnDefinition 元素中的 Width 屬性。

此範例會在 4 欄的格線中結合固定、自動和等比例調整大小。

資料行	調整大小	描述
欄 1	Auto	列會根據其內容調整大小。
欄 2	*	計算出自動欄之後，欄會取得剩餘寬度的一部分。 「欄 2」的寬度將是「欄 4」的二分之一。
欄 3	44	該欄的寬度為 44 像素。
欄 4	2*	計算出自動欄之後，欄會取得剩餘寬度的一部分。 「欄 4」的寬度是「欄 2」的兩倍。

預設欄寬為「*」，因此不需要為第二欄明確設定此值。

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

在 Visual Studio XAML 設計工具中，結果看起來會如下所示。

VariableSizedWrapGrid \(英文\)

VariableSizedWrapGrid 是方格樣式的版面配置面板，其中列或欄在達到 MaximumRowsOrColumns 值時會自動換行到新列或新欄。

Orientation 屬性指定方格在換行之前是否將其項目新增至列或欄。 預設方向為 Vertical，這代表方格會從上到下新增項目，直到一欄填滿，然後換到新欄。 當值為 Horizontal 時，方格會從左到右新增項目，然後換到新列。

資料格大小由 ItemHeight 和 ItemWidth 指定。 每個資料格的大小都一樣。 如果未指定 ItemHeight 或 ItemWidth，則第一個資料格的大小會符合其內容，且其他所有資料格的大小均為第一個資料格的大小。

您可以使用 VariableSizedWrapGrid.ColumnSpan 和 VariableSizedWrapGrid.RowSpan 附加屬性來指定子元素應填滿的相鄰資料格數量。

以下是在 XAML 中使用 VariableSizedWrapGrid 的方法。

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

結果如下所示。

在此範例中，每欄的最大列數為 3。 第一欄僅包含 2 個項目 (紅色和藍色矩形)，因為藍色矩形跨越 2 列。 然後綠色矩形會換行到下一欄的頂端。

畫布

Canvas 面板使用固定座標點定位子元素，且不支援可變式版面配置。 您可以透過在每個元素上設定 Canvas.Left 和 Canvas.Top 附加屬性來指定各個子元素上的點。 在版面配置的 Arrange 階段，父項 Canvas 會從其子系讀取這些附加屬性值。

Canvas 中的物件可以重疊，其中一個物件繪製在另一個物件之上。 預設情況下，Canvas 會按照宣告的順序轉譯子對象，因此最後一個子對象會在頂端轉譯 (每個元素的預設 z 索引為 0)。 這與其他內建面板相同。 但是，Canvas 也支援 Canvas.ZIndex 附加屬性，您可以在每個子元素上設定該屬性。 您可以在程式碼中設定此屬性，以在執行階段變更元素的繪製順序。 具有最高 Canvas.ZIndex 值的元素最後繪製，因此會繪製在共用相同空間或以任何方式重疊的任何其他元素上。 請注意，其會遵守 Alpha 值 (透明度)，因此即使元素重疊，如果頂端元素的 Alpha 值並非最大，重疊區域中顯示的內容可能會混合。

Canvas 不會對其子系進行任何大小調整。 每個元素都必須指定其大小。

以下是 XAML 中的 Canvas 範例。

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

結果如下所示。

請謹慎使用 Canvas 面板。 雖然在某些情況下能夠精確控制 UI 中元素的位置很方便，但固定位置的配置面板會導致 UI 的該區域無法適應整個應用程式視窗大小的變化。 應用程式視窗大小調整可能來自裝置方向變更、分割應用程式視窗、變更顯示器，以及許多其他使用者場景。

ItemsControl 的面板

有幾個特殊用途的面板只能當作 ItemsPanel 來顯示 ItemsControl 中的項目。 它們是 ItemsStackPanel、ItemsWrapGrid、VirtualizingStackPanel 和 WrapGrid。 您不能將這些面板用於一般 UI 配置。

取得範例程式碼

• WinUI 2 資源庫範例 - 以互動式格式查看所有 XAML 控制項。