Udostępnij za pośrednictwem

Dodawanie widżetu pulpitu nawigacyjnego

  • Artykuł

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Widżety na pulpicie nawigacyjnym są implementowane jako współtworzenie struktury rozszerzeń. Jedno rozszerzenie może mieć wiele współtworzeń. Dowiedz się, jak utworzyć rozszerzenie z wieloma widżetami jako współtworzenie.

Ten artykuł jest podzielony na trzy części, z których każdy składa się z poprzedniego — począwszy od prostego widżetu i kończąc na kompleksowym widżecie.

Napiwek

Zapoznaj się z naszą najnowszą dokumentacją dotyczącą programowania rozszerzeń przy użyciu zestawu SDK rozszerzenia usługi Azure DevOps.

Przygotowanie i wymagana konfiguracja na potrzeby tego samouczka

Aby utworzyć rozszerzenia dla usługi Azure DevOps lub TFS, potrzebne są wstępnie wymagane oprogramowanie i narzędzia:

Wiedza: Do programowania widżetów wymagana jest pewna wiedza na temat języka JavaScript, HTML i CSS.

  • Organizacja w usłudze Azure DevOps do instalowania i testowania widżetu. Więcej informacji można znaleźć tutaj
  • Edytor tekstów. W przypadku wielu samouczków użyliśmy polecenia Visual Studio Code, który można pobrać tutaj
  • Najnowsza wersja węzła, którą można pobrać tutaj
  • Międzyplatformowy interfejs wiersza polecenia dla usługi Azure DevOps (tfx-cli) w celu spakowania rozszerzeń.
    • Narzędzie tfx-cli można zainstalować przy użyciu npmpolecenia , składnika node.js, uruchamiając polecenie npm i -g tfx-cli
  • Katalog główny projektu. Ten katalog jest określany jako home w całym samouczku.

Struktura pliku rozszerzenia:

|--- README.md
|--- sdk    
    |--- node_modules           
    |--- scripts
        |--- VSS.SDK.min.js       
|--- img                        
    |--- logo.png                           
|--- scripts                        
|--- hello-world.html               // html page to be used for your widget  
|--- vss-extension.json             // extension's manifest

Co znajdziesz w samouczku

  1. W pierwszej części tego przewodnika pokazano, jak utworzyć nowy widżet, który wyświetla prosty komunikat "Hello World".
  2. Druga część opiera się na pierwszym, dodając wywołanie do interfejsu API REST usługi Azure DevOps.
  3. W trzeciej części wyjaśniono, jak dodać konfigurację do widżetu.

Uwaga

Jeśli jesteś w pośpiechu i chcesz od razu uzyskać ręce na kod, możesz pobrać przykłady tutaj. Po pobraniu widgets przejdź do folderu, a następnie postępuj zgodnie z instrukcjami Krok 6 i Krok 7 bezpośrednio, aby opublikować przykładowe rozszerzenie zawierające trzy przykładowe widżety o różnych złożonościach.

Rozpocznij pracę z niektórymi podstawowymi stylami widżetów , które udostępniamy za ciebie, oraz wskazówki dotyczące struktury widżetów.

Część 1. Witaj świecie

W tej części przedstawiono widżet, który wyświetla tekst "Hello World" przy użyciu języka JavaScript.

Overview dashboard with a sample widget

Krok 1. Pobieranie zestawu SDK klienta — VSS.SDK.min.js

Podstawowy skrypt VSS.SDK.min.jszestawu SDK , umożliwia rozszerzenia sieci Web komunikowanie się z ramką usługi Azure DevOps hosta. Skrypt wykonuje operacje, takie jak inicjowanie, powiadamianie rozszerzenia jest ładowane lub pobieranie kontekstu dotyczącego bieżącej strony. Pobierz plik zestawu SDK VSS.SDK.min.js klienta i dodaj go do aplikacji internetowej. Umieść go w folderze home/sdk/scripts .

Użyj polecenia "npm install", aby pobrać zestaw SDK:

npm install vss-web-extension-sdk

Aby dowiedzieć się więcej na temat zestawu SDK, odwiedź stronę github zestawu SDK klienta.

Krok 2. Strona HTML — hello-world.html

Strona HTML to klej, który przechowuje układ razem i zawiera odwołania do arkuszy CSS i JavaScript. Możesz nadać temu plikowi nazwę. Wystarczy zaktualizować wszystkie odwołania do hello-world tej nazwy.

Widżet jest oparty na kodzie HTML i jest hostowany w elemecie iframe. Dodaj poniższy kod HTML w pliku hello-world.html. Dodamy obowiązkowe odwołanie do VSS.SDK.min.js pliku i dołączymy h2 element do elementu , który jest aktualizowany przy użyciu ciągu Hello World w nadchodzącym kroku.

    <!DOCTYPE html>
    <html>
        <head>          
            <script src="sdk/scripts/VSS.SDK.min.js"></script>              
        </head>
        <body>
            <div class="widget">
                <h2 class="title"></h2>
            </div>
        </body>
    </html>

Mimo że używamy pliku HTML, większość elementów nagłówka HTML innych niż skrypt i link są ignorowane przez strukturę.

Krok 3. Twój kod JavaScript

Używamy języka JavaScript do renderowania zawartości w widżecie. W tym artykule opakujemy cały kod JavaScript wewnątrz &lt;script&gt; elementu w pliku HTML. Możesz mieć ten kod w osobnym pliku JavaScript i odwołać się do niego w pliku HTML. Kod renderuje zawartość. Ten kod JavaScript inicjuje również zestaw SDK usługi VSS, mapuje kod widżetu na nazwę widżetu i powiadamia platformę rozszerzenia o sukcesach lub niepowodzeniach widżetu. W naszym przypadku poniżej znajduje się kod, który będzie drukować ciąg "Hello World" w widżecie. Dodaj ten script element w head kodzie HTML.

    <script type="text/javascript">
        VSS.init({                        
            explicitNotifyLoaded: true,
            usePlatformStyles: true
        });

        VSS.require("TFS/Dashboards/WidgetHelpers", function (WidgetHelpers) {
            WidgetHelpers.IncludeWidgetStyles();
            VSS.register("HelloWorldWidget", function () {                
                return {
                    load: function (widgetSettings) {
                        var $title = $('h2.title');
                        $title.text('Hello World');

                        return WidgetHelpers.WidgetStatusHelper.Success();
                    }
                }
            });
            VSS.notifyLoadSucceeded();
        });
    </script>

