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

Článek
10/16/2024

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

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í sady SDK rozšíření Azure DevOps.

Požadavky

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

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

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 do manifestu rozšíření příspěvek. 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 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, jako je 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, které pole ovládací prvek přidruží. Colors konfiguruje, které barvy se mapují na hodnoty v ovládacím prvku.

Hodnoty pro vstupy, které uživatelé získají, když přidají do formuláře pracovní položky. Tyto hodnoty se předají příspěvku ovládacího prvku při 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žka. 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 funguje jako skupina nebo rozšíření stránky s jedním rozdílem, že může přijímat určité uživatelské vstupy. 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ž na formuláři pracovní položky dojde k událostem, které mohou ovlivnit váš ovládací prvek přispěl. 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ý vlastní ovládací prvek pracovní položky pro pole Priorita.

Snímek obrazovky vlastního ovládacího prvku ve formuláři pracovní položky

Sdílet prostřednictvím