Popup

In een pop-up wordt inhoud boven op de andere gebruikersinterface in uw app weergegeven. De klasse Popup in de naamruimte Microsoft.UI.Xaml.Controls.Primitives is een container voor algemeen gebruik voor die inhoud. Het heeft geen standaardvisualsjabloon, dus u geeft de inhoud, het uiterlijk en de logica om het te openen en te sluiten.

Popup is een bouwsteen op laag niveau. WinUI biedt ook besturingselementen voor veelvoorkomende soorten tijdelijke gebruikersinterface, zoals flyouts, dialoogvensters, TeachingTips en knopinfo. Deze controles omvatten hun eigen stijl, plaatsing en gedrag bij sluiten.

Is dit de juiste controle?

Gebruik geen Popup als een besturingselement op een hoger niveau past bij uw scenario. Gebruik in plaats daarvan deze besturingselementen:

Gebruik een Popup wanneer u aangepaste inhoud nodig hebt die boven uw gebruikersinterface zweeft en geen van deze besturingselementen aan uw behoeften voldoet. U kunt bijvoorbeeld een pop-up gebruiken voor een overlay die u zelf stijlt en plaatst.

Een pop-up is niet modaal, dus de gebruiker kan nog steeds communiceren met de gebruikersinterface erachter. Als de gebruiker moet reageren voordat deze doorgaat, gebruikt u een ContentDialog.

Aanbevelingen

• Geef de pop-upinhoud een achtergrond, een rand en afgeronde hoeken, zodat deze opvalt in de gebruikersinterface erachter. Het WinUI 3 Gallery-voorbeeld maakt gebruik van de AcrylicBackgroundFillColorDefaultBrush, SurfaceStrokeColorDefaultBrushen OverlayCornerRadius resources. Zie Acrylic material en ThemeShadow in Pop-ups voor meer informatie.
• Als u light dismiss niet inschakelt, voegt u een knop of een ander besturingselement toe waarmee de pop-up wordt gesloten.
• Houd de inhoud van pop-ups kort en gericht op één taak.

Een pop-up maken

De WinUI 3 Gallery-app bevat interactieve voorbeelden van WinUI-besturingselementen en -functies. Haal de app op uit de Microsoft Store of blader door de broncode op GitHub.

Een pop-up fungeert als host voor één element, dat u instelt als Child element. Het kind is meestal een paneel of een UserControl deelvenster dat de pop-upinhoud definieert. Als u de pop-up wilt weergeven, stelt u IsOpen in op true. Als u het wilt verbergen, stelt u het in IsOpen op false.

Dit voorbeeld is gebaseerd op het WinUI 3 Gallery-voorbeeld. Het definieert een pop-up naast de knop die deze opent en de pop-upinhoud bevat een knop waarmee de pop-up wordt gesloten.

<Grid HorizontalAlignment="Left" VerticalAlignment="Top">
    <Button Content="Show popup" Click="ShowPopupClicked" />
    <Popup x:Name="StandardPopup" HorizontalOffset="200" VerticalOffset="0">
        <Grid MinWidth="240"
              Padding="16"
              Background="{ThemeResource AcrylicBackgroundFillColorDefaultBrush}"
              BorderBrush="{ThemeResource SurfaceStrokeColorDefaultBrush}"
              BorderThickness="1"
              CornerRadius="{StaticResource OverlayCornerRadius}">
            <StackPanel Spacing="8">
                <TextBlock FontSize="16" Text="Simple popup" />
                <Button Content="Close" Click="ClosePopupClicked" />
            </StackPanel>
        </Grid>
    </Popup>
</Grid>

// Opens the popup if it isn't already open.
private void ShowPopupClicked(object sender, RoutedEventArgs e)
{
    if (!StandardPopup.IsOpen)
    {
        StandardPopup.IsOpen = true;
    }
}

// Closes the popup when the user clicks the Close button inside it.
private void ClosePopupClicked(object sender, RoutedEventArgs e)
{
    if (StandardPopup.IsOpen)
    {
        StandardPopup.IsOpen = false;
    }
}

Een pop-up maken in code

U kunt ook een pop-up in code maken zonder deze toe te voegen aan de visualstructuur. Een pop-up die u in XAML declareert of toevoegt aan een deelvenster in de visualstructuur, haalt de XamlRoot van het bovenliggende element op. Een pop-up zonder bovenliggend item heeft dat niet, dus u moet de eigenschap XamlRoot instellen voordat u deze opent.

private Popup? _popup;

