模式对话框|Azure DevOps 扩展 - Azure DevOps

2025-03-24

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

使用 HostDialogService 可以向用户呈现模式对话框，并阻止与 Web 访问的所有部分交互，直到对话框被关闭。

提示

查看有关使用 Azure DevOps 扩展 SDK 进行扩展开发的最新文档。

与标准对话控件相比，通过 HostDialogService 提供的模式对话会阻止用户在整个页面上（而不仅仅是在扩展中）进行交互。

对话内容

若要开始，请在扩展清单中声明类型 ms.vss-web.control 的贡献。此贡献表示对话框中显示的内容。

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

属性 uri 引用在对话的内容区域中呈现的页面：

<!DOCTYPE html>
<html>
    <head>
        <script src="sdk/scripts/VSS.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>
            VSS.init();
            var registrationForm = (function() {
                var callbacks = [];
                
                function inputChanged() {
                    // Execute registered callbacks
                    for(var 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  
                    };
                }

                var name = document.getElementById("inpName");
                var dateOfBirth = document.getElementById("inpDob");
                var 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
            VSS.register("registration-form", registrationForm);
        </script>
    </body>
</html>

显示对话框

若要显示对话框（例如，当用户在工具栏或菜单上选择操作时），请在 HostDialogService 实例上调用 openDialog 函数，传递对话框内容的完全限定标识符，例如 my-publisher.my-extension.registration-form ，以及任何对话框选项：

    VSS.getService(VSS.ServiceIds.Dialog).then(function(dialogService) {
        var extensionCtx = VSS.getExtensionContext();
        // Build absolute contribution ID for dialogContent
        var contributionId = extensionCtx.publisherId + "." + extensionCtx.extensionId + ".registration-form";

        // Show dialog
        var dialogOptions = {
            title: "My Dialog",
            width: 800,
            height: 600
        };

        dialogService.openDialog(contributionId, dialogOptions);
    });

显示对话框 (高级)

选择“确定”按钮时，可以调用函数。此函数由 getDialogResult 在显示对话框时提供的选项中指定。

如果对的 getDialogResult 调用返回非 null 值，则此值将传递给 (okCallback 指定的函数，) 选项中也会关闭对话框。

在此示例中， attachFormChanged 当窗体上的输入发生更改时，将调用回调。根据表单是否有效，启用或禁用“确定”按钮。

    VSS.getService(VSS.ServiceIds.Dialog).then(function(dialogService) {
        var registrationForm;
        var extensionCtx = VSS.getExtensionContext();
        var contributionId = extensionCtx.publisherId + "." + extensionCtx.extensionId + ".registration-form";

        var dialogOptions = {
            title: "Registration Form",
            width: 800,
            height: 600,
            getDialogResult: function() {
                // Get the result from registrationForm object
                return registrationForm ? registrationForm.getFormData() : null;
            },
            okCallback: function (result) {
                // Log the result to the console
                console.log(JSON.stringify(result));
            }
        };

        dialogService.openDialog(contributionId, dialogOptions).then(function(dialog) {
            // Get registrationForm instance which is registered in registrationFormContent.html
            dialog.getContributionInstance("registration-form").then(function (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(function(isValid) {
                    dialog.updateOkButton(isValid);
                });
                
                // Set the initial ok enabled state
                registrationForm.isFormValid().then(function (isValid) {
                    dialog.updateOkButton(isValid);
                });
            });                            
        });
    });

启用或禁用“确定”按钮

最初禁用“确定”按钮。但是，可以通过在对话框中调用 updateOkButton 方法来启用/禁用此按钮：

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

将值传递给对话框控件

在主机对话框中打开对话内容时，可以将初始值传递给对话内容。

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

打开对话框时，需要指定以下选项才能传递 myId：

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

自定义对话框按钮

okText和 cancelText 属性可用于指定“确定”和“取消”按钮的备用标题：

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

若要在对话框中不显示任何按钮，可以将属性设置为 buttons[]：

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

通过

模式对话框