Partager via

Créer des dialogues modals dans les extensions

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Les boîtes de dialogue modales offrent un moyen puissant de créer des expériences utilisateur ciblées dans les extensions Azure DevOps. Le service de dialogue vous permet de présenter un dialogue modal qui bloque l’interaction utilisateur avec l’ensemble de l’interface Azure DevOps jusqu’à ce que la boîte de dialogue soit ignorée. Cette action garantit que les utilisateurs effectuent des tâches importantes ou fournissent des informations requises.

Utilisez des boîtes de dialogue modales dans vos extensions pour :

  • Collecter des entrées utilisateur via des formulaires
  • Afficher les messages de confirmation pour les actions critiques
  • Afficher des informations détaillées qui nécessitent une attention de l’utilisateur
  • Guider les utilisateurs par le biais de processus en plusieurs étapes

Importante

Lorsque vous créez des dialogues modals, ils bloquent l’interaction avec l’ensemble de la page Azure DevOps, et pas seulement votre extension. Cette approche offre une véritable expérience modale, mais vous devez l’utiliser de manière réfléchie pour éviter de perturber le flux de travail utilisateur.

Conditions préalables

Catégorie Besoin Détails
Configuration de l’extension Projet d'extension en cours Fichier manifeste vss-extension.json valide
Inscription au marché Extension inscrite auprès de Visual Studio Marketplace pour le test et le déploiement
Connaissances sur le développement Présentation des principes de base du développement d’extensions Azure DevOps
environnement de développement Node.js et npm Node.js version 14 ou ultérieure avec npm installé
Éditeur de code Visual Studio Code ou un autre IDE recommandé
Accès à « Azure DevOps » Accès à une organisation Azure DevOps à des fins de test
Packages requis Kit de développement logiciel (SDK) d'extension Installer : npm install azure-devops-extension-sdk
API d’extension Installer : npm install azure-devops-extension-api
Autorisations d’extension Étendues du manifeste Incluez les étendues appropriées dans vss-extension.json, par exemple : "vso.work""vso.project"
Importations du Kit de développement logiciel (SDK Modules obligatoires Importer le KIT SDK et les services : import * as SDK from "azure-devops-extension-sdk"

Contenu de la boîte de dialogue

Pour commencer, déclarez une contribution de type ms.vss-web.control dans votre manifeste d’extension. Cette contribution représente le contenu affiché dans la boîte de dialogue.

    {
        "id": "registration-form",
        "type": "ms.vss-web.control",
        "description": "The content to be displayed in the dialog",
        "targets": [],
        "properties": {
            "uri": "registration-form.html"
        }
    }

La uri propriété fait référence à une page qui est affichée dans la zone de contenu de la boîte de dialogue :

<!DOCTYPE html>
<html>
    <head>
        <script src="node_modules/azure-devops-extension-sdk/lib/SDK.js"></script>
    </head>
    <body>
        <h2 id="header">Register now</h2>
        <p>
            <label>Name:</label>
            <input id="inpName" />
        </p>
        <p>
            <label>Date of birth:</label>
            <input id="inpDob" />
        </p>
        <p>
            <label>Email address:</label>
            <input id="inpEmail" />
        </p>
        <script type="module">
            import * as SDK from "azure-devops-extension-sdk";
            
            SDK.init();
            const registrationForm = (function() {
                const callbacks = [];
                
                function inputChanged() {
                    // Execute registered callbacks
                    for(let i = 0; i < callbacks.length; i++) {
                        callbacks[i](isValid());
                    }
                }
                
                function isValid() {
                    // Check whether form is valid or not
                    return !!(name.value) && !!(dateOfBirth.value) && !!(email.value);
                }
                
                function getFormData() {
                    // Get form values
                    return {
                        name: name.value,
                        dateOfBirth: dateOfBirth.value,
                        email: email.value  
                    };
                }

                const name = document.getElementById("inpName");
                const dateOfBirth = document.getElementById("inpDob");
                const email = document.getElementById("inpEmail");
                
                name.addEventListener("change", inputChanged);
                dateOfBirth.addEventListener("change", inputChanged);
                email.addEventListener("change", inputChanged);
                
                return {
                    isFormValid: function() {
                        return isValid();   
                    },
                    getFormData: function() {
                        return getFormData();
                    },
                    attachFormChanged: function(cb) {
                         callbacks.push(cb);
                    }
                };
            })();
            
            // Register form object to be used across this extension
            SDK.register("registration-form", registrationForm);
        </script>
    </body>
</html>

Afficher la boîte de dialogue

Pour afficher la boîte de dialogue (par exemple, quand un utilisateur sélectionne une action dans une barre d’outils ou un menu), appelez la openDialog fonction sur une instance du service de dialogue :

import * as SDK from "azure-devops-extension-sdk";

SDK.getService(SDK.CommonServiceIds.Dialog).then((dialogService) => {
    const extensionCtx = SDK.getExtensionContext();
    // Build absolute contribution ID for dialogContent
    const contributionId = `${extensionCtx.publisherId}.${extensionCtx.extensionId}.registration-form`;

    // Show dialog
    const dialogOptions = {
        title: "My Dialog",
        width: 800,
        height: 600
    };

    dialogService.openDialog(contributionId, dialogOptions);
});

Fonctionnalités avancées de boîte de dialogue

Une fonction peut être appelée lorsque le bouton OK est sélectionné. Vous spécifiez cette fonction en définissant getDialogResult dans les options que vous fournissez lors de l’affichage de la boîte de dialogue.

Si un appel à getDialogResult retourne une valeur non null, cette valeur est ensuite passée à la fonction spécifiée par okCallback (également dans les options) et la boîte de dialogue est fermée.

Dans cet exemple, le attachFormChanged rappel est appelé lorsque les entrées sur le formulaire changent. Selon que le formulaire est valide ou non, le bouton OK est activé ou désactivé.

import * as SDK from "azure-devops-extension-sdk";

SDK.getService(SDK.CommonServiceIds.Dialog).then((dialogService) => {
    let registrationForm;
    const extensionCtx = SDK.getExtensionContext();
    const contributionId = `${extensionCtx.publisherId}.${extensionCtx.extensionId}.registration-form`;

    const dialogOptions = {
        title: "Registration Form",
        width: 800,
        height: 600,
        getDialogResult: () => {
            // Get the result from registrationForm object
            return registrationForm ? registrationForm.getFormData() : null;
        },
        okCallback: (result) => {
            // Log the result to the console
            console.log(JSON.stringify(result));
        }
    };

    dialogService.openDialog(contributionId, dialogOptions).then((dialog) => {
        // Get registrationForm instance which is registered in registration-form.html
        dialog.getContributionInstance("registration-form").then((registrationFormInstance) => {
        
            // Keep a reference of registration form instance (to be used previously in dialog options)
            registrationForm = registrationFormInstance;
            
            // Subscribe to form input changes and update the Ok enabled state
            registrationForm.attachFormChanged((isValid) => {
                dialog.updateOkButton(isValid);
            });
            
            // Set the initial ok enabled state
            registrationForm.isFormValid().then((isValid) => {
                dialog.updateOkButton(isValid);
            });
        });                            
    });
});

Contrôler le bouton OK

Initialement, le bouton OK est désactivé. Toutefois, vous pouvez activer/désactiver ce bouton en appelant la updateOkButton méthode dans la boîte de dialogue :

    dialogService.openDialog(contributionId, dialogOptions).then((dialog) => {
        // Set true/false to enable/disable ok button
        dialog.updateOkButton(true); 
    });

Transmettre des valeurs à la boîte de dialogue

Il est possible de transmettre des valeurs initiales au contenu de boîte de dialogue lorsque vous l’ouvrez dans la boîte de dialogue hôte.

    {
        "id": "registration-form",
        "type": "ms.vss-web.control",
        "description": "The content displayed in the dialog",
        "targets": [],
        "properties": {
            "uri": "registration-form.html?id={{myId}}"
        }
    }

Lorsque la boîte de dialogue s’ouvre, les options suivantes myId doivent être spécifiées pour passer :

    const dialogOptions = {
        title: "My Dialog Title",
        width: 800,
        height: 600,
        urlReplacementObject: { myId: new Date().getTime() }
    };

Personnaliser les boutons de boîte de dialogue

Les okText attributs et cancelText peuvent être utilisés pour spécifier d’autres titres pour les boutons OK et Annuler :

    const dialogOptions = {
        title: "My Dialog Title",
        width: 800,
        height: 600,
        okText: "Yes",
        cancelText: "No" 
    };

Pour ne pas afficher de boutons dans la boîte de dialogue, vous pouvez définir l’attribut sur buttons[]:

    const dialogOptions = {
        title: "My Dialog Title",
        width: 800,
        height: 600,
        buttons: []
    };

Si vous avez une question ou si vous recherchez plus d’informations, envisagez d’accéder à l’un des domaines suivants :

  • Last updated on