Gerenciar janelas do aplicativo (SDK do Aplicativo Windows)

  • Artigo

Este tópico contém uma seção de exemplo de código .

O SDK do Aplicativo Windows fornece a classe Microsoft.UI.Windowing.AppWindow fácil de usar. AppWindow é independente de estrutura e está disponível para todos os aplicativos do Windows, incluindo Win32, WPF e WinForms. Você pode contrastar a natureza independente da estrutura do AppWindow com Microsoft.UI.Xaml.Window, que é a classe de janela especificamente para a estrutura WinUI 3. AppWindow também é uma evolução do Windows.UI.WindowManagement.AppWindow do Plataforma Universal do Windows (UWP).

A versão SDK do Aplicativo Windows do Microsoft.UI.Windowing.AppWindow não depende de padrões assíncronos e fornece comentários imediatos ao seu aplicativo sobre se as chamadas à API foram bem-sucedidas. No futuro, quando se trata de introduzir novos recursos, integrar-se à interface do usuário/UX do Windows e habilitar novos cenários de janelas, as APIs de janela SDK do Aplicativo Windows serão o foco. Recomendamos que você comece a aproveitar essas APIs para suas operações de janela.

Consulte também Instalar ferramentas para o SDK do Aplicativo Windows, Criar seu primeiro projeto WinUI 3 e Usar o SDK do Aplicativo Windows em um projeto existente.

A classe AppWindow

Microsoft.UI.Windowing.AppWindow é uma API de janelas de alto nível que permite cenários de janelas fáceis de usar. O AppWindow integra-se bem à interface do usuário/UX do Windows e a outros aplicativos.

AppWindow representa uma abstração de alto nível de um contêiner gerenciado pelo sistema para o conteúdo de um aplicativo. É o contêiner no qual o conteúdo está hospedado; e representa a entidade com a qual os usuários interagem quando redimensionam e movem seu aplicativo na tela. Se você estiver familiarizado com o Win32, a "janela do aplicativo" poderá ser vista como uma abstração de alto nível do HWND. Se você estiver familiarizado com a UWP, a "janela do aplicativo" poderá ser vista como uma substituição para CoreWindow/ApplicationView/Windows.UI.WindowManagement.AppWindow.

Para a versão SDK do Aplicativo Windows do Microsoft.UI.Windowing.AppWindow, estamos dando suporte apenas a HWNDsde nível superior. Há um mapeamento 1:1 entre um AppWindow e um HWND de nível superior.

O tempo de vida de um objeto AppWindow e um HWND é o mesmo: o AppWindow está disponível imediatamente após a criação da janela; e é destruída quando a janela é fechada.

A classe AppWindowPresenter e as subclasses

Cada AppWindow tem um AppWindowPresenter (apresentador) aplicado a ele. Se você for um desenvolvedor UWP que trabalhou com Windows.UI.WindowManagement.AppWindow, isso será familiar; mesmo que não seja um mapeamento 1:1 de funcionalidade e comportamento. Consulte também Consulte Migração da funcionalidade de janelas.

Como um novo conceito para o modelo de aplicativo Win32, um apresentador é semelhante a (mas não o mesmo que) uma combinação de estado e estilos de janela. Alguns apresentadores também têm comportamentos de interface do usuário/experiência do usuário definidos neles que não são inspecionáveis do estado clássico da janela e das propriedades de estilo (como uma barra de título de ocultação automática).

Por padrão, um apresentador é criado pelo sistema e aplicado a um AppWindow no momento da criação. No SDK do Aplicativo Windows 1.0 Estável, na área de trabalho do Windows, o tipo de apresentador é OverlappedPresenter, que é uma subclasse de AppWindowPresenter. Não há necessidade de seu aplicativo escondê-lo, nem manter uma referência a ele para voltar ao apresentador padrão para uma janela depois de ter aplicado outro apresentador. Isso ocorre porque o sistema mantém a mesma instância desse apresentador durante o tempo de vida do AppWindow para o qual ele foi criado; e seu aplicativo pode reaplica-lo chamando o método AppWindow.SetPresenter com AppWindowPresenterKind.Default como um parâmetro.

