Popup

Vyskakovací okno zobrazí obsah nad ostatními prvky uživatelského rozhraní ve vaší aplikaci. Třída Popup v Microsoft.UI.Xaml.Controls.Primitives oboru názvů je univerzální kontejner pro tento obsah. Nemá žádnou výchozí šablonu vizuálu, takže zadáte obsah, jeho vzhled a logiku pro jeho otevření a zavření.

Popup je základní prvek nízké úrovně. WinUI také poskytuje ovládací prvky pro běžné druhy přechodných uživatelských rozhraní, jako jsou informační rámečky, dialogy, tipy pro výuku a popisy ovládacích prvků. Tyto ovládací prvky zahrnují vlastní styly, umístění a chování při zavření.

Tlačítko s popiskem „Zobrazit popup (pomocí posunu)“ vedle otevřeného popupu obsahujícího text „Jednoduchý popup“ a tlačítko Zavřít.

Je to správná kontrola?

Nepoužívejte Popup, pokud vašemu scénáři vyhovuje ovládací prvek vyšší úrovně. Místo toho použijte tyto ovládací prvky:

Scenario Ovládací prvek
Umožňuje zobrazit informace nebo získat vstup od uživatele související s položkou v uživatelském rozhraní, které se zavře, když uživatel klikne mimo ni. Vyskakovací nabídka
Zobrazí seznam příkazů nebo možností. MenuFlyout
Položte otázku nebo zobrazte informace, na které musí uživatel odpovědět, než bude pokračovat. ContentDialog
Upozorněte na novou nebo důležitou funkcionalitu, s cílením na konkrétní prvek nebo bez něj. Výuková rada
Zobrazí krátký popis prvku, když na něj uživatel najede myší nebo přesune fokus na něj. Nástroj tip

Použijte Popup, když potřebujete vlastní obsah, který je nad uživatelským rozhraním, a žádný z těchto ovládacích prvků nevyhovuje vašim potřebám. Můžete například použít vyskakovací okno pro překryvné okno, které si stylujete a umístíte sami.

Vyskakovací okno není modální, takže uživatel může dál pracovat s uživatelským rozhraním za ním. Pokud uživatel musí odpovědět, než bude pokračovat, použijte ContentDialog.

Recommendations

  • Dejte obsahu vyskakovacího okna pozadí, ohraničení a zaoblené rohy, aby vynikl od uživatelského rozhraní za ním. Ukázka galerie WinUI 3 používá prostředky AcrylicBackgroundFillColorDefaultBrush, SurfaceStrokeColorDefaultBrush a OverlayCornerRadius. Další informace naleznete v tématu Akrylový materiál a ThemeShadow v Popups.
  • Pokud nepovolíte kliknutí mimo, přidejte tlačítko nebo jiný ovládací prvek, který zavře automaticky otevírané okno.
  • Udržujte obsah automaticky otevíraného okna stručný a zaměřený na jeden úkol.

Vytvořit vyskakovací okno

Otevřete aplikaci Galerie WinUI 3 a podívejte se, jak funguje automaticky otevírané okno

Ikona galerie WinUI 3 Aplikace Galerie WinUI 3 obsahuje interaktivní příklady ovládacích prvků a funkcí WinUI. Získejte aplikaci z Microsoft Store nebo vyhledejte zdrojový kód na GitHub.

Místní okno hostuje jeden prvek, který jste nastavili jako jeho Child. Podřízeným prvkem je obvykle panel nebo prvek UserControl, který definuje obsah místního okna. Pokud chcete zobrazit vyskakovací okno, nastavte IsOpen na true. Chcete-li jej skrýt, nastavte IsOpen na false.

Tento příklad je založený na ukázce galerie WinUI 3. Deklaruje vyskakovací okno vedle tlačítka, které jej otevírá, a obsah vyskakovacího okna obsahuje tlačítko, které vyskakovací okno zavře.

<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;
    }
}

Vytvoření vyskakovacího okna v kódu

Můžete také vytvořit automaticky otevírané okno v kódu, aniž byste ho přidali do vizuálního stromu. Místní okno, které deklarujete v XAML nebo přidáte na panel ve vizuálním stromu, získá XamlRoot z nadřazeného prvku. Automaticky otevírané okno, které nemá nadřazený objekt, ji nemá, takže před otevřením musíte nastavit jeho vlastnost XamlRoot.

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

Ve WinUI 3 selže otevření automaticky otevíraného okna, které nemá nadřazený prvek ani XamlRoot. Prvek XamlRoot je null, dokud se nepřidá do živého vizuálního stromu, takže hodnotu získejte z prvku, který je už načtený, spíše než v konstruktoru stránky. V Window třídě můžete použít this.Content.XamlRoot. Další informace najdete v tématu ContentDialog, a Popup.

Note

Automaticky otevírané okno, které není ve vizuálním stromu, se při zobrazení dotykové klávesnice nepřemístí, takže ho klávesnice může zakrýt. Pokud místní okno obsahuje ovládací prvky pro zadávání textu, jako je například TextBox, deklarujte místní okno v XAML nebo ho přidejte na panel ve vizuálním stromu.

Zavření místního okna kliknutím mimo něj

