Sdílet prostřednictvím

Správa oken aplikací

Sada Windows App SDK poskytuje třídu Microsoft.UI.Windowing,AppWindow která představuje abstrakci HWND vysoké úrovně. Ve vaší aplikaci je mapování 1:1 mezi AppWindow a HWND nejvyšší úrovně. AppWindow a související třídy poskytují rozhraní API, která umožňují spravovat mnoho aspektů oken nejvyšší úrovně vaší aplikace bez nutnosti přímého přístupu k HWND.

Poznámka:

Tento článek ukazuje, jak používat AppWindow rozhraní API ve vaší aplikaci. Jako předpoklad doporučujeme, abyste si přečetli a porozuměli informacím v AppWindow, které platí bez ohledu na to, jestli používáte WinUI nebo jinou architekturu uživatelského rozhraní.

Otevřete aplikaci Galerie WinUI 3 a podívejte se AppWindow v akci.

Aplikace WinUI 3 Gallery obsahuje interaktivní příklady většiny ovládacích prvků, vlastností a funkcionality WinUI 3. Získání aplikace z Microsoft Storu nebo získání zdrojového kódu na GitHubu

Rozhraní API AppWindow můžete použít s libovolnou architekturou uživatelského rozhraní, kterou sada Windows App SDK podporuje – WinUI 3, WPF, WinForms nebo Win32. AppWindow Rozhraní API spolupracují s okny API specifickými pro framework:

Obvykle používáte AppWindow rozhraní API k:

  • Umožňuje spravovat velikost a umístění okna aplikace.

  • Správa názvu okna, ikony a barvy záhlaví; nebo vytvořte plně vlastní záhlaví pomocí rozhraní API AppWindowTitleBar .

    Další informace a příklady najdete v části Přizpůsobení záhlaví.

  • Umožňuje spravovat vzhled a chování okna pomocí rozhraní API odvozených od AppWindowPresenter.

Reakce na AppWindow změny

Na změny AppWindow odpovíte zpracováním jedné změněné události a pak zkontrolujete args události (AppWindowChangedEventArgs), abyste zjistili, jaký druh změny se stalo. Pokud došlo ke změně, kterou vás zajímá, můžete na ni reagovat. Mezi potenciální změny patří pozice, velikost, prezentační vrstva, viditelnost a pořadí vykreslování.

Tady je příklad obslužné rutiny události AppWindow.Changed.

private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
{
    // ConfigText and SizeText are TextBox controls defined in XAML for the page.
    if (args.DidPresenterChange == true)
    {
        ConfigText.Text = sender.Presenter.Kind.ToString();
    }

    if (args.DidSizeChange == true)
    {
        SizeText.Text = sender.Size.Width.ToString() + ", " + sender.Size.Height.ToString();
    }
}

Window velikost a umístění

Třída AppWindow má několik vlastností a metod, které můžete použít ke správě velikosti a umístění okna.

Kategorie Vlastnosti
Vlastnosti pouze pro čtení Pozice, velikost, velikost klienta
Events Změněno (DidPositionChange, DidSizeChange)
Metody velikosti a umístění Přesunutí, změna velikosti, ResizeClient, MoveAndResize
Metody pořadí Z MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInZOrderBelow

Zavolejte Resize pro zadání nové velikosti okna.

V tomto příkladu je kód v MainWindow.xaml.cs, takže můžete použít Windowvlastnost .AppWindow k získání AppWindow instance.

public MainWindow()
{
    InitializeComponent();
    AppWindow.Resize(new Windows.Graphics.SizeInt32(1200, 800));
}

Voláním metody Move změňte umístění okna.

Tento příklad přesune okno na střed na obrazovce, když uživatel klikne na tlačítko.

K tomu dochází v souboru kódu pro třídu Page , takže nemáte automaticky přístup k objektům Window nebo AppWindow objektům. Máte několik možností, jak získat AppWindow.

private void MoveWindowButton_Click(object sender, RoutedEventArgs e)
{
    AppWindow appWindow = AppWindow.GetFromWindowId(XamlRoot.ContentIslandEnvironment.AppWindowId);
    RectInt32? area = DisplayArea.GetFromWindowId(appWindow.Id, DisplayAreaFallback.Nearest)?.WorkArea;
    if (area == null) return;
    appWindow.Move(new PointInt32((area.Value.Width - appWindow.Size.Width) / 2, (area.Value.Height - appWindow.Size.Height) / 2));
}

