共用方式為

.NET MAUI 視窗

  • 發行項

.NET 多平台應用程式 UI （.NET MAUI） Window 類別可讓您建立、設定、顯示及管理多個視窗。

Window 會定義下列屬性：

  • FlowDirection型 FlowDirection別為 的 ，定義視窗 UI 元素配置的方向。
  • Height型 double別為 的 ，指定 Windows 上視窗的高度。
  • MaximumHeight型 double別為 的 ，代表桌面平台上視窗的最大高度。 有效值介於 0 和 double.PositiveInfinity之間。
  • MaximumWidth型 double別為 的 ，代表桌面平台上視窗的最大寬度。 有效值介於 0 和 double.PositiveInfinity之間。
  • MinimumHeight型 double別為 的 ，代表桌面平臺上視窗的最小高度。 有效值介於 0 和 double.PositiveInfinity之間。
  • MinimumWidth型 double別為 的 ，代表桌面平臺上視窗的最小寬度。 有效值介於 0 和 double.PositiveInfinity之間。
  • Overlays型 IReadOnlyCollection<IWindowOverlay>別為 的 ，表示視窗重疊的集合。
  • Page型 Page別為 的 ，表示視窗所顯示的頁面。 這個屬性是 類別的內容屬性 Window ，因此不需要明確設定。
  • Title型 string別為 的 ，表示視窗的標題。
  • Width型 double別為 的 ，指定 Windows 上視窗的寬度。
  • X類型 double為 的 ，指定 Windows 上視窗的 X 座標。
  • Y類型 double為 的 ，指定 Windows 上視窗的 Y 座標。

除了 屬性之外 Overlays ，這些屬性是由 BindableProperty 物件所支援，這表示這些屬性可以是數據系結的目標，並設定樣式。

類別 Window 會定義下列事件：

  • Created，會在建立窗口時引發。
  • Resumed，會在視窗從睡眠狀態繼續時引發。
  • Activated，會在啟動窗口時引發。
  • Deactivated，會在停用窗口時引發。
  • Stopped，會在視窗停止時引發。
  • Destroying，在終結窗口時引發。
  • SizeChanged，當視窗變更大小時，會在桌面平台上引發。
  • Backgrounding，具有隨附 BackgroundingEventArgs 的物件，當視窗關閉或進入背景狀態時，會在iOS和Mac Catalyst上引發。 此事件可用來將任何 string 狀態保存至 State 物件的 屬性 BackgroundingEventArgs ，OS 將保留到繼續窗口為止。 當視窗繼續時，狀態會透過 IActivationState 自變數 CreateWindow 提供給方法。
  • DisplayDensityChanged，具有隨附 DisplayDensityChangedEventArgs 的物件，當視窗的有效點每英吋 （DPI） 變更時，會在Android和 Windows 上引發。

如需生命週期事件及其相關覆寫的詳細資訊，請參閱 應用程式生命週期。

類別 Window 也會定義下列強制回應導覽事件：

  • ModalPopped，使用 ModalPoppedEventArgs，當檢視已以強制回應方式彈出時引發。
  • ModalPopping，若為 ModalPoppingEventArgs，當檢視已強制回應時，就會引發此檢視。
  • ModalPushed，具有 ModalPushedEventArgs，在強制推送檢視之後引發。
  • ModalPushing，使用 ModalPushingEventArgs，會在強制推送檢視時引發。
  • PopCanceled，會在取消強制回應快顯時引發。

類別 VisualElement 具有 Window 公開父 Window 對象的屬性。 您可以從任何頁面、版面配置或檢視存取這個屬性，以操作 Window 物件。

建立視窗

根據預設，當您將 MainPage 屬性設定為 Page 類別中的 App 物件時，.NET MAUI 會Window建立 物件。 不過，您也可以覆寫 CreateWindow 類別 App 中的 方法，以建立 Window 物件：

namespace MyMauiApp
{
    public partial class App : Application
    {
        public App()
        {
            InitializeComponent();

            MainPage = new MainPage();
        }

        protected override Window CreateWindow(IActivationState activationState)
        {
            Window window = base.CreateWindow(activationState);

            // Manipulate Window object

            return window;
        }
    }
}

雖然 類別 Window 具有預設建構函式和接受 Page 自變數的建構函式，其代表應用程式的根頁面，您也可以呼叫基底 CreateWindow 方法以傳回 .NET MAUI 建立 Window 的物件。

根據預設，您的 .NET MAUI 應用程式會 CreateWindow 覆寫 類別 App 中的 方法，以建立 Window 物件：

namespace MyMauiApp
{
    public partial class App : Application
    {
        public App()
        {
            InitializeComponent();
        }

        protected override Window CreateWindow(IActivationState? activationState)
        {
            return new Window(new AppShell());
        }
    }
}

類別 Window 具有預設建構函式，以及接受 Page 自變數的建構函式，代表應用程式的根頁面。

此外，您也可以建立自己的 Window衍生物件：

namespace MyMauiApp
{
    public class MyWindow : Window
    {
        public MyWindow() : base()
        {
        }

        public MyWindow(Page page) : base(page)
        {
        }

        // Override Window methods
    }
}

Window接著，您可以在 類別App的CreateWindow覆寫中建立 MyWindow 物件，以取用衍生類別。

無論您的物件建立方式 Window 為何，它都會是應用程式中根頁面的父代。

多窗口支援

您可以在 Android、iPad 上的 iOS、iPad 上的 iOS、Mac Catalyst 和 Windows 上同時開啟多個視窗。 建立物件並使用 物件上的 Application 方法加以開啟OpenWindow，即可達成Window此目的：

Window secondWindow = new Window(new MyPage());
Application.Current?.OpenWindow(secondWindow);

