Utiliser des boîtes de dialogue dans des onglets

Article
02/02/2024

Ajoutez des boîtes de dialogue modales (appelées modules de tâche dans TeamsJS v1.x) à vos onglets pour simplifier l’expérience utilisateur pour tous les flux de travail qui nécessitent une entrée de données. Les boîtes de dialogue vous permettent de collecter des entrées utilisateur dans une fenêtre modale Microsoft Teams-Aware, comme la modification des cartes du Planificateur. Vous pouvez utiliser des boîtes de dialogue pour créer une expérience similaire.

Les deux opérations main des dialogues impliquent leur ouverture et leur fermeture (envoi). Les fonctions sont légèrement différentes pour les versions antérieures (antérieures à v2.x.x) de la bibliothèque TeamsJS :

TeamsJs v2
TeamsJs v1

// Open HTML dialog
microsoftTeams.dialog.url.open(
    urlDialogInfo: UrlDialogInfo, 
       submitHandler?: DialogSubmitHandler, 
       messageFromChildHandler?: PostMessageChannel
): void;

// Open Adaptive Card dialog
microsoftTeams.dialog.adaptiveCard.open(
    adaptiveCardDialogInfo: AdaptiveCardDialogInfo,
    submitHandler?: DialogSubmitHandler
): void;

// Submit HTML dialog (AC dialogs send result from Action.Submit)
   microsoftTeams.dialog.url.submit(
    result?: string | any,
    appIds?: string | string[]
): void;

Remarque

La dialog.submit propriété ne peut être appelée que dans une boîte de dialogue.

// Same function is used for both HTML and Adaptive Card dialogs.
microsoftTeams.tasks.startTask(
    taskInfo: TaskInfo,
    submitHandler?: (err: string, result: string | any) => void
): void;

// Only works for HTML dialogs (AC dialogs send result from Action.Submit)
microsoftTeams.tasks.submitTask(
    result?: string | any,
    appIds?: string | string[]
): void;

Les sections suivantes expliquent le processus d’appel d’une boîte de dialogue à partir d’un onglet et d’envoi du résultat.

Appeler une boîte de dialogue à partir d’un onglet

Remarque

À compter de TeamsJS v2.8.x, l’espace de noms prend en charge les dialog dialogues basés sur une carte adaptative. L’espace tasks de noms est toujours pris en charge pour la compatibilité descendante, mais la meilleure pratique consiste à mettre à jour tasks.startTask() l’appel vers dialog.url.open ou dialog.adaptiveCard.open pour les dialogues html et de carte adaptative, respectivement. Pour plus d’informations, consultez l’espace de noms de la boîte de dialogue.

Vous pouvez appeler une boîte de dialogue HTML ou carte adaptative à partir d’un onglet.

Boîte de dialogue HTML

 microsoftTeams.dialog.url.open(urlDialogInfo, submitHandler);

La valeur de UrlDialogInfo.url est définie sur l’emplacement du contenu de votre boîte de dialogue. La fenêtre de boîte de dialogue s’ouvre et UrlDialogInfo.url est chargée en tant qu’élément <iframe> à l’intérieur. JavaScript dans la page de boîte de dialogue appelle microsoftTeams.app.initialize(). S’il existe une submitHandler fonction sur la page et qu’il y a une erreur lors de l’appel microsoftTeams.dialog.url.open()de , submitHandler est appelé avec err défini sur la chaîne d’erreur indiquant la même chose.

Avertissement

Les services cloud de Microsoft, y compris les versions web des domaines Teams (teams.microsoft.com), Outlook (outlook.com) et Microsoft 365 (microsoft365.com) migrent vers le domaine cloud.microsoft . Effectuez les étapes suivantes avant juin 2024 pour vous assurer que votre application continue à s’afficher sur le client web Teams :

Mettez à jour le Kit de développement logiciel (SDK) TeamsJS vers la version 2.19.0 ou une version ultérieure. Pour plus d’informations sur la dernière version du Kit de développement logiciel (SDK) TeamsJS, consultez Bibliothèque de client JavaScript Microsoft Teams.
Mettez à jour vos en-têtes de stratégie de sécurité de contenu dans votre application Teams pour permettre à votre application d’accéder au domaine teams.cloud.microsoft . Si votre application Teams s’étend sur Outlook et Microsoft 365, veillez à autoriser votre application à accéder aux domaines teams.cloud.microsoft, outlook.cloud.microsoft et m365.cloud.microsoft .

Boîte de dialogue Carte adaptative

 microsoftTeams.dialog.adaptiveCard.open(adaptiveCardDialogInfo, submitHandler);

La valeur de adaptiveCardDialogInfo.card est le JSON pour une carte adaptative. Vous pouvez spécifier un submitHandler à appeler avec une chaîne d’erreur , s’il y a eu une erreur lors de l’appel open() ou si l’utilisateur ferme la boîte de dialogue à l’aide du bouton X (Quitter).

La section suivante donne un exemple d’appel d’un dialogue.

Exemple d’appel d’une boîte de dialogue

L’image suivante affiche la boîte de dialogue :

Formulaire personnalisé du module de tâches

Le code suivant est adapté à partir de l’exemple de boîte de dialogue :

TeamsJs v2
TeamsJs v1

let urlDialogInfo = {
    title: null,
    height: null,
    width: null,
    url: null,
    fallbackUrl: null,
};

urlDialogInfo.url = "https://contoso.com/teamsapp/customform";
urlDialogInfo.title = "Custom Form";
urlDialogInfo.height = 510;
urlDialogInfo.width = 430;
submitHandler = (submitHandler) => {
        console.log(`Submit handler - err: ${submitHandler.err}`);
        alert("Result = " + JSON.stringify(submitHandler.result) + "\nError = " + JSON.stringify(submitHandler.err));
    };

 microsoftTeams.dialog.url.open(urlDialogInfo, submitHandler);

let taskInfo = {
    title: null,
    height: null,
    width: null,
    url: null,
    card: null,
    fallbackUrl: null,
    completionBotId: null,
};

taskInfo.url = "https://contoso.com/teamsapp/customform";
taskInfo.title = "Custom Form";
taskInfo.height = 510;
taskInfo.width = 430;
submitHandler = (err, result) => {
    console.log(`Submit handler - err: ${err}`);
    console.log(`Submit handler - result\rName: ${result.name}\rEmail: ${result.email}\rFavorite book: ${result.favoriteBook}`);
};
microsoftTeams.tasks.startTask(taskInfo, submitHandler);

le submitHandler renvoie les valeurs de err ou result à la console.

Envoyer le résultat d’une boîte de dialogue

En cas d’erreur lors de l’appel de la boîte de dialogue, votre submitHandler fonction est immédiatement appelée avec une err chaîne indiquant l’erreur qui s’est produite. La submitHandler fonction est également appelée avec une err chaîne lorsque l’utilisateur sélectionne X dans la boîte de dialogue à quitter.

S’il n’y a pas d’erreur d’appel et que l’utilisateur ne sélectionne pas X pour ignorer la boîte de dialogue, l’utilisateur sélectionne un bouton Envoyer quand il a terminé. Les sections suivantes expliquent ce qui se passe ensuite pour les types de dialogue html et carte adaptative.

Boîtes de dialogue HTML ou JavaScript

Après avoir validé l’entrée utilisateur, appelez microsoftTeams.dialog.url.submit(). Vous pouvez appeler submit() sans paramètre si vous souhaitez que Teams ferme la boîte de dialogue, ou vous pouvez transmettre un objet ou une chaîne result à votre application en tant que premier paramètre, et un appId de l’application qui a ouvert la boîte de dialogue en tant que deuxième paramètre. Si vous appelez submit() avec un result paramètre, vous devez passer un appId (ou un tableau de appId chaînes d’applications autorisées à recevoir le résultat de la boîte de dialogue). Cette action permet à Teams de vérifier que l’application qui envoie le résultat est identique à la boîte de dialogue appelée.

Teams appelle ensuite votre submitHandler où err est null et result est l’objet ou la chaîne que vous avez passé à submit().

Boîtes de dialogue carte adaptative

Lorsque vous appelez la boîte de dialogue avec un submitHandler et que l’utilisateur sélectionne un Action.Submit bouton, les valeurs du carte sont retournées en tant qu’objet data . Si l’utilisateur appuie sur la touche Échap ou sélectionne X pour quitter la boîte de dialogue, votre submitHandler est appelé avec la err chaîne . Si votre application contient un bot en plus d’un onglet, vous pouvez inclure le appId du bot comme valeur de completionBotId dans l’objet TaskInfo (BotAdaptiveCardDialogInfo).

