Kontrolki okien dialogowych

Kontrolki okien dialogowych to modalne nakładki interfejsu użytkownika, które zapewniają kontekstowe informacje o aplikacji. Blokują interakcje z oknem aplikacji, dopóki nie zostaną jawnie odrzucone. Często żądają pewnego rodzaju akcji od użytkownika.

Czy jest to właściwa kontrola?

Użyj okien dialogowych, aby powiadomić użytkowników o ważnych informacjach lub zażądać potwierdzenia lub dodatkowych informacji przed ukończeniem akcji.

Aby uzyskać zalecenia dotyczące tego, kiedy używać okna dialogowego, a kiedy wysuwanego (podobnej kontrolki), zobacz Okna dialogowe i wysuwane.

Ogólne wskazówki

• Wyraźnie zidentyfikuj problem lub cel użytkownika w pierwszym wierszu tekstu okna dialogowego.
• Tytuł okna dialogowego to główna instrukcja i jest opcjonalna.
  • Użyj krótkiego tytułu, aby wyjaśnić, co ludzie muszą zrobić za pomocą okna dialogowego.
  • Jeśli używasz okna dialogowego do dostarczania prostego komunikatu, błędu lub pytania, możesz opcjonalnie pominąć tytuł. Polegaj na tekście zawartości, aby dostarczyć te podstawowe informacje.
  • Upewnij się, że tytuł jest powiązany bezpośrednio z opcjami przycisków.
• Zawartość okna dialogowego zawiera tekst opisowy i jest wymagana.
  • Przedstaw komunikat, błąd lub blokujące pytanie w jak najprostszy sposób.
  • Jeśli jest używany tytuł okna dialogowego, użyj obszaru zawartości, aby podać więcej szczegółów lub zdefiniować terminologię. Nie powtarzaj tytułu z nieco innym sformułowaniem.
• Musi zostać wyświetlony co najmniej jeden przycisk okna dialogowego.
  • Upewnij się, że okno dialogowe ma co najmniej jeden przycisk odpowiadający bezpiecznej akcji, takiej jak "Zrozumiano!", "Zamknij" lub "Anuluj". Użyj interfejsu API CloseButton, aby dodać ten przycisk.
  • Użyj określonych odpowiedzi na instrukcję główną lub treść jako tekst przycisku. Przykład: "Czy chcesz zezwolić usłudze AppName na dostęp do lokalizacji?", a następnie przyciski "Zezwalaj" i "Blokuj". Konkretne odpowiedzi można zrozumieć szybciej, co skutkuje skutecznym podejmowaniem decyzji.
  • Upewnij się, że tekst przycisków akcji jest zwięzły. Krótkie ciągi umożliwiają użytkownikowi szybkie i pewnie dokonanie wyboru.
  • Oprócz bezpiecznego, niedestrukcyjnego działania, jeżeli chcesz, możesz przedstawić użytkownikowi jeden lub dwa przyciski związane z instrukcją główną. Te przyciski akcji "zrób to" potwierdzają główny punkt okna dialogowego. Użyj interfejsów API PrimaryButton i SecondaryButton, aby dodać te akcje "zrób to".
  • Przyciski akcji "Zrób to" powinny być wyświetlane jako przyciski z lewej strony. Bezpieczna, niezniszczalna akcja powinna być wyświetlana jako najbardziej prawy przycisk.
  • Opcjonalnie możesz wybrać rozróżnienie jednego z trzech przycisków jako domyślnego przycisku okna dialogowego. Użyj interfejsu API DefaultButton, aby odróżnić jeden z przycisków.
• Nie używaj okien dialogowych dla błędów kontekstowych dla określonego miejsca na stronie, takich jak błędy walidacji (na przykład w polach haseł), użyj samej kanwy aplikacji, aby wyświetlić błędy wbudowane.
• Użyj klasy ContentDialog, aby stworzyć swoje doświadczenie dialogowe. Nie używaj przestarzałego interfejsu API MessageDialog.

Tworzenie okna dialogowego

• Ważne interfejsy API: Klasa ContentDialog

Otwórz aplikację Galeria WinUI 3 i zobacz działanie ContentDialog

Aplikacja Galeria WinUI 3 zawiera interaktywne przykłady większości kontrolek, funkcji i funkcji interfejsu WinUI 3. Pobierz aplikację ze Sklepu Microsoft lub pobierz kod źródłowy w witrynie GitHub

Aby utworzyć okno dialogowe, należy użyć klasy ContentDialog. Dialog można utworzyć w kodzie lub znacznikach. Chociaż zwykle łatwiej jest definiować elementy interfejsu użytkownika w języku XAML, w przypadku prostego okna dialogowego łatwiej jest po prostu używać kodu. W tym przykładzie zostanie utworzone okno dialogowe z powiadomieniem użytkownika o braku połączenia sieci Wi-Fi, a następnie użycie metody ShowAsync do jej wyświetlenia.

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

Jeśli okno dialogowe zawartości jest bardziej złożone, można go łatwiej utworzyć za pomocą języka XAML. Możesz utworzyć go w pliku XAML dla strony lub utworzyć podklasę ContentDialog z jego własnym plikiem .xaml i plikiem code-behind. Aby zapoznać się z pełnymi przykładami obu tych elementów, zobacz dokumentację klasy [ContentDialog].

W programie Visual Studio nie ma szablonu elementu do utworzenia nowego pliku okna dialogowego zawartości, ale możesz użyć szablonu Pusta strona i zmodyfikować pliki wynikowe w celu utworzenia okna dialogowego.

Aby utworzyć nowe okno dialogowe zawartości za pomocą języka XAML i kodu-behind

1. W okienku Eksplorator rozwiązań kliknij prawym przyciskiem myszy nazwę projektu i wybierz polecenie Dodaj > nowy element...
2. W oknie dialogowym Dodawanie nowego elementu wybierz pozycję WinUI na liście szablonów po lewej stronie okna.
3. Wybierz szablon Pusta strona .
4. Nazwij plik . (W tym przykładzie plik ma nazwę XamlContentDialog).
5. Naciśnij przycisk Dodaj.

W nowym pliku xaml zmień otwierające i zamykające tagi strony na Okno dialogowe zawartości.

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

</Page>
-->

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

</ContentDialog>

W pliku .xaml.cs zmień klasę, aby dziedziczyła po elemencie ContentDialog zamiast Page.

// public sealed partial class XamlContentDialog : Page

public sealed partial class XamlContentDialog : ContentDialog

Pokaż okno dialogowe

Aby wyświetlić okno dialogowe, wywołaj metodę ShowAsync .

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

Ostrzeżenie

W danym oknie może być otwarty tylko jeden plik ContentDialog. Próba otwarcia dwóch okien dialogowych zawartości spowoduje zgłoszenie wyjątku.

Ustaw XamlRoot

Po wyświetleniu elementu ContentDialog należy ręcznie przypisać XamlRoot dialogu do korzenia hosta XAML. W tym celu ustaw właściwość XamlRoot elementu ContentDialog na ten sam element XamlRoot, który znajduje się już w drzewie XAML.

Jeśli właściwość ContentDialog jest wyświetlana na stronie, możesz ustawić właściwość XamlRoot elementu ContentDialog na wartość XamlRoot strony, jak pokazano w poprzednim przykładzie.

Okno nie ma właściwości XamlRoot, więc jeśli okno dialogowe jest wyświetlane z okna, ustaw właściwość XamlRoot okna na wartość elementu zawartości głównej okna, jak pokazano tutaj.

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

Odpowiadanie na przyciski okna dialogowego

Gdy użytkownik kliknie przycisk okna dialogowego, metoda ShowAsync zwraca właściwość ContentDialogResult , aby poinformować, który przycisk użytkownik kliknie.

Dialog w tym przykładzie zadaje pytanie i wykorzystuje zwrócony ContentDialogResult do określenia odpowiedzi użytkownika.

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

Zapewnij bezpieczne działanie

Ponieważ okna dialogowe blokują interakcję użytkownika, a przyciski są podstawowym mechanizmem odrzucania okna dialogowego, upewnij się, że okno dialogowe zawiera co najmniej jeden przycisk "bezpieczny" i niezniszczalny, taki jak "Zamknij" lub "Got it!". Wszystkie okna dialogowe powinny zawierać co najmniej jeden przycisk bezpiecznej akcji, aby zamknąć okno dialogowe. Dzięki temu użytkownik może bezpiecznie zamknąć okno dialogowe bez wykonywania akcji.

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

Gdy okna dialogowe są używane do wyświetlania pytania blokującego, okno dialogowe powinno przedstawić użytkownikowi przyciski akcji związane z pytaniem. Przycisk "bezpieczny" i niezniszczalny może towarzyszyć jednym lub dwóm przyciskom akcji "zrób to". Podczas prezentowania użytkownikowi wielu opcji upewnij się, że przyciski wyraźnie wyjaśniają akcje "zrób to" i "nie rób tego" związane z zadaną kwestią.

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

Trójprzyciskowe okno dialogowe jest używane, gdy prezentujesz użytkownikowi dwie akcje „zrób to” oraz jedną akcję „nie rób tego”. Trzy okna dialogowe przycisków powinny być używane oszczędnie z wyraźnymi rozróżnieniami między akcją pomocniczą a bezpieczną/zamkniętą akcją.

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

Trzy przyciski dialogowe

ContentDialog ma trzy różne typy przycisków, których można użyć do utworzenia okna dialogowego.

• CloseButton — wymagane — reprezentuje bezpieczną, niezniszczającą akcję, która umożliwia użytkownikowi zamknięcie okna dialogowego. Jest wyświetlany jako najbardziej prawy przycisk.
• głównyPrzycisk — opcjonalny — reprezentuje pierwszą czynność "wykonaj to". Jest wyświetlany jako przycisk po lewej stronie.
• SecondaryButton — opcjonalny — reprezentuje drugie działanie „zrób to”. Pojawia się jako środkowy przycisk.

Użycie wbudowanych przycisków spowoduje, że przyciski zostaną odpowiednio ustawione, będą prawidłowo reagować na zdarzenia klawiatury, obszar poleceń pozostanie widoczny nawet wtedy, gdy pojawi się klawiatura ekranowa, a okno dialogowe będzie wyglądać spójnie z innymi oknami dialogowymi.

Przycisk zamykania

Każde okno dialogowe powinno zawierać bezpieczny, niezniszczalny przycisk akcji, który umożliwia użytkownikowi bezpieczne zamknięcie okna dialogowego.

Użyj interfejsu API ContentDialog.CloseButton, aby utworzyć ten przycisk. Dzięki temu można stworzyć odpowiednie doświadczenie użytkownika dla wszystkich zestawów wejściowych, w tym również myszy, klawiatury, dotyku i gamepada. To doświadczenie nastąpi, gdy:

• Użytkownik klika lub naciska przycisk CloseButton.
• Użytkownik naciska przycisk wstecz systemu.
• Użytkownik naciska ESC na klawiaturze.
• Użytkownik naciska gamepad B.

Gdy użytkownik kliknie przycisk okna dialogowego, metoda ShowAsync zwraca właściwość ContentDialogResult , aby poinformować, który przycisk użytkownik kliknie. Naciśnięcie przycisku zamykania zwraca wartość ContentDialogResult.None.

GuzikPierwszy i GuzikDrugi

Oprócz funkcji CloseButton możesz opcjonalnie przedstawić użytkownikowi jeden lub dwa przyciski akcji związane z instrukcją główną. Użyj przycisku PrimaryButton, aby wykonać pierwszą akcję "Zrób to", i przycisku SecondaryButton, aby wykonać drugą akcję "Zrób to". W oknach dialogowych z trzema przyciskami element PrimaryButton zazwyczaj reprezentuje afirmatywne działanie "zrób to", podczas gdy element SecondaryButton zazwyczaj reprezentuje neutralną lub pomocniczą akcję "zrób to". Na przykład aplikacja może monitować użytkownika o subskrybowanie usługi. Przycisk PrimaryButton jako działanie afirmacyjne "zrób to" będzie zawierać tekst Subskrybuj, a przycisk SecondaryButton jako działanie neutralne "zrób to" będzie zawierać tekst Wypróbuj. Funkcja CloseButton umożliwiłaby użytkownikowi anulowanie bez wykonywania żadnej akcji.

Gdy użytkownik kliknie element PrimaryButton, metoda ShowAsync zwraca wartość ContentDialogResult.Primary. Gdy użytkownik kliknie przycisk SecondaryButton, metoda ShowAsync zwraca wartość ContentDialogResult.Secondary.

Przycisk domyślny

Opcjonalnie możesz wybrać rozróżnienie jednego z trzech przycisków jako przycisku domyślnego. Określenie przycisku domyślnego powoduje wystąpienie następujących sytuacji:

• Przycisk otrzymuje wizualne wyróżnienie jako przycisk akcentowy.
• Przycisk automatycznie odpowie na klucz ENTER
  • Gdy użytkownik naciśnie ENTER na klawiaturze, program obsługi kliknięć skojarzony z przyciskiem domyślnym zostanie wyzwolony, a właściwość ContentDialogResult zwróci wartość skojarzoną z przyciskiem domyślnym
  • Jeśli użytkownik umieścił fokus klawiatury na kontrolce obsługującej ENTER, przycisk domyślny nie odpowie na naciśnięcia ENTER
• Przycisk będzie automatycznie otrzymywać fokus po otwarciu okna dialogowego, chyba że zawartość okna dialogowego zawiera interfejs użytkownika z możliwością koncentracji uwagi

Użyj właściwości ContentDialog.DefaultButton, aby wskazać przycisk domyślny. Domyślnie nie ustawiono przycisku domyślnego.

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

Okna dialogowe potwierdzenia (OK/Anuluj)

Okno dialogowe potwierdzenia daje użytkownikom możliwość potwierdzenia, że chcą wykonać akcję. Mogą potwierdzić akcję lub wybrać anulowanie. Typowe okno dialogowe potwierdzenia ma dwa przyciski: przycisk potwierdzenia ("OK") i przycisk anuluj.

• Ogólnie rzecz biorąc, przycisk potwierdzenia powinien znajdować się po lewej stronie (przycisk podstawowy), a przycisk Anuluj (przycisk pomocniczy) powinien znajdować się po prawej stronie.

  
• Jak wspomniano w sekcji ogólne zalecenia, użyj przycisków z tekstem, który identyfikuje konkretne odpowiedzi na główną instrukcję lub zawartość.

UwP i WinUI 2

Ważne

Informacje i przykłady w tym artykule są zoptymalizowane dla aplikacji korzystających z Windows App SDK oraz WinUI 3, ale generalnie mają zastosowanie także w aplikacjach UWP używających WinUI 2. Zobacz dokumentację interfejsu API platformy UWP, aby uzyskać informacje i przykłady dotyczące platformy.

Ta sekcja zawiera informacje potrzebne do używania kontrolki w aplikacji platformy UWP lub WinUI 2.

API dla tej kontrolki istnieją w ramach przestrzeni nazw Windows.UI.Xaml.Controls.

• interfejsy API platformy UWP:klasa ContentDialog
• Otwórz aplikację Galerii WinUI 2 i zobacz ContentDialog w działaniu. Aplikacja z galerii WinUI 2 zawiera interaktywne przykłady większości kontrolek, funkcji i funkcji winUI 2. Pobierz aplikację ze Sklepu Microsoft lub pobierz kod źródłowy w witrynie GitHub.

Zalecamy użycie najnowszej wersji WinUI 2 , aby uzyskać najbardziej aktualne style i szablony dla wszystkich kontrolek. Interfejs WinUI 2.2 lub nowszy zawiera nowy szablon dla tej kontrolki, który używa zaokrąglonych narożników. Aby uzyskać więcej informacji, zobacz Zaokrąglenie narożnika.

ContentDialog w AppWindow lub Xaml Islands

UWAGA: Ta sekcja dotyczy tylko aplikacji przeznaczonych dla systemu Windows 10 w wersji 1903 lub nowszej. Wyspy AppWindow i XAML nie są dostępne we wcześniejszych wersjach. Aby uzyskać więcej informacji na temat przechowywania wersji, zobacz Wersja adaptacyjna aplikacji.

Domyślnie okna dialogowe zawartości są wyświetlane modalnie względem korzenia ApplicationView. W przypadku korzystania z AppWindow lub wyspy XAMLwewnątrz ContentDialog, należy ręcznie ustawić XamlRoot na root XAML hosta w oknie dialogowym.

Aby to zrobić, ustaw właściwość XamlRoot obiektu ContentDialog na ten sam XamlRoot, co element już znajdujący się w AppWindow lub XAML Island, jak pokazano tutaj.

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

Ostrzeżenie

W danym wątku może być otwarty tylko jeden dialog typu ContentDialog. Próba otwarcia dwóch ContentDialogs spowoduje zgłoszenie wyjątku, nawet jeśli próby otwarcia podejmowane są w oddzielnych instancjach AppWindow.

Powiązane artykuły

• Podpowiedzi
• Menu i menu kontekstowe
• , klasa wysuwana
• klasy ContentDialog