Estender o formulário de item de trabalho

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022

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

• Adicionar um grupo
• Adicionar uma página (separador)
• Adicionar uma ação de menu
• Adicionar um controle personalizado
• Ouça os acontecimentos
• 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 seu manifesto de extensão com o tipo ms.vss-work-web.work-item-form-group direcionado 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 regista um fornecedor que responde a eventos do formulário de item de trabalho. Utiliza o WorkItemFormService para ler os valores do campo quando o item de trabalho carrega.

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 é renderizada como um separador 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, inclua uma contribuição no manifesto da sua extensão, tendo o tipo ms.vss-work-web.work-item-form-page como alvo 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 de 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 por defeito no final da segunda coluna, e as contribuições de página aparecem como o último separador. As contribuições de controlo não são mostradas por defeito – os utilizadores têm de as adicionar manualmente ao formulário. No Azure DevOps Server, consulte Configurar extensões de formulários 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 reticências 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

Ouvir os eventos

Os observadores ouvem eventos de item de trabalho sem qualquer interface de utilizador no formulário. Use observadores para ouvir o evento onSaved, uma vez que os observadores existem fora do formulário e não são eliminados 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 seguinte regista 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 vs. fornecedor de ações

Usar ms.vss-web.action-provider ao carregar dinamicamente itens do menu usando getMenuItems no handler do menu. Usa ms.vss-web.action quando os teus itens do menu estiverem estáticos e definidos no manifesto.

Padrões obsoletos

Os seguintes padrões já não são suportados:

• require("VSS/Events/Document") - não suportado com o New Boards Hub
• SDK.js script tag com usePlatformScripts: true - use o pacote azure-devops-extension-sdk npm ao invés

Conteúdo relacionado

• Adicionar um controle personalizado ao formulário de item de trabalho
• Configurar extensões de formulários de itens de trabalho (no local)
• Referência do manifesto de extensão
• Modelo de contribuição