WinUI 3 ve Windows Uygulama SDK'sı için pencereleme genel bakışı

WinUI uygulamasındaki pencereleme işlevi, her ikisi de Window temel alan XAML AppWindow sınıfı ve sınıfının bir bileşimi tarafından sağlanır.

• Önemli API'ler: Window sınıf, AppWindow sınıf

WinUI 3 Galeri uygulamasını açın ve pencereleme örneklerinin nasıl çalıştığını görün

WinUI 3 Galeri uygulaması, WinUI denetimlerinin ve özelliklerinin etkileşimli örneklerini içerir. uygulamayı Microsoft Store adresinden alın veya GitHub üzerindeki kaynak koduna göz atın.

XAML Window

Uygulamanızda pencere nesnesi, program kodunuzdaki pencereyi temsil eden Microsoft.UI.Xaml.Window sınıfının (veya türetilmiş bir sınıfın) bir örneğidir. Oluşturucuya bir çağrı ile doğrudan oluşturursunuz. XAML Window , uygulama içeriğinizi eklediğiniz ve uygulamanızın pencerelerinin yaşam döngüsünü yönettiğiniz yerdir.

HWND

Uygulama penceresi işletim sistemi tarafından Windows oluşturulur ve win32 pencere nesnesiyle temsil edilir. İçeriğinizin barındırıldığı sistem tarafından yönetilen bir kapsayıcıdır ve kullanıcıların uygulamanızı yeniden boyutlandırıp ekranda taşıdıkları zaman etkileşime geçtikleri varlığı temsil eder. (Daha fazla bilgi için Win32 belgelerindeki Hakkında Windows bölümüne bakın.)

Uygulama penceresi oluşturulduktan sonra Windows oluşturma işlevi, pencereyi benzersiz olarak tanımlayan bir window handle (HWND) döndürür. A window handle , HWND veri türüne sahiptir, ancak C# dilinde IntPtr olarak ortaya çıkar. İşletim sistemi tarafından çizilen ve mevcut olduğunda sistem kaynaklarını kullanan bir pencereye karşılık gelen iç Windows veri yapısına yönelik opak bir tanıtıcıdır.

HWND, XAML Window nesnesi oluşturulduktan sonra, genellikle Window.Etkinleştir yöntemi çağrıldığında oluşturulur.

AppWindow

Uygulama SDK'sı Windows, Microsoft.UI.Windowing.AppWindow sınıfı aracılığıyla ek pencere işlevi sağlar. AppWindow HWND'nin üst düzey soyutlamasını temsil eder. Uygulamanızdaki bir AppWindow ile en üst düzey HWND arasında 1:1 eşlemesi vardır. AppWindow ve ilgili sınıflar, HWND'ye doğrudan erişmenize gerek kalmadan, uygulamanızın üst seviye pencerelerinin birçok yönünü yönetmenize olanak tanıyan API'ler sağlar.

Bir AppWindow nesnenin ve HWND'nin ömrü aynıdır; AppWindow pencere oluşturulduktan hemen sonra kullanılabilir ve pencere kapatıldığında yok edilir.

Pencereleme API'si diyagramı

Bu diyagram, uygulamanızdaki pencereleri yönetmek için kullandığınız sınıflar ve API'ler arasındaki ilişkiyi ve pencere yönetiminin her bir bölümünden hangi sınıfların sorumlu olduğunu gösterir. Bazı durumlarda, ExtendsContentIntoTitleBar gibi, API AppWindow üyesidir ve diğer UI çerçeveleri için kullanılabilir hale getirilirken, kolaylık olması amacıyla Window sınıfında da kullanıma sunulur. Diyagram kapsamlı değildir, ancak en sık kullanılan API'leri gösterir.

Uyarı

AppWindow API'lerini Windows Uygulama SDK'sının desteklediği herhangi bir UI çerçevesiyle kullanabilirsiniz: Win32, WPF, WinForms veya WinUI. WinUI dışındaki çerçeveler için, diyagramın XAML Window kutusunda gösterilen işlevsellik, çerçeveye özgü uygun pencereleme API'leriyle değiştirilir:

• WPF Window
• Windows Formlar Formu
• Win32 pencereleme API'leri, MFC Windows

Window/AppWindow API karşılaştırması

Uygulamanızın kullanıcı arayüzü çerçevesi olarak WinUI XAML kullanıyorsanız, hem Window hem de AppWindow API'lerini kullanabilirsiniz. Uygulama SDK'sı 1.4'ten Windows başlayarak, var olan bir XAML penceresinden Windownesne almak için özelliğiniAppWindow kullanabilirsiniz.AppWindow Bu AppWindow nesnesiyle ek pencere yönetimi API'lerine erişiminiz olur.

Önemli

WinUI 1.3 veya sonraki bir sürümü kullanmıyorsanız, AppWindow API'lerini kullanabilmek için AppWindow birlikte çalışma API'lerini edinin. Birlikte çalışma API'leri hakkında daha fazla bilgi için, Uygulama pencerelerini yönetme - UI çerçevesi ve HWND çalışması ve Pencereleme galeri örneği'ne bakın.

Yaşam süresi yönetimi

XAML Window	AppWindow
Yapıcı	Oluşturma, GetFromWindowId
Etkinleştir	Göster, Gizle
Kapat, Kapalı	Yok Et, Yok Etme Süreci, Kapatma
>>>	Id, OwnerWindowId

Visual Studio'de yeni bir WinUI project oluşturduğunuzda, project şablonu sizin için MainWindow alt sınıfı olan bir Window sınıfı sağlar. Uygulamanızın yalnızca bir pencereye ihtiyacı varsa, ihtiyacınız olan tek şey budur. Ek pencerelerin nasıl oluşturulup yönetileceğini ve neden bunu yapmak isteyebileceğinizi öğrenmek için bkz. Uygulamanız için birden çok pencere gösterme.

Sınıfın AppWindow yeni bir pencere oluşturup yok etmek için API'leri vardır; ancak bir WinUI uygulaması için oluşturduğunuz pencereye içerik eklemek için API olmadığından bunu pratikte yapmazsınız. Bunun yerine, sistem tarafından oluşturulan ve XAML AppWindow ve HWND ile ilişkili bir Window örneği alırsınız. WinUI 1.4 ve sonraki sürümlerinde Window.AppWindow özelliğini kullanarak AppWindow örneğini alabilirsiniz. Diğer durumlarda, AppWindow.GetFromWindowId yöntemini kullanarak AppWindow örneğini alabilirsiniz. Daha fazla bilgi için bkz. Uygulama pencerelerini yönetme .

Content

XAML Window	AppWindow
Content	Yok

.Window content özelliği, uygulama içeriğinizi görüntüleyen pencereye eklediğiniz yerdir. Bunu XAML'de veya kodda yapabilirsiniz.

Başlık, simge ve başlık çubuğu

XAML Window	AppWindow
Başlık	Başlık
SetTitleBar	TitleBar
>>>	SetIcon, SetTaskbarIcon, SetTitleBarIcon
Başlık Çubuğuna İçeriği Genişletir	AppWindow.TitleBar.ExtendsContentIntoTitleBar

Uygulamanızın başlık çubuğunu değişen derecelerde değiştirebilirsiniz; başlığı ve simgeyi ayarlama, renkleri değiştirme veya başlık çubuğunu tamamen özel uygulama içeriğiyle değiştirme.

Kod örnekleri de dahil olmak üzere başlık çubuğu API'lerini kullanma hakkında bilgi için bkz. Başlık çubuğu özelleştirme.

Boyut ve konum

XAML Window	AppWindow
Sınır -ları	Konum, Boyut, İstemciBoyutu
BoyutDeğişken	Değiştirildi (DidPositionChange, DidSizeChange)
>>>	Taşı, Yeniden Boyutlandır, ResizeClient, MoveAndResize
>>>	MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInZOrderBelow

Siz veya uygulamanın kullanıcı arabirimi yönetiminde, pencere boyutu değiştiğinde öğeleri taşımak gibi işlemleri gerçekleştirmek için Window.Bounds özelliğini ve SizeChanged olayını kullanırsınız. XAML, gerçek fiziksel pikseller yerine effective pixels (epx) kullanır. Effective pixels sanal bir ölçü birimidir ve ekran yoğunluğundan bağımsız olarak düzen boyutlarını ve aralığını ifade etmek için kullanılır.

AppWindowise, temel ölçü biriminin Windowfiziksel cihaz pikselleri olduğu Koordinat Sistemi'ni kullanır. Pencereyi yeniden boyutlandırma veya ekrandaki başka bir şeye göre taşıma gibi pencere yönetimi faaliyetleri için AppWindow API'lerini kullanırsınız.

Bazı durumlarda, bir sınıftaki ölçümleri diğer sınıfta kullanmanız gerekebilir; bu durumda effective pixels ve cihaz pikselleri arasında dönüştürme yapmanız gerekir. Örneğin, özel başlık çubuğunda sürükleme bölgeleri ayarlarsanız ölçümleri dönüştürmeniz gerekir. Ölçümleri dönüştürmek için XamlRoot.RasterizationScale kullanma örneği için Başlık çubuğu özelleştirme makalesinin etkileşimli içerik bölümüne bakın.

Görünüm ve davranış

XAML Window	AppWindow
SystemBackdrop	Yok
>>>	Sunucu, SetPresenter
>>>	IsShownInSwitchers
Görünür, GörünürlükDeğiştirildi	IsVisible, Değiştirildi (GörünürlükDeğiştiMi)
DispatcherQueue	DispatcherQueue, AssociateWithDispatcherQueue
Compositor	Yok

XAML Window API'leri genellikle arka plan gibi uygulama içeriğinizin görünümünden sorumludur. SystemBackdrop hakkında daha fazla bilgi için bkz. Mika veya Akrilik malzemeleri uygulama.

AppWindow API'ler pencerenin istemci olmayan kısmından ve uygulamanızın işletim sistemiyle etkileşimlerinden Windows sorumludur.

Uyarı

XAML Window sınıfı, UWP Windows.UI.Xaml.Window sınıfından taşınan çeşitli özelliklere sahiptir, ancak WinUI uygulamalarında desteklenmez. Bu özelliklerin her zaman bir null değeri vardır ve WinUI uygulamalarında kullanılmaz: CoreWindow, Currentve Dispatcher.

Geçerli pencereyi izleme

Current özelliği WinUI uygulamalarında desteklenmese de, uygulamanızın başka bölümlerinden Window API'lerine erişmeniz gerekebilir. Örneğin, bir Window için koddan Window sınırları almanız veya SizeChanged olayını ele almanız gerekebilir. Bu durumda, App sınıfınızda bir genel statik özellik kullanarak Current özelliğine benzer şekilde Window erişimi sağlayabilirsiniz.

Bunu yapmak için, burada gösterildiği gibi Uygulama sınıfındaki Window bildirimini değiştirin.

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

Ardından, uygulamanızdaki diğer yerlerden Window öğesine erişmek için App.Window kullanın.

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

Önemli

Sınıfınızda Window statik App bir özellik kullanmak, uygulamanız yalnızca tek bir pencere kullanıyorsa kullanışlıdır. Uygulamanız birden çok pencere kullanıyorsa, doğru örneğine eriştiğinizden emin olmak için Window kullanarak Window örneklerini izlemelisiniz. Daha fazla bilgi ve örnek için bkz. Uygulamanız için birden çok pencere gösterme .

İlgili konular

• Uygulama pencerelerini yönetme
• Windowing işlevsellik geçişi
• .NET uygulamasından birlikte çalışabilirlik API'lerini çağır
• Bir window handle (HWND) al
• Windowing galeri örneği