Partager via


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

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

Découvrez comment personnaliser la façon dont le formulaire d’élément de travail est présenté aux utilisateurs via des contributions effectuées via une extension.

Consultez l’exemple d’interface utilisateur dans les exemples d’extension Azure DevOps sur GitHub pour obtenir la source complète.

Ajouter un groupe

Élément de barre d’outils sous forme d’élément de travail.

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

Property Description
name Texte qui apparaît sur le groupe.
uri URI vers une page qui héberge le code html qui s’affiche sur le formulaire d’élément de travail et ses scripts.
height (Facultatif) Définit la hauteur du groupe. En cas d’omission, il est de 100 %.

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 qui peut avoir un impact sur 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

Événement Description de l'événement Argument Description des arguments
onFieldChanged Déclenché après la modification d’un champ. Si le changement de champ a exécuté des règles qui ont mis à jour d’autres champs, toutes ces modifications font partie d’un événement unique. id L'ID de l'élément de travail.
changedFields Tableau avec le nom de référence de tous les champs modifiés. id L'ID de l'élément de travail.
onLoaded Déclenché après le chargement des données dans le formulaire d’élément de travail, lorsque l’utilisateur ouvre un élément de travail ou lorsque l’utilisateur accède à un autre élément de travail dans la vue de triage. id L'ID de l'élément de travail.
onReset Déclenché après que l’utilisateur annule les modifications apportées à l’élément de travail. id L'ID de l'élément de travail.
onRefreshed Déclenché après l’actualisation manuelle de l’élément de travail par l’utilisateur. id L'ID de l'élément de travail.
onSaved Déclenché après l’enregistrement d’un élément de travail. Pour les éléments de travail d’une boîte de dialogue, vous devez cibler le type « ms.vss-work-web.work-item-notifications » pour vous assurer que l’événement se déclenche depuis la fermeture du dialogue, ce type de contribution est déchargé. Pour plus d’informations, consultez Écouter les événements. id L'ID de l'élément de travail.
onUnloaded Déclenché avant que l’utilisateur ferme la boîte de dialogue, ou avant que l’utilisateur ne se déplace vers un autre élément de travail dans la vue de triage. id L'ID de l'élément de travail.

Ajouter une page

Une nouvelle page est affichée sous la forme d’un onglet du formulaire d’élément de travail. Les nouvelles pages apparaissent en regard de l’onglet Détails.

Nouvelle page sous la forme d’un onglet du formulaire d’élément de travail.

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

Property Description
name Texte qui s’affiche sur la page de l’onglet.
URI URI vers une page qui héberge le code html qui s’affiche sur le formulaire d’élément de travail et ses scripts.

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

Événement Description de l'événement Argument Description des arguments
onFieldChanged Déclenché après la modification d’un champ. Si le changement de champ a exécuté des règles qui ont mis à jour d’autres champs, toutes ces modifications font partie d’un événement unique. id L'ID de l'élément de travail.
changedFields Tableau avec le nom de référence de tous les champs modifiés. id L'ID de l'élément de travail.
onLoaded Déclenché après le chargement des données dans le formulaire d’élément de travail, lorsque l’utilisateur ouvre un élément de travail ou lorsque l’utilisateur accède à un autre élément de travail dans la vue de triage. id L'ID de l'élément de travail.
onReset Déclenché après que l’utilisateur annule les modifications apportées à l’élément de travail. id L'ID de l'élément de travail.
onRefreshed Déclenché après l’actualisation manuelle de l’élément de travail par l’utilisateur. id L'ID de l'élément de travail.
onSaved Déclenché après l’enregistrement d’un élément de travail. Pour les éléments de travail d’une boîte de dialogue, vous devez cibler le type « ms.vss-work-web.work-item-notifications » pour vous assurer que l’événement se déclenche depuis la fermeture du dialogue, ce type de contribution est déchargé. Pour plus d’informations, consultez Écouter les événements. id L'ID de l'élément de travail.
onUnloaded Déclenché avant que l’utilisateur ferme la boîte de dialogue, ou avant que l’utilisateur ne se déplace vers un autre élément de travail dans la vue de triage. id L'ID de l'élément de travail.

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 des contributions de page apparaissent après toutes les pages de 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, de sorte que les utilisateurs doivent 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

Ajoutez un élément à la barre d’outils de l’élément de travail.

Pour ajouter un élément à la barre d’outils de l’élément de travail, ajoutez cette contribution à votre manifeste d’extension. L’élément apparaît dans le ... liste déroulante en haut à droite du formulaire d’élément de travail.

"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

Property Description
texte Texte qui apparaît dans l’élément de barre d’outils.
title Texte d’info-bulle qui s’affiche sur l’élément de menu.
toolbarText Texte qui s’affiche lorsque l’élément est survolé.
URI URI vers une page qui inscrit le gestionnaire d’actions de barre d’outils.
icône URL vers une icône qui apparaît dans l’élément de menu. Les URL relatives sont résolues à l’aide de baseUri.
groupe Détermine l’emplacement d’affichage de l’élément de menu, associé à d’autres personnes. Les éléments de barre d’outils portant le même nom de groupe sont regroupés et divisés par un séparateur du reste des éléments.
registeredObjectId (Facultatif) Nom du gestionnaire d’actions de menu inscrites. La valeur par défaut est l’ID de contribution.

É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. Il s’agit de la meilleure façon d’écouter le formulaire d’élément de travail sur L’événement enregistré, car l’observateur vit en dehors du formulaire et n’est pas détruit lorsque le formulaire se ferme, 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

Property Description
uri URI vers une page qui héberge les scripts à l’écoute des événements.

Événements

Événement Description de l'événement Argument Description des arguments
onFieldChanged Déclenché après la modification d’un champ. Si le changement de champ a exécuté des règles qui ont mis à jour d’autres champs, toutes ces modifications font partie d’un événement unique. id L'ID de l'élément de travail.
changedFields Tableau avec le nom de référence de tous les champs modifiés. id L'ID de l'élément de travail.
onLoaded Déclenché après le chargement des données dans le formulaire d’élément de travail, lorsque l’utilisateur ouvre un élément de travail ou lorsque l’utilisateur accède à un autre élément de travail dans la vue de triage. id L'ID de l'élément de travail.
onReset Déclenché après que l’utilisateur annule les modifications apportées à l’élément de travail. id L'ID de l'élément de travail.
onRefreshed Déclenché après l’actualisation manuelle de l’élément de travail par l’utilisateur. id L'ID de l'élément de travail.
onSaved Déclenché après l’enregistrement d’un élément de travail. Pour les éléments de travail d’une boîte de dialogue, vous devez cibler le type « ms.vss-work-web.work-item-notifications » pour vous assurer que l’événement se déclenche depuis la fermeture du dialogue, ce type de contribution est déchargé. Pour plus d’informations, consultez Écouter les événements. id L'ID de l'élément de travail.
onUnloaded Déclenché avant que l’utilisateur ferme la boîte de dialogue, ou avant que l’utilisateur ne se déplace vers un autre élément de travail dans la vue de triage. id L'ID de l'élément de travail.

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

Remarque

New Boards Hub est actuellement en préversion, mais il est disponible pour tous. Nous vous suggérons vivement d’activer immédiatement New Boards Hub et de tester vos extensions internes.

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

require("VSS/Events/Document") l’importation n’est plus prise en charge avec new boards Hub.