Använd WinRT XAML-kontroller i skrivbordsappar (XAML-öar)

Från och med Windows 10, version 1903, kan du vara värd för WinRT XAML-kontroller i icke-UWP-skrivbordsprogram med hjälp av en funktion som kallas XAML Islands. Med den här funktionen kan du förbättra utseendet, känslan och funktionerna i dina befintliga WPF-, Windows Forms- och C++-skrivbordsprogram (Win32) med de senaste Funktionerna i Windows-användargränssnittet som endast är tillgängliga via WinRT XAML-kontroller. Det innebär att du kan använda UWP-funktioner som Windows Ink och kontroller som stöder Fluent Design System i dina befintliga WPF-, Windows Forms- och C++-skrivbordsprogram.

Du kan vara värd för alla WinRT XAML-kontroller som härleds från Windows.UI.Xaml.UIElement, inklusive:

• De flesta förstapartskontroller för WinRT XAML som tillhandahålls av Windows SDK eller WinUI 2-biblioteket (se undantag).
• Alla anpassade WinRT XAML-kontroller (till exempel en användarkontroll som består av flera WinRT XAML-kontroller som fungerar tillsammans). Du måste ha källkoden för den anpassade kontrollen så att du kan kompilera den med ditt program.

I grund och botten skapas XAML-öar med hjälp av WinRT XAML-hosting-API:et. Det här API:et består av flera Windows Runtime-klasser och COM-gränssnitt som introducerades i Windows 10 version 1903 SDK. Vi tillhandahåller också en uppsättning XAML Island .NET-kontroller i Windows Community Toolkit som använder WinRT XAML-värd-API:et internt och ger en bekvämare utvecklingsupplevelse för WPF- och Windows Forms-appar.

Hur du använder XAML-öar beror på din programtyp och vilka typer av WinRT XAML-kontroller du vill vara värd för.

Kravspecifikation

XAML-öarna har följande körningstidskrav:

• Windows 10, version 1903 eller en senare version.
• Om programmet inte är paketerat i ett MSIX-paket för distribution måste datorn ha Visual C++ Runtime installerat.

WPF- och Windows Forms-program

Vi rekommenderar att WPF- och Windows Forms-program använder XAML Island .NET-kontrollerna som är tillgängliga i Windows Community Toolkit. Dessa kontroller ger en objektmodell som efterliknar (eller ger åtkomst till) egenskaper, metoder och händelser för motsvarande WinRT XAML-kontroller. De hanterar även beteende som tangentbordsnavigering och layoutändringar.

Det finns två uppsättningar XAML Island-kontroller för WPF- och Windows Forms-program: omslutna kontroller och värdkontroller.

Omslutna kontroller

WPF- och Windows Forms-program kan använda ett urval av XAML Island-kontroller som omsluter gränssnittet och funktionerna i en specifik WinRT XAML-kontroll. Du kan lägga till dessa kontroller direkt på designytan för ditt WPF- eller Windows Forms-projekt och sedan använda dem som andra WPF- eller Windows Forms-kontroller i designern.

Följande omslutna WinRT XAML-kontroller är för närvarande tillgängliga i Windows Community Toolkit.

En genomgång som visar hur du använder de omslutna WinRT XAML-kontrollerna finns i Använda XAML-öar som värd för en UWP XAML-kontroll i en C#WPF-app.

Värdkontroller

För anpassade kontroller och andra scenarier utöver de som omfattas av de tillgängliga omslutna kontrollerna kan WPF- och Windows Forms-program också använda WindowsXamlHost-kontrollen som är tillgänglig i Windows Community Toolkit.

Genomgångar som visar hur du använder WindowsXamlHost- kontroll finns i Använda XAML-öar som värd för en UWP XAML-kontroll i en C#WPF-app och Värd för en anpassad WinRT XAML-kontroll i en WPF-app med XAML Islands.

Konfigurera projektet så att det använder XAML Island .NET-kontrollerna

XAML Island .NET-kontrollerna kräver Windows 10, version 1903 eller en senare version. Om du vill använda dessa kontroller installerar du ett av De NuGet-paket som anges nedan. De här paketen innehåller allt du behöver för att använda de omslutna kontrollerna och värdkontrollerna för XAML Island, och de innehåller andra relaterade NuGet-paket som också krävs.

