Расширение формы рабочего элемента

Сервисы Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Используйте расширения для настройки формы рабочего элемента путем добавления групп, страниц, действий меню, наблюдателей или пользовательских элементов управления.

Подсказка

Если вы создаёте новое расширение Azure DevOps, попробуйте сначала использовать эти поддерживаемые образцы коллекций — они работают с текущими сборками продуктов и охватывают современные сценарии (например, добавление вкладок на страницы pull request).

Пример расширения Azure DevOps (GitHub) — компактный начальный пример, демонстрирующий распространенные шаблоны расширений: https://github.com/microsoft/azure-devops-extension-sample
Примеры расширений Azure DevOps (коллекция устаревших версий и руководство по вкладам) — установите, чтобы проверить цели пользовательского интерфейса, или просмотрите исходный код: https://marketplace.visualstudio.com/items/ms-samples.samples-contributions-guide https://github.com/Microsoft/vso-extension-samples/tree/master/contributions-guide
Примеры Microsoft Learn (просмотр примеров Azure DevOps) — подобранные, актуальные примеры в документации Microsoft: /samples/browse/?terms=azure%20devops%20extension

Если пример не работает в вашей организации, установите его в личную или тестовую организацию и сравните целевые идентификаторы манифеста расширения и версии API с текущими документами. Справочные материалы и API см. в статье:

Добавление группы
Добавление страницы (вкладка)
Добавление действия меню
Добавление пользовательского элемента управления
Прослушивание событий
Настройка вкладов

Полный исходный код см. в примере пользовательского интерфейса в примерах расширений Azure DevOps на GitHub.

Подсказка

Для получения последних рекомендаций по разработке расширений, включая темизацию и миграцию из VSS.SDK, смотрите на портале разработчика пакета SDK для расширений Azure DevOps.

Добавление группы

Снимок экрана: элемент панели инструментов в форме рабочего элемента.

Чтобы добавить группу на главную страницу, добавьте запись в манифест расширения с типом 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
       }
   }
]

Свойства

Свойство	Описание
`name`	Текст, отображаемый в группе.
`uri`	URI к HTML-странице, загруженной в IFrame.
`height`	(Необязательно) Высота группы. Значение по умолчанию — 100%.

Пример на языке 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));
            }
        };
    });
});

События

Мероприятие	Описание события	Аргумент	Описание аргумента
`onFieldChanged`	Запущено после изменения поля. Если изменение поля изменило правила, обновляющие другие поля, все эти изменения являются частью одного события.	Идентификатор	Идентификатор рабочего элемента
`changedFields`	Массив с именами ссылок на все измененные поля.	Идентификатор	Идентификатор рабочего элемента
`onLoaded`	Возникает после загрузки данных в форме рабочего элемента, когда пользователь открывает рабочий элемент или когда пользователь переходит к другому рабочему элементу в представлении трижажа.	Идентификатор	Идентификатор рабочего элемента
`onReset`	Запускается после отмены изменений рабочего элемента.	Идентификатор	Идентификатор рабочего элемента
`onRefreshed`	Выполняется после ручного обновления рабочего элемента пользователем.	Идентификатор	Идентификатор рабочего элемента
`onSaved`	Запускается после сохранения рабочего элемента. Для рабочих элементов в диалоговом окне следует нацелиться на `ms.vss-work-web.work-item-notifications` тип, чтобы событие сработало, поскольку после закрытия диалога этот тип вклада выгружается. Дополнительные сведения см. в разделе "Прослушивание событий".	Идентификатор	Идентификатор рабочего элемента
`onUnloaded`	Запускается перед тем, как пользователь закроет диалоговое окно, или перед переходом к другому рабочему элементу в представлении сортировки.	Идентификатор	Идентификатор рабочего элемента

Добавление страницы

Новая страница отображается в виде вкладки в форме рабочего элемента. Новые страницы отображаются рядом с вкладкой "Сведения ".

Снимок экрана, на котором показана новая страница в виде вкладки в форме рабочего элемента.

Чтобы добавить страницу в форму рабочего элемента, добавьте вклад в манифест расширения с целевым типом ms.vss-work-web.work-item-form-pagems.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"
        } 
    }
]

Свойства

Свойство	Описание
`name`	Текст, отображаемый на странице вкладок.
`uri`	URI к HTML-странице, загруженной в IFrame.

Пример на языке JavaScript

См. пример JavaScript в разделе группы форм. Имя зарегистрированного объекта должно соответствовать id вкладу.

События

