Étendre le formulaire d’élément de travail

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

Cet article explique comment utiliser des extensions pour personnaliser le formulaire d’élément de travail. Vous pouvez ajouter une action, un observateur, un groupe ou une page au formulaire d’élément de travail dans Azure DevOps.

• Ajouter un groupe à la page principale
• Ajouter une page (onglet)
• Ajouter une action au menu contextuel
• Ajouter un contrôle personnalisé
• Écouter les événements sur le formulaire
• Configurer des contributions dans un formulaire d’élément de travail

Pour obtenir le code source complet, consultez l’exemple d’interface utilisateur dans les exemples d’extension Azure DevOps sur GitHub.

Ajouter un groupe

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

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

Propriétés

Exemple en JavaScript

Cet exemple montre comment inscrire un objet appelé lorsque des événements se produisent sur le formulaire d’élément de travail susceptibles d’affecter votre groupe contribué.

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

Événements

Ajouter une page

Une nouvelle page est affichée sous la forme d’un onglet du formulaire d’élément de travail. De nouvelles pages s’affichent à côté de l’onglet Détails .

Pour ajouter une page au formulaire d’élément de travail, ajoutez une contribution à votre manifeste d’extension. Le type de cette contribution doit être ms.vss-work-web.work-item-form-page et il doit cibler la ms.vss-work-web.work-item-form contribution.

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

Propriétés

Exemple en JavaScript

Consultez l’exemple JavaScript dans la section groupe de formulaires. Le nom de l’objet inscrit doit correspondre à id la contribution.

Événements

Configurer des contributions dans un formulaire d’élément de travail

Dans Azure DevOps Services, par défaut, les extensions de groupe apparaissent à la fin de la deuxième colonne du formulaire et les contributions de page apparaissent après toutes les pages du formulaire d’élément de travail sous forme d’onglet. Les contributions de contrôle ne sont pas affichées dans le formulaire par défaut, les utilisateurs doivent donc les ajouter manuellement au formulaire. Dans Azure DevOps Server, pour afficher/masquer ou déplacer le contrôle, les contributions de groupe et de page dans le formulaire d’élément de travail, consultez Configurer les extensions de formulaire d’élément de travail.

Ajouter une action de menu

Pour ajouter un élément à la barre d’outils de l’élément de travail, ajoutez cette contribution à votre manifeste d’extension. Sélectionnez les points de suspension verticaux dans le formulaire de l’élément de travail pour afficher le menu déroulant.

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

Propriétés

Écouter les événements

Pour ajouter un observateur à l’élément de travail, qui écoute les événements d’élément de travail, ajoutez cette contribution à votre manifeste d’extension. Il n’existe aucune visualisation pour les observateurs sur le formulaire d’élément de travail. C’est la meilleure façon d’écouter l’élément de travail formulaire onSaved événement, car l’observateur vit en dehors du formulaire et n’est pas détruit à la fermeture du formulaire, ce qui peut se produire juste après l’enregistrement.

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

Propriétés

Événements

Exemple HTML/JavaScript

<!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>    

Modifications apportées au hub New Boards

Utiliser les kits SDK les plus récents

Vérifiez que votre extension utilise la dernière version d’azure-devops-extension-sdk

Lorsque vous utilisez le nouveau SDK, vous devez également utiliser le package azure-devops-extension-api pour les API REST. Nous mettons à jour les méthodes et interfaces chaque sprint pour nous assurer qu’elles incluent toutes les fonctionnalités les plus récentes.

Quand utiliser une action ou un fournisseur d’actions

Utilisez cette option ms.vss-web.action-provider lors du chargement dynamique des éléments de menu à l’aide getMenuItems du gestionnaire de menus. Évitez d’utiliser ms.vss-web.action-provider lorsque vos éléments de menu sont statiques et définis dans votre manifeste. À la place ms.vss-web.action , vous devez utiliser.

Le package require("VSS/Events/Document") n’est plus pris en charge

L’importation require("VSS/Events/Document") n’est plus prise en charge avec le New Boards Hub.