Использование элемента управления картой в Azure MapsUse the Azure Maps map control

Библиотека JavaScript на стороне клиента Map Control позволяет отображать карты и встроенные функции Azure Maps в веб-приложение или мобильном приложении.The Map Control client-side JavaScript library allows you to render maps and embedded Azure Maps functionality into your web or mobile application.

Обязательные условияPrerequisites

Для использования Map Control на веб-странице необходимо выполнить одно из следующих условий.To use the Map Control in a web page, you must have one of the following prerequisites:

Создание карты на веб-страницеCreate a new map in a web page

Карту можно внедрить на веб-страницу с помощью Map Control библиотеки JavaScript на стороне клиента.You can embed a map in a web page by using the Map Control client-side JavaScript library.

  1. Создайте HTML-файл.Create a new HTML file.

  2. Загрузите в веб-пакет SDK Azure Maps.Load in the Azure Maps Web SDK. Вы можете выбрать один из вариантов:You can choose one of two options:

    • Используйте глобально размещенную версию CDN Azure Maps веб-пакета SDK, добавив ссылки на JavaScript и таблицу стилей в <head> ЭЛЕМЕНТЕ HTML-файла:Use the globally hosted CDN version of the Azure Maps Web SDK by adding references to the JavaScript and stylesheet in the <head> element of the HTML file:

      <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>
      
    • Загрузите исходный код веб-пакета SDK Azure Maps локально с помощью пакета Azure-Maps-Control NPM и разместите его в своем приложении.Load the Azure Maps Web SDK source code locally using the azure-maps-control NPM package and host it with your app. Этот пакет также включает определения TypeScript.This package also includes TypeScript definitions.

      npm install azure-maps-controlnpm install azure-maps-control

    Затем добавьте ссылки на таблицу стилей Azure Maps в <head> элемент файла:Then add references to the Azure Maps stylesheet to the <head> element of the file:

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

    Примечание

    Определения typescript можно импортировать в приложение, добавив следующий код:Typescript definitions can be imported into your application by adding the following code:

    import * as atlas from 'azure-maps-control';
    
  3. Чтобы отобразить карту так, чтобы она занимала основную область страницы, добавьте следующий элемент <style> к элементу <head>.To render the map so that it fills the full body of the page, add the following <style> element to the <head> element.

     <style>
         html, body {
             margin: 0;
         }
    
         #myMap {
             height: 100vh;
             width: 100vw;
         }
     </style>
    
  4. В основной области страницы добавьте элемент <div> и присвойте ему idmyMap.In the body of the page, add a <div> element and give it an id of myMap.

     <body onload="InitMap()">
         <div id="myMap"></div>
     </body>
    
  5. Теперь мы инициализируем элемент управления картой.Now, we'll initialize the map control. Чтобы проверить подлинность элемента управления, необходимо либо владеть Azure Maps ключом подписки, либо использовать учетные данные Azure Active Directory (AAD) с параметрами проверки подлинности.In order to authenticate the control, you'll either need to own an Azure Maps subscription key or use Azure Active Directory (AAD) credentials with authentication options.

    Если вы используете ключ подписки для проверки подлинности, скопируйте и вставьте следующий элемент script в <head> элемент и ниже первого <script> элемента.If you're using a subscription key for authentication, copy and paste the following script element inside the <head> element, and below the first <script> element. Замените на <Your Azure Maps Key> ключ первичной подписки Azure Maps.Replace <Your Azure Maps Key> with your Azure Maps primary subscription key.

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

    Если для проверки подлинности используется Azure Active Directory (AAD), скопируйте и вставьте следующий элемент script в <head> элемент и ниже первого <script> элемента.If you're using Azure Active Directory (AAD) for authentication, copy and paste the following script element inside the <head> element, and below the first <script> element.

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

    Дополнительные сведения о проверке подлинности с помощью Azure Maps см. в статье Проверка подлинности с помощью Azure Maps документа.For more information about authentication with Azure Maps, see the Authentication with Azure Maps document. Кроме того, список примеров, демонстрирующих интеграцию Azure Active Directory (AAD) с Azure Maps, можно найти здесь.Also, a list of samples showing how to integrate Azure Active Directory (AAD) with Azure Maps can be found here.

    Совет

    В этом примере мы передали id карту <div> .In this example, we've passed in the id of the map <div>. Другой способ сделать это — передать HTMLElement объект, передав в document.getElementById('myMap') качестве первого параметра.Another way to do this is to pass in the HTMLElement object by passingdocument.getElementById('myMap') as the first parameter.

  6. Кроме того, может оказаться полезным добавить следующие meta элементы в head элемент страницы:Optionally, you may find it helpful to add the following meta elements to the head element of the page:

     <!-- 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. Если поместить все вместе, ваш HTML-файл должен выглядеть примерно так, как в следующей разметке:Putting it all together, your HTML file should look something like the following markup:

     <!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. Откройте файл в веб-браузере и вы увидите готовую для просмотра карту.Open the file in your web browser and view the rendered map. Оно должно выглядеть, как показано ниже:It should look like the image below:

    Изображение схемы, показывающее результат визуализации