AppWindowPresenter – třída a podtřídy

Každý AppWindow má na sobě aplikován AppWindowPresenter (prezentér). Prezentující je vytvořen systémem a aplikován na AppWindow během vytváření. Každá podtřída AppWindowPresenter poskytuje předem definovanou konfiguraci, která je vhodná pro účely okna. Tyto prezentující odvozené z AppWindowPresenter jsou k dispozici ve všech podporovaných verzích operačního systému.

  • CompactOverlayPresenter

    Konfiguruje vždy nahoře okno s pevnou velikostí a s poměrem stran 16:9 pro zážitky podobné obraz v obraze. Ve výchozím nastavení je InitialSizeCompactOverlaySize.Small, ale můžete ji změnit na Medium nebo Large. Můžete také použít AppWindow.Resize pro přepsání poměru stran 16:9 a nastavení okna na požadovanou velikost.

  • FullScreenPresenter

    Nakonfiguruje okno tak, aby poskytovalo prostředí na celé obrazovce vhodné pro sledování videa. Okno nemá ohraničení nebo záhlaví a skryje panel úloh systému.

  • OverlappedPresenter

    Standardní konfigurace okna, která ve výchozím nastavení poskytuje ohraničení s úchyty pro změnu velikosti a titulní lištou s tlačítky pro minimalizaci, maximalizaci a obnovení.

Poznámka:

Jako nový koncept v modelu aplikace Win32, prezentér se podobá kombinaci stavu okna a stylů, ale není totéž co. Někteří prezentující mají také definované chování, které nejde zkontrolovat z klasických vlastností stavu a stylu okna (například automatické skrytí záhlaví).

Výchozí prezentující

Výchozí prezentující, který se použije při vytvoření AppWindow, je instance OverlappedPresenter s výchozími nastaveními vlastností. Není třeba udržovat na něj odkaz, abyste se po použití jiného prezentéru mohli vrátit k výchozímu prezentéru okna. Je to proto, že systém uchovává stejnou instanci tohoto prezentujícího pro dobu životnosti AppWindow, pro kterou byla vytvořena; a můžete ji znovu použít voláním metody AppWindow.SetPresenter s AppWindowPresenterKind.Default jako parametr.

Důležité

Volání SetPresenter(AppWindowPresenterKind.Default) vždy znovu použije výchozí instanci prezentujícího, která je vytvořena pomocí AppWindow. Pokud vytvoříte a použijete dalšího prezentujícího a budete ho chtít později znovu použít, musíte mít odkaz na svého prezentujícího.

Můžete také získat odkaz na výchozí instanci prezentujícího a upravit ji. Pokud jste použili nového prezentujícího, nejprve se ujistěte, že se použije výchozí prezentující, jak je znázorněno tady:

appWindow.SetPresenter(AppWindowPresenterKind.Default);
OverlappedPresenter defaultPresenter = (OverlappedPresenter)appWindow.Presenter;
defaultPresenter.IsMaximizable = false;
defaultPresenter.IsMinimizable = false;

Upravit překrývajícího presenteru

OverlappedPresenter je flexibilní prezentační prvek, který můžete konfigurovat různými způsoby.

Metody Create* umožňují vytvořit prezentér s překrýváním s výchozími nastaveními vlastností nebo jeden s předem nakonfigurovanými nastaveními vlastností pro konkrétní použití.

Tato tabulka ukazuje, jak se vlastnosti konfigurace nastaví při vytváření objektu OverlappedPresenter z každé metody.

Vlastnictví Create CreateForContextMenu CreateForDialog CreateForToolWindow
HasBorder true true true true
HasTitleBar true false true true
IsAlwaysOnTop false false false false
IsMaximizable true false false true
JeMinimalizovatelné true false false true
IsModal false false false false
JeNastavitelný true false false true

Použitý prezentující objekt je živý. Změna libovolné vlastnosti objektu AppWindow.Presenter se projeví okamžitě. Neexistují žádné události, které by vás mohly o těchto změnách informovat, ale vlastnosti aktuálních hodnot můžete kdykoli zkontrolovat.

