Formular für Arbeitselemente erweitern

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

Verwenden Sie Erweiterungen, um das Arbeitsaufgabenformular anzupassen, indem Sie Gruppen, Seiten, Menüaktionen, Beobachter oder benutzerdefinierte Steuerelemente hinzufügen.

• Hinzufügen einer Gruppe
• Hinzufügen einer Seite (Registerkarte)
• Hinzufügen einer Menüaktion
• Hinzufügen eines benutzerdefinierten Steuerelements
• Auf Ereignisse lauschen
• Konfigurieren von Beiträgen

Den vollständigen Quellcode finden Sie im Beispiel für die Benutzeroberfläche in den Azure DevOps-Erweiterungsbeispielen auf GitHub.

Eine Gruppe hinzufügen

Um der Hauptseite eine Gruppe hinzuzufügen, fügen Sie dem Erweiterungsmanifest einen Beitrag mit Typ ms.vss-work-web.work-item-form-group, der auf ms.vss-work-web.work-item-form abzielt, hinzu.

"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

JavaScript-Beispiel

In diesem Beispiel wird ein Anbieter registriert, der auf Arbeitsaufgabenformularereignisse reagiert. Es verwendet WorkItemFormService, um Feldwerte zu lesen, wenn das Arbeitselement geladen wird.

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

async function getWorkItemFormService(): Promise<IWorkItemFormService> {
    return await SDK.getService<IWorkItemFormService>(WorkItemTrackingServiceIds.WorkItemFormService);
}

SDK.init();

SDK.ready().then(() => {
    SDK.register(SDK.getContributionId(), () => {
        return {
            // Called when the active work item is modified
            onFieldChanged: (args) => {
                console.log("onFieldChanged", JSON.stringify(args));
            },

            // Called when a new work item is being loaded in the UI
            onLoaded: async (args) => {
                const service = await getWorkItemFormService();
                const values = await service.getFieldValues([
                    "System.Id", "System.Title", "System.State", "System.CreatedDate"
                ]);
                console.log("onLoaded", JSON.stringify(values));
            },

            // Called when the active work item is being unloaded in the UI
            onUnloaded: (args) => {
                console.log("onUnloaded", JSON.stringify(args));
            },

            // Called after the work item has been saved
            onSaved: (args) => {
                console.log("onSaved", JSON.stringify(args));
            },

            // Called when the work item is reset to its unmodified state (undo)
            onReset: (args) => {
                console.log("onReset", JSON.stringify(args));
            },

            // Called when the work item has been refreshed from the server
            onRefreshed: (args) => {
                console.log("onRefreshed", JSON.stringify(args));
            }
        };
    });
});

Ereignisse

Seite hinzufügen

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

Um dem Arbeitsaufgabenformular eine Seite hinzuzufügen, fügen Sie Ihrem Erweiterungsmanifest einen Beitrag mit dem Typ ms.vss-work-web.work-item-form-page für ms.vss-work-web.work-item-form zielgerichtet hinzu.

"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

JavaScript-Beispiel

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

Ereignisse

Konfigurieren von Beiträgen

In Azure DevOps Services werden Gruppenerweiterungen standardmäßig am Ende der zweiten Spalte angezeigt, und Seitenbeiträge werden als letzte Registerkarte angezeigt. Steuerelementbeiträge werden nicht standardmäßig angezeigt – Benutzer müssen sie dem Formular manuell hinzufügen. Informationen zu Azure DevOps Server finden Sie unter Konfigurieren von Formularerweiterungen für Arbeitsaufgaben zum Anzeigen, Ausblenden oder Verschieben von Beiträgen.

Menüaktion hinzufügen

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 im Dropdownmenü mit den vertikalen Auslassungspunkten (...) angezeigt.

"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

Auf Ereignisse lauschen

Beobachter überwachen Arbeitsaufgabenereignisse ohne UI auf der Oberfläche. Verwenden Sie Beobachter, um auf das onSaved Ereignis zu hören, da Beobachter sich außerhalb des Formulars befinden und nicht zerstört werden, wenn der Formulardialog geschlossen wird.

"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

Ereignisse

JavaScript-Beispiel

Im folgenden Beispiel wird ein Beobachter mithilfe des modernen SDK registriert:

import * as SDK from "azure-devops-extension-sdk";

SDK.init();

SDK.ready().then(() => {
    SDK.register(SDK.getContributionId(), () => {
        return {
            onFieldChanged: (args) => {
                // Handle field changes
            },
            onLoaded: (args) => {
                // Handle work item loaded
            },
            onUnloaded: (args) => {
                // Handle work item unloaded
            },
            onSaved: (args) => {
                // Handle work item saved
            },
            onReset: (args) => {
                // Handle work item reset (undo)
            },
            onRefreshed: (args) => {
                // Handle work item refreshed
            }
        };
    });
});

Kompatibilitätshinweise

Aktion im Vergleich zum Aktionsanbieter

Verwenden Sie ms.vss-web.action-provider, wenn Menüelemente dynamisch mithilfe von getMenuItems auf dem Menühandler geladen werden. Verwenden Sie ms.vss-web.action, wenn Ihre Menüelemente statisch sind und im Manifest definiert werden.

Veraltete Muster

Die folgenden Muster werden nicht mehr unterstützt:

• require("VSS/Events/Document") - nicht unterstützt mit dem New Boards Hub
• SDK.jsScript-Tag mit usePlatformScripts: true - verwenden Sie stattdessen das npm-Paket azure-devops-extension-sdk

Verwandte Inhalte

• Hinzufügen eines benutzerdefinierten Steuerelements zum Workitem-Formular.
• Konfigurieren von Formularerweiterungen für Arbeitselemente (vor Ort)
• Erweiterungsmanifestreferenz
• Beitragsmodell