创建 Visual Studio 用户提示

用户提示是一种简单的 UI 机制，用于提示用户进行选择、确认消息或提供单行字符串输入。 提示用户创建一个对话框，其中包含消息、标题栏、 关闭 按钮和可选图标。 当对话框提示用户从一组选项中进行选择时，它还包含选项的一到三个按钮。

用户提示有两个变体：选项提示和输入提示。

选项提示的常见示例是请求使用“确定”或“取消”提示进行确认，或者要求用户在一小组选项（不超过三个选项）中进行选择。

向用户提供的选项将映射到返回值的类型，该类型在类型参数 TResult 中定义。

若要要求用户提供单行字符串输入（如项目名称），请使用输入提示。

用户始终可以选择在不做出选择的情况下关闭提示。

用户提示部分

1. 消息
2. 选项按钮
3. “关闭”按钮

开始吧

若要开始，请按照 创建第一个 Visual Studio 扩展中的步骤作。

处理用户提示

本文介绍以下使用用户提示的方案：

• 显示用户提示
• 使用内置选项
• 使用自定义选项创建提示

显示用户提示

使用新的扩展性模型创建用户提示非常简单，只需从 ShowPromptAsync 帮助程序调用方法并传入选项即可。

ShellExtensibility.ShowPromptAsync（）

ShowPromptAsync 方法采用三个参数：

示例：

下面的代码 Command 显示了用户提示，其中包含一条简单的消息和一个 “确定 ”按钮。

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    await this.Extensibility.Shell().ShowPromptAsync("This is a user prompt.", PromptOptions.OK, cancellationToken))
}

使用内置选项

SDK 中提供了多个预定义 PromptOptions 集。

好的

OKCancel

重试/取消

带有图标的确认

示例：

使用单个 “确定 ”选项创建提示。

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken ct)
{
    // Asking the user to confirm an operation.
    if (!await this.Extensibility.Shell().ShowPromptAsync("Continue with executing the command?", PromptOptions.OKCancel, ct))
    {
      return;
    }
    
    ...
}

如果用户选择“确定”，那么在等待ShowPromptAsynctrue时将返回结果。 如果用户选择 “关闭 ”按钮，则返回 false。

更改内置选项的默认选择为取消

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken ct)
{
  // Asking the user to confirm an operation.
  if (!await this.Extensibility.Shell().ShowPromptAsync("Continue with executing the command?", PromptOptions.OKCancel.WithCancelAsDefault(), ct))
  {
    return;
  }
  
  ...
}

使用自定义选项创建提示

还可以自定义向用户呈现的选项以及映射到每个选项的返回值。

而不是使用PromptOptions中定义的集合，创建一个PromptOptions<TResult>的新实例并将其传递给ShowPromptAsync。

示例：

首先创建一个值类型来定义返回值：

public enum TokenThemeResult
{
  None,
  Solarized,
  OneDark,
  GruvBox,
}

然后创建 PromptOptions<TResult> 实例并将其传递给 ShowPromptAsync 以及必需的 message 及 cancellationToken 参数。

通过设置 Title 和 Icon 属性来自定义标题和图标。

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken ct)
{
  // Custom prompt
  Systems selectedSystem = await shell.ShowPromptAsync(
      "Select the system to configure:",
      new PromptOptions<Systems>
      {
          Choices =
          {
              { "Core", Systems.CoreSystem },
              { "Auxiliary", Systems.AuxiliarySystem },
              { "Monitoring", Systems.MonitoringSystem },
          },
          DismissedReturns = Systems.CoreSystem,
          DefaultChoiceIndex = 2
          Title = "Configuration Assistant",
          Icon = ImageMoniker.KnownValues.Settings,
      },
      cancellationToken);

  Debug.WriteLine($"Selected system: {selectedSystem}");
}

该 Choices 集合将用户选择映射到自定义 Systems 枚举中的值。 如果用户选择 “关闭 ”按钮， DismissedReturns 则设置返回的值。 DefaultChoiceIndex 是集合中 Choices 定义默认选项的从零开始的索引。

创建输入提示

string? projectName = await shell.ShowPromptAsync(
    "Enter the name of the project to configure?",
    InputPromptOptions.Default with { Title = "Configuration Assistant" },
    cancellationToken);

除了自定义图标（如选择提示）外，输入提示还支持默认值。 设置 DefaultText 实例上的 InputPromptOptions 属性。

如果用户选择 “取消 ”按钮、要关闭的 “关闭 ”按钮或 Esc 键，则返回值为 null。 如果用户将输入留空并选择 “确定 ”按钮或 Enter 键，则返回值为空字符串。

否则，返回值是在用户确认输入时输入的内容。

相关内容

以下示例演示如何使用用户提示：

• UserPromptSample
• MarkdownLinter