Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
La fonctionnalité de fenêtrage dans une application WinUI est fournie par une combinaison de la classe XAML Window et de la AppWindow classe, qui sont toutes deux basées sur le modèle HWND Win32.
- API importantes : Window classe, AppWindow classe
L’application WinUI 3 Gallery inclut des exemples interactifs de la plupart des contrôles, des caractéristiques et des fonctionnalités de WinUI 3. Obtenir l’application à partir du Microsoft Store ou obtenir le code source sur GitHub
XAML Window
Dans votre application, l’objet window est une instance de la classe Microsoft.UI.XamlWindow (ou d’une classe dérivée) qui représente la fenêtre dans le code de votre programme. Vous le créez directement avec un appel au constructeur. Le code XAML Window est l’endroit où vous attachez votre contenu d’application et gérez le cycle de vie des fenêtres de votre application.
HWND
La fenêtre d’application est créée par le Windows système d’exploitation et est représentée par un objet de fenêtre Win32. Il s’agit d’un conteneur géré par le système dans lequel votre contenu est hébergé et représente l’entité avec laquelle les utilisateurs interagissent lorsqu’ils redimensionnent et déplacent votre application à l’écran. (Voir « À propos » Windows de la documentation Win32 pour plus d’informations.)
Après Windows avoir créé la fenêtre d’application, la fonction de création retourne un window handle (HWND) qui identifie de façon unique la fenêtre. A window handle a le type de données HWND, bien qu'il soit exposé en C# sous forme de IntPtr. Il s’agit d’un handle opaque vers une structure de données interne Windows qui correspond à une fenêtre dessinée par le système d’exploitation et qui consomme des ressources système lorsqu’elles sont présentes.
Le HWND est créé après l'objet XAML Window, généralement lorsque la méthode Window.Activate est appelée.
AppWindow
Le Windows Kit de développement logiciel (SDK) d’application fournit des fonctionnalités de fenêtrage supplémentaires via la classe Microsoft.UI.Windowing.AppWindow AppWindow représente une abstraction de haut niveau du HWND. Il existe une correspondance 1:1 entre un AppWindow et un HWND de premier niveau dans votre application. AppWindow et ses classes associées fournissent des API qui vous permettent de gérer de nombreux aspects des fenêtres de niveau supérieur de votre application sans avoir à accéder directement au HWND.
La durée de vie d’un AppWindow objet et d’un HWND est la même : elle AppWindow est disponible immédiatement après la création de la fenêtre ; et elle est détruite lorsque la fenêtre est fermée.
Diagramme de l’API de fenêtre
Ce diagramme montre la relation entre les classes et les API que vous utilisez pour gérer les fenêtres dans votre application et les classes responsables de chaque partie de la gestion des fenêtres. Dans certains cas, comme ExtendsContentIntoTitleBar, l’API est un membre de AppWindow afin de la rendre accessible à d’autres frameworks d’interface utilisateur, mais elle est également exposée dans la classe Window pour des raisons de commodité. Le diagramme n’est pas complet, mais montre les API les plus couramment utilisées.
Note
Vous pouvez utiliser AppWindow des API avec n’importe quelle infrastructure d’interface utilisateur prise en charge par le Windows SDK d’application : Win32, WPF, WinForms ou WinUI 3. Pour les frameworks autres que WinUI 3, les fonctionnalités affichées dans la zone XAML Window du diagramme sont remplacées par les API de fenêtrage spécifiques à l’infrastructure appropriées :
Window/AppWindow Comparaison d’API
Si vous utilisez WinUI 3 XAML comme framework d’interface utilisateur de votre application, les deux API Window et AppWindow sont disponibles pour vous. À compter du Windows Kit de développement logiciel (SDK) d’application 1.4, vous pouvez utiliser la Windowpropriété .AppWindow pour obtenir un AppWindow objet à partir d’une fenêtre XAML existante. Avec cet AppWindow objet, vous avez accès aux API de gestion de fenêtre supplémentaires.
Important
Si vous n’utilisez pas WinUI 3 1.3 ou une version ultérieure, utilisez les API d’interopérabilité pour obtenir les AppWindow afin d'utiliser les API AppWindow. Pour plus d’informations sur les API d’interopérabilité, consultez Gérer les fenêtres d'application - Framework d'interface utilisateur et interopérabilité HWND et l'exemple de la galerie de fenêtres .
Gestion de la durée de vie
| XAML Window | AppWindow |
|---|---|
| Constructor | Create, GetFromWindowId |
| Activate | Afficher, Masquer |
| Fermer, fermé | Détruire, détruire, fermer |
| >>> | Id, OwnerWindowId |
Lorsque vous créez un projet WinUI dans Visual Studio, le modèle de projet fournit une MainWindow classe pour vous, qui est une sous-classe de Window. Si votre application n’a besoin que d’une seule fenêtre, il s’agit de tout ce dont vous avez besoin. Pour savoir comment créer et gérer des fenêtres supplémentaires, et pourquoi vous souhaiterez peut-être afficher plusieurs fenêtres pour votre application.
La AppWindow classe dispose d’API pour créer et détruire une nouvelle fenêtre . Toutefois, pour une application WinUI, vous ne le ferez pas en pratique, car il n’existe aucune API pour attacher du contenu à la fenêtre que vous créez. Au lieu de cela, vous obtenez une instance de AppWindow créée par le système et associée au XAML Window et au HWND. Dans WinUI 1.4 et versions ultérieures, vous pouvez utiliser la Windowpropriété .AppWindow pour obtenir l’instance de AppWindow. Dans d’autres cas, vous pouvez utiliser la méthode statique AppWindow.GetFromWindowId pour obtenir l’instance AppWindow. Pour plus d’informations, consultez Gérer les fenêtres d’application .
Content
| XAML Window | AppWindow |
|---|---|
| Contenu | N/A |
Le Window.Content est l’emplacement où vous attachez le contenu de votre application à la fenêtre qui l’affiche. Vous pouvez le faire en XAML ou en code.
Titre, icône et barre de titre
| XAML Window | AppWindow |
|---|---|
| Titre | Titre |
| SetTitleBar | TitleBar |
| >>> | SetIcon, SetTaskbarIcon, SetTitleBarIcon |
| ExtendsContentIntoTitleBar | AppWindow. TitleBar.ExtendsContentIntoTitleBar |
Vous pouvez modifier la barre de titre de votre application à des degrés variables ; définition du titre et de l’icône, modification des couleurs ou remplacement complet de la barre de titre par du contenu d’application personnalisé.
Pour plus d’informations sur l’utilisation d’API de barre de titre, notamment des exemples de code, consultez Personnalisation de la barre de titre.
Taille et poste
| XAML Window | AppWindow |
|---|---|
| Bounds | Position, Taille, ClientSize |
| SizeChanged | Changed (DidPositionChange, DidSizeChange) |
| >>> | Move, Resize, ResizeClient, MoveAndResize |
| >>> | MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInzOrderBelow |
Vous utilisez la propriété Window.Bounds et l'événement SizeChanged pour gérer les éléments de l'interface utilisateur de votre application, par exemple pour déplacer les éléments lorsque la taille de la fenêtre change. XAML utilise effective pixels (epx), pas de pixels physiques réels. Effective pixels sont une unité virtuelle de mesure et sont utilisées pour exprimer les dimensions de disposition et l’espacement, indépendamment de la densité de l’écran.
AppWindow, d’autre part, utilise le Window système de coordonnées, où l’unité de base de mesure est des pixels d’appareil physique. Vous utilisez les AppWindow API pour les actions de fenêtrage, telles que le redimensionnement de la fenêtre ou son déplacement par rapport à un autre élément à l’écran.
Dans certains cas, vous devrez peut-être utiliser des mesures d'une classe dans l'autre classe, auquel cas vous devrez convertir entre effective pixels et les pixels de l'appareil. Par exemple, si vous définissez des régions de glissement dans une barre de titre personnalisée, vous devez convertir les mesures. Pour obtenir un exemple d’utilisation de XamlRoot.RasterizationScale pour convertir des mesures, consultez la section contenu interactif de l’article de personnalisation de la barre de titre.
Apparence et comportement
| XAML Window | AppWindow |
|---|---|
| SystemBackdrop | N/A |
| >>> | Présentateur, SetPresenter |
| >>> | IsShownInSwitchers |
| Visible, VisibilityChanged | IsVisible, Changed (DidVisibilityChange) |
| DispatcherQueue | DispatcherQueue, AssociateWithDispatcherQueue |
| Compositor | N/A |
Les API XAML Window sont généralement responsables de l’apparence du contenu de votre application, comme l’arrière-plan. Pour plus d’informations sur SystemBackdrop, consultez Appliquer des matériaux Mica ou Acrylique.
AppWindow Les API sont responsables de la partie non cliente de la fenêtre et de l’interaction de votre application avec le Windows système d’exploitation.
Note
La classe XAML Window a plusieurs propriétés qui ont été transmises à partir de l’UWP Windows. UI. Xaml.Window classe, mais ne sont pas prises en charge dans les applications WinUI. Ces propriétés ont toujours une null valeur et ne sont pas utilisées dans les applications WinUI : CoreWindow, Currentet Dispatcher.
Suivre la fenêtre active
Même si la Current propriété n’est pas prise en charge dans les applications WinUI, vous devrez peut-être toujours accéder aux Window API à partir d’autres emplacements de votre application. Par exemple, vous devrez peut-être obtenir les Window limites ou gérer l'événement Window.SizeChanged à partir du code d'un Page. Dans ce cas, vous pouvez fournir l'accès à Window de manière similaire à la propriété Current en utilisant une propriété statique publique dans votre classe App.
Pour ce faire, modifiez la Window déclaration dans la classe App comme indiqué ici.
// 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 };
...
Ensuite, pour accéder aux Window autres emplacements de votre application, utilisez App.Window, comme suit :
// 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 };
Important
L’utilisation d’une propriété statique Window dans votre App classe est utile si votre application utilise uniquement une seule fenêtre. Si votre application utilise plusieurs fenêtres, vous devez plutôt utiliser WindowId pour suivre les instances de Window afin de vous assurer que vous accédez bien à la bonne instance de Window. Pour plus d’informations et d’exemples, consultez Afficher plusieurs fenêtres pour votre application .
Rubriques connexes
Collaborer avec nous sur GitHub
La source de ce contenu se trouve sur GitHub, où vous pouvez également créer et examiner les problèmes et les demandes de tirage. Pour plus d’informations, consultez notre guide du contributeur.
Windows developer