DockLayout

项目
12/22/2023

DockLayout 是一种布局，其中视图可以停靠到布局容器的侧面。

下图从概念上显示了 DockLayout 的结构。子视图停靠在以下 4 个可能的停靠位置之一：顶部、底部、左侧或右侧（等效于 DockPosition.Top、DockPosition.Bottom、DockPosition.Left 和 DockPosition.Right）。未显式停靠（或包含 DockPosition.None）的视图将显示在中心位置（或位于顶部 / 底部和左侧 / 右侧位置之间）。

DockLayout concept

生成 DockLayout

以下部分介绍如何在 C# 和 XAML 中使用 DockLayout。

XAML

包括 XAML 命名空间

若要在 XAML 中使用工具包，需要将以下 xmlns 添加到页面或视图中：

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

因此，以下内容：

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

将被修改为包括 xmlns，如下所示：

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

使用 DockLayout

可以在 XAML 中创建基本 DockLayout，如下所示：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MyProject.MyContentPage">

    <toolkit:DockLayout>
        <Button toolkit:DockLayout.DockPosition="Top" Text="Top" HeightRequest="50" />
        <Button toolkit:DockLayout.DockPosition="Bottom" Text="Bottom" HeightRequest="70" />
        <Button toolkit:DockLayout.DockPosition="Left" Text="Left" WidthRequest="80" />
        <Button toolkit:DockLayout.DockPosition="Right" Text="Right" WidthRequest="90" />
        <Button Text="Center" />
    </toolkit:DockLayout>
    
</ContentPage>

对于左侧 / 右侧停靠，应指定 WidthRequest。对于顶部 / 底部停靠，HeightRequest 将沿停靠方向定义子视图的大小。正交方向始终由 DockLayout 管理器隐式计算。

C#

可以在 C# 中方便地构造 DockLayout，如下所示：

using CommunityToolkit.Maui.Layouts;

var page = new ContentPage
{
    Content = new DockLayout
    {
        { new Button { Text = "Top", HeightRequest = 50 }, DockPosition.Top },
        { new Button { Text = "Bottom", HeightRequest = 70 }, DockPosition.Bottom },
        { new Button { Text = "Left", WidthRequest = 80 }, DockPosition.Left },
        { new Button { Text = "Right", WidthRequest = 90 }, DockPosition.Right },
        { new Button { Text = "Center" } },
    }
};

备注：DockPosition.None 是默认值，可以省略。

设置停靠位置

要在 C# 中设置停靠位置，请使用 DockLayout.SetDockPosition(IView, DockPosition) 应用附加 DockPosition 属性。

var button = new Button { Text = "Top", HeightRequest = 50 };
DockLayout.SetDockPosition(button, DockPosition.Top);

自定义 DockLayout

DockLayout 容器支持使用任意 Padding 以及多个特定于 DockLayout 的属性进行自定义。下面提供了包含所有可用选项的 XAML 示例：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MyProject.MyContentPage">

    <toolkit:DockLayout HeightRequest="400"
                    WidthRequest="600"
                    Padding="10,20,30,40"
                    VerticalSpacing="10"
                    HorizontalSpacing="15"
                    ShouldExpandLastChild="False">
        ...
    </toolkit:DockLayout>
    
</ContentPage>

属性

属性	类型	描述
`Padding`	`Thickness`	获取或设置布局容器周围的填充（继承自 `Layout`）。
`HorizontalSpacing`	`double`	获取或设置停靠视图之间的水平间距。
`VerticalSpacing`	`double`	获取或设置停靠视图之间的垂直间距。
		`HorizontalSpacing` 和 `VerticalSpacing` 应用于 `DockLayout` 中的相邻视图之间。例如，`HorizontalSpacing` 会添加到左侧视图、无视图和右侧视图之间，但也会添加到同一 `DockPosition` 中的相邻视图之间，例如停靠到左侧的多个视图。 `VerticalSpacing` 在顶部、无和底部位置的垂直堆叠视图之间呈现。
`ShouldExpandLastChild`	`bool`	如果为 true，则最后一个子级将展开以填充剩余空间（默认值：`true`）。

其他说明

如果在空间受约束的位置使用 DockLayout（尤其是当通过 HeightRequest 或 WidthRequest 指定了容器大小时），则优先顺序为子视图添加到 DockLayout 容器的顺序。因此，每当没有足够空间呈现所有子视图时，呈现时将删除优先级最低的子视图（最后添加的子视图）。因此，应始终检查容器的大小，确保其至少涵盖其所有子视图的最小大小。

示例

可以在 .NET MAUI 社区工具包示例应用程序中查找 DockLayout 功能的具体示例。

API

可以在 DockLayout 和 DockLayoutManager 中的 .NET MAUI 社区工具包 GitHub 存储库查看 DockLayout 的源代码。

通过