Utilizar o controlo de mapa do Azure Maps

A biblioteca JavaScript do lado do cliente do Controlo de Mapas permite-lhe renderizar mapas e incorporar a funcionalidade Azure Maps na sua aplicação web ou móvel.

Esta documentação utiliza o Azure Maps Web SDK, no entanto os serviços Azure Maps podem ser utilizados com qualquer controlo de mapas. Aqui estão alguns populares controlos de mapas abertos para os que a equipa do Azure Maps criou plugin's.

Pré-requisitos

Para utilizar o Controlo do Mapa numa página web, deve ter um dos seguintes pré-requisitos:

Criar um novo mapa numa página web

Pode incorporar um mapa numa página web utilizando a biblioteca JavaScript do lado do cliente do Controlo de Mapas.

  1. Crie um novo ficheiro HTML.

  2. Carregue no Azure Maps Web SDK. Pode escolher uma de duas opções:

    • Utilize a versão CDN globalmente hospedada do Azure Maps Web SDK adicionando referências ao JavaScript e à folha de estilo no <head> elemento do ficheiro HTML:

      <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.css" type="text/css">
      <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.js"></script>
      
    • Carregue o código fonte SDK web Azure Maps localmente usando o pacote NPM de controlo de mapas azure e acolhê-lo com a sua aplicação. Este pacote também inclui definições typeScript.

      npm instalar azure-maps-control

    Em seguida, adicione referências à folha de estilo Azure Maps ao <head> elemento do ficheiro:

    <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.css" type="text/css" />
    

    Nota

    As definições de escrita podem ser importadas para a sua aplicação adicionando o seguinte código:

    import * as atlas from 'azure-maps-control';
    
  3. Para tornar o mapa de modo a preencher todo o corpo da página, adicione o <style> seguinte elemento ao <head> elemento.

     <style>
         html, body {
             margin: 0;
         }
    
         #myMap {
             height: 100vh;
             width: 100vw;
         }
     </style>
    
  4. No corpo da página, adicione um <div> elemento e dê-lhe um id dos meus Mapas.

     <body onload="InitMap()">
         <div id="myMap"></div>
     </body>
    
  5. Agora, vamos inicializar o controlo do mapa. Para autenticar o controlo, você terá de possuir uma chave de subscrição Azure Maps ou usar credenciais Azure Ative Directory (AAD) com opções de autenticação.

    Se estiver a utilizar uma chave de subscrição para autenticação, copie e cole o seguinte elemento de script dentro do <head> elemento e abaixo do primeiro <script> elemento. Substitua <Your Azure Maps Key> a sua chave de subscrição primária do Azure Maps.

    <script type="text/javascript">
       function InitMap()
       {
           var map = new atlas.Map('myMap', {
               center: [-122.33, 47.6],
               zoom: 12,
               language: 'en-US',
               authOptions: {
                   authType: 'subscriptionKey',
                   subscriptionKey: '<Your Azure Maps Key>'
               }
           });
      }
    </script>
    

    Se estiver a utilizar o Azure Ative Directory (AAD) para autenticação, copie e cole o seguinte elemento de script dentro do <head> elemento e abaixo do primeiro <script> elemento.

    <script type="text/javascript">
      function InitMap()
      {
          var map = new atlas.Map('myMap', {
              center: [-122.33, 47.6],
              zoom: 12,
              language: 'en-US',
              authOptions: {
                  authType: 'aad',
                  clientId: '<Your AAD Client Id>',
                  aadAppId: '<Your AAD App Id>',
                  aadTenant: '<Your AAD Tenant Id>'
              }
          });
      }
    </script>
    

    Para obter mais informações sobre a autenticação com o Azure Maps, consulte o documento Autenticação com Mapas Azure. Além disso, uma lista de amostras que mostram como integrar o Azure Ative Directory (AAD) com a Azure Maps pode ser consultada aqui.

    Dica

    Neste exemplo, passamos no id <div> mapa. Outra forma de fazer isso é passar no HTMLElement objeto passando document.getElementById('myMap') como o primeiro parâmetro.

  6. Opcionalmente, poderá achar útil adicionar os meta seguintes elementos ao head elemento da página:

     <!-- Ensures that IE and Edge uses the latest version and doesn't emulate an older version -->
     <meta http-equiv="x-ua-compatible" content="IE=Edge">
    
     <!-- Ensures the web page looks good on all screen sizes. -->
     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    
  7. Juntando tudo, o seu ficheiro HTML deve parecer algo como a seguinte marcação:

     <!DOCTYPE html>
     <html>
     <head>
         <title></title>
    
         <meta charset="utf-8">
    
         <!-- Ensures that IE and Edge uses the latest version and doesn't emulate an older version -->
         <meta http-equiv="x-ua-compatible" content="IE=Edge">
    
         <!-- Ensures the web page looks good on all screen sizes. -->
         <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    
         <!-- Add references to the Azure Maps Map control JavaScript and CSS files. -->
         <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.css" type="text/css">
         <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/2/atlas.min.js"></script>
    
    
         <script type="text/javascript">
             //Create an instance of the map control and set some options.
             function InitMap()
             {
                 var map = new atlas.Map('myMap', {
                     center: [-122.33, 47.6],
                     zoom: 12,
                     language: 'en-US',
                     authOptions: {
                         authType: 'subscriptionKey',
                         subscriptionKey: '<Your Azure Maps Key>'
                     }
                 });
             }
         </script>
    
         <style>
             html, body {
                 margin: 0;
             }
    
             #myMap {
                 height: 100vh;
                 width: 100vw;
             }
         </style>
     </head>
     <body onload="InitMap()">
         <div id="myMap"></div>
     </body>
     </html>
    
  8. Abra o ficheiro no seu navegador web e veja o mapa renderizado. Deve parecer a imagem abaixo:

    Imagem de mapa mostrando resultado renderizado

<a name="localizing-the-map">Localização do mapa

O Azure Maps fornece duas maneiras diferentes de definir a língua e a visão regional para o mapa renderizado. A primeira opção é adicionar esta informação ao espaço de nome global, o atlas que resultará em todas as instâncias de controlo de mapas na sua aplicação por defeito nestas definições. O seguinte define a língua para o francês ("fr-FR") e a visão regional para "Auto":

atlas.setLanguage('fr-FR');
atlas.setView('Auto');

A segunda opção é passar esta informação para as opções do mapa ao carregar o mapa assim:

map = new atlas.Map('myMap', {
    language: 'fr-FR',
    view: 'Auto',

    authOptions: {
        authType: 'aad',
        clientId: '<Your AAD Client Id>',
        aadAppId: '<Your AAD App Id>',
        aadTenant: '<Your AAD Tenant Id>'
    }
});

Nota

É possível carregar várias instâncias de mapa na mesma página com diferentes configurações de linguagem e região. Além disso, estas definições podem ser atualizadas após as cargas do mapa utilizando a setStyle função do mapa.

Aqui está um exemplo de Azure Maps com a linguagem definida para "fr-FR" e a visão regional definida para "Auto".

Imagem de mapa mostrando rótulos em francês

Está aqui documentada umalista completa das línguas apoiadas e dos pontos de vista regionais.

Apoio à nuvem do Governo de Azure

O Azure Maps Web SDK suporta a nuvem do Governo Azure. Todos os URLs JavaScript e CSS utilizados para aceder ao Azure Maps Web SDK permanecem os mesmos. As seguintes tarefas terão de ser feitas para se ligar à versão em nuvem do Governo Azure da plataforma Azure Maps.

Quando utilizar o controlo interativo do mapa, adicione a seguinte linha de código antes de criar uma instância da Map classe.

atlas.setDomain('atlas.azure.us');

Certifique-se de que utiliza os detalhes de autenticação do Azure Maps a partir da plataforma cloud do Governo Azure ao autenticar o mapa e os serviços.

Ao utilizar o módulo de serviços, o domínio dos serviços tem de ser definido ao criar uma instância de um ponto final de URL API. Por exemplo, o seguinte código cria uma instância da SearchURL classe e aponta o domínio para a nuvem do Governo Azure.

var searchURL = new atlas.service.SearchURL(pipeline, 'atlas.azure.us');

Se aceder diretamente aos serviços Azure Maps REST, altere o domínio URL para atlas.azure.us . Por exemplo, se utilizar o serviço de API de pesquisa, altere o domínio URL de https://atlas.microsoft.com/search/ https://atlas.azure.us/search/ .

Estruturas JavaScript

Se desenvolver usando uma estrutura JavaScript, um dos seguintes projetos de código aberto pode ser útil:

Passos seguintes

Saiba como criar e interagir com um mapa:

Saiba como modelar um mapa:

Aprenda as melhores práticas e veja as amostras:

Para obter uma lista de amostras que mostram como integrar o Azure Ative Directory (AAD) com o Azure Maps, consulte: