Visão geral de janelas para WinUI e Windows SDK de aplicativo

A funcionalidade de janelas em um aplicativo WinUI é fornecida por uma combinação da classe XAML Window e da AppWindow classe, ambas baseadas no modelo Win32 HWND.

O aplicativo WinUI 3 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 3. Obtenha o aplicativo no da Microsoft Store ou obtenha o código-fonte em do GitHub

XAML Window

Em seu aplicativo, o objeto window é uma instância da classe Microsoft.UI.Xaml.Window (ou uma classe derivada) que representa a janela no código do programa. Cria-o diretamente através de uma chamada ao construtor. O XAML Window é onde você anexa o conteúdo do aplicativo e gerencia o ciclo de vida das janelas do aplicativo.

HWND

A janela doWindows aplicativo é criada pelo sistema operacional e é representada por um objeto de janela Win32. É um contêiner gerenciado pelo sistema no qual seu conteúdo é hospedado e representa a entidade com a qual os usuários interagem quando redimensionam e movem seu aplicativo na tela. (Consulte Sobre Windows na documentação do Win32 para obter mais informações.)

Depois de Windows criar a janela do aplicativo, a função de criação retorna um window handle (HWND) que identifica exclusivamente a janela. A window handle tem o tipo de dados HWND, embora tenha aparecido em C# como um IntPtr. É um identificador opaco para uma estrutura de dados interna Windows que corresponde a uma janela desenhada pelo sistema operativo e que consome recursos do sistema quando presente.

O HWND é criado após o objeto XAML Window, normalmente quando o método Window.Activate é chamado.

AppWindow

O Windows SDK do aplicativo fornece funcionalidade de janela adicional por meio da classe Microsoft.UI.Windowing.AppWindow AppWindow representa uma abstração de alto nível do HWND. Há um mapeamento 1:1 entre um AppWindow e um HWND de nível superior no seu aplicativo. AppWindow e suas classes relacionadas fornecem APIs que permitem gerenciar muitos aspetos das janelas de nível superior do seu aplicativo sem a necessidade de acessar o HWND diretamente.

O tempo de vida de um AppWindow objeto e de um HWND é o mesmo: o AppWindow está disponível imediatamente após a janela ter sido criada e é destruído quando a janela é fechada.

Diagrama de API de janelas

Este diagrama mostra a relação entre as classes e APIs que você usa para gerenciar janelas em seu aplicativo e quais classes são responsáveis por cada parte do gerenciamento de janelas. Em alguns casos, como ExtendsContentIntoTitleBar, a API é um membro do AppWindow para disponibilizar a outras estruturas de interface do usuário, mas é também exposta na classe Window por conveniência. O diagrama não é abrangente, mas mostra as APIs mais comumente usadas.

Window/AppWindow Comparação de API

Se você usar o WinUI 3 XAML como a estrutura da interface do usuário do seu aplicativo, as Window APIs e as AppWindow estarão disponíveis para você. A partir do Windows App SDK 1.4, você pode usar a Windowpropriedade .AppWindow para obter um AppWindow objeto de uma janela XAML existente. Com este AppWindow objeto, você tem acesso às APIs de gerenciamento de janelas adicionais.

Gestão do tempo de vida

Quando você cria um novo projeto WinUI no Visual Studio, o modelo de projeto fornece uma MainWindow classe para você, que é uma subclasse de Window. Se o seu aplicativo só precisa de uma janela, isso é tudo o que você precisa. Para saber como criar e gerenciar janelas adicionais e por que você pode querer, consulte Mostrar várias janelas para seu aplicativo.

A AppWindow classe tem APIs para criar e destruir uma nova janela, no entanto, para um aplicativo WinUI, você não fará isso na prática porque não há API para anexar conteúdo à janela que você cria. Em vez disso, obtém uma instância de AppWindow que é criada pelo sistema e associada a XAML Window e HWND. No WinUI 1.4 e posterior, você pode usar a Windowpropriedade .AppWindow para obter a instância de AppWindow. Em outros casos, pode-se usar o método estático AppWindow.GetFromWindowId para obter a instância de AppWindow. Consulte Gerir janelas de aplicações para obter mais informações.

