Diyalog kontrolleri

İletişim kutusu denetimleri, bağlamsal uygulama bilgileri sağlayan kalıcı kullanıcı arabirimi katmanlardır. Uygulama penceresiyle etkileşimleri açıkça kapatılana kadar engeller. Genellikle kullanıcıdan bir tür eylem isterler.

Doğru kontrol bu mu?

Kullanıcıları önemli bilgiler hakkında bilgilendirmek veya bir eylem tamamlanmadan önce onay ya da ek bilgi istemek için iletişim kutularını kullanın.

Bir iletişim kutusunun ne zaman kullanılacağı ve ne zaman bir açılır öğenin (benzer bir kontrol) kullanılacağıyla ilgili öneriler için bakın: İletişim kutuları ve açılır öğeler.

Genel yönergeler

• İletişim kutusu metninin ilk satırında sorunu veya kullanıcının amacını net bir şekilde tanımlayın.
• Diyalog kutusu başlığı ana yönergedir ve isteğe bağlıdır.
  • İnsanların iletişim kutusuyla ne yapmaları gerektiğini açıklamak için kısa bir başlık kullanın.
  • Basit bir mesaj, hata veya soru iletmek için iletişim kutusunu kullanıyorsanız, isteğe bağlı olarak başlığı atlayabilirsiniz. Bu temel bilgileri sunmak için içerik metnine güvenin.
  • Başlığın doğrudan düğme seçimleriyle ilgili olduğundan emin olun.
• Diyalog penceresi içeriği gereklidir ve açıklayıcı metni içermelidir.
  • Mesajı, hatayı veya engelleme sorusunu mümkün olduğunca basit bir şekilde sunun.
  • Bir iletişim kutusu başlığı kullanılıyorsa, daha fazla ayrıntı sağlamak veya terminolojiyi tanımlamak için içerik alanını kullanın. Başlığı biraz farklı ifadelerle tekrarlamayın.
• En az bir iletişim düğmesi görünmelidir.
  • Diyalog kutunuzda "Aldım!", "Kapat" veya "İptal" gibi güvenli, zararsız bir eyleme karşılık gelen en az bir düğme olduğundan emin olun. Bu düğmeyi eklemek için CloseButton API'sini kullanın.
  • Ana talimata veya içeriğe belirli yanıtları düğme metni olarak kullanın. Örneğin, "AppName uygulamasının konumunuza erişmesine izin vermek istiyor musunuz?", ardından "İzin Ver" ve "Engelle" düğmeleri. Belirli yanıtlar daha hızlı anlaşılabilir ve bu da verimli karar verme ile sonuçlanır.
  • Eylem düğmelerinin metninin kısa ve öz olduğundan emin olun. Kısa dizeler, kullanıcının hızlı ve güvenli bir şekilde seçim yapmasını sağlar.
  • Güvenli, tahribatsız eyleme ek olarak, isteğe bağlı olarak kullanıcıya ana talimatla ilgili bir veya iki işlem düğmesi sunabilirsiniz. Bu "uygula" eylem düğmeleri iletişim kutusunun ana işlevini onaylar. Bu "yap" eylemlerini eklemek için PrimaryButton ve SecondaryButton API'lerini kullanın.
  • "Yap" eylem düğmeleri en soldaki düğmeler olarak görünmelidir. Güvenli, yıkıcı olmayan eylem en sağdaki düğme olarak görünmelidir.
  • İsteğe bağlı olarak, üç düğmeden birini iletişim kutusunun varsayılan düğmesi olarak ayırt etmeyi seçebilirsiniz. Düğmelerden birini ayırt etmek için DefaultButton API'sini kullanın.
• Doğrulama hataları (örneğin, parola alanlarında) gibi sayfanın belirli bir yerine bağlamsal olan hatalar için iletişim kutularını kullanmayın, satır içi hataları göstermek için uygulamanın tuvalini kullanın.
• İletişim kutusu deneyiminizi oluşturmak için ContentDialog sınıfını kullanın. Kullanım dışı bırakılan MessageDialog API'sini kullanmayın.

Diyalog oluştur

• Önemli API'ler: ContentDialog sınıfı

WinUI 3 Gallery uygulamasını açın ve ContentDialog'u çalışırken 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.

İletişim kutusu oluşturmak için ContentDialog sınıfınıkullanırsınız. Kod veya işaretleme içinde bir iletişim kutusu oluşturabilirsiniz. XAML'de kullanıcı arabirimi öğelerini tanımlamak genellikle daha kolay olsa da, basit bir iletişim kutusu söz konusu olduğunda yalnızca kod kullanmak daha kolay olabilir. Bu örnek, kullanıcıya Wi-Fi bağlantısı olmadığını bildirmek için bir iletişim kutusu oluşturur ve ardından bunu görüntülemek için ShowAsync yöntemini kullanır.

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "OK"
    };

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

İçerik iletişim kutunuz daha karmaşıksa, XAML ile oluşturmak daha kolay olabilir. Bunu sayfanızın XAML dosyasında oluşturabilir veya ContentDialog'un kendi .xaml ve arka planda kod dosyasıyla bir alt sınıfını oluşturabilirsiniz. Her ikisinin de tam örnekleri için bkz. [ContentDialog] sınıf başvurusu.

yeni bir içerik iletişim kutusu dosyası oluşturmak için Visual Studio öğe şablonu yoktur, ancak Boş Sayfa şablonunu kullanabilir ve sonuçta elde edilen dosyaları değiştirerek bir iletişim kutusu oluşturabilirsiniz.

XAML ve arka planda kod içeren yeni bir içerik iletişim kutusu oluşturmak için

1. Solution Explorer bölmesinde proje adına sağ tıklayın ve > Yeni Öğe Ekle... öğesini seçin.
2. Yeni Öğe Ekle iletişim kutusunda, pencerenin sol tarafındaki şablon listesinde WinUI'yi seçin.
3. Boş Sayfa şablonunu seçin.
4. Dosyayı adlandırın. (Bu örnekte, dosya olarak adlandırılır XamlContentDialog).
5. Ekle'ye basın.

Yeni .xaml dosyasında, açılış ve kapanış Page etiketlerini Content Dialog ile değiştirin.

<!--
<Page
    x:Class="ContentDialog_WinUI3.XamlContentDialog"
    ...>

</Page>
-->

<ContentDialog
    x:Class="ContentDialog_WinUI3.XamlContentDialog"
    ...>

</ContentDialog>

.xaml.cs dosyasında sınıfınızı Page yerine ContentDialog'dan devralın.

// public sealed partial class XamlContentDialog : Page

public sealed partial class XamlContentDialog : ContentDialog

İletişim kutusunu göster

İletişim kutusunu göstermek için ShowAsync yöntemini çağırın.

XamlContentDialog xamlDialog = new XamlContentDialog()
{
    XamlRoot = this.XamlRoot
};
await xamlDialog.ShowAsync();

Uyarı

Bir kerede pencere başına yalnızca bir ContentDialog açılabilir. İki içerik iletişim kutusunu açmaya çalışmak bir hata oluşturur.

XamlRoot'unu ayarlama

Bir ContentDialog gösterdiğinizde, XamlRoot'u el ile XAML konağının köküne ayarlamanız gerekir. Bunu yapmak için, ContentDialog'un XamlRoot özelliğini, zaten XAML ağacındaki bir öğenin XamlRoot'u ile aynı olacak şekilde ayarlayın.

ContentDialog bir Sayfadan gösteriliyorsa, önceki örnekte gösterildiği gibi ContentDialog'un XamlRoot özelliğini Sayfanın XamlRoot değerine ayarlayabilirsiniz.

Window'un XamlRoot özelliği yoktur, bu nedenle iletişim kutusu bir Window'dan gösteriliyorsa, iletişim kutusunun XamlRoot özelliğini burada gösterildiği gibi Pencerenin kök içerik öğesininkine ayarlayın.

<Window
    ... >
    <Grid x:Name="rootPanel">
    
    </Grid>
</Window>

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        XamlRoot = rootPanel.XamlRoot,
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "Ok"
    };

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

İletişim kutusu düğmelerine yanıt ver

Kullanıcı bir iletişim kutusu düğmesine tıkladığında, ShowAsync yöntemi kullanıcının hangi düğmeyi tıkladığını size bildirmek için bir ContentDialogResult döndürür.

Bu örnekteki iletişim kutusu bir soru sorar ve kullanıcının yanıtını belirlemek için döndürülen ContentDialogResult öğesini kullanır.

private async void DisplayDeleteFileDialog()
{
    ContentDialog deleteFileDialog = new ContentDialog
    {
        Title = "Delete file permanently?",
        Content = "If you delete this file, you won't be able to recover it. Do you want to delete it?",
        PrimaryButtonText = "Delete",
        CloseButtonText = "Cancel"
    };

    ContentDialogResult result = await deleteFileDialog.ShowAsync();

    // Delete the file if the user clicked the primary button.
    /// Otherwise, do nothing.
    if (result == ContentDialogResult.Primary)
    {
        // Delete the file.
    }
    else
    {
        // The user clicked the CloseButton, pressed ESC, Gamepad B, or the system back button.
        // Do nothing.
    }
}

Güvenli bir eylem sağlayın

İletişim kutuları kullanıcı etkileşimini engellediğinden ve düğmeler kullanıcıların iletişim kutusunu kapatmak için birincil mekanizma olduğundan, iletişim kutunuzun "Kapat" veya "Anladım!" gibi en az bir "güvenli" ve geri dönüşlü düğme içerdiğinden emin olun. Tüm iletişim kutuları, iletişim kutusunu kapatmak için en az bir güvenli eylem düğmesi içermelidir. Bu, kullanıcının bir eylem gerçekleştirmeden iletişim kutusunu güvenle kapatabilmesini sağlar.

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "OK"
    };

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

İletişim kutuları bir engelleme sorusunu görüntülemek için kullanıldığında, iletişim kutunuz kullanıcıya soruyla ilgili eylem düğmeleri sunmalıdır. "Güvenli" ve tahribatsız düğmeye bir veya iki "yap" eylem düğmesi eşlik edebilir. Kullanıcıya birden fazla seçenek sunarken, düğmelerin önerilen soruyla ilgili "yap" ve güvenli/"yapma" eylemlerini net bir şekilde açıkladığından emin olun.

private async void DisplayLocationPromptDialog()
{
    ContentDialog locationPromptDialog = new ContentDialog
    {
        Title = "Allow AppName to access your location?",
        Content = "AppName uses this information to help you find places, connect with friends, and more.",
        CloseButtonText = "Block",
        PrimaryButtonText = "Allow"
    };

    ContentDialogResult result = await locationPromptDialog.ShowAsync();
}

Kullanıcıya iki "yap" eylemi ve bir "yapma" eylemi sunduğunuzda üç düğmeli iletişim kutusu kullanılır. İkincil eylem ile güvenli/kapatma eylemi arasında net ayrımlar yaparak üç düğmeli iletişim kutuları nadiren kullanılmalıdır.

private async void DisplaySubscribeDialog()
{
    ContentDialog subscribeDialog = new ContentDialog
    {
        Title = "Subscribe to App Service?",
        Content = "Listen, watch, and play in high definition for only $9.99/month. Free to try, cancel anytime.",
        CloseButtonText = "Not Now",
        PrimaryButtonText = "Subscribe",
        SecondaryButtonText = "Try it"
    };

    ContentDialogResult result = await subscribeDialog.ShowAsync();
}

Üç iletişim kutusu düğmesi

ContentDialog, bir iletişim deneyimi oluşturmak için kullanabileceğiniz üç farklı düğme türüne sahiptir.

• CloseButton - Gerekli - Kullanıcının iletişim kutusundan çıkmasını sağlayan güvenli, zararsız eylemi temsil eder. En sağdaki düğme olarak görünür.
• PrimaryButton - İsteğe Bağlı - İlk "yap" eylemini temsil eder. En soldaki düğme olarak görünür.
• SecondaryButton - İsteğe bağlı - İkinci "yap" eylemini temsil eden düğme. Orta düğme olarak görünür.

Yerleşik düğmelerin kullanılması, düğmeleri uygun şekilde konumlandıracak, klavye olaylarına doğru şekilde yanıt verdiklerinden emin olacak, ekran klavyesi açıkken bile komut alanının görünür kalmasını sağlayacak ve iletişim kutusunun diğer iletişim kutularıyla tutarlı görünmesini sağlayacaktır.

Kapat Butonu

Her iletişim kutusu, kullanıcının iletişim kutusundan güvenle çıkmasını sağlayan güvenli, geri dönüşlü bir eylem düğmesi içermelidir.

Bu düğmeyi oluşturmak için ContentDialog.CloseButton API'sini kullanın. Bu, fare, klavye, dokunma ve oyun kumandası dahil olmak üzere tüm girişler için doğru kullanıcı deneyimini oluşturmanıza olanak tanır. Bu deneyim şu durumlarda gerçekleşir:

• Kullanıcı Kapat düğmesine tıklar veya dokunur.
• Kullanıcı sistem geri düğmesine basar.
• Kullanıcı klavyedeki ESC düğmesine basar.
• Kullanıcı Gamepad B'ye basar.

Kullanıcı bir iletişim kutusu düğmesine tıkladığında, ShowAsync yöntemi kullanıcının hangi düğmeyi tıkladığını size bildirmek için bir ContentDialogResult döndürür. CloseButton düğmesine basıldığında ContentDialogResult.None döndürülür.

PrimaryButton ve SecondaryButton

CloseButton'a ek olarak, isteğe bağlı olarak kullanıcıya ana komutla ilgili bir veya iki eylem düğmesi sunabilirsiniz. İlk "yap" eylemi için PrimaryButton'ı ve ikinci "yap" eylemi için SecondaryButton'ı kullanın. Üç düğmeli iletişim kutularında, PrimaryButton genellikle olumlu "yap" eylemini temsil ederken, SecondaryButton genellikle nötr veya ikincil bir "yap" eylemini temsil eder. Örneğin, bir uygulama kullanıcıdan bir hizmete abone olmasını isteyebilir. BirincilDüğme onaylayıcı bir "yap" eylemi olarak Abone Ol metnini barındırırken, İkincilDüğme nötr bir "yap" eylemi olarak Denemek metnini barındırır. CloseButton, kullanıcının her iki eylemi de gerçekleştirmeden iptal etmesine olanak tanır.

Kullanıcı PrimaryButton düğmesine tıkladığında, ShowAsync yöntemi ContentDialogResult.Primary döndürür. Kullanıcı İkincilDüğmesini tıkladığında ShowAsync yöntemi ContentDialogResult.Secondary döndürür.

Varsayılan Düğme

İsteğe bağlı olarak, üç düğmeden birini varsayılan düğme olarak ayırt etmeyi seçebilirsiniz. Varsayılan düğmenin belirtilmesi aşağıdakilerin olmasına neden olur:

• Düğme, "Accent Button" görsel stilini alır
• Düğme ENTER tuşuna otomatik olarak yanıt verecektir
  • Kullanıcı klavyede ENTER tuşuna bastığında, Varsayılan Düğme ile ilişkili tıklama işleyicisi tetiklenir ve ContentDialogResult Varsayılan Düğme ile ilişkili değeri döndürür
  • Kullanıcı Klavye Odağı'nı ENTER işleyen bir denetime yerleştirdiyse, Varsayılan Düğme ENTER tuşlarına yanıt vermez
• İletişim kutusu içeriğinde odaklanabilir bir kullanıcı arabirimi bulunmadığı sürece, iletişim kutusu açıldığında düğme otomatik olarak odaklanır.

Varsayılan düğmeyi belirtmek için ContentDialog.DefaultButton özelliğini kullanın. Varsayılan olarak, varsayılan bir düğme ayarlanmamıştır.

olan bir iletişim kutusu

private async void DisplaySubscribeDialog()
{
    ContentDialog subscribeDialog = new ContentDialog
    {
        Title = "Subscribe to App Service?",
        Content = "Listen, watch, and play in high definition for only $9.99/month. Free to try, cancel anytime.",
        CloseButtonText = "Not Now",
        PrimaryButtonText = "Subscribe",
        SecondaryButtonText = "Try it",
        DefaultButton = ContentDialogButton.Primary
    };

    ContentDialogResult result = await subscribeDialog.ShowAsync();
}

Onay iletişim kutuları (Tamam/İptal)

Onay iletişim kutusu, kullanıcılara bir eylem gerçekleştirmek istediklerini onaylama şansı verir. İşlemi onaylayabilir veya iptal etmeyi seçebilirler. Tipik bir onay iletişim kutusunda iki düğme bulunur: bir onaylama ("Tamam") düğmesi ve bir iptal düğmesi.

• Genel olarak, onaylama düğmesi solda (birincil düğme) ve iptal düğmesi (ikincil düğme) sağda olmalıdır.

  
• Genel öneriler bölümünde belirtildiği gibi, ana talimata veya içeriğe verilen belirli yanıtları tanımlayan metin içeren düğmeler kullanın.

AppWindow veya Xaml Adaları'nda ContentDialog

NOT: Bu bölüm yalnızca Windows 10, sürüm 1903 veya sonraki sürümleri hedefleyen uygulamalar için geçerlidir. AppWindow ve XAML Adaları önceki sürümlerde kullanılamaz. Sürüm oluşturma hakkında daha fazla bilgi için Sürüm uyarlamalı uygulamalar bölümüne bakın.

Varsayılan olarak, içerik diyalogları kök ApplicationView'e göre modsal olarak görüntülenir. ContentDialog'u bir AppWindow veya bir XAML Adasıiçinde kullandığınızda, iletişim kutusundaki XamlRoot'u XAML konağı köküne manuel olarak ayarlamanız gerekir.

Bunu yapmak için, ContentDialog'un XamlRoot özelliğini, aşağıda gösterildiği gibi, AppWindow'da veya XAML Adası'nda bulunan bir öğeyle aynı XamlRoot olarak ayarlayın.

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "OK"
    };

    // Use this code to associate the dialog to the appropriate AppWindow by setting
    // the dialog's XamlRoot to the same XamlRoot as an element that is already present in the AppWindow.
    if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
    {
        noWifiDialog.XamlRoot = elementAlreadyInMyAppWindow.XamlRoot;
    }

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

Uyarı

Bir kerede iş parçacığı başına yalnızca bir ContentDialog açık olabilir. İki ContentDialog'un açılmaya çalışılması, AppWindow'un ayrı örneklerinde açmaya çalışsalar bile bir özel durum oluşturur.

İlgili makaleler

• İpucu
• Menüler ve bağlam menüsü
• Flyout sınıfı
• ContentDialog Sınıfı