Přidání vlastního ovládacího prvku do formuláře pracovní položky

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

Vlastní ovládací prvky umožňují změnit způsob zobrazení uživatelů a interakci s polem ve formuláři pracovní položky. Následující článek vás provede postupem vytvoření tohoto ukázkového vlastního ovládacího prvku. V tomto článku se dozvíte, jak vytvořit vlastní ovládací prvek.

Tip

Projděte si nejnovější dokumentaci k vývoji rozšíření pomocí Azure DevOps Extension SDK.

Požadavky

Do projektu zahrňte sadu azure-devops-extension-sdk:

1. Nainstalujte sadu SDK přes npm: npm install azure-devops-extension-sdk.

2. Inicializujete ho v kódu JavaScriptu:

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

Přidání vlastního ovládacího prvku

Pokud chcete přidat ovládací prvek na hlavní stránku, přidejte příspěvek do manifestu rozšíření. Typ příspěvku by měl být ms.vss-work-web.work-item-form-control a měl by cílit na příspěvek ms.vss-work-web.work-item-form .

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

Formulář pracovní položky přidá prvek typu IFrame k hostování vlastního ovládacího prvku.

Vlastnosti

Vlastnost	Popis
name	Text, který se zobrazí ve skupině
uri	Identifikátor URI na stránku, která je hostitelem kódu HTML načteného elementem IFrame.
height	(Volitelné) Definuje výšku prvku IFrame. Pokud tento parametr vynecháte, bude to 50 pixelů.
inputs	Hodnoty, které uživatel poskytuje ve formuláři.

Pokud chcete dynamicky změnit velikost prvku IFrame, můžete použít dostupnou resize method sadu SDK klienta.

Vlastní ovládací prvek ve formuláři pracovní položky je dalším typem příspěvku, stejně jako příspěvek skupiny a stránky. Hlavní rozdíl spočívá v tom, že příspěvek k řízení může převzít sadu uživatelských vstupů, zatímco skupinové a stránkové příspěvky nemůžou.

Řízení vstupů příspěvků

Chcete-li definovat vstupy pro váš řídicí příspěvek, použijte inputs vlastnost v objektu příspěvku v manifestu.

V následující ukázce vidíte dva vstupy: FieldName a Colors. FieldName určuje, s kterým polem ovládací prvek spojuje. Colors konfiguruje, které barvy se přiřazují k hodnotám v ovládacím prvku.

Hodnoty pro vstupy poskytují uživatelé při přidání do formuláře pracovních položek. Tyto hodnoty se předají komponentě ovládacího prvku při jejím načtení do formuláře.

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

Následující vlastnosti definují uživatelský vstup, který může příspěvek použít:

• ID – jedinečné ID pro vstup.
• popis – několik vět popisujících vstup.
• type (volitelné) – typ vstupu.
  • Platné hodnoty:
    • WorkItemField – Označuje, že vstup je pole pracovní položky. Hodnota zadaná uživatelem pro tento vstup by měla být referenčním názvem platného pole pracovní položky.
• properties (volitelné) – Vlastní vlastnosti pro vstup.
  • Platné klíče:
    • workItemFieldTypes - Definuje pole typů polí, které tento vstup podporuje. Platné hodnoty:
      • String
      • Integer
      • DateTime
      • PlainText
      • HTML
      • TreePath
      • History
      • Double
      • Guid
      • Boolean
      • Identity
      • PicklistString
      • PicklistInteger
      • PicklistDouble
• ověřování – sada vlastností, které definují, které hodnoty jsou považovány za platné pro vstup.
  • Platné klíče:
    • dataType – Definuje datový typ vstupní hodnoty. Platné hodnoty pro tuto vlastnost:
      • String
      • Number
      • Boolean
      • Field
    • isRequired – Logická hodnota, která označuje, jestli je vstup povinný k tomu, aby měl hodnotu.

Ukázka JavaScriptu

Rozšíření ovládacího prvku se chová podobně jako rozšíření pro skupiny nebo stránky, ale s tím rozdílem, že může přijímat určité vstupy od uživatelů. Ke čtení vstupních hodnot uživatele použijte VSS.getConfiguration().witInputs. Následující ukázka ukazuje, jak zaregistrovat objekt, který se volá, když dojde k událostem na formuláři pracovní položky, které mohou ovlivnit váš přispěný ovládací prvek. Také ukazuje, jak číst vstupní hodnoty poskytnuté uživatelem pro tento ovládací prvek.

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

Následující snímek obrazovky ukazuje ukázkový ovládací prvek pro vlastní pracovní položku v poli Priorita.