VSS.init Inicjuje uzgadnianie między elementem iframe hostem widżetu a ramką hosta. Przekazujemy explicitNotifyLoaded: true element , aby widżet mógł jawnie powiadomić hosta po zakończeniu ładowania. Ta kontrolka umożliwia nam powiadamianie o zakończeniu ładowania po upewnieniu się, że moduły zależne są ładowane. Przekazujemy usePlatformStyles: true tak, aby podstawowe style usługi Azure DevOps dla elementów HTML (takich jak treść, div itd.) mogły być używane przez widżet. Jeśli widżet woli nie używać tych stylów, może przekazać element usePlatformStyles: false.

VSS.require służy do ładowania wymaganych bibliotek skryptów usługi VSS. Wywołanie tej metody automatycznie ładuje biblioteki ogólne, takie jak JQuery i JQueryUI. W naszym przypadku zależymy od biblioteki WidgetHelpers, która służy do przekazywania stanu widżetu do platformy widżetów. Dlatego przekazujemy odpowiednią nazwę TFS/Dashboards/WidgetHelpers modułu i wywołanie zwrotne do VSS.require. Wywołanie zwrotne jest wywoływane po załadowaniu modułu. Wywołanie zwrotne zawiera resztę kodu JavaScript potrzebnego do widżetu. Na końcu wywołania zwrotnego wywołujemy VSS.notifyLoadSucceeded metodę powiadamiania o zakończeniu ładowania.

WidgetHelpers.IncludeWidgetStyles zawiera arkusz stylów z podstawowymi arkuszami css , aby rozpocząć pracę. Pamiętaj, aby opakowować zawartość wewnątrz elementu HTML z klasą widget , aby korzystać z tych stylów.

VSS.register służy do mapowania funkcji w języku JavaScript, która unikatowo identyfikuje widżet między różnymi współtworzeniami w rozszerzeniu. Nazwa powinna być zgodna z id nazwą, która identyfikuje Twój wkład zgodnie z opisem w kroku 5. W przypadku widżetów przekazana funkcja VSS.register powinna zwrócić obiekt spełniający kontrakt, na przykład zwrócony obiekt powinien mieć właściwość ładowania, której wartość jest inną funkcją, która IWidget ma podstawową logikę renderowania widżetu. W naszym przypadku należy zaktualizować tekst h2 elementu na "Hello World". Jest to ta funkcja, która jest wywoływana, gdy platforma widżetów tworzy wystąpienie widżetu. Użyjemy elementu WidgetStatusHelper z WidgetHelpers, aby powrócić jako powodzenie WidgetStatus .

Ostrzeżenie

Jeśli nazwa użyta do zarejestrowania widżetu nie jest zgodna z identyfikatorem udziału w manifeście, funkcje widżetu nieoczekiwanie.

Element vss-extension.json powinien zawsze znajdować się w katalogu głównym folderu (w tym przewodniku, HelloWorld). Dla wszystkich pozostałych plików można umieścić je w dowolnej strukturze wewnątrz folderu, wystarczy zaktualizować odwołania odpowiednio w plikach HTML i w vss-extension.json manifeście.

Krok 4. Logo rozszerzenia: logo.png

Logo jest wyświetlane w witrynie Marketplace i w katalogu widżetów po zainstalowaniu rozszerzenia przez użytkownika.

Potrzebujesz ikony wykazu 98 pikseli x 98-px. Wybierz obraz, nadaj mu logo.pngnazwę i umieść go w folderze img .

Aby obsługiwać program TFS 2015 Update 3, potrzebny jest dodatkowy obraz o rozmiarze 330 pikseli x 160 pikseli. Ten obraz podglądu jest wyświetlany w tym wykazie. Wybierz obraz, nadaj mu preview.pngnazwę i umieść go w img folderze tak jak poprzednio.

Możesz nazwać te obrazy tak długo, jak długo manifest rozszerzenia w następnym kroku zostanie zaktualizowany o nazwy, których używasz.

Krok 5. Manifest rozszerzenia: vss-extension.json

Utwórz plik json (vss-extension.jsonna przykład) w home katalogu z następującą zawartością:

    {
        "manifestVersion": 1,
        "id": "vsts-extensions-myExtensions",
        "version": "1.0.0",
        "name": "My First Set of Widgets",
        "description": "Samples containing different widgets extending dashboards",
        "publisher": "fabrikam",
        "categories": ["Azure Boards"],
        "targets": [
            {
                "id": "Microsoft.VisualStudio.Services"
            }
        ],
        "icons": {
            "default": "img/logo.png"
        },
        "contributions": [
            {
                "id": "HelloWorldWidget",
                "type": "ms.vss-dashboards-web.widget",
                "targets": [
                    "ms.vss-dashboards-web.widget-catalog"
                ],
                "properties": {
                    "name": "Hello World Widget",
                    "description": "My first widget",
                    "catalogIconUrl": "img/CatalogIcon.png",
                    "previewImageUrl": "img/preview.png",                            
                    "uri": "hello-world.html",
                    "supportedSizes": [
                         {
                                "rowSpan": 1,
                                "columnSpan": 2
                            }
                        ],
                    "supportedScopes": ["project_team"]
                }
            }
        ],
        "files": [
            {
                "path": "hello-world.html", "addressable": true
            },
            {
                "path": "sdk/scripts", "addressable": true
            },
            {
                "path": "img", "addressable": true
            }
        ]
    }

Aby uzyskać więcej informacji na temat wymaganych atrybutów, zobacz dokumentację manifestu rozszerzenia

Uwaga

Wydawca w tym miejscu musi zostać zmieniony na nazwę wydawcy. Aby utworzyć wydawcę teraz, odwiedź stronę Package/Publish/Install.

Ikony

Stanza ikon określa ścieżkę do ikony rozszerzenia w manifeście.

Udziały

Każdy wpis współtworzenia definiuje właściwości.

  • Identyfikator umożliwiający zidentyfikowanie twojego udziału. Ten identyfikator powinien być unikatowy w obrębie rozszerzenia. Ten identyfikator powinien być zgodny z nazwą użytą w kroku 3 do zarejestrowania widżetu.
  • Typ udziału. Dla wszystkich widżetów typ powinien mieć wartość ms.vss-dashboards-web.widget.
  • Tablica celów , do których przyczynia się wkład. Dla wszystkich widżetów element docelowy powinien mieć wartość [ms.vss-dashboards-web.widget-catalog].
  • Właściwości to obiekty, które zawierają właściwości typu współtworzenia. W przypadku widżetów następujące właściwości są obowiązkowe.