Tänk på följande information:

• Värdkontrollpaketen ingår också i de omslutande kontrollpaketen. Du kan installera de omslutna kontrollpaketen om du vill använda båda uppsättningarna med kontroller.

• Om du är värd för en anpassad WinRT XAML-kontroll måste du också utföra några ytterligare steg för att referera till den anpassade kontrollen. För mer information, se Att använda en anpassad WinRT XAML-kontroll i en WPF-applikation genom att använda XAML Islands.

Webbvisningskontroller

Windows Community Toolkit innehåller också följande .NET-kontroller för att vara värd för webbinnehåll i WPF- och Windows Forms-program. Dessa kontroller används ofta i liknande scenarier för modernisering av skrivbordsappar som XAML Island-kontrollerna, och de underhålls på samma Microsoft.Toolkit.Win32-lagringsplats som XAML Island-kontrollerna.

Om du vill använda dessa kontroller installerar du något av följande NuGet-paket:

• WPF: Microsoft.Toolkit.Wpf.UI.Controls.WebView
• Windows-formulär: Microsoft.Toolkit.Forms.UI.Controls.WebView

C++-skrivbordsprogram (Win32)

XAML Island .NET-kontrollerna stöds inte i C++-skrivbordsprogram. Dessa program måste i stället använda WinRT XAML-värd-API:et som tillhandahålls av Windows 10 SDK (version 1903 och senare).

WinRT XAML-värd-API:et består av flera Windows Runtime-klasser och COM-gränssnitt som din C++-skrivbordsapplikation kan använda för att värda alla WinRT XAML-kontroller som härleds från Windows.UI.Xaml.UIElement. Du kan vara värd för WinRT XAML-kontroller i valfritt gränssnittselement i ditt program som har ett associerat fönsterhandtag (HWND). Mer information om det här API:et finns i följande artiklar.

• Använda WinRT XAML hosting-API:et i en C++-skrivbordsapp
• Värd för en Standard WinRT XAML-kontroll i en C++-skrivbordsapp
• Använd en anpassad WinRT XAML-kontroll i en C++-skrivbordsapplikation

Arkitektur för XAML-öar

Här är en snabb titt på hur de olika typerna av XAML Island-kontroller organiseras arkitektoniskt ovanpå WinRT XAML-värd-API:et.

API:erna som visas längst ned i det här diagrammet levereras med Windows SDK. De omslutna kontrollerna och värdkontrollerna är tillgängliga via NuGet-paket i Windows Community Toolkit.

Begränsningar och lösningar

I följande avsnitt beskrivs begränsningar och lösningar för vissa UWP-utvecklingsscenarier i skrivbordsappar som använder XAML-öar.

Stöds endast med tillfälliga åtgärder

✔️ Värdkontroller från WinUI 2 Library på en XAML-ö stöds villkorligt i den aktuella versionen av XAML Islands. Om din skrivbordsapp använder ett MSIX-paket för distribution kan du använda WinUI-kontroller från förhandsversioner eller släppversioner av Microsoft.UI.Xaml- NuGet-paketet. Om din skrivbordsapp inte paketeras med MSIX kan du endast hosta WinUI-kontroller om du installerar en förhandsversion av NuGet-paketet Microsoft.UI.Xaml eller om du använder det dynamiska beroenden-API:t . Stöd för värdkontroller från WinUI 3.0-biblioteket kommer i en senare version.

✔️ Om du vill komma åt rotelementet i ett träd med XAML-innehåll på en XAML-ö och hämta relaterad information om kontexten där det finns, ska du inte använda klasserna CoreWindow, ApplicationView och Window . Använd I stället klassen XamlRoot . Mer information finns i det här avsnittet.

✔️ För att stödja Share-kontrakt från en WPF-, Windows Forms- eller C++-skrivbordsapp (Win32) måste appen använda IDataTransferManagerInterop--gränssnittet för att hämta DataTransferManager-objektet för att initiera delningsåtgärden för ett specifikt fönster. Ett exempel som visar hur du använder det här gränssnittet i en WPF-app finns i ShareSource-exemplet.

✔️ Det går inte att använda x:Bind med värdbaserade kontroller på XAML-öarna. Du måste deklarera datamodellen i ett .NET Standard-bibliotek.

