Teilen über

Erweitern des Arbeitselementformulars

  • Artikel

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

Erfahren Sie, wie Sie anpassen, wie das Formular für Arbeitsaufgaben benutzern über Beiträge präsentiert wird, die über eine Erweiterung vorgenommen werden.

Sehen Sie sich das UI-Beispiel in den Azure DevOps-Erweiterungsbeispielen auf GitHub für die vollständige Quelle an.

Eine Gruppe hinzufügen

Symbolleistenelement im Arbeitsaufgabenformular.

Um der Hauptseite eine Gruppe hinzuzufügen, fügen Sie ihrem Erweiterungsmanifest einen Beitrag hinzu. Die Art dieses Beitrags sollte sein ms.vss-work-web.work-item-form-group , und er sollte auf den ms.vss-work-web.work-item-form Beitrag abzielen.

"contributions": [
   {  
       "id": "sample-work-item-form-group",
       "type": "ms.vss-work-web.work-item-form-group",
       "description": "Custom work item form group",
       "targets": [
           "ms.vss-work-web.work-item-form"
       ],
       "properties": {
           "name": "My Group",
           "uri": "workItemGroup.html",
           "height": 600
       }
   }
]

Eigenschaften

Eigenschaften Beschreibung
name Text, der in der Gruppe angezeigt wird.
uri URI zu einer Seite, die den HTML-Code hostt, der im Arbeitsaufgabenformular und den zugehörigen Skripts angezeigt wird.
height (Optional) Definiert die Höhe der Gruppe. Wenn sie weggelassen wird, beträgt sie 100 %.

JavaScript-Beispiel

In diesem Beispiel wird gezeigt, wie Sie ein Objekt registrieren, das aufgerufen wird, wenn Ereignisse im Arbeitsaufgabenformular auftreten, die sich auf Ihre beigetragene Gruppe auswirken können.

import { IWorkItemFormService, WorkItemTrackingServiceIds } from "azure-devops-extension-api/WorkItemTracking";
import * as SDK from "azure-devops-extension-sdk";

// Get the WorkItemFormService.  This service allows you to get/set fields/links on the 'active' work item (the work item
// that currently is displayed in the UI).
async function getWorkItemFormService()
{
    const workItemFormService = await SDK.getService<IWorkItemFormService>(WorkItemTrackingServiceIds.WorkItemFormService);
    return workItemFormService;
}

// Register a listener for the work item group contribution after initializing the SDK.
SDK.register(SDK.getContributionId(), function () {
    return {
        // Called when the active work item is modified
        onFieldChanged: function(args) {
            $(".events").append($("<div/>").text("onFieldChanged - " + JSON.stringify(args)));
        },
        
        // Called when a new work item is being loaded in the UI
        onLoaded: function (args) {

            getWorkItemFormService().then(function(service) {            
                // Get the current values for a few of the common fields
                service.getFieldValues(["System.Id", "System.Title", "System.State", "System.CreatedDate"]).then(
                    function (value) {
                        $(".events").append($("<div/>").text("onLoaded - " + JSON.stringify(value)));
                    });
            });
        },
        
        // Called when the active work item is being unloaded in the UI
        onUnloaded: function (args) {
            $(".events").empty();
            $(".events").append($("<div/>").text("onUnloaded - " + JSON.stringify(args)));
        },
        
        // Called after the work item has been saved
        onSaved: function (args) {
            $(".events").append($("<div/>").text("onSaved - " + JSON.stringify(args)));
        },
        
        // Called when the work item is reset to its unmodified state (undo)
        onReset: function (args) {
            $(".events").append($("<div/>").text("onReset - " + JSON.stringify(args)));
        },
        
        // Called when the work item has been refreshed from the server
        onRefreshed: function (args) {
            $(".events").append($("<div/>").text("onRefreshed - " + JSON.stringify(args)));
        }
    }
});

Ereignisse

