A WinUI 3 és a Windows App SDK ablakozási áttekintése

A következőre érvényes:: ✅ WinUI, ✅ Windows App SDK

A WinUI-alkalmazások ablakkezelési funkcióit az XAML Window osztály és az AppWindow osztály kombinációja biztosítja, amelyek mindegyike a Win32 HWND modellen alapul.

Fontos API-k: Window osztály, AppWindow osztály

Nyissa meg a WinUI 3 Katalógus alkalmazást, és tekintse meg a windowsos mintákat működés közben

A WinUI 3 Katalógus alkalmazás interaktív példákat tartalmaz a WinUI vezérlőire és funkcióira. Kérje le az alkalmazást a Microsoft Áruházból vagy keresse meg a forráskódot a GitHub webhelyen.

XAML Window

Az alkalmazásban az ablakobjektum a Microsoft.UI.Xaml.Window osztály (vagy származtatott osztály) egy példánya, amely a programkód ablakát jelöli. Közvetlenül a konstruktor hívásával hozza létre. Az XAML Window pont az alkalmazás tartalmának csatolására és az ablakainak életciklusának kezelésére szolgál.

HWND

Az alkalmazásablakot az Windows operációs rendszer hozza létre, és egy Win32-ablakobjektum képviseli. Ez egy rendszer által felügyelt tároló, amelyben a tartalom található, és azt az entitást jelöli, amelyet a felhasználók az alkalmazás átméretezésekor és a képernyőn való áthelyezésekor használnak. (További Windowsinformációt a Win32 dokumentációjában talál.)

Az alkalmazásablak létrehozása után Windows a létrehozási függvény egy window handle (HWND) értéket ad vissza, amely egyedileg azonosítja az ablakot. Az A window handle HWND adattípussal rendelkezik, bár C#-ban intPtrként van felszínre hozva. Ez egy nem átlátszó fogantyú egy belső Windows adatszerkezethez, amely egy ablakot képvisel, amelyet az operációs rendszer rajzol és rendszer erőforrásokat igényel, amikor jelen van.

A HWND az XAML Window objektum után jön létre, általában akkor, amikor a Window.Activate metódust meghívják.

AppWindow

Az Windows App SDK további ablakozási funkciókat biztosít a Microsoft.UI.Windowing. osztályon keresztül.AppWindow AppWindow A HWND magas szintű absztrakcióját jelöli. Az alkalmazásban egy 1:1-es leképezés található egy AppWindow és egy legfelső szintű HWND között. AppWindow és annak kapcsolódó osztályai olyan API-kat biztosítanak, amelyekkel az alkalmazás legfelső szintű ablakainak számos aspektusát kezelheti anélkül, hogy közvetlenül elérné a HWND-t.

Egy objektum és egy HWND élettartama AppWindow megegyezik – az AppWindow ablak létrehozása után azonnal elérhető, és az ablak bezárásakor elpusztul.

Ablakozási API-diagram

Ez az ábra az alkalmazás ablakainak kezeléséhez használt osztályok és API-k közötti kapcsolatot mutatja be, valamint azt, hogy mely osztályok felelősek az ablakkezelés egyes részeiért. Bizonyos esetekben, mint ExtendsContentIntoTitleBar, az API a AppWindow tagja, hogy elérhetővé váljon más UI keretrendszerek számára, de kényelmi okokból az Window osztályon is elérhető. A diagram nem átfogó, de a leggyakrabban használt API-kat mutatja.

Megjegyzés:

A AppWindow API-kat bármely olyan felhasználói keretrendszerrel használhatja, amelyet a Windows App SDK támogat – Win32, WPF, WinForms vagy WinUI. A WinUI-tól eltérő keretrendszerek esetében a diagram XAML Window mezőjében látható funkciókat a megfelelő keretrendszerspecifikus ablakkezelési API-k váltják fel:

Window/AppWindow API-összehasonlítás

Ha a WinUI XAML-t használja az alkalmazás felhasználói felületi keretrendszereként, mind a Window, mind a AppWindow API elérhető az Ön számára. Az Windows App SDK 1.4-től kezdve a Window.AppWindow tulajdonság használatával lekérhet egy objektumot AppWindow egy meglévő XAML-ablakból. Ezzel a AppWindow objektummal hozzáférhet a további ablakkezelési API-khoz.

Fontos

Ha nem a WinUI 1.3-at vagy annak újabb verzióját használja, alkalmazza az interop API-kat a AppWindow megszerzéséhez, hogy használhassa a AppWindow API-kat. Az interop API-król további információt a Az alkalmazás windows – felhasználói felület keretrendszere és a HWND interop, valamint a Windowing katalógusminta című témakörben talál.

Élettartam-kezelés

XAML Window	AppWindow
Constructor	Létrehozás, GetAblakAzonosítóból
Aktivál	Megjelenítés, elrejtés
Bezárás, Bezárás	Megsemmisítés, megsemmisítés, lezárás
>>>	Id, OwnerWindowId

Amikor új WinUI-project hoz létre Visual Studio, a project sablon egy MainWindow osztályt biztosít Önnek, amely a Window alosztálya. Ha az alkalmazásnak csak egy ablakra van szüksége, csak erre van szüksége. További ablakok létrehozásának és kezelésének, valamint a kívánt lehetőségeknek a megismeréséhez tekintse meg az alkalmazás több ablakának megjelenítése című témakört.