Stöds inte

🚫 Använda XAML-öar i WPF- och Windows Forms-appar som riktar sig till .NET Framework. XAML-öarna stöds endast i appar som är avsedda för .NET Core 3.x.

🚫 UWP XAML-innehåll i XAML-öar svarar inte på ändringar i Windows-tema från mörkt till ljust eller vice versa under körning. Innehållet svarar på ändringar med hög kontrast under körning.

🚫 Lägga till en Windows.UI.Xaml.WebView-kontroll . För WPF- och WinForms-appar, se dessa alternativ.

🚫 MediaPlayer-kontrollen och MediaPlayerElement-värdkontrollen stöds inte i helskärmsläge.

🚫 Textinmatning med handskriftsvyn. Mer information om den här funktionen finns i den här artikeln.

🚫 Textkontroller som använder @Places och @People innehållslänkar. Mer information om den här funktionen finns i den här artikeln.

🚫 XAML-öarna kan inte vara värd för en ContentDialog- som innehåller en kontroll som tar emot textinmatning, till exempel en TextBox, RichEditBoxeller AutoSuggestBox. Om du gör detta svarar inte inmatningskontrollen korrekt på tangenttryckning. För att uppnå liknande funktioner med hjälp av en XAML Island rekommenderar vi att du använder en Popup som innehåller indatakontrollen.

🚫 XAML-öarna stöder för närvarande inte visning av SVG-filer i en hostad Windows.UI.Xaml.Controls.Image-kontroll eller med hjälp av ett Windows.UI.Xaml.Media.Imaging.SvgImageSource-objekt. Som en lösning konverterar du de bildfiler som du vill visa till rasterbaserade format som JPG eller PNG.

Värdkontext för fönster i XAML-öar

När du är värd för XAML Islands i en skrivbordsapp kan du ha flera träd med XAML-innehåll som körs på samma tråd samtidigt. Om du vill komma åt rotelementet i ett träd med XAML-innehåll på en XAML-ö och hämta relaterad information om kontexten där det finns använder du klassen XamlRoot . Klasserna CoreWindow, ApplicationView och Window ger inte rätt information för XAML-öarna. CoreWindow- och Window-objekt finns i tråden och är tillgängliga för din app, men de returnerar inte meningsfulla gränser eller synlighet (de är alltid osynliga och har storleken 1x1). För mer information, se Fönsterhanterare.

Om du till exempel vill hämta avgränsningsrektangeln för fönstret som innehåller en WinRT XAML-kontroll som finns på en XAML-ö använder du egenskapen XamlRoot.Size för kontrollen. Eftersom varje WinRT XAML-kontroll som kan finnas på en XAML-ö härleds från Windows.UI.Xaml.UIElement, kan du använda XamlRoot-egenskapen för kontrollen för att komma åt XamlRoot-objektet .

Size windowSize = myUWPControl.XamlRoot.Size;

Använd inte egenskapen CoreWindows.Bounds för att hämta avgränsningsrektangeln.

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

En tabell med vanliga fönsterrelaterade API:er som du bör undvika i samband med XAML Islands och de rekommenderade XamlRoot-ersättningarna finns i tabellen i det här avsnittet.

Ett exempel som visar hur du använder det här gränssnittet i en WPF-app finns i ShareSource-exemplet .

Ytterligare resurser

Mer bakgrundsinformation och självstudier om hur du använder XAML-öar finns i följande artiklar och resurser:

• Modernisera en WPF-appguide: Den här självstudien innehåller stegvisa instruktioner för hur du använder de omslutna kontrollerna och värdkontrollerna i Windows Community Toolkit för att lägga till WinRT XAML-kontroller i ett befintligt affärsprogram för WPF. Den här handledningen innehåller den fullständiga koden för WPF-programmet samt detaljerade instruktioner för varje steg i processen.
• XAML Islands-kodexempel: Den här lagringsplatsen innehåller Windows Forms-, WPF- och C++-skrivbordsexempel (Win32) som visar hur du använder XAML-öar.
• XAML Islands v1 – Uppdateringar och översikt: Det här blogginlägget beskriver många vanliga frågor om XAML-öar och innehåller en detaljerad utvecklingsöversikt.