型Application.Current.Windows別的 IReadOnlyList<Window> 集合會維護向 Application 對象註冊之所有Window對象的參考。

您可以使用 方法，將特定視窗帶到 Mac Catalyst 和 Windows Application.Current.ActivateWindow 上：

Application.Current?.ActivateWindow(secondWindow);

您可以使用 方法關閉 Application.Current.CloseWindow Windows：

// Close a specific window
Application.Current?.CloseWindow(secondWindow);

// Close the active window
Application.Current?.CloseWindow(GetParentWindow());

重要

多視窗支援可在 Windows 上運作，而不需要額外的設定。 不過，Android、iPadOS 和 Mac Catalyst 需要額外的設定。

Android 設定

若要在 Android 上使用多視窗支援，您必須將 Android > > MainActivity.cs 平臺中的LaunchMode.SingleTop啟動模式從 變更MainActivity為 LaunchMode.Multiple：

using Android.App;
using Android.Content.PM;
using Android.OS;

namespace MyMauiApp;

[Activity(Theme = "@style/Maui.SplashTheme", MainLauncher = true, LaunchMode = LaunchMode.Multiple, ...)]
public class MainActivity : MauiAppCompatActivity
{
}

iPadOS 和macOS設定

若要在 iPadOS 和 Mac Catalyst 上使用多窗口支援，請將名為 SceneDelegate 的類別新增至 平臺 > iOS 和 平臺 > MacCatalyst 資料夾：

using Foundation;
using Microsoft.Maui;
using UIKit;

namespace MyMauiApp;

[Register("SceneDelegate")]
public class SceneDelegate : MauiUISceneDelegate
{
}

然後，在 XML 編輯器中，開啟 [平臺 iOS > Info.plist] 檔案和 [平臺>>] MacCatalyst > Info.plist 檔案，並將下列 XML 新增至每個檔案的結尾：

<key>UIApplicationSceneManifest</key>
<dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <true/>
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneConfigurationName</key>
        <string>__MAUI_DEFAULT_SCENE_CONFIGURATION__</string>
        <key>UISceneDelegateClassName</key>
        <string>SceneDelegate</string>
      </dict>
    </array>
  </dict>
</dict>

重要

多視窗支援不適用於 iPhone 的 iOS。

定位和調整視窗大小

視窗的位置和大小可以透過在 Windows 上設定 X、 Y、 Width和 Height 屬性，以程式設計方式為 Windows 上的 Window .NET MAUI 應用程式定義。

警告

Mac Catalyst 不支援藉由設定 X、 Y、 Width和 Height 屬性，以程式設計方式調整或重新置放視窗。

例如，若要在啟動時設定視窗位置和大小，您應該覆寫 CreateWindow 類別App中的方法，並在 對象上Window設定X、 YWidth和 Height 屬性：

public partial class App : Application
{
    public App()
    {
        InitializeComponent();
    }

    protected override Window CreateWindow(IActivationState activationState) =>
        new Window(new AppShell())
        {
            Width = 700,
            Height = 500,
            X = 100,
            Y = 100
        };
}

或者，從任何頁面、版面配置或檢視存取 Window 屬性，即可定位及調整視窗大小。 例如，下列程式代碼示範如何將視窗放置在畫面中央：

// Get display size
var displayInfo = DeviceDisplay.Current.MainDisplayInfo;

// Center the window
Window.X = (displayInfo.Width / displayInfo.Density - Window.Width) / 2;
Window.Y = (displayInfo.Height / displayInfo.Density - Window.Height) / 2;

如需取得裝置螢幕計量的相關信息，請參閱 裝置顯示資訊。

Mac Catalyst

Mac Catalyst 不支援以程序設計方式重設大小或重新定位視窗。 不過，啟用重設大小的因應措施是將 和 MaximumWidth 屬性設定為所需的窗口寬度，並將 MinimumHeight 和 MaximumHeight 屬性設定MinimumWidth為所需的視窗高度。 這會觸發重設大小，然後您可以將屬性還原回其原始值：

Window.MinimumWidth = 700;
Window.MaximumWidth = 700;
Window.MinimumHeight = 500;
Window.MaximumHeight = 500;

// Give the Window time to resize
Dispatcher.Dispatch(() =>
{
    Window.MinimumWidth = 0;
    Window.MinimumHeight = 0;
    Window.MaximumWidth = double.PositiveInfinity;
    Window.MaximumHeight = double.PositiveInfinity;
});

從 App 類別分離視窗管理

視窗管理可以 App 藉由建立實作 介面的 IWindowCreator 類別，並在方法中 CreateWindow 新增視窗管理程序代碼，以分離類別：

public class WindowCreator : IWindowCreator
{
    public Window CreateWindow(Application app, IActivationState activationState)
    {
        var window = new Window(new ContentPage
        {
            Content = new Grid
            {
                new Label
                {
                    Text = "Hello from IWindowCreator",
                    HorizontalOptions = LayoutOptions.Center,
                    VerticalOptions = LayoutOptions.Center
                }
            }
        });

        return window;
    }
}

然後，在類別中 MauiProgram ，您應該在應用程式的服務容器中將視窗管理類型註冊為相依性：

builder.Services.AddSingleton<IWindowCreator, WindowCreator>();

重要

請確定您的註冊程式代碼會 IWindowCreator 指定介面及其具體類型。

然後，請確定您的 App 類別未設定 MainPage 屬性：

public partial class App : Application
{
    public App()
    {
        InitializeComponent();
    }
}

如果 IWindowCreator 介面及其具體類型已向應用程式的服務容器註冊，而且 MainPage 未設定 類別的 屬性，則會使用已註冊的類型 Application 來建立 Window。