作業項目フォームの拡張
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
拡張機能を通じて行われた投稿を使用して、作業項目フォームをユーザーに表示する方法をカスタマイズする方法について説明します。
- メイン ページにグループを追加する
- ページを追加する (タブ)
- コンテキスト メニューにアクションを追加する
- カスタム コントロールを追加する
- フォーム上のイベントをリッスンする
- 作業項目フォームでコントリビューションを構成する
完全なソースについては、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
}
}
]
Properties
| Property | 説明 |
|---|---|
name |
グループに表示されるテキスト。 |
uri |
作業項目フォームとそのスクリプトに表示される HTML をホストするページへの URI。 |
height |
(省略可能)グループの高さを定義します。 省略すると、100% になります。 |
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)));
}
}
});
Events
| Event | イベントの説明 | 引数 | 引数の説明 |
|---|---|---|---|
| onFieldChanged | フィールドが変更された後に発生します。 フィールド変更で他のフィールドを更新するルールが実行された場合、これらの変更はすべて 1 つのイベントに含まれます。 | ID | 作業項目の ID。 |
| changedFields | 変更されたすべてのフィールドの参照名を持つ配列。 | ID | 作業項目の ID。 |
| onLoaded | データが作業項目フォームに読み込まれた後、ユーザーが作業項目を開いたとき、またはユーザーがトリアージ ビューで別の作業項目に移動したときに発生します。 | ID | 作業項目の ID。 |
| onReset | ユーザーが作業項目の変更を元に戻した後に発生します。 | ID | 作業項目の ID。 |
| onRefreshed | ユーザーが作業項目を手動で更新した後に発生します。 | ID | 作業項目の ID。 |
| onSaved | 作業項目が保存された後に発生します。 ダイアログ内の作業項目の場合は、"ms.vss-work-web.work-item-notifications" 型をターゲットにして、ダイアログが閉じると、このコントリビューションの種類がアンロードされるため、イベントが確実に発生するようにする必要があります。 詳細については、「 Listen for events」を参照してください。 | ID | 作業項目の ID。 |
| onUnloaded | ユーザーがダイアログを閉じる前、またはユーザーがトリアージ ビューの別の作業項目に移動する前に発生します。 | ID | 作業項目の ID。 |
ページを追加
新しいページが作業項目フォームのタブとしてレンダリングされます。 [詳細] タブの横に新しいページが表示されます。
作業項目フォームにページを追加するには、拡張機能マニフェストに投稿を追加します。 このコントリビューションの種類は 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"
}
}
]
Properties
| Property | 内容 |
|---|---|
| name | タブ ページに表示されるテキスト。 |
| uri | 作業項目フォームとそのスクリプトに表示される HTML をホストするページへの URI。 |
JavaScript のサンプル
フォーム グループセクションの JavaScript サンプルを参照してください。 登録されているオブジェクトの名前は、コントリビューションの id と一致する必要があります。
Events
| Event | イベントの説明 | 引数 | 引数の説明 |
|---|---|---|---|
| onFieldChanged | フィールドが変更された後に発生します。 フィールド変更で他のフィールドを更新するルールが実行された場合、これらの変更はすべて 1 つのイベントに含まれます。 | ID | 作業項目の ID。 |
| changedFields | 変更されたすべてのフィールドの参照名を持つ配列。 | ID | 作業項目の ID。 |
| onLoaded | データが作業項目フォームに読み込まれた後、ユーザーが作業項目を開いたとき、またはユーザーがトリアージ ビューで別の作業項目に移動したときに発生します。 | ID | 作業項目の ID。 |
| onReset | ユーザーが作業項目の変更を元に戻した後に発生します。 | ID | 作業項目の ID。 |
| onRefreshed | ユーザーが作業項目を手動で更新した後に発生します。 | ID | 作業項目の ID。 |
| onSaved | 作業項目が保存された後に発生します。 ダイアログ内の作業項目の場合は、"ms.vss-work-web.work-item-notifications" 型をターゲットにして、ダイアログが閉じると、このコントリビューションの種類がアンロードされるため、イベントが確実に発生するようにする必要があります。 詳細については、「 Listen for events」を参照してください。 | ID | 作業項目の ID。 |
| onUnloaded | ユーザーがダイアログを閉じる前、またはユーザーがトリアージ ビューの別の作業項目に移動する前に発生します。 | ID | 作業項目の 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"
}
}
]
Properties
| Property | 説明 |
|---|---|
| text | ツール バー項目に表示されるテキスト。 |
| タイトル | メニュー項目に表示されるツールヒント テキスト。 |
| toolbarText | 項目をポイントしたときに表示されるテキスト。 |
| uri | ツール バー アクション ハンドラーを登録するページへの URI。 |
| icon | メニュー項目に表示されるアイコンの URL。 相対 URL は baseUri を使用して解決されます。 |
| グループ | 他のユーザーに関連するメニュー項目が表示される場所を決定します。 同じグループ名のツール バー項目は、グループ化され、残りの項目の区切り記号で分割されます。 |
| registeredObjectId | (省略可能)登録済みのメニュー アクション ハンドラーの名前。 既定値はコントリビューション ID です。 |
イベントをリッスンする
作業項目イベントをリッスンする作業項目にオブザーバーを追加するには、このコントリビューションを拡張機能マニフェストに追加します。 作業項目フォームにオブザーバーの視覚化はありません。 これは、オブザーバーがフォームの外部に存在し、フォームが閉じると破棄されないため、保存イベントの作業項目フォームをリッスンする最適な方法です。これは、保存直後に発生する可能性があります。
"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"
}
}
]
Properties
| Property | 説明 |
|---|---|
| uri | イベントをリッスンするスクリプトをホストするページへの URI。 |
Events
| Event | イベントの説明 | 引数 | 引数の説明 |
|---|---|---|---|
| onFieldChanged | フィールドが変更された後に発生します。 フィールド変更で他のフィールドを更新するルールが実行された場合、これらの変更はすべて 1 つのイベントに含まれます。 | ID | 作業項目の ID。 |
| changedFields | 変更されたすべてのフィールドの参照名を持つ配列。 | ID | 作業項目の ID。 |
| onLoaded | データが作業項目フォームに読み込まれた後、ユーザーが作業項目を開いたとき、またはユーザーがトリアージ ビューで別の作業項目に移動したときに発生します。 | ID | 作業項目の ID。 |
| onReset | ユーザーが作業項目の変更を元に戻した後に発生します。 | ID | 作業項目の ID。 |
| onRefreshed | ユーザーが作業項目を手動で更新した後に発生します。 | ID | 作業項目の ID。 |
| onSaved | 作業項目が保存された後に発生します。 ダイアログ内の作業項目の場合は、"ms.vss-work-web.work-item-notifications" 型をターゲットにして、ダイアログが閉じると、このコントリビューションの種類がアンロードされるため、イベントが確実に発生するようにする必要があります。 詳細については、「 Listen for events」を参照してください。 | ID | 作業項目の ID。 |
| onUnloaded | ユーザーがダイアログを閉じる前、またはユーザーがトリアージ ビューの別の作業項目に移動する前に発生します。 | ID | 作業項目の ID。 |
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 での変更
Note
新しい Boards Hub は現在プレビュー段階ですが、すべてのユーザーが利用できるようになります。 新しい Boards Hub をすぐに有効にし、内部拡張機能をテストすることを強くお勧めします。
最新の SDK を使用する
拡張機能で最新バージョンの azure-devops-extension-sdk が使用されていることを確認します
新しい SDK を使用する場合は、REST API 用の azure-devops-extension-api パッケージも使用する必要があります。 すべてのスプリントに最新の機能がすべて含まれるように、メソッドとインターフェイスを更新します。
アクションまたはアクション プロバイダーを使用するタイミング
メニュー ハンドラーでgetMenuItemsを使用してメニュー項目を動的に読み込む場合は、ms.vss-web.action-providerを使用します。 メニュー項目が静的であり、マニフェストで定義されている場合は、 ms.vss-web.action-provider を使用しないでください。 代わりに、 ms.vss-web.action を使用する必要があります。
Package require("VSS/Events/Document") はサポートされなくなりました
require("VSS/Events/Document") インポートは、新しい Boards Hub ではサポートされなくなりました。