Controlos XAML UWP de host em aplicações de ambiente de trabalho (Ilhas XAML UWP)

A partir do Windows 10, versão 1903, pode hospedar controlos XAML UWP em aplicações desktop não-UWP, usando uma funcionalidade chamada UWP XAML Islands. Esta funcionalidade permite-lhe melhorar o aspeto, a sensação e a funcionalidade das suas aplicações existentes para WPF, Windows Forms e C++ desktop (Win32) com funcionalidades da interface do Windows que só estão disponíveis através de controlos UWP XAML. Isto significa que pode usar funcionalidades UWP como Windows Ink e controlos que suportam o Fluent Design System nas suas aplicações de ambiente de trabalho WPF, Windows Forms e C++ existentes.

Pode alojar qualquer controlo UWP XAML que derive de Windows.UI.Xaml.UIElement, incluindo:

• A maioria dos controlos UWP XAML de primeira parte fornecidos pelo SDK do Windows ou pela biblioteca WinUI para UWP (ver exceções).
• Qualquer controlo UWP XAML personalizado (por exemplo, um controlo de utilizador que consiste em vários controlos UWP XAML que funcionam em conjunto). Você deve ter o código-fonte para o controle personalizado para que você possa compilá-lo com seu aplicativo.

Fundamentalmente, as Ilhas XAML UWP são criadas utilizando a API de alojamento UWP XAML. Esta API consiste em várias classes de Windows Runtime e interfaces COM que foram introduzidas no SDK do Windows 10, versão 1903. Também fornecemos um conjunto de controlos de .NET XAML Island no Windows Community Toolkit que utilizam internamente a API de alojamento UWP XAML e proporcionam uma experiência de desenvolvimento mais conveniente para aplicações WPF e Windows Forms.

A forma como usas as Ilhas XAML UWP depende do tipo de aplicação e dos tipos de controlos UWP XAML que queres alojar.

Requerimentos

As ilhas XAML UWP têm estes requisitos de tempo de execução:

• Windows 10, versão 1903, ou uma versão posterior.
• Se seu aplicativo não estiver empacotado em um pacote MSIX para implantação, o computador deve ter o Visual C++ Runtime instalado.

Aplicações WPF e Windows Forms

Recomendamos que as aplicações WPF e Windows Forms utilizem os controlos XAML Island .NET disponíveis no Windows Community Toolkit. Estes controlos fornecem um modelo de objeto que imita (ou dá acesso a) as propriedades, métodos e eventos dos respetivos controlos UWP XAML. Eles também lidam com comportamentos como navegação pelo teclado e alterações de layout.

Existem dois conjuntos de controlos de ilha XAML para aplicações WPF e Windows Forms: controlos wrapped e controlos host.

Controles encapsulados

As aplicações WPF e Windows Forms podem usar uma seleção de controles XAML Island que integram a interface e a funcionalidade de um controle XAML UWP específico. Podes adicionar estes controlos diretamente à superfície de design do teu projeto WPF ou Windows Forms e depois utilizá-los como qualquer outro controlo WPF ou Windows Forms no designer.

Os seguintes controlos UWP XAML incorporados estão atualmente disponíveis no Windows Community Toolkit.

Para um guia que demonstra como usar os controlos UWP XAML encapsulados, veja Use ilhas XAML para hospedar um controlo UWP XAML numa aplicação WPF C#.

Controles do anfitrião

Para controlos personalizados e outros cenários para além daqueles cobertos pelos controlos wrapped disponíveis, as aplicações WPF e Windows Forms podem também usar o controlo WindowsXamlHost disponível no Windows Community Toolkit.

Para um passo a passo que mostra como usar o controlo WindowsXamlHost, consulte Use ilhas XAML para hospedar um controlo XAML UWP numa aplicação C# WPF e Hospede um controlo XAML personalizado UWP numa aplicação WPF usando ilhas XAML.

Configure o seu project para usar os controlos .NET do XAML Island

Os controlos XAML Island .NET requerem Windows 10, versão 1903 ou uma versão posterior. Para usar esses controles, instale um dos pacotes NuGet listados abaixo. Esses pacotes fornecem tudo o que você precisa para usar os controles encapsulados de XAML Island e os controles de host, incluindo outros pacotes NuGet relacionados que também são necessários.