Мероприятие	Описание события	Аргумент	Описание аргумента
`onFieldChanged`	Запущено после изменения поля. Если изменение поля изменило правила, обновляющие другие поля, все эти изменения являются частью одного события.	Идентификатор	Идентификатор рабочего элемента
`changedFields`	Массив с именами ссылок на все измененные поля.	Идентификатор	Идентификатор рабочего элемента
`onLoaded`	Возникает после загрузки данных в форме рабочего элемента, когда пользователь открывает рабочий элемент или когда пользователь переходит к другому рабочему элементу в представлении трижажа.	Идентификатор	Идентификатор рабочего элемента
`onReset`	Запускается после отмены изменений рабочего элемента.	Идентификатор	Идентификатор рабочего элемента
`onRefreshed`	Выполняется после ручного обновления рабочего элемента пользователем.	Идентификатор	Идентификатор рабочего элемента
`onSaved`	Запускается после сохранения рабочего элемента. Для рабочих элементов в диалоговом окне следует нацелиться на `ms.vss-work-web.work-item-notifications` тип, чтобы событие сработало, поскольку после закрытия диалога этот тип вклада выгружается. Дополнительные сведения см. в разделе "Прослушивание событий".	Идентификатор	Идентификатор рабочего элемента
`onUnloaded`	Запускается перед тем, как пользователь закроет диалоговое окно, или перед переходом к другому рабочему элементу в представлении сортировки.	Идентификатор	Идентификатор рабочего элемента

Настройка вкладов

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

Свойства

Свойство	Описание
`text`	Текст, отображаемый на элементе панели инструментов.
`title`	Текст подсказки, отображаемый в элементе меню.
`toolbarText`	Текст, который отображается при наведении указателя мыши на элемент.
`uri`	URI страницы, которая регистрирует обработчик действия панели инструментов.
`icon`	URL-адрес значка, отображаемого в элементе меню. Относительные URL-адреса определяются с помощью `baseUri`.
`group`	Определяет, где элемент меню отображается относительно других элементов. Элементы панели инструментов с тем же именем группы группируются и разделяются разделителем от остальных элементов.
`registeredObjectId`	(Необязательно) Имя зарегистрированного обработчика действия меню. По умолчанию используется идентификатор вклада.

Слушайте события

Наблюдатели прослушивают события рабочих элементов без пользовательского интерфейса формы. Используйте наблюдателей для прослушивания 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"
       }
   }
]

Свойства

Свойство	Описание
`uri`	URI на страницу, которая размещает скрипты, прослушивающие события.

События

Мероприятие	Описание события	Аргумент	Описание аргумента
`onFieldChanged`	Запущено после изменения поля. Если изменение поля изменило правила, обновляющие другие поля, все эти изменения являются частью одного события.	Идентификатор	Идентификатор рабочего элемента
`changedFields`	Массив с именами ссылок на все измененные поля.	Идентификатор	Идентификатор рабочего элемента
`onLoaded`	Возникает после загрузки данных в форме рабочего элемента, когда пользователь открывает рабочий элемент или когда пользователь переходит к другому рабочему элементу в представлении трижажа.	Идентификатор	Идентификатор рабочего элемента
`onReset`	Запускается после отмены изменений рабочего элемента.	Идентификатор	Идентификатор рабочего элемента
`onRefreshed`	Выполняется после ручного обновления рабочего элемента пользователем.	Идентификатор	Идентификатор рабочего элемента
`onSaved`	Запускается после сохранения рабочего элемента. Для рабочих элементов в диалоговом окне следует нацелиться на `ms.vss-work-web.work-item-notifications` тип, чтобы событие сработало, поскольку после закрытия диалога этот тип вклада выгружается. Дополнительные сведения см. в разделе "Прослушивание событий".	Идентификатор	Идентификатор рабочего элемента
`onUnloaded`	Запускается перед тем, как пользователь закроет диалоговое окно, или перед переходом к другому рабочему элементу в представлении сортировки.	Идентификатор	Идентификатор рабочего элемента

Пример на языке 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
            }
        };
    });
});

Заметки о совместимости

Действие и поставщик действий

Используйте ms.vss-web.action-provider при динамической загрузке элементов меню с помощью getMenuItems обработчика меню. Используйте ms.vss-web.action , когда элементы меню являются статическими и определены в манифесте.

Устаревшие шаблоны

Следующие шаблоны больше не поддерживаются:

require("VSS/Events/Document") — не поддерживается в текущем интерфейсе Boards
SDK.js Тег скрипта с usePlatformScripts: true — используйте вместо него пакет azure-devops-extension-sdk npm

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-04-03

Расширение формы рабочего элемента

Добавление группы

Свойства

Пример на языке JavaScript

События

Добавление страницы

Свойства

Пример на языке JavaScript

События

Настройка вкладов

Добавление действия меню

Свойства

Слушайте события

Свойства

События

Пример на языке JavaScript

Заметки о совместимости

Действие и поставщик действий

Устаревшие шаблоны

Связанный контент

Обратная связь

Дополнительные ресурсы