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 importieren: import * as SDK from "azure-devops-extension-sdk" und Dienste: import { CommonServiceIds, IHostPageLayoutService } from "azure-devops-extension-api"

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></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>
        <div id="root"></div>
        <script type="text/javascript" src="registration-form.js" charset="utf-8"></script>
    </body>
</html>

Die entsprechende JavaScript-Datei (registration-form.js) initialisiert das SDK, ruft alle vom Host übergebenen Konfigurationen ab und ruft nach Bedarf auf SDK.notifyLoadSucceeded() :

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

SDK.init();
SDK.ready().then(() => {
    // Retrieve configuration passed through the dialog options
    const config = SDK.getConfiguration();
    console.log("Dialog configuration:", config);

    SDK.notifyLoadSucceeded();
});

Hinweis

Bündeln Sie Ihr JavaScript mit einem Tool wie webpack, damit die import-Anweisung zur Laufzeit korrekt aufgelöst wird. Die HTML-Seite verweist auf die gebündelte Ausgabedatei (z. B registration-form.js. ).

Dialogfeld anzeigen

Um das Dialogfeld anzuzeigen (z. B. wenn ein Benutzer eine Aktion auf einer Symbolleiste oder einem Menü auswählt), rufen Sie die openCustomDialog Methode auf der IHostPageLayoutService:

import * as SDK from "azure-devops-extension-sdk";
import { CommonServiceIds, IHostPageLayoutService } from "azure-devops-extension-api";

const dialogService = await SDK.getService<IHostPageLayoutService>(CommonServiceIds.HostPageLayoutService);
const extensionCtx = SDK.getExtensionContext();

// Build absolute contribution ID for dialog content
const contributionId = `${extensionCtx.publisherId}.${extensionCtx.extensionId}.registration-form`;

// Show dialog
dialogService.openCustomDialog(contributionId, {
    title: "My Dialog",
    configuration: {
        // Pass initial data to the dialog content
        message: "Please fill out the registration form."
    },
    onClose: (result) => {
        if (result !== undefined) {
            console.log("Dialog result:", result);
        }
    }
});

Dialogergebnisse verarbeiten

Der onClose Callback in den Dialogoptionen erhält das Ergebnis, wenn der Dialog beendet wird. Verwenden Sie die configuration Option, um anfängliche Daten an den Dialoginhalt zu übergeben.

In diesem Beispiel öffnet die Hostseite ein benutzerdefiniertes Dialogfeld und behandelt das Ergebnis, wenn das Dialogfeld geschlossen wird:

import * as SDK from "azure-devops-extension-sdk";
import { CommonServiceIds, IHostPageLayoutService } from "azure-devops-extension-api";

const dialogService = await SDK.getService<IHostPageLayoutService>(CommonServiceIds.HostPageLayoutService);
const extensionCtx = SDK.getExtensionContext();
const contributionId = `${extensionCtx.publisherId}.${extensionCtx.extensionId}.registration-form`;

dialogService.openCustomDialog(contributionId, {
    title: "Registration Form",
    configuration: {
        defaultName: "Contoso User"
    },
    onClose: (result) => {
        if (result !== undefined) {
            // User completed the dialog
            console.log("Registration data:", JSON.stringify(result));
        } else {
            // User dismissed the dialog without completing
            console.log("Dialog was dismissed.");
        }
    }
});

Verwenden Sie SDK.getConfiguration() auf der Dialoginhaltsseite, um die vom Host übergebenen Daten abzurufen. Die Inhaltsseite des Dialogs kann nicht direkt mit dem Host kommunizieren, außer über das onClose Ergebnis:

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

SDK.init();
SDK.ready().then(() => {
    const config = SDK.getConfiguration();
    
    // Use configuration values passed from the host
    if (config.defaultName) {
        document.getElementById("inpName").value = config.defaultName;
    }

    SDK.notifyLoadSucceeded();
});

Anzeigen eines Meldungsdialogfelds

Verwenden Sie openMessageDialog für einfache Bestätigungsdialogfelder mit den Schaltflächen "OK" und "Abbrechen" anstelle eines benutzerdefinierten Dialogfelds:

import * as SDK from "azure-devops-extension-sdk";
import { CommonServiceIds, IHostPageLayoutService } from "azure-devops-extension-api";

const dialogService = await SDK.getService<IHostPageLayoutService>(CommonServiceIds.HostPageLayoutService);

dialogService.openMessageDialog("Are you sure you want to proceed?", {
    title: "Confirm Action",
    showCancel: true,
    onClose: (result) => {
        // result is true if OK was selected, false if Cancel
        if (result) {
            console.log("User confirmed.");
        } else {
            console.log("User canceled.");
        }
    }
});

Übergeben von Werten an das Dialogfeld

Übergeben Sie die Anfangswerte an Dialoginhalte, indem Sie die configuration Option verwenden. Die Dialoginhaltsseite ruft diese Werte mit SDK.getConfiguration().

// Host page: pass configuration when opening the dialog
dialogService.openCustomDialog(contributionId, {
    title: "My Dialog Title",
    configuration: {
        itemId: 42,
        timestamp: new Date().getTime()
    },
    onClose: (result) => {
        if (result !== undefined) {
            console.log("Dialog result:", result);
        }
    }
});

// Dialog content page: retrieve configuration
import * as SDK from "azure-devops-extension-sdk";

SDK.init();
SDK.ready().then(() => {
    const config = SDK.getConfiguration();
    console.log("Item ID:", config.itemId);
    console.log("Timestamp:", config.timestamp);

    SDK.notifyLoadSucceeded();
});

Dialogfeldschaltflächen anpassen

Für Meldungsdialogfelder geben die Eigenschaften okText und cancelText alternative Titel für die Schaltflächen „OK“ und „Abbrechen“ an.

dialogService.openMessageDialog("Do you want to save changes?", {
    title: "Save Changes",
    showCancel: true,
    okText: "Yes",
    cancelText: "No",
    onClose: (result) => {
        if (result) {
            console.log("User selected Yes.");
        }
    }
});

Light Dismiss aktivieren

Legen Sie lightDismiss für benutzerdefinierte Dialogfelder auf true fest, sodass ein Klick außerhalb des Dialogfelds es schließt.

dialogService.openCustomDialog(contributionId, {
    title: "My Dialog Title",
    lightDismiss: true,
    onClose: (result) => {
        console.log("Dialog closed.");
    }
});

Hinweis

"Die Funktion 'Light Dismiss' ist standardmäßig aktiviert (true)." Setzen Sie es auf false, damit der Benutzer das Dialogfeld explizit schließen muss.

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

  • Last updated on