Content

A propriedade Window.Content é onde se anexa o conteúdo do seu aplicativo à janela que o exibe. Você pode fazer isso em XAML ou em código.

Título, ícone e barra de título

Você pode modificar a barra de título do seu aplicativo em diferentes graus; definir o título e o ícone, alterar as cores ou substituir completamente a barra de título por conteúdo personalizado da aplicação.

Para obter informações sobre como usar APIs da barra de título, incluindo exemplos de código, consulte Personalização da barra de título.

Tamanho e posição

Você utiliza a propriedade Window.Bounds e o evento SizeChanged para gerir elementos na interface do utilizador da aplicação, como mover elementos quando o tamanho da janela altera. XAML usa effective pixels (epx), não pixels físicos reais. Effective pixels são uma unidade de medida virtual e são usados para expressar dimensões de layout e espaçamento, independentemente da densidade da tela.

AppWindow, por outro lado, usa o Window Sistema de Coordenadas, onde a unidade básica de medida são os pixels do dispositivo físico. Você usa as AppWindow APIs para ações de janela, como redimensionar a janela ou movê-la em relação a outra coisa na tela.

Em alguns casos, você pode precisar usar medidas de uma classe na outra classe, caso em que você precisará converter entre effective pixels pixels e dispositivo. Por exemplo, se definires regiões de arrasto numa barra de título personalizada, precisarás de converter medidas. Para obter um exemplo de como usar XamlRoot.RasterizationScale para converter medidas, consulte a seção de conteúdo interativo do artigo de personalização da barra de título .

Aparência e comportamento

As APIs XAML Window geralmente são responsáveis pela aparência do conteúdo do seu aplicativo, como o plano de fundo. Para obter mais informações sobre SystemBackdrop, consulte Aplicar materiais de mica ou acrílico.

AppWindow As APIs são responsáveis pela parte não cliente da janela e pela interação do seu aplicativo com o Windows sistema operacional.

Acompanhar a janela atual

Mesmo que a Current propriedade não seja suportada em aplicações WinUI, no entanto, pode ainda precisar acessar as Window APIs a partir de outras partes da sua aplicação. Por exemplo, talvez seja necessário obter os Window limites ou manipular o evento Window.SizeChanged de uma Página no código. Nesse caso, você pode fornecer acesso ao Window de forma semelhante à Current propriedade usando uma propriedade estática pública em sua App classe.

Para fazer isso, modifique a Window declaração na classe App, conforme mostrado aqui.

// App.xaml.cs in a WinUI app
public partial class App : Application
{
    ...
    public static Window Window { get { return m_window; } }
    private static Window m_window;
}

// App.xaml.h in a WinUI app
...
struct App : AppT<App>
{
    ...
    static winrt::Microsoft::UI::Xaml::Window Window(){ return window; };

private:
    static winrt::Microsoft::UI::Xaml::Window window;
};
...

// App.xaml.cpp
...
winrt::Microsoft::UI::Xaml::Window App::window{ nullptr };
...

Em seguida, para acessar o Window de outros lugares em seu aplicativo, use App.Window, desta forma:

// MainPage.xaml.cs in a WinUI app
var width = App.Window.Bounds.Width;

// MainPage.xaml.cpp in a WinUI app
#include <App.xaml.h>
auto width{ App::Window().Bounds().Width };

Tópicos relacionados

• Gerenciar janelas de aplicativos
• Migração da funcionalidade de janelas
• Executar chamadas às APIs de interoperabilidade a partir de uma aplicação .NET
• Recuperar um window handle (HWND)
• Exemplo de galeria de janelas