Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022
使用自定义控件可以更改用户查看和与工作项窗体上的字段交互的方式。 以下文章将指导你完成此示例自定义控件的生成方式。 本文介绍如何生成自己的自定义控件。
提示
有关最新的扩展开发指南，包括主题处理以及从 VSS.SDK 的迁移，请参阅 Azure DevOps 扩展 SDK 开发人员门户。
先决条件
在项目中导入 azure-devops-extension-sdk：
通过 npm 安装 SDK：
npm install azure-devops-extension-sdk。在 JavaScript 代码中初始化它：
import * as SDK from "azure-devops-extension-sdk"; SDK.init();
添加控制项贡献
在您的ms.vss-work-web.work-item-form中添加一个类型为、目标为ms.vss-work-web.work-item-form-control的贡献：
"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 |
IFrame 中加载的 HTML 页面的 URI。 |
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
}
}
]
输入属性
以下属性定义用户输入：
| 属性 | 说明 |
|---|---|
| id | 输入的唯一 ID。 |
| 说明 | 输入的简短说明。 |
| 类型 | （可选）输入类型。 使用 WorkItemField 指示该值应为工作项字段引用名称。 |
| 性能 | （可选）自定义属性。 用于workItemFieldTypes限制哪些字段类型有效（例如，、String、IntegerDateTimeBoolean、 ）。 |
| 验证 | 有效性规则。 设置 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);
});
以下屏幕截图显示了“优先级”字段的示例自定义工作项控件。
