WinUI 3 と App SDK のウィンドウの概要

WinUI アプリのウィンドウ機能は、XAML クラスと クラスの組み合わせによって提供されます。どちらも Win32 HWND モデルに基づいています。

WinUI 3 ギャラリー アイコン

WinUI 3 ギャラリー アプリには、WinUI コントロールと機能の対話型の例が含まれています。 Microsoft Store からアプリを取得するか、GitHub でソース コードを参照します。

Xaml

アプリでは、ウィンドウ オブジェクトは、プログラム コード内のウィンドウを表す Microsoft.UI.Xaml. クラス (または派生クラス) のインスタンスです。 コンストラクターを呼び出して直接作成します。 XAML では、アプリのコンテンツをアタッチし、アプリのウィンドウのライフサイクルを管理します。

HWND

アプリケーション ウィンドウは、 オペレーティング システムによって作成され、Win32 ウィンドウ オブジェクトによって表されます。 これは、コンテンツがホストされるシステム管理コンテナーであり、ユーザーが画面上でアプリのサイズを変更して移動するときに操作するエンティティを表します。 (詳細については、Win32 ドキュメントの「について」を参照してください)。

アプリケーション ウィンドウ 作成した後、作成関数はウィンドウを一意に識別する () を返します。 には HWND データ型がありますが、C# では IntPtr として表示されます。 これは、OS によって描画され、存在するときにシステム リソースを消費するウィンドウに対応する内部の データ構造への不透明なハンドルです。

HWND は、XAML オブジェクトの後に作成されます。通常は .Activate メソッドが呼び出される際に作成されます。

AppWindow

App SDK は、Microsoft.UI.Windowing. クラスを通じて追加のウィンドウ機能を提供します。 は、HWND の高度な抽象化を表します。 アプリの と最上位の HWND の間には、1 対 1 のマッピングがあります。 AppWindow とそれに関連するクラスは、HWND を直接accessすることなく、アプリのトップレベル ウィンドウのさまざまな側面を管理できる API を提供します。

オブジェクトと HWND の有効期間は同じです。はウィンドウが作成された直後に使用でき、ウィンドウが閉じられると破棄されます。

ウィンドウ化 API の図

この図は、アプリでウィンドウを管理するために使用するクラスと API の関係と、ウィンドウ管理の各部分を担当するクラスを示しています。 場合によっては、 のように、API は他の UI フレームワークで使用できるようにするための のメンバーですが、便宜上、 クラスでも公開されます。 この図は包括的ではありませんが、最も一般的に使用される API を示しています。

Win UI ウィンドウダイアグラム

/ API の比較

WinUI XAML をアプリの UI フレームワークとして使用する場合は、 API と API の両方を使用できます。 App SDK 1.4 以降では、. プロパティを使用して、既存の XAML ウィンドウから オブジェクトを取得できます。 このAppWindow オブジェクトを使用すると、追加のウィンドウ管理 API にアクセスできます。

有効期間管理

Visual Studioで新しい WinUI projectを作成すると、project テンプレートは MainWindow クラスを提供します。これは、Window のサブクラスです。 アプリに必要なウィンドウが 1 つだけの場合は、これですべて必要になります。 追加のウィンドウを作成および管理する方法と、必要な理由については、「 アプリに複数のウィンドウを表示する」を参照してください。

クラスには、新しいウィンドウを作成および破棄するための API があります。ただし、WinUI アプリの場合は、作成するウィンドウにコンテンツをアタッチする API がないため、実際にはこれを行いません。 代わりに、システムによって作成され、XAML と HWND に関連付けられているのインスタンスを取得します。 WinUI 1.4 以降では、 . プロパティを使用して、 のインスタンスを取得できます。 他のケースでは、.GetFromWindowId メソッドを使用して インスタンスを取得できます。 詳細については、「 アプリ ウィンドウの管理 」を参照してください。

Content

。Content プロパティは、アプリコンテンツを表示するウィンドウに添付する場所です。 これは XAML またはコードで行うことができます。

タイトル、アイコン、タイトル バー

アプリのタイトル バーをさまざまな角度に変更できます。タイトルとアイコンの設定、色の変更、またはタイトル バーをカスタム アプリ コンテンツに完全に置き換えます。

コード例を含むタイトル バー API の使用については、「 タイトル バーのカスタマイズ」を参照してください。

サイズと位置

アプリの UI 内で、.Bounds プロパティと SizeChanged イベントを使用して、ウィンドウ サイズが変更されたときに要素の移動などの管理を行います。 XAML では、実際の物理ピクセルではなく (epx) が使用されます。 は仮想測定単位であり、画面密度に関係なく、レイアウトの寸法と間隔を表すために使用されます。

一方、基本的な測定単位は物理である座標系を使用します。 ウィンドウのサイズを変更したり、画面上の他の何かに関連して移動したりするなどのウィンドウ操作には、 API を使用します。

場合によっては、他のクラスの 1 つのクラスの測定値を使用する必要がある場合があります。その場合は、 ピクセルとデバイス ピクセルの間で変換する必要があります。 たとえば、カスタム タイトル バーでドラッグ領域を設定する場合は、測定値を変換する必要があります。 XamlRoot.RasterizationScale を使用して測定値を変換する方法の例については、タイトル バーのカスタマイズに関する記事の対話型コンテンツセクションを参照してください。

外観と動作

XAML API は、一般に、バックグラウンドなどのアプリ コンテンツの外観を担当します。 SystemBackdrop の詳細については、「マイカまたはアクリル素材を適用する」を参照してください。

API は、ウィンドウの クライアント以外 の部分と、 OS とのアプリの対話を担当します。

現在のウィンドウを追跡する

WinUI アプリでは Current プロパティはサポートされていませんが、アプリ内の他の場所から Window API をaccessしなければならない場合があります。 たとえば、 境界の取得が必要になる場合や、 のコードから .SizeChanged イベントの処理が必要になる場合があります。 この場合、Window クラスのパブリック静的プロパティを使用して、Current プロパティと同様の方法で、App にaccessを指定できます。

次に示すように、App クラスの Window 宣言を変更してください。

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

次に、アプリ内の他の場所から Window をaccessするには、次のように 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 };

関連トピック

• アプリ ウィンドウの管理
• ウィンドウ機能の移行
• .NET アプリから相互運用 API を呼び出します
• (HWND) を取得する
• ウィンドウ ギャラリーのサンプル