Diretrizes de navegação vertical

Serviços do Azure DevOps

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

Contexto da equipe

Na navegação horizontal tradicional, os usuários podem ir para um projeto ou equipe selecionando em um seletor que está no canto superior esquerdo do cabeçalho da página. Este seletor apresentou uma lista de equipes recentes e um meio de navegar por 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, 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 confiar em SDK.getWebContext().team. Em vez disso, siga as orientações abaixo, com base na categoria em que sua extensão se enquadra.

Extensões de hub com reconhecimento de 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 da 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 de pivot e de painel

Sua extensão pode verificar o objeto de configuração passado para sua contribuição. Esse objeto tem propriedades diferentes, dependendo do tipo de contribuição e de onde a contribuição está hospedada. O exemplo mostra a equipe de leitura da configuração e o retorno à 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ção

Sua extensão pode verificar o objeto actionContext passado para o retorno de chamada invocado quando um usuário seleciona o item de menu contribuído. 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 seu hub. Este ícone aparece ao lado do hub na barra de navegação vertical. Ele deve estar empacotado junto com sua extensão.

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

1. Defina a propriedade iconAsset da contribuição do hub como 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 propriedade de contribuição includesData.

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

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