Použití mapového ovládacího prvku Azure Maps

  • Článek

Sada Azure Mapy Web SDK poskytuje ovládací prvek mapy, který umožňuje přizpůsobení interaktivních map s vlastním obsahem a obrázky pro zobrazení ve webových nebo mobilních aplikacích. Tento modul je pomocná knihovna, která usnadňuje používání služeb Azure Mapy REST ve webových aplikacích nebo aplikací Node.js pomocí JavaScriptu nebo TypeScriptu.

Tento článek používá sadu Azure Mapy Web SDK, ale služby Azure Mapy pracují s libovolným ovládacím prvku mapování. Seznam modulů plug-in pro ovládací prvky mapování třetích stran najdete v komunitě Azure Mapy – opensourcové projekty.

Poznámka:

Vyřazení nástroje Map Control v1 sady Azure Mapy Web SDK

Verze 1 ovládacího prvku mapování webové sady SDK je nyní zastaralá a bude vyřazena 26. 9. 9. 26. Pokud se chcete vyhnout přerušení služeb, proveďte migraci na verzi 3 mapového ovládacího prvku webové sady SDK do 26. 9. 9. 26. Verze 3 je zpětně kompatibilní a má několik výhod, včetně kompatibility WebGL 2, zvýšeného výkonu a podpory pro 3D terénní dlaždice. Další informace najdete v průvodci migrací sady Azure Mapy Web SDK v1.

Požadavky

Pokud chcete použít ovládací prvek Mapování na webové stránce, musíte mít jednu z následujících požadavků:

  • Účet Azure Mapy
  • Klíč předplatného nebo přihlašovací údaje Microsoft Entra. Další informace najdete v tématu Možnosti ověřování.

Vytvoření nové mapy na webové stránce

Mapu můžete vložit na webovou stránku pomocí javascriptové knihovny mapového ovládacího prvku na straně klienta.

  1. Vytvořte nový soubor HTML.

  2. Načtěte do sady Azure Mapy Web SDK. Můžete zvolit jednu ze dvou možností:

    • Pomocí globálně hostované verze CDN sady Azure Mapy Web SDK přidejte odkazy na JavaScript a stylesheet v <head> elementu souboru 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>

    • Zdrojový kód webové sady SDK azure Mapy načtěte místně pomocí balíčku npm azure-maps-control a hostujte ho s vaší aplikací. Tento balíček obsahuje také definice TypeScriptu.

      npm install azure-maps-control

    Pak do elementu souboru přidejte odkazy na Azure Mapy stylesheet<head>:

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

    Poznámka:

    Definice TypeScriptu můžete do aplikace importovat přidáním následujícího kódu:

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

  3. Pokud chcete mapu vykreslit tak, aby vyplnila celý text stránky, přidejte do elementu <head> následující <style> prvek.

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

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

  4. Do textu stránky přidejte <div> prvek a dejte mu id objekt myMap.

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

  5. Dále inicializujete ovládací prvek mapy. K ověření ovládacího prvku použijte klíč předplatného Azure Mapy nebo přihlašovací údaje Microsoft Entra s možnostmi ověřování.

    Pokud pro ověřování používáte klíč předplatného, zkopírujte a vložte následující element skriptu do elementu <head> a pod první <script> prvek. Nahraďte <Your Azure Maps Key> klíčem předplatného Azure Mapy.

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

    Pokud pro ověřování používáte MICROSOFT Entra ID, zkopírujte a vložte následující element skriptu do elementu <head> a pod první <script> prvek.

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

    Další informace o ověřování pomocí Azure Mapy najdete v dokumentu Ověřování v Azure Mapy. Seznam ukázek znázorňující integraci Azure AD s Azure Mapy najdete v tématu Ukázky Azure Mapy a Azure Active Directory na GitHubu.

    Tip

    V tomto příkladu id<div>jsme předali mapu . Dalším způsobem, jak to udělat, je předat HTMLElement objekt předánímdocument.getElementById('myMap') jako první parametr.

  6. Volitelně může být užitečné přidat do prvku stránky následující meta prvky head :

     <!-- 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. Váš soubor HTML by teď měl vypadat přibližně jako následující fragment kódu:

     <!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. Otevřete soubor ve webovém prohlížeči a zobrazte vykreslenou mapu. Měl by vypadat jako na následujícím obrázku:

    Screenshot of a map image showing rendered result.

Lokalizace mapy

Azure Mapy nabízí dva různé způsoby nastavení jazyka a regionálního zobrazení vykreslené mapy. První možností je přidat tyto informace do globálního atlas oboru názvů, což vede ke všem instancím ovládacích prvků mapování ve vaší aplikaci, které mají výchozí nastavení. Následující nastavení jazyka na francouzštinu ("fr-FR") a regionální zobrazení na "Auto":

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

Druhou možností je předat tyto informace do možností mapy při načítání mapy takto:

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

Poznámka:

Na stejné stránce je možné načíst více instancí mapování s různými nastaveními jazyka a oblasti. Kromě toho je možné tato nastavení aktualizovat po načtení mapy pomocí setStyle funkce mapy.

Tady je příklad azure Mapy s jazykem nastaveným na fr-FR a regionálním zobrazením nastaveným na Auto.

Screenshot showing a map image with its labels in French.

Seznam podporovaných jazyků a regionálních zobrazení najdete v tématu Podpora lokalizace v Azure Mapy.

Kompatibilita WebGL 2

Počínaje službou Azure Mapy Web SDK 3.0 zahrnuje webová sada SDK úplnou kompatibilitu s WebGL 2, což je výkonná grafická technologie, která umožňuje hardwarově akcelerované vykreslování v moderních webových prohlížečích. Díky použití WebGL 2 můžou vývojáři využít možnosti moderních grafických procesorů k efektivnějšímu vykreslování složitých map a vizualizací, což vede ke zlepšení výkonu a vizuální kvality.

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 terénní dlaždice

Počínaje službou Azure Mapy Web SDK 3.0 můžou vývojáři využívat 3D vizualizace terénu. Tato funkce umožňuje začlenit data o zvýšení oprávnění do map a vytvořit tak imerzivní prostředí pro uživatele. Ať už se jedná o vizualizaci horských oblastí, údolí nebo jiných geografických vlastností, podpora 3D terénu přináší vaší mapovacím aplikacím novou úroveň realismu.

Následující příklad kódu ukazuje, jak implementovat 3D terén dlaždice.

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

Podpora cloudu Azure Government

Sada Azure Mapy Web SDK podporuje cloud Azure Government. Všechny adresy URL JavaScriptu a CSS používané pro přístup k sadě Azure Mapy Web SDK zůstanou stejné. Abyste se mohli připojit ke cloudové verzi Azure Government platformy Azure Mapy, je potřeba provést následující úlohy.

Při použití interaktivního mapového ovládacího prvku před vytvořením instance Map třídy přidejte následující řádek kódu.

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

Při ověřování map a služeb nezapomeňte použít podrobnosti ověřování Azure Mapy z cloudové platformy Azure Government.

JavaScriptové architektury

Pokud vyvíjíte pomocí javascriptové architektury, může být užitečný jeden z následujících opensourcových projektů:

Další kroky

Zjistěte, jak vytvořit mapu a pracovat s ní:

Vytvoření mapy

Naučte se stylovat mapu:

Volba stylu mapy

Seznamte se s osvědčenými postupy a projděte si ukázky:

Osvědčené postupy

Ukázky kódu

Seznam ukázek ukazujících, jak integrovat ID Microsoft Entra s Azure Mapy, najdete tady:

Ukázky ověřování Microsoft Entra