Um apresentador pode ser aplicado a apenas uma única janela de cada vez. Tentar aplicar o mesmo apresentador a uma segunda janela gera uma exceção. Isso significa que, se você tiver várias janelas e quiser alternar cada uma delas para um modo de apresentação específico, precisará criar vários apresentadores do mesmo tipo e, em seguida, aplicar cada uma à sua própria janela.

Alguns apresentadores têm funcionalidades que permitem que um usuário faça alterações fora do próprio controle do aplicativo. Quando essa alteração acontece, seu aplicativo é notificado por um evento AppWindow.Changed no AppWindow afetado, com a propriedade AppWindowChangedEventArgs.DidPresenterChange definida truecomo . Em seguida, seu aplicativo deve inspecionar a propriedade do apresentador aplicado para ver o que mudou.

O apresentador aplicado é um objeto ao vivo. Uma alteração em qualquer propriedade do objeto AppWindow.Presenter entra em vigor imediatamente.

Um apresentador não pode ser destruído enquanto ele é aplicado a uma janela. Para destruir um objeto de apresentador, primeiro aplique um objeto de apresentador diferente à janela; dessa forma, o apresentador que você pretende destruir é removido da janela. Você pode fazer isso aplicando outro apresentador específico à janela ou chamando o método AppWindow.SetPresenter com AppWindowPresenterKind.Default como um argumento, que reaplicará o apresentador padrão criado pelo sistema para a janela. Se você tiver mantido uma referência ao apresentador criado pelo sistema para a janela, ela será válida neste ponto (ou seja, a instância que foi criada pela primeira vez para a janela será aplicada novamente).

Apresentadores disponíveis

Esses apresentadores derivados de AppWindowPresenter são fornecidos e estão disponíveis em todas as versões do sistema operacional com suporte.

  • CompactOverlayPresenter. Cria uma janela sempre na parte superior de um tamanho fixo, com uma taxa de proporção de 16:9 para permitir experiências semelhantes à imagem na imagem.
  • FullScreenPresenter. Permite que uma janela entre em uma experiência de tela inteira.
  • OverlappedPresenter. O apresentador padrão criado pelo sistema, que permite solicitar e reagir para minimizar/maximizar/restaurar operações e alterações de estado.

Estrutura de interface do usuário e interoperabilidade HWND

A classe AppWindow está disponível para qualquerHWND de nível superior em seu aplicativo. Isso significa que, quando você estiver trabalhando com uma estrutura de interface do usuário da área de trabalho (incluindo o WinUI 3), poderá continuar a usar o ponto de entrada dessa estrutura para criar uma janela e anexar seu conteúdo. E depois de criar uma janela com essa estrutura de interface do usuário, você pode usar as funções de interoperabilidade de janela (veja abaixo) fornecidas no SDK do Aplicativo Windows para acessar o AppWindow correspondente e seus métodos, propriedades e eventos.

C#. Os wrappers do .NET para as funções de interoperabilidade de janela são implementados como métodos da classe Microsoft.UI.Win32Interop . Consulte também Chamar APIs de interoperabilidade de um aplicativo .NET.

C++. As funções de interoperabilidade são definidas no arquivo de cabeçalho winrt/Microsoft.ui.interop.h .

A seção Exemplo de código abaixo mostra o código-fonte real; mas aqui está a receita para recuperar um objeto AppWindow dada uma janela existente:

  1. Recupere o HWND para o objeto de janela existente (para sua estrutura de interface do usuário), se você ainda não o tiver.
  2. Passe esse HWND para a função de interoperabilidade GetWindowIdFromWindow para recuperar um WindowId.
  3. Passe essa WindowId para o método estático AppWindow.GetFromWindowId para recuperar o AppWindow.

