ウィンドウ機能の移行
このトピックでは、UWP の ApplicationView/CoreWindow または AppWindow から Windows App SDK の Microsoft.UI.Windowing.AppWindow への移行を含め、ウィンドウ管理に関連するガイダンスを示します。
重要な API
- Microsoft.UI.Windowing.AppWindow
- Windows.UI.Core.CoreWindow.Dispatcher プロパティ
- Microsoft.UI.Window.DispatcherQueue プロパティ
API と機能の違いの概要
Windows App SDK には、Win32 HWND モデルをベースにした Microsoft.UI.Windowing.AppWindow クラスが用意されています。 その AppWindow クラスは、UWP の ApplicationView/CoreWindow および AppWindow の Windows App SDK バージョンです。
Windows App SDK ウィンドウ設定 API を利用するには、Win32 モデルを使用するように UWP コードを移行する必要があります。 Windows App SDK の AppWindow の詳細については、「アプリ ウィンドウの管理」を参照してください。
ヒント
アプリ ウィンドウの管理のトピックには、WinUI 3 ウィンドウから AppWindow を取得する方法を示すコード サンプルが含まれています。 WinUI 3 アプリでは、このコード パターンを使用して、このトピックの残りの部分で説明されている AppWindow API を呼び出すことができます。
UWP と Windows App SDK のウィンドウの種類
UWP アプリでは、ApplicationView/CoreWindow、または AppWindow を使用してウィンドウ コンテンツをホストすることができます。 そのコードを Windows App SDK に移行するために必要な作業は、それら 2 つのウィンドウ モデルのうち、どちらを UWP アプリで使用しているかによって異なります。 UWP の Windows.UI.WindowManagement.AppWindow を使い慣れている場合は、それと Microsoft.UI.Windowing.AppWindow の間に類似点があることがわかるでしょう。
UWP のウィンドウの種類
- Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow。
- Windows.UI.WindowManagement.AppWindow。 AppWindow は、UI スレッドと、アプリでコンテンツの表示に使用するウィンドウを統合します。 AppWindow を使用している UWP アプリは、ApplicationView/CoreWindow のアプリよりも、Windows App SDK AppWindow への移行のために必要な作業が少なくて済みます。
Windows App SDK のウィンドウの種類
- Microsoft.UI.Windowing.AppWindow は、アプリのコンテンツのシステム マネージド コンテナーを表す高水準の抽象化です。
UWP と Win32 のウィンドウ モデルの違いとして、UWP API サーフェスと Windows App SDK API サーフェスの間には直接的な 1 対 1 の対応がないことに注意してください。 UWP から "引き継がれた" クラス名とメンバー名 (このトピックの対応表に反映されています) の場合でも、動作が異なる場合があります。
スプラッシュ画面
Win32 アプリでは、UWP アプリとは異なり、既定では起動時にスプラッシュ スクリーンが表示されません。 起動エクスペリエンスがこの機能に依存する UWP アプリの場合、最初のアプリ ウィンドウへのカスタム切り替えの実装を選択できます。
ウィンドウの作成、表示、閉じる、破棄
Microsoft.UI.Windowing.AppWindow の有効期間は、HWND の場合と同じです。つまり、AppWindow オブジェクトは、ウィンドウが作成された直後に使用可能になり、ウィンドウが閉じられたときに破棄されます。
作成と表示
AppWindow.Create は、既定の構成を使用してアプリ ウィンドウを作成します。 ウィンドウの作成と表示は、UI フレームワークを使用していないシナリオの場合にのみ必要です。 UWP アプリを Win32 と互換性のある UI フレームワークに移行する場合には、ウィンドウ相互運用メソッドを使用すれば、既に作成済みのウィンドウから引き続き AppWindow オブジェクトにアクセスできます。
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows App SDK |
|---|---|---|
| CoreApplication.CreateNewView または CoreWindow.GetForCurrentThread |
AppWindow.TryCreateAsync | AppWindow.Create |
| CoreWindow.Activate | AppWindow.TryShowAsync | AppWindow.Show |
閉じる
UWP では、ApplicationView.TryConsolidateAsync は、ユーザーが閉じるジェスチャを開始するのとプログラム的に同等です。 "統合" というこの概念 (UWP の ApplicationView/CoreWindow ウィンドウ モデル) は、Win32 には存在しません。 Win32 では、ウィンドウが分離スレッドに存在する必要はありません。 UWP の ApplicationView/CoreWindow ウィンドウ モデルを再現するには、開発者は新しいスレッドを作成し、そこで新しいウィンドウを作成する必要があります。 Win32 モデルの場合、既定のシステム動作は閉じる>非表示>破棄です。
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows App SDK |
|---|---|---|
| ApplicationView.TryConsolidateAsync | AppWindow.CloseAsync | AppWindow.Destroy |
ウィンドウの基本的なカスタマイズ
UWP から Windows App SDK に移行するときは、既定の AppWindow で同じエクスペリエンスを想定できます。 ただし必要に応じて、カスタマイズされたウィンドウ エクスペリエンスのために既定の Microsoft.UI.Windowing.AppWindow を変更できます。 ウィンドウをカスタマイズする方法の詳細については、「Microsoft.UI.Windowing.AppWindow」を参照してください。
ウィンドウのサイズ変更
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows App SDK |
|---|---|---|
| ApplicationView.TryResizeView | AppWindow.RequestSize | AppWindow.Resize |
CoreWindow.Bounds (C# では一般的に CoreWindow.GetForCurrentThread.Bounds として示されます) |
AppWindowPlacement.Size | AppWindow.Size |
ウィンドウの配置
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows App SDK |
|---|---|---|
| 不可能 | AppWindow.GetPlacement | AppWindow.Position |
| 不可能 | Appwindow.RequestMoveXxx | AppWindow.Move |
ウィンドウのタイトル
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows App SDK |
|---|---|---|
| ApplicationView.Title | AppWindow.Title | AppWindow.Title |
コンパクト オーバーレイと全画面
コンパクト オーバーレイまたは全画面への切り替えを行うアプリでは、Windows App SDK の AppWindowPresenter を活用すると便利です。 UWP の AppWindow を使い慣れている場合は、既にプレゼンターの概念をご存じかもしれません。
UWP アプリ ウィンドウのプレゼンターと Windows App SDK アプリ ウィンドウのプレゼンターは、機能と動作が 1 対 1 に対応していません。 UWP ApplicationView/CoreWindow アプリを使用している場合、アプリでコンパクト オーバーレイ (ピクチャ イン ピクチャ) または全画面ウィンドウ エクスペリエンスを引き続き提供できますが、プレゼンターの概念はおそらく初めて知るものでしょう。 アプリ ウィンドウのプレゼンターの詳細については、「プレゼンター」を参照してください。 既定では、重複するプレゼンターが作成時に AppWindow に適用されます。 CompactOverlay と FullScreen は、既定のもの以外で使用可能な唯一のプレゼンターです。
コンパクト オーバーレイ
UWP の ApplicationViewMode または AppWindowPresentionKind を使用してコンパクト オーバーレイ ウィンドウを表示していた場合は、コンパクト オーバーレイの AppWindowPresenterKind を使用する必要があります。 Microsoft.UI.Windowing.CompactOverlayPresenter は、縦横比 16:9 の 3 つの固定ウィンドウ サイズのみをサポートしており、ユーザーはサイズを変更できません。 AppWindow の表示を変更するには、ApplicationViewMode.TryEnterViewModeAsync または AppWindowPresenterKind.RequestPresentation ではなく、AppWindow.SetPresenter を使用する必要があります。
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows App SDK |
|---|---|---|
| ApplicationViewMode.CompactOverlay | AppWindowPresentationKind.CompactOverlay | AppWindowPresenterKind.CompactOverlay |
| ApplicationView.TryEnterViewModeAsync と ApplicationViewMode.CompactOverlay | AppWindowPresenter.RequestPresentation と AppWindowPresenterKind.CompactOverlay | AppWindow.SetPresenter と AppWindowPresenterKind.CompactOverlay |
全画面
UWP の ApplicationViewWindowingMode または AppWindowPresentionKind クラスを使用して全画面ウィンドウを表示していた場合は、全画面の AppWindowPresenterKind を使用する必要があります。 Windows App SDK は、最も制限の厳しい全画面エクスペリエンス (つまり、FullScreen が IsExclusive の場合) のみをサポートしています。 ApplicationView/CoreWindow の場合は、ApplicationView.ExitFullScreenMode を使用してアプリの全画面表示を解除することができます。 プレゼンターを使用する場合は、アプリの全画面表示を解除するには、AppWindow.SetPresenter を使用して、プレゼンターの設定をオーバーラップまたは既定に戻します。
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows App SDK |
|---|---|---|
| ApplicationViewWindowingMode.FullScreen | AppWindowPresentationKind.FullScreen | AppWindowPresenterKind.FullScreen |
| ApplicationView.TryEnterFullScreenMode | AppWindowPresenter.RequestPresentation と AppWindowPresenterKind.FullScreen | AppWindow.SetPresenter と AppWindowPresenterKind.FullScreen |
アプリ ウィンドウのプレゼンターを操作する方法の詳細については、「ウィンドウ ギャラリーのサンプル」を参照してください。 さまざまなアプリ ウィンドウ プレゼンターの状態を切り替える方法を示しています。
カスタム タイトル バー
注意
現在、タイトル バー カスタマイズ API は Windows 11 でのみ機能します。 これらの API を呼び出す前に、コードで AppWindowTitleBar.IsCustomizationSupported を確認することをお勧めします。
アプリで既定のタイトル バーを使用している場合は、Win32 に移行するときに、タイトル バーに関する追加の作業は必要ありません。 一方、UWP アプリでカスタム タイトル バーを使用している場合は、Windows App SDK アプリで次のシナリオを再作成することができます。
- システムによって表示されるタイトル バーをカスタマイズする
- アプリで表示するカスタム タイトル バー
UWP の ApplicationViewTitleBar、CoreApplicationViewTitleBar、AppWindowTitleBar クラスを使用しているコードは、Windows App SDK の Microsoft.UI.Windowing.AppWindowTitleBar クラスを使用するように移行します。
システムによって表示されるタイトル バーをカスタマイズする
色のカスタマイズ API の表を次に示します。
注意
AppWindowTitleBar.ExtendsContentIntoTitleBar が true の場合、透明性は次のプロパティに対してのみサポートされます: AppWindowTitleBar.ButtonBackgroundColor、AppWindowTitleBar.ButtonInactiveBackgroundColor、AppWindowTitleBar.ButtonPressedBackgroundColor、AppWindowTitleBar.ButtonHoverBackgroundColor、AppWindowTitleBar.BackgroundColor (暗黙的に設定されます)。
次の Windows App SDK API は、AppWindow.Title API に加えて、システムによって表示されるタイトル バーをさらにカスタマイズするためのものです。
- AppWindow.SetIcon。 hIcon ハンドルを使用するか、リソースまたはファイルへの文字列パスを使用して、タイトル バーとタスク バーのアイコン画像を設定します。
- AppWindowTitleBar.IconShowOptions。 ウィンドウ アイコンをタイトル バーにどのように表示するかを指定する値を取得または設定します。 現在サポートされている値は、HideIconAndSystemMenu と ShowIconAndSystemMenu の 2 つです。
- AppWindowTitleBar.ResetToDefault。 現在のタイトル バーをウィンドウの既定の設定に戻します。
アプリで表示するカスタム タイトル バー (完全なカスタマイズ)
移行して AppWindowTitleBar を使用する場合は、コードで次のカスタム タイトル バー API を呼び出す前に、AppWindowTitleBar.IsCustomizationSupported を確認することをお勧めします。
| UWP ApplicationView/CoreWindow | Windows App SDK AppWindow |
|---|---|
| CoreApplicationViewTitleBar.ExtendViewIntoTitleBar | AppWindowTitleBar.ExtendsContentIntoTitleBar プラットフォームでは、[最小化]/[最大化]/[閉じる] ボタンが自動的に表示され、閉鎖情報が報告されます。 |
| CoreApplicationViewTitleBar.SystemOverlayLeftInset | AppWindowTitleBar.LeftInset |
| CoreApplicationViewTitleBar.SystemOverlayRightInset | AppWindowTitleBar.RightInset |
| CoreApplicationViewTitleBar.Height | AppWindowTitleBar.Height |
| AppWindowTitleBarOcclusion AppWindowTitleBar.GetTitleBarOcclusions |
ExtendsContentIntoTitleBar が true の場合にアプリのコンテンツを遮蔽するアプリ ウィンドウのシステム予約領域を表します。 Windows App SDK の AppWindow の左右の埋め込み情報は、タイトル バーの高さと組み合わせることで、同じ情報を提供します。 AppWindowTitleBar.LeftInset、AppWindowTitleBar.RightInset、AppWindowTitleBar.Height |
これらの Windows App SDK API は、タイトル バーの完全なカスタマイズ用です。
- AppWindowTitleBar.SetDragRectangles。 ウィンドウのドラッグ領域を設定します。
- AppWindowTitleBar.ResetToDefault。 現在のタイトル バーをウィンドウの既定の設定に戻します。
これらの UWP AppWindow API は、Windows App SDK API と 1 対 1 で直接対応はしていません。
- AppWindowTitleBarVisibility。 AppWindowTitleBar の優先の表示を指定する定数を定義します。
- AppWindowTitleBar.GetPreferredVisibility。 タイトル バーの優先表示モードを取得します。
- AppWindowTitleBar.SetPreferredVisibility。 タイトル バーの優先表示モードを設定します。
AppWindowTitleBar を使用した作業の詳細については、「ウィンドウ ギャラリーのサンプル」を参照してください。 それには、カスタム色のタイトル バーを作成する方法と、カスタム タイトル バーを表示する方法が示されています。
イベント処理
UWP アプリで AppWindow.Changed イベントを使用している場合は、そのコードを Microsoft.UI.Windowing.AppWindow.Changed イベントに移行できます。
サイズ変更イベント
サイズ変更イベント処理コードを移行する場合は、Windows App SDK の AppWindowChangedEventArgs.DidSizeChange プロパティを使用するように切り替える必要があります。 値は、アプリ ウィンドウのサイズが変更された場合は true、それ以外の場合は false です。
| UWP ApplicationView/CoreWindow | UWP AppWindow | Windows App SDK |
|---|---|---|
| CoreWindow.SizeChanged | AppWindowChangedEventArgs.DidSizeChange | AppWindowChangedEventArgs.DidSizeChange |
MainPage と MainWindow
Visual Studio で新しい UWP プロジェクトを作成するとき、プロジェクト テンプレートに MainPage クラスが用意されています。 アプリでは、そのクラスの名前を変更している可能性があります (また、ページとユーザー コントロールを追加した可能性があります)。 プロジェクト テンプレートには、App クラスのメソッドにナビゲーション コードも用意されています。
Visual Studio で新しい Windows App SDK プロジェクトを作成すると、プロジェクト テンプレートには MainWindow クラス (Microsoft.UI.Xaml.Window 型) が用意されていますが、Page はありません。 また、プロジェクト テンプレートにはナビゲーション コードが用意されていません。
ただし、Windows App SDK プロジェクトにページとユーザー コントロールを追加することもできます。 たとえば、プロジェクトに新しいページ項目を追加して (WinUI>空白のページ (WinUI 3))、MainPage.xaml という名前や他の名前を付けることができます。 そうすると、Microsoft.UI.Xaml.Controls.Page 型の新しいクラスがプロジェクトに追加されます。 それから、プロジェクトへのナビゲーション コードの追加に関する情報について「ページ ナビゲーションを実装する必要がありますか」を参照してください。
Windows Apps SDK アプリが十分にシンプルな場合、ページやユーザー コントロールを作成する必要はなく、XAML マークアップと分離コードを MainWindow にコピーできます。 ただし、そのワークフローの例外については、「ビジュアル状態マネージャーと Page.Resources」を参照してください。
CoreWindow.Dispatcher を DispatcherQueue に変更する
UWP の Windows.UI.Core.CoreWindow クラスの一部のユース ケースは、Windows App SDK の Microsoft.UI.Xaml.Window に移行します。
たとえば、UWP アプリで Windows.UI.Core.CoreWindow.Dispatcher プロパティを使用している場合、解決策は Microsoft.UI.Xaml.Window.Dispatcher プロパティ (常に null が返される) に移行することでは "ありません"。 代わりに、Microsoft.UI.Xaml.Window.DispatcherQueue プロパティに移行します。これにより、Microsoft.UI.Dispatching.DispatcherQueue が返されます。
詳細とコード例については、「Windows.UI.Core.CoreDispatcher を Microsoft.UI.Dispatching.DispatcherQueue に変更する」を参照してください。
関連トピック
Windows developer
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示