Właściwości Opis
name Nazwa widżetu do wyświetlenia w wykazie widżetów.
opis Opis widżetu do wyświetlenia w wykazie widżetów.
catalogIconUrl Ścieżka względna ikony wykazu dodana w kroku 4 do wyświetlenia w wykazie widżetów. Obraz powinien mieć rozmiar 98 pikseli x 98 pikseli. Jeśli użyto innej struktury folderu lub innej nazwy pliku, określ w tym miejscu odpowiednią ścieżkę względną.
previewImageUrl Względna ścieżka obrazu podglądu dodanego w kroku 4 do wyświetlenia w wykazie widżetów tylko dla programu TFS 2015 Update 3. Obraz powinien mieć rozmiar 330 pikseli x 160 pikseli. Jeśli użyto innej struktury folderu lub innej nazwy pliku, określ w tym miejscu odpowiednią ścieżkę względną.
uri Ścieżka względna pliku HTML dodanego w kroku 1. Jeśli użyto innej struktury folderu lub innej nazwy pliku, określ w tym miejscu odpowiednią ścieżkę względną.
supportedSizes Tablica rozmiarów obsługiwanych przez widżet. Gdy widżet obsługuje wiele rozmiarów, pierwszy rozmiar tablicy to domyślny rozmiar widżetu. Parametr widget size jest określony dla wierszy i kolumn zajmowanych przez widżet w siatce pulpitu nawigacyjnego. Jeden wiersz/kolumna odpowiada 160 pikseli. Każdy wymiar powyżej 1x1 pobiera dodatkowe 10 pikseli, które reprezentują rynnę między widżetami. Na przykład widżet 3x2 jest 160*3+10*2 szeroki i 160*2+10*1 wysoki. Maksymalny obsługiwany rozmiar to 4x4.
supportedScopes Obecnie obsługujemy tylko pulpity nawigacyjne zespołu. Wartość musi mieć wartość project_team. W przyszłości, gdy będziemy obsługiwać inne zakresy pulpitu nawigacyjnego, będzie więcej opcji do wyboru w tym miejscu.

Files

Stanza plików określa pliki, które chcesz dołączyć do pakietu — stronę HTML, skrypty, skrypty zestawu SDK i logo. Ustaw addressable wartość na true , chyba że dołączysz inne pliki, które nie muszą być adresowalne pod adresem URL.

Uwaga

Aby uzyskać więcej informacji na temat pliku manifestu rozszerzenia, takich jak jego właściwości i ich działania, zapoznaj się z dokumentacją manifestu rozszerzenia.

Krok 6. Pakowanie, publikowanie i udostępnianie

Po napisaniu rozszerzenia następnym krokiem w kierunku przejścia do witryny Marketplace jest spakować wszystkie pliki razem. Wszystkie rozszerzenia są pakowane jako pliki VSIX 2.0 zgodne z .vsix — firma Microsoft udostępnia międzyplatformowy interfejs wiersza polecenia (CLI) umożliwiający spakowanie rozszerzenia.

Pobieranie narzędzia do tworzenia pakietów

Możesz zainstalować lub zaktualizować międzyplatformowy interfejs wiersza polecenia dla usługi Azure DevOps (tfx-cli) przy użyciu npmskładnika Node.js z poziomu wiersza polecenia.

npm i -g tfx-cli

Pakowanie rozszerzenia

Pakowanie rozszerzenia do pliku vsix jest łatwe po utworzeniu interfejsu wiersza polecenia tfx. Przejdź do katalogu macierzystego rozszerzenia i uruchom następujące polecenie.

tfx extension create --manifest-globs vss-extension.json

Uwaga

W każdej aktualizacji należy zwiększać wersję rozszerzenia/integracji.
Podczas aktualizowania istniejącego rozszerzenia zaktualizuj wersję w manifeście lub przekaż --rev-version przełącznik wiersza polecenia. Zwiększa to numer wersji poprawki rozszerzenia i zapisuje nową wersję w manifeście.

Po utworzeniu spakowanego rozszerzenia w pliku vsix możesz opublikować rozszerzenie w witrynie Marketplace.

Tworzenie wydawcy dla rozszerzenia

Wszystkie rozszerzenia, w tym rozszerzenia firmy Microsoft, są identyfikowane jako dostarczane przez wydawcę. Jeśli nie jesteś jeszcze członkiem istniejącego wydawcy, utworzysz go.

  1. Zaloguj się do portalu publikowania w witrynie Marketplace programu Visual Studio
  2. Jeśli nie jesteś jeszcze członkiem istniejącego wydawcy, zostanie wyświetlony monit o utworzenie wydawcy. Jeśli nie zostanie wyświetlony monit o utworzenie wydawcy, przewiń w dół do dołu strony i wybierz pozycję Publikuj rozszerzenia poniżej powiązanych witryn.
    • Określ identyfikator wydawcy, na przykład: mycompany-myteam
      • Identyfikator jest używany jako wartość atrybutu w pliku manifestu publisher rozszerzeń.
    • Określ nazwę wyświetlaną wydawcy, na przykład: My Team
  3. Przejrzyj umowę wydawcy witryny Marketplace i wybierz pozycję Utwórz

Teraz wydawca jest zdefiniowany. W przyszłej wersji możesz udzielić uprawnień do wyświetlania rozszerzeń wydawcy i zarządzania nimi. Zespoły i organizacje mogą łatwo i bezpieczniej publikować rozszerzenia w ramach wspólnego wydawcy, ale bez konieczności udostępniania zestawu poświadczeń dla zestawu użytkowników.

Zaktualizuj plik manifestu vss-extension.json w przykładach, aby zastąpić fikcyjny identyfikator wydawcy identyfikatorem fabrikam wydawcy.

Publikowanie i udostępnianie rozszerzenia

Po utworzeniu wydawcy możesz teraz przekazać rozszerzenie do witryny Marketplace.

  1. Znajdź przycisk Przekaż nowe rozszerzenie, przejdź do spakowanego pliku vsix i wybierz pozycję Przekaż.

Rozszerzenie można również przekazać za pomocą wiersza polecenia, używając tfx extension publish polecenia zamiast tfx extension create spakować i opublikować rozszerzenie w jednym kroku. Opcjonalnie możesz użyć --share-with polecenia , aby udostępnić rozszerzenie co najmniej jednemu kontu po opublikowaniu. Będziesz też potrzebować osobistego tokenu dostępu.

tfx extension publish --manifest-globs your-manifest.json --share-with yourOrganization

Krok 7. Dodawanie widżetu z wykazu

  1. Przejdź do projektu w usłudze Azure DevOps, http://dev.azure.com/{yourOrganization}/{yourProject}

  2. Wybierz pozycję Przegląd, a następnie wybierz pozycję Pulpity nawigacyjne.

  3. Wybierz pozycję Dodaj widżet.

  4. Wyróżnij widżet, a następnie wybierz pozycję Dodaj.

    Widżet zostanie wyświetlony na pulpicie nawigacyjnym.

Część 2. Hello World z interfejsem API REST usługi Azure DevOps

Widżety mogą wywoływać dowolne interfejsy API REST w usłudze Azure DevOps w celu interakcji z zasobami usługi Azure DevOps. W tym przykładzie używamy interfejsu API REST dla rozwiązania WorkItemTracking do pobierania informacji o istniejącym zapytaniu i wyświetlania niektórych informacji o kwerendzie w widżecie bezpośrednio poniżej tekstu "Hello World".