Alguns dos benefícios de usar o AppWindow (mesmo ao trabalhar com uma estrutura de interface do usuário) são:

  • Personalização fácil da barra de título; que, por padrão, mantém a interface do usuário do Windows 11 (cantos arredondados, submenu de grupo de ajuste).
  • Experiências de sobreposição compacta e de tela inteira fornecidas pelo sistema (imagem em imagem).
  • Windows Runtime superfície de API (WinRT) para alguns dos principais conceitos de janelas do Win32.

Exemplo de código

Este exemplo de código demonstra como recuperar um AppWindow de uma janela do WinUI 3. Para usar o exemplo, crie um novo projeto Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho) e cole o código.

C#. O exemplo de código usa as classes WinRT.Interop.WindowNative e Microsoft.UI.Win32Interop (consulte Chamar APIs de interoperabilidade de um aplicativo .NET). Consulte também Recuperar um identificador de janela (HWND).

Para obter detalhes adicionais sobre como trabalhar com o AppWindow, consulte o exemplo da Galeria de janelas.

// MainWindow.xaml.cs
private void myButton_Click(object sender, RoutedEventArgs e)
{
    // Retrieve the window handle (HWND) of the current (XAML) WinUI 3 window.
    var hWnd =
        WinRT.Interop.WindowNative.GetWindowHandle(this);

    // Retrieve the WindowId that corresponds to hWnd.
    Microsoft.UI.WindowId windowId =
        Microsoft.UI.Win32Interop.GetWindowIdFromWindow(hWnd);

    // Lastly, retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft.UI.Windowing.AppWindow appWindow =
        Microsoft.UI.Windowing.AppWindow.GetFromWindowId(windowId);

    if (appWindow != null)
    {
        // You now have an AppWindow object, and you can call its methods to manipulate the window.
        // As an example, let's change the title text of the window.
        appWindow.Title = "Title text updated via AppWindow!";
    }
}

// pch.h
#include "microsoft.ui.xaml.window.h" // For the IWindowNative interface.
#include <winrt/Microsoft.UI.Interop.h> // For the WindowId struct and the GetWindowIdFromWindow function.
#include <winrt/Microsoft.UI.Windowing.h> // For AppWindow::GetFromWindowId

// mainwindow.xaml.cpp
void MainWindow::myButton_Click(IInspectable const&, RoutedEventArgs const&)
{
    // Retrieve the window handle (HWND) of the current (XAML) WinUI 3 window.
    auto windowNative{ this->try_as<::IWindowNative>() };
    winrt::check_bool(windowNative);
    HWND hWnd{ 0 };
    windowNative->get_WindowHandle(&hWnd);

    // Retrieve the WindowId that corresponds to hWnd.
    Microsoft::UI::WindowId windowId = 
        Microsoft::UI::GetWindowIdFromWindow(hWnd);

    // Lastly, retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft::UI::Windowing::AppWindow appWindow = 
        Microsoft::UI::Windowing::AppWindow::GetFromWindowId(windowId);

    if (appWindow)
    {
        // You now have an AppWindow object, and you can call its methods to manipulate the window.
        // As an example, let's change the title text of the window.
        appWindow.Title(L"Title text updated via AppWindow!");
    }
}

Limitações

  • O AppWindow está disponível apenas para aplicativos da área de trabalho (empacotados e não empacotados); não está disponível para aplicativos UWP.
  • Atualmente, o SDK do Aplicativo Windows não fornece métodos para anexar o conteúdo da estrutura da interface do usuário a um AppWindow. Você está limitado a usar os métodos de acesso de interoperabilidade HWND demonstrados na seção Exemplo de código .
  • Atualmente, a personalização titleBar só tem suporte em Windows 11 ou versões posteriores. Confira Personalização da barra de título para obter detalhes.