在傳統型應用程式中裝載 WinRT XAML 控制項 (XAML Islands)

從 Windows 10 版本 1903 開始,您可以使用稱為「XAML Islands」的功能,將 WinRT XAML 控制項裝載在非 UWP 傳統型應用程式中。 這項功能可讓您使用僅透過 WinRT XAML 控制項提供的最新 Windows 10 UI 功能,來增強現有 WPF、Windows Forms 和 c + + desktop (Win32) 應用程式的外觀、風格和功能。 這表示您可以使用 UWP 功能,例如Windows Ink和控制項,以支援現有 WPF、Windows Forms 和 c + + 桌面應用程式中的Fluent Design 系統

您可以裝載衍生自 Windows.UI.Xaml.UIElement 的任何 WinRT XAML 控制項,包括:

  • Windows SDK 或 WinUI 2 程式庫所提供的任何第一方 WinRT XAML 控制項。
  • 任何自訂 WinRT XAML 控制項 (例如,由數個可搭配使用的 WinRT XAML 控制群組成的使用者控制項)。 您必須擁有自訂控制項的原始程式碼,才能使用您的應用程式進行編譯。

基本上,會使用 WINRT xaml 裝載 API 來建立 XAML 孤島。 這個 API 是由 Windows 10 版本 1903 SDK 中引進的數個 Windows 執行階段類別和 COM 介面所組成。 我們也在Windows 社群工具組中提供一組 XAML 島 .net 控制項,在內部使用 WinRT XAML 裝載 API,並為 WPF 和 Windows Forms 應用程式提供更方便的開發體驗。

您使用 XAML Islands 的方式取決於您的應用程式類型,以及您想要裝載的 WinRT XAML 控制項類型。

注意

如果您有關於 XAML Islands 的意見反應,請在 Microsoft.Toolkit.Win32 存放庫中建立新問題,並留下您的意見。

需求

XAML Islands 具有下列執行階段需求:

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

WPF 和 Windows Form 應用程式

注意

目前只有以 .net Core 3.x 為目標的應用程式才支援使用 XAML 孤島來裝載 WPF 中的 WinRT XAML 控制項和 Windows Forms 應用程式。 以 .NET 5 為目標的應用程式,或任何 .NET Framework 版本的應用程式中,尚不支援 XAML 孤島。

我們建議 WPF 和 Windows Forms 應用程式使用「Windows 社區工具組」中提供的 XAML Island .NET 控制項。 這些控制項會提供物件模型,模擬 (或提供存取) 對應 WinRT XAML 控制項的屬性、方法和事件。 它們也會處理鍵盤導覽和版面配置變更之類的行為。

WPF 和 Windows Forms 應用程式有兩組 XAML Island 控制項:「包裝的控制項」和「主控制項」。

包裝的控制項

WPF 和 Windows Forms 應用程式可以使用 XAML Island 控制項的選項,以包裝特定 WinRT XAML 控制項的介面和功能。 您可以直接將控制項新增至 WPF 或 Windows Forms 專案的設計介面,然後像設計工具中的任何其他 WPF 或 Windows Forms 控制項一樣來使用它們。

下列包裝的 WinRT XAML 控制項目前可在「Windows 社區工具組」中使用。

控制 最低支援的作業系統 說明
InkCanvas
InkToolbar
Windows 10 (版本 1903) 在您的 Windows Forms 或 WPF 傳統型應用程式中,為 Windows Ink 型使用者互動提供介面和相關的工具列。
MediaPlayerElement Windows 10 (版本 1903) 內嵌檢視,該檢視會在 Windows Forms 或 WPF 傳統型應用程式中串流和轉譯媒體內容 (例如影片)。
MapControl Windows 10 (版本 1903) 可讓您在 Windows Forms 或 WPF 傳統型應用程式中顯示符號或真實感地圖。

如需示範如何使用包裝的 WinRT XAML 控制項的逐步解說,請參閱在 WPF 應用程式中裝載標準 WinRT XAML 控制項

主控制項

對於可用包裝的控制項未涵蓋的自訂控制項和其他案例,WPF 和 Windows Forms 應用程式也可以使用「Windows 社群工具組」中提供的 WindowsXamlHost 控制項。

