在桌面應用程式中託管 UWP XAML 控制項（UWP XAML Islands）

這很重要

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

從 Windows 10 年版本 1903 開始，你可以利用名為 UWP XAML Islands 的功能，在非 UWP 桌面應用程式中架設 UWP XAML 控制項。 此功能讓您能提升現有 WPF、Windows Forms 及 C++ 桌面（Win32）應用程式的外觀、使用感與功能，並搭配僅透過 UWP XAML 控制項提供的 Windows UI 功能。 這表示你可以在現有的 WPF、Windows Forms 和 C++ 桌面應用程式中使用 UWP 功能，如 Windows Ink以及支援 Fluent Design System 的控制項。

你可以承載任何源自 Windows.UI.Xaml.UIElement 的 UWP XAML 控制項，包括：

  • 大多數第一方 UWP XAML 控制項由 Windows SDK 或 WinUI for UWP 函式庫提供（參見 exceptions）。
  • 任何自訂的 UWP XAML 控制項（例如，由多個 UWP XAML 控制項組成且協同運作的使用者控制項）。 您必須擁有自訂控制項的原始程式碼，才能使用您的應用程式進行編譯。

基本上，UWP XAML 島嶼是透過使用 UWP XAML 主機 API 建立的。 此 API 包含多個 Windows 執行階段 類別與 COM 介面，這些介面是在 Windows 10 版本 1903 SDK 中引入的。 我們也在 Windows 社群工具包中提供一組 XAML 島嶼.NET控制項，內部使用 UWP XAML 主機 API，為WPF與Windows Forms應用程式提供更便利的開發體驗。

你使用 UWP XAML Islands 的方式取決於你的應用程式類型以及你想架設的 UWP XAML 控制類型。

需求

UWP XAML 島嶼有以下執行時間要求：

  • Windows 10，版本 1903，或更新版本。
  • 如果您的應用程式沒有封裝在 MSIX 套件中以供部署，則電腦必須安裝 C++ Visual Runtime。

WPF 與 Windows Forms 應用程式

備註

目前僅在目標為 .NET Core 3.x 的應用程式中支援使用 UWP XAML Islands 將 UWP XAML 控制項託載於 WPF 和 Windows Forms 應用程式中。 UWP XAML 島嶼尚未在針對 .NET 的應用程式或任何版本的 .NET 框架應用程式中獲得支援。

我們建議 WPF 與 Windows Forms 應用程式使用 Windows 社群工具包中提供的 XAML Island .NET 控制項。 這些控制項提供一個物件模型，模擬（或提供存取）對應 UWP XAML 控制項的屬性、方法與事件。 它們也會處理鍵盤導覽和版面配置變更之類的行為。

XAML 島嶼控制項有兩種用於 WPF 與 Windows Forms 應用程序的方式：封裝控制項和宿主控制項。

包裝式控制項

WPF 和 Windows Forms 應用程式可以使用一系列 XAML 島嶼控制項，這些控制項包裹特定 UWP XAML 控制項的介面與功能。 你可以直接將這些控制項加入WPF或Windows Forms專案的設計介面，然後像其他WPF或Windows Forms控制項一樣在設計視圖中使用。

以下包裝的 UWP XAML 控制項目前可在 Windows 社群工具包中取得。

管理 支援 OS 的最低版本 Description
墨水畫布
墨水工具列		 Windows 10，版本 1903 提供一個界面及相關工具列，以便在 Windows Forms 或 WPF 桌面應用程式中進行基於 Windows Ink 的使用者互動。
MediaPlayerElement Windows 10，版本 1903 嵌入一個視圖，用於在您的 Windows Forms 或 WPF 桌面應用程式中串流並渲染媒體內容，例如影片。
MapControl Windows 10，版本 1903 讓您能在 Windows Forms 或 WPF 桌面應用程式中顯示符號或寫實地圖。

若想了解如何使用封裝的 UWP XAML 控制項，請參考 如何使用 XAML Islands 在 C# WPF 應用程式中主控 UWP XAML 控制項。

主機控制項

對於自訂控制項及超出現有包裝控制項範圍的其他情境，WPF 和 Windows Forms 應用程式也可使用 Windows 社群工具包中提供的 WindowsXamlHost控制項。

管理 支援 OS 的最低版本 Description
WindowsXamlHost Windows 10，版本 1903 可以承載任何源自 Windows.UI.Xaml.UIElement 的 UWP XAML 控制項，包括由 Windows SDK 提供的任何第一方 UWP XAML 控制項以及自訂控制項。

如需示範如何使用 WindowsXamlHost 控制項的教學，請參見 使用 XAML Islands 在 C# WPF 應用程式中托管 UWP XAML 控制項 以及 使用 XAML Islands 在WPF應用程式中架設自訂的 UWP XAML 控制項。

將你的 project 設定為使用 XAML Island 的 .NET 控制項

XAML Island .NET 控制需要 Windows 10、1903 版本或更新版本。 若要使用這些控制項，請安裝以下所列的其中一個 NuGet 套件。 這些套件提供您使用 XAML Island 包裝的控制項和主控制項所需的所有項目，並且包含其他也需要的相關 NuGet 套件。

控制項的類型 NuGet 套件 相關文章
包裹的控制項 這些套件的 6.0.0 版或更新版本： 使用 XAML 島嶼在 C# WPF 應用程式中托管 UWP XAML 控制項
主控制項 這些套件的 6.0.0 版或更新版本： 使用 XAML 島嶼在 C# WPF 應用程式中托管 UWP XAML 控制項
在WPF應用程式中託管自訂的UWP XAML控制項

請注意下列詳細資料：

Web 檢視控制項

Windows 社群工具包也提供以下 .NET 控制項，用於在 WPF 和 Windows Forms 應用程式中架設網頁內容。 這些控制項常用於與 XAML 島嶼控制項相似的桌面應用程式現代化場景，且與 XAML 島嶼控制項相同的 Microsoft.Toolkit.Win32 倉庫中維護。

管理 支援 OS 的最低版本 Description
WebView Windows 10，版本 1803 使用 Microsoft Edge 轉譯引擎來顯示 Web 內容。
WebViewCompatible Windows 7 提供與更多作業系統版本相容的 WebView 版本。 此控制項使用Microsoft Edge渲染引擎在Windows 10 1803及更新版本中顯示網頁內容，並使用Internet Explorer渲染引擎在較早期版本的Windows 10、Windows 8.x及Windows 7上顯示網頁內容。

若要使用這些控制項，請安裝其中一個 NuGet 套件：

C++ 桌面型 (Win32) 應用程式

XAML Island .NET 控制項不支援 C++ 桌面應用程式。 這些應用程式必須改用Windows 10 SDK（版本 1903 及以上）提供的 UWP XAML 寄存 API。

UWP XAML 主機 API 包含多個 Windows 執行階段 類別與 COM 介面，您的 C++ 桌面應用程式可用來承載任何源自 Windows.UI.Xaml.UIElement 的 UWP XAML 控制項。 你可以在應用程式中任何有相關視窗句柄（HWND）的 UI 元素中托管 UWP XAML 控制項。 如需此 API 的詳細資訊，請參閱下列文章：

備註

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

UWP XAML 島嶼架構

以下是快速了解不同類型的 XAML 島嶼控制元件如何在 UWP XAML 主機 API 之上進行架構組織。

主機控制架構

出現在此圖表底部的 API 是隨 Windows SDK 提供的。 包裝的控制項和主控制項可透過「Windows 社區工具組」中的 NuGet 套件來取得。

限制和因應措施

以下章節將討論在使用 UWP XAML Islands 的桌面應用程式中，某些 UWP 開發場景的限制與變通方法。

僅能通過變通方法來支援

✔️ 在目前的 UWP XAML 島嶼版本中，WinUI for UWP 函式庫 中的控制項之託管在 XAML 島嶼內被有條件地支援。 如果您的桌面應用程式使用 MSIX 套件進行部署，則可以從 Microsoft.UI.XamlNuGet 套件的搶鮮版或發行版本裝載 WinUI 控制項。 如果您的桌面應用程式未使用 MSIX 進行封裝，您只有在安裝 Microsoft.UI.Xaml NuGet 套件的搶鮮版，或是使用 動態相依性 API，才能裝載 WinUI 控制項。

