Açılır pencere denetimi - Windows apps

Açılır pencere, uygulamanızdaki diğer kullanıcı arabiriminin üzerinde içerik görüntüler. ad alanındaki Microsoft.UI.Xaml.Controls.Primitives sınıfı, bu içerik için genel amaçlı bir kapsayıcıdır. Varsayılan görsel şablonu olmadığından içeriği, görünümünü ve onu açıp kapatan mantığı sağlarsınız.

Popup düşük düzeyli bir yapı taşıdır. WinUI ayrıca açılır pencereler, iletişim kutuları, öğretici ipuçları ve araç ipuçları gibi yaygın geçici kullanıcı arabirimi türleri için denetimler sağlar. Bu denetimler kendi stil, yerleştirme ve kapatma davranışlarını içerir.

Doğru kontrol bu mu?

Senaryonuza Popup daha üst düzey bir denetim uygunsa kullanmayın. Bunun yerine şu denetimleri kullanın:

Scenario	Denetim
Kullanıcı dışına tıkladığında kapanan kullanıcı arabiriminde bir öğeyle ilgili bilgileri gösterin veya giriş toplayın.	Açılır Pencere
Komutların veya seçeneklerin listesini gösterin.	MenuFlyout
Bir soru sorun veya kullanıcının devam etmeden önce yanıtlaması gereken bilgi gösterin.	ContentDialog
Belirli bir öğeyi hedefleyerek veya hedeflemeden yeni veya önemli bir özelliği işaret edin.	Öğretim İpucu
Kullanıcı öğenin üzerine geldiğinde veya odağı üzerine getirdiğinde öğenin kısa bir açıklamasını gösterin.	Araç ipucu

Kullanıcı arabiriminizin üzerinde kayan özel içeriğe ihtiyacınız olduğunda ve bu denetimlerin hiçbiri gereksinimlerinizi karşılamıyorsa Popup kullanın. Örneğin, kendiniz stil verip konumlandırdığınız bir kaplama için bir açılır pencere kullanabilirsiniz.

Açılan pencere modal olmadığından, kullanıcı arkasındaki kullanıcı arabirimiyle etkileşime devam edebilir. Kullanıcının devam etmeden önce yanıt vermesi gerekiyorsa bir ContentDialog kullanın.

Recommendations

Açılan içeriğe arka plan, kenarlık ve yuvarlatılmış köşeler verin; böylece arkasındaki kullanıcı arabiriminden öne çıkar. WinUI 3 Galerisi örneği, SurfaceStrokeColorDefaultBrush, OverlayCornerRadius ve AcrylicBackgroundFillColorDefaultBrush kaynaklarını kullanır. Daha fazla bilgi için bkz. Akrilik malzeme ve ThemeShadow in Popups.
light dismiss'i etkinleştirmezseniz, açılır pencereyi kapatan bir düğme veya başka bir denetim ekleyin.
Açılır pencere içeriğinin kısa ve tek bir göreve odaklanmış durumda kalmasını sağlayın.

Önemli API'ler: Popup sınıfı, IsOpen özelliği, Child özelliği

WinUI 3 Galeri uygulamasını açın ve Popup'ın nasıl çalıştığını görün

WinUI 3 Galeri uygulaması, WinUI denetimlerinin ve özelliklerinin etkileşimli örneklerini içerir. uygulamayı Microsoft Store adresinden alın veya GitHub üzerindeki kaynak koduna göz atın.

Açılan pencere, Child öğesi olarak ayarladığınız tek bir öğeyi barındırır. Alt öğe genellikle bir panel veya açılan içeriği tanımlayan bir UserControl olur. Açılan menüyü göstermek için IsOpen değerini true olarak ayarlayın. Gizlemek için false öğesini IsOpen olarak ayarlayın.

Bu örnek, WinUI 3 Galerisi örneğini temel alır. Onu açan düğmenin yanında bir açılır pencere tanımlar ve açılır pencere içeriğinde açılır pencereyi kapatan bir düğme bulunur.

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

Kodda, görsel ağaç yapısına eklemeden de bir açılır pencere oluşturabilirsiniz. XAML'de bildirdiğiniz veya görsel ağaçtaki bir panele eklediğiniz bir açılır pencere, XamlRoot'unu üst öğesinden alır. Üst öğesi olmayan bir açılır pencere çalışmaz, bu nedenle açmadan önce XamlRoot özelliğini ayarlamanız gerekir.

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

WinUI 3'te, ne üst öğesi ne de XamlRoot olan bir açılır pencerenin açılması başarısız olur. Bir öğenin XamlRoot değeri, öğe canlı görsel ağacına eklenene kadar null olur; bu nedenle değeri bir sayfa oluşturucusunda değil, zaten yüklenmiş bir öğeden alın. Bir Window sınıfta this.Content.XamlRoot kullanabilirsiniz. Daha fazla bilgi için bkz. ContentDialog ve Popup.

Note

Görsel ağaçta olmayan bir açılır pencere, dokunmatik klavye göründüğünde kendisini yeniden konumlandırmaz, böylece klavye onu kaplayabilir. Açılan pencere, TextBox gibi metin girişi denetimleri içeriyorsa, açılır pencereyi XAML'de tanımlayın veya görsel ağaçtaki bir panele ekleyin.

Varsayılan olarak, kodunuz IsOpen öğesini false olarak ayarlayana kadar açılır pencere açık kalır. Kullanıcı açılan pencerenin dışına tıkladığında veya dokunduğunda ya da Esc tuşuna bastığında açılan pencereyi kapatmak için IsLightDismissEnabled öğesini true olarak ayarlayın. Bu davranışa light dismiss denir.

