Diretrizes de navegação vertical

Azure DevOps Services

A navegação vertical traz alterações que afetam algumas extensões. Esses resultados incluem suporte para ícones de extensão, juntamente com alterações no contexto da equipe.

Dica

Confira nossa documentação mais recente sobre o desenvolvimento de extensão usando o SDK da Extensão do Azure DevOps.

Contexto da equipe

Na navegação horizontal tradicional, os usuários podem ir para um projeto ou equipe selecionando de um seletor que está no canto superior esquerdo do cabeçalho da página. Esse seletor apresentou uma lista de equipes recentes e uma maneira de procurar todas as equipes. Na nova navegação vertical, um usuário só pode navegar em um projeto (e não em uma equipe). Essa alteração foi feita para simplificar a experiência geral. No entanto, ele introduziu um desafio para extensões da Web que dependem da capacidade dos usuários de alternar equipes usando o seletor de equipe tradicional no cabeçalho da página.

SDK.getWebContext() é uma API do lado do cliente fornecida pelo SDK que fornece informações sobre a organização, o projeto e a equipe atuais em que o usuário está operando:

{
    "account": {
        "name": "Fabrikam",
        "id": "50e49b94-4bb6-40e7-8c85-a6d756d8a4d8"
    },
    "project": {
        "name": "Fabrikam Dev",
        "id": "049b1af2-fc87-4e50-95e4-151357f04b7f"
    },
    "team": {
        "name": "Ops Team",
        "id": "9b3a6b80-fe95-4c8c-8aa1-1e5d535d7af1"
    }
}

Não recomendamos depender de SDK.getWebContext().team. Em vez disso, siga as diretrizes abaixo, com base na categoria em que sua extensão se enquadra.

Extensões de hub que estão cientes da equipe

Se sua extensão precisar fornecer aos usuários uma maneira de selecionar uma equipe, você poderá usar a API REST do Teams para obter uma lista de equipes para o projeto atual. O exemplo a seguir mostra como chamar essa API de sua extensão.

import { getClient } from "azure-devops-extension-api";
import { CoreRestClient } from "azure-devops-extension-api/Core";
import * as SDK from "azure-devops-extension-sdk";

private async getTeams() {
    const client = getClient(CoreRestClient);
    
    client.getTeams(SDK.getWebContext().project.id).then(
        function(teams) {
            console.log(teams);
        }
    );
}

Para obter um exemplo de uma extensão que fornece um controle de seletor de equipe, consulte Calendário da Equipe.

Extensões dinâmicas/painéis que estão em hubs com reconhecimento de equipe, como Backlogs e Dashboard

Sua extensão pode marcar o objeto de configuração passado para sua contribuição. Esse objeto tem propriedades diferentes dependendo do tipo de contribuição e do local em que a contribuição está hospedada. O exemplo mostra a equipe de leitura da configuração e a queda para a equipe de leitura do webContext para dar suporte à nova navegação vertical e à navegação horizontal mais antiga em versões locais.

function getCurrentTeam() {
  let webContext = SDK.getWebContext();
  let configuration = SDK.getConfiguration();

  if ("team" in configuration) {
    return configuration.team;
  } else if ("team" in webContext) {
    return webContext.team;
  } else {
    return null; // should only happen if not in a project context
  }
}

Extensões de ações que estão em hubs com reconhecimento de equipe, como Backlogs e Dashboard

Sua extensão pode marcar o objeto actionContext passado para o retorno de chamada invocado quando um usuário seleciona o item de menu de contribuição. O exemplo mostra a equipe de leitura do actionContext.

var menuContributionHandler = (function () {
        "use strict";
        return {
            // This is a callback that gets invoked when a user selects the newly contributed menu item
            // The actionContext parameter contains team information.
            execute: function (actionContext) {
                if("team" in actionContext) {
                    alert(`Team. Id is ${actionContext.team.id}, Name is ${actionContext.team.name}`);
                }
            }
        };
    }());

Ícone do hub

Opcionalmente, você pode definir um ativo (como um .png ou .jpg) como o ícone do hub. Esse ícone aparece ao lado do hub na barra de navegação vertical. Ele deve ser empacotado com sua extensão.

Observação

Esses ícones não aparecem na navegação horizontal.

Conclua as etapas a seguir para definir um ícone para o hub.

1. Defina a iconAsset propriedade da contribuição do hub para o identificador de ativo totalmente qualificado, que segue o padrão: {publisher-id}.{extension-id}/{asset-path}.

2. Adicione uma entrada para esse ativo na includesata propriedade de contribuição.

3. Empacote o ativo com sua extensão listando-o files na propriedade na raiz do manifesto.

Exemplo nº 1:

{
  "id": "my-extension",
  "publisherId": "my-publisher",
  ...
  "contributions": [
        {
            "id": "example-hub",
            "type": "ms.vss-web.hub",
            "targets": [
                "ms.vss-code-web.code-hub-group"
            ],
            "properties": {
                "name": "My Hub",
                "iconAsset": "my-publisher.my-extension/images/fabrikam-logo.png",
                "includesData": {
                    "assets": [
                        "my-publisher.my-extension/images/fabrikam-logo.png"
                    ]
                }
            }
       }
  ],
 "files": [
     {
         "path": "images/fabrikam-logo.png",
         "addressable": true
     }
 ]
}

Exemplo nº 2:

Quando temas como claro versus escuro são aplicados, você pode especificar os ícones no manifesto da extensão da seguinte maneira.

{
    "id": "hub",
    "type": "ms.vss-web.hub",
    "targets": [
        "ms.vss-work-web.work-hub-group"
    ],
    "properties": {
        "name": "Hub",
        "description": "Something",
        "uri": "pages/Hub.html",
        "icon": {
            "light": "img/hub-light.png",
            "dark": "img/hub-dark.png"
        }
    }
}