Rozhraní API pro dialog – MRTK3

Dialogy jsou krátkodobá zobrazení uživatelského rozhraní, která poskytují kontextové informace o aplikacích. Často od uživatele požadují nějakou akci a pak vrátí výsledek zpět do obchodní logiky aplikace v asynchronním úkolu nebo výsledku. Pomocí dialogových oken můžete uživatele upozornit na důležité informace nebo požádat o potvrzení před dokončením akce.

Uživatelské jádro MRTK3 poskytuje IDialog rozhraní API spolu se základní Dialog implementací a DialogPool prostředím pro vytváření a správu instancí. Tato dokumentace popisuje rozhraní API fluent řízené kódem pro zobrazení dialogů z obchodní logiky. Dokumentaci k předfabám, které jsou součástí balíčku UX Components, najdete v dokumentaci k prefabu dialogového okna tady.

Využití

DialogPool Umístěte někam do své scény nebo hierarchie uživatelského rozhraní. V případě potřeby můžete spravovat vlastní globální DialogPool odkazy pomocí jednoduchého, nadřízenýho nebo jiného vzoru. Sada MRTK sama o sobě nevytěžuje názor na to, jak udržujete globální DialogPool odkaz, ale komponenta musí být někde ve vaší scéně, aby se do sestavení zahrnulo zobrazení dialogového okna, na které odkazujete.

DialogPool nástroj automaticky nastaví svůj prefab odkaz na standardní součásti uživatelského prostředí, CanvasDialog.prefab pokud je balíček nainstalovaný. Další informace o standardu CanvasDialog.prefabUX Components najdete v dokumentaci tady.

Jakmile získáte DialogPool odkaz, můžete ke konfiguraci a zobrazení dialogového okna použít rozhraní API tvůrce fluent stylu.

dialogPool.Get()
    .SetHeader("This is the Dialog's header.")
    .SetBody("You can specify the dialog's body text here.")
    .SetPositive("The positive button's label.", (args) => { /* Do thing! */ })
    .Show()

V dialogovém okně opětovného otevření se zobrazí pouze dílčí ovládací prvky, které jsou zadané ve vašich voláních rozhraní API tvůrce. Výsledkem výše uvedeného příkladu kódu bude například dialogové okno s textem záhlaví i základním textem, ale pouze jedním tlačítkem kladné volby. Další tlačítka lze zadat zřetězeným voláním dalších metod.

// This dialog will show all three buttons.
dialogPool.Get()
    .SetHeader("A header.")
    .SetBody("Foobarbaz!")
    .SetPositive("The positive button's label.", (args) => { /* Do thing! */ })
    .SetNegative("The negative button's label.", (args) => { /* Do another thing! */ })
    .SetNeutral("A neutral option, too!", (args) => { /* Do some neutral thing. */ })
    .Show()

Zpětná args volání tlačítka se DialogButtonEventArgspředávají jako , který bude obsahovat odkaz na IDialog událost, která vygenerovala událost, a DialogButtonType tlačítko, které uživatel zvolil.

Je možné, že dialogové okno může být externě zavřeno, než se uživatel bude moct rozhodnout. Příčinou může být otevření jiného dialogového okna nebo ruční zavření dialogového okna v kódu. V takovém případě by zpětné volání zadané do SetPositive() nikdy nebylo vyvoláno. Pokud si chcete poslechnout jakoukoli událost v dialogovém okně, včetně externího zavření, můžete si poslechnout OnDismissed zpětné volání.

var dialog = dialogPool.Get()?SetBody("Foobar!");
dialog.OnDismissed += (args) => { /* do things! */ };
dialog.Show();

OnDismissed předá DialogDismissedEventArgsparametr , který bude obsahovat DialogButtonEventArgs parametr , pokud se uživatel rozhodl, nebo null pokud byl dialog zavřen z nějakého jiného důvodu.

Standardní IDialog.Show() metoda je vhodná pro typické idiomické použití Unity v jiných metodáchasync . Pokud obchodní logiku async píšete v kontextu, můžete použít metodu IDialog.ShowAsync() pro await výsledek dialogového okna s výraznější syntaxí.

async void SomeAsyncBusinessLogic()
{
    var result = await dialogPool.Get()
                    .SetBody("The await will resolve when the user selects the option.")
                    .SetNeutral("A button!")
                    .ShowAsync();

    Debug.Log("Async dialog says: " + result.Choice?.ButtonText);
}

ShowAsync vrátí stejný typ arg jako OnDismissed, a DialogDismissedEventArgs.

Ukázková scéna a prefabs

Informace o zahrnutých prefabách a ukázkových scénách najdete v dokumentaci ke komponentám uživatelského rozhraní zde.