Hantera appfönster

Windows App SDK tillhandahåller klassen Microsoft.UI.Windowing.AppWindow som representerar en abstraktion på hög nivå av HWND. Det finns en 1:1-mappning mellan en AppWindow och en HWND på toppnivå i din app. AppWindow och dess relaterade klasser tillhandahåller API:er som gör att du kan hantera många aspekter av appens toppnivåfönster utan att behöva komma åt HWND direkt.

WinUI 3-galleriappen innehåller interaktiva exempel på de flesta WinUI 3-kontroller, funktioner och funktioner. Hämta appen från Microsoft Store eller hämta källkoden på GitHub

Du kan använda AppWindow API:er med valfritt gränssnittsramverk som Windows App SDK stöder – WinUI 3, WPF, WinForms eller Win32. AppWindow API:er fungerar tillsammans med ramverksspecifika fönster-API:er:

• XAML Window
• WPF Window
• Formulärformulär för Windows
• Win32-fönster-API:er, MFC Windows

Du använder vanligtvis AppWindow API:er för att:

• Hantera storleken och positionen för appens fönster.

• Hantera fönsterrubriken, ikonen och titelradens färg; eller skapa en helt anpassad titelrad med AppWindowTitleBar-API:er.

  Mer information och exempel finns i Anpassning av namnlist .

• Hantera fönstrets utseende och beteende med AppWindowPresenter-härledda API:er.

AppWindow Svara på ändringar

Du svarar på ändringar i AppWindow genom att hantera den enda Changed-händelsen och kontrollerar sedan händelseargument (AppWindowChangedEventArgs) för att avgöra vilken typ av ändring som skedde. Om ändringen som du är intresserad av har skett kan du svara på den. Potentiella ändringar inkluderar position, storlek, presentatör, synlighet och z-ordning.

Här är ett exempel på en AppWindow.Changed händelsehanterare.

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 storlek och placering

Klassen AppWindow har flera egenskaper och metoder som du kan använda för att hantera fönstrets storlek och placering.

Anropa Ändra storlek för att ange en ny fönsterstorlek.

I det här exemplet finns koden i MainWindow.xaml.cs, så du kan använda Windowegenskapen .AppWindow för att hämta instansen AppWindow .

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

Anropa metoden Flytta för att ändra positionen för ett fönster.

I det här exemplet flyttas fönstret så att det centreras på skärmen när användaren klickar på en knapp.

Detta inträffar i kodfilen för en sidklass , så att du inte automatiskt har åtkomst till objekten Window eller AppWindow . Du har några alternativ för att hämta AppWindow.

• Om du behåller en referens till Window enligt beskrivningen i Spåra det aktuella fönstret eller Spåra instanser av Window, kan du först hämta Window och sedan AppWindow från Window-egenskapen.AppWindow
• Eller så kan du anropa den statiska AppWindow. GetFromWindowId-metoden för att hämta instansen AppWindow , som du ser här. (Se Fastställa vilket fönster som är värd för ett visuellt element.)

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

Klassen AppWindowPresenter och underklasserna

Var och AppWindow en har en AppWindowPresenter (presentatör) tillämpad på den. En presentatör skapas av systemet och tillämpas på en AppWindow när den skapas. Varje underklass av AppWindowPresenter tillhandahåller en fördefinierad konfiguration som är lämplig för fönstrets syfte. Dessa AppWindowPresenter-härledda presentatörer tillhandahålls och de är tillgängliga för alla operativsystemversioner som stöds.

• CompactOverlayPresenter

  Konfigurerar ett alltid-på-topp-fönster med en fast storlek och en proportion på 16:9 för att möjliggöra upplevelser som liknar bild-i-bild. Som standard är InitialSizeCompactOverlaySize.Small, men du kan ändra den till Medium eller Large. Du kan också anropa AppWindow. Ändra storlek för att åsidosätta proportionerna 16:9 och gör fönstret till önskad storlek.

• FullScreenPresenter

  Konfigurerar ett fönster för att ge en helskärmsmiljö som passar för att titta på video. Fönstret har ingen kantlinje eller namnlist och döljer systemaktivitetsfältet.

