Ajouter un contrôle personnalisé au formulaire d’élément de travail

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

Les contrôles personnalisés vous permettent de modifier la façon dont les utilisateurs affichent et interagissent avec un champ sur le formulaire d’élément de travail. L’article suivant vous guide tout au long de la façon dont cet exemple de contrôle personnalisé a été créé. Découvrez comment créer votre propre contrôle personnalisé.

Conseil

Consultez notre documentation la plus récente sur le développement d’extensions à l’aide du Kit de développement logiciel (SDK) d’extension Azure DevOps.

Ajouter le contrôle personnalisé

Pour ajouter un contrôle à la page principale, ajoutez une contribution à votre manifeste d’extension. Le type de contribution doit être ms.vss-work-web.work-item-form-control et cibler la ms.vss-work-web.work-item-form contribution.

"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
        }
    }
]

Le formulaire d’élément de travail ajoute un IFrame pour héberger le contrôle personnalisé.

Propriétés

Property	Description
name	Texte qui apparaît sur le groupe.
uri	URI vers une page qui héberge le code html chargé par l’IFrame.
height	(Facultatif) Définit la hauteur de l’IFrame. En cas d’omission, il s’agit de 50 pixels.
inputs	Valeurs qu’un utilisateur fournit dans le formulaire.

Si vous souhaitez redimensionner dynamiquement l’IFrame, vous pouvez utiliser le resize method Kit de développement logiciel (SDK) client.

Un contrôle personnalisé sur le formulaire d’élément de travail est un autre type de contribution, tel que la contribution de groupe et de page. La principale différence est qu’une contribution de contrôle peut prendre un ensemble d’entrées utilisateur alors que les contributions de groupe et de page ne peuvent pas.

Contrôler les entrées de contribution

Pour définir les entrées de votre contribution de contrôle, utilisez la inputs propriété dans l’objet de contribution dans le manifeste.

Dans l’exemple suivant, vous voyez deux entrées : FieldName et Colors. FieldName spécifie le champ auquel le contrôle associe. Colors configure les couleurs qui correspondent aux valeurs du contrôle.

Les valeurs des entrées sont fournies par les utilisateurs lorsqu’ils ajoutent au formulaire d’élément de travail. Ces valeurs sont transmises à la contribution du contrôle lorsqu’elles sont chargées sur le formulaire.

"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
        }
    }
]

Les propriétés suivantes définissent une entrée utilisateur que la contribution peut utiliser :

• ID : ID unique pour l’entrée.
• description : quelques phrases décrivant l’entrée.
• type (facultatif) : type d’entrée.
  • Valeurs valides :
    • WorkItemField - Indique que l’entrée est un champ Élément de travail. La valeur fournie par l’utilisateur pour cette entrée doit être un nom de référence pour le champ d’élément de travail valide.
• propriétés (facultatif) : propriétés personnalisées pour l’entrée.
  • Clés valides :
    • workItemFieldTypes - Définit un tableau de types de champs pris en charge par cette entrée. Valeurs valides :
      • String
      • Integer
      • DateTime
      • PlainText
      • HTML
      • TreePath
      • History
      • Double
      • Guid
      • Boolean
      • Identity
      • PicklistString
      • PicklistInteger
      • PicklistDouble
• validation : ensemble de propriétés qui définit les valeurs considérées comme valides pour l’entrée.
  • Clés valides :
    • dataType - Définit le type de données de la valeur d’entrée. Valeurs valides pour cette propriété :
      • String
      • Number
      • Boolean
      • Field
    • isRequired - Valeur booléenne, qui indique si l’entrée doit avoir une valeur.

Exemple en JavaScript

Une extension de contrôle fonctionne comme une extension de groupe ou de page avec une différence qu’elle peut prendre certaines entrées utilisateur. Pour lire les valeurs d’entrée utilisateur, utilisez VSS.getConfiguration().witInputs. L’exemple suivant montre comment inscrire un objet appelé lorsque des événements se produisent sur le formulaire d’élément de travail qui peut affecter votre contrôle contribué. Il montre également comment lire les valeurs d’entrée fournies par l’utilisateur pour ce contrôle.

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);

La capture d’écran suivante montre un exemple de contrôle d’élément de travail personnalisé pour le champ Priorité .