Adicionar um controle personalizado ao formulário de item de trabalho

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

Os controles personalizados permitem alterar como os usuários exibem e interagem com um campo no formulário de item de trabalho. O artigo a seguir orienta você sobre como esse controle personalizado de exemplo foi criado. Saiba como criar seu próprio controle personalizado.

Dica

Confira nossa documentação mais recente sobre o desenvolvimento de extensão usando o SDK da Extensão do Azure DevOps.

Adicionar o controle personalizado

Para adicionar um controle à página principal, adicione uma contribuição ao manifesto de extensão. O tipo de contribuição deve ser ms.vss-work-web.work-item-form-control e deve ser direcionado à ms.vss-work-web.work-item-form contribuição.

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

O formulário de item de trabalho adiciona um IFrame para hospedar o controle personalizado.

Propriedades

Propriedade	Descrição
name	Texto que aparece no grupo.
uri	URI para uma página que hospeda o html carregado pelo IFrame.
height	(Opcional) Define a altura do IFrame. Quando omitido, são 50 pixels.
inputs	Os valores que um usuário fornece no formulário.

Se você deseja redimensionar dinamicamente o IFrame, você pode usar o resize method disponível no SDK do cliente.

Um controle personalizado no formulário de item de trabalho é outro tipo de contribuição, como contribuição de página de grupo e de nome. A principal diferença é que uma contribuição de controle pode receber um conjunto de entradas do usuário, enquanto as contribuições de grupo e página não podem.

Controle de contribuições de insumos

Para definir as entradas para sua contribuição de controle, use a inputs propriedade no objeto de contribuição no manifesto.

No exemplo a seguir, você vê duas entradas: FieldName e Colors. FieldName Especifica a qual campo o controle se associa. Colors Configura quais cores mapeiam para quais valores no controle.

Os valores das entradas são fornecidos pelos usuários quando eles são adicionados ao formulário de item de trabalho. Esses valores são passados para a contribuição de controle quando ela é carregada no formulário.

"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.",
        "validation": {
            "dataType": "String",
            "isRequired": false
        }
    }
]

As propriedades a seguir definem uma entrada de usuário que a contribuição pode usar:

• id - Um ID exclusivo para a entrada.
• description - Algumas frases descrevendo a entrada.
• type (opcional) - O tipo de entrada.
  • Valores válidos:
    • WorkItemField - Indica que a entrada é um campo Item de Trabalho. O valor fornecido pelo usuário para essa entrada deve ser um nome de referência para o campo de item de trabalho válido.
• propriedades (opcional) - Propriedades personalizadas para a entrada.
  • Chaves válidas:
    • workItemFieldTypes - Define uma matriz de tipos de campo que essa entrada suporta. Valores válidos:
      • String
      • Integer
      • DateTime
      • PlainText
      • HTML
      • TreePath
      • History
      • Double
      • Guid
      • Boolean
      • Identity
      • PicklistString
      • PicklistInteger
      • PicklistDouble
• validation - Um conjunto de propriedades que define quais valores são considerados válidos para a entrada.
  • Chaves válidas:
    • dataType - Define o tipo de dados do valor de entrada. Valores válidos para esta propriedade:
      • String
      • Number
      • Boolean
      • Field
    • isRequired - Um valor booleano, que indica se a entrada é necessária para ter um valor.

Exemplo de JavaScript

Uma extensão de controle funciona como uma extensão de grupo ou página com uma diferença de que pode receber determinadas entradas do usuário. Para ler os valores de entrada do usuário, use VSS.getConfiguration().witInputs. O exemplo a seguir mostra como registrar um objeto que é chamado quando ocorrem eventos no formulário de item de trabalho que podem afetar seu controle contribuído. Ele também mostra como ler valores de entrada fornecidos pelo usuário para esse controle.

import { Control } from "control";
import * as ExtensionContracts from "TFS/WorkItemTracking/ExtensionContracts";

var control: Control;

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

VSS.register(VSS.getContribution().id, provider);

A captura de tela a seguir mostra um exemplo de controle de item de trabalho personalizado para o campo Prioridade .