Verwenden des Azure Maps-Kartensteuerelements

  • Artikel

Das Azure Maps Web SDK bietet ein Kartensteuerelement, das die Anpassung interaktiver Karten mit Ihren eigenen Inhalten und Bildern zur Anzeige in Ihren Web- oder Mobile-Anwendungen ermöglicht. Dieses Modul ist eine Hilfsbibliothek, die die Verwendung der REST-Dienste von Azure Maps in Web- oder Node.js-Anwendungen vereinfacht, indem JavaScript oder TypeScript verwendet wird.

In diesem Artikel wird das Azure Maps Web SDK verwendet, aber die Azure Maps-Dienste funktionieren mit jedem Kartensteuerelement. Eine Liste der Kartensteuerelement-Plug-Ins eines Drittanbieters finden Sie unter Azure Maps Community – Open-Source-Projekte.

Hinweis

Azure Maps Web SDK Map Control v1 eingestellt

Version 1 des Web SDK Map Control ist jetzt veraltet und wird am 19.09.26 eingestellt. Um Dienstunterbrechungen zu vermeiden, migrieren Sie bis zum 19.09.26 zur Version 3 des Web SDK Map Control. Version 3 ist abwärtskompatibel und bietet mehrere Vorteile, einschließlich WebGL 2-Kompatibilität, erhöhter Leistung und Unterstützung für 3D-Geländekacheln. Weitere Informationen finden Sie im Migrationshandbuch zum Azure Maps Web SDK v1.

Voraussetzungen

Zur Verwendung des Kartensteuerelements auf einer Webseite müssen Sie eine der folgenden Voraussetzungen erfüllen:

Erstellen einer neuen Karte auf einer Webseite

Sie können eine Karte in eine Webseite einbetten, indem Sie die clientseitige JavaScript-Bibliothek des Kartensteuerelements verwenden.

  1. Erstellen Sie eine neue HTML-Datei.

  2. Laden Sie das Azure Maps Web SDK. Sie können eine dieser beiden Optionen wählen:

    • Verwenden Sie die global gehostete CDN-Version des Azure Maps Web SDK, indem Sie Verweise auf JavaScript und stylesheet dem Element <head> der HTML-Datei hinzufügen:

      <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>

    • Laden Sie den Quellcode des Azure Maps Web-SDK lokal mithilfe des npm-Pakets azure-maps-control, und hosten Sie ihn mit Ihrer App. Dieses Paket enthält außerdem TypeScript-Definitionen.

      npm install azure-maps-control

    Fügen Sie dem <head>-Element der Datei Verweise auf das Azure Maps-stylesheet hinzu:

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

    Hinweis

    Sie können TypeScript-Definitionen in Ihre Anwendung importieren, indem Sie den folgenden Code hinzufügen:

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

  3. Um die Karte so zu rendern, dass sie den gesamten Bereich der Seite ausfüllt, fügen Sie dem <head>-Element das folgende <style>-Element hinzu.

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

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

  4. Fügen Sie im Seitenbereich ein <div>-Element hinzu, und geben Sie ihm die idmyMap.

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

  5. Dann initialisieren Sie das Kartensteuerelement. Zur Authentifizierung des Steuerelements verwenden Sie einen Azure Maps-Abonnementschlüssel oder Microsoft Entra-Anmeldeinformationen (AAD) mit Authentifizierungsoptionen.

    Wenn Sie einen Abonnementschlüssel für die Authentifizierung nutzen, kopieren Sie das folgende Skriptelement und fügen Sie es innerhalb des <head>-Elements und unterhalb des ersten <script>-Elements ein. Ersetzen Sie <Your Azure Maps Key> mit Ihrem Azure Maps-Abonnementschlüssel.

    <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>

    Wenn Sie eine Microsoft Entra ID für die Authentifizierung nutzen, kopieren Sie das folgende Skriptelement und fügen Sie es innerhalb des <head>-Elements und unterhalb des ersten <script>-Elements ein.

    <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>

    Weitere Informationen zur Authentifizierung mit Azure Maps finden Sie im Dokument Authentifizierung mit Azure Maps. Eine Liste der Beispiele zur Integration von Azure AD in Azure Karten finden Sie unter Azure Karten & Azure Active Directory-Beispiele in GitHub.

    Tipp

    In diesem Beispiel wurde der Wert id der Karte <div> übergeben. Eine andere Möglichkeit, dies zu tun, ist es, das HTMLElement-Objekt zu übergeben, indem document.getElementById('myMap') als erster Parameter übergeben wird.

  6. Optional können Sie dem head-Element auf dieser Seite auch die folgenden meta-Elemente hinzufügen:

     <!-- 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. Ihre HTML-Datei sieht nun in etwa wie der folgende Codeausschnitt aus:

     <!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. Öffnen Sie die Datei in Ihrem Webbrowser, und zeigen Sie die gerenderte Karte an. Das Ergebnis sollte folgendermaßen aussehen:

    Screenshot of a map image showing rendered result.