Ereignis Ereignisbeschreibung Argument Argumentbeschreibung
onFieldChanged Wird ausgelöst, nachdem ein Feld geändert wurde. Wenn die Feldänderung Regeln ausgeführt hat, die andere Felder aktualisiert haben, sind alle diese Änderungen Teil eines einzelnen Ereignisses. Kennung Die ID des Arbeitselements.
changedFields Array mit dem Verweisnamen aller geänderten Felder. Kennung Die ID des Arbeitselements.
onLoaded Wird ausgelöst, nachdem die Daten im Arbeitsaufgabenformular geladen werden, wenn der Benutzer eine Arbeitsaufgabe öffnet oder der Benutzer zu einer anderen Arbeitsaufgabe in der Triageansicht navigiert. Kennung Die ID des Arbeitselements.
onReset Wird ausgelöst, nachdem der Benutzer die Änderungen an der Arbeitsaufgabe rückgängig machen kann. Kennung Die ID des Arbeitselements.
onRefreshed Wird ausgelöst, nachdem der Benutzer die Arbeitsaufgabe manuell aktualisiert hat. Kennung Die ID des Arbeitselements.
onSaved Wird nach dem Speichern einer Arbeitsaufgabe ausgelöst. Für Arbeitsaufgaben in einem Dialogfeld sollten Sie auf den Typ "ms.vss-work-web.work-item-notifications" abzielen, um sicherzustellen, dass das Ereignis ausgelöst wird, nachdem das Dialogfeld geschlossen wurde, dieser Beitragstyp entladen wird. Weitere Informationen finden Sie unter "Auf Ereignisse lauschen". Kennung Die ID des Arbeitselements.
onUnloaded Wird ausgelöst, bevor der Benutzer das Dialogfeld schließt oder bevor der Benutzer zu einer anderen Arbeitsaufgabe in der Triageansicht wechselt. Kennung Die ID des Arbeitselements.

Seite hinzufügen

Eine neue Seite wird als Registerkarte im Arbeitsaufgabenformular gerendert. Neue Seiten werden neben der Registerkarte "Details" angezeigt.

Neue Seite als Registerkarte im Arbeitsaufgabenformular.

Um dem Arbeitsaufgabenformular eine Seite hinzuzufügen, fügen Sie ihrem Erweiterungsmanifest einen Beitrag hinzu. Die Art dieses Beitrags sollte sein ms.vss-work-web.work-item-form-page , und er sollte auf den ms.vss-work-web.work-item-form Beitrag abzielen.

"contributions": [
    {  
        "id": "sample-work-item-form-page",
        "type": "ms.vss-work-web.work-item-form-page",
        "description": "Custom work item form page",
        "targets": [
            "ms.vss-work-web.work-item-form"
        ],
        "properties": {
            "name": "My Page",
            "uri": "workItemPage.html"
        } 
    }
]

Eigenschaften

Eigenschaften Beschreibung
name Text, der auf der Registerkartenseite angezeigt wird.
uri URI zu einer Seite, die den HTML-Code hostt, der im Arbeitsaufgabenformular und den zugehörigen Skripts angezeigt wird.

JavaScript-Beispiel

Sehen Sie sich das JavaScript-Beispiel im Abschnitt "Formulargruppe" an. Der Name des registrierten Objekts sollte mit dem id Beitrag übereinstimmen.

Ereignisse

Ereignis Ereignisbeschreibung Argument Argumentbeschreibung
onFieldChanged Wird ausgelöst, nachdem ein Feld geändert wurde. Wenn die Feldänderung Regeln ausgeführt hat, die andere Felder aktualisiert haben, sind alle diese Änderungen Teil eines einzelnen Ereignisses. Kennung Die ID des Arbeitselements.
changedFields Array mit dem Verweisnamen aller geänderten Felder. Kennung Die ID des Arbeitselements.
onLoaded Wird ausgelöst, nachdem die Daten im Arbeitsaufgabenformular geladen werden, wenn der Benutzer eine Arbeitsaufgabe öffnet oder der Benutzer zu einer anderen Arbeitsaufgabe in der Triageansicht navigiert. Kennung Die ID des Arbeitselements.
onReset Wird ausgelöst, nachdem der Benutzer die Änderungen an der Arbeitsaufgabe rückgängig machen kann. Kennung Die ID des Arbeitselements.
onRefreshed Wird ausgelöst, nachdem der Benutzer die Arbeitsaufgabe manuell aktualisiert hat. Kennung Die ID des Arbeitselements.
onSaved Wird nach dem Speichern einer Arbeitsaufgabe ausgelöst. Für Arbeitsaufgaben in einem Dialogfeld sollten Sie auf den Typ "ms.vss-work-web.work-item-notifications" abzielen, um sicherzustellen, dass das Ereignis ausgelöst wird, nachdem das Dialogfeld geschlossen wurde, dieser Beitragstyp entladen wird. Weitere Informationen finden Sie unter "Auf Ereignisse lauschen". Kennung Die ID des Arbeitselements.
onUnloaded Wird ausgelöst, bevor der Benutzer das Dialogfeld schließt oder bevor der Benutzer zu einer anderen Arbeitsaufgabe in der Triageansicht wechselt. Kennung Die ID des Arbeitselements.