Esteja atento aos seguintes detalhes:

• Os pacotes de controle de host também estão incluídos nos pacotes de controle empacotados. Você pode instalar os pacotes de controle encapsulados se quiser usar ambos os conjuntos de controles.

• Se estiveres a hospedar um controlo UWP XAML personalizado, também terás de fazer alguns passos adicionais para referenciar o controlo personalizado. Para mais informações, veja Hospedar um controlo UWP XAML personalizado numa aplicação WPF usando ilhas XAML.

Controles de exibição da Web

O Windows Community Toolkit também fornece os seguintes controlos .NET para alojar conteúdos web em aplicações WPF e Windows Forms. Estes controlos são frequentemente usados em cenários de modernização de aplicações desktop semelhantes aos controlos da ilha XAML, e são mantidos no mesmo repositório Microsoft.Toolkit.Win32 que os controlos da ilha XAML.

Para usar esses controles, instale um destes pacotes NuGet:

• WPF: Microsoft.Toolkit. Wpf. UI. Controls.WebView
• Windows Forms: Microsoft. Toolkit.Forms.UI.Controls.WebView

Aplicativos de área de trabalho C++ (Win32)

Os controlos .NET do XAML Island não são suportados em aplicações desktop C++. Estas aplicações devem, em vez disso, utilizar a API de alojamento XAML UWP fornecida pelo SDK Windows 10 (versão 1903 e posteriores).

A API de alojamento UWP XAML consiste em várias classes Windows Runtime e interfaces COM que a sua aplicação de ambiente de trabalho C++ pode usar para alojar qualquer controlo UWP XAML que derive de Windows. UI. Xaml.UIElement. Pode alojar controlos UWP XAML em qualquer elemento da interface da sua aplicação que tenha um handle de janela associado (HWND). Para obter mais informações sobre essa API, consulte os seguintes artigos.

• Utilização da API de alojamento UWP XAML numa aplicação de ambiente de trabalho C++
• Hospedar um controlo UWP XAML padrão numa aplicação de ambiente de trabalho C++
• Hospedar um controlo UWP XAML personalizado numa aplicação de ambiente de trabalho C++

Arquitetura das Ilhas XAML UWP

Aqui está uma rápida visão geral de como os diferentes tipos de controlos da Ilha XAML estão organizados arquitetonicamente sobre a API de alojamento UWP XAML.

As APIs que aparecem na parte inferior deste diagrama são fornecidas com o SDK do Windows. Os controles encapsulados e os controles de host estão disponíveis por meio de pacotes NuGet no Kit de Ferramentas da Comunidade do Windows.

Limitações e soluções alternativas

As secções seguintes discutem limitações e soluções alternativas para certos cenários de desenvolvimento UWP em aplicações de ambiente de trabalho que utilizam ilhas UWP XAML.

Suportado apenas com soluções alternativas

✔️ O alojamento de controlos a partir do WinUI para a Biblioteca UWP numa ilha XAML é suportado condicionalmente na versão atual das Ilhas XAML UWP. Se seu aplicativo de área de trabalho usa um pacote MSIX para implantação, você pode hospedar controles WinUI de versões de pré-lançamento ou de lançamento do pacote Microsoft.UI.Xaml NuGet. Se seu aplicativo da área de trabalho não estiver empacotado usando MSIX, você poderá hospedar controles WinUI somente se instalar uma versão de pré-lançamento do pacote NuGet Microsoft.UI.Xaml ou se usar a API de Dependências Dinâmicas .

✔️ Para aceder ao elemento raiz de uma árvore de conteúdo XAML num XAML Island e obter informações relacionadas sobre o contexto em que está alojado, não use as classes CoreWindow, ApplicationView e Window. Em vez disso, use a classe XamlRoot. Para obter mais informações, consulte esta seção.

✔️ Para suportar o contrato Share de uma aplicação desktop WPF, Windows Forms ou C++ (Win32), a sua aplicação deve usar a interface IDataTransferManagerInterop para que o objeto DataTransferManager inicie a operação de partilha para uma janela específica. Para um exemplo que demonstra como usar esta interface numa aplicação WPF, veja o exemplo ShareSource.

