Estender o formulário do item de trabalho

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

Use extensões para personalizar o formulário de item de trabalho adicionando grupos, páginas, ações de menu, observadores ou controles personalizados.

• Adicionar um grupo
• Adicionar uma página (guia)
• Adicionar uma ação de menu
• Adicionar um controle personalizado
• Escutar eventos
• Configurar contribuições

Para obter o código-fonte completo, consulte o exemplo de interface do usuário nos exemplos de extensão do Azure DevOps no GitHub.

Adicionar um grupo

Para adicionar um grupo à página principal, adicione uma contribuição ao manifesto de extensão com o tipo ms.vss-work-web.work-item-form-group direcionado para ms.vss-work-web.work-item-form.

"contributions": [
   {  
       "id": "sample-work-item-form-group",
       "type": "ms.vss-work-web.work-item-form-group",
       "description": "Custom work item form group",
       "targets": [
           "ms.vss-work-web.work-item-form"
       ],
       "properties": {
           "name": "My Group",
           "uri": "workItemGroup.html",
           "height": 600
       }
   }
]

Propriedades

Exemplo de JavaScript

Este exemplo registra um provedor que responde a eventos de formulário de item de trabalho. Ele usa o WorkItemFormService para ler os valores de campo quando o item de trabalho é carregado.

import { IWorkItemFormService, WorkItemTrackingServiceIds } from "azure-devops-extension-api/WorkItemTracking";
import * as SDK from "azure-devops-extension-sdk";

async function getWorkItemFormService(): Promise<IWorkItemFormService> {
    return await SDK.getService<IWorkItemFormService>(WorkItemTrackingServiceIds.WorkItemFormService);
}

SDK.init();

SDK.ready().then(() => {
    SDK.register(SDK.getContributionId(), () => {
        return {
            // Called when the active work item is modified
            onFieldChanged: (args) => {
                console.log("onFieldChanged", JSON.stringify(args));
            },

            // Called when a new work item is being loaded in the UI
            onLoaded: async (args) => {
                const service = await getWorkItemFormService();
                const values = await service.getFieldValues([
                    "System.Id", "System.Title", "System.State", "System.CreatedDate"
                ]);
                console.log("onLoaded", JSON.stringify(values));
            },

            // Called when the active work item is being unloaded in the UI
            onUnloaded: (args) => {
                console.log("onUnloaded", JSON.stringify(args));
            },

            // Called after the work item has been saved
            onSaved: (args) => {
                console.log("onSaved", JSON.stringify(args));
            },

            // Called when the work item is reset to its unmodified state (undo)
            onReset: (args) => {
                console.log("onReset", JSON.stringify(args));
            },

            // Called when the work item has been refreshed from the server
            onRefreshed: (args) => {
                console.log("onRefreshed", JSON.stringify(args));
            }
        };
    });
});

Eventos

Adicionar uma página

Uma nova página é exibida como uma aba no formulário do item de trabalho. Novas páginas aparecem ao lado da guia Detalhes .

Para adicionar uma página ao formulário do item de trabalho, adicione uma contribuição ao manifesto de extensão com o tipo ms.vss-work-web.work-item-form-page destinando-se a ms.vss-work-web.work-item-form:

"contributions": [
    {  
        "id": "sample-work-item-form-page",
        "type": "ms.vss-work-web.work-item-form-page",
        "description": "Custom work item form page",
        "targets": [
            "ms.vss-work-web.work-item-form"
        ],
        "properties": {
            "name": "My Page",
            "uri": "workItemPage.html"
        } 
    }
]

Propriedades

Exemplo de JavaScript

Consulte o exemplo de JavaScript na seção do grupo de formulários. O nome do objeto registrado deve corresponder ao id da contribuição.

Eventos

Configurar contribuições

No Azure DevOps Services, as extensões de grupo aparecem no final da segunda coluna por padrão e as contribuições de página aparecem como a última guia. As contribuições de controle não são mostradas por padrão – os usuários devem adicioná-las manualmente ao formulário. No Servidor do Azure DevOps, consulte Configurar extensões de formulário de item de trabalho para mostrar, ocultar ou mover contribuições.

Adicionar ação de menu

Para adicionar um item à barra de ferramentas do item de trabalho, adicione essa contribuição ao manifesto da extensão. O item aparece no menu suspenso de três pontos verticais (...).

"contributions": [
   {  
      "id": "sample-work-item-menu",  
      "type": "ms.vss-web.action",  
      "description": "Sample toolbar item which updates the title of a work item",  
      "targets": [  
          "ms.vss-work-web.work-item-context-menu"  
      ],  
      "properties": {  
          "text": "Try me!",  
          "title": "Updates the title of the work item from the extension",  
          "toolbarText": "Try me!",  
          "icon": "images/show-properties.png",  
          "uri": "menu-workItemToolbarButton.html"  
      }  
   }
]

Propriedades

Ouça os eventos

Observadores ouvem eventos de item de trabalho sem nenhuma interface do usuário no formulário. Use observadores para escutar o evento onSaved, já que os observadores vivem fora do formulário e não são destruídos quando a caixa de diálogo do formulário é fechada.

"contributions": [
   {  
       "id": "sample-work-item-form-observer",
       "type": "ms.vss-work-web.work-item-notifications",
       "description": "Gets events about the current work item form for the 'Try Me!' toolbar button",
       "targets": [
           "ms.vss-work-web.work-item-form"
       ],
       "properties": {
           "uri": "myformobserver.html"
       }
   }
]

Propriedades

Eventos

Exemplo de JavaScript

O exemplo a seguir registra um observador usando o SDK moderno:

import * as SDK from "azure-devops-extension-sdk";

SDK.init();

SDK.ready().then(() => {
    SDK.register(SDK.getContributionId(), () => {
        return {
            onFieldChanged: (args) => {
                // Handle field changes
            },
            onLoaded: (args) => {
                // Handle work item loaded
            },
            onUnloaded: (args) => {
                // Handle work item unloaded
            },
            onSaved: (args) => {
                // Handle work item saved
            },
            onReset: (args) => {
                // Handle work item reset (undo)
            },
            onRefreshed: (args) => {
                // Handle work item refreshed
            }
        };
    });
});

Notas de compatibilidade

Ação versus provedor de ação

Use ms.vss-web.action-provider ao carregar dinamicamente itens de menu usando getMenuItems no manipulador de menu. Use ms.vss-web.action quando os itens de menu estiverem estáticos e definidos no manifesto.

Padrões preteridos

Não há mais suporte para os seguintes padrões:

• require("VSS/Events/Document") – não é compatível com o Hub de Novos Quadros
• SDK.js tag de script com usePlatformScripts: true - use o pacote npm azure-devops-extension-sdk em seu lugar

Conteúdo relacionado

• Adicionar um controle personalizado ao formulário de item de trabalho
• Configurar extensões para formulários de itens de trabalho (local)
• Referência de Manifesto da Extensão
• Modelo de Contribuição