控制 最低支援的作業系統 說明
WindowsXamlHost Windows 10 (版本 1903) 可以裝載衍生自 Windows.UI.Xaml.UIElement 的任何 WinRT XAML 控制項,包括 Windows SDK 所提供的任何第一方 WinRT XAML 控制項,以及自訂控制項。

如需示範如何使用 WindowsXamlHost 控制項的逐步解說,請參閱 在 WPF 應用程式中裝載標準 WinRT XAML 控制項使用 XAML Islands 在 WPF 應用程式中裝載自訂 WinRT XAML 控制項

將您的專案設定為使用 XAML Island .NET 控制項

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

控制項的類型 NuGet 套件 相關文章
包裝的控制項 這些套件的 6.0.0 版或更新版本: 在 WPF 應用程式中裝載標準 WinRT XAML 控制項
主控制項 這些套件的 6.0.0 版或更新版本: 在 WPF 應用程式中裝載標準 WinRT XAML 控制項
在 WPF 應用程式中裝載自訂 WinRT XAML 控制項

請注意下列詳細資料:

  • 主控制項套件也會包含在包裝的控制項套件中。 如果您想要同時使用這兩組控制項,您可以安裝包裝的控制項套件。

  • 如果您裝載的是自訂 WinRT XAML 控制項,您也必須執行一些額外的步驟來參考自訂控制項。 如需詳細資訊,請參閱使用 XAML Islands 在 WPF 應用程式中裝載自訂 WinRT XAML 控制項

Web 檢視控制項

「Windows 社區工具組」也提供下列 .NET 控制項,以便在 WPF 和 Windows Forms 應用程式中裝載 Web 內容。 這些控制項通常用於類似的傳統型應用程式現代化案例,作為 XAML Island 控制項,而且它們會在與 XAML Island 控制項相同的 Microsoft.Toolkit.Win32 存放庫中進行維護。

控制 最低支援的作業系統 說明
WebView Windows 10 (版本 1803) 使用 Microsoft Edge 轉譯引擎來顯示 Web 內容。
WebViewCompatible Windows 7 提供與更多作業系統版本相容的 WebView 版本。 此控制項使用 Microsoft Edge 轉譯引擎來顯示 Windows 10 1803 版和更新版本上的 Web 內容,以及使用 Internet Explorer 轉譯引擎來顯示舊版 Windows 10、Windows 8.x 和 Windows 7 上的 Web 內容。

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

C + + desktop (Win32) 應用程式

C + + 桌面應用程式不支援 XAML 島 .NET 控制項。 這些應用程式必須改為使用 Windows 10 SDK (1903 版和更新版本) 所提供的 WinRT XAML 裝載 API

WinRT XAML 裝載 API 包含數個 Windows 執行階段類別和 COM 介面,可供您的 c + + 桌面應用程式用來裝載任何衍生自 Windows 的 WinRT XAML 控制項。UI。Xaml。 UIElement。 您可以在具有相關聯視窗控制碼 (HWND) 的應用程式中,將 WinRT XAML 控制項裝載於任何 UI 元素中。 如需此 API 的詳細資訊,請參閱下列文章:

注意

Windows 社群工具組中包裝的控制項和主控制項,會在內部使用 winrt xaml 裝載 api,並在您直接使用 winrt xaml 裝載 api (包括鍵盤流覽和配置變更)時,執行您需要自行處理的所有行為。 針對 WPF 和 Windows Forms 應用程式,我們強烈建議您直接使用這些控制項,而不是直接使用 WinRT XAML 裝載 api,因為它們會將許多使用 api 的執行詳細資料抽象化掉。

XAML Island 的架構

以下將快速探討不同類型的 XAML 島控制項如何以在 WinRT XAML 裝載 API 的基礎結構上組織。

裝載控制項架構

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

限制和因應措施

下列各節將討論使用 XAML Islands 的傳統型應用程式中某些 UWP 開發案例的限制和因應措施。

有因應措施才能使用

: heavy_check_mark: XAML 島的目前版本中有條件地支援從 XAML 島中的 WinUI 2 程式庫 裝載控制項。 如果您的桌面應用程式使用 MSIX 套件進行部署,則可以從 Microsoft.UI.XamlNugGet 套件的搶鮮版或發行版本裝載 WinUI 控制項。 如果您的傳統型應用程式未使用 MSIX 進行封裝,您必須先安裝 Microsoft.UI.Xaml NuGet 套件搶鮮版才能裝載 WinUI 控制項。 WinUI 3.0 程式庫中的裝載控制項支援會在之後的版本中推出。

