Share via

視窗化功能移轉

  • 發行項

本主題包含與視窗管理相關的指引，包括從 UWP 的 ApplicationView/CoreWindow 或 AppWindow 到 Window App SDK Microsoft.UI.Windowing.AppWindow。

重要 API

API 和/或功能差異摘要

Windows 應用程式 SDK 提供以 Win32 HWND 模型為基礎的 Microsoft.UI.Windowing.AppWindow 類別。 AppWindow 類別是 Windows 應用程式 SDK 版的 UWP ApplicationView/CoreWindow 和 AppWindow。

若要利用 Windows 應用程式 SDK 視窗化 API，表示您將移轉 UWP 程式代碼以使用 Win32 模型。 有關 Windows 應用程式 SDK AppWindow 的詳細資訊，請參閱管理應用程式視窗。

提示

管理應用程式視窗主題包含程式碼範例，示範如何從 WinUI 3 視窗擷取 AppWindow 。 在您的 WinUI 3 應用程式中，使用該程式代碼模式，讓您可以呼叫本主題其餘部分所述的 AppWindow API。

UWP 中的視窗類型與 Windows 應用程式 SDK

在 UWP 應用程式中，您可以使用 ApplicationView/CoreWindow 或 AppWindow 託管視窗內容。 將該程式代碼移轉至 Windows 應用程式 SDK 的工作取決於 UWP 應用程式使用的這兩種視窗化模型。 如果您熟悉 UWP 的 Windows.UI.WindowManagement.AppWindow，您可能會看到與 Microsoft.UI.Windowing.AppWindow 之間的相似之處。

UWP 視窗類型

Windows 應用程式 SDK 視窗類型

請記住，UWP 與 Win32 之間視窗化模型的差異表示 UWP API 介面與 Windows 應用程式 SDK API 介面之間沒有直接的 1:1 對應。 即使是從 UWP 繼續的類別和成員名稱(反應在本主題的對應資料表中)，行為也可能不同。

啟動顯示畫面

不同於 UWP 應用程式，Win32 應用程式預設不會在啟動時顯示啟動顯示畫面。 依賴這項功能的 UWP app，其啟動體驗可能會選擇實作自訂轉換至其第一個應用程式視窗。

建立、顯示、關閉和終結視窗

Microsoft.UI.Windowing.AppWindow 的生命週期與 HWND 相同； 這意味著 AppWindow 物件在視窗建立後立即可用，並在視窗關閉時銷毀。

建立和顯示

AppWindow.Create 會建立具有預設組態的應用程式視窗。 只有在您未使用 UI 架構的案例中，才需要建立和顯示視窗。 如果您要將 UWP 應用程式移轉至 Win32 相容的 UI 架構，您仍然可以使用視窗化 Interop 方法，從已建立的視窗連線到 AppWindow 物件。

UWP 應用程式檢視/CoreWindow UWP AppWindow Windows 應用程式 SDK
CoreApplication.CreateNewView
或
CoreWindow.GetForCurrentThread		 AppWindow.TryCreateAsync AppWindow.Create
CoreWindow.Activate AppWindow.TryShowAsync AppWindow.Show

關閉

在UWP中， ApplicationView.TryConsolidateAsync 是使用者起始關閉手勢的程序設計對等專案。 Win32 中不存在這種整合概念 (在 UWP 的 ApplicationView/CoreWindow 視窗模型中)。 Win32 不需要 Windows 存在於不同的執行緒中。 複製 UWP 的 ApplicationView/CoreWindow 視窗模型需要開發人員建立一個新執行緒，並在其中建立一個新視窗。 在 Win32 模型下，預設的系統行為是 Close>Hide>Destroy。

UWP 應用程式檢視/CoreWindow UWP AppWindow Windows 應用程式 SDK
ApplicationView.TryConsolidateAsync AppWindow.CloseAsync AppWindow.Destroy

基本視窗自訂

當您從 UWP 移轉至 Windows 應用程式 SDK 時，您可以預期預設 AppWindow 會有相同的體驗。 但如有需要，您可以變更自訂視窗化體驗的預設 Microsoft.UI.Windowing.AppWindow。 如需如何自訂視窗的詳細資訊，請參閱 Microsoft.UI.Windowing.AppWindow。

調整視窗大小

