Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
In einem Popup werden Inhalte über der anderen Benutzeroberfläche in Ihrer App angezeigt. Die Popup-Klasse im Microsoft.UI.Xaml.Controls.Primitives Namespace ist ein allgemeiner Container für diesen Inhalt. Es verfügt nicht über eine standardmäßige visuelle Vorlage, sodass Sie den Inhalt, dessen Darstellung und die Logik bereitstellen, die sie öffnet und schließt.
Popup ist ein Baustein auf niedriger Ebene. WinUI bietet auch Steuerelemente für gängige Arten von vorübergehender Benutzeroberfläche, z. B. Flyouts, Dialogfelder, Lehrtipps und QuickInfos. Diese Steuerelemente umfassen ihr eigenes Formatierungs-, Platzierungs- und Ausblendverhalten.
Ist dies das richtige Steuerelement?
Verwenden Sie kein Popup, wenn ein Steuerelement auf höherer Ebene zu Ihrem Szenario passt. Verwenden Sie stattdessen die folgenden Steuerelemente:
| Scenario | Steuerung |
|---|---|
| Zeigen Sie Informationen an, oder erfassen Sie Eingaben im Zusammenhang mit einem Element in einer Benutzeroberfläche, die geschlossen wird, wenn der Benutzer außerhalb klickt. | Flyout |
| Anzeigen einer Liste von Befehlen oder Optionen. | MenuFlyout |
| Stellen Sie eine Frage, oder zeigen Sie Informationen an, auf die der Benutzer antworten muss, bevor er fortfahren kann. | ContentDialog |
| Verweisen Sie auf ein neues oder wichtiges Feature mit oder ohne Ausrichtung auf ein bestimmtes Element. | Lehrinfo |
| Zeigen Sie eine kurze Beschreibung eines Elements an, wenn der Benutzer mit dem Mauszeiger darüber fährt oder den Fokus darauf verschiebt. | ToolTip |
Verwenden Sie ein Popup, wenn Sie benutzerdefinierten Inhalt benötigen, der über Ihrer Benutzeroberfläche schwebt, und keines dieser Steuerelemente Ihren Anforderungen entspricht. Sie können beispielsweise ein Popup für eine Überlagerung verwenden, die Sie gestalten und selbst positionieren.
Ein Popup ist nicht modal, sodass der Benutzer weiterhin mit der Benutzeroberfläche dahinter interagieren kann. Wenn der Benutzer reagieren muss, bevor er fortfahren kann, verwenden Sie einen ContentDialog.
Recommendations
- Verleihen Sie dem Popupinhalt einen Hintergrund, einen Rahmen und abgerundete Ecken, sodass er von der Benutzeroberfläche dahinter hervorsticht. Das WinUI 3 Gallery-Beispiel verwendet die
AcrylicBackgroundFillColorDefaultBrush,SurfaceStrokeColorDefaultBrushundOverlayCornerRadiusRessourcen. Weitere Informationen finden Sie unter Acrylmaterial und ThemeShadow in Popups. - Wenn Sie das Schließen durch Klicken außerhalb nicht aktivieren, fügen Sie eine Schaltfläche oder ein anderes Steuerelement hinzu, das das Popup schließt.
- Halten Sie Popupinhalte kurz, und konzentrieren Sie sich auf eine einzelne Aufgabe.
Popup erstellen
- Wichtige APIs: Popupklasse, IsOpen-Eigenschaft, Child-Eigenschaft
Die WinUI 3 Gallery-App enthält interaktive Beispiele für WinUI-Steuerelemente und -Features. Rufen Sie die App aus dem Microsoft Store ab, oder durchsuchen Sie den Quellcode auf GitHub.
Ein Popup hostet ein einzelnes Element, das Sie als Child-Element festlegen. Das untergeordnete Element ist in der Regel ein Panel oder ein UserControl, das den Popupinhalt definiert. Um das Popup anzuzeigen, legen Sie IsOpen auf true. Um es auszublenden, setzen Sie IsOpen auf false.
Dieses Beispiel basiert auf dem WinUI 3 Gallery-Beispiel. Es deklariert ein Popup neben der Schaltfläche, die sie öffnet, und der Popupinhalt enthält eine Schaltfläche, mit der das Popup geschlossen wird.
<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;
}
}
Erstellen Sie ein Pop-up im Code
Sie können auch ein Popup im Code erstellen, ohne es der visuellen Struktur hinzuzufügen. Ein Popup, das Sie in XAML deklarieren oder einem Panel im visuellen Strukturbaum hinzufügen, erhält sein XamlRoot vom übergeordneten Element. Ein Popup ohne übergeordnetes Element verfügt nicht darüber, daher müssen Sie seine Eigenschaft XamlRoot festlegen, bevor Sie es öffnen.
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;
}
Important
In WinUI 3 schlägt das Öffnen eines Popups fehl, das weder ein übergeordnetes Element noch ein XamlRoot aufweist. Die XamlRoot eines Elements ist null, bis das Element der aktiven visuellen Struktur hinzugefügt wird. Rufen Sie den Wert daher von einem Element ab, das bereits geladen ist, und nicht in einem Seitenkonstruktor. In einem Window Kurs können Sie this.Content.XamlRoot verwenden. Weitere Informationen finden Sie unter ContentDialog, und Popup.
Note
Ein Popup, das sich nicht in der visuellen Struktur befindet, wird nicht neu positioniert, wenn die Bildschirmtastatur angezeigt wird, sodass die Tastatur sie abdecken kann. Wenn das Popup Texteingabesteuerelemente enthält, z. B. ein TextBox, deklarieren Sie das Popup in XAML, oder fügen Sie es einem Panel in der visuellen Struktur hinzu.
Schließen eines Popups durch einfaches Ausblenden
Standardmäßig bleibt ein Popup geöffnet, bis Ihr Code IsOpen auf false setzt. Legen Sie IsLightDismissEnabled auf true fest, um das Popup zu schließen, wenn der Benutzer außerhalb des Popups klickt oder darauf tippt oder die ESC-TASTE drückt. Dieses Verhalten wird als Light dismiss bezeichnet.
Standardmäßig wird der Bereich außerhalb eines Light-Dismiss-Popups nicht abgedunkelt. Um es abzudunkeln, legen Sie LightDismissOverlayMode auf On fest. Diese Eigenschaft hat keine Wirkung, wenn IsLightDismissEnabledfalse ist.
<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>
Popup positionieren
Sie können ein Popup mithilfe von Offsets oder relativ zu einem anderen Element positionieren.
Offsets verwenden
HorizontalOffset und VerticalOffset legen die Position des Popups in Pixel fest. Der Punkt, von dem die Offsets gemessen werden, hängt davon ab, ob das Popup über ein übergeordnetes Element verfügt:
- Ein Popup in der visuellen Struktur ist gegenüber seiner eigenen Position im Layout des übergeordneten Elements versetzt. In einem vertikalen
StackPanelbefindet sich diese Position beispielsweise unter den Elementen, die vor dem Popup stehen. Im ersten Beispiel teilt sich das Popup ein einzelligesGridmit der Schaltfläche, sodass es 200 Pixel rechts von der oberen linken Ecke desGridangezeigt wird. - Ein Popup, das kein übergeordnetes Element aufweist, z. B. ein Popup, das Sie im Code erstellen, ist gegenüber der oberen linken Ecke seines XAML-Root versetzt, was normalerweise der Inhaltsbereich des App-Fensters ist.
Platzieren Sie ein Popup neben einem Element
Um ein Popup neben einem bestimmten Element anzuzeigen, legen Sie PlacementTarget auf dieses Element fest. Legen Sie dann DesiredPlacement auf einen anderen PopupPlacementMode-Wert als Auto fest, z. B. Bottom oder RightEdgeAlignedTop.
Wenn das Popup geöffnet wird, positioniert das Framework es relativ zum Zielelement. Wenn das Popup nicht in die bevorzugte Position passt, verschiebt das Framework es auf die entgegengesetzte Seite des Ziels.
HorizontalOffset und VerticalOffset gelten weiterhin und verschieben das Popup aus der berechneten Position.
ActualPlacement gibt an, wo das Popup angezeigt wird. Das ActualPlacementChanged-Ereignis tritt auf, wenn sich dieser Wert ändert, während das Popup geöffnet ist.
<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}";
}
Anzeigen eines Popups außerhalb des App-Fensters
Standardmäßig ist ein Popup auf die Grenzen des XAML-Roots beschränkt, was normalerweise der Inhaltsbereich des App-Fensters ist. Ab Windows App SDK 1.4 können Sie ShouldConstrainToRootBounds auf false festlegen, damit sich das Popup über das Fenster hinaus erstrecken kann. Beispielsweise können Sie dies tun, wenn das Popup größer als ein kleines Fenster ist.
Legen Sie ShouldConstrainToRootBounds fest, bevor Sie das Popup zum ersten Mal öffnen. Sie können sie nach dem Öffnen des Popups nicht mehr ändern.
<Popup x:Name="UnconstrainedPopup" ShouldConstrainToRootBounds="False">
<!-- Popup content -->
</Popup>
Popup animieren
Um den Popupinhalt beim Anzeigen zu animieren, fügen Sie der Auflistung ChildTransitions einen Übergang hinzu. PopupThemeTransition stellt die Animation für eingeblendete UI bereit, z. B. QuickInfo-ähnliche Inhalte, wenn sie angezeigt werden.
<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>
Um stattdessen die Ein- und Ausblendeanimationen aus einem Storyboard zu steuern, verwenden Sie PopInThemeAnimation und PopOutThemeAnimation. Weitere Informationen finden Sie unter Einblenden/Ausblenden des Popups.
Antworten, wenn ein Popup geöffnet oder geschlossen wird
Das Opened-Ereignis tritt auf, wenn IsOpen auf true gesetzt wird. Das Ereignis Closed tritt auf, wenn IsOpen auf false festgelegt ist, einschließlich der Fälle, in denen das Popup durch einfaches Ausblenden geschlossen wird. Verwenden Sie Closed für Aufgaben, die ausgeführt werden müssen, unabhängig davon, wie das Popup geschlossen wird. Beispielsweise verwendet das WinUI 3-Katalogbeispiel Closed, um eine Einstellung wieder zu aktivieren, die deaktiviert wird, während das Popup geöffnet ist.
Beide Ereignisse verwenden EventHandler<object>, sodass ihre Handler einen object Absender und ein object Ereignisargument akzeptieren.
<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.";
}
Tastatur, Fokus und Barrierefreiheit
- Wenn Light Dismiss aktiviert ist, verschiebt das Öffnen des Popups den Fokus darauf, und das Schließen des Popups gibt den Fokus auf das Element zurück, das zuvor den Fokus hatte. Der Benutzer kann auch ESC drücken, um das Popup zu schließen.
- Wenn Light Dismiss nicht aktiviert ist, wird der Fokus beim Öffnen des Popups nicht verschoben. Setzen Sie den Fokus auf ein Element im Popup, nachdem Sie es geöffnet haben, fügen Sie eine Schaltfläche „Schließen“ hinzu, die Tastaturbenutzer erreichen können, und setzen Sie den Fokus nach dem Schließen wieder auf das Element, das das Popup geöffnet hat.
- Ein Popup löst keine Routingereignisse aus, z. B.
KeyDownundPointerPressed. Um diese Ereignisse zu behandeln, fügen Sie stattdessen die Handler an das untergeordnete Element des Popups an. - Stellen Sie sicher, dass jedes interaktive Element im Popup über einen barrierefreien Namen verfügt. Weitere Informationen finden Sie unter Barrierefreiheit der Tastatur und Verfügbarmachen grundlegender Informationen zur Barrierefreiheit.
Verwandte Artikel
Zusammenarbeit auf GitHub
Die Quelle für diesen Inhalt finden Sie auf GitHub, wo Sie auch Issues und Pull Requests erstellen und überprüfen können. Weitere Informationen finden Sie in unserem Leitfaden für Mitwirkende.
Windows developer