Partilhar via

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.

Abra o aplicativo WinUI 3 Gallery e veja Exemplos de janelas em ação

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.

win u i diagrama de janelas

Observação

Você pode usar AppWindow APIs com qualquer estrutura de interface do usuário suportada pelo SDK do Windows aplicativo - Win32, WPF, WinForms ou WinUI 3. Para estruturas diferentes do WinUI 3, a funcionalidade mostrada na caixa XAML Window do diagrama seria substituída pelas APIs de janela específicas da estrutura apropriadas:

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.

Importante

Se não estiver a usar o WinUI 3 1.3 ou posterior, utilize APIs de interoperação para obter o AppWindow e usar as APIs AppWindow. Para obter mais informações sobre as APIs de interoperabilidade, consulte Manage app windows - UI framework e HWND interop e o exemplo de galeria Windowing.

Gestão do tempo de vida

XAML Window AppWindow
Constructor Criar, GetFromWindowId
Activate Mostrar, Ocultar
Fechar, Fechar Destruir, Destruindo, Fechar
>>> Id, ProprietárioWindowId

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

XAML Window AppWindow
Content N/A

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

XAML Window AppWindow
Título Título
SetTitleBar TitleBar
>>> SetIcon, SetTaskbarIcon, SetTitleBarIcon
ExtendsContentIntoTitleBar AppWindow. TitleBar.ExtendsContentIntoTitleBar

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

XAML Window AppWindow
Limites Posição, Tamanho, ClientSize
TamanhoAlterado Alterado (DidPositionChange, DidSizeChange)
>>> Mover, Redimensionar, RedimensionarClient, MoveAndResize
>>> MoveEmZOrderAbaixo, MoveEmZOrderAoTopo, MoveEmZOrderAbaixoDe

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

XAML Window AppWindow
SystemBackdrop N/A
>>> Apresentador, SetPresenter
>>> IsShownInSwitchers
Visível, VisibilidadeAlterada IsVisible, alterado (DidVisibilityChange)
DispatcherQueue DispatcherQueue, AssociateWithDispatcherQueue
Compositor N/A

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.

Observação

A classe XAML Window tem várias propriedades que foram transferidas da UWP Windows. UI. Xaml.Window , mas não são suportados em aplicativos WinUI. Essas propriedades sempre têm um null valor e não são usadas em aplicativos WinUI: CoreWindow, Currente Dispatcher.

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

Importante

Usar uma propriedade estática Window em sua App classe é útil se seu aplicativo usar apenas uma única janela. Se seu aplicativo usa várias janelas, você deve usar WindowId para rastrear as Window instâncias, para garantir que você está acessando a instância correta do Window. Consulte Mostrar várias janelas para a sua aplicação para obter mais informações e exemplos.

  • Last updated on