Overview dashboard with a sample widget using the REST API for WorkItemTracking.

Krok 1. HTML

Skopiuj plik hello-world.html z poprzedniego przykładu i zmień nazwę kopii na hello-world2.html. Folder wygląda teraz następująco:

|--- README.md
|--- sdk    
    |--- node_modules           
    |--- scripts
        |--- VSS.SDK.min.js       
|--- img                        
    |--- logo.png                           
|--- scripts                        
|--- hello-world.html               // html page to be used for your widget  
|--- hello-world2.html              // renamed copy of hello-world.html
|--- vss-extension.json             // extension's manifest

Dodaj nowy element "div" tuż poniżej ciągu "h2", aby przechowywać informacje o kwerendzie. Zaktualizuj nazwę widżetu z "HelloWorldWidget" na "HelloWorldWidget2" w wierszu, w którym jest wywoływana nazwa "VSS.register". Dzięki temu platforma może jednoznacznie identyfikować widżet w ramach rozszerzenia. 
<!DOCTYPE html>
<html>
    <head>                          
        <script src="sdk/scripts/VSS.SDK.min.js"></script>              
        <script type="text/javascript">
            VSS.init({
                explicitNotifyLoaded: true,
                usePlatformStyles: true
            });

            VSS.require("TFS/Dashboards/WidgetHelpers", function (WidgetHelpers) {
                WidgetHelpers.IncludeWidgetStyles();
                VSS.register("HelloWorldWidget2", function () {                
                    return {
                        load: function (widgetSettings) {
                            var $title = $('h2.title');
                            $title.text('Hello World');

                            return WidgetHelpers.WidgetStatusHelper.Success();
                        }
                    }
                });
                VSS.notifyLoadSucceeded();
            });       
        </script>
    </head>
    <body>
        <div class="widget">
            <h2 class="title"></h2>
            <div id="query-info-container"></div>
        </div>
    </body>
</html>

Krok 2. Uzyskiwanie dostępu do zasobów usługi Azure DevOps

Aby umożliwić dostęp do zasobów usługi Azure DevOps, zakresy należy określić w manifeście rozszerzenia. Dodajemy zakres do naszego manifestu vso.work .
Ten zakres wskazuje, że widżet wymaga dostępu tylko do odczytu do zapytań i elementów roboczych. Zobacz wszystkie dostępne zakresy tutaj. Dodaj poniższe polecenie na końcu manifestu rozszerzenia.

{
    ...,
    "scopes":[
        "vso.work"
    ]
}

Ostrzeżenie

Dodawanie lub zmienianie zakresów po opublikowaniu rozszerzenia nie jest obecnie obsługiwane. Jeśli rozszerzenie zostało już przekazane, usuń je z witryny Marketplace. Przejdź do Visual Studio Marketplace Publishing Portalpozycji , kliknij prawym przyciskiem myszy rozszerzenie i wybierz pozycję "Usuń".

Krok 3. Wykonywanie wywołania interfejsu API REST

Istnieje wiele bibliotek po stronie klienta, do których można uzyskać dostęp za pośrednictwem zestawu SDK, aby wykonywać wywołania interfejsu API REST w usłudze Azure DevOps. Te biblioteki są nazywane klientami REST i są otokami języka JavaScript wokół wywołań Ajax dla wszystkich dostępnych punktów końcowych po stronie serwera. Możesz użyć metod udostępnianych przez tych klientów zamiast pisania wywołań Ajax samodzielnie. Te metody mapować odpowiedzi interfejsu API na obiekty, które mogą być używane przez kod.

W tym kroku zaktualizujemy VSS.require wywołanie , aby załadować TFS/WorkItemTracking/RestClientelement , który udostępnia klienta REST WorkItemTracking. Możemy użyć tego klienta REST, aby uzyskać informacje o zapytaniu o nazwie Feedback w folderze Shared Queries.

Wewnątrz funkcji, którą przekazujemy do VSS.register, tworzymy zmienną do przechowywania bieżącego identyfikatora projektu. Aby pobrać zapytanie, potrzebujemy tej zmiennej. Utworzymy również nową metodę getQueryInfo używania klienta REST. Ta metoda, która jest następnie wywoływana z metody load.

Metoda getClient udostępnia potrzebne wystąpienie klienta REST. Metoda getQuery zwraca zapytanie opakowane w obietnicę. Zaktualizowany VSS.require wygląd wygląda następująco:

VSS.require(["TFS/Dashboards/WidgetHelpers", "TFS/WorkItemTracking/RestClient"], 
    function (WidgetHelpers, TFS_Wit_WebApi) {
        WidgetHelpers.IncludeWidgetStyles();
        VSS.register("HelloWorldWidget2", function () { 
            var projectId = VSS.getWebContext().project.id;

            var getQueryInfo = function (widgetSettings) {
                // Get a WIT client to make REST calls to Azure DevOps Services
                return TFS_Wit_WebApi.getClient().getQuery(projectId, "Shared Queries/Feedback")
                    .then(function (query) {
                        // Do something with the query

                        return WidgetHelpers.WidgetStatusHelper.Success();
                    }, function (error) {                            
                        return WidgetHelpers.WidgetStatusHelper.Failure(error.message);
                    });
            }

            return {
                load: function (widgetSettings) {
                    // Set your title
                    var $title = $('h2.title');
                    $title.text('Hello World');

                    return getQueryInfo(widgetSettings);
                }
            }
        });
        VSS.notifyLoadSucceeded();
    });

Zwróć uwagę na użycie metody Failure z WidgetStatusHelperklasy . Dzięki niej można wskazać strukturę widżetów, że wystąpił błąd i skorzystać ze standardowego środowiska błędów udostępnionego wszystkim widżetom.

Jeśli nie masz Feedback zapytania w folderze Shared Queries , zastąp Shared Queries\Feedback ciąg w kodzie ścieżką zapytania, które istnieje w projekcie.

Krok 4. Wyświetlanie odpowiedzi

Ostatnim krokiem jest renderowanie informacji o kwerendzie wewnątrz widżetu. Funkcja getQuery zwraca obiekt typu Contracts.QueryHierarchyItem wewnątrz obietnicy. W tym przykładzie wyświetlamy identyfikator zapytania, nazwę zapytania i nazwę twórcy zapytania w tekście "Hello World". Zastąp // Do something with the query komentarz poniższym kodem:

    // Create a list with query details                                
    var $list = $('<ul>');                                
    $list.append($('- ').text("Query Id: " + query.id));
    $list.append($('- ').text("Query Name: " + query.name));
    $list.append($('- ').text("Created By: " + ( query.createdBy? query.createdBy.displayName: "<unknown>" ) ) );                                                            

    // Append the list to the query-info-container
    var $container = $('#query-info-container');
    $container.empty();
    $container.append($list);

