Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022
自定義控件可讓您變更使用者如何檢視和與工作項目表單上的欄位互動。 下列文章將逐步引導您完成此自定義控件範例的建置方式。 本文說明如何建置自己的自定義控件。
提示
如需取得最新的擴充功能開發指引，包括主題設定及從 VSS.SDK 遷移的相關資料，請參考 Azure DevOps Extension SDK 開發者入口網站。
必要條件
請在您的專案中加入 azure-devops-extension-sdk：
透過 npm 安裝 SDK：
npm install azure-devops-extension-sdk。在您的 JavaScript 程式代碼中將其初始化：
import * as SDK from "azure-devops-extension-sdk"; SDK.init();
加上控制貢獻
在你的 extension manifest 中新增一個類型為 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 中載入自訂控制項。
控制性質
| 屬性 | 說明 |
|---|---|
name |
出現在群組上的文字。 |
uri |
URI 指向 IFrame 中載入的 HTML 頁面。 |
height |
（可選）IFrame 的高度（像素數）。 預設值為 50。 |
inputs |
使用者在新增控制項時所提供的數值。 |
要動態調整 IFrame 大小，請使用 resize SDK 中的方法。
自訂控制是一種類似群組貢獻和頁面貢獻的貢獻類型。 主要差異在於控制貢獻接受使用者輸入，而群組和頁面貢獻則不接受。
控制參與輸入
利用 inputs 貢獻物件中的屬性來定義可配置的控制輸入。
以下範例定義了兩個輸入： 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
}
}
]
輸入屬性
以下屬性定義了使用者輸入：
| 屬性 | 說明 |
|---|---|
| 識別碼 | 輸入的唯一識別碼。 |
| 描述 | 輸入的簡短說明。 |
| type | （可選）輸入類型。 用來 WorkItemField 表示該值應該是工作項目欄位的參考名稱。 |
| 屬性 | （可選）自訂屬性。 用workItemFieldTypes來限制哪些欄位類型有效（例如，String， Integer， DateTimeBoolean， ）。 |
| 驗證 | 驗證規則。 設定 dataType（String、Number、Boolean 或 Field）和 isRequired（true 或 false）。 |
支援workItemFieldTypes值：String，Integer，DateTime，PlainText，HTML，TreePath，History，Double，Guid，Boolean，Identity，PicklistString，PicklistInteger，PicklistDouble。
JavaScript 範例
自訂控制擴充功能的運作方式類似於群組或頁面擴充功能，但多了一個特性，能夠透過SDK.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);
});
下列螢幕快照顯示 [優先順序] 欄位的自訂工作專案控制項範例。
