Párbeszédablak-vezérlők

A párbeszédpanel-vezérlők olyan modális felhasználói felületi átfedések, amelyek környezeti alkalmazásinformációkat biztosítanak. Letiltják az alkalmazásablakkal folytatott interakciókat, amíg explicit módon el nem utasítják őket. Gyakran kérnek valamilyen műveletet a felhasználótól.

Példa egy párbeszédre

Ez a megfelelő vezérlő?

A párbeszédpanelek segítségével értesítheti a felhasználókat a fontos információkról, vagy megerősítést vagy további információkat kérhet egy művelet végrehajtása előtt.

A párbeszédpanelek és az úszó panelek (hasonló vezérlők) használatának időpontjával kapcsolatos javaslatokért lásd: Párbeszédpanelek és úszó panelek.

Általános irányelvek

Egyértelműen azonosítsa a problémát vagy a felhasználó célját a párbeszédpanel szövegének első sorában.
A párbeszédpanel címe a fő utasítás, és nem kötelező.
- A párbeszédpanel használata esetén használjon egy rövid címet, hogy elmagyarázza, mit kell tenniük a felhasználóknak.
- Ha a párbeszédpanelt egy egyszerű üzenet, hiba vagy kérdés megjelenítéséhez használja, kihagyhatja a címet. A tartalomszövegre támaszkodva adja meg ezeket az alapvető információkat.
- Győződjön meg arról, hogy a cím közvetlenül a gombválasztásokhoz kapcsolódik.
A párbeszédpanel tartalma tartalmazza a leíró szöveget, és kötelező.
- A lehető legegyszerűbben jelenítse meg az üzenetet, a hibát vagy a blokkoló kérdést.
- Ha használ egy párbeszédpanel címet, akkor a tartalomterületen részletesebb információt adhat meg vagy definiálhatja a terminológiát. Ne ismételje meg a címet kissé eltérő szöveggel.
Legalább egy párbeszédgombnak meg kell jelennie.
- Biztosítsa, hogy a párbeszédpanelen legyen legalább egy gomb, amely egy biztonságos, nem ártalmas műveletet jelez, mint például a "Megvan!", "Bezárás" vagy "Mégse". A Gomb hozzáadásához használja a CloseButton API-t.
- A fő utasításra vagy tartalomra adott válaszok használata gombszövegként. Például: "Engedélyezi az AppName számára, hogy hozzáférjen a tartózkodási helyéhez?", majd az "Engedélyezés" és a "Letiltás" gombok. A konkrét válaszok gyorsabban értelmezhetők, ami hatékony döntéshozatalt eredményez.
- Győződjön meg arról, hogy a műveletgombok szövege tömör. A rövid sztringek lehetővé teszik, hogy a felhasználó gyorsan és magabiztosan válasszon.
- A biztonságos, nem romboló művelet mellett opcionálisan egy vagy két, a fő utasításhoz kapcsolódó gombot jeleníthet meg a felhasználó számára. Ezek a "végrehajtás" gombok megerősítik a dialógusablak lényegét. A PrimaryButton és a SecondaryButton API-k segítségével adja hozzá ezeket a "do it" műveleteket.
- A "do it" műveletgomb(ok)nak a bal szélső gombként kell megjelennie. A biztonságos, nem romboló műveletnek a jobb szélső gombként kell megjelennie.
- Választhatja, hogy a párbeszédpanel alapértelmezett gombjaként meg szeretné különböztetni a három gomb egyikét. A DefaultButton API-val megkülönböztethet egy gombot.
Ne használjon párbeszédpaneleket olyan hibákhoz, amelyek a lap egy adott helyére vonatkoznak, például érvényesítési hibákra (például jelszómezőkben), használja magát az alkalmazás vásznát beágyazott hibák megjelenítéséhez.
A ContentDialog osztály használatával hozhatja létre a párbeszédpanelt. Ne használja az elavult MessageDialog API-t.

Dialógus létrehozása

Fontos API-k: ContentDialog osztály

Nyissa meg a WinUI 3 Katalógus alkalmazást, és tekintse meg működés közben a ContentDialogot

A WinUI 3 Katalógus alkalmazás interaktív példákat tartalmaz a WinUI vezérlőire és funkcióira. Kérje le az alkalmazást a Microsoft Áruházból vagy keresse meg a forráskódot a GitHub webhelyen.

Párbeszédpanel létrehozásához használja a ContentDialog osztályt. Létrehozhat egy párbeszédablakot kódban vagy jelölőnyelvvel. Bár a felhasználói felület elemeit általában könnyebben definiálhatja az XAML-ben, egy egyszerű párbeszédpanel esetén egyszerűbb lehet a kód használata. Ez a példa létrehoz egy párbeszédpanelt, amely értesíti a felhasználót arról, hogy nincs Wi-Fi-kapcsolat, majd a ShowAsync metódussal jeleníti meg.

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

Ha a tartalom párbeszédpanel összetettebb, egyszerűbb lehet az XAML használatával létrehozni. Létrehozhatja a lap XAML-fájljában, vagy létrehozhatja a ContentDialog alosztályát saját .xaml és kód mögötti fájllal. Mindkettőre vonatkozó teljes példákért tekintse meg a [ContentDialog] osztályreferenciáját.

A Visual Studio nem tartalmaz elemsablont egy új tartalom párbeszédpanelfájl létrehozásához, de az Üres lap sablont használhatja, és módosíthatja az eredményként kapott fájlokat egy párbeszédpanel létrehozásához.

Új tartalom párbeszédpanel létrehozása az XAML-lel és a mögöttes kóddal

A Solution Explorer panelen kattintson a jobb gombbal a projekt nevére, és válassza a Add > New Item...
Az Új elem hozzáadása párbeszédpanelen válassza a WinUI lehetőséget az ablak bal oldalán található sablonlistában.
Válassza ki az Üres lap sablont.
A fájl neve legyen . (Ebben a példában a fájl neve XamlContentDialog).
Nyomja le a Hozzáadás billentyűt.

Az új .xaml fájlban módosítsa a nyitó és záró lapcímkéket Tartalom párbeszédpanelre.

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

</Page>
-->

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

</ContentDialog>

A .xaml.cs fájlban az osztályt állítsa úgy, hogy a ContentDialogból öröklődjön az Oldal helyett.

// public sealed partial class XamlContentDialog : Page

public sealed partial class XamlContentDialog : ContentDialog

A párbeszédpanel megjelenítése

Párbeszédpanel megjelenítéséhez hívja meg a ShowAsync metódust .

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

Figyelmeztetés

Egyszerre csak egy ContentDialog lehet megnyitva egy ablakban. Ha két tartalom párbeszédpanelt próbál megnyitni, kivételt fog eredményezni.

Az XamlRoot beállítása

ContentDialog megjelenítésekor manuálisan kell beállítania a párbeszédpanel XamlRoot elemét az XAML-gazdagép gyökerére. A tartalom megjelenítéséhez állítsa a ContentDialog XamlRoot tulajdonságát ugyanarra a XamlRootra, mint amelyet már egy XAML-fa elem használ.

Ha a ContentDialog egy lapról jelenik meg, a ContentDialog XamlRoot tulajdonságát az oldal XamlRoot tulajdonságára állíthatja, ahogyan az előző példában is látható.

Az Ablak nem rendelkezik XamlRoot tulajdonságmal, ezért ha a párbeszédpanel egy Ablakból jelenik meg, állítsa a párbeszédpanel XamlRoot tulajdonságát az ablak gyökértartalomelemének XamlRoot tulajdonságára, ahogy az itt látható.

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

Válasz a párbeszédpanel gombjaira

Amikor a felhasználó egy párbeszédpanel gombra kattint, a ShowAsync metódus egy ContentDialogResult értéket ad vissza, hogy megtudja, melyik gombra kattint a felhasználó.

A példában szereplő párbeszédpanel kérdést tesz fel, és a visszaadott ContentDialogResult használatával határozza meg a felhasználó válaszát.

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

Biztonságos művelet biztosítása

Mivel a párbeszédpanelek blokkolják a felhasználói interakciót, és mivel a felhasználók számára a gombok az elsődleges mechanizmus a párbeszédpanel bezárásához, győződjön meg arról, hogy a párbeszédpanel legalább egy "biztonságos" és nondestruktív gombot tartalmaz, mint például "Bezárás" vagy "Megvan!". Minden párbeszédpanelnek tartalmaznia kell legalább egy biztonságos művelet gombot a párbeszédpanel bezárásához. Ez biztosítja, hogy a felhasználó magabiztosan bezárja a párbeszédpanelt művelet végrehajtása nélkül.

Egy gombos párbeszédpanel

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

Ha a párbeszédpanelek egy blokkoló kérdés megjelenítésére szolgálnak, a párbeszédpanelen a felhasználónak a kérdéshez kapcsolódó műveletgombokat kell megjelenítenie. "Biztonságos" és "nem destruktív" gombot egy vagy két "csináld meg" gomb kísérheti. Ha a felhasználót több lehetőséggel is meg szeretné jeleníteni, győződjön meg arról, hogy a gombok egyértelműen elmagyarázzák a javasolt kérdéshez kapcsolódó "csináld" és "ne tegye meg" műveleteket.

Két gombos párbeszédpanel

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

Három gomb párbeszédpanelt használ, amikor két "csináld meg" művelettel és egy "ne csináld meg" művelettel jeleníti meg a felhasználót. A három gombos párbeszédpanelt takarékosan kell használni, egyértelmű különbségekkel a másodlagos művelet és a biztonságos/záró művelet között.

Három gombos párbeszédpanel

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

A három párbeszéd gomb

A ContentDialog három különböző gombtípussal rendelkezik, amelyekkel párbeszédpanel-felületet hozhat létre.

CloseButton – Kötelező – Azt a biztonságos, nem strukturáló műveletet jelöli, amely lehetővé teszi, hogy a felhasználó kilépjen a párbeszédpanelről. A jobb szélső gombként jelenik meg.
PrimaryButton – Nem kötelező – Az első "csináld meg" műveletet jelöli. A bal szélső gombként jelenik meg.
SecondaryButton – Nem kötelező – A második "csináld meg" műveletet jelöli. Középső gombként jelenik meg.

A beépített gombok megfelelően helyezik el a gombokat, gondoskodnak arról, hogy megfelelően reagáljanak a billentyűzeteseményekre, győződjön meg arról, hogy a parancsterület akkor is látható marad, ha a képernyő-billentyűzet be van kapcsolva, és konzisztenssé teszi a párbeszédpanelt más párbeszédpanelekkel.

Bezárásgomb

Minden párbeszédpanelnek tartalmaznia kell egy biztonságos, nem strukturált műveletgombot, amely lehetővé teszi a felhasználó számára, hogy magabiztosan kilépjen a párbeszédpanelből.

A gomb létrehozásához használja a ContentDialog.CloseButton API-t. Ez lehetővé teszi, hogy a megfelelő felhasználói élményt hozza létre minden bemenethez, beleértve az egeret, a billentyűzetet, az érintést és a játékpadot. Ez az élmény akkor fog megtörténni, amikor:

A felhasználó a CloseButtonra kattint vagy koppint.
A felhasználó lenyomja a rendszer vissza gombját.
A felhasználó lenyomja az ESC gombot a billentyűzeten.
A felhasználó megnyomja a "B" gamepadet.

Amikor a felhasználó egy párbeszédpanel gombra kattint, a ShowAsync metódus egy ContentDialogResult értéket ad vissza, hogy megtudja, melyik gombra kattint a felhasználó. A CloseButton lenyomása a ContentDialogResult.None értéket adja vissza.

PrimaryButton és SecondaryButton

A CloseButtonon kívül szükség esetén egy vagy két műveleti gombot is megjeleníthet a felhasználónak a fő utasításhoz kapcsolódóan. Használja a PrimaryButtont az első "csináld meg" művelethez, a Másodlagosbuttont pedig a második "csináld meg" művelethez. A háromgombos párbeszédpaneleken a PrimaryButton általában az igenlő "do it" műveletet, míg a SecondaryButton általában egy semleges vagy másodlagos "do it" műveletet jelöl. Egy alkalmazás például megkérheti a felhasználót, hogy iratkozzon fel egy szolgáltatásra. A PrimaryButton, mint az igenlő "csináld" művelet, a Feliratkozás szöveget tartalmazná, míg a SecondaryButton, mint semleges "próbáld ki" művelet, a Próbáld ki szöveget jelenítené meg. A CloseButton lehetővé teszi a felhasználó számára, hogy bármelyik művelet végrehajtása nélkül mondja le a műveletet.

Amikor a felhasználó a PrimaryButtonra kattint, a ShowAsync metódus a ContentDialogResult.Primary értéket adja vissza. Amikor a felhasználó a SecondaryButtonra kattint, a ShowAsync metódus a ContentDialogResult.Secondary értéket adja vissza.

Három gombos párbeszédpanel

Alapértelmezett gomb

Dönthet úgy is, hogy a három gomb közül az egyiket választja alapértelmezettként. Az alapértelmezett gomb megadása esetén a következők történnek:

A gomb megkapja az Ékezetes gomb vizualizációs kezelését
A gomb automatikusan válaszol az ENTER billentyűre
- Amikor a felhasználó lenyomja az ENTER billentyűt a billentyűzeten, az Alapértelmezett gombhoz társított kattintáskezelő aktiválódik, és a ContentDialogResult visszaadja az Alapértelmezett gombhoz társított értéket
- Ha a felhasználó olyan vezérlőre helyezte a Billentyűzetfókuszt, amely kezeli az ENTER billentyűt, az Alapértelmezett gomb nem válaszol az ENTER billentyűkombinációkra
A gomb automatikusan fókuszba kerül a párbeszédpanel megnyitásakor, kivéve, ha a párbeszédpanel tartalma fókuszba helyezhető felhasználói felületet tartalmaz

Az alapértelmezett gombot a ContentDialog.DefaultButton tulajdonság használatával jelezheti. Alapértelmezés szerint nincs beállítva alapértelmezett gomb.

Három gombos párbeszédpanel alapértelmezett gombbal

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

Megerősítő ablakok (OK/Mégse)

A megerősítést kérő párbeszédpanelen a felhasználók ellenőrizhetik, hogy műveletet szeretnének végrehajtani. Megerősíthetik a műveletet, vagy dönthetnek a lemondás mellett. Egy tipikus megerősítő párbeszédpanelen két gomb található: egy megerősítés ("OK") gomb és egy mégse gomb.

Általában a megerősítés gombnak a bal oldalon kell lennie (az elsődleges gomb), a mégse gombnak (a másodlagos gombnak) pedig a jobb oldalon kell lennie.
Az általános javaslatok szakaszban leírtaknak megfelelően használjon olyan szöveget tartalmazó gombokat, amelyek a fő utasításra vagy tartalomra adott válaszokat azonosítják.

ContentDialog az AppWindowban vagy a Xaml-szigeteken

MEGJEGYZÉS: Ez a szakasz csak azokra az alkalmazásokra vonatkozik, amelyek Windows 10, 1903-at vagy újabb verziót céloznak meg. Az AppWindow és az XAML-szigetek nem érhetők el a korábbi verziókban. A verziószámozással kapcsolatos további információkért lásd: Adaptív verziójú alkalmazások.

Alapértelmezés szerint a tartalom párbeszédpanelek modálisan jelennek meg a gyökér ApplicationView-hoz képest. Ha Egy AppWindow-szigeten vagy egy XAML-szigeten belül használja a ContentDialogot, manuálisan kell beállítania a párbeszédpanel XamlRoot elemét az XAML-gazdagép gyökerére.

A ContentDialog XamlRoot tulajdonságát állítsa be ugyanarra a XamlRootra, mint az AppWindow vagy egy XAML-sziget már meglévő elemének XamlRootja, ahogyan itt látható.

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