扩展“工作项”窗体

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022

使用扩展通过添加组、页面、菜单操作、观察器或自定义控件来实现工作项窗体的自定义。

• 添加组
• 添加页面（选项卡）
• 添加菜单操作
• 添加自定义控件
• 侦听事件
• 设置贡献参数

有关完整的源代码，请参阅 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
       }
   }
]

属性

JavaScript 示例

此示例注册一个提供程序，以响应工作项表单事件。 当工作项加载时，它使用WorkItemFormService读取字段值。

import { IWorkItemFormService, WorkItemTrackingServiceIds } from "azure-devops-extension-api/WorkItemTracking";
import * as SDK from "azure-devops-extension-sdk";

async function getWorkItemFormService(): Promise<IWorkItemFormService> {
    return await SDK.getService<IWorkItemFormService>(WorkItemTrackingServiceIds.WorkItemFormService);
}

SDK.init();

SDK.ready().then(() => {
    SDK.register(SDK.getContributionId(), () => {
        return {
            // Called when the active work item is modified
            onFieldChanged: (args) => {
                console.log("onFieldChanged", JSON.stringify(args));
            },

            // Called when a new work item is being loaded in the UI
            onLoaded: async (args) => {
                const service = await getWorkItemFormService();
                const values = await service.getFieldValues([
                    "System.Id", "System.Title", "System.State", "System.CreatedDate"
                ]);
                console.log("onLoaded", JSON.stringify(values));
            },

            // Called when the active work item is being unloaded in the UI
            onUnloaded: (args) => {
                console.log("onUnloaded", JSON.stringify(args));
            },

            // Called after the work item has been saved
            onSaved: (args) => {
                console.log("onSaved", JSON.stringify(args));
            },

            // Called when the work item is reset to its unmodified state (undo)
            onReset: (args) => {
                console.log("onReset", JSON.stringify(args));
            },

            // Called when the work item has been refreshed from the server
            onRefreshed: (args) => {
                console.log("onRefreshed", JSON.stringify(args));
            }
        };
    });
});

事件

添加页面

工作项表单上会显示一个新的选项卡。 新页面显示在“ 详细信息 ”选项卡旁边。

若要向工作项窗体添加页面，请在扩展清单中添加一个类型为 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"
        } 
    }
]

属性

JavaScript 示例

请参阅窗体组部分中的 JavaScript 示例。 已注册对象的名称应与贡献的名称匹配 id 。

事件

配置贡献

在 Azure DevOps Services 中，组扩展默认显示在第二列末尾，页面贡献显示为最后一个选项卡。默认情况下不显示控件贡献 - 用户必须手动将其添加到窗体。 在 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"  
      }  
   }
]

属性

侦听事件

观察者在没有任何用户界面的表单上侦听工作项事件。 使用观察者侦听onSaved事件，因为观察者位于表单之外，而表单对话框关闭时不被销毁。

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

属性

事件

JavaScript 示例

以下示例通过使用现代 SDK 注册观察者：

import * as SDK from "azure-devops-extension-sdk";

SDK.init();

SDK.ready().then(() => {
    SDK.register(SDK.getContributionId(), () => {
        return {
            onFieldChanged: (args) => {
                // Handle field changes
            },
            onLoaded: (args) => {
                // Handle work item loaded
            },
            onUnloaded: (args) => {
                // Handle work item unloaded
            },
            onSaved: (args) => {
                // Handle work item saved
            },
            onReset: (args) => {
                // Handle work item reset (undo)
            },
            onRefreshed: (args) => {
                // Handle work item refreshed
            }
        };
    });
});

兼容性说明

操作与操作提供者

在通过菜单处理程序使用getMenuItems动态加载菜单项时，应用ms.vss-web.action-provider。 当菜单项是静态的，并在清单中定义时使用 ms.vss-web.action 。

弃用的模式

不再支持以下模式：

• require("VSS/Events/Document") - 新版板中心不支持
• SDK.js脚本标签和usePlatformScripts: true——请使用 npm 包azure-devops-extension-sdk来替代。

相关内容

• 将自定义控件添加到工作项窗体
• 配置工作项表单扩展（本地）
• 扩展清单引用
• 贡献模型