Dodawanie kontrolki niestandardowej do formularza elementu roboczego

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

Kontrolki niestandardowe umożliwiają zmianę sposobu wyświetlania i interakcji użytkowników z polem w formularzu elementu roboczego. W poniższym artykule przedstawiono sposób tworzenia tej przykładowej kontrolki niestandardowej. Dowiedz się, jak utworzyć własną kontrolkę niestandardową.

Napiwek

Zapoznaj się z naszą najnowszą dokumentacją dotyczącą programowania rozszerzeń przy użyciu zestawu SDK rozszerzenia usługi Azure DevOps.

Dodawanie kontrolki niestandardowej

Aby dodać kontrolkę do strony głównej, dodaj współtworzenie manifestu rozszerzenia. Typ udziału powinien być ms.vss-work-web.work-item-form-control i powinien być ukierunkowany na ms.vss-work-web.work-item-form wkład.

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

Formularz elementu roboczego dodaje element IFrame do hostowania kontrolki niestandardowej.

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 ładowany przez element IFrame.
height	(Opcjonalnie) Definiuje wysokość elementu IFrame. Po pominięciu jest to 50 pikseli.
inputs	Wartości, które użytkownik podaje w formularzu.

Jeśli chcesz dynamicznie zmieniać rozmiar elementu IFrame, możesz użyć resize method elementu dostępnego w zestawie SDK klienta.

Niestandardowa kontrolka w formularzu elementu roboczego to inny typ współtworzenia, taki jak współtworzenie grupy i strony. Główną różnicą jest to, że udział kontrolki może przyjąć zestaw danych wejściowych użytkownika, podczas gdy udział grup i stron nie może.

Kontrolowanie danych wejściowych współtworzenia

Aby zdefiniować dane wejściowe dla udziału kontrolki, użyj inputs właściwości w obiekcie contribution w manifeście.

W poniższym przykładzie są widoczne dwa dane wejściowe: FieldName i Colors. FieldName określa, z którym polem kojarzy się kontrolka. Colors Konfiguruje kolory mapowania wartości w kontrolce.

Wartości danych wejściowych są dostarczane przez użytkowników podczas dodawania ich do formularza elementu roboczego. Te wartości są przekazywane do udziału kontrolki po załadowaniu go do formularza.

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

Następujące właściwości definiują dane wejściowe użytkownika, których może używać współtworzenie:

• id — unikatowy identyfikator danych wejściowych.
• description — kilka zdań opisujących dane wejściowe.
• type (opcjonalnie) — typ danych wejściowych.
  • Prawidłowe wartości:
    • WorkItemField — Wskazuje, że dane wejściowe są polem Element roboczy. Wartość podana przez użytkownika dla tych danych wejściowych powinna być nazwą odwołania dla prawidłowego pola elementu roboczego.
• properties (opcjonalnie) — właściwości niestandardowe dla danych wejściowych.
  • Prawidłowe klucze:
    • workItemFieldTypes — Definiuje tablicę typów pól, które obsługują te dane wejściowe. Prawidłowe wartości:
      • String
      • Integer
      • DateTime
      • PlainText
      • HTML
      • TreePath
      • History
      • Double
      • Guid
      • Boolean
      • Identity
      • PicklistString
      • PicklistInteger
      • PicklistDouble
• validation — zestaw właściwości definiujących, które wartości są uznawane za prawidłowe dla danych wejściowych.
  • Prawidłowe klucze:
    • dataType - Definiuje typ danych wartości wejściowej. Prawidłowe wartości dla tej właściwości:
      • String
      • Number
      • Boolean
      • Field
    • isRequired - Wartość logiczna, która wskazuje, czy dane wejściowe są wymagane do posiadania wartości.

Przykład języka JavaScript

Rozszerzenie kontrolki działa jak rozszerzenie grupy lub strony z jedną różnicą, że może przyjmować pewne dane wejściowe użytkownika. Aby odczytać wartości wejściowe użytkownika, użyj polecenia VSS.getConfiguration().witInputs. W poniższym 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ą kontrolkę. Pokazano również, jak odczytywać wartości wejściowe udostępniane przez użytkownika dla tej kontrolki.

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

Poniższy zrzut ekranu przedstawia przykładową niestandardową kontrolkę elementu roboczego dla pola Priorytet .