• OverlappedPresenter

  Standardfönstrets konfiguration, som standard ger en ram med storlekshandtag och en titelrad med knapparna minimera/maximera/återställa.

Förvald presentatör

Standardpresentatören som används när en AppWindow skapas är en instans av OverlappedPresenter med standardegenskaper. Det finns ingen anledning att behålla en referens till den för att gå tillbaka till standardpresentatören för ett fönster efter att ha tillämpat en annan presentatör. Det beror på att systemet behåller samma instans av denna presentatör under hela livslängden av AppWindow för vilken den skapades; och du kan återigen tillämpa den genom att anropa AppWindow.SetPresenter-metod med AppWindowPresenterKind.Default som parameter.

Du kan också hämta en referens till standardinstansen för presentatören och ändra den. Om du har tillämpat en ny presentatör kontrollerar du först att standardpresentatören tillämpas, som du ser här:

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

Ändra en OverlappedPresenter

OverlappedPresenter är en flexibel presentatör som du kan konfigurera på flera olika sätt.

Med Create* -metoderna kan du skapa en överlappande presentatör med standardegenskaper, eller en med egenskapsinställningar förkonfigurerade för en viss användning.

Den här tabellen visar hur konfigurationsegenskaper anges när du skapar ett OverlappedPresenter-objekt från varje metod.

Den använda presentatören är ett levande objekt. En ändring av en egenskap hos .Presenter-objektet träder i kraft omedelbart. Det finns inga händelser som meddelar dig om dessa ändringar, men du kan kontrollera egenskaperna för aktuella värden när som helst.

Egenskaperna HasBorder och HasTitleBar är skrivskyddade. Du kan ange dessa värden genom att anropa metoden SetBorderAndTitleBar (SetBorderAndTitleBar(bool hasBorder, bool hasTitleBar)). En OverlappedPresenter kan inte ha en titelrad utan kantlinje. Om parametern hasTitleBar är truemåste parametern hasBorder alltså också vara true. Annars genereras ett undantag med det här meddelandet:

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

Ange IsMaximizable till false för att dölja maximeringsknappen i verktygsfältet. Vi rekommenderar att du gör detta om du anger PreferredMaximumHeight egenskaperna eller PreferredMaximumWidth eftersom dessa egenskaper begränsar fönsterstorleken även i maximerat tillstånd. Detta påverkar inte anrop till metoden Maximera .

Ange IsMinimizable till false för att dölja minimera-knappen i verktygsfältet. Detta påverkar inte anrop till metoden Minimera .

Ange IsResizable till för att false dölja storlekskontrollerna och förhindra att användaren ändrar storlek på fönstret. Detta påverkar inte anrop till AppWindow.Resize-metoden.

Ange IsAlwaysOnTop till true för att hålla det här fönstret ovanpå andra fönster. Om du anropar någon av AppWindow.MoveInZOrder* metoderna börjar de fortfarande gälla för att ändra z-ordningen för fönstret även om den här egenskapen är true.

Ange PreferredMaximumHeight och PreferredMaximumWidth för att begränsa den maximala storlek som användaren kan sträcka fönstret till. Vi rekommenderar att du ställer in IsMaximizable till false om du anger de maximala storleksegenskaperna, eftersom dessa egenskaper begränsar fönsterstorleken även när det är maximerat. Dessa egenskaper påverkar även anrop till AppWindow. Ändra storlek; fönstret ändras inte större än den angivna maximala höjden och bredden.

Ange PreferredMinimumHeight och PreferredMinimumWidth för att ange den minsta storlek som användaren kan krympa fönstret till. Dessa egenskaper påverkar även anrop till AppWindow. Ändra storlek; fönstret ändras inte mindre än den angivna minimihöjden och bredden.

Modala fönster

Du kan ange IsModal till true för att skapa ett modalt fönster. Ett modalt fönster är ett separat fönster som blockerar interaktionen med dess ägarfönster tills det stängs. Men om du vill skapa ett modalt fönster måste du också ange ägarfönstret. annars utlöses ett undantag med det här meddelandet:

The parameter is incorrect.

