使用 UWP XAML 主機 API

這很重要

本主題使用或提及 CommunityToolkit/Microsoft.Toolkit.Win32 GitHub 倉庫中的類型。 關於 UWP XAML 島嶼支援的重要資訊,請參閱該倉庫中的 XAML 島嶼通知。

非 UWP 桌面應用程式(包括 C++ 桌面(Win32)、WPF 及 Windows Forms 應用程式)可使用 UWP XAML 託管 API,在任何與視窗 handle(HWND)相關的 UI 元素中託管 UWP XAML 控制項。 關於此功能的概述,請參閱桌面應用程式中的 Host UWP XAML 控制(UWP XAML Islands)。

UWP XAML 主機 API 是你桌面應用程式的合適選擇嗎?

UWP XAML 主機 API 提供底層基礎架構,用於桌面應用程式中託管 UWP XAML 控制項。 某些類型的桌面應用程式可以選擇使用替代且更方便的 API 來達成此目標。

  • 如果你有 C++ 桌面應用程式,且想在應用程式中架設 UWP XAML 控制項,必須使用 UWP XAML 主機 API。 這類應用程式沒有其他替代方案。

  • 對於WPF和Windows Forms應用程式,我們強烈建議你使用 Windows 社群工具包中的 XAML Island .NET 控制項,而非直接使用 UWP XAML 主機 API。 這些控制項內部使用 UWP XAML 主機 API,並實作了你若直接使用 UWP XAML 主機 API 時需要自行處理的所有行為,包括鍵盤導覽與版面配置的變更。

由於我們建議只有 C++ 桌面應用程式使用 UWP XAML 主機 API,本文主要提供 C++ 桌面應用程式的說明與範例。 不過,如果你願意,也可以在 WPF 和 Windows Forms 應用程式中使用 UWP XAML 主機 API。 本文指向 Windows Community Toolkit 中的 host 控制項 的 WPF 和 Windows Forms 的相關原始碼,讓你能查看這些控制項如何運用 UWP XAML 主機 API。

學習如何使用 XAML 主機 API

要按照步驟說明及程式碼範例,在 C++ 桌面應用程式中使用 XAML 主機 API,請參閱以下文章:

範例

你在程式碼中使用 UWP XAML 主機 API 的方式,取決於你的應用程式類型、設計以及其他因素。 為了說明如何在完整應用程式的情境中使用此 API,本文引用以下範例的程式碼。

C++ 桌面 (Win32)

以下範例示範如何在 C++ 桌面應用程式中使用 UWP XAML 主機 API:

  • Simple XAML 島嶼樣本。 此範例展示了在未封裝的 C++ 桌面應用程式中,如何託管 UWP XAML 控制項的基本實作。

  • XAML 島嶼,附自訂對照樣本。 本範例展示了在封裝的 C++ 桌面應用程式中完整實作託管自訂 UWP XAML 控制項,並處理鍵盤輸入與焦點導航等其他行為。

WPF 與 Windows Forms

Windows 社群工具包中的 WindowsXamlHost 控制項作為 WPF 與 Windows Forms 應用程式中使用 UWP XAML 主機 API 的參考範例。 原始碼可於以下地點取得:

備註

我們強烈建議您使用 Windows 社群工具包中的 XAML .NET Island 控制項,而非直接在 WPF 和 Windows Forms 應用程式中使用 UWP XAML 主機 API。 本文中的 WPF 與 Windows Forms 範例連結僅供說明用途。

API 架構

UWP XAML 主機 API 包含這些主要的 Windows 執行階段 類型與 COM 介面。

類型或介面 Description
WindowsXamlManager 此類別代表 UWP XAML 框架。 此類別提供一個靜態的 InitializeForCurrentThread 方法,可在桌面應用程式中目前執行緒上初始化 UWP XAML 框架。
DesktopWindowXamlSource 這個類別代表你在桌面應用程式中托管的 UWP XAML 內容實例。 此類別中最重要的成員是 內容 屬性。 你把這個屬性指派到你想架設的 Windows.UI.Xaml.UIElement 。 此類別還有其他成員,負責將鍵盤焦點導航導向進出 XAML 群島。
IDesktopWindowXamlSourceNative 此 COM 介面提供 AttachToWindow 方法,你可以用它將應用程式中的 XAML 島連接到父 UI 元素。 每個 DesktopWindowXamlSource 物件都實作了這個介面。
IDesktopWindowXamlSourceNative2 此 COM 介面提供 PreTranslateMessage 方法,使 UWP XAML 框架能正確處理某些 Windows 訊息。 每個 DesktopWindowXamlSource 物件都實作了這個介面。

下圖展示了託管於桌面應用程式的 XAML 島嶼中物件的階層結構。

  • 最基本的是你應用程式中想要架設 XAML Island 的 UI 元素。 此 UI 元素必須有視窗代柄(HWND)。 你可以在 XAML Island 中架設的 UI 元素範例包括:用於 C++ 桌面應用程式的 window、用於WPF應用程式的 System.Windows.Interop.HwndHost,以及用於Windows Forms應用程式的 System.Windows.Forms.Control。

  • 下一層是一個 DesktopWindowXamlSource 物件。 此物件提供 XAML 島嶼的主機基礎設施。 你的程式碼負責建立這個物件並將其附加到父 UI 元素。

  • 當你建立 DesktopWindowXamlSource 時,這個物件會自動建立一個原生子視窗來承載你的 UWP XAML 控制項。 這個原生子視窗大多從您的程式碼中抽象化,但如果需要,您可以存取它的 handle(HWND)。

  • 最後,最頂層是你想在桌面應用程式中架設的 UWP XAML 控制項。 這可以是任何從 Windows.UI.Xaml.UIElement 衍生的 UWP 物件,包括 Windows SDK 提供的任何 UWP XAML 控制項,以及自訂的使用者控制項。

DesktopWindowXamlSource 架構

備註

當你在桌面應用程式中架設 UWP XAML Islands 時,你可以在同一執行緒上同時執行多條 XAML 內容樹狀結構。 若要存取 XAML 島嶼中 XAML 內容樹的根元素,並取得與其托管上下文相關的資訊,請使用XamlRoot類別。 CoreWindow、ApplicationView 和 Windows API 無法提供 UWP XAML 島嶼的正確資訊。 如需詳細資訊,請參閱本節。

最佳做法

使用 UWP XAML 主機 API 時,請遵循每個承載 UWP XAML 控制項的執行緒的最佳實務:

故障排除

在 UWP 應用程式中使用 UWP XAML 主機 API 時出現錯誤

問題 解決辦法
您的應用程式收到一個帶有以下訊息的 COMException :「無法啟用 DesktopWindowXamlSource。 此類型無法用於 UWP 應用程式。」或「無法啟用 WindowsXamlManager。 此類型無法用於 UWP 應用程式。」 這個錯誤表示你正在嘗試使用 UWP 的 XAML 主機 API(具體來說,你是想實例化 DesktopWindowXamlSource 或 WindowsXamlManager 類型)在 UWP 應用程式中。 UWP XAML 主機 API 僅設計用於非 UWP 桌面應用程式,如 WPF、Windows Forms 及 C++ 桌面應用程式。

嘗試使用 WindowsXamlManager 或 DesktopWindowXamlSource 類型時出現錯誤

問題 解決辦法
您的應用程式會收到一個例外,並顯示以下訊息:「WindowsXamlManager 和 DesktopWindowXamlSource 支援針對 Windows 版本 10.0.18226.0 及以上的應用程式。 請檢查應用程式清單或套件清單,並確保 MaxTestedVersion 屬性已更新。」 此錯誤表示您的應用程式嘗試使用 UWP XAML 主機 API 中的 WindowsXamlManager 或 DesktopWindowXamlSource 類型,但作業系統無法判斷該應用程式是針對 Windows 10、版本 1903 或更新版本而建置。 UWP XAML 主機 API 最初是在早期版本的 Windows 10 中作為預覽引入,但從 Windows 10 版本 1903 開始才支援。

要解決這個問題,可以為該應用程式建立 MSIX 套件並從套件執行,或在project安裝 Microsoft.Toolkit.Win32.UI.SDK NuGet 套件。

嘗試附加到不同執行緒的視窗時發生錯誤

問題 解決辦法
你的應用程式收到一個 COMException 訊息:「AttachToWindow 方法失敗,因為指定的 HWND 是在另一個執行緒上建立的。」 這個錯誤表示你的應用程式呼叫了 IDesktopWindowXamlSourceNative::AttachToWindow 方法,並將另一個執行緒建立的視窗的 HWND 傳給它。 你必須將在與您呼叫該方法的程式碼相同執行緒中建立的視窗的 HWND 傳遞給此方法。

錯誤連接至另一個頂層視窗的視窗

問題 解決辦法
您的應用程式收到一個 COMException 錯誤,訊息如下:「AttachToWindow 方法失敗,因為指定的 HWND 所屬的頂層視窗與先前在同一執行緒中傳遞給 AttachToWindow 的 HWND 所屬的頂層視窗不同。」 此錯誤表示您的應用程式呼叫了 IDesktopWindowXamlSourceNative::AttachToWindow 方法,並將一個從不同頂層視窗降落的視窗的 HWND 傳達給它,該視窗與你之前在同一執行緒呼叫中指定的視窗不同。

當你的應用程式在特定執行緒呼叫 AttachToWindow 後,同一執行緒中的所有其他 DesktopWindowXamlSource 物件只能附加到同一個頂層視窗的後代視窗,而該視窗是第一次呼叫 AttachToWindow 時傳遞的。 當某個執行緒的所有 DesktopWindowXamlSource 物件都關閉後,下一個 DesktopWindowXamlSource 就可以自由附加到任何視窗上。

要解決這個問題,請關閉本串中綁定至其他頂層視窗的所有 DesktopWindowXamlSource 物件,或為此 DesktopWindowXamlSource 建立新串。