Vlastnosti HasBorder a HasTitleBar jsou jen pro čtení. Tyto hodnoty můžete nastavit voláním SetBorderAndTitleBar metoda (SetBorderAndTitleBar(bool hasBorder, bool hasTitleBar)). OverlappedPresenter nemůže mít záhlaví bez ohraničení. To znamená, že pokud je parametr hasTitleBartrue, pak musí být parametr hasBorder také true. V opačném případě je vyvolána výjimka s touto zprávou:

The parameter is incorrect.
Invalid combination: Border=false, TitleBar=true.

Nastavte IsMaximizable tak, aby false se tlačítko maximalizovat na panelu nástrojů skryje. Doporučujeme to udělat, pokud nastavíte PreferredMaximumHeight nebo PreferredMaximumWidth vlastnosti, protože tyto vlastnosti omezují velikost okna i v maximalizovaném stavu. To nemá vliv na volání maximalizační metody.

Nastavte IsMinimizable tak, aby false se minimalizované tlačítko na panelu nástrojů skrylo. To nemá vliv na volání metody Minimalizovat .

Nastavte isResizable na false pro skrytí ovládacích prvků změny velikosti a zabránění uživateli ve změně velikosti okna. To nemá vliv na volání metody AppWindow.Resize.

Nastavte IsAlwaysOnTop tak, aby true toto okno zůstalo nad ostatními okny. Pokud voláte některou z metod AppWindow.MoveInZOrder*, stále se projeví tak, že změní pořadí vykreslování okna, i když je tato vlastnost true.

Nastavit PreferredMaximumHeight a PreferredMaximumWidth omezit maximální velikost, na kterou může uživatel roztáhnout okno. Doporučujeme nastavit IsMaximizable na false, pokud nastavíte vlastnosti maximální velikosti, protože tyto vlastnosti omezují velikost okna i v maximalizovaném stavu. Tyto vlastnosti také ovlivňují volání AppWindow.Resize; okno nebude zvětšeno nad stanovenou maximální výšku a šířku.

Nastavit PreferredMinimumHeight a PreferredMinimumWidth nastavit minimální velikost, na kterou může uživatel zmenšit okno. Tyto vlastnosti ovlivňují také volání AppWindow.Resize; okno nebude zmenšeno na menší rozměry, než je zadaná minimální výška a šířka.

IsModal můžete nastavit tak, aby true se vytvořilo modální okno. Modální okno je samostatné okno, které blokuje interakci s oknem vlastníka , dokud není zavřené. Chcete-li však vytvořit modální okno, musíte také nastavit okno vlastníka; v opačném případě je vyvolána výjimka s touto zprávou:

The parameter is incorrect.

The window should have an owner when IsModal=true.

K nastavení okna vlastníka v aplikaci WinUI je potřeba interoperabilita Win32. Další informace a ukázkový kód najdete na AppWindow stránce ukázkové aplikace Galerie WinUI.

Použití prezentujícího

Prezentující lze použít jenom na jedno okno najednou. Při pokusu o použití stejného prezenteru u druhého okna vyvolá výjimku. To znamená, že pokud máte více oken a chcete každé z nich přepnout do konkrétního prezentačního režimu, musíte vytvořit více prezentujících stejného druhu a pak je aplikovat na své vlastní okno.

Při použití nového prezentujícího (vlastnost AppWindow.Presenter se změní), je vaše aplikace upozorněna událostí AppWindow.Changed na změněném AppWindow, s vlastností AppWindowChangedEventArgs.DidPresenterChange nastavenou na true.

Návod

Pokud aplikujete upravený prezentační komponent a povolíte změnu mezi prezentačními komponenty, nezapomeňte zachovat odkaz na upravený komponent, aby ho bylo možné znovu aplikovat na AppWindow.

Tento příklad ukazuje, jak provést následující akce:

V konstruktoru pro okno se zde vytvoří, upraví a použije prezenter.

OverlappedPresenter presenter = OverlappedPresenter.Create();
presenter.PreferredMinimumWidth = 420;
presenter.PreferredMinimumHeight = 550;
AppWindow.SetPresenter(presenter);

