作業項目フォームにカスタム コントロールを追加する

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

ユーザー設定コントロールを使用すると、ユーザーが作業項目フォームのフィールドを表示および操作する方法を変更できます。 次の記事では、このサンプル カスタム コントロールの作成方法について説明します。 独自のカスタム コントロールを構築する方法について説明します。

ヒント

Azure DevOps 拡張機能 SDK を使用した拡張機能開発に関する最新のドキュメントを確認してください。

カスタム コントロールを追加する

メイン ページにコントロールを追加するには、拡張機能マニフェストに投稿を追加します。 投稿の種類は ms.vss-work-web.work-item-form-control 、投稿の対象 ms.vss-work-web.work-item-form にする必要があります。

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

作業項目フォームは、カスタム コントロールをホストする IFrame を追加します。

Properties

Property	説明
name	グループに表示されるテキスト。
uri	IFrame によって読み込まれる html をホストするページへの URI。
height	(省略可能)IFrame の高さを定義します。 省略すると、50 ピクセルになります。
inputs	ユーザーがフォーム内で指定する値。

IFrame のサイズを動的に変更する場合は、クライアント SDK で使用可能なサイズを使用 resize method できます。

作業項目フォームのカスタム コントロールは、グループやページの投稿などの別の種類の投稿です。 メイン違いは、グループとページのコントリビューションでは、コントロールのコントリビューションで一連のユーザー入力を受け取ることができるということです。

コントリビューション入力を制御する

コントロールコントリビューションの入力を定義するには、マニフェストの inputs コントリビューション オブジェクトのプロパティを使用します。

次の例では、次の 2 つの入力が表示されます FieldNameColors。 FieldName は、コントロールが関連付けるフィールドを指定します。 Colors は、コントロール内のどの値にマップされる色を構成します。

入力の値は、ユーザーが作業項目フォームに追加したときに提供されます。 これらの値は、フォームに読み込まれるとコントロールのコントリビューションに渡されます。

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

次のプロパティは、コントリビューションで使用できるユーザー入力を定義します。

• id - 入力の一意の ID。
• description - 入力を記述するいくつかの文。
• type (省略可能) - 入力の種類。
  • 有効な値:
    • WorkItemField - 入力が作業項目フィールドであることを示します。 この入力に対してユーザーが指定する値は、有効な作業項目フィールドの参照名である必要があります。
• properties (省略可能) - 入力のカスタム プロパティ。
  • 有効なキー:
    • workItemFieldTypes - この入力でサポートされるフィールド型の配列を定義します。 有効な値:
      • String
      • Integer
      • DateTime
      • PlainText
      • HTML
      • TreePath
      • History
      • Double
      • Guid
      • Boolean
      • Identity
      • PicklistString
      • PicklistInteger
      • PicklistDouble
• validation - 入力に対して有効と見なされる値を定義するプロパティのセット。
  • 有効なキー:
    • dataType - 入力値のデータ型を定義します。 このプロパティの有効な値:
      • String
      • Number
      • Boolean
      • Field
    • isRequired - ブール値。入力に値が必要かどうかを示します。

JavaScript のサンプル

コントロール拡張機能は、特定のユーザー入力を受け取ることができる 1 つの違いを持つグループまたはページ拡張機能と同様に機能します。 ユーザー入力値を読み取るために使用 VSS.getConfiguration().witInputsします。 次の例は、投稿されたコントロールに影響する可能性がある作業項目フォームでイベントが発生したときに呼び出されるオブジェクトを登録する方法を示しています。 また、このコントロールに対してユーザーによって提供される入力値を読み取る方法も示します。

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);

次のスクリーンショットは、[優先度] フィールドのカスタム作業項目コントロールの例を示しています。