Dodaj niestandardową kontrolkę 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. W tym artykule pokazano, 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.

Wymagania wstępne

Uwzględnij zestaw azure-devops-extension-sdk w projekcie:

1. Zainstaluj zestaw SDK za pomocą narzędzia npm: npm install azure-devops-extension-sdk.

2. Zainicjuj go w kodzie JavaScript:

   import * as SDK from "azure-devops-extension-sdk";
   SDK.init();
   

Dodaj kontrolkę niestandardową

Aby dodać kontrolkę do strony głównej, dodaj element do 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
        }
    }
],
"manifestVersion": 1.0,
    "scopes": [
        "vso.work"
    ]

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	URI do strony, która hostuje HTML ładowany przez IFrame.
height	(Opcjonalnie) Określa wysokość ramki IFrame. Jeśli zostanie pominięte, 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 jest innym typem wkładu, podobnym do wkładu grupy i strony. Główną różnicą jest to, że wkład kontrolki może przyjmować zestaw danych wejściowych od użytkownika, podczas gdy wkłady grup i stron tego nie mogą.

Kontrola danych wejściowych wkładu

Aby zdefiniować dane wejściowe dla swojej kontroli, użyj właściwości inputs 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, które kolory są przypisane do których 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 komponentu sterującego, gdy jest on ładowany w formularzu.

"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.",
        "type": "string",
        "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 Elementu Roboczego. Wartość podana przez użytkownika dla tego wejścia powinna być nazwą referencyjną 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, gdy zdarzenia występujące w formularzu elementu roboczego mogą wpływać na przydzieloną kontrolkę. Pokazano również, jak odczytywać wartości wejściowe udostępniane przez użytkownika dla tej kontrolki.

import { Control } from "control";
import * as SDK from "azure-devops-extension-sdk";
import * as ExtensionContracts from "azure-devops-extension-api/WorkItemTracking/WorkItemTracking";

let control;

const provider = () => {
    return {
        onLoaded: (workItemLoadedArgs) => {
            // create the control
            const config = SDK.getConfiguration();
            const fieldName = config.witInputs["FieldName"];
            const colors = config.witInputs["Colors"];
            control = new Control(fieldName, colors);
        },
        onFieldChanged: (fieldChangedArgs) => {
            const changedValue = fieldChangedArgs.changedFields[control.getFieldName()];
            if (changedValue !== undefined) {
                control.updateExternal(changedValue);
            }
        }
    };
};

SDK.init();
SDK.ready().then(() => {
    SDK.register(SDK.getContributionId(), provider);
});

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