Twój finał hello-world2.html wygląda następująco:

<!DOCTYPE html>
<html>
<head>    
    <script src="sdk/scripts/VSS.SDK.min.js"></script>
    <script type="text/javascript">
        VSS.init({
            explicitNotifyLoaded: true,
            usePlatformStyles: true
        });

        VSS.require(["TFS/Dashboards/WidgetHelpers", "TFS/WorkItemTracking/RestClient"], 
            function (WidgetHelpers, TFS_Wit_WebApi) {
                WidgetHelpers.IncludeWidgetStyles();
                VSS.register("HelloWorldWidget2", function () {                
                    var projectId = VSS.getWebContext().project.id;

                    var getQueryInfo = function (widgetSettings) {
                        // Get a WIT client to make REST calls to Azure DevOps Services
                        return TFS_Wit_WebApi.getClient().getQuery(projectId, "Shared Queries/Feedback")
                            .then(function (query) {
                                // Create a list with query details                                
                                var $list = $('<ul>');
                                $list.append($('- ').text("Query ID: " + query.id));
                                $list.append($('- ').text("Query Name: " + query.name));
                                $list.append($('- ').text("Created By: " + (query.createdBy ? query.createdBy.displayName: "<unknown>") ));

                                // Append the list to the query-info-container
                                var $container = $('#query-info-container');
                                $container.empty();
                                $container.append($list);

                                // Use the widget helper and return success as Widget Status
                                return WidgetHelpers.WidgetStatusHelper.Success();
                            }, function (error) {
                                // Use the widget helper and return failure as Widget Status
                                return WidgetHelpers.WidgetStatusHelper.Failure(error.message);
                            });
                    }

                    return {
                        load: function (widgetSettings) {
                            // Set your title
                            var $title = $('h2.title');
                            $title.text('Hello World');

                            return getQueryInfo(widgetSettings);
                        }
                    }
                });
            VSS.notifyLoadSucceeded();
        });       
    </script>

</head>
<body>
    <div class="widget">
        <h2 class="title"></h2>
        <div id="query-info-container"></div>
    </div>
</body>
</html>

Krok 5. Aktualizacje manifestu rozszerzenia

W tym kroku zaktualizujemy manifest rozszerzenia, aby zawierał wpis dla naszego drugiego widżetu. Dodaj nowy wkład do tablicy we contributions właściwości i dodaj nowy plik hello-world2.html do tablicy we właściwości files. Potrzebujesz innego obrazu podglądu dla drugiego widżetu. Nadaj temu preview2.png nazwę i umieść ją w folderze img .

 {
     ...,
     "contributions":[
         ...,
        {
             "id": "HelloWorldWidget2",
             "type": "ms.vss-dashboards-web.widget",
             "targets": [
                 "ms.vss-dashboards-web.widget-catalog"
             ],
             "properties": {
                 "name": "Hello World Widget 2 (with API)",
                 "description": "My second widget",
                 "previewImageUrl": "img/preview2.png",                            
                 "uri": "hello-world2.html",
                 "supportedSizes": [
                      {
                             "rowSpan": 1,
                             "columnSpan": 2
                         }
                     ],
                 "supportedScopes": ["project_team"]
             }
         }

     ],
     "files": [
         {
             "path": "hello-world.html", "addressable": true
         },
         {
             "path": "hello-world2.html", "addressable": true
         },      
         {
             "path": "sdk/scripts", "addressable": true
         },
         {
             "path": "img", "addressable": true
         }
     ],
     "scopes":[
         "vso.work"
     ]
 }

Krok 6. Pakowanie, publikowanie i udostępnianie

Pakowanie, publikowanie i udostępnianie rozszerzenia. Jeśli rozszerzenie zostało już opublikowane, możesz ponownie spakować rozszerzenie i bezpośrednio zaktualizować je do witryny Marketplace.

Krok 7. Dodawanie widżetu z katalogu

Teraz przejdź do pulpitu nawigacyjnego zespołu pod adresem https:\//dev.azure.com/{yourOrganization}/{yourProject}. Jeśli ta strona jest już otwarta, odśwież ją. Zatrzymaj wskaźnik myszy na przycisku Edytuj w prawym dolnym rogu i wybierz przycisk Dodaj. Zostanie otwarty katalog widżetów, w którym znajdziesz zainstalowany widżet. Wybierz widżet i wybierz przycisk "Dodaj", aby dodać go do pulpitu nawigacyjnego.

Część 3. Hello World z konfiguracją

W części 2 tego przewodnika pokazano, jak utworzyć widżet przedstawiający informacje o zapytaniach dla zakodowanego zapytania. W tej części dodajemy możliwość skonfigurowania zapytania do użycia zamiast zakodowanego na dysku twardym. W trybie konfiguracji użytkownik będzie widzieć podgląd na żywo widżetu na podstawie ich zmian. Te zmiany zostaną zapisane w widżecie na pulpicie nawigacyjnym, gdy użytkownik wybierze pozycję Zapisz.

Overview dashboard live preview of the widget based on changes.

Krok 1. HTML

Implementacje widżetów i konfiguracji widżetów są bardzo podobne. Oba są implementowane w strukturze rozszerzeń jako współtworzenie. Oba używają tego samego pliku zestawu SDK, VSS.SDK.min.js. Oba są oparte na językach HTML, JavaScript i CSS.

Skopiuj plik html-world2.html z poprzedniego przykładu i zmień nazwę kopii na hello-world3.html. Dodaj kolejny plik HTML o nazwie configuration.html. Folder wygląda teraz jak w poniższym przykładzie:

|--- README.md
|--- sdk    
    |--- node_modules           
    |--- scripts
        |--- VSS.SDK.min.js       
|--- img                        
    |--- logo.png                           
|--- scripts          
|--- configuration.html                          
|--- hello-world.html               // html page to be used for your widget  
|--- hello-world2.html              // renamed copy of hello-world.html
|--- hello-world3.html              // renamed copy of hello-world2.html
|--- vss-extension.json             // extension's manifest

Dodaj poniższy kod HTML w pliku "configuration.html". W zasadzie dodajemy obowiązkowe odwołanie do usługi VSS. Plik SDK.min.js i element "select" listy rozwijanej, aby wybrać zapytanie z listy wstępnie ustawionej. 
    <!DOCTYPE html>
    <html xmlns="http://www.w3.org/1999/xhtml">
        <head>                          
            <script src="sdk/scripts/VSS.SDK.min.js"></script>              
        </head>
        <body>
            <div class="container">
                <fieldset>
                    <label class="label">Query: </label>
                    <select id="query-path-dropdown" style="margin-top:10px">
                        <option value="" selected disabled hidden>Please select a query</option>
                        <option value="Shared Queries/Feedback">Shared Queries/Feedback</option>
                        <option value="Shared Queries/My Bugs">Shared Queries/My Bugs</option>
                        <option value="Shared Queries/My Tasks">Shared Queries/My Tasks</option>                        
                    </select>
                </fieldset>             
            </div>
        </body>
    </html>