Ve výchozím nastavení zůstane vyskakovací okno otevřené, dokud váš kód nenastaví IsOpen na false. Nastavte IsLightDismissEnabled na true, aby se automaticky otevírané okno zavřelo, když uživatel klikne nebo klepne mimo něj, nebo stiskne klávesu Esc. Toto chování se nazývá zavření kliknutím mimo.

Ve výchozím nastavení oblast mimo místní oznámení, které se zavře kliknutím mimo něj, neztmavne. Pokud ji chcete ztmavit, nastavte LightDismissOverlayMode na On. Tato vlastnost nemá žádný vliv, pokud IsLightDismissEnabled je 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>

Umístěte vyskakovací okno

Vyskakovací okno můžete umístit pomocí posunů nebo vzhledem k jinému prvku.

Použít posuny

HorizontalOffset a VerticalOffset nastaví pozici automaticky otevíraného okna v pixelech. Bod, ze kterého se odsazení měří, závisí na tom, jestli má automaticky otevírané okno nadřazenou položku:

  • Místní okno ve vizuálním stromu je posunuté od vlastní pozice v rozložení nadřazeného objektu. Například ve svislém umístění StackPanelje tato pozice pod prvky, které přicházejí před automaticky otevírané okno. V prvním příkladu vyskakovací okno sdílí s tlačítkem jednu buňku Grid, takže se zobrazí 200 pixelů vpravo od levého horního rohu Grid.
  • Automaticky otevírané okno, které nemá nadřazený objekt, například objekt, který vytvoříte v kódu, je posunuté od levého horního rohu kořene XAML, což je obvykle oblast obsahu okna aplikace.

Umístěte vyskakovací okno vedle elementu

Chcete-li zobrazit překryvné okno vedle konkrétního prvku, nastavte PlacementTarget na tento element. Potom nastavte DesiredPlacement na jinou hodnotu PopupPlacementMode než Auto, například Bottom nebo RightEdgeAlignedTop.

Když se vyskakovací okno otevře, framework ho umístí vzhledem k cílovému prvku. Pokud se vyskakovací okno nevejde do upřednostňované pozice, framework jej přesune na opačnou stranu cílového prvku. HorizontalOffset a VerticalOffset stále platí a posunou automaticky otevírané okno z vypočítané pozice.

ActualPlacement udává, kde se automaticky otevírané okno zobrazuje. Událost ActualPlacementChanged nastane, když se tato hodnota změní, když je otevřené místní okno.

<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}";
}

Zobrazit vyskakovací okno mimo okno aplikace

Ve výchozím nastavení je místní okno omezené na hranice kořene XAML, což je obvykle oblast obsahu okna aplikace. Počínaje Windows App SDK 1.4 můžete nastavit ShouldConstrainToRootBounds na false, aby se místní nabídka mohla rozšířit mimo okno. Můžete to udělat například v případě, že je vyskakovací okno větší než malé okno.

Nastavte ShouldConstrainToRootBounds před prvním otevřením vyskakovacího okna. Po otevření vyskakovacího okna ho nemůžete změnit.

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

Animovat vyskakovací okno

Pokud chcete animovat obsah místního okna při jeho zobrazení, přidejte přechod do kolekce ChildTransitions. PopupThemeTransition poskytuje animaci pro vyskakovací uživatelské rozhraní, jako je například obsah podobný popisku, jak se zobrazí.

<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>

Chcete-li místo toho ovládat zobrazení a skrytí animací z scénáře, použijte PopInThemeAnimation a PopOutThemeAnimation. Další informace najdete v tématu Zobrazit/skrýt automaticky otevírané okno.

Reagovat při otevření nebo zavření vyskakovacích oken

Událost Opened nastane, když je IsOpen nastavena na true. Událost Closed nastane, když je IsOpen nastaveno na false, včetně případů, kdy se místní okno zavře kliknutím mimo něj. Použijte Closed pro práci, která se musí provést bez ohledu na to, jak se automaticky otevírané okno zavře. Například ukázka galerie WinUI 3 používá Closed k opětovnému povolení nastavení, které zakáže, když je vyskakovací okno otevřené.

Obě události používají EventHandler<object>, takže vaše obslužné rutiny přijímají object odesílatele a object argument události.

<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.";
}

Klávesnice, zaměření a přístupnost

  • Když je zapnuté zavření kliknutím mimo, otevření místního okna přesune fokus do něj a zavření místního okna vrátí fokus na prvek, který měl fokus předtím. Uživatel může také stisknutím klávesy Esc zavřít automaticky otevírané okno.
  • Pokud není zapnutý light dismiss, automaticky otevírané okno nepřesune fokus při otevření. Přesuňte fokus na prvek v automaticky otevíraném okně po jeho otevření, přidejte tlačítko Zavřít, ke kterému se uživatelé klávesnice dostanou, a vraťte fokus na prvek, který automaticky otevírané okno otevřel, poté co se zavře.
  • Automaticky otevírané okno nevyvolá směrované události, například KeyDown a PointerPressed. Pokud chcete tyto události zpracovat, připojte obslužné rutiny místo toho k podřízenému prvku vyskakovacího okna.
  • Ujistěte se, že každý interaktivní prvek ve vyskakovacím okně má přístupný název. Další informace najdete v tématu Přístupnost pomocí klávesnice a Zpřístupnění základních informací o přístupnosti.
  • Poslední aktualizace v