API диалоговых окон — MRTK3

Диалоговые окна — это кратковременные представления пользовательского интерфейса, предоставляющие контекстные сведения о приложении. Они часто запрашивают от пользователя какое-либо действие, а затем возвращают результат обратно в бизнес-логику приложения в асинхронной задаче или результате. Диалоговые окна позволяют уведомлять пользователей о важных сведениях или запрашивать подтверждение перед выполнением действия.

UXCore MRTK3 предоставляет IDialog API, а также базовую Dialog реализацию и для DialogPool создания экземпляров и управления ими. В этой документации описывается управляемый кодом API fluent для отображения диалогов из бизнес-логики. Документацию по заготовкам, включенным в пакет компонентов пользовательского интерфейса, см. в документации по заготовке Dialog здесь.

Использование

Поместите DialogPool объект в иерархию сцены или пользовательского интерфейса. При желании можно управлять собственной глобальной DialogPool ссылкой с помощью одноэлементного, диспетчерского или другого шаблона. Сам MRTK не предоставляет мнение о том, как вы поддерживаете глобальную DialogPool ссылку, но компонент должен находиться в сцене, чтобы упоминаемая заготовка представления диалогового окна была включена в сборку.

DialogPool автоматически установит ссылку на заготовку стандартных компонентов CanvasDialog.prefab пользовательского интерфейса, если пакет установлен. Дополнительные сведения о стандарте CanvasDialog.prefabкомпонентов пользовательского интерфейса см. в документации здесь.

Получив ссылку DialogPool , вы можете использовать API построителя в свободном стиле для настройки и отображения диалогового окна.

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

В диалоговом окне повторного использования будут отображаться только вложенные элементы управления, указанные в вызовах API построителя. Например, приведенный выше пример кода приведет к созданию диалогового окна с текстом заголовка и текстом основного текста, но только с одной кнопкой положительного выбора. Дополнительные кнопки можно указать путем связывания последующих вызовов методов.

// 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()

Объект , args передаваемый через обратные вызовы кнопки, будет DialogButtonEventArgsиметь значение , включающее как ссылку на IDialog объект , создавший событие, так и DialogButtonType кнопку, выбранную пользователем.

Возможно, диалоговое окно будет закрыто извне, прежде чем пользователь сможет принять решение. Это может быть вызвано открытием другого диалога или закрытием диалога вручную в коде. В этом случае обратный вызов, предоставленный для SetPositive() , никогда не будет вызван. Если вы хотите прослушать любое событие в диалоговом окне, включая внешнее закрытие, вы можете прослушать обратный OnDismissed вызов.

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

OnDismissed передает DialogDismissedEventArgs, который будет содержать DialogButtonEventArgs , если пользователь сделал выбор или null если диалоговое окно было отклонено по какой-либо другой причине.

Стандартный IDialog.Show() метод подходит для типичного идиоматического использования Unity в методах, отличных отasync . Если вы пишете бизнес-логику в контексте async , можно использовать IDialog.ShowAsync() метод для await в результатах диалога с более выразительным синтаксисом.

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возвращает тот же тип аргумента, что OnDismissedи , .DialogDismissedEventArgs

Пример сцены и заготовок

Сведения о включенных заготовках и примерах сцен см. в документации по компонентам пользовательского интерфейса здесь.