Lokalisieren der Karte

Azure Maps bietet zwei verschiedene Möglichkeiten zum Festlegen der Sprache und der regionalen Ansicht für die gerenderte Karte. Die erste Option besteht darin, diese Informationen dem globalen atlas-Namespace hinzuzufügen, was dazu führt, dass alle Instanzen der Kartensteuerelemente in Ihrer App diese Einstellungen als Standard verwenden. Im Folgenden wird die Sprache auf Französisch („fr-FR“) und die regionale Ansicht auf „Auto“ festgelegt:

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

Die zweite Option besteht darin, diese Informationen beim Laden der Karte folgendermaßen an die Kartenoptionen zu übergeben:

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>'
    }
});

Hinweis

Es ist möglich, auf der gleichen Seite mehrere Karteninstanzen mit unterschiedlichen Sprach- und Regionseinstellungen zu laden. Darüber hinaus können diese Einstellungen mithilfe der Kartenfunktion setStyle aktualisiert werden, nachdem die Karte geladen wurde.

Dies ist ein Beispiel für Azure Maps, bei dem die Sprache auf „fr-FR“ und die regionale Ansicht auf Auto festgelegt wurden.

Screenshot showing a map image with its labels in French.

Eine Liste der unterstützten Sprachen und regionalen Ansichten finden Sie unter Unterstützte Sprachen in Azure Maps.

WebGL 2-Kompatibilität

Ab Azure Maps Web SDK 3.0 bietet das Web SDK vollständige Kompatibilität mit WebGL 2, einer leistungsstarken Grafiktechnologie, die das hardwarebeschleunigte Rendern in modernen Webbrowsern ermöglicht. Mithilfe von WebGL 2 können Entwickler*innen die Funktionen moderner GPUs nutzen, um komplexe Karten und Visualisierungen effizienter zu rendern und so die Leistung und visuelle Qualität zu verbessern.

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>

3D-Geländekacheln

Ab Azure Maps Web SDK 3.0 können Entwickler*innen 3D-Geländevisualisierungen nutzen. Mit diesem Feature können Sie Höhendaten in Ihre Karten integrieren und so eine noch ansprechendere Erfahrung für Ihre Benutzer*innen schaffen. Unabhängig davon, ob es sich um die Visualisierung von Bergketten, Tälern oder anderen geografischen Merkmalen handelt, die 3D-Geländeunterstützung sorgt bei Ihren Kartenanwendungen für ein neues Maß an Realismus.

Im folgenden Codebeispiel wird die Implementierung von 3D-Geländekacheln veranschaulicht.

<!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>

Unterstützung für die Azure Government-Cloud

Das Azure Maps Web SDK unterstützt die Azure Government-Cloud. Alle JavaScript- und CSS-URLs, die für den Zugriff auf das Azure Maps Web SDK verwendet werden, bleiben unverändert. Die folgenden Aufgaben müssen ausgeführt werden, um eine Verbindung mit der Azure Government-Cloudversion der Azure Maps-Plattform herzustellen.

Wenn Sie das interaktive Kartensteuerelement verwenden, fügen Sie die folgende Codezeile hinzu, bevor Sie eine Instanz der Map-Klasse erstellen.

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

Verwenden Sie beim Authentifizieren der Karte und Dienste unbedingt die Azure Maps-Authentifizierungsinformationen der Azure Government-Cloudplattform.

JavaScript-Frameworks

Bei Entwicklungen mit einem JavaScript-Framework kann eins der folgenden Open-Source-Projekte nützlich sein:

Nächste Schritte

Erfahren Sie, wie Sie Karten erstellen und mit ihnen interagieren:

Erstellen einer Karte

Erfahren Sie, wie Sie den Stil einer Karte auswählen:

Auswählen eines Kartenstils

Informieren Sie sich über bewährte Methoden, und sehen Sie sich die folgenden Beispiele an:

bewährten Methoden

Codebeispiele

Eine Liste mit Beispielen zur Integration von Microsoft Entra ID in Azure Maps finden Sie hier:

Microsoft Entra-Authentifizierungsbeispiele