Le corps de la carte adaptative tel que rempli par l’utilisateur est envoyé au bot à l’aide d’un message task/submit invoke lorsque l’utilisateur sélectionne un bouton Action.Submit. Le schéma de l’objet que vous recevez est similaire au schéma que vous recevez pour les messages de tâche/extraction et de tâche/envoi. La seule différence est que le schéma de l’objet JSON est un objet de carte adaptative par opposition à un objet contenant un objet de carte adaptative comme lorsque les cartes adaptatives sont utilisées avec des bots.

Le code suivant est l’exemple de charge utile :

{
  "task": {
    "type": "continue",
    "value": {
      "title": "Title",
      "height": "height",
      "width": "width",
      "url": null,
      "card": "Adaptive Card or Adaptive Card bot card attachment",
      "fallbackUrl": null,
      "completionBotID": "bot App ID"
    }
  }
}

Le code suivant est l’exemple de demande d’appel :

let adaptiveCardDialogInfo = {
    title: "Dialog Demo",
    height: "medium",
    width: "medium",
    card: null,
    fallbackUrl: null,
    completionBotId: null,
};

adaptiveCardDialogInfo.card = {
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
        {
            "type": "TextBlock",
            "text": "This is a sample adaptive card.",
            "wrap": true
        }
    ]
}

submitHandler = (err, result) => {
    console.log(`Submit handler - err: ${err}`);
    alert(
        "Result = " + JSON.stringify(result) + "\nError = " + JSON.stringify(err)
    );
};

microsoftTeams.dialog.adaptiveCard.open(adaptiveCardDialogInfo, submitHandler);

La section suivante fournit un exemple d’envoi du résultat d’un dialogue (appelé module de tâche dans TeamsJS v1.x).

Exemple d’envoi du résultat d’un dialogue

Pour reprendre l’exemple précédent d’appel d’un dialogue HTML, voici un exemple de formulaire HTML incorporé dans la boîte de dialogue :

<form method="POST" id="customerForm" action="/register" onSubmit="return validateForm()">

Il existe cinq champs sur ce formulaire, mais cet exemple ne nécessite que trois valeurs, name, emailet favoriteBook.

Le code suivant fournit un exemple de la fonction validateForm() qui appelle submit() :

function validateForm() {
    var customerInfo = {
        name: document.forms["customerForm"]["name"].value,
        email: document.forms["customerForm"]["email"].value,
        favoriteBook: document.forms["customerForm"]["favoriteBook"].value
    }
    microsoftTeams.dialog.url.submit(customerInfo, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
    return true;
}

Erreurs d’appel de boîte de dialogue

Remarque

L’espace tasks de noms est remplacé par l’espace de dialog noms . L’espace dialog de noms inclut des sous-espaces de noms pour les fonctionnalités HTML (url), Carte adaptative (adaptiveCard) et bot (dialog.url.bot et dialog.adaptiveCard.bot).

Le tableau suivant fournit les valeurs possibles de err que votre submitHandler reçoit :

Problème	Message d’erreur qui est la valeur de `err`
Les valeurs pour `TaskInfo.url` et `TaskInfo.card` ont été spécifiées.	Les valeurs de carte et d’URL ont été spécifiées. L’un ou l’autre, mais pas les deux, sont autorisés.
`TaskInfo.url` et `TaskInfo.card` spécifié.	Vous devez spécifier une valeur pour la carte ou l’URL.
`appId` non valide.	ID d'application non valide.
L’utilisateur a sélectionné le bouton X, en le fermant.	L’utilisateur a annulé ou fermé la boîte de dialogue.

Exemple de code

Exemple de nom	Description	.NET	Node.js	Manifeste
Exemple de boîte de dialogue bots-V4	Cet exemple montre comment créer des boîtes de dialogue à l’aide de bot framework v4 et des onglets Teams.	View	View	View

Étape suivante

Utilisation de boîtes de dialogue à partir de bots

Utiliser des boîtes de dialogue dans des onglets

Appeler une boîte de dialogue à partir d’un onglet

Boîte de dialogue HTML

Boîte de dialogue Carte adaptative

Exemple d’appel d’une boîte de dialogue

Envoyer le résultat d’une boîte de dialogue

Boîtes de dialogue HTML ou JavaScript

Boîtes de dialogue carte adaptative

Exemple d’envoi du résultat d’un dialogue

Erreurs d’appel de boîte de dialogue

Exemple de code

Étape suivante

Voir aussi

Commentaires

Ressources supplémentaires