The window should have an owner when IsModal=true.

För att ställa in ägarfönstret i en WinUI-app krävs Win32-interop. Mer information och exempelkod finns på AppWindow sidan i WinUI Gallery-exempelappen.

• Starta WinUI Galleri-appen
• Öppna ModalWindow.xaml.cs på GitHub

Tillämpa en presentatör

En presentatör kan endast tillämpas på ett enda fönster i taget. Om du försöker använda samma presentatör i ett andra fönster genereras ett undantag. Det innebär att om du har flera fönster och vill växla var och en till ett specifikt presentationsläge måste du skapa flera presentatörer av samma slag och sedan tillämpa var och en på sitt eget fönster.

När en ny presentatör tillämpas (presentatörsegenskapen AppWindow. ändras) meddelas din app av en AppWindow.Changed-händelse på den berörda AppWindow, med egenskapen AppWindowChangedEventArgs.DidPresenterChange inställd på true.

Det här exemplet visar hur du gör följande:

• AppWindowAnvänd . Presentatörsegenskap för att hämta den aktuella presentatören.
• Använd egenskapen AppWindowPresenter.Kind för att kontrollera vilken typ av konfiguration som tillämpas för närvarande.
• Ring AppWindow. SetPresenter för att ändra den aktuella konfigurationen.

Här skapas, modifieras och tillämpas en presentatör i konstruktorn för fönstret.

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

På sidan som är fönstrets innehåll kan du hämta en referens till AppWindow och den tillämpade presentatören.

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

UI Framework och HWND interop

Klassen AppWindow är tillgänglig för alla HWND på toppnivå i din app. Det innebär att när du arbetar med ett skrivbordsgränssnittsramverk (inklusive WinUI 3) kan du fortsätta att använda ramverkets startpunkt för att skapa ett fönster och koppla dess innehåll. Och när du har skapat ett fönster med det användargränssnittsramverket kan du använda interop-funktionerna för fönster (se nedan) i Windows App SDK för att få åtkomst till motsvarande AppWindow metoder, egenskaper och händelser.

Några av fördelarna med att använda AppWindow (även när du arbetar med ett gränssnittsramverk) är:

• Enkel anpassning av namnlist; som standard behåller Windows 11:s användargränssnitt (rundade hörn, popup-fönster för snapgrupper).
• Systembaserad helskärms- och kompakt överläggsupplevelse (bild-i-bild).
• API-ytan för Windows Runtime (WinRT) täcker några av de grundläggande Win32-fönsterbegreppen.

Hämta AppWindow för versioner av Windows App SDK före 1.3 (eller andra ramverk för skrivbordsappar)

Egenskapen Window.AppWindow är tillgänglig i Windows App SDK version 1.3 och senare. För tidigare versioner kan du använda det funktionellt likvärdiga kodexemplet i det här avsnittet.

C#. .NET-omslag för interop-funktionerna för fönster implementeras som metoder i klassen Microsoft.UI.Win32Interop. Se även Anropa interop-API:er från en .NET-app.

C++. Interop-funktionerna definieras i winrt/Microsoft.ui.interop.h huvudfil.

I kodexemplet nedan visas den faktiska källkoden. men här är receptet för att hämta ett AppWindow objekt givet ett befintligt fönster:

1. Hämta HWND för ditt befintliga fönsterobjekt (för ditt gränssnittsramverk) om du inte redan har det.
2. Skicka HWND till funktionen GetWindowIdFromWindow interop för att hämta ett WindowId.
3. Skicka WindowId till den statiska AppWindow.GetFromWindowId-metoden för att hämta 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!");
    }
}

Fler exempel på hur du arbetar med AppWindow finns i exemplet för fönstergalleriet.

Limitations

Windows App SDK tillhandahåller för närvarande inte metoder för att koppla UI Framework-innehåll till en AppWindow.

Relaterade ämnen

• Översikt över fönster
• Anpassning av namnlist
• Migrering av fönsterfunktionalitet
• Anropa interop-API:er från en .NET-app
• Hämta ett fönsterhandtag (HWND)
• exempel på fönstergalleri