Janelas .NET MAUI

Artigo
11/06/2024

A classe de Window do .NET MAUI (.NET Multi-Platform App UI) fornece a capacidade de criar, configurar, mostrar e gerenciar várias janelas.

Window define as propriedades a seguir:

FlowDirection, do tipo FlowDirection, define a direção na qual o elemento da interface do usuário da janela é disposto.
Height, do tipo double, especifica a altura da janela no Windows.
MaximumHeight, do tipo double, representa a altura máxima da janela em plataformas de área de trabalho. Os valores válidos são de 0 a double.PositiveInfinity.
MaximumWidth, do tipo double, representa a largura máxima da janela em plataformas de área de trabalho. Os valores válidos são de 0 a double.PositiveInfinity.
MinimumHeight, do tipo double, representa a altura mínima da janela em plataformas de área de trabalho. Os valores válidos são de 0 a double.PositiveInfinity.
MinimumWidth, do tipo double, representa a largura mínima da janela em plataformas de área de trabalho. Os valores válidos são de 0 a double.PositiveInfinity.
Overlays, do tipo IReadOnlyCollection<IWindowOverlay>, representa a coleção de sobreposições de janela.
Page, do tipo Page, indica a página que está sendo exibida pela janela. A propriedade é a propriedade de conteúdo da classe Window e, portanto, não precisa ser definida explicitamente.
O Title, do tipo string, representa o título da janela.
Width, do tipo double, especifica a largura da janela no Windows.
X, do tipo double, especifica a coordenada X da janela no Windows.
Y, do tipo double, especifica a coordenada Y da janela no Windows.

Essas propriedades, com exceção da propriedade Overlays, são apoiadas por objetos BindableProperty, o que significa que elas podem ser alvos de associações de dados e estilizadas.

A classe Window define os eventos a seguir:

Created, que é gerado quando a janela é criada.
Resumed, que é gerado quando a janela é retomada de um estado de suspensão.
Activated, que é gerado quando a janela é ativada.
Deactivated, que é gerado quando a janela é desativada.
Stopped, que é gerado quando a janela é interrompida.
Destroying, que é gerada quando a janela é destruída.
SizeChanged, que é gerado em plataformas de área de trabalho quando a janela muda de tamanho.
Backgrounding, com um objeto BackgroundingEventArgs que acompanha, que é gerado no iOS e no Mac Catalyst quando a janela é fechada ou entra em um estado de plano de fundo. Esse evento pode ser usado para persistir qualquer estado string à propriedade State do objeto BackgroundingEventArgs, que o sistema operacional preservará até que seja hora de retomar a janela. Quando a janela é retomada, o estado é fornecido pelo argumento IActivationState para o método CreateWindow.
DisplayDensityChanged, com um objeto DisplayDensityChangedEventArgs que acompanha, que é gerado no Android e no Windows quando os pontos por polegada (DPI) efetivos da janela foram alterados.

Para obter mais informações sobre os eventos do ciclo de vida e suas substituições associadas, consulte Ciclo de vida do aplicativo.

A classe Window também define os seguintes eventos de navegação modal:

ModalPopped, com ModalPoppedEventArgs, que é gerado quando uma exibição é mostrada de forma modal.
ModalPopping, com ModalPoppingEventArgs, que é gerado quando uma exibição é exibida de forma modal.
ModalPushed, com ModalPushedEventArgs, que é gerado quando uma exibição é enviada de forma modal.
ModalPushing, com ModalPushingEventArgs, que é gerado quando uma exibição é enviada de forma modal.
PopCanceled, que é gerado quando uma exibição modal é cancelada.

A classe VisualElement tem uma propriedade Window que expõe o objeto Window pai. Essa propriedade pode ser acessada de qualquer página, layout ou exibição para manipular objetos Window.

Criar uma janela

Por padrão, o .NET MAUI cria um objeto Window quando você define a propriedade MainPage para um objeto Page em sua classe App. No entanto, você também pode substituir o método CreateWindow em sua classe App para criar um objeto 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;
        }
    }
}

Embora a classe Window tenha um construtor padrão e um construtor que aceite um argumento Page, que representa a página raiz do aplicativo, você também pode chamar o método CreateWindow base para retornar o objeto Window .NET MAUI criado.

Por padrão, seu aplicativo .NET MAUI substitui o CreateWindow método em sua App classe para criar um Window objeto:

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

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

A Window classe tem um construtor padrão e um construtor que aceita um Page argumento, que representa a página raiz do aplicativo.