Na stránce, která je obsahem okna, můžete získat odkaz na AppWindow a použitý prezenter.

AppWindow appWindow;
OverlappedPresenter modifiedPresenter;

private void AppWindowPage_Loaded(object sender, RoutedEventArgs e)
{
    appWindow = AppWindow.GetFromWindowId(XamlRoot.ContentIslandEnvironment.AppWindowId);
    modifiedPresenter = (OverlappedPresenter)appWindow.Presenter;

    appWindow.Changed += AppWindow_Changed;
}

private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
{
    if (args.DidPresenterChange)
    {
        // ConfigText is a TextBox control defined in XAML for the page.
        ConfigText.Text = appWindow.Presenter.Kind.ToString();
    }
}

private void CompactOverlayButton_Click(object sender, RoutedEventArgs e)
{
    if (appWindow.Presenter.Kind != AppWindowPresenterKind.CompactOverlay)
    {
        appWindow.SetPresenter(CompactOverlayPresenter.Create());
        fullScreenButton.IsChecked = false;
    }
    else
    {
        appWindow.SetPresenter(modifiedPresenter);
    }
}

private void FullScreenButton_Click(object sender, RoutedEventArgs e)
{
    if (appWindow.Presenter.Kind != AppWindowPresenterKind.FullScreen)
    {
        appWindow.SetPresenter(FullScreenPresenter.Create());
        compactOverlayButton.IsChecked = false;
    }
    else
    {
        appWindow.SetPresenter(modifiedPresenter);
    }
}

Architektura uživatelského rozhraní a interoperabilita HWND

Třída AppWindow je k dispozici pro jakýkoli HWND nejvyšší úrovně ve vaší aplikaci. To znamená, že když pracujete s architekturou desktopového uživatelského rozhraní (včetně WinUI 3), můžete k vytvoření okna a připojení jejího obsahu i nadále používat vstupní bod této architektury. Jakmile vytvoříte okno s danou architekturou uživatelského rozhraní, můžete k přístupu k odpovídajícím AppWindow metodám, vlastnostem a událostem použít funkce vzájemné spolupráce oken (viz níže) uvedené v sadě Windows App SDK.

Mezi výhody použití AppWindow (i při práci s architekturou uživatelského rozhraní) patří:

  • Snadné přizpůsobení titulku, které ve výchozím nastavení zachovává uživatelské rozhraní Windows 11 (zaoblené rohy, vyskakovací seznam skupin pro přichytávání).
  • Celou obrazovku a kompaktní překrytí (obraz v obraze) nabízí systém.
  • Rozhraní API prostředí Windows Runtime (WinRT) pro některé základní koncepty oken Win32

Získejte AppWindow pro verze sady Windows App SDK před verzí 1.3 (nebo jiných architektur desktopových aplikací)

Vlastnost Window.AppWindow je k dispozici v sadě Windows App SDK verze 1.3 a novější. V dřívějších verzích můžete použít funkční ekvivalentní příklad kódu v této části.

C#. Obálky rozhraní .NET pro funkce vzájemné spolupráce oken jsou implementovány jako metody třídy Microsoft.UI.Win32Interop . Podívejte se také na volání API pro interoperabilitu z aplikace .NET.

C++. Funkce interoperabilní jsou definovány v hlavičkovém souboru winrt/Microsoft.ui.interop.h.

Následující část s ukázkovým kódem ukazuje skutečný zdrojový kód; ale tady je recept na načtení objektu AppWindow s existujícím oknem:

  1. Pokud ho ještě nemáte, načtěte HWND pro existující objekt okna (pro architekturu uživatelského rozhraní).
  2. Předejte tento HWND funkci interop GetWindowIdFromWindow k načtení WindowId.
  3. ID okna předat statické metodě AppWindow.GetFromWindowId pro načtení AppWindow.
// 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 the AppWindow class.

// 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->m_inner.as<::IWindowNative>() };
    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!");
    }
}

Další příklady práce s AppWindowokny najdete v ukázce galerie oken.

Omezení

Sada Windows App SDK v současné době neposkytuje metody pro připojení obsahu architektury uživatelského rozhraní k objektu AppWindow.

  • Last updated on