Creare dialoghi modali nelle estensioni

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

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

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

Il file JavaScript corrispondente (registration-form.js) inizializza l'SDK, recupera tutte le configurazioni passate dall'host e chiama SDK.notifyLoadSucceeded() quando è pronto:

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

Annotazioni

Impacchetta il tuo JavaScript con uno strumento come webpack in modo che l'istruzione import venga risolta correttamente in fase di runtime. La pagina HTML fa riferimento al file di output in bundle , ad esempio registration-form.js.

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 il openCustomDialog metodo in 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);
        }
    }
});

Gestire i risultati della finestra di dialogo

Il onClose callback nelle opzioni della finestra di dialogo riceve il risultato quando la finestra di dialogo viene chiusa. Usare l'opzione configuration per passare i dati iniziali al contenuto della finestra di dialogo.

In questo esempio, la pagina host apre una finestra di dialogo personalizzata e gestisce il risultato quando la finestra di dialogo viene chiusa:

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

Nella pagina del contenuto della finestra di dialogo usare SDK.getConfiguration() per recuperare i dati passati dall'host. La pagina dei contenuti della finestra di dialogo non può comunicare direttamente con l'host, se non tramite il risultato onClose.

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

Visualizzare una finestra di dialogo di messaggio

Per semplici finestre di dialogo di conferma con i pulsanti OK e Annulla, usare openMessageDialog invece di una finestra di dialogo personalizzata:

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

Passare valori alla finestra di dialogo

Passare i valori iniziali al contenuto della finestra di dialogo usando l'opzione configuration . La pagina del contenuto della finestra di dialogo recupera questi valori con 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();
});

Personalizzare i pulsanti della finestra di dialogo

Per le finestre di dialogo dei messaggi, le okText proprietà e cancelText specificano titoli alternativi per i pulsanti OK e Annulla:

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

Abilitare la chiusura della luce

Per le finestre di dialogo personalizzate, impostare lightDismiss su true in modo che selezionare all'esterno della finestra di dialogo la chiuda.

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

Annotazioni

La chiusura della luce è abilitata per impostazione predefinita (true). Impostarlo su false per richiedere all'utente di chiudere in modo esplicito la finestra di dialogo.

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

  • Last updated on