.NET MAUI TwoPaneView 布局

项目
02/25/2025

TwoPaneView 类表示一个带有两个视图的容器，这些视图会调整内容的大小且在可用空间内并排或按从上到下的顺序放置内容。 TwoPaneView 继承自 Grid，因此考虑这些属性时最简单的方式是看作它们要应用于网格。

Surface Duo dual-screen emulator showing a basic TwoPaneView test app

布局控件由 Microsoft.Maui.Controls.Foldable NuGet 包提供。

可折叠设备支持概述

可折叠设备包括来自其他制造商的 Microsoft Surface Duo 和 Android 设备。它们弥合了手机和大屏幕（如平板电脑和台式机）之间的差距，因为应用可能需要调整适应同一设备上的各种屏幕大小和方向，包括适应屏幕中的铰链或折叠。

请访问双屏开发人员文档，了解有关生成面向可折叠设备的应用的详细信息，包括设计模式和用户体验。还可以下载适用于 Windows、Mac 和 Linux 的 Surface Duo Emulator。

重要

TwoPaneView 控件仅适应支持 Google 提供的 Jetpack Window Manager API 的 Android 可折叠设备（如 Microsoft Surface Duo）。

在所有其他平台和设备（例如其他 Android 设备、iOS、macOS、Windows）上，它就像可配置且响应迅速的拆分视图一样，可以动态显示一两个窗格，并按比例在屏幕上调整大小。

添加和配置可折叠支持 NuGet

为解决方案打开“NuGet 包管理器”对话框。
在“浏览”选项卡下，搜索 Microsoft.Maui.Controls.Foldable。
将 Microsoft.Maui.Controls.Foldable 包安装到你的解决方案中。

在 CreateMauiApp 方法中，将 UseFoldable() 初始化方法（和命名空间）调用添加到项目的 MauiApp 类：

using Microsoft.Maui.Foldable; // ADD THIS NAMESPACE
...
public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    ...
    builder.UseFoldable(); // ADD THIS LINE TO THE TEMPLATE
    return builder.Build();
}

必须进行 UseFoldable() 初始化，应用才能检测到应用状态的更改，例如横跨折叠的屏幕。

更新 Platforms/Android 中 MainActivity 类上的 [Activity(...)] 属性，使其包括所有这些ConfigurationChanges选项：
```
ConfigurationChanges = ConfigChanges.Orientation | ConfigChanges.ScreenSize
    | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize | ConfigChanges.UiMode
```
必须有这些值才能更可靠地报告配置更改和范围状态以获得可靠的双屏幕支持。

设置 TwoPaneView

要将 TwoPaneView 布局添加到页面，请执行以下操作：

为可折叠 NuGet 添加 foldable 命名空间别名：

xmlns:foldable="clr-namespace:Microsoft.Maui.Controls.Foldable;assembly=Microsoft.Maui.Controls.Foldable"

在页面上添加 TwoPaneView 作为根元素，并将控件添加到 Pane1 和 Pane2：

<foldable:TwoPaneView x:Name="twoPaneView">
    <foldable:TwoPaneView.Pane1
        BackgroundColor="#dddddd">
        <Label
            Text="Hello, .NET MAUI!"
            SemanticProperties.HeadingLevel="Level1"
            FontSize="32"
            HorizontalOptions="Center" />
    </foldable:TwoPaneView.Pane1>
    <foldable:TwoPaneView.Pane2>
        <StackLayout BackgroundColor="{AppThemeBinding Light={StaticResource Secondary}, Dark={StaticResource Primary}}">
            <Label Text="Pane2 StackLayout"/>
        </StackLayout>
    </foldable:TwoPaneView.Pane2>
</foldable:TwoPaneView>

了解 TwoPaneView 模式

只有其中一个模式可处于活动状态：

SinglePane 当前只有一个窗格可见。
Wide：这两个窗格按水平布局。一个窗格位于左侧，另一个窗格位于右侧。当位于两个屏幕上时，这是设备纵向显示时的模式。
Tall：这两个窗格按垂直布局。一个窗格位于顶部，另一个窗格位于底部。当位于两个屏幕上时，这是设备横向显示时的模式。

当仅在一个屏幕上时控制 TwoPaneView

当 TwoPaneView 占用单个屏幕时，将应用以下属性：

MinTallModeHeight 指示控件进入 Tall 模式所必需的最小高度。
MinWideModeWidth 指示控件进入 Wide 模式所必需的最小宽度。
Pane1Length 在 Wide 模式中设置 Pane1 的宽度，在 Tall 模式中设置 Pane1 的高度，在 SinglePane 模式下不起作用。
Pane2Length 在 Wide 模式中设置 Pane2 的宽度，在 Tall 模式中设置 Pane2 的高度，在 SinglePane 模式下不起作用。

重要

如果 TwoPaneView 横跨铰链或折叠，则这些属性不起作用。

在一个或两个屏幕上时应用的属性

当 TwoPaneView 占用一个或两个屏幕时，将应用以下属性：

TallModeConfiguration 指明是处于 Tall 模式（上/下排列方式），还是只想一个窗格可见（如 TwoPaneViewPriority 所定义）。
WideModeConfiguration 指明是处于 Wide 模式（左/右排列方式），还是只想一个窗格可见（如 TwoPaneViewPriority 所定义）。
PanePriority 确定是显示 Pane1 还是 Pane2（如果在 SinglePane 模式下）。

疑难解答

如果 TwoPaneView 布局未按预期工作，请仔细检查此页面上的设置说明。省略或错误地配置 UseFoldable() 方法或 ConfigurationChanges 属性值是导致错误的常见原因。

通过