Az AppWindow osztály api-kkal rendelkezik egy új ablak létrehozásához és elpusztításához. WinUI-alkalmazások esetében azonban ezt a gyakorlatban nem fogja megtenni, mert nincs api a létrehozott ablakhoz tartalom csatolásához. Ehelyett a rendszer létrehoz egy példányt AppWindow , amely az XAML-hez Window és a HWND-hez van társítva. A WinUI 1.4-ben és újabb verzióiban a Window.AppWindow tulajdonság használatával lekérheti a példányt AppWindow. Más esetekben használhatja a statikus AppWindow.GetFromWindowId metódust a példány lekérésére AppWindow. További információt az alkalmazásablakok kezelése című témakörben talál.

Content

XAML Window	AppWindow
Content	N/A

A Window.Content metódus az, ahol az alkalmazás tartalmat az azt megjelenítő ablakhoz csatolja. Ezt XAML-ben vagy kódban teheti meg.

Cím, ikon és címsor

XAML Window	AppWindow
Title	Title
SetTitleBar	TitleBar
>>>	SetIcon, SetTaskbarIcon, SetTitleBarIcon
ExtendsContentIntoTitleBar	AppWindow.TitleBar.ExtendsContentIntoTitleBar

Az alkalmazás címsorát eltérő mértékben módosíthatja; a cím és az ikon beállítása, a színek módosítása vagy a címsor teljes cseréje egyéni alkalmazástartalommal.

További információ a címsor API-k használatáról, beleértve a kódpéldákat is, lásd: Címsor testreszabása.

Méret és pozíció

XAML Window	AppWindow
Határok	Pozíció, Méret, Ügyfélméret
Méretváltozás	Módosítva (DidPositionChange, DidSizeChange)
>>>	Áthelyezés, Átméretezés, ResizeClient, MoveAndResize
>>>	MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInZOrderBelow

A WindowBounds tulajdonságot és a SizeChanged eseményt használja az alkalmazás felhasználói felületén lévő dolgok kezeléséhez, például az elemek mozgatásához, amikor az ablakméret változik. Az XAML az effective pixels-t (epx) használja, nem pedig a tényleges fizikai képpontokat. Effective pixels virtuális mértékegységek, amelyek az elrendezés méreteit és térközeit fejezik ki, a képernyő sűrűségétől függetlenül.

AppWindowmásrészt a koordinátarendszertWindow használja, ahol az alapvető mértékegység a fizikai eszköz képpontja. Az API-kat ablakozási AppWindow műveletekhez használhatja, például átméretezheti az ablakot, vagy áthelyezheti a képernyőn lévő valami máshoz képest.

Bizonyos esetekben szüksége lehet arra, hogy az egyik osztályban lévő méréseket a másik osztályban használja, ilyenkor át kell alakítania a effective pixels képpontokat eszköz képpontokká. Ha például egy egyéni címsorban állítja be a húzási régiókat, akkor a méréseket át kell számítania. A XamlRoot.RasterizationScale használatával a mérések konvertálására vonatkozó példát a Címsor testreszabási cikkének interaktív tartalom szakaszában találja.

Megjelenés és viselkedés

XAML Window	AppWindow
SystemBackdrop	N/A
>>>	Előadó, SetPresenter
>>>	IsShownInSwitchers
Látható, LáthatóságVáltozott	Látható, Módosult (VáltozottALáthatóság)
DispatcherQueue	DispatcherQueue, AssociateWithDispatcherQueue
Compositor	N/A

Az XAML Window API-k általában felelősek az alkalmazás tartalmának megjelenéséért, például a háttérért. A SystemBackdropról további információt a Mica vagy az Akril anyagok alkalmazása című témakörben talál.

AppWindow Az API-k felelősek az ablak nem ügyfél jellegű részéért és az alkalmazás operációs rendszerrel való Windows interakciójáért.

Megjegyzés:

Az XAML Window osztály számos tulajdonsággal rendelkezik, amelyeket az UWP-ből Windowsszállítottak át. UI. Xaml.Window osztály, de winUI-alkalmazásokban nem támogatottak. Ezek a tulajdonságok mindig rendelkeznek null értékkel, és nem használhatók a WinUI-alkalmazásokban: CoreWindow, Currentés Dispatcher.

Az aktuális ablak nyomon követése

Annak ellenére, hogy a WinUI-alkalmazások nem támogatják a Current tulajdonságot, előfordulhat, hogy hozzá kell férnie az alkalmazás más részein található Window API-khoz. Előfordulhat például, hogy be kell szereznie a Window határokat, vagy kezelnie kell a Window.SizeChanged eseményt kódból egy Page-t. Ebben az esetben, akkor a hozzáférést a Window a Current tulajdonsághoz hasonlóan a App osztály nyilvános statikus tulajdonságával is megadhatja.

Ehhez módosítsa a Window deklarációt az App osztályban az itt látható módon.

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

Ezután a Window eléréséhez az alkalmazás más helyeiről használja a App.Window-et, az alábbi módon:

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

Fontos

Window Statikus tulajdonság használata az App osztályban akkor hasznos, ha az alkalmazás csak egyetlen ablakot használ. Ha az alkalmazás több ablakot használ, akkor a WindowsId használatával kövesse nyomon a Window példányokat, hogy biztosan a megfelelő példányhoz Windowférhessen hozzá. További információkért és példákért tekintse meg az alkalmazás több ablakának megjelenítése című témakört.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-03-11