WinUI ve Windows Uygulama SDK'sı için pencereye 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ı çoğu WinUI 3 denetimi, özelliği ve işlevselliğine ilişkin etkileşimli örnekler içerir. Uygulamayı Microsoft Store'dan alın veya GitHub'dan kaynak kodunu alı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şmeye gerek kalmadan uygulamanızın üst düzey pencerelerinin birçok yönünü yönetmenize olanak sağlayan 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ı

API'leri, Uygulama SDK'sının AppWindow desteklediği herhangi bir UI çerçevesiyle kullanabilirsinizWindows: Win32, WPF, WinForms veya WinUI 3. WinUI 3 dışındaki çerçeveler için, diyagramın XAML Window kutusunda gösterilen işlevsellik uygun çerçeveye özgü 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 UI çerçevesi olarak WinUI 3 XAML kullanıyorsanız hem hem Window de AppWindow API'leri 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 nesneyle ek pencere yönetimi API'lerine erişiminiz vardır.

Önemli

WinUI 3 1.3 veya daha yeni bir sürümünü kullanmıyorsanız, AppWindow API'lerini kullanmak için AppWindow almak üzere birlikte çalışma API'lerini kullanın. Birlikte çalışma API'leri hakkında daha fazla bilgi için bkz. Uygulama pencerelerini yönetme - UI çerçevesi ve HWND birlikte çalışma ve Pencereleme galerisi örneği.

Yaşam süresi yönetimi

XAML Window	AppWindow
Constructor	Oluşturma, GetFromWindowId
Activate	Göster, Gizle
Kapat, Kapat	Yok Et, Yok Etme Süreci, Kapatma
>>>	Id, OwnerWindowId

Visual Studio'da yeni bir WinUI projesi oluşturduğunuzda, proje şablonu sizin için MainWindow'in 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
ExtendsContentIntoTitleBar	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

Özellik Current WinUI uygulamalarında desteklenmese bile, uygulamanızdaki Window diğer yerlerdeki API'lere 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, sınıfınızdaki genel statik bir özellik kullanarak Window özelliğine benzer bir şekilde Current erişimi sağlayabilirsinizApp.

Bunu yapmak için, burada gösterildiği gibi Window bildirimini Uygulama sınıfında 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 erişmek için, şunu kullanarak: App.Window

// 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
• Pencereleme işlevselliğinin taşınması
• Bir .NET uygulamasından birlikte çalışma API'lerini çağırın
• Bir window handle (HWND) al
• Pencereleme galerisi örneği