Jazyk

Správa oken aplikací

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í API, která umožňují spravovat mnoho aspektů hlavních oken 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 přečíst si informace o AppWindow v přehledu Windowing pro WinUI 3 a Windows App SDK, které platí pro použití WinUI nebo jiné architektury uživatelského rozhraní.

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

Ikona galerie WinUI 3 Aplikace Galerie WinUI 3 obsahuje interaktivní příklady ovládacích prvků a funkcí WinUI. Získejte aplikaci z Microsoft Store nebo vyhledejte zdrojový kód na GitHub.

Rozhraní API AppWindow můžete použít s libovolnou architekturou uživatelského rozhraní, kterou Windows App SDK podporuje – WinUI, WPF (Windows Presentation Foundation), 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 access k objektům Window nebo AppWindow. 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));
}

Nastavte velikost okna v logických pixelech (experimentální)

Důležité

Vlastnosti Window velikosti v této části jsou experimentální rozhraní API, která byla zavedena v Windows App SDK 2.3 Experimental A. Rozhraní API jsou označená jako experimentální a v budoucí verzi mohou být změněna nebo odebrána. Nepoužívejte je v produkčních aplikacích. Odkazy ke stažení najdete v tématu Nejnovější Windows App SDK ke stažení.

AppWindow.Resize a AppWindow.ResizeClient přebírají velikosti ve fyzických pixelech. Pokud chcete na displejích získat stejnou velikost s různými faktory škálování, musíte hodnoty převést sami. Třída Microsoft.UI.Xaml.Window má v experimentálních verzích vlastnosti pro získání a nastavení velikosti klientské oblasti okna v logických pixelech, označovaných také jako pixely nezávislé na zařízení (DIPs). Okno převede hodnoty pro aktuální měřítko zobrazení, takže klientská oblast o šířce Width 640 je při měřítku 100 % široká 640 fyzických pixelů a při měřítku 150 % široká 960 fyzických pixelů. Tyto vlastnosti můžete nastavit v jazyce XAML nebo v kódu, aniž byste museli použít vlastnost Window.AppWindow.

Vlastnictví Description
Šířka, Výška Velikost klientské oblasti, když je okno v obnoveném stavu.
MinWidth, MinHeight Nejmenší velikost klientské oblasti, na kterou může uživatel okno změnit. Výchozí hodnota je 0.
MaxWidth, MaxHeight Největší klientská oblast, do které může uživatel změnit velikost okna. Výchozí hodnota je kladné nekonečno, což znamená, že neexistuje žádné maximum.

Otevřete aplikaci Galerie WinUI 3 a podívejte se Window na změnu velikosti prvků v akci.

Tento příklad nastavuje počáteční velikost a omezení velikosti okna v souboru XAML.

<Window
    x:Class="MyApp.SettingsWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Width="640"
    Height="480"
    MinWidth="320"
    MinHeight="240"
    MaxWidth="960"
    MaxHeight="720">
    <TextBlock Margin="24" Text="Resize this window." />
</Window>

Tento příklad nastavuje stejné hodnoty v jazyce C# pro okno, které vytvoří v kódu.

Window window = new Window
{
    Width = 640,
    Height = 480,
    MinWidth = 320,
    MinHeight = 240,
    MaxWidth = 960,
    MaxHeight = 720,
    Content = new TextBlock { Margin = new Thickness(24), Text = "Resize this window." }
};

// A size that you set before the first call to Activate is applied when the window is shown.
window.Activate();

Tato tabulka ukazuje, jak Window vlastnosti souvisejí s AppWindow rozhraními API pro změnu velikosti. AppWindow.Resize(new SizeInt32(1200, 800)) Například vytvoří celé okno, včetně ohraničení a titulkového pruhu, o velikosti 1200 × 800 fyzických pixelů. Nastavení Width na 1200 a Height na 800 dává klientské oblasti velikost 1200 × 800 logických pixelů, což je 1800 × 1200 fyzických pixelů na displeji při 150% měřítku.

API Co to dimenzuje Units
Window. Šířka, Window. Výška (experimentální) Klientská oblast obnoveného okna. Můžete získat a nastavit hodnoty. Logické pixely
Window.Hranice Aktuální klientská oblast. Read-only. Logické pixely
AppWindow.Změna velikosti Celé okno, včetně ohraničení a záhlaví okna. Fyzické pixely
AppWindow.ResizeClient Klientská zóna. Fyzické pixely
AppWindow.Velikost, AppWindow.VelikostKlienta Aktuální okno a klientská oblast. Read-only. Fyzické pixely

Při použití Window vlastností velikosti mějte na paměti toto chování:

  • Velikost byla obnovena. Pokud je okno maximalizované nebo minimalizované, Height a Width vrátí velikost klienta, na kterou se okno vrátí, když se obnoví. Pokud je nastavíte v daném stavu, obnovená velikost se změní a okno zůstane maximalizované nebo minimalizované. Pokud okno používá FullScreenPresenter nebo CompactOverlayPresenter, použije se velikost, kterou nastavíte, když se okno přepne zpět na OverlappedPresenter.
  • Omezení velikostiMinWidth, MinHeight, MaxWidth a MaxHeight se projeví, když okno používá OverlappedPresenter, což je výchozí presenter. Okno za vás nastaví vlastnosti PreferredMinimumWidth, PreferredMaximumWidth, PreferredMinimumHeight a PreferredMaximumHeight prezentujícího a aktualizuje je, když se okno přesune na displej s jiným měřítkem. Nenastavujte tyto vlastnosti presenteru sami pro dimenzi, kterou omezíte pomocí vlastností Window. Další informace o vlastnostech Presenteru naleznete v tématu Úprava OverlappedPresenteru.
  • Maximalizované Stejně jako vlastnosti PreferredMaximumHeight a MaxWidth prezentujícího i PreferredMaximumWidth a MaxHeight omezují velikost okna, i když je maximalizované. Když například maximalizujete okno z předchozích příkladů, jeho klientská oblast není větší než 960 × 720 logických pixelů, a to i na větším displeji.
  • Platné hodnoty. Nastavte Width a Height na hodnoty mezi minimálními a maximálními limity. Width, Height, MinWidtha MinHeight musí být konečné a 0 nebo větší. MaxWidth a MaxHeight musí být 0 nebo více nebo kladné nekonečno pro žádné maximum. Jiné hodnoty způsobí, že setter vyvolá výjimku, což v jazyce C# představuje ArgumentException.

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í. Nemusíte udržovat odkaz, abyste se mohli vrátit k výchozímu prezentéru okna po použití jiného prezentéru. 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 3.

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í:

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), můžete i nadále používat vstupní bod této architektury pro vytvoření okna a připojit jeho obsah. A jakmile vytvoříte okno s danou architekturou uživatelského rozhraní, můžete použít funkce spolupráce oken (viz níže) uvedené v Windows App SDK pro přístup k odpovídajícím AppWindow a jeho metodám, vlastnostem a událostem.

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

  • Snadné přizpůsobení titulku okna; které ve výchozím nastavení udržuje uživatelské rozhraní Windows 11 (zaoblené rohy, pop-up skupiny).
  • 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 Windows App SDK před 1.3 (nebo jiné rámce pro desktopové aplikace).

Vlastnost Window.AppWindow je dostupná v 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#. .NET obálky pro funkce interoperability oken jsou implementovány jako metody třídy Microsoft.UI.Win32Interop. Viz také volání interoperabilních rozhraní API 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 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 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 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 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 AppWindow najdete v ukázce galerie Windowing.

Omezení

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

  • Poslední aktualizace v