Krok 2. JavaScript — konfiguracja

Użyj języka JavaScript, aby renderować zawartość w konfiguracji widżetu tak jak w przypadku widżetu w kroku 3 części 1 w tym przewodniku. Ten kod JavaScript renderuje zawartość, inicjuje zestaw VSS SDK, mapuje kod konfiguracji widżetu na nazwę konfiguracji i przekazuje ustawienia konfiguracji do platformy. W naszym przypadku poniżej znajduje się kod, który ładuje konfigurację widżetu. Otwórz plik configuration.html i poniższy <script> element w pliku <head>.

    <script type="text/javascript">
        VSS.init({                        
            explicitNotifyLoaded: true,
            usePlatformStyles: true
        });

        VSS.require("TFS/Dashboards/WidgetHelpers", function (WidgetHelpers) {
            VSS.register("HelloWorldWidget.Configuration", function () {   
                var $queryDropdown = $("#query-path-dropdown"); 

                return {
                    load: function (widgetSettings, widgetConfigurationContext) {
                        var settings = JSON.parse(widgetSettings.customSettings.data);
                        if (settings && settings.queryPath) {
                             $queryDropdown.val(settings.queryPath);
                         }

                        return WidgetHelpers.WidgetStatusHelper.Success();
                    },
                    onSave: function() {
                        var customSettings = {
                            data: JSON.stringify({
                                    queryPath: $queryDropdown.val()
                                })
                        };
                        return WidgetHelpers.WidgetConfigurationSave.Valid(customSettings); 
                    }
                }
            });
            VSS.notifyLoadSucceeded();
        });
    </script>

VSS.init, VSS.requirei VSS.register odgrywają taką samą rolę, jak w przypadku widżetu, zgodnie z opisem w części 1. Jedyną różnicą jest to, że w przypadku konfiguracji widżetów przekazywana funkcja VSS.register powinna zwrócić obiekt spełniający IWidgetConfiguration kontrakt.

Właściwość load kontraktu IWidgetConfiguration powinna mieć funkcję jako jego wartość. Ta funkcja zawiera zestaw kroków renderowania konfiguracji widżetu. W naszym przypadku należy zaktualizować wybraną wartość elementu listy rozwijanej przy użyciu istniejących ustawień, jeśli istnieją. Ta funkcja jest wywoływana, gdy platforma tworzy wystąpienie widget configuration

Właściwość onSave kontraktu IWidgetConfiguration powinna mieć funkcję jako jego wartość. Ta funkcja jest wywoływana przez platformę, gdy użytkownik wybierze pozycję Zapisz w okienku konfiguracji. Jeśli dane wejściowe użytkownika są gotowe do zapisania, serializuj je w ciągu, utwórz custom settings obiekt i użyj polecenia WidgetConfigurationSave.Valid() , aby zapisać dane wejściowe użytkownika.

W tym przewodniku używamy formatu JSON do serializacji danych wejściowych użytkownika w ciągu. Możesz wybrać dowolny inny sposób serializacji danych wejściowych użytkownika do ciągu. Jest dostępny dla widżetu za pośrednictwem właściwości WidgetSettings custom Ustawienia obiektu. Widżet musi wykonać deserializacji, który został omówiony w kroku 4.

Krok 3. JavaScript — włączanie podglądu na żywo

Aby włączyć aktualizację podglądu na żywo, gdy użytkownik wybierze zapytanie z listy rozwijanej, dołączymy procedurę obsługi zdarzeń zmiany do przycisku. Ta procedura obsługi powiadamia platformę o zmianie konfiguracji. Przekazuje również element customSettings , który ma być używany do aktualizowania wersji zapoznawczej. Aby powiadomić platformę, notify należy wywołać metodę .widgetConfigurationContext Przyjmuje dwa parametry, nazwę zdarzenia, które w tym przypadku to WidgetHelpers.WidgetEvent.ConfigurationChange, i EventArgs obiekt zdarzenia, utworzony na podstawie customSettingsWidgetEvent.Args metody pomocnika.

Dodaj poniższe polecenie w funkcji przypisanej load do właściwości .

 $queryDropdown.on("change", function () {
     var customSettings = {
        data: JSON.stringify({
                queryPath: $queryDropdown.val()
            })
     };
     var eventName = WidgetHelpers.WidgetEvent.ConfigurationChange;
     var eventArgs = WidgetHelpers.WidgetEvent.Args(customSettings);
     widgetConfigurationContext.notify(eventName, eventArgs);
 });

Należy powiadomić strukturę zmiany konfiguracji co najmniej raz, aby można było włączyć przycisk "Zapisz".

Na końcu twój configuration.html wygląd wygląda następująco:

    <!DOCTYPE html>
    <html xmlns="http://www.w3.org/1999/xhtml">
        <head>                          
            <script src="sdk/scripts/VSS.SDK.min.js"></script>      
            <script type="text/javascript">
                VSS.init({                        
                    explicitNotifyLoaded: true,
                    usePlatformStyles: true
                });

                VSS.require("TFS/Dashboards/WidgetHelpers", function (WidgetHelpers) {
                    VSS.register("HelloWorldWidget.Configuration", function () {   
                        var $queryDropdown = $("#query-path-dropdown");

                        return {
                            load: function (widgetSettings, widgetConfigurationContext) {
                                var settings = JSON.parse(widgetSettings.customSettings.data);
                                if (settings && settings.queryPath) {
                                     $queryDropdown.val(settings.queryPath);
                                 }

                                 $queryDropdown.on("change", function () {
                                     var customSettings = {data: JSON.stringify({queryPath: $queryDropdown.val()})};
                                     var eventName = WidgetHelpers.WidgetEvent.ConfigurationChange;
                                     var eventArgs = WidgetHelpers.WidgetEvent.Args(customSettings);
                                     widgetConfigurationContext.notify(eventName, eventArgs);
                                 });

                                return WidgetHelpers.WidgetStatusHelper.Success();
                            },
                            onSave: function() {
                                var customSettings = {data: JSON.stringify({queryPath: $queryDropdown.val()})};
                                return WidgetHelpers.WidgetConfigurationSave.Valid(customSettings); 
                            }
                        }
                    });
                    VSS.notifyLoadSucceeded();
                });
            </script>       
        </head>
        <body>
            <div class="container">
                <fieldset>
                    <label class="label">Query: </label>
                    <select id="query-path-dropdown" style="margin-top:10px">
                        <option value="" selected disabled hidden>Please select a query</option>
                        <option value="Shared Queries/Feedback">Shared Queries/Feedback</option>
                        <option value="Shared Queries/My Bugs">Shared Queries/My Bugs</option>
                        <option value="Shared Queries/My Tasks">Shared Queries/My Tasks</option>                        
                    </select>
                </fieldset>     
            </div>
        </body>
    </html>

Krok 4. JavaScript — implementowanie ponownego ładowania w widżecie

Skonfigurowaliśmy konfigurację widżetu do przechowywania ścieżki zapytania wybranej przez użytkownika. Teraz musimy zaktualizować kod w widżecie, aby użyć tej przechowywanej konfiguracji zamiast zakodowanej Shared Queries/Feedback na podstawie poprzedniego przykładu.

Otwórz plik hello-world3.html i zaktualizuj nazwę widżetu z HelloWorldWidget2 do HelloWorldWidget3 w wierszu, w którym wywołujesz polecenie VSS.register. Dzięki temu platforma może jednoznacznie identyfikować widżet w ramach rozszerzenia.

Funkcja zamapowana na HelloWorldWidget3 obecnie VSS.register zwraca obiekt, który spełnia IWidget kontrakt. Ponieważ nasz widżet wymaga teraz konfiguracji, ta funkcja musi zostać zaktualizowana, aby zwrócić obiekt spełniający umowę IConfigurableWidget . W tym celu zaktualizuj instrukcję return, aby uwzględnić właściwość o nazwie reload, jak pokazano poniżej. Wartość tej właściwości jest funkcją, która wywołuje metodę getQueryInfo jeszcze raz. Ta metoda ponownego ładowania jest wywoływana przez strukturę za każdym razem, gdy użytkownik wprowadza zmiany w celu wyświetlenia podglądu na żywo. Jest to również wywoływane podczas zapisywania konfiguracji.

return {
    load: function (widgetSettings) {
        // Set your title
        var $title = $('h2.title');
        $title.text('Hello World');

        return getQueryInfo(widgetSettings);
    },
    reload: function (widgetSettings) {
        return getQueryInfo(widgetSettings);
    }
}

Zakodowana na stałe ścieżka zapytania w poleceniu "getQueryInfo" powinna zostać zastąpiona skonfigurowaną ścieżką zapytania, którą można wyodrębnić z parametru "widget Ustawienia", który jest przekazywany do metody. Dodaj poniższe elementy na początku metody "getQueryInfo" i zastąp zakodowaną ścieżkę zapytania ciągiem "settings.queryPath". 
var settings = JSON.parse(widgetSettings.customSettings.data);
if (!settings || !settings.queryPath) {
    var $container = $('#query-info-container');
    $container.empty();
    $container.text("Sorry nothing to show, please configure a query path.");

    return WidgetHelpers.WidgetStatusHelper.Success();
}

Na tym etapie widżet jest gotowy do renderowania przy użyciu skonfigurowanych ustawień.

load Właściwości i reload mają podobną funkcję. Jest to przypadek większości prostych widżetów. W przypadku złożonych widżetów istnieją pewne operacje, które chcesz uruchomić tylko raz bez względu na liczbę zmian konfiguracji. Mogą też istnieć pewne operacje o dużej wadze, które nie muszą być uruchamiane więcej niż raz. Takie operacje byłyby częścią funkcji odpowiadającej load właściwości, a nie reload właściwości.

Krok 5. Aktualizacje manifestu rozszerzenia

Otwórz plik, vss-extension.json aby dołączyć dwa nowe wpisy do tablicy we contributions właściwości . Jeden dla widżetu HelloWorldWidget3 i drugi dla jego konfiguracji. Potrzebujesz jeszcze innego obrazu podglądu dla trzeciego widżetu. Nadaj temu preview3.png nazwę i umieść ją w folderze img . Zaktualizuj tablicę we właściwości , files aby uwzględnić dwa nowe pliki HTML dodane w tym przykładzie.

{
    ...
    "contributions": [
        ... , 
        {
             "id": "HelloWorldWidget3",
             "type": "ms.vss-dashboards-web.widget",
             "targets": [
                 "ms.vss-dashboards-web.widget-catalog",
                 "fabrikam.vsts-extensions-myExtensions.HelloWorldWidget.Configuration"
             ],
             "properties": {
                 "name": "Hello World Widget 3 (with config)",
                 "description": "My third widget",
                 "previewImageUrl": "img/preview3.png",                       
                 "uri": "hello-world3.html",
                 "supportedSizes": [
                      {
                             "rowSpan": 1,
                             "columnSpan": 2
                         }
                     ],
                 "supportedScopes": ["project_team"]
             }
         },
         {
             "id": "HelloWorldWidget.Configuration",
             "type": "ms.vss-dashboards-web.widget-configuration",
             "targets": [ "ms.vss-dashboards-web.widget-configuration" ],
             "properties": {
                 "name": "HelloWorldWidget Configuration",
                 "description": "Configures HelloWorldWidget",
                 "uri": "configuration.html"
             }
         }
    ],
    "files": [
            {
                "path": "hello-world.html", "addressable": true
            },
             {
                "path": "hello-world2.html", "addressable": true
            },
            {
                "path": "hello-world3.html", "addressable": true
            },
            {
                "path": "configuration.html", "addressable": true
            },
            {
                "path": "sdk/scripts", "addressable": true
            },
            {
                "path": "img", "addressable": true
            }
        ],
        ...     
}

Zwróć uwagę, że współtworzenie konfiguracji widżetu jest nieco inne niż sam widżet. Wpis współtworzenia dla konfiguracji widżetu ma następujące elementy:
  • Identyfikator umożliwiający zidentyfikowanie twojego udziału. Powinno to być unikatowe w obrębie rozszerzenia.
  • Typ udziału. W przypadku wszystkich konfiguracji widżetu powinno to być ms.vss-dashboards-web.widget-configuration
  • Tablica celów , do których przyczynia się wkład. W przypadku wszystkich konfiguracji widżetów ma on jeden wpis: ms.vss-dashboards-web.widget-configuration.
  • Właściwości zawierające zestaw właściwości, które zawierają nazwę, opis i identyfikator URI pliku HTML używanego do konfiguracji.

Aby obsługiwać konfigurację, należy również zmienić współtworzenie widżetu. Tablica obiektów docelowych dla widżetu musi zostać zaktualizowana, aby uwzględnić identyfikator konfiguracji w postaci>>id for the extension<publisher< .. W tym przypadku jest to .id for the configuration contribution<>fabrikam.vsts-extensions-myExtensions.HelloWorldWidget.Configuration

Ostrzeżenie

