Memperluas formulir tugas kerja

Layanan Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Artikel ini menjelaskan cara menggunakan ekstensi untuk mengkustomisasi formulir item kerja. Anda dapat menambahkan tindakan, pengamat, grup, atau halaman ke formulir item kerja di Azure DevOps.

Petunjuk / Saran

Jika Anda memulai ekstensi Azure DevOps baru, coba koleksi sampel yang dikelola ini terlebih dahulu—mereka bekerja dengan build produk saat ini dan mencakup skenario modern (misalnya, menambahkan tab pada halaman permintaan pull).

Sampel ekstensi Azure DevOps (GitHub)—sampel starter ringkas yang menunjukkan pola ekstensi umum: https://github.com/microsoft/azure-devops-extension-sample
Sampel ekstensi Azure DevOps (panduan pengumpulan dan kontribusi warisan)—instal untuk memeriksa target UI, atau lihat sumbernya: https://marketplace.visualstudio.com/items/ms-samples.samples-contributions-guide dan https://github.com/Microsoft/vso-extension-samples/tree/master/contributions-guide
Sampel Microsoft Learn (jelajahi sampel Azure DevOps)—sampel yang telah diseleksi, terbaru di seluruh dokumentasi Microsoft: /samples/browse/?terms=azure%20devops%20extension

Jika sampel tidak berfungsi di organisasi Anda, instal ke organisasi pribadi atau pengujian dan bandingkan ID target manifes ekstensi dan versi API dengan dokumen saat ini. Untuk referensi dan API, lihat:

azure-devops-extension-api
azure-devops-extension-sdk
API ekstensi yang diinstal

Menambahkan grup ke halaman utama
Menambahkan halaman (tab)
Menambahkan tindakan ke menu konteks
Tambahkan kontrol kustom
Mendengarkan acara di formulir
Mengonfigurasi kontribusi dalam formulir item kerja

Untuk kode sumber lengkap, lihat contoh UI dalam sampel ekstensi Azure DevOps di GitHub.

Menambahkan grup

Tangkapan layar yang menunjukkan item bilah alat dalam formulir item kerja.

Untuk menambahkan grup ke halaman utama, tambahkan kontribusi ke manifes ekstensi Anda. Jenis kontribusi ini harus dan ms.vss-work-web.work-item-form-group harus menargetkan ms.vss-work-web.work-item-form kontribusi.

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

Karakteristik

Harta benda	Deskripsi
`name`	Teks yang muncul di grup.
`uri`	URI ke halaman yang menghosting html yang ditampilkan pada formulir item kerja dan skripnya.
`height`	(Opsional) Menentukan tinggi grup. Jika dihilangkan, itu adalah 100%.

Contoh JavaScript

Contoh ini menunjukkan cara mendaftarkan objek yang dipanggil saat peristiwa terjadi pada formulir item kerja yang mungkin memengaruhi grup kontribusi Anda.

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)));
        }
    }
});

Peristiwa

Peristiwa	Deskripsi kejadian	Argumen	Deskripsi argumen
`onFieldChanged`	Dipecat setelah bidang berubah. Jika perubahan bidang menjalankan aturan yang memperbarui bidang lain, semua perubahan ini adalah bagian dari satu peristiwa.	ID	ID item kerja
`changedFields`	Array dengan nama referensi semua bidang yang diubah.	ID	ID item kerja
`onLoaded`	Diaktifkan setelah data dimuat dalam formulir item kerja, saat pengguna membuka item kerja, atau saat pengguna menavigasi ke item kerja lain dalam tampilan triase.	ID	ID item kerja
`onReset`	Diaktifkan setelah pengguna membatalkan perubahan pada item kerja.	ID	ID item kerja
`onRefreshed`	Diaktifkan setelah pengguna menyegarkan item kerja secara manual.	ID	ID item kerja
`onSaved`	Dipecat setelah item kerja disimpan. Untuk item kerja dalam dialog, Anda harus menargetkan jenis untuk `ms.vss-work-web.work-item-notifications` memastikan peristiwa diaktifkan karena setelah dialog ditutup, jenis kontribusi ini akan dibongkar. Untuk informasi selengkapnya, lihat Mendengarkan peristiwa.	ID	ID item kerja
`onUnloaded`	Diaktifkan sebelum pengguna menutup dialog, atau sebelum pengguna berpindah ke item kerja lain dalam tampilan triase.	ID	ID item kerja

Tambahkan halaman

Halaman baru dirender sebagai tab pada formulir item kerja. Halaman baru muncul di samping tab Detail .

Cuplikan layar yang menampilkan halaman baru sebagai tab pada formulir item kerja.

Untuk menambahkan halaman ke formulir item kerja, tambahkan kontribusi ke manifes ekstensi Anda. Jenis kontribusi ini harus dan ms.vss-work-web.work-item-form-page harus menargetkan ms.vss-work-web.work-item-form kontribusi.

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

Karakteristik

Harta benda	Deskripsi
Nama	Teks yang muncul di halaman tab.
URI	URI ke halaman yang menghosting html yang ditampilkan pada formulir item kerja dan skripnya.

Contoh JavaScript

Lihat contoh JavaScript di bagian grup formulir. Nama objek terdaftar harus sesuai dengan id kontribusi.

Peristiwa

Peristiwa	Deskripsi kejadian	Argumen	Deskripsi argumen
`onFieldChanged`	Dipecat setelah bidang berubah. Jika perubahan bidang menjalankan aturan yang memperbarui bidang lain, semua perubahan ini adalah bagian dari satu peristiwa.	ID	ID item kerja
`changedFields`	Array dengan nama referensi semua bidang yang diubah.	ID	ID item kerja
`onLoaded`	Diaktifkan setelah data dimuat dalam formulir item kerja, saat pengguna membuka item kerja, atau saat pengguna menavigasi ke item kerja lain dalam tampilan triase.	ID	ID item kerja
`onReset`	Diaktifkan setelah pengguna membatalkan perubahan pada item kerja.	ID	ID item kerja
`onRefreshed`	Diaktifkan setelah pengguna menyegarkan item kerja secara manual.	ID	ID item kerja
`onSaved`	Dipecat setelah item kerja disimpan. Untuk item kerja dalam dialog, Anda harus menargetkan jenis untuk `ms.vss-work-web.work-item-notifications` memastikan peristiwa diaktifkan karena setelah dialog ditutup, jenis kontribusi ini akan dibongkar. Untuk informasi selengkapnya, lihat Mendengarkan peristiwa.	ID	ID item kerja
`onUnloaded`	Diaktifkan sebelum pengguna menutup dialog, atau sebelum pengguna berpindah ke item kerja lain dalam tampilan triase.	ID	ID item kerja

Mengonfigurasi kontribusi dalam formulir item kerja

Di Azure DevOps Services, secara default, ekstensi grup muncul di akhir kolom kedua formulir, dan kontribusi halaman muncul setelah semua halaman formulir item kerja sebagai tab. Kontribusi kontrol tidak ditampilkan dalam formulir secara default, sehingga pengguna harus menambahkannya secara manual ke formulir. Di Azure DevOps Server, untuk menampilkan/menyembunyikan atau memindahkan kontribusi kontrol, grup, dan halaman dalam formulir item kerja, lihat Mengonfigurasi ekstensi formulir item kerja.

Tangkapan layar yang menunjukkan cara menambahkan item ke toolbar item kerja.

Untuk menambahkan item ke toolbar item kerja, tambahkan kontribusi ini ke manifes ekstensi Anda. Pilih elipsis vertikal dalam formulir item kerja untuk melihat menu tarik-turun.

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

Karakteristik

Harta benda	Deskripsi
`text`	Teks yang muncul pada item bilah alat.
`title`	Teks petunjuk yang muncul pada item menu.
`toolbarText`	Teks yang muncul saat item diarahkan ke atas.
`uri`	URI ke halaman yang mendaftarkan penanganan tindakan toolbar.
`icon`	URL ke ikon yang muncul pada item menu. URL relatif diselesaikan menggunakan `baseUri`.
`group`	Menentukan di mana item menu muncul, terkait dengan yang lain. Item bilah alat dengan nama grup yang sama dikelompokkan dan dibagi oleh pemisah dari item lainnya.
`registeredObjectId`	(Opsional) Nama pengelola aksi menu yang terdaftar. Default ke ID kontribusi.