private void ShowPopupFromCodeClicked(object sender, RoutedEventArgs e)
{
    _popup ??= new Popup
    {
        // PopupContent is a UserControl in your app that defines the popup content.
        Child = new PopupContent(),
        IsLightDismissEnabled = true,

        // Required because this popup isn't in the visual tree. Use the XamlRoot
        // of an element that's already loaded, such as the button that was clicked.
        XamlRoot = ((UIElement)sender).XamlRoot
    };

    _popup.IsOpen = true;
}

Een pop-up sluiten door buiten de pop-up te klikken

Standaard blijft een pop-up geopend totdat uw code IsOpen op false instelt. Stel IsLightDismissEnabled in op true om de pop-up te sluiten wanneer de gebruiker erbuiten klikt of tikt, of op de Esc-toets drukt. Dit gedrag wordt light dismiss genoemd.

Standaard wordt het gebied buiten een pop-up die sluit wanneer je erbuiten klikt niet donkerder. Als u het wilt donkerder maken, stelt u LightDismissOverlayMode in op On. Deze eigenschap heeft geen effect wanneer IsLightDismissEnabled dit is false.

<Popup x:Name="LightDismissPopup"
       IsLightDismissEnabled="True"
       LightDismissOverlayMode="On">
    <Border Padding="16"
            Background="{ThemeResource AcrylicBackgroundFillColorDefaultBrush}"
            BorderBrush="{ThemeResource SurfaceStrokeColorDefaultBrush}"
            BorderThickness="1"
            CornerRadius="{StaticResource OverlayCornerRadius}">
        <TextBlock Text="Click outside this popup or press Esc to close it." />
    </Border>
</Popup>

Een pop-up plaatsen

U kunt een pop-up plaatsen met behulp van offsets of ten opzichte van een ander element.

Offsets gebruiken

HorizontalOffset en VerticalOffset stellen de positie van de pop-up in pixels in. Het punt waaruit de verschuivingen worden gemeten, is afhankelijk van of de pop-up een bovenliggend item heeft:

• Een pop-up in de visualstructuur wordt verschoven van zijn eigen positie in de indeling van het bovenliggende element. In een verticale StackPanel bevindt die positie zich bijvoorbeeld onder de elementen die vóór de pop-up komen. In het eerste voorbeeld deelt de pop-up een enkele cel Grid met de knop, zodat deze 200 pixels rechts van de linkerbovenhoek van de Gridknop wordt weergegeven.
• Een pop-up met geen bovenliggend item, zoals een pop-up die u in code maakt, wordt verschoven vanaf de linkerbovenhoek van de XAML-root. Dit is meestal het inhoudsgebied van uw app-venster.

Een pop-up naast een element plaatsen

Als u een pop-up naast een specifiek element wilt weergeven, stelt u PlacementTarget in op dat element. Stel vervolgens DesiredPlacement in op een PopupPlacementMode-waarde anders dan Auto, zoals Bottom of RightEdgeAlignedTop.

Wanneer de pop-up wordt geopend, plaatst het framework deze ten opzichte van het doelelement. Als de pop-up niet in de voorkeurspositie past, wordt de pop-up verplaatst naar de tegenovergestelde kant van het doel. HorizontalOffset en VerticalOffset zijn nog steeds van toepassing en verschuiven de pop-up ten opzichte van de berekende positie.

ActualPlacement meldt waar de pop-up wordt weergegeven. De gebeurtenis ActualPlacementChanged treedt op wanneer die waarde verandert terwijl de pop-up is geopend.

<StackPanel Spacing="8">
    <Button x:Name="DetailsButton" Content="Show details" Click="ShowDetailsClicked" />
    <TextBlock x:Name="PlacementStatus" />
    <Popup x:Name="DetailsPopup"
           PlacementTarget="{x:Bind DetailsButton}"
           DesiredPlacement="BottomEdgeAlignedLeft"
           IsLightDismissEnabled="True"
           ActualPlacementChanged="DetailsPopup_ActualPlacementChanged">
        <Border Padding="16"
                Background="{ThemeResource AcrylicBackgroundFillColorDefaultBrush}"
                BorderBrush="{ThemeResource SurfaceStrokeColorDefaultBrush}"
                BorderThickness="1"
                CornerRadius="{StaticResource OverlayCornerRadius}">
            <TextBlock Text="This popup appears below the button when there's room." />
        </Border>
    </Popup>
</StackPanel>

private void ShowDetailsClicked(object sender, RoutedEventArgs e)
{
    DetailsPopup.IsOpen = true;
}

private void DetailsPopup_ActualPlacementChanged(object sender, object e)
{
    // ActualPlacement differs from DesiredPlacement when the popup
    // doesn't fit in the preferred position.
    PlacementStatus.Text = $"Actual placement: {DetailsPopup.ActualPlacement}";
}

Een pop-up weergeven buiten het app-venster

