Udostępnij za pośrednictwem

Jak używać kontrolki mapy usługi Azure Maps

Zestaw Web SDK usługi Azure Maps udostępnia kontrolkę Map Control, która umożliwia dostosowywanie interaktywnych map z własnymi treściami i obrazami do wyświetlania w aplikacjach sieciowych lub mobilnych. Ten moduł jest biblioteką pomocniczą, która ułatwia korzystanie z usług REST Azure Maps w aplikacjach webowych lub Node.js przy użyciu języka JavaScript lub TypeScript.

Uwaga

Wycofanie wersji 1 kontrolki mapy w ramach Web SDK usługi Azure Maps

Wersja 1 kontrolki mapowej Web SDK jest teraz przestarzała i zostanie wycofana w dniu 19.09.2026. Aby uniknąć przerw w działaniu usługi, przeprowadź migrację do wersji 3 Web SDK do kontroli mapy do 19 września 2026. Wersja 3 jest zgodna z poprzednimi wersjami i ma kilka korzyści, w tym zgodność z biblioteką WebGL 2, zwiększoną wydajność i obsługę kafelków terenu 3D. Aby uzyskać więcej informacji, zobacz Przewodnik migracji zestawu Web SDK usługi Azure Maps w wersji 1.

Wymagania wstępne

Aby użyć kontrolki mapy na stronie internetowej, musisz mieć jedną z następujących wymagań wstępnych:

Tworzenie nowej mapy na stronie internetowej

Można osadzić mapę na stronie internetowej, używając biblioteki JavaScript Map Control po stronie klienta.

  1. Utwórz nowy plik HTML.

  2. Załaduj zestaw Sdk sieci Web usługi Azure Maps. Możesz wybrać jedną z dwóch opcji:

    • Użyj globalnie hostowanej wersji zestawu SDK sieci Web usługi Azure Maps, dodając odwołania do języka JavaScript i stylesheet w <head> elemencie pliku 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>

    • Załaduj kod źródłowy zestawu Web SDK usługi Azure Maps lokalnie przy użyciu pakietu npm azure-maps-control i hostuj go z aplikacją. Ten pakiet zawiera również definicje języka TypeScript.

      Npm install azure-maps-control

    Następnie dodaj odwołania do usługi Azure Maps stylesheet do <head> elementu pliku:

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

    Uwaga

    Definicje języka TypeScript można zaimportować do aplikacji, dodając następujący kod:

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

  3. Aby renderować mapę tak, aby wypełniała pełną treść strony, dodaj następujący <style> element do <head> elementu .

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

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

  4. W treści strony dodaj element <div> i nadaj mu idmyMap.

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

  5. Następnie zainicjuj kontrolkę mapy. Aby uwierzytelnić kontrolkę, użyj klucza subskrypcji Azure Maps lub poświadczeń Microsoft Entra z opcjami uwierzytelniania.

    Jeśli używasz klucza subskrypcji do uwierzytelniania, skopiuj i wklej następujący element skryptu <head> wewnątrz elementu i poniżej pierwszego <script> elementu. Zastąp <Your Azure Maps Key> ciąg kluczem subskrypcji usługi 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>

    Jeśli używasz identyfikatora Entra firmy Microsoft do uwierzytelniania, skopiuj i wklej następujący element skryptu <head> wewnątrz elementu i poniżej pierwszego <script> elementu.

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

    Aby uzyskać więcej informacji na temat uwierzytelniania za pomocą usługi Azure Maps, zobacz dokument Authentication with Azure Maps (Uwierzytelnianie za pomocą usługi Azure Maps ). Aby uzyskać listę przykładów pokazujących, jak zintegrować usługę Azure AD z usługą Azure Maps, zobacz Azure Maps i Azure Active Directory Samples in GitHub (Przykłady usługi Azure Maps i Azure Active Directory w usłudze GitHub).

    Napiwek

    W tym przykładzie przekazaliśmy id z mapy <div>. Innym sposobem wykonania tej czynności jest przekazanie obiektu HTMLElement poprzez przekazanie document.getElementById('myMap') jako pierwszego parametru.

  6. Opcjonalnie warto dodać następujące meta elementy do head elementu strony:

     <!-- Ensures that Internet Explorer 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. Plik HTML powinien teraz wyglądać podobnie do następującego fragmentu kodu:

     <!DOCTYPE html>
 <html>
 <head>
     <title></title>

     <meta charset="utf-8">

     <!-- Ensures that Internet Explorer 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. Otwórz plik w przeglądarce internetowej i wyświetl renderowaną mapę. Powinien wyglądać podobnie do poniższej ilustracji:

    Zrzut ekranu przedstawiający obraz mapy przedstawiający renderowany wynik.

Lokalizowanie mapy

Usługa Azure Maps udostępnia dwa różne sposoby ustawiania języka i widoku regionalnego dla renderowanej mapy. Pierwszą opcją jest dodanie tych informacji do globalnej atlas przestrzeni nazw, co spowoduje, że wszystkie wystąpienia kontrolek mapy w aplikacji będą domyślnie korzystać z tych ustawień. Poniżej ustawiono język francuski ("fr-FR") i ustawienie regionalne na "Auto":

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

Drugą opcją jest przekazanie tych informacji do opcji mapy podczas ładowania mapy w następujący sposób:

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

Uwaga

Istnieje możliwość załadowania wielu wystąpień mapy na tej samej stronie z różnymi ustawieniami języka i regionu. Ponadto te ustawienia można zaktualizować po załadowaniu mapy przy użyciu setStyle funkcji mapy.

Oto przykład usługi Azure Maps z językiem ustawionym na wartość "fr-FR" i widok regionalny ustawiony na wartość Auto.

Zrzut ekranu przedstawiający obraz mapy z etykietami w języku francuskim.

Aby uzyskać listę obsługiwanych języków i widoków regionalnych, zobacz Obsługa lokalizacji w usłudze Azure Maps.

Zgodność z WebGL 2

Począwszy od wersji 3.0 Azure Maps Web SDK, Web SDK obejmuje pełną zgodność z biblioteką WebGL 2, zaawansowaną technologią graficzną, która umożliwia renderowanie przyspieszane sprzętowo w nowoczesnych przeglądarkach internetowych. Korzystając z biblioteki WebGL 2, deweloperzy mogą wykorzystać możliwości nowoczesnych procesorów GPU do wydajniejszego renderowania złożonych map i wizualizacji, co zwiększa wydajność i jakość wizualizacji.

Zrzut ekranu obrazu mapy pokazujący zgodność z WebGL 2. 

<!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@^8/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>

Kafelki terenu 3D

Począwszy od zestawu Web SDK usługi Azure Maps w wersji 3.0, deweloperzy mogą korzystać z wizualizacji terenu 3D. Ta funkcja umożliwia dołączanie danych wysokości do map, tworząc bardziej immersyjne doświadczenie dla użytkowników. Niezależnie od tego, czy chodzi o wizualizację pasm górskich, dolin lub innych cech geograficznych, wsparcie dla terenu 3D wnosi nowy poziom realizmu do aplikacji mapowych.

W poniższym przykładzie kodu pokazano, jak zaimplementować kafelki terenu 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>

Obsługa chmury Azure Government

Internetowy zestaw SDK usługi Azure Maps obsługuje chmurę Azure Government. Wszystkie adresy URL języka JavaScript i CSS używane do uzyskiwania dostępu do zestawu Sdk sieci Web usługi Azure Maps pozostają takie same. Aby połączyć się z wersją chmury azure Government platformy Azure Maps, należy wykonać następujące zadania.

W przypadku korzystania z interaktywnej kontrolki mapy dodaj następujący wiersz kodu przed utworzeniem wystąpienia Map klasy.

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

Pamiętaj, aby podczas uwierzytelniania mapy i usług używać szczegółów uwierzytelniania usługi Azure Maps z platformy w chmurze Azure Government.

Struktury Języka JavaScript

W przypadku programowania przy użyciu platformy JavaScript może być przydatne jedno z następujących projektów typu open source:

Następne kroki

Dowiedz się, jak tworzyć mapę i korzystać z niej:

Tworzenie mapy

Dowiedz się, jak stylować mapę:

Wybieranie stylu mapy

Poznaj najlepsze rozwiązania i zapoznaj się z przykładami:

Najlepsze praktyki

Przykłady kodu

Aby zapoznać się z listą przykładów pokazujących sposób integracji identyfikatora entra firmy Microsoft z usługą Azure Maps, zobacz:

Przykłady uwierzytelniania Microsoft Entra