Hinzufügen eines benutzerdefinierten Steuerelements zum Arbeitsaufgabenformular

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

Mit benutzerdefinierten Steuerelementen können Sie ändern, wie Benutzer ein Feld im Arbeitselementformular anzeigen und damit interagieren. Der folgende Artikel führt Sie durch die Erstellung dieses benutzerdefinierten Beispielsteuerelements. Erfahren Sie, wie Sie Ihr eigenes benutzerdefiniertes Steuerelement erstellen.

Tipp

Sehen Sie sich unsere neueste Dokumentation zur Erweiterungsentwicklung mithilfe des Azure DevOps-Erweiterungs-SDK an.

Hinzufügen des benutzerdefinierten Steuerelements

Fügen Sie ihrem Erweiterungsmanifest einen Beitrag hinzu, um der seite Standard ein Steuerelement hinzuzufügen. Die Art des Beitrags sollte sein ms.vss-work-web.work-item-form-control und sollte auf den ms.vss-work-web.work-item-form Beitrag abzielen.

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

Das Arbeitsaufgabenformular fügt einen IFrame zum Hosten des benutzerdefinierten Steuerelements hinzu.

Eigenschaften

Eigenschaften	Beschreibung
name	Text, der in der Gruppe angezeigt wird.
uri	URI zu einer Seite, die den html-Code hosten, der vom IFrame geladen wird.
height	(Optional) Definiert die Höhe des IFrames. Wenn sie weggelassen wird, beträgt sie 50 Pixel.
inputs	Die Werte, die ein Benutzer innerhalb des Formulars bereitstellt.

Wenn Sie die Größe des IFrame dynamisch ändern möchten, können Sie das resize method verfügbare im Client-SDK verwenden.

Ein benutzerdefiniertes Steuerelement im Arbeitsaufgabenformular ist ein weiterer Beitragstyp, z. B. Gruppen- und Seitenbeitrag. Der Standard Unterschied besteht darin, dass ein Steuerelementbeitrag eine Reihe von Benutzereingaben übernehmen kann, während Gruppen- und Seiteneingaben Beiträge nicht möglich sind.

Steuern von Beitragseingaben

Um die Eingaben für Ihren Steuerelementbeitrag zu definieren, verwenden Sie die inputs Eigenschaft im Beitragsobjekt im Manifest.

Im folgenden Beispiel werden zwei Eingaben angezeigt: FieldName und Colors. FieldName Gibt an, mit welchem Feld das Steuerelement verknüpft wird. Colors konfiguriert, welche Farben den Werten im Steuerelement zugeordnet sind.

Die Werte für die Eingaben werden von den Benutzern bereitgestellt, wenn sie dem Arbeitsaufgabenformular hinzugefügt werden. Diese Werte werden an den Steuerelementbeitrag übergeben, wenn sie im Formular geladen wird.

"inputs": [
    {
        "id": "FieldName",
        "description": "The field associated with the control.",
        "type": "WorkItemField",
        "properties": {
            "workItemFieldTypes": ["String"]
        },
        "validation": {
            "dataType": "String",
            "isRequired": true
        }
    },
    {
        "id": "Colors",
        "description": "The colors that match the values in the control.",
        "validation": {
            "dataType": "String",
            "isRequired": false
        }
    }
]

Die folgenden Eigenschaften definieren eine Benutzereingabe, die der Beitrag verwenden kann:

• id – Eine eindeutige ID für die Eingabe.
• description - Einige Sätze, die die Eingabe beschreiben.
• type (optional) - Der Typ der Eingabe.
  • Gültige Werte:
    • WorkItemField – Gibt an, dass es sich bei der Eingabe um ein Arbeitselementfeld handelt. Der vom Benutzer für diese Eingabe bereitgestellte Wert sollte ein Verweisname für das gültige Arbeitselementfeld sein.
• Eigenschaften (optional) – Benutzerdefinierte Eigenschaften für die Eingabe.
  • Gültige Schlüssel:
    • workItemFieldTypes – Definiert ein Array von Feldtypen, die diese Eingabe unterstützt. Gültige Werte:
      • String
      • Integer
      • DateTime
      • PlainText
      • HTML
      • TreePath
      • History
      • Double
      • Guid
      • Boolean
      • Identity
      • PicklistString
      • PicklistInteger
      • PicklistDouble
• validation – Eine Reihe von Eigenschaften, die definieren, welche Werte als gültig für die Eingabe gelten.
  • Gültige Schlüssel:
    • dataType – Definiert den Datentyp des Eingabewerts. Gültige Werte für diese Eigenschaft:
      • String
      • Number
      • Boolean
      • Field
    • isRequired - Ein boolescher Wert, der angibt, ob die Eingabe über einen Wert verfügt.

JavaScript-Beispiel

Eine Steuerelementerweiterung funktioniert wie eine Gruppen- oder Seitenerweiterung mit einem Unterschied, dass bestimmte Benutzereingaben erforderlich sind. Verwenden Sie VSS.getConfiguration().witInputszum Lesen der Benutzereingabewerte . Im folgenden Beispiel wird gezeigt, wie Sie ein Objekt registrieren, das aufgerufen wird, wenn Ereignisse im Arbeitsaufgabenformular auftreten, die sich auf ihr beigetragenes Steuerelement auswirken können. Außerdem wird gezeigt, wie Eingabewerte gelesen werden, die vom Benutzer für dieses Steuerelement bereitgestellt werden.

import { Control } from "control";
import * as ExtensionContracts from "TFS/WorkItemTracking/ExtensionContracts";

var control: Control;

var provider = () => {
    return {
        onLoaded: (workItemLoadedArgs: ExtensionContracts.IWorkItemLoadedArgs) => {
            // create the control
            var fieldName = VSS.getConfiguration().witInputs["FieldName"];
            var colors = VSS.getConfiguration().witInputs["Colors"];
            control = new Control(fieldName, colors);
        },
        onFieldChanged: (fieldChangedArgs: ExtensionContracts.IWorkItemFieldChangedArgs) => {
            var changedValue = fieldChangedArgs.changedFields[control.getFieldName()];
            if (changedValue !== undefined) {
                control.updateExternal(changedValue);
            }
        }
    }
};

VSS.register(VSS.getContribution().id, provider);

Der folgende Screenshot zeigt ein Beispiel für ein benutzerdefiniertes Arbeitsaufgabensteuerelement für das Feld "Priorität ".