Konfigurieren von Beiträgen im Arbeitsaufgabenformular

In Azure DevOps Services werden standardmäßig die Gruppenerweiterungen am Ende der zweiten Spalte des Formulars und der Seitenbeiträge angezeigt, nachdem alle Arbeitsaufgabenformularseiten als Registerkarte angezeigt werden. Steuerelementbeiträge werden standardmäßig nicht im Formular angezeigt, sodass Benutzer sie manuell dem Formular hinzufügen müssen. Informationen zum Ein-/Ausblenden oder Verschieben des Steuerelements, der Gruppen- und Seitenbeiträge im Arbeitsaufgabenformular finden Sie unter "Konfigurieren von Formularerweiterungen für Arbeitsaufgaben" in Azure DevOps Server.

Menüaktion hinzufügen

Fügen Sie der Arbeitsaufgabensymbolleiste ein Element hinzu.

Wenn Sie der Symbolleiste für Arbeitsaufgaben ein Element hinzufügen möchten, fügen Sie diesen Beitrag zu Ihrem Erweiterungsmanifest hinzu. Das Element wird in der ... dropdown in der oberen rechten Ecke des Arbeitsaufgabenformulars.

"contributions": [
   {  
      "id": "sample-work-item-menu",  
      "type": "ms.vss-web.action",  
      "description": "Sample toolbar item which updates the title of a work item",  
      "targets": [  
          "ms.vss-work-web.work-item-context-menu"  
      ],  
      "properties": {  
          "text": "Try me!",  
          "title": "Updates the title of the work item from the extension",  
          "toolbarText": "Try me!",  
          "icon": "images/show-properties.png",  
          "uri": "menu-workItemToolbarButton.html"  
      }  
   }
]

Eigenschaften

Eigenschaften Beschreibung
Text Text, der im Symbolleistenelement angezeigt wird.
title QuickInfo-Text, der im Menüelement angezeigt wird.
toolbarText Text, der beim Daraufzeigen des Elements angezeigt wird.
uri URI zu einer Seite, die den Symbolleistenaktionshandler registriert.
Symbol URL zu einem Symbol, das im Menüelement angezeigt wird. Relative URLs werden mithilfe von baseUri aufgelöst.
group Bestimmt, wo das Menüelement angezeigt wird, was mit anderen zusammenhängt. Symbolleistenelemente mit demselben Gruppennamen werden gruppiert und durch ein Trennzeichen von den restlichen Elementen geteilt.
registeredObjectId (Optional) Name des registrierten Menüaktionshandlers. Der Standardwert ist die Beitrags-ID.

Auf Ereignisse lauschen

Um der Arbeitsaufgabe einen Beobachter hinzuzufügen, der die Arbeitsaufgabenereignisse überwacht, fügen Sie diesen Beitrag zu Ihrem Erweiterungsmanifest hinzu. Es gibt keine Visualisierung für Beobachter im Arbeitsaufgabenformular. Dies ist die beste Möglichkeit, das Arbeitsaufgabenformular auf dem gespeicherten Ereignis abzuhören, da der Beobachter außerhalb des Formulars lebt und nicht zerstört wird, wenn das Formular geschlossen wird, was direkt nach dem Speichern passieren kann.

"contributions": [
   {  
       "id": "sample-work-item-form-observer",
       "type": "ms.vss-work-web.work-item-notifications",
       "description": "Gets events about the current work item form for the 'Try Me!' toolbar button",
       "targets": [
           "ms.vss-work-web.work-item-form"
       ],
       "properties": {
           "uri": "myformobserver.html"
       }
   }
]

Eigenschaften

Eigenschaften Beschreibung
uri URI zu einer Seite, auf der die Skripts gehostet werden, die Ereignisse überwachen.

Ereignisse

