Partager via

Créer des invites utilisateur Visual Studio

  • Article

Les invites utilisateur sont un mécanisme d’interface utilisateur simple permettant d’inviter l’utilisateur à effectuer une sélection. Inviter l’utilisateur à créer une boîte de dialogue avec un message, un à trois boutons pour les choix et un bouton d’abandon.

Remarque

L’interface utilisateur exacte utilisée pour inviter les utilisateurs à changer dans les futures versions en fonction des commentaires des utilisateurs ou d’autres facteurs.

Les exemples courants demandent une confirmation avec une invite OK/Cancel ou demandent à l’utilisateur de choisir parmi un petit ensemble d’options (pas plus de trois).

L’utilisateur a toujours la possibilité d’ignorer l’invite sans effectuer de sélection.

Les choix présentés à l’utilisateur sont mappés pour renvoyer les valeurs du type défini dans le paramètre de TResult type.

Parties d’une invite utilisateur

Screenshot showing the parts of a user prompt.

  1. Message
  2. Boutons de choix
  3. Bouton Ignorer

Bien démarrer

Pour commencer, suivez la section créer le projet dans la section Prise en main.

Utiliser des invites utilisateur

Ce guide décrit les scénarios suivants pour l’utilisation des invites utilisateur :

Afficher une invite d’utilisateur

La création d’une invite utilisateur avec le nouveau modèle d’extensibilité est aussi simple que l’appel de la ShowPromptAsync méthode à partir des helpers ShellExtensibility et la transmission de vos options.

ShellExtensibility.ShowPromptAsync<TResult>()

La méthode ShowPromptAsync accepte trois paramètres :

Paramètre Type Requise Description
message string Oui Texte du message de l’invite.
options PromptOptions<TResult> Oui Définit les choix de l’utilisateur, en les mappant pour retourner des valeurs.
cancellationToken CancellationToken Oui Pour CancellationToken l’opération asynchrone. Lorsqu’elle est déclenchée, l’invite est fermée de force.

Exemple

Le code suivant à l’intérieur d’un affiche Command une invite utilisateur avec un message simple et un bouton OK.

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

Utiliser les options intégrées

Plusieurs ensembles PromptOptions de prédéfinis sont disponibles dans le Kit de développement logiciel (SDK).

OK

Option Par défaut Valeur de retour
« OK » Oui true
Ignorée false

OKCancel

Option Par défaut Valeur de retour
« OK » Oui true
« Annuler » Non false
Ignorée false

RetryCancel

Option Par défaut Valeur de retour
« Réessayer » Oui true
« Annuler » Non false
Ignorée false

Exemple

Screenshot showing a user prompt with OK.

Créez une invite avec un seul choix « OK ».

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

Si l’utilisateur clique sur « OK », ShowPromptAsync retourne true une fois attendu. Si l’utilisateur clique sur le bouton ignorer, il retourne false.

Remplacez le choix par défaut d’une option intégrée par « Annuler »

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

Créer une invite avec des options personnalisées

Screenshot showing a custom user prompt.

Outre les options intégrées, vous pouvez personnaliser les choix présentés à l’utilisateur et la valeur de retour mappée à chacun d’eux.

Au lieu d’utiliser les jeux définis dans PromptOptions, créez une instance de PromptOptions<TResult> et passez-la à ShowPromptAsync.

Exemple

Commencez par créer un type valeur pour définir les valeurs de retour :

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

Ensuite, créez l’instance et transmettez-la PromptOptions<TResult> avec ShowPromptAsync les arguments et cancellationToken les arguments requis message :

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken ct)
{
  // Custom prompt
  var themeResult = await this.Extensibility.Shell().ShowPromptAsync(
    "Which theme should be used for the generated output?",
    new PromptOptions<TokenThemeResult>
    {
      Choices =
      {
        { "Solarized Is Awesome", TokenThemeResult.Solarized },
        { "OneDark Is The Best", TokenThemeResult.OneDark },
        { "GruvBox Is Groovy", TokenThemeResult.GruvBox },
      },
      DismissedReturns = TokenThemeResult.None,
      DefaultChoiceIndex = 2,
    },
    ct);

  Debug.WriteLine($"Selected Token Theme: {themeResult}");
}

La Choices collection mappe les choix utilisateur aux valeurs de l’énumération TokenThemeResult . DismissedReturns définit la valeur retournée si l’utilisateur clique sur le bouton ignorer. DefaultChoiceIndex est un index de base zéro dans la Choices collection qui définit le choix par défaut.

Étapes suivantes

Les exemples suivants montrent comment utiliser les invites utilisateur :