Extender el formulario del elemento de trabajo
Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019
Obtenga información sobre cómo personalizar cómo se presenta el formulario de elemento de trabajo a los usuarios a través de contribuciones realizadas a través de una extensión.
- Agregar un grupo a la página principal
- Agregar una página (pestaña)
- Agregar una acción al menú contextual
- Adición de un control personalizado
- Escucha de eventos en el formulario
- Configurar contribuciones en el formulario de elemento de trabajo
Consulte el ejemplo de interfaz de usuario en ejemplos de extensión de Azure DevOps en GitHub para obtener el origen completo.
Agregar un grupo
Para agregar un grupo a la página principal, agregue una contribución al manifiesto de extensión. El tipo de esta contribución debe ser ms.vss-work-web.work-item-form-group y debe tener como destino la ms.vss-work-web.work-item-form contribución.
"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
}
}
]
Propiedades
| Property | Descripción |
|---|---|
name |
Texto que aparece en el grupo. |
uri |
URI a una página que hospeda el html que se muestra en el formulario de elemento de trabajo y sus scripts. |
height |
(Opcional) Define el alto del grupo. Cuando se omite, es del 100 %. |
Ejemplo de JavaScript
En este ejemplo se muestra cómo registrar un objeto al que se llama cuando se producen eventos en el formulario de elemento de trabajo que puede afectar al grupo contribuido.
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)));
}
}
});
Eventos
| Evento | Descripción del evento | Argument | Descripción del argumento |
|---|---|---|---|
| onFieldChanged | Se desencadena después de que un campo haya cambiado. Si el cambio de campo ejecutó reglas que actualizaron otros campos, todos estos cambios forman parte de un único evento. | ID | El identificador del elemento de trabajo. |
| changedFields | Matriz con el nombre de referencia de todos los campos modificados. | ID | El identificador del elemento de trabajo. |
| onLoaded | Se desencadena después de cuando los datos se cargan en el formulario de elemento de trabajo, cuando el usuario abre un elemento de trabajo o cuando el usuario navega a otro elemento de trabajo en la vista de evaluación de prioridades. | ID | El identificador del elemento de trabajo. |
| onReset | Se desencadena después de que el usuario deshaga los cambios en el elemento de trabajo. | ID | El identificador del elemento de trabajo. |
| onRefreshed | Se desencadena después de que el usuario actualice el elemento de trabajo manualmente. | ID | El identificador del elemento de trabajo. |
| onSaved | Se desencadena después de guardar un elemento de trabajo. En el caso de los elementos de trabajo de un cuadro de diálogo, debe tener como destino el tipo "ms.vss-work-web.work-item-notifications" para asegurarse de que el evento se activa desde que se cierra el cuadro de diálogo, este tipo de contribución se descarga. Para obtener más información, consulte Escucha de eventos. | ID | El identificador del elemento de trabajo. |
| onUnloaded | Se desencadena antes de que el usuario cierre el cuadro de diálogo o antes de que el usuario se mueva a otro elemento de trabajo en la vista de evaluación de prioridades. | ID | El identificador del elemento de trabajo. |
Agregar una página
Una nueva página se representa como una pestaña en el formulario de elemento de trabajo. Las páginas nuevas aparecen junto a la pestaña Detalles.
Para agregar una página al formulario de elemento de trabajo, agregue una contribución al manifiesto de extensión. El tipo de esta contribución debe ser ms.vss-work-web.work-item-form-page y debe tener como destino la ms.vss-work-web.work-item-form contribución.
"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"
}
}
]
Propiedades
| Property | Descripción |
|---|---|
| nombre | Texto que aparece en la página de pestañas. |
| uri | URI a una página que hospeda el html que se muestra en el formulario de elemento de trabajo y sus scripts. |
Ejemplo de JavaScript
Consulte el ejemplo de JavaScript en la sección grupo de formularios. El nombre del objeto registrado debe coincidir con el id de la contribución.
Eventos
| Evento | Descripción del evento | Argument | Descripción del argumento |
|---|---|---|---|
| onFieldChanged | Se desencadena después de que un campo haya cambiado. Si el cambio de campo ejecutó reglas que actualizaron otros campos, todos estos cambios forman parte de un único evento. | ID | El identificador del elemento de trabajo. |
| changedFields | Matriz con el nombre de referencia de todos los campos modificados. | ID | El identificador del elemento de trabajo. |
| onLoaded | Se desencadena después de cuando los datos se cargan en el formulario de elemento de trabajo, cuando el usuario abre un elemento de trabajo o cuando el usuario navega a otro elemento de trabajo en la vista de evaluación de prioridades. | ID | El identificador del elemento de trabajo. |
| onReset | Se desencadena después de que el usuario deshaga los cambios en el elemento de trabajo. | ID | El identificador del elemento de trabajo. |
| onRefreshed | Se desencadena después de que el usuario actualice el elemento de trabajo manualmente. | ID | El identificador del elemento de trabajo. |
| onSaved | Se desencadena después de guardar un elemento de trabajo. En el caso de los elementos de trabajo de un cuadro de diálogo, debe tener como destino el tipo "ms.vss-work-web.work-item-notifications" para asegurarse de que el evento se activa desde que se cierra el cuadro de diálogo, este tipo de contribución se descarga. Para obtener más información, consulte Escucha de eventos. | ID | El identificador del elemento de trabajo. |
| onUnloaded | Se desencadena antes de que el usuario cierre el cuadro de diálogo o antes de que el usuario se mueva a otro elemento de trabajo en la vista de evaluación de prioridades. | ID | El identificador del elemento de trabajo. |
Configurar contribuciones en el formulario de elemento de trabajo
En Azure DevOps Services, de forma predeterminada, las extensiones de grupo aparecen al final de la segunda columna del formulario y las contribuciones de página después de todas las páginas del formulario del elemento de trabajo como una pestaña. Las contribuciones de control no se muestran en el formulario de forma predeterminada, por lo que los usuarios tienen que agregarlas manualmente al formulario. En Azure DevOps Server, para mostrar u ocultar o mover el control, las contribuciones de grupo y página en el formulario de elemento de trabajo, consulte Configuración de extensiones de formulario de elemento de trabajo.
Agregar acción de menú
Para agregar un elemento a la barra de herramientas del elemento de trabajo, agregue esta contribución al manifiesto de extensión. El elemento aparece en ... desplegable en la parte superior derecha del formulario de elemento de trabajo.
"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"
}
}
]
Propiedades
| Property | Descripción |
|---|---|
| text | Texto que aparece en el elemento de la barra de herramientas. |
| title | Texto de información sobre herramientas que aparece en el elemento de menú. |
| toolbarText | Texto que aparece cuando se mantiene el puntero sobre el elemento. |
| uri | URI en una página que registra el controlador de acciones de la barra de herramientas. |
| Icono | Dirección URL a un icono que aparece en el elemento de menú. Las direcciones URL relativas se resuelven mediante baseUri. |
| group | Determina dónde aparece el elemento de menú, relacionado con otros usuarios. Los elementos de la barra de herramientas con el mismo nombre de grupo se agrupan y se dividen por un separador del resto de los elementos. |
| registeredObjectId | (Opcional) Nombre del controlador de acción de menú registrado. El valor predeterminado es el identificador de contribución. |
Escucha de eventos
Para agregar un observador al elemento de trabajo, que escucha los eventos del elemento de trabajo, agregue esta contribución al manifiesto de extensión. No hay ninguna visualización para los observadores en el formulario de elemento de trabajo. Esta es la mejor manera de escuchar el formulario de elemento de trabajo en El evento guardado, ya que el observador reside fuera del formulario y no se destruye cuando se cierra el formulario, lo que puede ocurrir justo después de guardar.
"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"
}
}
]
Propiedades
| Property | Descripción |
|---|---|
| uri | URI a una página que hospeda los scripts que escuchan eventos. |
Eventos
| Evento | Descripción del evento | Argument | Descripción del argumento |
|---|---|---|---|
| onFieldChanged | Se desencadena después de que un campo haya cambiado. Si el cambio de campo ejecutó reglas que actualizaron otros campos, todos estos cambios forman parte de un único evento. | ID | El identificador del elemento de trabajo. |
| changedFields | Matriz con el nombre de referencia de todos los campos modificados. | ID | El identificador del elemento de trabajo. |
| onLoaded | Se desencadena después de cuando los datos se cargan en el formulario de elemento de trabajo, cuando el usuario abre un elemento de trabajo o cuando el usuario navega a otro elemento de trabajo en la vista de evaluación de prioridades. | ID | El identificador del elemento de trabajo. |
| onReset | Se desencadena después de que el usuario deshaga los cambios en el elemento de trabajo. | ID | El identificador del elemento de trabajo. |
| onRefreshed | Se desencadena después de que el usuario actualice el elemento de trabajo manualmente. | ID | El identificador del elemento de trabajo. |
| onSaved | Se desencadena después de guardar un elemento de trabajo. En el caso de los elementos de trabajo de un cuadro de diálogo, debe tener como destino el tipo "ms.vss-work-web.work-item-notifications" para asegurarse de que el evento se activa desde que se cierra el cuadro de diálogo, este tipo de contribución se descarga. Para obtener más información, consulte Escucha de eventos. | ID | El identificador del elemento de trabajo. |
| onUnloaded | Se desencadena antes de que el usuario cierre el cuadro de diálogo o antes de que el usuario se mueva a otro elemento de trabajo en la vista de evaluación de prioridades. | ID | El identificador del elemento de trabajo. |
Ejemplo de 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>
Cambios con el nuevo concentrador de paneles
Nota:
New Boards Hub está actualmente en versión preliminar, pero está disponible para todos los usuarios. Le recomendamos encarecidamente que habilite inmediatamente New Boards Hub y pruebe las extensiones internas.
Uso de los SDK más recientes
Asegúrese de que la extensión usa la versión más reciente de azure-devops-extension-sdk
Al usar el nuevo SDK, también debe usar el paquete azure-devops-extension-api para las API REST. Actualizamos los métodos e interfaces de cada sprint para asegurarnos de que incluye todas las características más recientes.
Cuándo usar acción o proveedor de acciones
Úselo ms.vss-web.action-provider al cargar dinámicamente elementos de menú mediante getMenuItems en el controlador de menús. Evite usar ms.vss-web.action-provider cuando los elementos de menú sean estáticos y definidos en el manifiesto. En su lugar ms.vss-web.action , debe usarse.
Package require("VSS/Events/Document") ya no se admite
require("VSS/Events/Document") la importación ya no se admite con El nuevo concentrador de paneles.