✔️ 要在 XAML 島嶼中access XAML 內容樹的根元素並取得其所託管上下文的相關資訊，請勿使用 CoreWindow、ApplicationView 以及 Window 類別。 而是改成使用 XamlRoot 類別。 如需詳細資訊，請參閱本節。

✔️ 要支援 WPF、Windows Forms 或 C++ 桌面（Win32）應用程式中的 Share 合約，您的應用程式必須使用 IDataTransferManagerInterop 介面，讓 DataTransferManager 物件啟動特定視窗的分享操作。 若想了解如何在WPF應用程式中使用此介面，請參考 ShareSource 範例。

✔️ 在 UWP XAML Islands 中不支援使用 x:Bind 裝載控制項。 你必須在 .NET Standard 函式庫中宣告資料模型。

不支援

🚫 在目標為 .NET 框架的 WPF 和 Windows Forms 應用程式中使用 UWP XAML 島嶼。 UWP XAML 島僅支援針對 .NET Core 3.x 的應用程式。

🚫 UWP XAML 在 UWP XAML Islands 中，執行時不會對 Windows 主題從暗到亮或相反的變更做出反應。 內容會在執行階段回應高對比變更。

🚫 新增 Windows.UI.Xaml.WebView 控制項。 關於WPF和 WinForms 應用程式，請參見 這些替代方案。

🚫 MediaPlayer控制項與MediaPlayerElement主機控制在全螢幕模式下不支援。

🚫 含手寫檢視的文字輸入。 如需這項功能的詳細資訊，請參閱本文。

🚫 使用 @Places 和 @People 內容連結的文字控制項。 如需這項功能的詳細資訊，請參閱本文。

🚫 UWP XAML Islands 不支援託管包含可接受文字輸入控制項的 ContentDialog，例如 TextBox、RichEditBox 或 AutoSuggestBox。 如果這樣做，輸入控制項將不會正確回應按鍵操作。 若要使用 XAML Island 來達到類似的功能，建議您裝載包含輸入控制項的快顯視窗。

🚫 UWP XAML 島目前不支援透過託管的 Windows.UI.Xaml.Controls.Image 控制項或使用 Windows.UI.Xaml.Media.Imaging.SvgImageSource 物件顯示 SVG 檔案。 因應措施是將您想要顯示的影像檔案轉換成點陣式的格式，例如 JPG 或 PNG。

XAML 島嶼的視窗主機環境

當你在桌面應用程式中架設 UWP XAML Islands 時，你可以在同一執行緒上同時執行多條 XAML 內容樹狀結構。 若要存取 XAML 島嶼中 XAML 內容樹的根元素，並取得與其托管上下文相關的資訊，請使用XamlRoot類別。 CoreWindow、ApplicationView 和 Window 類別無法提供 UWP XAML 島嶼的正確資訊。 CoreWindow 和 Window 物件存在於執行緒上，且可供您的應用程式存取，但不會傳回有意義的界限或可見度 (這些物件一律不可見，且大小為 1x1)。 如需詳細資訊，請參閱視窗系統主機。

例如，要取得託管於 XAML Islands 且包含 UWP XAML 控制項的視窗之邊界矩形，請使用控制項的 XamlRoot.Size 屬性。 因為每個可以託管在 XAML 島上的 UWP XAML 控制項都源自 Windows。UI。Xaml.UIElement，你可以利用控制項的 XamlRoot 屬性來存取 XamlRoot 物件。

Size windowSize = myUWPControl.XamlRoot.Size;

請不要使用 CoreWindows.Bounds 屬性來取得周框矩形。

// This will return incorrect information for a UWP XAML control that is hosted in a XAML Island.
Rect windowSize = CoreWindow.GetForCurrentThread().Bounds;

在使用 UWP XAML Islands 方案時，您應避免的常見視窗相關 API 及建議使用的 XamlRoot 替代項，請參考 本節的表格。

若想了解如何在WPF應用程式中使用此介面，請參考 ShareSource範例。

其他資源

欲了解更多使用 UWP XAML 島嶼的背景資訊與教學，請參閱以下文章與資源：

  • Last updated on