✔️若要在 XAML Island 中存取 XAML 內容樹狀結構的根元素,並取得其裝載所在內容的相關資訊,請勿使用 CoreWindowApplicationViewWindow 類別。 而是改成使用 XamlRoot 類別。 如需詳細資訊,請參閱本節

: heavy_check_mark:若要從 WPF、Windows Forms 或 c + + desktop (Win32) 應用程式支援共用合約,您的應用程式必須使用IDataTransferManagerInterop介面取得DataTransferManager物件,以起始特定視窗的共用作業。 如需示範如何在 WPF 應用程式中使用此介面的範例,請參閱 ShareSource 範例

✔️不支援在 XAML Islands 中搭配使用 x:Bind 與裝載控制項。 您將必須在 .NET Standard 程式庫中宣告資料模型。

不受支援

🚫在以 .NET Framework 為目標的 WPF 和 Windows Forms 應用程式中使用 XAML Islands。 只有以 .NET Core 3.x 為目標的應用程式才支援 XAML Islands。

🚫在執行階段,XAML Islands 中的 UWP XAML 內容不會回應從深色變淺色的 Windows 主題變更,反之亦然。 內容會在執行階段回應高對比變更。

🚫新增 WebView 控制項到自訂使用者控制項 (開啟執行緒、關閉執行緒或退出程序)。

🚫在全螢幕模式中不支援 MediaPlayer 控制項和 MediaPlayerElement 主控制項。

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

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

🚫XAML Islands 不支援裝載 ContentDialog,其中包含接受文字輸入的控制項,例如 TextBoxRichEditBoxAutoSuggestBox。 如果這樣做,輸入控制項將不會正確地回應按鍵功能。 若要使用 XAML Island 來達到類似的功能,建議您裝載包含輸入控制項的快顯視窗

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

XAML Island 的視窗裝載內容

當您在桌面應用程式中裝載 XAML Island 時,您可以在相同的執行緒上同時執行 XAML 內容的多個樹狀結構。 若要在 XAML Island 中存取 XAML 內容樹狀結構的根元素,並取得其裝載所在內容的相關資訊,請使用 XamlRoot 類別。 CoreWindowApplicationViewWindow 類別不會提供 XAML Island 的正確資訊。 CoreWindowWindow 物件存在於執行緒上,且可供您的應用程式存取,但不會傳回有意義的界限或可見度 (這些物件一律不可見,且大小為 1x1)。 如需詳細資訊,請參閱視窗裝載

例如,若要取得裝載在 XAML Island 中的 WinRT XAML 控制項所在視窗的周框矩形,請使用控制項的 XamlRoot.Size 屬性。 可裝載於 XAML Island 中的每個 WinRT XAML 控制項都衍生自 Windows.UI.Xaml.UIElement,因此您可以使用控制項的 XamlRoot 屬性來存取 XamlRoot 物件。

Size windowSize = myUWPControl.XamlRoot.Size;

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

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

如需您在 XAML Island 內容中應避免使用的一般視窗相關 API 的表格,以及建議的 XamlRoot 取代項目,請參閱本節的表格。

如需示範如何在 WPF 應用程式中使用此介面的範例,請參閱 ShareSource 範例。

其他資源

如需有關使用 XAML Islands 的更多背景資訊和教學課程,請參閱下列文章和資源:

  • 將 WPF 應用程式現代化教學課程:本教學課程提供逐步指示,說明如何使用「Windows 社區工具組」中包裝的控制項和主控制項,將 WinRT XAML 控制項新增至現有的 WPF 企業營運應用程式。 本教學課程包含 WPF 應用程式的完整程式碼,以及程序中每個步驟的詳細指示。
  • XAML 島程式碼範例:此存放庫包含 Windows Forms、WPF 和 c + + desktop (Win32) 範例,示範如何使用 XAML 孤島。
  • XAML Islands v1 - 更新與藍圖:此部落格文章討論許多有關 XAML Islands 的常見問題,並提供詳細的開發藍圖。