Varsayılan olarak, dışarı tıklayınca kapanan açılır pencerenin dışındaki alan kararmaz. Koyulaştırmak için LightDismissOverlayMode değerini On olarak ayarlayın. IsLightDismissEnabled, false olduğunda bu özelliğin etkisi yoktur.

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

Ofsetleri kullanarak veya başka bir öğeye göre bir açılır pencere konumlandırabilirsiniz.

Ofsetleri kullan

HorizontalOffset ve VerticalOffset , açılan pencere konumunu piksel cinsinden ayarlar. Uzaklıkların ölçüldiği nokta, açılan pencerede üst öğe bulunup bulunmadığına bağlıdır:

Görsel ağaçtaki bir açılır pencere, üst öğesinin düzeninde kendi konumuna göre kaydırılmıştır. Örneğin, dikey bir StackPanel içinde, bu konum açılır pencereden önce gelen öğelerin altındadır. İlk örnekte, açılan pencere düğmeyle aynı tek hücreli Grid öğesini paylaşır, bu nedenle Grid öğesinin sol üst köşesinin 200 piksel sağında görünür.
Kodda oluşturduğunuz gibi üst öğesi olmayan bir açılır pencere, genellikle uygulama pencerenizin içerik alanı olan XAML kökünün sol üst köşesine göre kaydırılır.

Belirli bir öğenin yanında bir açılan pencere göstermek için PlacementTarget özelliğini bu öğeye ayarlayın. Ardından DesiredPlacement değerini, Bottom dışında bir RightEdgeAlignedTop değerine, örneğin Auto veya olarak ayarlayın.

Açılır pencere açıldığında, çerçeve bunu hedef öğeye göre konumlandırmış olur. Açılan pencere tercih edilen konuma sığmazsa çerçeve bunu hedefin karşı tarafına taşır. HorizontalOffset ve VerticalOffset hâlâ geçerlidir ve açılan menüyü hesaplanan konumdan kaydırın.

ActualPlacement açılır pencerenin gösterildiği yeri rapor eder. Açılan pencere açıkken bu değer değiştiğinde ActualPlacementChanged olayı gerçekleşir.

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

Varsayılan olarak, bir açılır pencere genellikle uygulama pencerenizin içerik alanı olan XAML kökünün sınırlarıyla kısıtlanır. Windows Uygulama SDK'sı 1.4'ten başlayarak, açılan pencerenin pencerenin ötesine genişlemesine izin vermek için false öğesini olarak ayarlayabilirsiniz. Örneğin, açılan pencere küçük bir pencereden büyük olduğunda bunu yapabilirsiniz.

Açılır pencereyi ilk kez açmadan önce ShouldConstrainToRootBounds ayarlayın. Açılır pencere açıldıktan sonra bunu değiştiremezsiniz.

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

Açılır pencere içeriği göründüğünde onu canlandırmak için ChildTransitions koleksiyonuna bir geçiş ekleyin. PopupThemeTransition, araç ipucu benzeri içerik gibi açılır kullanıcı arabirimi göründüğünde animasyon sağlar.

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

Bunun yerine, gösterme ve gizleme animasyonlarını görsel taslaktan denetlemek için PopOutThemeAnimation ve PopInThemeAnimation kullanın. Daha fazla bilgi için bkz. Açılır pencereyi göster/gizle.

true IsOpen olarak ayarlandığında Opened olayı gerçekleşir. Kapalı olayı, falseIsOpen olarak ayarlandığında, açılan pencerenin hafif kapatma yoluyla kapatılması da dahil olmak üzere gerçekleşir. Açılan pencere kapatılsa da gerçekleşmesi gereken işler için kullanın Closed . Örneğin, WinUI 3 Galerisi örneği, açılır pencere açıkken devre dışı bıraktığı bir ayarı yeniden etkinleştirmek için Closed kullanır.

Her iki olay da EventHandler<object> kullanır, bu nedenle işleyicileriniz bir object gönderen ve bir object olay argümanı alır.

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

Klavye, odak ve erişilebilirlik

Light dismiss etkinleştirildiğinde, açılan pencere açıldığında odak bunun içine taşınır ve açılan pencere kapatıldığında odak daha önce odakta olan öğeye döndürülür. Kullanıcı, açılır pencereyi kapatmak için Esc tuşuna da basabilir.
Light dismiss etkinleştirilmediğinde açılır pencere açıldığında odağı taşımaz. Siz açtıktan sonra odağı açılır penceredeki bir öğeye taşıyın, klavye kullanıcılarının ulaşabileceği bir Kapat düğmesi ekleyin ve kapatıldıktan sonra odağı, açılır pencereyi açan öğeye geri döndürün.
Açılan pencere, PointerPressed ve KeyDown gibi yönlendirilmiş olayları oluşturmaz. Bu olayları işlemek için, işleyicileri bunun yerine popup'ın çocuk öğesine ekleyin.
Açılan penceredeki her etkileşimli öğenin erişilebilir bir ada sahip olduğundan emin olun. Daha fazla bilgi için bkz. Klavye erişilebilirliği ve Temel erişilebilirlik bilgilerini kullanıma sunma.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-10-16

Popup

Doğru kontrol bu mu?

Recommendations

Açılır pencere oluştur

Kodda bir açılır pencere oluşturun

Dışarı tıklayarak açılır pencereyi kapatma

Açılır pencereyi konumlandırın

Ofsetleri kullan

Bir öğenin yanına açılır pencere yerleştirin

Uygulama penceresinin dışında bir açılan pencere göster

Bir açılır pencereyi canlandırın

Açılır pencere açıldığında veya kapandığında yanıt verme

Klavye, odak ve erişilebilirlik

İlgili makaleler

Geri Bildirim

Ek kaynaklar