Hinzufügen eines benutzerdefinierten Steuerelements zum Arbeitsaufgabenformular

Artikel
10/16/2024

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. In diesem Artikel erfahren Sie, wie Sie ein eigenes benutzerdefiniertes Steuerelement erstellen.

Tipp

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

Voraussetzungen

Fügen Sie das Azure-devops-extension-sdk in Ihr Projekt ein:

Installieren Sie das SDK über npm: npm install azure-devops-extension-sdk.

Initialisieren Sie sie in Ihrem JavaScript-Code:

import * as SDK from "azure-devops-extension-sdk";
SDK.init();

Hinzufügen des benutzerdefinierten Steuerelements

Um der Hauptseite ein Steuerelement hinzuzufügen, fügen Sie ihrem Erweiterungsmanifest einen Beitrag hinzu. 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
        }
    }
],
"manifestVersion": 1.0,
    "scopes": [
        "vso.work"
    ]

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 Hauptunterschied besteht darin, dass ein Steuerelementbeitrag eine Reihe von Benutzereingaben übernehmen kann, während Gruppen- und Seitenbeiträ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.",
        "type": "string",
        "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 SDK from "azure-devops-extension-sdk";
import * as ExtensionContracts from "azure-devops-extension-api/WorkItemTracking/WorkItemTracking";

let control;

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

SDK.init();
SDK.ready().then(() => {
    SDK.register(SDK.getContributionId(), provider);
});

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

Screenshot des benutzerdefinierten Steuerelements im Arbeitsaufgabenformular.

Freigeben über