Freigeben über

Erstellen von modalen Dialogfeldern in Erweiterungen

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

Modale Dialogfelder bieten eine leistungsstarke Möglichkeit, fokussierte Benutzeroberflächen in Azure DevOps-Erweiterungen zu erstellen. Mit dem Dialogdienst können Sie ein modales Dialogfeld präsentieren, das die Benutzerinteraktion mit der gesamten Azure DevOps-Schnittstelle blockiert, bis das Dialogfeld geschlossen wird. Diese Aktion stellt sicher, dass Benutzer wichtige Aufgaben ausführen oder erforderliche Informationen bereitstellen.

Verwenden Sie modale Dialogfelder in Ihren Erweiterungen, um:

  • Sammeln von Benutzereingaben über Formulare
  • Anzeigen von Bestätigungsmeldungen für kritische Aktionen
  • Detaillierte Informationen anzeigen, die die Aufmerksamkeit des Benutzers erfordern
  • Führen Sie Die Benutzer durch mehrstufige Prozesse

Von Bedeutung

Wenn Sie modale Dialogfelder erstellen, blockieren sie die Interaktion mit der gesamten Azure DevOps-Seite, nicht nur Ihrer Erweiterung. Dieser Ansatz bietet eine echte modale Oberfläche, aber Sie sollten es überlegt verwenden, um zu vermeiden, dass der Benutzerworkflow gestört wird.

Voraussetzungen

Kategorie Anforderung Einzelheiten
Erweiterungseinrichtung Projekt zur Arbeitserweiterung Eine gültige vss-extension.json Manifestdatei
Marketplace-Registrierung Erweiterung, die bei Visual Studio Marketplace für Tests und Bereitstellung registriert ist
Entwicklungswissen Grundlegendes zur Entwicklung von Azure DevOps-Erweiterungen
Entwicklungsumgebung Node.js und npm Node.js Version 14 oder höher mit installierter npm
Code-Editor Visual Studio Code oder andere empfohlene IDE
Azure DevOps-Zugriff Zugriff auf eine Azure DevOps-Organisation zum Testen
Erforderliche Pakete Erweiterungs-SDK Installieren: npm install azure-devops-extension-sdk
Erweiterungs-API Installieren: npm install azure-devops-extension-api
Erweiterungsberechtigungen Reservierungsumfang des Manifests Fügen Sie entsprechende Bereiche in vss-extension.json, z. B.: "vso.work", "vso.project"
SDK-Importe Erforderliche Module Sdk und Dienste importieren: import * as SDK from "azure-devops-extension-sdk"

Inhalt des Dialogfelds

Deklarieren Sie zunächst einen Beitrag vom Typ ms.vss-web.control in Ihrem Erweiterungsmanifest. Dieser Beitrag stellt den Inhalt dar, der im Dialogfeld angezeigt wird.

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

Die uri -Eigenschaft verweist auf eine Seite, die im Inhaltsbereich des Dialogfelds gerendert wird:

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

Dialogfeld anzeigen

Um das Dialogfeld anzuzeigen (z. B. wenn ein Benutzer eine Aktion auf einer Symbolleiste oder einem Menü auswählt), rufen Sie die openDialog Funktion in einer Instanz des Dialogdiensts auf:

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

Erweiterte Dialogfeldfunktionen

Eine Funktion kann aufgerufen werden, wenn die Schaltfläche OK ausgewählt ist. Sie geben diese Funktion an, indem Sie getDialogResult in den Optionen festlegen, die Sie beim Anzeigen des Dialogfelds bereitstellen.

Wenn ein Aufruf von getDialogResult einen Wert ungleich NULL zurückgibt, wird dieser Wert an die von okCallback angegebene Funktion (auch in den Optionen) übergeben, und das Dialogfeld wird geschlossen.

In diesem Beispiel wird der attachFormChanged Rückruf aufgerufen, wenn sich Eingaben im Formular ändern. Basierend darauf, ob das Formular gültig ist oder nicht, ist die Schaltfläche "OK" aktiviert oder deaktiviert.

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

Steuern der Schaltfläche "OK"

Zunächst ist die Schaltfläche OK deaktiviert. Sie können diese Schaltfläche jedoch aktivieren/deaktivieren, indem Sie die updateOkButton -Methode im Dialogfeld aufrufen:

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

Übergeben von Werten an das Dialogfeld

Beim Öffnen des Host-Dialogs können Anfangswerte an Dialoginhalte übergeben werden.

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

Wenn das Dialogfeld geöffnet wird, müssen die folgenden Optionen angegeben werden, um folgendes zu übergeben myId:

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

Dialogfeldschaltflächen anpassen

Die okText Attribute und cancelText können verwendet werden, um alternative Titel für die Schaltflächen OK und Abbrechen anzugeben:

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

Um keine Schaltflächen im Dialogfeld anzuzeigen, können Sie das buttons Attribut auf []festlegen:

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

Wenn Sie eine Frage haben oder nach weiteren Informationen suchen, sollten Sie zu einem der folgenden Bereiche wechseln:

  • Last updated on