Udostępnij przez

Tworzenie modalnych okien dialogowych w rozszerzeniach

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

Modalne okna dialogowe zapewniają zaawansowany sposób tworzenia skoncentrowanych środowisk użytkownika w rozszerzeniach usługi Azure DevOps. Usługa okna dialogowego umożliwia wyświetlenie modalnego okna dialogowego, które blokuje interakcję użytkownika z całym interfejsem usługi Azure DevOps, dopóki okno dialogowe nie zostanie odrzucone. Ta akcja gwarantuje, że użytkownicy wykonują ważne zadania lub dostarczają wymagane informacje.

Użyj modalnych okien dialogowych w swoich rozszerzeniach, aby:

  • Zbieranie danych wejściowych użytkownika za pomocą formularzy
  • Wyświetlanie komunikatów potwierdzenia dla akcji krytycznych
  • Pokaż szczegółowe informacje, które wymagają uwagi użytkownika
  • Przeprowadzanie użytkowników przez procesy wieloetapowe

Ważne

Podczas tworzenia modalnych okien dialogowych blokują interakcję z całą stroną usługi Azure DevOps, a nie tylko z rozszerzeniem. Takie podejście zapewnia prawdziwe środowisko modalne, ale należy użyć go przemyślanie, aby uniknąć zakłócania przepływu pracy użytkownika.

Wymagania wstępne

Kategoria Wymaganie Szczegóły
Konfiguracja rozszerzenia Roboczy projekt rozszerzenia Prawidłowy vss-extension.json plik manifestu
Rejestracja w witrynie Marketplace Rozszerzenie zarejestrowane w witrynie Visual Studio Marketplace na potrzeby testowania i wdrażania
Wiedza o rozwoju Omówienie podstaw programowania rozszerzeń usługi Azure DevOps
środowisko deweloperskie Node.js i npm Node.js w wersji 14 lub nowszej z zainstalowanym programem npm
Edytor kodu Zalecany program Visual Studio Code lub inne środowisko IDE
Dostęp do usługi Azure DevOps Dostęp do organizacji usługi Azure DevOps na potrzeby testowania
Wymagane pakiety SDK rozszerzeń Zainstaluj: npm install azure-devops-extension-sdk
Interfejs API rozszerzenia Zainstaluj: npm install azure-devops-extension-api
Uprawnienia rozszerzenia Zakresy manifestu Uwzględnij odpowiednie zakresy w pliku vss-extension.json, na przykład: "vso.work", "vso.project"
Importowanie zestawu SDK Wymagane moduły Importowanie zestawu SDK i usług: import * as SDK from "azure-devops-extension-sdk"

Zawartość okna dialogowego

Aby rozpocząć, zadeklaruj udział typu ms.vss-web.control w manifeście rozszerzenia. Ten wkład reprezentuje zawartość wyświetlaną w oknie dialogowym.

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

Właściwość uri odwołuje się do strony renderowanej w obszarze zawartości okna dialogowego:

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

Pokaż okno dialogowe

Aby wyświetlić okno dialogowe (na przykład gdy użytkownik wybierze akcję na pasku narzędzi lub menu), wywołaj openDialog funkcję w wystąpieniu usługi okna dialogowego:

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

Zaawansowane funkcje okna dialogowego

Funkcję można wywołać po wybraniu przycisku OK. Tę funkcję należy określić, ustawiając getDialogResult w opcjach podanych podczas wyświetlania okna dialogowego.

Jeśli wywołanie metody zwraca getDialogResult wartość inną niż null, ta wartość jest następnie przekazywana do funkcji określonej przez okCallback (również w opcjach), a okno dialogowe zostanie zamknięte.

W tym przykładzie attachFormChanged wywołanie zwrotne jest wywoływane po zmianie danych wejściowych w formularzu. Na podstawie tego, czy formularz jest prawidłowy, czy nie, przycisk OK jest włączony lub wyłączony.

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

Kontrolowanie przycisku OK

Początkowo przycisk OK jest wyłączony. Można jednak włączyć/wyłączyć ten przycisk, wywołując metodę updateOkButton w oknie dialogowym:

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

Przekazywanie wartości do okna dialogowego

Istnieje możliwość przekazania początkowych wartości do zawartości okna dialogowego po otwarciu jej w oknie dialogowym hosta.

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

Po otwarciu okna dialogowego należy określić następujące opcje, aby przekazać myId.

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

Dostosowywanie przycisków okien dialogowych

Atrybuty okText i cancelText mogą służyć do określania alternatywnych tytułów przycisków OK i Anuluj:

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

Aby nie wyświetlać żadnych przycisków w oknie dialogowym, możesz ustawić buttons atrybut na []:

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

Jeśli masz pytanie lub szukasz więcej informacji, rozważ przejście do jednego z następujących obszarów:

  • Last updated on