Standaard is een pop-up beperkt tot de grenzen van de XAML-root. Dit is meestal het inhoudsgebied van uw app-venster. Vanaf Windows App SDK 1.4 kunt u ShouldConstrainToRootBounds instellen op false om de pop-up buiten het venster te laten uitstrekken. U kunt dit bijvoorbeeld doen wanneer de pop-up groter is dan een klein venster.

Stel ShouldConstrainToRootBounds in voordat u de pop-up voor de eerste keer opent. U kunt deze niet wijzigen nadat de pop-up is geopend.

<Popup x:Name="UnconstrainedPopup" ShouldConstrainToRootBounds="False">
    <!-- Popup content -->
</Popup>

Een pop-up animeren

Als u de pop-upinhoud wilt animeren wanneer deze wordt weergegeven, voegt u een overgang toe aan de verzameling ChildTransitions . PopupThemeTransition biedt de animatie voor pop-in-UI, zoals tooltipachtige inhoud, zoals deze wordt weergegeven.

<Popup x:Name="AnimatedPopup" IsLightDismissEnabled="True">
    <Popup.ChildTransitions>
        <TransitionCollection>
            <PopupThemeTransition />
        </TransitionCollection>
    </Popup.ChildTransitions>
    <Border Padding="16"
            Background="{ThemeResource AcrylicBackgroundFillColorDefaultBrush}"
            BorderBrush="{ThemeResource SurfaceStrokeColorDefaultBrush}"
            BorderThickness="1"
            CornerRadius="{StaticResource OverlayCornerRadius}">
        <TextBlock Text="This content animates when the popup opens." />
    </Border>
</Popup>

Als u in plaats daarvan de animaties voor weergeven en verbergen vanuit een storyboard wilt beheren, gebruikt u PopInThemeAnimation en PopOutThemeAnimation. Zie Pop-up weergeven/verbergen voor meer informatie.

Reageren wanneer een pop-up wordt geopend of gesloten

De gebeurtenis Geopend treedt op wanneer IsOpen is ingesteld op true. De gebeurtenis Gesloten treedt op wanneer IsOpen is ingesteld op false, inclusief wanneer de pop-up wordt gesloten door elders te klikken of tikken. Gebruik Closed voor werk dat moet gebeuren, ongeacht hoe de pop-up wordt gesloten. Het voorbeeld van de WinUI 3-galerie gebruikt Closed bijvoorbeeld om een instelling die het uitschakelt terwijl het pop-upvenster is geopend, opnieuw in te schakelen.

Beide gebeurtenissen gebruiken EventHandler<object>, dus uw afhandelaren hebben een object afzender en een object gebeurtenisargument als parameter.

<StackPanel Spacing="8">
    <TextBlock x:Name="StatusText" />
    <Popup x:Name="StatusPopup"
           IsLightDismissEnabled="True"
           Opened="StatusPopup_Opened"
           Closed="StatusPopup_Closed">
        <!-- Popup content -->
    </Popup>
</StackPanel>

private void StatusPopup_Opened(object sender, object e)
{
    StatusText.Text = "The popup is open.";
}

private void StatusPopup_Closed(object sender, object e)
{
    // Closed occurs for every close, including light dismiss.
    StatusText.Text = "The popup is closed.";
}

Toetsenbord, focus en toegankelijkheid

• Wanneer light dismiss is ingeschakeld, verplaatst het openen van de pop-up de focus naar de pop-up en bij het sluiten van de pop-up wordt de focus teruggezet naar het element dat eerder de focus had. De gebruiker kan ook op Esc drukken om het pop-upvenster te sluiten.
• Wanneer light dismiss niet is ingeschakeld, verplaatst de pop-up de focus niet wanneer deze wordt geopend. Verplaats de focus naar een element in de pop-up nadat u het hebt geopend, voeg een knop Sluiten toe die toetsenbordgebruikers kunnen bereiken en breng de focus terug naar het element dat de pop-up heeft geopend nadat deze is gesloten.
• Een pop-up genereert geen gerouteerde gebeurtenissen, zoals KeyDown en PointerPressed. Als u deze gebeurtenissen wilt afhandelen, koppelt u de handlers in plaats daarvan aan het kindelement van de pop-up.
• Zorg ervoor dat elk interactief element in de pop-up een toegankelijke naam heeft. Zie Toetsenbordtoegankelijkheid en Basisinformatie over toegankelijkheid beschikbaar maken voor meer informatie.

Gerelateerde artikelen

• Dialoogvensters en uitschuifmenu's
• Flyouts
• dialoogbesturingselementen
• Lestip
• Tooltip
• Schaduwen in Windows-apps
• Pop-upklasse