Aggiungere un controllo personalizzato al modulo dell'elemento di lavoro

Articolo
10/16/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

I controlli personalizzati consentono di modificare il modo in cui gli utenti visualizzano e interagiscono con un campo nel modulo dell'elemento di lavoro. L'articolo seguente illustra come è stato compilato questo controllo personalizzato di esempio. Questo articolo illustra come creare un controllo personalizzato.

Suggerimento

Vedere la documentazione più recente sullo sviluppo di estensioni con Azure DevOps Extension SDK.

Prerequisiti

Includere azure-devops-extension-sdk nel progetto:

Installare l'SDK tramite npm: npm install azure-devops-extension-sdk.

Inizializzarlo nel codice JavaScript:

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

Aggiungere il controllo personalizzato

Per aggiungere un controllo alla pagina principale, aggiungere un contributo al manifesto dell'estensione. Il tipo di contributo dovrebbe essere ms.vss-work-web.work-item-form-control e dovrebbe essere il ms.vss-work-web.work-item-form contributo.

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

Il modulo dell'elemento di lavoro aggiunge un IFrame per ospitare il controllo personalizzato.

Proprietà

Proprietà	Descrizione
`name`	Testo visualizzato nel gruppo.
`uri`	URI a una pagina che ospita il codice HTML caricato dall'IFrame.
`height`	(Facoltativo) Definisce l'altezza dell'IFrame. Quando viene omesso, è di 50 pixel.
`inputs`	I valori forniti da un utente all'interno del modulo.

Se si vuole ridimensionare dinamicamente l'IFrame, è possibile usare il resize method valore disponibile nell'SDK client.

Un controllo personalizzato nel modulo dell'elemento di lavoro è un altro tipo di contributo, ad esempio il contributo di gruppo e pagina. La differenza principale è che un contributo di controllo può accettare un set di input utente mentre i contributi di gruppo e di pagina non possono.

Controllare gli input dei contributi

Per definire gli input per il contributo del controllo, usare la inputs proprietà nell'oggetto contributo nel manifesto.

Nell'esempio seguente vengono visualizzati due input: FieldName e Colors. FieldName specifica il campo a cui viene associato il controllo. Colors configura i colori mappati ai valori del controllo.

I valori per gli input vengono forniti dagli utenti quando aggiungono al modulo dell'elemento di lavoro. Questi valori vengono passati al contributo del controllo quando viene caricato nel modulo.

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

Le proprietà seguenti definiscono un input utente che il contributo può usare:

id : ID univoco per l'input.
description : alcune frasi che descrivono l'input.
type (facoltativo): tipo di input.
- Valori validi:
  - WorkItemField - Indica che l'input è un campo elemento di lavoro. Il valore fornito dall'utente per questo input deve essere un nome di riferimento per il campo dell'elemento di lavoro valido.
proprietà (facoltative): proprietà personalizzate per l'input.
- Chiavi valide:
  - workItemFieldTypes - Definisce una matrice di tipi di campo supportati da questo input. Valori validi:
    - String
    - Integer
    - DateTime
    - PlainText
    - HTML
    - TreePath
    - History
    - Double
    - Guid
    - Boolean
    - Identity
    - PicklistString
    - PicklistInteger
    - PicklistDouble
validation : set di proprietà che definisce quali valori sono considerati validi per l'input.
- Chiavi valide:
  - dataType : definisce il tipo di dati del valore di input. Valori validi per questa proprietà:
    - String
    - Number
    - Boolean
    - Field
  - isRequired - Valore booleano che indica se l'input deve avere un valore.

Esempio in JavaScript

Un'estensione di controllo funziona come un gruppo o un'estensione di pagina con una differenza che può richiedere determinati input utente. Per leggere i valori di input dell'utente, usare VSS.getConfiguration().witInputs. Nell'esempio seguente viene illustrato come registrare un oggetto chiamato quando si verificano eventi nel modulo dell'elemento di lavoro che possono influire sul controllo fornito. Viene inoltre illustrato come leggere i valori di input forniti dall'utente per questo controllo.

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

Lo screenshot seguente mostra un controllo dell'elemento di lavoro personalizzato di esempio per il campo Priorità .

Screenshot del controllo personalizzato nel modulo dell'elemento di lavoro.

Condividi tramite