擴充工作項目表單

Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022

本文說明如何使用延伸模組來自訂工作專案表單。 您可以將動作、觀察者、群組或頁面新增至 Azure DevOps 中的工作專案表單。

• 將群組新增至主頁面
• 新增頁面 （索引標籤）
• 將動作新增至操作功能表
• 新增自定義控制件
• 監聽窗體上的事件
• 在工作項目表單中設定貢獻

如需完整的原始程式碼，請參閱 GitHub 上的 Azure DevOps 擴充功能範例中的 UI 範例。

新增群組

若要將群組新增至主頁面，請將項目新增至擴充功能清單。 此貢獻的類型應該是ms.vss-work-web.work-item-form-group，而且它應該針對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
       }
   }
]

屬性

JavaScript 範例

此範例展示如何註冊一個當工作項目表單上發生可能影響您貢獻群組的事件時會被呼叫的物件。

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

// Get the WorkItemFormService.  This service allows you to get/set fields/links on the 'active' work item (the work item
// that currently is displayed in the UI).
async function getWorkItemFormService()
{
    const workItemFormService = await SDK.getService<IWorkItemFormService>(WorkItemTrackingServiceIds.WorkItemFormService);
    return workItemFormService;
}

// Register a listener for the work item group contribution after initializing the SDK.
SDK.register(SDK.getContributionId(), function () {
    return {
        // Called when the active work item is modified
        onFieldChanged: function(args) {
            $(".events").append($("<div/>").text("onFieldChanged - " + JSON.stringify(args)));
        },
        
        // Called when a new work item is being loaded in the UI
        onLoaded: function (args) {

            getWorkItemFormService().then(function(service) {            
                // Get the current values for a few of the common fields
                service.getFieldValues(["System.Id", "System.Title", "System.State", "System.CreatedDate"]).then(
                    function (value) {
                        $(".events").append($("<div/>").text("onLoaded - " + JSON.stringify(value)));
                    });
            });
        },
        
        // Called when the active work item is being unloaded in the UI
        onUnloaded: function (args) {
            $(".events").empty();
            $(".events").append($("<div/>").text("onUnloaded - " + JSON.stringify(args)));
        },
        
        // Called after the work item has been saved
        onSaved: function (args) {
            $(".events").append($("<div/>").text("onSaved - " + JSON.stringify(args)));
        },
        
        // Called when the work item is reset to its unmodified state (undo)
        onReset: function (args) {
            $(".events").append($("<div/>").text("onReset - " + JSON.stringify(args)));
        },
        
        // Called when the work item has been refreshed from the server
        onRefreshed: function (args) {
            $(".events").append($("<div/>").text("onRefreshed - " + JSON.stringify(args)));
        }
    }
});

事件

新增頁面

新的頁面會作為標籤呈現在工作項目表單上。 詳細 索引標籤旁會出現新的頁面。

若要將頁面新增至工作項目表單，請將貢獻新增至延伸模組指令清單。 此貢獻的類型應該是ms.vss-work-web.work-item-form-page，而且它應該針對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"
        } 
    }
]

屬性

JavaScript 範例

請參閱窗體群組一節中的 JavaScript 範例。 已註冊物件的名稱應該與貢獻中的id相符。

事件

在工作項目表單中設定參與專案

根據預設，在 Azure DevOps Services 中，群組延伸模組會出現在窗體的第二個數據行結尾，而頁面貢獻會顯示在所有工作專案表單頁面之後做為索引卷標。根據預設，控件貢獻不會顯示在窗體中，因此用戶必須手動將它們新增至表單。 在 Azure DevOps Server 中，若要在工作專案表單中顯示/隱藏或移動控件、群組和頁面貢獻，請參閱 設定工作專案表單延伸模組。

新增選單操作

若要將專案新增至工作項目的工具列，請將此功能新增至擴充功能清單。 請選取工作項目表單中的垂直省略號，來查看選單下拉選項。

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

屬性

監聽事件

若要將觀察者新增至工作專案以接收工作專案事件，請將此貢獻新增至擴充功能清單。 工作項目表單上沒有觀察者的可視化。 這是在 onSaved 事件上接聽工作專案窗體的最佳方式，因為觀察者位於窗體外部，而且即使在儲存後窗體關閉時，也不會損毀。

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

屬性

事件

HTML/JavaScript 範例

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <title>Work item extension page sample</title>
</head>

<body>
    <script src="sdk/scripts/SDK.js"></script>

    <script>
        SDK.init({
            usePlatformScripts: true
        });
        
        SDK.ready(function () {
             // Register a listener for the work item page contribution.
            SDK.register(SDK.getContributionId(), function () {
                return {
                    // Called when the active work item is modified
                    onFieldChanged: function(args) {
                        
                    },
                    
                    // Called when a new work item is being loaded in the UI
                    onLoaded: function (args) {
            
                    },
                    
                    // Called when the active work item is being unloaded in the UI
                    onUnloaded: function (args) {
            
                    },
                    
                    // Called after the work item has been saved
                    onSaved: function (args) {
            
                    },
                    
                    // Called when the work item is reset to its unmodified state (undo)
                    onReset: function (args) {
            
                    },
                    
                    // Called when the work item has been refreshed from the server
                    onRefreshed: function (args) {
            
                    }
                }
            });    
        });
     </script>
</body>
</html>    

新看板中心的變更

使用最新的 SDK

請確定您的擴充功能使用的是最新版的 azure-devops-extension-sdk

使用新的 SDK 時，您也應該使用適用於 REST API 的 azure-devops-extension-api 套件。 我們會在每個開發衝刺期間更新方法和介面，確保它包含所有最新功能。

使用動作或動作提供者的時機

使用 ms.vss-web.action-provider 在選單處理程式上動態載入選單項目時使用 getMenuItems。 避免在您的選單項目已在清單檔中定義且為靜態時使用 ms.vss-web.action-provider 。 請改 ms.vss-web.action 用 。

不再支援套件require("VSS/Events/Document")

新版 Boards Hub 不再支援匯入 require("VSS/Events/Document")。