Condividi tramite

Creare dialoghi modali nelle estensioni

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

Le finestre di dialogo modali offrono un modo efficace per creare esperienze utente incentrate nelle estensioni di Azure DevOps. Il servizio di dialogo consente di presentare una finestra di dialogo modale che blocca l'interazione dell'utente con l'intera interfaccia di Azure DevOps fino a quando la finestra di dialogo non viene chiusa. Questa azione garantisce che gli utenti completino attività importanti o forniscano informazioni necessarie.

Usare finestre di dialogo modali nelle estensioni per:

  • Raccogliere l'input dell'utente tramite moduli
  • Visualizzare i messaggi di conferma per le azioni critiche
  • Mostra informazioni dettagliate che richiedono l'attenzione dell'utente
  • Guidare gli utenti attraverso processi in più passaggi

Importante

Quando si creano finestre di dialogo modali, bloccano l'interazione con l'intera pagina di Azure DevOps, non solo con l'estensione. Questo approccio offre un'esperienza modale reale, ma è consigliabile usarla in modo ponderato per evitare di interrompere il flusso di lavoro dell'utente.

Prerequisiti

Categoria Requisito Dettagli
Configurazione dell'estensione Progetto di estensione funzionante Un file manifest valido vss-extension.json
Registrazione al Marketplace Estensione registrata in Visual Studio Marketplace per test e distribuzione
Conoscenza dello sviluppo Informazioni sui principi fondamentali dello sviluppo di estensioni per Azure DevOps
Ambiente di sviluppo Node.js e npm Node.js versione 14 o successiva con npm installato
Editor di codice Visual Studio Code o altri IDE consigliati
Accesso ad Azure DevOps Accesso a un'organizzazione di Azure DevOps per i test
Pacchetti obbligatori SDK dell'estensione Installare: npm install azure-devops-extension-sdk
API di estensione Installare: npm install azure-devops-extension-api
Autorizzazioni di estensione Ambiti del manifesto Includere ambiti appropriati in vss-extension.json, ad esempio : "vso.work", "vso.project"
Importazioni dell'SDK Moduli obbligatori Importare SDK e servizi: import * as SDK from "azure-devops-extension-sdk"

Contenuto della finestra di dialogo

Per iniziare, dichiarare un contributo di tipo ms.vss-web.control nel manifesto dell'estensione. Questo contributo rappresenta il contenuto visualizzato all'interno della finestra di dialogo.

    {
        "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 proprietà fa riferimento a una pagina di cui viene eseguito il rendering all'interno dell'area del contenuto della finestra di dialogo:

<!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>

Visualizzare la finestra di dialogo

Per visualizzare la finestra di dialogo, ad esempio quando un utente seleziona un'azione su una barra degli strumenti o un menu, chiamare la openDialog funzione in un'istanza del servizio della finestra di dialogo:

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

Funzionalità avanzate dei dialoghi

Una funzione può essere chiamata quando è selezionato il pulsante OK. Questa funzione viene specificata impostando getDialogResult nelle opzioni fornite quando si mostra la finestra di dialogo.

Se una chiamata a getDialogResult restituisce un valore non Null, questo valore viene quindi passato alla funzione specificata da okCallback (anche nelle opzioni) e la finestra di dialogo viene chiusa.

In questo esempio, il attachFormChanged callback viene chiamato quando cambiano gli input nel modulo. In base al fatto che il modulo sia valido o meno, il pulsante OK è abilitato o disabilitato.

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

Controllare il pulsante OK

Inizialmente, il pulsante OK è disabilitato. Tuttavia, è possibile abilitare/disabilitare questo pulsante chiamando il updateOkButton metodo nella finestra di dialogo:

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

Passare valori alla finestra di dialogo

È possibile passare i valori iniziali al contenuto della finestra di dialogo quando lo si apre nella finestra di dialogo host.

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

Quando si apre la finestra di dialogo, è necessario specificare le opzioni seguenti per passare myId:

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

Personalizzare i pulsanti della finestra di dialogo

Gli okText attributi e cancelText possono essere usati per specificare titoli alternativi per i pulsanti OK e Annulla:

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

Per non visualizzare pulsanti nella finestra di dialogo, è possibile impostare l'attributo buttons su []:

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

Se si ha una domanda o si stanno cercando altre informazioni, prendere in considerazione una delle aree seguenti:

  • Last updated on