UWP 應用程式檢視/CoreWindow UWP AppWindow Windows 應用程式 SDK
9ApplicationView.TryResizeView AppWindow.RequestSize AppWindow.Resize
CoreWindow.Bounds (通常以 C# 的形式CoreWindow.GetForCurrentThread.Bounds出現) AppWindowPlacement.Size AppWindow.Size

定位視窗

UWP 應用程式檢視/CoreWindow UWP AppWindow Windows 應用程式 SDK
不可行 AppWindow.GetPlacement AppWindow.Position
不可行 Appwindow.RequestMoveXxx AppWindow.Move

Window title

UWP 應用程式檢視/CoreWindow UWP AppWindow Windows 應用程式 SDK
ApplicationView.Title AppWindow.Title AppWindow.Title

緊湊的覆蓋和全屏

進入緊湊覆蓋或全螢幕模式的應用程式應利用 Windows 應用程式 SDK AppWindowPresenter。 如果您熟悉 UWP AppWindow，您可能已經熟悉展示者的概念。

UWP 應用程式視窗演示者與 Windows 應用程式 SDK 應用程式視窗演示者的功能和行為沒有 1:1 的對應。 如果你有 UWP ApplicationView/CoreWindow 應用程序，那麼你仍然可以在應用程式中擁有緊湊的疊加 (畫中畫) 或全螢幕視窗體驗，但演示者的概念對你來說可能是新的。 如需應用程式視窗展示者的詳細資訊，請參閱展示者。 根據預設，重疊的演示者會在建立時套用至 AppWindow。 CompactOverlay 和 FullScreen 是唯一可用的展示者，除了預設之外。

精簡重疊

如果您使用 UWP 的 ApplicationViewMode 或 AppWindowPresentionKind 來呈現精簡重疊視窗，則您應該使用精簡重疊 AppWindowPresenterKind。 Microsoft.UI.Windowing.CompactOverlayPresenter 僅支援 16:9 外觀比例的三個固定視窗大小，而且無法由使用者重設大小。 您應該使用 AppWindow.SetPresenter 來變更 AppWindow 的呈現方式，而不是 ApplicationViewMode.TryEnterViewModeAsync 或 AppWindowPresenterKind.RequestPresentation。

UWP 應用程式檢視/CoreWindow UWP AppWindow Windows 應用程式 SDK
ApplicationViewMode.CompactOverlay AppWindowPresentationKind.CompactOverlay AppWindowPresenterKind.CompactOverlay
ApplicationView.TryEnterViewModeAsync 搭配 ApplicationViewMode.CompactOverlay AppWindowPresenter.RequestPresentation 與 AppWindowPresenterKind.CompactOverlay AppWindow.SetPresenter 與 AppWindowPresenterKind.CompactOverla

全螢幕

如果您使用 UWP 的 ApplicationViewWindowingMode 或 AppWindowPresentionKind 類別來呈現全螢幕視窗，則您應該使用全螢幕 AppWindowPresenterKind。 Windows 應用程式 SDK 僅支持最嚴格的全螢幕體驗 (也就是 FullScreen 為 IsExclusive 時)。 針對 ApplicationView CoreWindow/，您可以使用ApplicationView.ExitFullScreenMode 將應用程式從全螢幕取出。 使用演示者時，您可以使用 AppWindow.SetPresenter，將展示者設定回重疊/預設，以將應用程式從全螢幕取出。

UWP 應用程式檢視/CoreWindow UWP AppWindow Windows 應用程式 SDK
ApplicationViewWindowingMode.FullScreen AppWindowPresentationKind.FullScreen AppWindowPresenterKind.FullScreen
ApplicationView.TryEnterFullScreenMode AppWindowPresenter.RequestPresentation 與 AppWindowPresenterKind.FullScreen AppWindow.SetPresenter 與 AppWindowPresenterKind.FullScreen

如需如何使用應用程式視窗演示者的詳細資訊，請參閱 Windowing 資源庫範例。 示範如何切換不同的應用程式視窗展示器狀態。

自訂標題欄

注意

標題欄自訂 API 目前僅適用於 Windows 11。 我們建議您在呼叫這些 API 之前在程式碼中檢查 AppWindowTitleBar.IsCustomizationSupported。

如果您的應用程式使用預設標題欄，則移轉到 Win32 時不需要額外的標題列工作。 另一方面，如果您的 UWP 應用程式具有自訂標題列，則可以在 Windows 應用程式 SDK 應用程式中重新建立下列案例。

  1. 自訂系統繪製的標題
  2. 應用程式繪製的自訂標題欄

使用 ApplicationViewTitleBar、CoreApplicationViewTitleBar 和 AppWindowTitleBar 類別的程式碼將移轉為使用 Windows 應用程式 SDK Microsoft.UI.Windowing.AppWindowTitleBar 類別。

自訂系統繪製的標題

以下是色彩自訂 API 的資料表。

注意

當 AppWindowTitleBar.ExtendsContentIntoTitleBar 為 true 時，僅以下屬性支援透明度：AppWindowTitleBar.ButtonBackgroundColor、AppWindowTitleBar.ButtonInactiveBackgroundColor、AppWindowTitleBar.ButtonPressedBackgroundColor、AppWindowTitleBar.ButtonHoverBackgroundColor 和 AppWindowTitleBar.BackgroundColor。

UWP 應用程式檢視/CoreWindow UWP AppWindow Windows 應用程式 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

除了 AppWindow.Title API 之外，這些 Windows 應用程式 SDK API 也用於進一步自訂系統繪製的標題列。

應用程式繪製的自訂標題列 (完整自訂)

如果您要移轉到使用 AppWindowTitleBar，那麼我們建議您在呼叫以下自訂標題列 API 之前在程式碼中檢查 AppWindowTitleBar.IsCustomizationSupported。

UWP 應用程式檢視/CoreWindow Windows 應用程式 SDK AppWindow
CoreApplicationViewTitleBar.ExtendViewIntoTitleBar AppWindowTitleBar.ExtendsContentIntoTitleBar
平台會繼續為您繪製 Minimize/Maximize/Close 按鈕，並報告遮擋資訊。
CoreApplicationViewTitleBar.SystemOverlayLeftInset AppWindowTitleBar.LeftInset
CoreApplicationViewTitleBar.SystemOverlayRightInset AppWindowTitleBar.RightInset
CoreApplicationViewTitleBar.Height AppWindowTitleBar.Height
AppWindowTitleBarOcclusion
AppWindowTitleBar.GetTitleBarOcclusions		 代表應用程式視窗的系統保留區域，如果 ExtendsContentIntoTitleBar 為 true，則會遮蔽應用程式內容。 Windows 應用程式 SDK AppWindow 左右的內嵌資訊，加上標題欄高度，提供相同的資訊。
AppWindowTitleBar.LeftInset, AppWindowTitleBar.RightInset, AppWindowTitleBar.Height

這些 Windows 應用程式 SDK API 適用於完整標題列自訂。

這些 UWP AppWindow API 沒有與 Windows 應用程式 SDK API 的直接 1:1 對應。

有關如何使用 AppWindowTitleBar 的更多詳細資訊，請參閱視窗庫範例。 其示範如何建立自訂色彩標題列，以及如何繪製自訂標題列。

事件處理

如果您的 UWP 應用程式使用 AppWindow.Changed 事件，您可以將該程式代碼移轉至 Microsoft.UI.Windowing.AppWindow.Changed 事件。

大小變更事件

移轉大小變更的事件處理程式碼時，您應該切換至使用 Windows 應用程式 SDK AppWindowChangedEventArgs.DidSizeChange 屬性。 如果應用程式視窗的大小已變更，則值為 true，否則為 false。

UWP 應用程式檢視/CoreWindow UWP AppWindow Windows 應用程式 SDK
CoreWindow.SizeChanged AppWindowChangedEventArgs.DidSizeChange AppWindowChangedEventArgs.DidSizeChange

MainPage 和 MainWindow

當您在Visual Studio中建立新的UWP專案時，專案範本會提供 MainPage 類別。 針對您的應用程式，您可能已重新命名該類別 (以及/或新增更多頁面和使用者控制項)。 項目範本也會提供您在 App 類別方法中的導覽程式代碼。

當您在 Visual Studio 中建立新的 Windows 應用程式 SDK 專案時，專案範本會為您提供 MainWindow 類別 (類型為 Microsoft.UI.Xaml.Window)，但沒有 Page。 項目範本不會提供任何導覽程序代碼。

不過，您可以選擇將頁面和使用者控制項新增至 Windows 應用程式 SDK 專案。 例如，您可以為專案新增一個新的頁面項目 (WinUI>Blank Page (WinUI 3))，並將其命名為 MainPage.xaml 或其他名稱。 這會新增至專案類型為 Microsoft.UI.Xaml.Controls.Page 的新類別。 然後，如需將導覽程式代碼新增至專案的資訊，請參閱是否需要實作頁面導覽？。

對於足夠簡單 Windows 應用程式 SDK 應用程式，您不需要建立頁面或使用者控件，而且您可以將 XAML 標記和程式碼後置複製到 MainWindow。 但如需該工作流程例外狀況的相關信息，請參閱 Visual State Manager和Page.Resources。

將 CoreWindow.Dispatcher 變更為 Window.DispatcherQueue。

UWP 的 Windows.UI.Core.CoreWindow 類別的一些使用案例會移轉至 Windows 應用程式 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。