Além disso, você também pode criar seu próprio objeto derivado de Window:

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

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

        // Override Window methods
    }
}

A classe derivada de Windowpode ser consumida criando um objeto MyWindow na substituição CreateWindow na classe App.

Independentemente de como seu objeto Window é criado, ele será o pai da página raiz em seu aplicativo.

Suporte a várias janelas

Várias janelas podem ser abertas simultaneamente no Android, iOS no iPad (iPadOS), Mac Catalyst e Windows. Isso pode ser feito criando um objeto Window e abrindo-o usando o método OpenWindow no objeto Application:

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

A coleção Application.Current.Windows, do tipo IReadOnlyList<Window> mantém referências a todos os objetos Window registrados com o objeto Application.

Uma janela específica pode ser trazida para a frente no Mac Catalyst e no Windows com o método Application.Current.ActivateWindow:

Application.Current?.ActivateWindow(secondWindow);

O Windows pode ser fechado com o método Application.Current.CloseWindow:

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

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

Importante

O suporte a várias janelas funciona no Windows sem configuração adicional. No entanto, é necessária uma configuração adicional no Android, iPadOS e no Mac Catalyst.

Configuração para Android

Para usar o suporte a várias janelas no Android, você deve alterar o modo de inicialização MainActivity em Plataformas > Android > MainActivity.cs de LaunchMode.SingleTop para 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
{
}

Configuração do iPadOS e macOS

Para usar o suporte a várias janelas no iPadOS e no Mac Catalyst, adicione uma classe chamada SceneDelegate às pastas Platforms > iOS e Platforms > MacCatalyst:

using Foundation;
using Microsoft.Maui;
using UIKit;

namespace MyMauiApp;

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

Em seguida, no editor XML, abra o arquivo Platforms > iOS > Info.plist e o arquivo Platforms > MacCatalyst > Info.plist e adicione o seguinte XML ao final de cada arquivo:

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

Importante

O suporte a várias janelas não funciona no iOS para iPhone.

Posicionar e dimensionar uma janela

A posição e o tamanho de uma janela podem ser definidos programaticamente para um aplicativo .NET MAUI no Windows definindo as propriedades X, Y, Width e Height em um objeto Window.

Aviso

O Mac Catalyst não dá suporte ao redimensionamento ou reposicionamento de janelas programaticamente definindo as propriedades X, Y, Width e Height.

Por exemplo, para definir a posição e o tamanho da janela na inicialização, você deve substituir o método CreateWindow em sua classe App e definir as propriedades X, Y, Width e Height em um objeto Window:

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

Como alternativa, uma janela pode ser posicionada e dimensionada acessando a propriedade Window de qualquer página, layout ou exibição. Por exemplo, o código a seguir mostra como posicionar uma janela no centro da tela:

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

Para obter informações sobre como obter as métricas de tela do dispositivo, consulte Informações de exibição do dispositivo.

Catalisador Mac

O Mac Catalyst não dá suporte ao redimensionamento ou reposicionamento de janelas programaticamente. No entanto, uma solução alternativa para habilitar o redimensionamento é definir as propriedades MinimumWidth e MaximumWidth à largura desejada da janela e as propriedades MinimumHeight e MaximumHeight à altura desejada da janela. Isso dispara um redimensionamento e você pode reverter as propriedades para seus valores originais:

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;
});

Desacoplar o gerenciamento de janelas da classe App

O gerenciamento de janelas pode ser dissociado da classe App criando uma classe que implementa a interface IWindowCreator e adicionando o código de gerenciamento de janela no método 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;
    }
}

Em seguida, na classe MauiProgram, você deve registrar o tipo de gerenciamento de janela como uma dependência no contêiner de serviço do aplicativo:

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

Importante

Verifique se o código de registro especifica a interface IWindowCreator, bem como seu tipo concreto.

Em seguida, verifique se a classe App não define a propriedade MainPage:

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

Desde que a interface IWindowCreator e seu tipo concreto tenham sido registrados com o contêiner de serviço do aplicativo e que a propriedade MainPage da classe Application não esteja definida, seu tipo registrado será usado para criar o Window.

Compartilhar via

Janelas .NET MAUI

Criar uma janela

Suporte a várias janelas

Configuração para Android

Configuração do iPadOS e macOS

Posicionar e dimensionar uma janela

Catalisador Mac

Desacoplar o gerenciamento de janelas da classe App

Recursos adicionais