作業項目フォームの拡張

Azure DevOps Services |Azure DevOps Server 2022 および Azure DevOps Server 2019

この記事では、拡張機能を使用して、作業項目フォームをユーザーに表示する方法をカスタマイズする方法について説明します。 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 では、既定では、グループ拡張機能はフォームの 2 列目の末尾に表示され、すべての作業項目フォーム ページの後にタブとしてページコントリビューションが表示されます。コントロールの投稿は既定ではフォームに表示されないため、ユーザーは手動でフォームに追加する必要があります。 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>    

新しい Boards Hub での変更

最新の SDK を使用する

拡張機能で最新バージョンの azure-devops-extension-sdk が使用されていることを確認します

新しい SDK を使用する場合は、REST API 用の azure-devops-extension-api パッケージも使用する必要があります。 すべてのスプリントに最新の機能がすべて含まれるように、メソッドとインターフェイスを更新します。

action と action-provider の使い分け

メニュー ハンドラーでms.vss-web.action-providerを使用してメニュー項目を動的に読み込む場合は、getMenuItemsを使用します。 メニュー項目が静的であり、マニフェストで定義されている場合は、 ms.vss-web.action-provider を使用しないでください。 代わりに、 ms.vss-web.action を使用する必要があります。

パッケージ require("VSS/Events/Document") はサポートされなくなりました

require("VSS/Events/Document") インポートは、新しい Boards Hub ではサポートされなくなりました。