Agregar un control personalizado al formulario de elemento de trabajo

Artículo
09/09/2024

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

Los controles personalizados permiten cambiar la forma en que los usuarios ven e interactúan con un campo en el formulario de elemento de trabajo. En el siguiente artículo se explica cómo se creó este control personalizado de ejemplo. En este artículo se muestra cómo crear su propio control personalizado.

Sugerencia

Consulte nuestra documentación más reciente sobre el desarrollo de extensiones mediante el SDK de extensión de Azure DevOps.

Requisitos previos

Incluya azure-devops-extension-sdk en el proyecto:

Instale el SDK a través de npm: npm install azure-devops-extension-sdk.

Inicialícelo en el código de JavaScript:

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

Adición del control personalizado

Para agregar un control a la página principal, agregue una contribución al manifiesto de extensión. El tipo de contribución debe ser ms.vss-work-web.work-item-form-control y debe tener como destino la ms.vss-work-web.work-item-form contribución.

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

El formulario de elemento de trabajo agrega un IFrame para hospedar el control personalizado.

Propiedades

Property	Descripción
`name`	Texto que aparece en el grupo.
`uri`	URI a una página que hospeda el html cargado por el IFrame.
`height`	(Opcional) Define el alto del IFrame. Cuando se omite, es de 50 píxeles.
`inputs`	Los valores que proporciona un usuario dentro del formulario.

Si desea cambiar el tamaño dinámicamente del IFrame, puede usar el resize method disponible en el SDK de cliente.

Un control personalizado en el formulario de elemento de trabajo es otro tipo de contribución, como la contribución de grupo y página. La principal diferencia es que una contribución de control puede tomar un conjunto de entradas de usuario mientras que las contribuciones de grupo y página no pueden.

Control de entradas de contribución

Para definir las entradas de la contribución de control, use la inputs propiedad en el objeto de contribución del manifiesto.

En el ejemplo siguiente verá dos entradas: FieldName y Colors. FieldName especifica con qué campo se asocia el control. Colors configura qué colores se asignan a qué valores del control.

Los valores de las entradas que proporcionan los usuarios cuando agregan al formulario de elemento de trabajo. Estos valores se pasan a la contribución de control cuando se cargan en el formulario.

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

Las siguientes propiedades definen una entrada de usuario que puede usar la contribución:

id : identificador único para la entrada.
description : algunas oraciones que describen la entrada.
type (opcional): tipo de entrada.
- Valores válidos:
  - WorkItemField : indica que la entrada es un campo Elemento de trabajo. El valor proporcionado por el usuario para esta entrada debe ser un nombre de referencia para el campo de elemento de trabajo válido.
properties (opcional): propiedades personalizadas para la entrada.
- Claves válidas:
  - workItemFieldTypes - Define una matriz de tipos de campo que admite esta entrada. Valores válidos:
    - String
    - Integer
    - DateTime
    - PlainText
    - HTML
    - TreePath
    - History
    - Double
    - Guid
    - Boolean
    - Identity
    - PicklistString
    - PicklistInteger
    - PicklistDouble
validation : conjunto de propiedades que define qué valores se consideran válidos para la entrada.
- Claves válidas:
  - dataType : define el tipo de datos del valor de entrada. Valores válidos para esta propiedad:
    - String
    - Number
    - Boolean
    - Field
  - isRequired : valor booleano, que indica si la entrada es necesaria para tener un valor.

Ejemplo de JavaScript

Una extensión de control funciona como un grupo o una extensión de página con una diferencia que puede tomar determinadas entradas de usuario. Para leer los valores de entrada del usuario, use VSS.getConfiguration().witInputs. En el ejemplo siguiente se muestra cómo registrar un objeto al que se llama cuando se producen eventos en el formulario de elemento de trabajo que puede afectar al control contribuido. También muestra cómo leer los valores de entrada proporcionados por el usuario para este control.

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

En la captura de pantalla siguiente se muestra un control de elemento de trabajo personalizado de ejemplo para el campo Prioridad .

Captura de pantalla del control personalizado en el formulario de elemento de trabajo.

Compartir vía