次の方法で共有

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

  • [アーティクル]

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

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

ヒント

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

前提条件

プロジェクトに azure-devops-extension-sdk を含めます。

  1. npm: npm install azure-devops-extension-sdk を使用して SDK をインストールします。

  2. JavaScript コードで初期化します。

    import * as SDK from "azure-devops-extension-sdk";
SDK.init();

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

メイン ページにコントロールを追加するには、 extension マニフェストに投稿を追加します。 コントリビューションの種類は 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
        }
    }
],
"manifestVersion": 1.0,
    "scopes": [
        "vso.work"
    ]

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

Properties

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

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

作業項目フォームのカスタム コントロールは、グループやページのコントリビューションなどコントリビューションのもう 1 つの種類です。 主な違いは、グループとページのコントリビューションでは実行できない一方で、コントロールコントリビューションがユーザー入力のセットを受け取ることができる点です。

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

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

次のサンプルでは、 FieldName と Colorsの 2 つの入力が表示されます。 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.",
        "type": "string",
        "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 SDK from "azure-devops-extension-sdk";
import * as ExtensionContracts from "azure-devops-extension-api/WorkItemTracking/WorkItemTracking";

let control;

const provider = () => {
    return {
        onLoaded: (workItemLoadedArgs) => {
            // create the control
            const config = SDK.getConfiguration();
            const fieldName = config.witInputs["FieldName"];
            const colors = config.witInputs["Colors"];
            control = new Control(fieldName, colors);
        },
        onFieldChanged: (fieldChangedArgs) => {
            const changedValue = fieldChangedArgs.changedFields[control.getFieldName()];
            if (changedValue !== undefined) {
                control.updateExternal(changedValue);
            }
        }
    };
};

SDK.init();
SDK.ready().then(() => {
    SDK.register(SDK.getContributionId(), provider);
});

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

作業項目フォームのカスタム コントロールのスクリーンショット。