ContentIsland

ContentIslandes una API de WinUI 3 y SDK de Aplicaciones para Windows que te permite hospedar contenido de representación que no sea XAML, como objetos visuales de composición, contenido win2D o superficies de Direct3D, dentro de una aplicación WinUI 3. Cada isla es una superficie de representación aislada con su propio estado de entrada, salida, diseño y accesibilidad. Se conecta una isla secundaria a un lugar de la isla principal utilizando un ChildSiteLink.

Usa ContentIsland para escenarios de interoperabilidad avanzados en los que necesitas contenido que no se expresa como elementos XAML estándar.

Funcionamiento de ContentIsland

Una aplicación XAML de WinUI 3 ya se ejecuta dentro de ContentIsland. Puede obtener esa isla principal desde XamlRoot.ContentIsland. Para colocar contenido adicional que no sea XAML dentro del árbol XAML, haga lo siguiente:

1. Reservar espacio en XAML.
2. Crea un elemento visual de ubicación en la isla principal.
3. Cree un ChildSiteLink para ese elemento visual de ubicación.
4. Crea una ContentIsland secundaria con su propio elemento visual raíz.
5. Conecte la isla hija y mantenga su tamaño y sus transformaciones sincronizados con el diseño XAML.

La isla secundaria puede entonces hospedar contenido de Composition, dibujos Win2D, elementos visuales basados en Direct3D u otro contenido de renderizado que no sea XAML.

Reservar espacio en XAML

Comience con un contenedor raíz y un elemento marcador de posición donde aparecerá la isla hija.

<Grid x:Name="RootPanel">
    <Border x:Name="IslandHost"
            Width="320"
            Height="200"
            HorizontalAlignment="Left"
            VerticalAlignment="Top" />
</Grid>

Crear una isla hija

Crea un elemento visual de ubicación en la isla principal y, a continuación, crea y conecta la isla secundaria.

using System.Numerics;
using Microsoft.UI.Composition;
using Microsoft.UI.Content;
using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Hosting;

private ChildSiteLink? _childSiteLink;
private ContentIsland? _childIsland;
private ContainerVisual? _placementVisual;
private ContainerVisual? _childRootVisual;

private void CreateContentIsland()
{
    ContentIsland parentIsland = IslandHost.XamlRoot.ContentIsland;
    Compositor compositor = ElementCompositionPreview.GetElementVisual(RootPanel).Compositor;

    // This visual marks where the child island appears inside the parent island.
    _placementVisual = compositor.CreateContainerVisual();
    ElementCompositionPreview.SetElementChildVisual(RootPanel, _placementVisual);

    _childSiteLink = ChildSiteLink.Create(parentIsland, _placementVisual);

    // Create the root visual for the child island's own scene graph.
    _childRootVisual = compositor.CreateContainerVisual();
    _childIsland = ContentIsland.Create(_childRootVisual);

    _childSiteLink.Connect(_childIsland);

    UpdateContentIslandLayout();
}

ContentIsland.Create toma el Visual raíz para la escena de la isla. Una vez conectada la isla, puedes añadir contenido de Composition bajo ese elemento visual raíz.

Colocar la isla en relación con un elemento XAML

Mantenga el elemento visual de colocación y el ChildSiteLink sincronizados con el elemento marcador de posición. Este ejemplo asigna los límites del marcador de posición al panel raíz y, a continuación, actualiza tanto el elemento visual de colocación como el enlace.

using System.Numerics;
using Windows.Foundation;

private void UpdateContentIslandLayout()
{
    if (_placementVisual is null || _childSiteLink is null)
    {
        return;
    }

    GeneralTransform transform = IslandHost.TransformToVisual(RootPanel);
    Point position = transform.TransformPoint(new Point(0, 0));

    Vector2 size = new((float)IslandHost.ActualWidth, (float)IslandHost.ActualHeight);
    Vector3 offset = new((float)position.X, (float)position.Y, 0);

    _placementVisual.Offset = offset;
    _placementVisual.Size = size;

    _childSiteLink.ActualSize = size;
    _childSiteLink.LocalToParentTransformMatrix =
        Matrix4x4.CreateTranslation(offset);
}

Sincronizar cambios de diseño

Suscríbase a los cambios de diseño para que la isla secundaria permanezca alineada con el marcador de posición XAML.

public MainPage()
{
    this.InitializeComponent();

    // XamlRoot is null until the element is in the visual tree.
    // Defer ContentIsland creation to the Loaded event.
    IslandHost.Loaded += OnIslandHostLoaded;
    IslandHost.LayoutUpdated += OnIslandHostLayoutUpdated;
    IslandHost.Unloaded += OnIslandHostUnloaded;
}

private void OnIslandHostLoaded(object sender, RoutedEventArgs e)
{
    IslandHost.Loaded -= OnIslandHostLoaded;
    CreateContentIsland();
}

private void OnIslandHostLayoutUpdated(object sender, object e)
{
    UpdateContentIslandLayout();
}

Si anima o cambia el tamaño del marcador de posición, llame a UpdateContentIslandLayout cada vez que cambie su tamaño o posición efectivos.

Añadir contenido a la isla hija

Una vez creada la isla secundaria, añade contenido de composición bajo el elemento visual raíz secundario.

private void AddSpriteVisual()
{
    if (_childRootVisual is null)
    {
        return;
    }

    Compositor compositor = _childRootVisual.Compositor;

    SpriteVisual sprite = compositor.CreateSpriteVisual();
    sprite.Size = new Vector2(320, 200);
    sprite.Brush = compositor.CreateColorBrush(Microsoft.UI.Colors.DodgerBlue);

    _childRootVisual.Children.InsertAtTop(sprite);
}

Puedes reemplazar el SpriteVisual por tu propio árbol visual basado en Win2D o Direct3D.

Limpieza de islas

ContentIsland y ChildSiteLink son recursos que se pueden ocultar. Cierre o desechelos cuando ya no sean necesarios.

private void OnIslandHostUnloaded(object sender, RoutedEventArgs e)
{
    IslandHost.LayoutUpdated -= OnIslandHostLayoutUpdated;
    IslandHost.Unloaded -= OnIslandHostUnloaded;

    _childIsland?.Close();
    _childSiteLink?.Close();

    _childIsland = null;
    _childSiteLink = null;
    _placementVisual = null;
    _childRootVisual = null;
}

Gestiona la limpieza en Unloaded o al cerrar la ventana para liberar de inmediato los recursos de renderizado.

Abrir la Galería de WinUI 3

La aplicación Galería de WinUI 3 incluye ejemplos interactivos de muchos controles y características de plataforma de WinUI 3.

Artículos relacionados

• Introducción a la capa visual
• Árbol visual de composición
• Uso de la capa visual con XAML de WinUI