Compartir a través de

Crear diálogos modales en extensiones

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

Los diálogos modales proporcionan una manera eficaz de crear experiencias de usuario centradas en las extensiones de Azure DevOps. El servicio de diálogo permite presentar un diálogo modal que bloquea la interacción del usuario con toda la interfaz de Azure DevOps hasta que se descarta el diálogo. Esta acción garantiza que los usuarios completen tareas importantes o proporcionen información necesaria.

Use diálogos modales en las extensiones para:

  • Recopilar datos de usuario a través de formularios
  • Mostrar mensajes de confirmación para acciones críticas
  • Mostrar información detallada que requiere atención del usuario
  • Guiar a los usuarios a través de procesos de varios pasos

Importante

Al crear diálogos modales, bloquean la interacción con toda la página de Azure DevOps, no solo la extensión. Este enfoque proporciona una experiencia modal verdadera, pero debe usarla cuidadosamente para evitar interrumpir el flujo de trabajo del usuario.

Prerrequisitos

Categoría Requisito Detalles
Configuración de la extensión Proyecto de extensión de trabajo Un archivo de manifiesto válido vss-extension.json
Registro de Marketplace Extensión registrada con Visual Studio Marketplace para pruebas e implementación
Conocimientos de desarrollo Descripción de los conceptos básicos de desarrollo de extensiones de Azure DevOps
Entorno de desarrollo Node.js y npm Node.js versión 14 o posterior con npm instalado
Editor de código Visual Studio Code u otro IDE recomendado
Acceso a Azure DevOps Acceso a una organización de Azure DevOps para pruebas
Paquetes necesarios SDK de extensión Instalar: npm install azure-devops-extension-sdk
API de extensión Instalar: npm install azure-devops-extension-api
Permisos de extensión Ámbitos del manifiesto Incluya los ámbitos adecuados en vss-extension.json, por ejemplo: "vso.work", "vso.project"
Importaciones del SDK Módulos necesarios Importación del SDK y los servicios: import * as SDK from "azure-devops-extension-sdk"

Contenido del cuadro de diálogo

Para empezar, declare una contribución de tipo ms.vss-web.control en el manifiesto de extensión. Esta contribución representa el contenido que se muestra en el cuadro de diálogo.

    {
        "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 propiedad hace referencia a una página que se representa dentro del área de contenido del cuadro de diálogo:

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

Mostrar el cuadro de diálogo

Para mostrar el cuadro de diálogo (por ejemplo, cuando un usuario selecciona una acción en una barra de herramientas o menú), llame a la openDialog función en una instancia del servicio de diálogo:

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

Características avanzadas del cuadro de diálogo

Se puede llamar a una función cuando se selecciona el botón Aceptar. Para especificar esta función, establezca getDialogResult en las opciones que proporcione al mostrar el cuadro de diálogo.

Si una llamada a getDialogResult devuelve un valor distinto de NULL, este valor se pasa a la función especificada por okCallback (también en las opciones) y se cierra el cuadro de diálogo.

En este ejemplo, se llama a la attachFormChanged devolución de llamada cuando cambian las entradas del formulario. En función de si el formulario es válido o no, el botón Aceptar está habilitado o deshabilitado.

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

Control del botón Aceptar

Inicialmente, el botón Aceptar está deshabilitado. Sin embargo, puede habilitar o deshabilitar este botón llamando al updateOkButton método en el cuadro de diálogo:

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

Pasar valores al cuadro de diálogo

Es posible pasar valores iniciales al contenido del cuadro de diálogo al abrirlo en el cuadro de diálogo host.

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

Cuando se abra el cuadro de diálogo, se deben especificar las siguientes opciones para pasar myId:

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

Personalizar botones de diálogo

Los okText atributos y cancelText se pueden usar para especificar títulos alternativos para los botones Aceptar y Cancelar:

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

Para no mostrar ningún botón en el cuadro de diálogo, puede establecer el buttons atributo en []:

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

Si tiene una pregunta o busca más información, considere la posibilidad de ir a una de las siguientes áreas:

  • Last updated on