对话框 API - MRTK3

对话框是提供上下文应用信息的短期 UI 视图。 它们经常向用户请求某些操作，然后通过异步任务或结果将结果返回到应用的业务逻辑中。 对话框可用于通知用户重要信息或在可以完成某个操作之前请求确认信息。

MRTK3 UXCore 提供 IDialog API 以及基本 Dialog 实现和用于生成和管理实例的 DialogPool。 本文档介绍代码驱动的 Fluent API，用于基于业务逻辑显示对话框。 有关 UX 组件包中包含的预制件的文档，请参阅此处的对话框预制件文档。

使用情况

将 DialogPool 放置在场景或 UI 层次结构中的某个位置。 如果需要，可以使用 singleton、管理器或其他模式管理自己的全局 DialogPool 引用。 MRTK 本身不会对如何维护全局 DialogPool 引用发表意见，但该组件必须存在于场景中的某个位置，以便在生成中包含引用的对话框视图预制件。

DialogPool 会自动将其预制件引用设置为标准 UX 组件 CanvasDialog.prefab（如果安装了该包）。 有关 UX 组件标准 CanvasDialog.prefab 的详细信息，请参阅此处的文档。

获取 DialogPool 引用后，可以使用 Fluent 样式的生成器 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() 方法适合非 async 方法中的典型 Unity 惯用用法。 如果要在 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。

示例场景和预制件

有关包含的预制件和示例场景的信息，请参阅此处的 UX 组件文档。