استخدام عنصر تحكم خرائط Azure

مقالة
10/18/2023

يوفر خرائط Azure Web SDK عنصر تحكم خريطة يتيح تخصيص الخرائط التفاعلية بالمحتوى والصور الخاصة بك للعرض في تطبيقات الويب أو الأجهزة المحمولة. هذه الوحدة النمطية هي مكتبة مساعدة تجعل من السهل استخدام خدمات REST في خرائط Azure في تطبيقات الويب أو Node.js.من خلال استخدام JavaScript أو TypeScript.

تستخدم هذه المقالة خرائط Azure Web SDK، ومع ذلك تعمل خدمات خرائط Azure مع أي عنصر تحكم في الخريطة. للحصول على قائمة بالمكونات الإضافية للتحكم في الخريطة التابعة لجهة خارجية، راجع خرائط Azure المجتمع - المشاريع مفتوحة المصدر.

إشعار

إيقاف خرائط Azure Web SDK Map Control v1

تم الآن إهمال الإصدار 1 من Web SDK Map Control وسيتم إيقافه في 9/19/26. لتجنب انقطاع الخدمة، قم بالترحيل إلى الإصدار 3 من Web SDK Map Control بحلول 9/19/26. الإصدار 3 متوافق مع الإصدارات السابقة وله العديد من الفوائد بما في ذلك توافق WebGL 2، وزيادة الأداء والدعم للوحات التضاريس ثلاثية الأبعاد. لمزيد من المعلومات، راجع دليل ترحيل خرائط Azure Web SDK v1.

المتطلبات الأساسية

لاستخدام عنصر التحكم بالخريطة في صفحة الويب، يجب أن يكون لديك أحد المتطلبات الأساسية التالية:

حساب خرائط Azure
مفتاح اشتراك أو بيانات اعتماد Microsoft Entra. لمزيد من المعلومات، راجع خيارات المصادقة.

إنشاء خريطة جديدة في صفحة الويب

يمكنك تضمين خريطة في صفحة ويب باستخدام مكتبة JavaScript من جانب العميل في عنصر التحكم بالخريطة.

قم بإنشاء ملف HTML جديد.
حمل في Web SDK الخاص بخرائط Azure . يمكنك اختيار أحد خيارين:
- استخدم إصدار CDN المستضاف عالميا من خرائط Azure Web SDK عن طريق إضافة مراجع إلى JavaScript وفي stylesheet<head> عنصر ملف 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>
```
- قم بتحميل التعليمات البرمجية المصدر خرائط Azure Web SDK محليا باستخدام حزمة npm للتحكم في خرائط azure واستضافتها مع تطبيقك. تتضمن هذه الحزمة أيضًا تعريفات TypeScript.
  
  npm تثبيت عنصر تحكم في خرائط Azure
ثم أضف مراجع إلى خرائط Azure stylesheet إلى <head> عنصر الملف:
```
<link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />
```
إشعار

يمكن استيراد تعريفات TypeScript إلى تطبيقك عن طريق إضافة التعليمات البرمجية التالية:
```
import * as atlas from 'azure-maps-control';
```
لعرض الخريطة بحيث تملأ النص الأساسي الكامل للصفحة، أضف العنصر <style> التالي إلى العنصر<head>.
```
 <style>
     html, body {
         margin: 0;
     }

     #myMap {
         height: 100vh;
         width: 100vw;
     }
 </style>
```
في النص الأساسي للصفحة، أضف العنصر <div> وأعطه id من myMap.
```
 <body onload="InitMap()">
     <div id="myMap"></div>
 </body>
```
بعد ذلك، قم بتهيئة عنصر تحكم الخريطة. لمصادقة عنصر التحكم، استخدم مفتاح اشتراك خرائط Azure أو بيانات اعتماد Microsoft Entra مع خيارات المصادقة.

في حالة كنت تستخدم مفتاح اشتراك للمصادقة، فانسخ والصق عنصر البرنامج النصي التالي داخل العنصر<head>، وأسفل العنصر <script> الأول. استبدل <Your Azure Maps Key> بمفتاح اشتراك خرائط 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>
```
إذا كنت تستخدم معرف Microsoft Entra للمصادقة، فانسخ والصق عنصر البرنامج النصي التالي داخل <head> العنصر، وأسفن العنصر الأول <script> .
```
<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>
```
لمزيد من المعلومات حول المصادقة مع خرائط Azure، راجع مستند المصادقة مع خرائط Azure. للحصول على قائمة بالعينات التي توضح كيفية تكامل Azure AD مع خرائط Azure، راجع خرائط Azure ونماذج Azure Active Directory في GitHub.

تلميح

في هذا المثال، عرضنا id الخاص بالخريطة في <div>. توجد طريقة أخرى للقيام بذلك وهي عرض العنصر HTMLElement عن طريق عرض document.getElementById('myMap') بصفته المعلمة الأولى.

بطريقة اختيارية، قد تجد أنه من المفيد إضافة العناصر meta إلى العنصر 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">

يجب أن يبدو ملف HTML الآن مشابها لمقتطف التعليمات البرمجية التالي:

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

افتح الملف في مستعرض الويب الخاص بك واستعرض الخريطة المعروضة. يجب أن تبدو مثل الصورة التالية:

ترجمة الخريطة

توفر خرائط Azure طريقتين مختلفتين لتعيين اللغة والعرض الإقليمي للخريطة المعروضة. الخيار الأول هو إضافة هذه المعلومات إلى مساحة الاسم العمومية atlas ، مما يؤدي إلى تعيين كافة مثيلات التحكم في الخريطة في تطبيقك افتراضيا إلى هذه الإعدادات. فيما يلي تعيين اللغة إلى الفرنسية ("fr-FR") وتعيين العرض الإقليمي إلى "تلقائي":

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

الخيار الثاني هو نقل هذه المعلومات إلى خيارات الخريطة عند تحميل الخريطة على النحو التالي:

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

إشعار

من الممكن تحميل مثيلات خريطة متعددة على نفس الصفحة باستخدام إعدادات لغة ومنطقة مختلفة. بالإضافة إلى ذلك، يمكن تحديث هذه الإعدادات بعد تحميل الخريطة عن طريق استخدام الوظيفة setStyle في الخريطة.

فيما يلي مثال على خرائط Azure مع تعيين اللغة إلى "fr-FR" وتعيين طريقة العرض الإقليمية إلى Auto.

للحصول على قائمة باللغات المدعومة وطرق العرض الإقليمية، راجع دعم الترجمة في خرائط Azure.

توافق WebGL 2

بدءا من خرائط Azure Web SDK 3.0، يتضمن Web SDK التوافق الكامل مع WebGL 2، وهي تقنية رسومات قوية تمكن العرض المتسارع للأجهزة في مستعرضات الويب الحديثة. باستخدام WebGL 2، يمكن للمطورين الاستفادة من قدرات وحدات معالجة الرسومات الحديثة لتقديم الخرائط والمرئيات المعقدة بشكل أكثر كفاءة، ما يؤدي إلى تحسين الأداء وجودة المرئيات.

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>

تجانبات التضاريس ثلاثية الأبعاد

بدءا من خرائط Azure Web SDK 3.0، يمكن للمطورين الاستفادة من مرئيات التضاريس ثلاثية الأبعاد. تسمح لك هذه الميزة بدمج بيانات الارتفاع في الخرائط الخاصة بك، مما يؤدي إلى إنشاء تجربة أكثر غامرة للمستخدمين. سواء كان تصور النطاقات الجبلية أو الوديان أو الميزات الجغرافية الأخرى، فإن دعم التضاريس ثلاثية الأبعاد يجلب مستوى جديدا من الواقعية لتطبيقات الخرائط الخاصة بك.

يوضح مثال التعليمات البرمجية التالي كيفية تنفيذ تجانبات التضاريس ثلاثية الأبعاد.

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

دعم Azure Government cloud

تدعم خرائط Azure Web SDK سحابة Microsoft Azure Government. تظل كافة عناوين URL لـ JavaScript وCSS المستخدمة للوصول إلى Web SDK الخاصة بخرائط Azure كما هي. يجب القيام بالمهام التالية للاتصال بإصدار سحابة Azure Government من النظام الأساسي خرائط Azure.

عند استخدام عنصر التحكم بالخريطة التفاعلي، أضف الخط التالي من التعليمات البرمجية قبل إنشاء مثيل للفئة Map.