Ereignis Ereignisbeschreibung Argument Argumentbeschreibung
onFieldChanged Wird ausgelöst, nachdem ein Feld geändert wurde. Wenn die Feldänderung Regeln ausgeführt hat, die andere Felder aktualisiert haben, sind alle diese Änderungen Teil eines einzelnen Ereignisses. Kennung Die ID des Arbeitselements.
changedFields Array mit dem Verweisnamen aller geänderten Felder. Kennung Die ID des Arbeitselements.
onLoaded Wird ausgelöst, nachdem die Daten im Arbeitsaufgabenformular geladen werden, wenn der Benutzer eine Arbeitsaufgabe öffnet oder der Benutzer zu einer anderen Arbeitsaufgabe in der Triageansicht navigiert. Kennung Die ID des Arbeitselements.
onReset Wird ausgelöst, nachdem der Benutzer die Änderungen an der Arbeitsaufgabe rückgängig machen kann. Kennung Die ID des Arbeitselements.
onRefreshed Wird ausgelöst, nachdem der Benutzer die Arbeitsaufgabe manuell aktualisiert hat. Kennung Die ID des Arbeitselements.
onSaved Wird nach dem Speichern einer Arbeitsaufgabe ausgelöst. Für Arbeitsaufgaben in einem Dialogfeld sollten Sie auf den Typ "ms.vss-work-web.work-item-notifications" abzielen, um sicherzustellen, dass das Ereignis ausgelöst wird, nachdem das Dialogfeld geschlossen wurde, dieser Beitragstyp entladen wird. Weitere Informationen finden Sie unter "Auf Ereignisse lauschen". Kennung Die ID des Arbeitselements.
onUnloaded Wird ausgelöst, bevor der Benutzer das Dialogfeld schließt oder bevor der Benutzer zu einer anderen Arbeitsaufgabe in der Triageansicht wechselt. Kennung Die ID des Arbeitselements.

HTML/JavaScript-Beispiel

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <title>Work item extension page sample</title>
</head>

<body>
    <script src="sdk/scripts/SDK.js"></script>

    <script>
        SDK.init({
            usePlatformScripts: true
        });
        
        SDK.ready(function () {
             // Register a listener for the work item page contribution.
            SDK.register(SDK.getContributionId(), function () {
                return {
                    // Called when the active work item is modified
                    onFieldChanged: function(args) {
                        
                    },
                    
                    // Called when a new work item is being loaded in the UI
                    onLoaded: function (args) {
            
                    },
                    
                    // Called when the active work item is being unloaded in the UI
                    onUnloaded: function (args) {
            
                    },
                    
                    // Called after the work item has been saved
                    onSaved: function (args) {
            
                    },
                    
                    // Called when the work item is reset to its unmodified state (undo)
                    onReset: function (args) {
            
                    },
                    
                    // Called when the work item has been refreshed from the server
                    onRefreshed: function (args) {
            
                    }
                }
            });    
        });
     </script>
</body>
</html>

Änderungen mit dem Hub für neue Boards

Hinweis

Der Hub für neue Boards befindet sich derzeit in der Vorschau, ist aber für alle verfügbar. Wir empfehlen dringend, dass Sie den New Boards Hub sofort aktivieren und Ihre internen Erweiterungen testen.

Verwenden der neuesten SDKs

Stellen Sie sicher, dass Ihre Erweiterung die neueste Version von azure-devops-extension-sdk verwendet.

Wenn Sie das neue SDK verwenden, sollten Sie auch das Azure-devops-extension-api-Paket für REST-APIs verwenden. Wir aktualisieren die Methoden und Schnittstellen jedes Sprints, um sicherzustellen, dass es alle neuesten Features enthält.

Gründe für die Verwendung von Aktionen oder Aktionsanbietern

Wird ms.vss-web.action-provider beim dynamischen Laden von Menüelementen im getMenuItems Menühandler verwendet. Vermeiden Sie die Verwendung ms.vss-web.action-provider , wenn Ihre Menüelemente statisch und in Ihrem Manifest definiert sind. Stattdessen ms.vss-web.action sollte verwendet werden.

Paket erforderlich("VSS/Events/Document") wird nicht mehr unterstützt.

require("VSS/Events/Document") Der Import wird mit dem New Boards Hub nicht mehr unterstützt.