Partilhar via

Criar caixas de diálogo modais em extensões

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022

As diálogos modais oferecem uma forma poderosa de criar experiências focadas para o usuário nas extensões do Azure DevOps. O serviço de diálogo permite-lhe apresentar um diálogo modal que bloqueia a interação do utilizador com toda a interface Azure DevOps até que o diálogo seja ignorado. Essa ação garante que os usuários concluam tarefas importantes ou forneçam as informações necessárias.

Use diálogos modais nas suas extensões para:

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

Importante

Quando crias diálogos modais, bloqueiam a interação com toda a página DevOps do Azure, não apenas com a tua 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 válido vss-extension.json
Registo no Marketplace Extensão registrada no Visual Studio Marketplace para teste e implantação
Conhecimento de desenvolvimento Noções básicas de desenvolvimento da extensão Azure DevOps
Ambiente de desenvolvimento Node.js e npm Node.js versão 14 ou posterior com npm instalado
Editor de código Código do Visual Studio ou outro IDE recomendado
Acesso ao Azure DevOps Acesso a uma organização de DevOps do Azure para teste
Pacotes necessários Kit de Desenvolvimento de 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 no 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 em seu manifesto de extensão. Esta 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 dentro da á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 o diálogo (por exemplo, quando um utilizador seleciona uma ação numa barra de ferramentas ou menu), chame a openDialog função numa 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 avançados de caixa de diálogo

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

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

Neste exemplo, a função de retorno attachFormChanged é executada quando as entradas no formulário são alteradas. Com base na validade ou não do formulário, o botão OK está ativado ou desativado.

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

Controle o botão OK

Inicialmente, o botão OK está desativado. No entanto, você pode ativar/desativar 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 quando você o abre 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 é aberta, as seguintes opções devem ser especificadas para passar myId:

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

Personalizar botões 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 dúvida ou estiver procurando mais informações, considere ir para uma das seguintes áreas:

  • Last updated on