Udostępnij za pośrednictwem


Rozszerzanie formularza elementu roboczego

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

Dowiedz się, jak dostosować sposób prezentowania użytkownikom formularza elementu roboczego za pośrednictwem współtworzenia w ramach rozszerzenia.

Zobacz przykład interfejsu użytkownika w przykładach rozszerzeń usługi Azure DevOps w witrynie GitHub, aby uzyskać pełne źródło.

Dodaj grupę

Element paska narzędzi w formularzu elementu roboczego.

Aby dodać grupę do strony głównej, dodaj udział w manifeście rozszerzenia. Typ tego udziału powinien być ms.vss-work-web.work-item-form-group i powinien być ukierunkowany na ms.vss-work-web.work-item-form wkład.

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

Właściwości

Właściwości opis
name Tekst wyświetlany w grupie.
uri Identyfikator URI do strony, która hostuje kod HTML wyświetlany w formularzu elementu roboczego i jego skryptach.
height (Opcjonalnie) Definiuje wysokość grupy. Po pominięciu jest to 100%.

Przykład języka JavaScript

W tym przykładzie pokazano, jak zarejestrować obiekt wywoływany w przypadku wystąpienia zdarzeń w formularzu elementu roboczego, który może mieć wpływ na twoją grupę współautorów.

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

Zdarzenia

Zdarzenie Opis zdarzenia Argument Opis argumentu
onFieldChanged Wyzwolony po zmianie pola. Jeśli zmieniono reguły uruchomienia pola, które zaktualizowały inne pola, wszystkie te zmiany są częścią pojedynczego zdarzenia. ID Identyfikator elementu roboczego.
changedFields Tablica z nazwą odwołania wszystkich zmienionych pól. ID Identyfikator elementu roboczego.
onLoaded Wyzwolony po załadowaniu danych w formularzu elementu roboczego, gdy użytkownik otworzy element roboczy lub gdy użytkownik przejdzie do innego elementu roboczego w widoku klasyfikacji. ID Identyfikator elementu roboczego.
onReset Wyzwolony po cofnięciu zmian w elemencie roboczym przez użytkownika. ID Identyfikator elementu roboczego.
onRefreshed Wyzwolono po ręcznym odświeżeniu elementu roboczego przez użytkownika. ID Identyfikator elementu roboczego.
onSaved Wyzwolony po zapisaniu elementu roboczego. W przypadku elementów roboczych w oknie dialogowym należy określić typ "ms.vss-work-web.work-item-notifications", aby zapewnić, że zdarzenie zostanie wyzwolone, ponieważ po zamknięciu okna dialogowego ten typ udziału zostanie zwolniony. Aby uzyskać więcej informacji, zobacz Nasłuchiwanie zdarzeń. ID Identyfikator elementu roboczego.
onUnloaded Wyzwolony przed zamknięciem okna dialogowego lub przed przejściem użytkownika do innego elementu roboczego w widoku klasyfikacji. ID Identyfikator elementu roboczego.

Dodaj stronę

Nowa strona jest renderowana jako karta w formularzu elementu roboczego. Nowe strony są wyświetlane obok karty Szczegóły.

Nowa strona jako karta w formularzu elementu roboczego.

Aby dodać stronę do formularza elementu roboczego, dodaj współtworzenie manifestu rozszerzenia. Typ tego udziału powinien być ms.vss-work-web.work-item-form-page i powinien być ukierunkowany na ms.vss-work-web.work-item-form wkład.

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

Właściwości

Właściwości Opis
name Tekst wyświetlany na stronie karty.
uri Identyfikator URI do strony, która hostuje kod HTML wyświetlany w formularzu elementu roboczego i jego skryptach.

Przykład języka JavaScript

Zobacz przykład języka JavaScript w sekcji grupy formularzy. Nazwa zarejestrowanego obiektu powinna być zgodna id z wartością udziału.

Zdarzenia

Zdarzenie Opis zdarzenia Argument Opis argumentu
onFieldChanged Wyzwolony po zmianie pola. Jeśli zmieniono reguły uruchomienia pola, które zaktualizowały inne pola, wszystkie te zmiany są częścią pojedynczego zdarzenia. ID Identyfikator elementu roboczego.
changedFields Tablica z nazwą odwołania wszystkich zmienionych pól. ID Identyfikator elementu roboczego.
onLoaded Wyzwolony po załadowaniu danych w formularzu elementu roboczego, gdy użytkownik otworzy element roboczy lub gdy użytkownik przejdzie do innego elementu roboczego w widoku klasyfikacji. ID Identyfikator elementu roboczego.
onReset Wyzwolony po cofnięciu zmian w elemencie roboczym przez użytkownika. ID Identyfikator elementu roboczego.
onRefreshed Wyzwolono po ręcznym odświeżeniu elementu roboczego przez użytkownika. ID Identyfikator elementu roboczego.
onSaved Wyzwolony po zapisaniu elementu roboczego. W przypadku elementów roboczych w oknie dialogowym należy określić typ "ms.vss-work-web.work-item-notifications", aby zapewnić, że zdarzenie zostanie wyzwolone, ponieważ po zamknięciu okna dialogowego ten typ udziału zostanie zwolniony. Aby uzyskać więcej informacji, zobacz Nasłuchiwanie zdarzeń. ID Identyfikator elementu roboczego.
onUnloaded Wyzwolony przed zamknięciem okna dialogowego lub przed przejściem użytkownika do innego elementu roboczego w widoku klasyfikacji. ID Identyfikator elementu roboczego.

Konfigurowanie współtworzenia w formularzu elementu roboczego

W usłudze Azure DevOps Services rozszerzenia grupy są domyślnie wyświetlane na końcu drugiej kolumny formularza i współtworzenia strony po wszystkich stronach formularza elementu roboczego jako karcie. Współtworzenie kontrolek nie jest domyślnie wyświetlane w formularzu, dlatego użytkownicy muszą ręcznie dodać je do formularza. W usłudze Azure DevOps Server, aby pokazać/ukryć lub przenieść kontrolkę, grupę i współtworzenie stron w formularzu elementu roboczego, zobacz Konfigurowanie rozszerzeń formularzy elementów roboczych.

Dodaj akcję menu

Dodaj element do paska narzędzi elementu roboczego.

Aby dodać element do paska narzędzi elementu roboczego, dodaj ten wkład do manifestu rozszerzenia. Element zostanie wyświetlony w ... lista rozwijana w prawym górnym rogu formularza elementu roboczego.

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

Właściwości

Właściwości opis
text Tekst wyświetlany na elemencie paska narzędzi.
title Tekst etykietki narzędzia wyświetlany w elemencie menu.
pasek narzędziTekst Tekst wyświetlany po umieszczeniu wskaźnika myszy na elemencie.
uri Identyfikator URI do strony, która rejestruje procedurę obsługi akcji paska narzędzi.
menu Adres URL ikony wyświetlanej w elemencie menu. Względne adresy URL są rozwiązywane przy użyciu identyfikatora baseUri.
grupa Określa, gdzie pojawia się element menu, powiązany z innymi. Elementy paska narzędzi o tej samej nazwie grupy są grupowane i dzielone przez separator z pozostałych elementów.
registeredObjectId (Opcjonalnie) Nazwa zarejestrowanego programu obsługi akcji menu. Domyślnie jest to identyfikator współtworzenia.

Nasłuchiwanie zdarzeń

Aby dodać obserwatora do elementu roboczego, który nasłuchuje zdarzeń elementu roboczego, dodaj ten wkład do manifestu rozszerzenia. Brak wizualizacji dla obserwatorów w formularzu elementu roboczego. Jest to najlepszy sposób nasłuchiwania formularza elementu roboczego na zdarzenie zapisane, ponieważ obserwator żyje poza formularzem i nie zostaje zniszczony po zamknięciu formularza, co może się zdarzyć bezpośrednio po zapisaniu.

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

Właściwości

Właściwości opis
uri Identyfikator URI do strony, która hostuje skrypty nasłuchujące zdarzeń.

Zdarzenia

Zdarzenie Opis zdarzenia Argument Opis argumentu
onFieldChanged Wyzwolony po zmianie pola. Jeśli zmieniono reguły uruchomienia pola, które zaktualizowały inne pola, wszystkie te zmiany są częścią pojedynczego zdarzenia. ID Identyfikator elementu roboczego.
changedFields Tablica z nazwą odwołania wszystkich zmienionych pól. ID Identyfikator elementu roboczego.
onLoaded Wyzwolony po załadowaniu danych w formularzu elementu roboczego, gdy użytkownik otworzy element roboczy lub gdy użytkownik przejdzie do innego elementu roboczego w widoku klasyfikacji. ID Identyfikator elementu roboczego.
onReset Wyzwolony po cofnięciu zmian w elemencie roboczym przez użytkownika. ID Identyfikator elementu roboczego.
onRefreshed Wyzwolono po ręcznym odświeżeniu elementu roboczego przez użytkownika. ID Identyfikator elementu roboczego.
onSaved Wyzwolony po zapisaniu elementu roboczego. W przypadku elementów roboczych w oknie dialogowym należy określić typ "ms.vss-work-web.work-item-notifications", aby zapewnić, że zdarzenie zostanie wyzwolone, ponieważ po zamknięciu okna dialogowego ten typ udziału zostanie zwolniony. Aby uzyskać więcej informacji, zobacz Nasłuchiwanie zdarzeń. ID Identyfikator elementu roboczego.
onUnloaded Wyzwolony przed zamknięciem okna dialogowego lub przed przejściem użytkownika do innego elementu roboczego w widoku klasyfikacji. ID Identyfikator elementu roboczego.

Przykład 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>    

Zmiany w usłudze New Boards Hub

Uwaga

Usługa New Boards Hub jest obecnie dostępna w wersji zapoznawczej, ale jest dostępna dla wszystkich użytkowników. Zdecydowanie zalecamy natychmiastowe włączenie usługi New Boards Hub i przetestowanie wewnętrznych rozszerzeń.

Korzystanie z najnowszych zestawów SDK

Upewnij się, że rozszerzenie korzysta z najnowszej wersji zestawu azure-devops-extension-sdk

W przypadku korzystania z nowego zestawu SDK należy również używać pakietu azure-devops-extension-api dla interfejsów API REST. Aktualizujemy metody i interfejsy każdego przebiegu, aby upewnić się, że zawiera wszystkie najnowsze funkcje.

Kiedy należy używać akcji lub dostawcy akcji

Użyj ms.vss-web.action-provider polecenia podczas dynamicznego ładowania elementów menu przy użyciu programu getMenuItems obsługi menu. Unikaj używania ms.vss-web.action-provider elementów menu jako statycznych i zdefiniowanych w manifeście. Zamiast tego ms.vss-web.action należy użyć polecenia .

Pakiet require("VSS/Events/Document") nie jest już obsługiwany

require("VSS/Events/Document") importowanie nie jest już obsługiwane w usłudze New Boards Hub.