Compartilhar via

Criar caixas de diálogo modais em extensões

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

Os diálogos modais fornecem uma maneira poderosa de criar experiências de usuário focadas em extensões do Azure DevOps. O serviço de diálogo permite apresentar uma caixa de diálogo modal que bloqueia a interação do usuário com a interface inteira do Azure DevOps até que a caixa de diálogo seja descartada. Essa ação garante que os usuários preencham tarefas importantes ou forneçam informações necessárias.

Use caixas de diálogo modais em suas extensões para:

  • Coletar dados do usuário através de formulários
  • Exibir mensagens de confirmação para ações críticas
  • Mostrar informações detalhadas que exigem atenção do usuário
  • Orientar os usuários por meio de processos de várias etapas

Importante

Quando você cria diálogos modais, eles bloqueiam a interação com toda a página do Azure DevOps, não apenas com a extensão. Essa abordagem fornece uma verdadeira experiência modal, mas você deve usá-la cuidadosamente para evitar interromper o fluxo de trabalho do usuário.

Pré-requisitos

Categoria Requisito Detalhes
Configuração da extensão Projeto de extensão de trabalho Um arquivo de manifesto vss-extension.json válido
Registro do Marketplace Extensão registrada no Visual Studio Marketplace para teste e implantação
Conhecimento de desenvolvimento Noções básicas sobre o desenvolvimento de extensão do Azure DevOps
ambiente de desenvolvimento Node.js e npm Node.js versão 14 ou posterior com o npm instalado
Editor de código Visual Studio Code ou outro IDE recomendado
Acesso ao Azure DevOps Acesso a uma organização do Azure DevOps para teste
Pacotes necessários SDK da extensão Instalar: npm install azure-devops-extension-sdk
API de extensão Instalar: npm install azure-devops-extension-api
Permissões de extensão Escopos de manifesto Inclua escopos apropriados em vss-extension.json, por exemplo: "vso.work", "vso.project"
Importações do SDK Módulos necessários Importar SDK e serviços: import * as SDK from "azure-devops-extension-sdk"

Conteúdo da caixa de diálogo

Para começar, declare uma contribuição do tipo ms.vss-web.control no manifesto da extensão. Essa contribuição representa o conteúdo exibido na caixa 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"
        }
    }

A uri propriedade faz referência a uma página que é renderizada na área de conteúdo da caixa 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 a caixa de diálogo

Para mostrar a caixa de diálogo (por exemplo, quando um usuário seleciona uma ação em uma barra de ferramentas ou menu), chame a openDialog função em uma instância do serviço 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);
});

Recursos de caixa de diálogo avançados

Uma função pode ser chamada quando o botão OK é selecionado. Especifique essa função definindo getDialogResult nas opções fornecidas ao mostrar a caixa de diálogo.

Se uma chamada para getDialogResult retornar um valor não nulo, esse valor será então passado para a função especificada por okCallback (também nas opções) e a caixa de diálogo será fechada.

Neste exemplo, o attachFormChanged retorno de chamada é chamado quando as entradas no formulário mudam. Com base em se o formulário é válido ou não, o botão OK está habilitado ou desabilitado.

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

Controlar o botão OK

Inicialmente, o botão OK está desabilitado. No entanto, você pode habilitar/desabilitar esse botão chamando o updateOkButton método na caixa de diálogo:

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

Passar valores para a caixa de diálogo

É possível passar valores iniciais para o conteúdo da caixa de diálogo ao abri-lo na caixa de diálogo do host.

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

Quando a caixa de diálogo for aberta, o usuário deve especificar as seguintes opções para passar myId:

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

Personalizar botões de caixa de diálogo

Os okText atributos e cancelText podem ser usados para especificar títulos alternativos para os botões OK e Cancelar:

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

Para não mostrar nenhum botão na caixa de diálogo, você pode definir o buttons atributo como []:

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

Se você tiver uma pergunta ou estiver procurando mais informações, considere ir para uma das seguintes áreas:

  • Last updated on