Sdílet prostřednictvím

Vytváření modálních dialogů v rozšířeních

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

Modální dialogy poskytují účinný způsob, jak v rozšířeních Azure DevOps vytvářet zaměřená uživatelská prostředí. Služba dialogových oken umožňuje prezentovat modální dialogové okno, které blokuje interakci uživatele s celým rozhraním Azure DevOps, dokud se dialog neukončí. Tato akce zajistí, že uživatelé dokončí důležité úkoly nebo poskytnou požadované informace.

Pomocí modálních dialogů v rozšířeních můžete:

  • Shromažďování uživatelských vstupů prostřednictvím formulářů
  • Zobrazení potvrzovaných zpráv pro kritické akce
  • Zobrazit podrobné informace, které vyžadují pozornost uživatele
  • Proveďte uživatele vícekrokovými procesy

Důležité

Když vytváříte modální dialogy, blokují interakci s celou stránkou Azure DevOps, nejen s vaším rozšířením. Tento přístup poskytuje skutečné modální prostředí, ale měli byste ho použít promyšleně, abyste se vyhnuli narušení uživatelského pracovního postupu.

Požadavky

Kategorie Požadavek Podrobnosti
Nastavení rozšíření Pracovní projekt rozšíření Platný vss-extension.json soubor manifestu
Registrace tržiště Rozšíření zaregistrované ve Visual Studio Marketplace pro testování a nasazení
Znalosti o vývoji Základní informace o vývoji rozšíření Azure DevOps
vývojového prostředí Node.js a npm Node.js verze 14 nebo novější s nainstalovaným npm
Editor kódu Visual Studio Code nebo jiné doporučené integrované vývojové prostředí (IDE)
Přístup k Azure DevOps Přístup k organizaci Azure DevOps pro testování
Požadované balíčky Rozšiřující SDK Instalovat: npm install azure-devops-extension-sdk
Rozhraní API rozšíření Instalovat: npm install azure-devops-extension-api
Oprávnění rozšíření Rozsahy manifestu Zahrnout příslušné rozsahy do vss-extension.json, například: "vso.work", "vso.project"
Import sady SDK Požadované moduly Import sady SDK a služeb: import * as SDK from "azure-devops-extension-sdk"

Obsah dialogového okna

Začněte tím, že deklarujte příspěvek typu ms.vss-web.control v manifestu rozšíření. Tento příspěvek představuje obsah zobrazený v dialogovém okně.

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

Vlastnost uri odkazuje na stránku, která se vykreslí v oblasti obsahu dialogového okna:

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

Zobrazit dialogové okno

Pokud chcete zobrazit dialogové okno (například když uživatel vybere akci na panelu nástrojů nebo nabídce), zavolejte openDialog funkci v instanci služby dialogového okna:

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

Pokročilé funkce dialogového okna

Funkci lze volat, když je vybráno tlačítko OK. Tuto funkci určíte nastavením getDialogResult v možnostech, které zadáte při zobrazení dialogového okna.

Pokud volání getDialogResult vrátí nenulovou hodnotu, tato hodnota se předá funkci specifikované okCallback (také v možnostech) a dialogové okno se zavře.

V tomto příkladu attachFormChanged se zpětné volání zavolá, když se změní vstupy ve formuláři. Na základě toho, jestli je formulář platný nebo ne, je tlačítko OK povolené nebo zakázané.

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

Ovládání tlačítka OK

Zpočátku je tlačítko OK zakázané. Toto tlačítko ale můžete povolit nebo zakázat voláním updateOkButton metody v dialogovém okně:

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

Předání hodnot do dialogového okna

Při otevření v dialogovém okně hostitele je možné předat počáteční hodnoty obsahu dialogového okna.

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

Po otevření dialogového okna je třeba určit následující možnosti pro předání myId.

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

Přizpůsobení tlačítek dialogového okna

okText Pomocí cancelText atributů můžete zadat alternativní názvy tlačítek OK a Storno:

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

Pokud nechcete v dialogovém okně zobrazovat žádná tlačítka, můžete atribut nastavit buttons na []:

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

Pokud máte dotaz nebo hledáte další informace, zvažte přechod na jednu z následujících oblastí:

  • Last updated on