Локализация картыLocalizing the map

Azure Maps предоставляет два разных способа настройки языкового и регионального представления для отображаемой схемы.Azure Maps provides two different ways of setting the language and regional view for the rendered map. Первый вариант — Добавить эту информацию в глобальное atlas пространство имен, что приведет к тому, что все экземпляры элементов управления картой в приложении будут по умолчанию иметь эти параметры.The first option is to add this information to the global atlas namespace, which will result in all map control instances in your app defaulting to these settings. Следующий пример устанавливает для языка значение французский (fr-FR) и региональное представление "Auto":The following sets the language to French ("fr-FR") and the regional view to "Auto":

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

Второй вариант заключается в передаче этой информации в параметры Map при загрузке карты следующим образом:The second option is to pass this information into the map options when loading the map like this:

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

Примечание

Можно загрузить несколько экземпляров карт на одной странице с разными языками и региональными параметрами.It is possible to load multiple map instances on the same page with different language and region settings. Кроме того, эти параметры можно обновить после загрузки сопоставлений с помощью setStyle функции Map.Additionally, these settings can be updated after the map loads using the setStyle function of the map.

Ниже приведен пример Azure Maps с языком, для которого задано значение "fr-FR", а для регионального представления задано значение "Авто".Here is an example of Azure Maps with the language set to "fr-FR" and the regional view set to "Auto".

Изображение схемы, показывающее метки на французском языке

Полный список поддерживаемых языков и региональных представлений приведен здесь.A complete list of supported languages and regional views is documented here.

Облачная поддержка Azure для государственных организацийAzure Government cloud support

Azure Maps веб-пакет SDK поддерживает облако Azure для государственных организаций.The Azure Maps Web SDK supports the Azure Government cloud. Все URL-адреса JavaScript и CSS, используемые для доступа к Azure Maps Web SDK, остаются неизменными.All JavaScript and CSS URLs used to access the Azure Maps Web SDK remain the same. Для подключения к облачной версии Azure Maps платформы Azure для государственных организаций необходимо выполнить следующие задачи.The following tasks will need to be done to connect to the Azure Government cloud version of the Azure Maps platform.

При использовании интерактивного элемента управления картой добавьте следующую строку кода перед созданием экземпляра Map класса.When using the interactive map control, add the following line of code before creating an instance of the Map class.

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

При проверке подлинности карт и служб обязательно используйте сведения о проверке подлинности Azure Maps на облачной платформе Azure для государственных организаций.Be sure to use Azure Maps authentication details from the Azure Government cloud platform when authenticating the map and services.

При использовании модуля служб необходимо задать домен для служб при создании экземпляра конечной точки URL-адреса API.When using the services module, the domain for the services needs to be set when creating an instance of an API URL endpoint. Например, следующий код создает экземпляр SearchURL класса и указывает домен в облаке Azure для государственных организаций.For example, the following code creates an instance of the SearchURL class and points the domain to the Azure Government cloud.

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

При непосредственном доступе к службам Azure Maps RESTFUL измените домен URL-адреса на atlas.azure.us .If directly accessing the Azure Maps REST services, change the URL domain to atlas.azure.us. Например, при использовании службы API поиска измените домен URL-адреса с https://atlas.microsoft.com/search/ на https://atlas.azure.us/search/ .For example, if using the search API service, change the URL domain from https://atlas.microsoft.com/search/ to https://atlas.azure.us/search/.

Платформы JavaScriptJavaScript frameworks

Для разработки с использованием платформы JavaScript может оказаться полезным один из следующих проектов с открытым исходным кодом:If developing using a JavaScript framework, one of the following open-source projects may be useful:

Дальнейшие действияNext steps

Узнайте, как создавать и взаимодействовать с картой:Learn how to create and interact with a map:

Узнайте, как изменить стиль карты:Learn how to style a map:

Чтобы добавить дополнительные данные на карту, выполните следующие действия.To add more data to your map:

Список примеров, демонстрирующих интеграцию Azure Active Directory (AAD) с Azure Maps, см. в следующих статьях:For a list of samples showing how to integrate Azure Active Directory (AAD) with Azure Maps, see: