Usare il controllo mappa di Mappe di Azure

  • Articolo

L'SDK Web di Mappe di Azure offre un controllo mappa che consente la personalizzazione delle mappe interattive con contenuti e immagini personalizzati per la visualizzazione nelle applicazioni Web o per dispositivi mobili. Questo modulo è una libreria helper che semplifica l'uso dei servizi REST Mappe di Azure nelle applicazioni Web o Node.js usando JavaScript o TypeScript.

Questo articolo usa l'SDK Web Mappe di Azure, ma i servizi Mappe di Azure funzionano con qualsiasi controllo mappa. Per un elenco dei plug-in di controllo mappa di terze parti, vedere Mappe di Azure community - Progetti open source.

Nota

ritiro Mappe di Azure Web SDK Map Control v1

La versione 1 di Web SDK Map Control è ora deprecata e verrà ritirata il 26/09/09/9. Per evitare interruzioni del servizio, eseguire la migrazione alla versione 3 del controllo mappa dell'SDK Web entro il 19/09/26. La versione 3 è compatibile con le versioni precedenti e offre diversi vantaggi, tra cui compatibilità WebGL 2, prestazioni e supporto maggiori per i riquadri del terreno 3D. Per altre informazioni, vedere La guida alla migrazione Mappe di Azure Web SDK v1.

Prerequisiti

Per usare il controllo mappa in una pagina Web, è necessario disporre di uno dei prerequisiti seguenti:

Creare una nuova mappa in una pagina Web

È possibile incorporare una mappa in una pagina Web usando la libreria JavaScript lato client Map Control.

  1. Creare un nuovo file HTML.

  2. Caricare Azure Maps Web SDK. È possibile scegliere una delle due opzioni:

    • Usare la versione rete CDN ospitata a livello globale di Mappe di Azure Web SDK aggiungendo riferimenti a JavaScript e stylesheet nell'elemento <head> del file HTML:

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

    • Caricare il codice sorgente Mappe di Azure Web SDK in locale usando il pacchetto npm azure-maps-control e ospitarlo con l'app. Questo pacchetto include anche le definizioni TypeScript.

      npm install azure-maps-control

    Aggiungere quindi riferimenti al Mappe di Azure stylesheet all'elemento <head> del file:

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

    Nota

    Le definizioni TypeScript possono essere importate nell'applicazione aggiungendo il codice seguente:

    import * as atlas from 'azure-maps-control';

  3. Per eseguire il rendering della mappa in modo che riempia l'intero corpo della pagina, aggiungere l'elemento <style> seguente all'elemento <head>.

     <style>
     html, body {
         margin: 0;
     }

     #myMap {
         height: 100vh;
         width: 100vw;
     }
 </style>

  4. Nel corpo della pagina aggiungere un elemento <div> e assegnargli un idmyMap.

     <body onload="InitMap()">
     <div id="myMap"></div>
 </body>

  5. Inizializzare quindi il controllo mappa. Per autenticare il controllo, usare una chiave di sottoscrizione Mappe di Azure o le credenziali di Microsoft Entra con le opzioni di autenticazione.

    Se si usa una chiave di sottoscrizione per l'autenticazione, copiare e incollare l'elemento script seguente all'interno dell'elemento <head> e sotto il primo <script> elemento. Sostituire <Your Azure Maps Key> con la chiave di sottoscrizione Mappe di Azure.

    <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 si usa Microsoft Entra ID per l'autenticazione, copiare e incollare l'elemento script seguente all'interno dell'elemento <head> e sotto il primo <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 Microsoft Entra Client Id>',
              aadAppId: '<Your Microsoft Entra App Id>',
              aadTenant: '<Your Microsoft Entra tenant Id>'
          }
      });
  }
</script>

    Per altre informazioni sull'autenticazione con Mappe di Azure, vedere il documento Autenticazione con Mappe di Azure. Per un elenco di esempi che illustrano come integrare Azure AD con Mappe di Azure, vedere esempi di Mappe di Azure e Azure Active Directory in GitHub.

    Suggerimento

    In questo esempio è stato passato nell'oggetto id della mappa <div>. Un altro modo per eseguire questa operazione consiste nel passare l'oggetto HTMLElement passandodocument.getElementById('myMap') come primo parametro.

  6. Facoltativamente, può risultare utile aggiungere gli elementi seguenti meta all'elemento head della pagina:

     <!-- 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. Il file HTML dovrebbe ora essere simile al frammento di codice seguente:

     <!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/3/atlas.min.css" type="text/css">
     <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/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. Aprire il file nel Web browser e visualizzare la mappa di cui è stato eseguito il rendering. Dovrebbe essere simile all'immagine seguente:

    Screenshot of a map image showing rendered result.

Localizzare la mappa

Mappe di Azure offre due modi diversi per impostare la lingua e la visualizzazione a livello di area per la mappa sottoposta a rendering. La prima opzione consiste nell'aggiungere queste informazioni allo spazio dei nomi globale atlas , che comporta tutte le istanze del controllo mappa nell'app per impostazione predefinita a queste impostazioni. Il codice seguente imposta la lingua su Francese ("fr-FR") e la visualizzazione a livello di area su "Automatica":

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

La seconda opzione consiste nel passare queste informazioni nelle opzioni della mappa durante il caricamento della mappa come segue:

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

È possibile caricare più istanze della mappa nella stessa pagina con impostazioni diverse di lingua e area geografica. Inoltre, queste impostazioni possono essere aggiornate dopo il caricamento della mappa usando la setStyle funzione della mappa.

Ecco un esempio di Mappe di Azure con la lingua impostata su "fr-FR" e la visualizzazione a livello di area impostata su Auto.

Screenshot showing a map image with its labels in French.

Per un elenco delle lingue supportate e delle visualizzazioni internazionali, vedere Supporto per la localizzazione in Mappe di Azure.

Compatibilità webGL 2

A partire da Mappe di Azure Web SDK 3.0, Web SDK include la compatibilità completa con WebGL 2, una potente tecnologia grafica che consente il rendering accelerato hardware nei Web browser moderni. Usando WebGL 2, gli sviluppatori possono sfruttare le funzionalità delle GPU moderne per eseguire il rendering di mappe e visualizzazioni complesse in modo più efficiente, con conseguente miglioramento delle prestazioni e della qualità visiva.

Map image showing WebGL 2 Compatibility.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, user-scalable=no" />
        <title>WebGL2 - Azure Maps Web SDK Samples</title>
        <link href=https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css rel="stylesheet"/>
        <script src=https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js></script>
        <script src="https://unpkg.com/deck.gl@latest/dist.min.js"></script>
        <style>
            html,
            body {
                width: 100%;
                height: 100%;
                padding: 0;
                margin: 0;
            }
            #map {
                width: 100%;
                height: 100%;
            }
        </style>
    </head>
    <body>
        <div id="map"></div>
        <script>
            var map = new atlas.Map("map", {
                center: [-122.44, 37.75],
                bearing: 36,
                pitch: 45,
                zoom: 12,
                style: "grayscale_light",
                // Get an Azure Maps key at https://azuremaps.com/.
                authOptions: {
                    authType: "subscriptionKey",
                    subscriptionKey: " <Your Azure Maps Key> "
                }
            });

            // Wait until the map resources are ready.
            map.events.add("ready", (event) => {
                // Create a custom layer to render data points using deck.gl
                map.layers.add(
                    new DeckGLLayer({
                        id: "grid-layer",
                        data: "https://raw.githubusercontent.com/visgl/deck.gl-data/master/website/sf-bike-parking.json",
                        cellSize: 200,
                        extruded: true,
                        elevationScale: 4,
                        getPosition: (d) => d.COORDINATES,
                        // GPUGridLayer leverages WebGL2 to perform aggregation on the GPU.
                        // For more details, see https://deck.gl/docs/api-reference/aggregation-layers/gpu-grid-layer
                        type: deck.GPUGridLayer
                    })
                );
            });

            // A custom implementation of WebGLLayer
            class DeckGLLayer extends atlas.layer.WebGLLayer {
                constructor(options) {
                    super(options.id);
                    // Create an instance of deck.gl MapboxLayer which is compatible with Azure Maps
                    // https://deck.gl/docs/api-reference/mapbox/mapbox-layer
                    this._mbLayer = new deck.MapboxLayer(options);

                    // Create a renderer
                    const renderer = {
                        renderingMode: "3d",
                        onAdd: (map, gl) => {
                            this._mbLayer.onAdd?.(map["map"], gl);
                        },
                        onRemove: (map, gl) => {
                            this._mbLayer.onRemove?.(map["map"], gl);
                        },
                        prerender: (gl, matrix) => {
                            this._mbLayer.prerender?.(gl, matrix);
                        },
                        render: (gl, matrix) => {
                            this._mbLayer.render(gl, matrix);
                        }
                    };
                    this.setOptions({ renderer });
                }
            }
        </script>
    </body>    
</html>

Riquadri del terreno 3D

A partire da Mappe di Azure Web SDK 3.0, gli sviluppatori possono sfruttare le visualizzazioni del terreno 3D. Questa funzionalità consente di incorporare i dati di elevazione dei privilegi nelle mappe, creando un'esperienza più immersiva per gli utenti. Che si tratti di visualizzare intervalli di montagna, valli o altre caratteristiche geografiche, il supporto del terreno 3D offre un nuovo livello di realismo alle applicazioni di mapping.

L'esempio di codice seguente illustra come implementare riquadri del terreno 3D.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, user-scalable=no" />
        <title>Elevation - Azure Maps Web SDK Samples</title>
        <link href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css rel="stylesheet" />
        <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js></script>
        <style>
            html,
            body {
                width: 100%;
                height: 100%;
                padding: 0;
                margin: 0;
            }
            #map {
                width: 100%;
                height: 100%;
            }
        </style>
    </head>

    <body>
        <div id="map"></div>
        <script>
            var map = new atlas.Map("map", {
                center: [-121.7269, 46.8799],
                maxPitch: 85,
                pitch: 60,
                zoom: 12,
                style: "road_shaded_relief",
                // Get an Azure Maps key at https://azuremaps.com/.
                authOptions: {
                    authType: "subscriptionKey",
                    subscriptionKey: "<Your Azure Maps Key>"
                }
            });

            // Create a tile source for elevation data. For more information on creating
            // elevation data & services using open data, see https://aka.ms/elevation
            var elevationSource = new atlas.source.ElevationTileSource("elevation", {
                url: "<tileSourceUrl>"
            });

            // Wait until the map resources are ready.
            map.events.add("ready", (event) => {

                // Add the elevation source to the map.
                map.sources.add(elevationSource);

                // Enable elevation on the map.
                map.enableElevation(elevationSource);
            });
        </script>
    </body>
</html>

supporto cloud Azure per enti pubblici

Mappe di Azure Web SDK supporta il cloud Azure per enti pubblici. Tutti gli URL JavaScript e CSS usati per accedere all'SDK Web di Mappe di Azure rimangono invariati. Le attività seguenti devono essere eseguite per connettersi alla versione cloud Azure per enti pubblici della piattaforma Mappe di Azure.

Quando si usa il controllo mappa interattivo, aggiungere la riga di codice seguente prima di creare un'istanza della Map classe .

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

Assicurarsi di usare Mappe di Azure dettagli di autenticazione dalla piattaforma cloud Azure per enti pubblici durante l'autenticazione della mappa e dei servizi.

Framework JavaScript

Se si sviluppa con un framework JavaScript, può risultare utile uno dei progetti open source seguenti:

Passaggi successivi

Informazioni su come creare e interagire con una mappa:

Creare una mappa

Informazioni su come applicare uno stile a una mappa:

Scegliere uno stile mappa

Informazioni sulle procedure consigliate e vedere esempi:

Procedure consigliate

Esempi di codice

Per un elenco di esempi che illustrano come integrare Microsoft Entra ID con Mappe di Azure, vedere:

Esempi di autenticazione di Microsoft Entra