Jeśli wpis współtworzenia dla konfigurowalnego widżetu nie jest przeznaczony dla konfiguracji przy użyciu odpowiedniego wydawcy i nazwy rozszerzenia zgodnie z wcześniejszym opisem, przycisk konfiguracji nie jest wyświetlany dla widżetu.

Na końcu tej części plik manifestu powinien zawierać trzy widżety i jedną konfigurację. Pełny manifest możesz pobrać z przykładu tutaj.

Krok 6. Pakowanie, publikowanie i udostępnianie

Jeśli rozszerzenie nie zostało jeszcze opublikowane, przeczytaj tę sekcję , aby spakować, opublikować i udostępnić rozszerzenie. Jeśli rozszerzenie zostało już opublikowane przed tym punktem, możesz ponownie spakować rozszerzenie i bezpośrednio zaktualizować je do witryny Marketplace.

Krok 7. Dodawanie widżetu z katalogu

Teraz przejdź do pulpitu nawigacyjnego zespołu na stronie https://dev.azure.com/{yourOrganization}/{yourProject}. Jeśli ta strona jest już otwarta, odśwież ją. Zatrzymaj wskaźnik myszy na przycisku Edytuj w prawym dolnym rogu i wybierz przycisk Dodaj. Powinno to spowodować otwarcie katalogu widżetów, w którym znajduje się zainstalowany widżet. Wybierz widżet i wybierz przycisk "Dodaj", aby dodać go do pulpitu nawigacyjnego.

Zostanie wyświetlony komunikat z prośbą o skonfigurowanie widżetu.

Overview dashboard with a sample widget from the catalog.

Istnieją dwa sposoby konfigurowania widżetów. Jednym z nich jest zatrzymanie wskaźnika myszy na widżecie, wybranie wielokropka wyświetlanego w prawym górnym rogu, a następnie wybranie pozycji Konfiguruj. Drugi to wybranie przycisku Edytuj w prawym dolnym rogu pulpitu nawigacyjnego, a następnie wybranie przycisku konfiguruj, który zostanie wyświetlony w prawym górnym rogu widżetu. Po prawej stronie zostanie otwarte środowisko konfiguracji i podgląd widżetu w środku. Przejdź dalej i wybierz zapytanie z listy rozwijanej. Podgląd na żywo pokazuje zaktualizowane wyniki. Wybierz pozycję "Zapisz", a widżet wyświetla zaktualizowane wyniki.

Krok 8. Konfigurowanie większej liczby (opcjonalnie)

Do dodatkowej configuration.html konfiguracji można dodać dowolną liczbę elementów formularza HTML. Dostępne są dwie konfigurowalne funkcje: nazwa widżetu i rozmiar widżetu.

Domyślnie nazwa podana dla widżetu w manifeście rozszerzenia jest przechowywana jako nazwa widżetu dla każdego wystąpienia widżetu, które kiedykolwiek zostanie dodane do pulpitu nawigacyjnego. Możesz zezwolić użytkownikom na skonfigurowanie tej funkcji, aby mogli dodać dowolną nazwę, którą chcą mieć w swoim wystąpieniu widżetu. Aby zezwolić na taką konfigurację, dodaj isNameConfigurable:true w sekcji właściwości widżetu w manifeście rozszerzenia.

Jeśli podasz więcej niż jeden wpis dla widżetu w tablicy supportedSizes w manifeście rozszerzenia, użytkownicy będą mogli również skonfigurować rozmiar widżetu.

Manifest rozszerzenia dla trzeciego przykładu w tym przewodniku będzie wyglądać podobnie do poniższego, jeśli włączymy konfigurację nazwy widżetu i rozmiaru:

{
    ...
    "contributions": [
        ... , 
        {
             "id": "HelloWorldWidget3",
             "type": "ms.vss-dashboards-web.widget",
             "targets": [
                 "ms.vss-dashboards-web.widget-catalog",  "fabrikam.vsts-extensions-myExtensions.HelloWorldWidget.Configuration"
             ],
             "properties": {
                 "name": "Hello World Widget 3 (with config)",
                 "description": "My third widget",
                 "previewImageUrl": "img/preview3.png",                       
                 "uri": "hello-world3.html",
                 "isNameConfigurable": true,
                 "supportedSizes": [
                    {
                        "rowSpan": 1,
                        "columnSpan": 2
                    },
                    {
                        "rowSpan": 2,
                        "columnSpan": 2
                    }
                 ],
                 "supportedScopes": ["project_team"]
             }
         },
         ...
}

Po poprzedniej zmianie ponownie spakuj i zaktualizuj rozszerzenie. Odśwież pulpit nawigacyjny z tym widżetem (Hello World Widget 3 (z konfiguracją)). Otwórz tryb konfiguracji widżetu. Teraz powinna być widoczna opcja zmiany nazwy i rozmiaru widżetu.

Widget where name and size can be configured

Przejdź dalej i wybierz inny rozmiar z listy rozwijanej. Zostanie wyświetlona zmiana rozmiaru podglądu na żywo. Zapisz zmianę, a widżet na pulpicie nawigacyjnym również zostanie zmieniony.

Ostrzeżenie

Jeśli usuniesz już obsługiwany rozmiar, widżet nie zostanie załadowany poprawnie. Pracujemy nad poprawką dla przyszłej wersji.

Zmiana nazwy widżetu nie powoduje żadnej widocznej zmiany w widżecie. Dzieje się tak, ponieważ nasze przykładowe widżety nie wyświetlają nigdzie nazwy widżetu. Zmodyfikujmy przykładowy kod, aby wyświetlić nazwę widżetu zamiast zakodowanego tekstu "Hello World".

W tym celu zastąp zakodowany tekst "Hello World" ciągiem widgetSettings.name w wierszu, w którym ustawiamy tekst h2 elementu. Dzięki temu nazwa widżetu jest wyświetlana za każdym razem, gdy widżet zostanie załadowany podczas odświeżania strony. Ponieważ chcemy, aby podgląd na żywo był aktualizowany za każdym razem, gdy zmienia się konfiguracja, należy również dodać ten sam kod w reload części naszego kodu. Końcowa instrukcja return w pliku hello-world3.html jest następująca:

return {
    load: function (widgetSettings) {
        // Set your title
        var $title = $('h2.title');
        $title.text(widgetSettings.name);

        return getQueryInfo(widgetSettings);
    },
    reload: function (widgetSettings) {
        // Set your title
        var $title = $('h2.title');
        $title.text(widgetSettings.name);

        return getQueryInfo(widgetSettings);
    }
}

Ponownie spakuj i zaktualizuj rozszerzenie. Odśwież pulpit nawigacyjny z tym widżetem. Wszelkie zmiany nazwy widżetu w trybie konfiguracji aktualizują teraz tytuł widżetu.