Mendengarkan acara

Untuk menambahkan pengamat ke item kerja, yang mendengarkan peristiwa item kerja, tambahkan kontribusi ini ke manifes ekstensi Anda. Tidak ada visualisasi untuk pengamat pada formulir item kerja. Ini adalah cara terbaik untuk mendengarkan formulir item kerja di peristiwa Saved karena pengamat tinggal di luar formulir dan tidak dihancurkan saat formulir ditutup, yang mungkin terjadi tepat setelah penyimpanan.

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

Karakteristik

Harta benda	Deskripsi
`uri`	URI ke halaman yang menghosting skrip yang mendengarkan peristiwa.

Peristiwa

Peristiwa	Deskripsi kejadian	Argumen	Deskripsi argumen
`onFieldChanged`	Dipecat setelah bidang berubah. Jika perubahan bidang menjalankan aturan yang memperbarui bidang lain, semua perubahan ini adalah bagian dari satu peristiwa.	ID	ID item kerja
`changedFields`	Array dengan nama referensi semua bidang yang diubah.	ID	ID item kerja
`onLoaded`	Diaktifkan setelah data dimuat dalam formulir item kerja, saat pengguna membuka item kerja, atau saat pengguna menavigasi ke item kerja lain dalam tampilan triase.	ID	ID item kerja
`onReset`	Diaktifkan setelah pengguna membatalkan perubahan pada item kerja.	ID	ID item kerja
`onRefreshed`	Diaktifkan setelah pengguna menyegarkan item kerja secara manual.	ID	ID item kerja
`onSaved`	Dipecat setelah item kerja disimpan. Untuk item kerja dalam dialog, Anda harus menargetkan jenis untuk `ms.vss-work-web.work-item-notifications` memastikan peristiwa diaktifkan karena setelah dialog ditutup, jenis kontribusi ini akan dibongkar. Untuk informasi selengkapnya, lihat Mendengarkan peristiwa.	ID	ID item kerja
`onUnloaded`	Diaktifkan sebelum pengguna menutup dialog, atau sebelum pengguna berpindah ke item kerja lain dalam tampilan triase.	ID	ID item kerja

Contoh 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>

Perubahan dengan Hub Papan Baru

Nota

Fitur Hub Papan Baru diaktifkan secara bawaan. Kami sangat menyarankan agar Anda menguji ekstensi internal Anda dengan Hub Papan Baru untuk memastikan kompatibilitas.

Menggunakan SDK terbaru

Pastikan ekstensi Anda menggunakan azure-devops-extension-sdk versi terbaru

Saat menggunakan SDK baru, Anda juga harus menggunakan paket azure-devops-extension-api untuk REST API. Kami memperbarui metode dan antarmuka setiap sprint untuk memastikannya mencakup semua fitur terbaru.

Kapan harus menggunakan action atau action-provider

Gunakan ms.vss-web.action-provider saat memuat item menu secara dinamis menggunakan getMenuItems pada penangan menu. Hindari menggunakan ms.vss-web.action-provider saat item menu Anda statis dan ditentukan dalam manifes Anda. Sebagai gantinya ms.vss-web.action harus digunakan.

Paket `require("VSS/Events/Document")` tidak lagi didukung

require("VSS/Events/Document") impor tidak lagi didukung dengan New Boards Hub.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-17

Bagikan melalui

Memperluas formulir tugas kerja

Menambahkan grup

Karakteristik

Contoh JavaScript

Peristiwa

Tambahkan halaman

Karakteristik

Contoh JavaScript

Peristiwa

Mengonfigurasi kontribusi dalam formulir item kerja

Tambahkan tindakan menu

Karakteristik

Mendengarkan acara

Karakteristik

Peristiwa

Contoh HTML/JavaScript

Perubahan dengan Hub Papan Baru

Menggunakan SDK terbaru

Kapan harus menggunakan action atau action-provider

Paket require("VSS/Events/Document") tidak lagi didukung

Saran dan Komentar

Sumber Daya Tambahan:

Paket `require("VSS/Events/Document")` tidak lagi didukung