Aracılığıyla paylaş

Uzantılarda modal iletişim kutuları oluşturma

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

Modal iletişim kutuları, Azure DevOps uzantılarında odaklanmış kullanıcı deneyimleri oluşturmak için güçlü bir yol sağlar. HostDialogService, iletişim kutusu kapatılana kadar tüm Azure DevOps arabirimiyle kullanıcı etkileşimini engelleyen kalıcı bir iletişim kutusu sunmanızı sağlar. Bu eylem, kullanıcıların önemli görevleri tamamlamasını veya gerekli bilgileri sağlamasını sağlar.

Uzantılarınızda kalıcı iletişim kutularını kullanarak:

  • Formlar aracılığıyla kullanıcı girişi toplama
  • Kritik eylemler için onay iletilerini görüntüleme
  • Kullanıcı dikkatini gerektiren ayrıntılı bilgileri göster
  • Çok adımlı işlemlerde kullanıcılara yol gösterme

Önemli

ile HostDialogServicekalıcı iletişim kutuları oluşturduğunuzda, yalnızca uzantınızla değil, tüm Azure DevOps sayfasıyla etkileşimi engeller. Bu yaklaşım gerçek bir kalıcı deneyim sağlar, ancak kullanıcı iş akışını kesintiye uğratmamak için bunu dikkatli bir şekilde kullanmanız gerekir.

Önkoşullar

Azure DevOps uzantınızda kalıcı iletişim kutuları oluşturmadan önce aşağıdakilere sahip olduğunuzdan emin olun:

Kategori Gereksinim Ayrıntılar
Uzantı kurulumu Çalışma uzantısı projesi Geçerli vss-extension.json bir bildirim dosyası
Çevrimiçi pazar yeri kaydı Test ve dağıtım için Visual Studio Market'e kaydedilen uzantı
Geliştirme bilgisi Azure DevOps uzantısı geliştirmeyle ilgili temel bilgileri anlama
Geliştirme ortamı Node.js ve npm npm yüklü Node.js sürüm 14 veya üzeri
Kod düzenleyicisi Visual Studio Code veya başka bir IDE önerilir
Azure DevOps erişimi Test için Azure DevOps kuruluşuna erişim
Gerekli paketler Uzantı SDK'sı Yükle: npm install azure-devops-extension-sdk
Uzantı API'si Yükle: npm install azure-devops-extension-api
Uzantı izinleri Bildirim kapsamları içinde vss-extension.jsonuygun kapsamları ekleyin, örneğin: "vso.work", "vso.project"
SDK aktarımları Gerekli modüller SDK ve hizmetleri içeri aktarma: import * as SDK from "azure-devops-extension-sdk" ve import { CommonServiceIds, IHostDialogService } from "azure-devops-extension-api"

İletişim kutusu içeriği

Başlamak için uzantı bildirim dosyanızda ms.vss-web.control türünde bir katkı belirtin. Bu katkı, iletişim kutusunda görüntülenen içeriği temsil eder.

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

özelliği, uri iletişim kutusunun içerik alanında işlenen bir sayfaya başvurur:

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

İletişim kutusunu göster

İletişim kutusunu göstermek için (örneğin, bir kullanıcı araç çubuğunda veya menüden bir eylem seçtiğinde), HostDialogService örneğindeki işlevi çağırın openDialog ve iletişim kutusu içeriğinin tam tanımlayıcısını (örneğin my-publisher.my-extension.registration-form ve tüm iletişim kutusu seçenekleri) geçirin:

    import * as SDK from "azure-devops-extension-sdk";
    
    SDK.getService<IHostDialogService>(CommonServiceIds.HostDialogService).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);
    });

Gelişmiş diyalog penceresi özellikleri

Tamam düğmesi seçildiğinde bir işlev çağrılabilir. Bu işlev, iletişim kutusunu gösterirken sağladığınız seçeneklerde tarafından getDialogResult belirtilir.

Eğer getDialogResult çağrısı null olmayan bir değer döndürürse, bu değer (aynı zamanda seçeneklerde belirtilen) okCallback fonksiyonuna geçirilir ve iletişim kutusu kapatılır.

Bu örnekte, attachFormChanged formdaki girişler değiştiğinde geri çağırma çağrılır. Formun geçerli olup olmadığına bağlı olarak Tamam düğmesi etkinleştirilir veya devre dışı bırakılır.

    import * as SDK from "azure-devops-extension-sdk";
    import { CommonServiceIds, IHostDialogService } from "azure-devops-extension-api";
    
    SDK.getService<IHostDialogService>(CommonServiceIds.HostDialogService).then((dialogService) => {
        let registrationForm: any;
        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: any) => {
                // Log the result to the console
                console.log(JSON.stringify(result));
            }
        };

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

Tamam düğmesini denetleme

Başlangıçta Tamam düğmesi devre dışı bırakılır. Ancak, iletişim kutusunda updateOkButton yöntemini çağırarak bu düğmeyi etkinleştirebilir/devre dışı bırakabilirsiniz.

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

Değerleri iletişim kutusuna geçirme

Host iletişim kutusunda açıldığında, iletişim kutusu içeriğine ilk değerleri geçirmek mümkündür.

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

İletişim kutusu açıldığında, myId'ı geçirmek için aşağıdaki seçeneklerin belirtilmesi gerekir.

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

İletişim kutusu düğmelerini özelleştir

okText ve cancelText öznitelikleri, Tamam ve İptal düğmeleri için alternatif başlıklar belirtmek için kullanılabilir:

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

İletişim kutusunda düğme göstermemek için özniteliğini buttons olarak []ayarlayabilirsiniz:

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

Bir sorunuz varsa veya daha fazla bilgi arıyorsanız, aşağıdaki alanlardan birine gitme seçeneğini göz önünde bulundurun: