ウィンドウ機能の移行

このトピックでは、UWP の ApplicationView/CoreWindow または AppWindow から Windows App SDK の Microsoft.UI.Windowing.AppWindow への移行を含め、ウィンドウ管理に関連するガイダンスを示します。

重要な API

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 App SDK のウィンドウの種類

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 に適用されます。 CompactOverlayFullScreen は、既定のもの以外で使用可能な唯一のプレゼンターです。

コンパクト オーバーレイ

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.TryEnterViewModeAsyncApplicationViewMode.CompactOverlay AppWindowPresenter.RequestPresentationAppWindowPresenterKind.CompactOverlay AppWindow.SetPresenterAppWindowPresenterKind.CompactOverlay

全画面

UWP の ApplicationViewWindowingMode または AppWindowPresentionKind クラスを使用して全画面ウィンドウを表示していた場合は、全画面の AppWindowPresenterKind を使用する必要があります。 Windows App SDK は、最も制限の厳しい全画面エクスペリエンス (つまり、FullScreenIsExclusive の場合) のみをサポートしています。 ApplicationView/CoreWindow の場合は、ApplicationView.ExitFullScreenMode を使用してアプリの全画面表示を解除することができます。 プレゼンターを使用する場合は、アプリの全画面表示を解除するには、AppWindow.SetPresenter を使用して、プレゼンターの設定をオーバーラップまたは既定に戻します。

UWP ApplicationView/CoreWindow UWP AppWindow Windows App SDK
ApplicationViewWindowingMode.FullScreen AppWindowPresentationKind.FullScreen AppWindowPresenterKind.FullScreen
ApplicationView.TryEnterFullScreenMode AppWindowPresenter.RequestPresentationAppWindowPresenterKind.FullScreen AppWindow.SetPresenterAppWindowPresenterKind.FullScreen

アプリ ウィンドウのプレゼンターを操作する方法の詳細については、「ウィンドウ ギャラリーのサンプル」を参照してください。 さまざまなアプリ ウィンドウ プレゼンターの状態を切り替える方法を示しています。

カスタム タイトル バー

注意

現在、タイトル バー カスタマイズ API は Windows 11 でのみ機能します。 これらの API を呼び出す前に、コードで AppWindowTitleBar.IsCustomizationSupported を確認することをお勧めします。

アプリで既定のタイトル バーを使用している場合は、Win32 に移行するときに、タイトル バーに関する追加の作業は必要ありません。 一方、UWP アプリでカスタム タイトル バーを使用している場合は、Windows App SDK アプリで次のシナリオを再作成することができます。

  1. システムによって表示されるタイトル バーをカスタマイズする
  2. アプリで表示するカスタム タイトル バー

UWP の ApplicationViewTitleBarCoreApplicationViewTitleBarAppWindowTitleBar クラスを使用しているコードは、Windows App SDK の Microsoft.UI.Windowing.AppWindowTitleBar クラスを使用するように移行します。

システムによって表示されるタイトル バーをカスタマイズする

色のカスタマイズ API の表を次に示します。

注意

AppWindowTitleBar.ExtendsContentIntoTitleBartrue の場合、透明性は次のプロパティに対してのみサポートされます: AppWindowTitleBar.ButtonBackgroundColorAppWindowTitleBar.ButtonInactiveBackgroundColorAppWindowTitleBar.ButtonPressedBackgroundColorAppWindowTitleBar.ButtonHoverBackgroundColorAppWindowTitleBar.BackgroundColor (暗黙的に設定されます)。

UWP ApplicationView/CoreWindow UWP AppWindow Windows App SDK
ApplicationViewTitleBar のプロパティ AppWindowTitleBar のプロパティ AppWindowTitleBar のプロパティ
BackgroundColor BackgroundColor BackgroundColor
ButtonBackgroundColor ButtonBackgroundColor ButtonBackgroundColor
ButtonForegroundColor ButtonForegroundColor ButtonForegroundColor
ButtonHoverBackgroundColor ButtonHoverBackgroundColor ButtonHoverBackgroundColor
ButtonHoverForegroundColor ButtonHoverForegroundColor ButtonHoverForegroundColor
ButtonInactiveBackgroundColor ButtonInactiveBackgroundColor ButtonInactiveBackgroundColor
ButtonInactiveForegroundColor ButtonInactiveForegroundColor ButtonInactiveForegroundColor
ButtonPressedBackgroundColor ButtonPressedBackgroundColor ButtonPressedBackgroundColor
ButtonPressedForegroundColor ButtonPressedForegroundColor ButtonPressedForegroundColor
ForegroundColor ForegroundColor ForegroundColor
InactiveBackgroundColor InactiveBackgroundColor InactiveBackgroundColor
InactiveForegroundColor InactiveForegroundColor InactiveForegroundColor

次の Windows App SDK API は、AppWindow.Title API に加えて、システムによって表示されるタイトル バーをさらにカスタマイズするためのものです。

  • AppWindow.SetIcon。 hIcon ハンドルを使用するか、リソースまたはファイルへの文字列パスを使用して、タイトル バーとタスク バーのアイコン画像を設定します。
  • AppWindowTitleBar.IconShowOptions。 ウィンドウ アイコンをタイトル バーにどのように表示するかを指定する値を取得または設定します。 現在サポートされている値は、HideIconAndSystemMenuShowIconAndSystemMenu の 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.LeftInsetAppWindowTitleBar.RightInsetAppWindowTitleBar.Height

これらの Windows App SDK API は、タイトル バーの完全なカスタマイズ用です。

これらの UWP AppWindow API は、Windows App SDK API と 1 対 1 で直接対応はしていません。

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 に変更する」を参照してください。