✔️ A utilização de x:Bind com controlos alojados em ilhas XAML do UWP não é suportada. Terás de declarar o modelo de dados numa biblioteca .NET Standard.

Não suportado

🚫 Utilização de ilhas UWP XAML em aplicações WPF e Windows Forms que têm como alvo o .NET Framework. As Ilhas XAML UWP são suportadas apenas em aplicações que visam o .NET Core 3.x.

🚫 conteúdo UWP XAML em UWP XAML Islands não responde a alterações de tema do Windows de escuro para claro ou vice-versa durante a execução. O conteúdo responde a alterações de alto contraste em tempo de execução.

🚫 Adicionando um controlo Windows.UI.Xaml.WebView. Para aplicações WPF e WinForms, veja estas alternativas.

🚫 O controlo MediaPlayer e o controlo MediaPlayerElement não funcionam em operação em ecrã completo.

🚫 Entrada de texto com a vista de caligrafia. Para obter mais informações sobre este recurso, consulte este artigo.

🚫 Controles de texto que usam @Places e @People links de conteúdo. Para obter mais informações sobre este recurso, consulte este artigo.

As ilhas XAML 🚫 UWP não suportam o alojamento de um ContentDialog que contenha um controlo que permita a entrada de texto, como um TextBox, RichEditBox ou AutoSuggestBox. Se você fizer isso, o controle de entrada não responderá corretamente a pressionamentos de teclas. Para obter uma funcionalidade semelhante usando uma ilha de XAML, recomendamos que se hospede um Popup que contenha o controlo de entrada.

As ilhas XAML UWP não suportam atualmente a exibição de ficheiros SVG num controlo Windows.UI.Xaml.Controls.Image hospedado ou utilizando um objeto Windows.UI.Xaml.Media.Imaging.SvgImageSource. Como solução alternativa, converta os arquivos de imagem que deseja exibir em formatos baseados em raster, como JPG ou PNG.

Contexto de janela do host para ilhas XAML

Quando alojas ilhas XAML UWP numa aplicação de ambiente de trabalho, podes ter várias árvores de conteúdo XAML a correr no mesmo tópico ao mesmo tempo. Para aceder ao elemento raiz de uma árvore de conteúdo XAML numa ilha XAML e obter informações relacionadas sobre o contexto em que está alojado, use a classe XamlRoot. As classes CoreWindow, ApplicationView e Window não fornecem a informação correta para as ilhas XAML UWP. os objetos CoreWindow e Window existem na thread e são acessíveis na sua aplicação, mas não retornarão limites significativos ou visibilidade (são sempre invisíveis e têm um tamanho de 1x1). Para obter mais informações, consulte Windowing hosts.

Por exemplo, para obter o retângulo delimitador da janela que contém um controlo UWP XAML alojado numa XAML Island, use a propriedade XamlRoot.Size do controlo. Porque todos os controlos XAML UWP que podem ser alojados numa ilha XAML derivam de Windows. UI. Xaml.UIElement, podes usar a propriedade XamlRoot do controlo para aceder ao objeto XamlRoot.

Size windowSize = myUWPControl.XamlRoot.Size;

Não use a propriedade CoreWindows.Bounds para obter o retângulo de delimitação.

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

Para uma tabela das APIs comuns relacionadas com janelas que deve evitar no contexto das Ilhas XAML UWP e das substituições recomendadas do XamlRoot , consulte a tabela nesta secção.

Para um exemplo que demonstre como usar esta interface numa aplicação WPF, consulte o exemplo ShareSource.

Recursos adicionais

Para mais informações de contexto e tutoriais sobre a utilização de ilhas UWP XAML, consulte os seguintes artigos e recursos:

• Exemplos de código UWP XAML Islands: Este repositório contém exemplos de Windows Forms, WPF e C++ desktop (Win32) que demonstram como usar UWP XAML Islands.
• UWP XAML Islands v1 - Atualizações e Roteiro: Este artigo de blogue discute muitas questões comuns sobre as Ilhas XAML da UWP e fornece um roteiro detalhado de desenvolvimento.