إضافة نافذة منبثقة إلى نقطة على مخطط

مقالة
06/15/2023

توضح لك هذه المقالة كيفية إضافة نافذة منبثقة إلى نقطة على مخطط.

فهم الرمز

تضيف التعليمات البرمجية التالية ميزة نقطة مع name وخصائص description إلى الخريطة باستخدام طبقة رمز. يتم إنشاء مثيل لفئة النافذة المنبثقة، لكن لا يتم عرضه. تتم إضافة أحداث الماوس إلى طبقة الرمز لتشغيل فتح النافذة المنبثقة وإغلاقها. عند تمرير رمز العلامة، يتم تحديث الخاصية position في النافذة المنبثقة بموضع العلامة، ويتم تحديث الخيار content ببعض HTML الذي يتضمن على خصائص name وdescription لميزة النقطة التي يتم تمريرها. ثم يتم عرض النافذة المنبثقة على المخطط باستخدام الدالة open الخاصة بها.

//Define an HTML template for a custom popup content laypout.
var popupTemplate = '<div class="customInfobox"><div class="name">{name}</div>{description}</div>';

//Create a data source and add it to the map.
var dataSource = new atlas.source.DataSource();
map.sources.add(dataSource);

dataSource.add(new atlas.data.Feature(new atlas.data.Point([-122.1333, 47.63]), {
  name: 'Microsoft Building 41', 
  description: '15571 NE 31st St, Redmond, WA 98052'
}));

//Create a layer to render point data.
var symbolLayer = new atlas.layer.SymbolLayer(dataSource);

//Add the polygon and line the symbol layer to the map.
map.layers.add(symbolLayer);

//Create a popup but leave it closed so we can update it and display it later.
popup = new atlas.Popup({
  pixelOffset: [0, -18],
  closeButton: false
});

//Add a hover event to the symbol layer.
map.events.add('mouseover', symbolLayer, function (e) {
  //Make sure that the point exists.
  if (e.shapes && e.shapes.length > 0) {
    var content, coordinate;
    var properties = e.shapes[0].getProperties();
    content = popupTemplate.replace(/{name}/g, properties.name).replace(/{description}/g, properties.description);
    coordinate = e.shapes[0].getCoordinates();

    popup.setOptions({
      //Update the content of the popup.
      content: content,

      //Update the popup's position with the symbol's coordinate.
      position: coordinate

    });
    //Open the popup.
    popup.open(map);
  }
});

map.events.add('mouseleave', symbolLayer, function (){
  popup.close();
});

توجد حالات يكون فيها أفضل نهج هو إنشاء نافذة منبثقة واحدة وإعادة استخدامها. على سبيل المثال، قد يكون لديك عدد كبير من النقاط وتريد إظهار نافذة منبثقة واحدة فقط في كل مرة. من خلال إعادة استخدام النافذة المنبثقة، يتم تقليل عدد عناصر DOM التي أنشأها التطبيق بشكل كبير، والتي يمكن أن توفر أداءً أفضل. تنشئ العينة التالية ميزات من 3 نقاط. إذا قمت بتحديد أي منها، يتم عرض نافذة منبثقة مع محتوى ميزة هذه النقطة.

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

تحتوي النافذة المنبثقة بشكل افتراضي على خلفية بيضاء وسهم مؤشر في الأسفل وزر إغلاق في الزاوية العلوية اليمنى. تغير العينة التالية لون الخلفية إلى أسود باستخدام خيار fillColor للنافذة المنبثقة. تتم إزالة زر الإغلاق عن طريق ضبط الخيار CloseButton على خطأ. يستخدم محتوى HTML للنافذة المنبثقة 10 بكسل مضاف من حواف النافذة المنبثقة. يتم جعل النص أبيض، لذلك يظهر بشكل جيد على الخلفية السوداء.

للحصول على عينة تعمل بكامل طاقتها توضح كيفية تخصيص مظهر نافذة منبثقة، راجع تخصيص نافذة منبثقة في خرائط Azure Samples. للحصول على التعليمات البرمجية المصدر لهذا النموذج، راجع تخصيص رمز مصدر منبثق.

تسهل قوالب النوافذ المنبثقة إنشاء تخطيطات تستند إلى البيانات للنوافذ المنبثقة. توضح الأقسام التالية استخدام قوالب منبثقة مختلفة لإنشاء محتوى منسق باستخدام خصائص الميزات.

إشعار

سيتم وضع بيئة الاختبار المعزولة لكل المحتوى المعروض باستخدام قالب النافذة المنبثقة داخل iframe كميزة أمان. مع ذلك، توجد قيود يجب مراعاتها:

يتم تعطيل جَميع البرامج النصية والنماذج وقفل المؤشر ووظيفة التنقل العلوية. يسمح بفتح الارتباطات في علامة تبويب جديدة عند تحديدها.
ستقتصر المتصفحات القديمة التي لا تدعم المعلمة srcdoc حول عناصر iframe على عرض كمية صغيرة من المحتوى.

إذا كنت تثق في البيانات التي يتم تحميلها في النوافذ المنبثقة وربما تريد أن تكون هذه البرامج النصية التي تم تحميلها في نوافذ منبثقة قادرة على الوصول إلى التطبيق الخاص بك، يمكنك تعطيل ذلك عن طريق ضبط خيار sandboxContent لقوالب النوافذ المنبثقة على خطأ.

قالب السلسلة

يستبدل قالب السلسلة العناصر النائبة بقيم خصائص الميزة. لا يلزم تعيين قيمة من نوع السلسلة لخصائص الميزة. على سبيل المثال، يحمل value1 عددًا صحيحًا. ثم يتم تمرير هذه القيم إلى خاصية المحتوى الخاصة لـ popupTemplate.

يحدد الخيار numberFormat تنسيق الرقم المراد عرضه. numberFormat إذا لم يتم تحديد ، فإن التعليمات البرمجية تستخدم تنسيق تاريخ القوالب المنبثقة. يقوم الخيار numberFormat بتنسيق الأرقام باستخدام الدالة Number.toLocaleString. لتنسيق أرقام كبيرة، ضع في اعتبارك استخدام الخيار numberFormat مع الدالات من NumberFormat.format. على سبيل المثال، تستخدم maximumFractionDigits التعليمات البرمجية التالية للمقتطف للحد من عدد أرقام الكسر إلى رقمين.

إشعار

توجد طريقة واحدة فقط يمكن أن يعرض بها قالب السلسلة الصور. أولًا، يجب أن يحتوي قالب السلسلة على علامة صورة بداخله. يجب أن تكون القيمة التي يتم تمريرها إلى علامة الصورة عنوان URL إلى صورة. بعد ذلك، يجب أن يحتوي قالب السلسلة على isImage يتم ضبطه عل صحيح في HyperLinkFormatOptions. يحدد الخيار isImage أن الارتباط هو لصورة، وسيتم تحميل الارتباط في علامة صورة. عند النقر فوق الارتباط، سيتم فتح الصورة.

var templateOptions = {
  content: 'This template uses a string template with placeholders.<br/><br/> - Value 1 = {value1}<br/> - Value 2 = {value2/subValue}<br/> - Array value [2] = {arrayValue/2}',
  numberFormat: {
    maximumFractionDigits: 2
  }
};

var feature = new atlas.data.Feature(new atlas.data.Point([0, 0]), {
    title: 'Template 1 - String template',
    value1: 1.2345678,
    value2: {
        subValue: 'Pizza'
    },
    arrayValue: [3, 4, 5, 6]
});

var popup = new atlas.Popup({
  content: atlas.PopupTemplate.applyTemplate(feature.properties, templateOptions),
  position: feature.geometry.coordinates
});

قالب PropertyInfo

يعرض قالب PropertyInfo الخصائص المتوفرة للميزة. يحدد الخيار label النص المراد عرضه للمستخدم. إذا label لم يتم تحديده، عرض الارتباط التشعبي. وإذا كان الارتباط التشعبي صورة، يتم عرض القيمة المعينة للعلامة "alt". dateFormat يحدد تنسيق التاريخ، وإذا لم يتم تحديد تنسيق التاريخ، عرض التاريخ كسلسلة. يعرض الخيار hyperlinkFormat ارتباطات قابلة للنقر، وبالمثل، يمكن استخدام الخيار email لعرض عناوين البريد الإلكتروني القابلة للنقر.

قبل أن يعرض قالب PropertyInfo الخصائص للمستخدم، فإنه يفحص بشكل متكرر أن الخصائص محددة بالفعل لتلك الميزة. كما أنه يتجاهل عرض خصائص النمط والعنوان. على سبيل المثال، لا يعرض colorوsizeanchorstrokeOpacity.visibility لذلك، بمجرد اكتمال فحص مسار الخاصية في الخلفية، يعرض قالب PropertyInfo المحتوى بتنسيق جدول.

var templateOptions = {
  content: [
    {
        propertyPath: 'createDate',
        label: 'Created Date'
    },
    {
        propertyPath: 'dateNumber',
        label: 'Formatted date from number',
        dateFormat: {
          weekday: 'long',
          year: 'numeric',
          month: 'long',
          day: 'numeric',
          timeZone: 'UTC',
          timeZoneName: 'short'
        }
    },
    {
        propertyPath: 'url',
        label: 'Code samples',
        hideLabel: true,
        hyperlinkFormat: {
          label: 'Go to code samples!',
          target: '_blank'
        }
    },
    {
        propertyPath: 'email',
        label: 'Email us',
        hideLabel: true,
        hyperlinkFormat: {
          target: '_blank',
          scheme: 'mailto:'
        }
    }
  ]
};

var feature = new atlas.data.Feature(new atlas.data.Point([0, 0]), {
    title: 'Template 2 - PropertyInfo',
    createDate: new Date(),
    dateNumber: 1569880860542,
    url: 'https://samples.azuremaps.com/',
    email: 'info@microsoft.com'
}),

var popup = new atlas.Popup({
  content: atlas.PopupTemplate.applyTemplate(feature.properties, templateOptions),
  position: feature.geometry.coordinates
});

قوالب محتوى متعددة

قد تعرض الميزة أيضا المحتوى باستخدام مجموعة من قالب String وقالب PropertyInfo. في هذه الحالة، يعرض قالب السلسلة قيم العناصر النائبة على خلفية بيضاء. ويعرض قالب PropertyInfo صورة كاملة العرض داخل جدول. الخصائص الموجودة في هذا النموذج مشابهة للخصائص التي شرحناها في العينات السابقة.

var templateOptions = {
  content: [
    'This template has two pieces of content; a string template with placeholders and a array of property info which renders a full width image.<br/><br/> - Value 1 = {value1}<br/> - Value 2 = {value2/subValue}<br/> - Array value [2] = {arrayValue/2}',
    [{
      propertyPath: 'imageLink',
      label: 'Image',
      hideImageLabel: true,
      hyperlinkFormat: {
        isImage: true
      }
    }]
  ],
  numberFormat: {
    maximumFractionDigits: 2
  }
};

var feature = new atlas.data.Feature(new atlas.data.Point([0, 0]), {
    title: 'Template 3 - Multiple content template',
    value1: 1.2345678,
    value2: {
    subValue: 'Pizza'
    },
    arrayValue: [3, 4, 5, 6],
    imageLink: 'https://samples.azuremaps.com/images/Pike_Market.jpg'
});

var popup = new atlas.Popup({
  content: atlas.PopupTemplate.applyTemplate(feature.properties, templateOptions),
  position: feature.geometry.coordinates
});

نقاط بدون قالب محدد

عندما لا يتم تعريف القالب المنبثق على أنه قالب السلسلة أو قالب PropertyInfo أو مزيج من كليهما، فإنه يستخدم الإعدادات الافتراضية. عندما يكون title وdescription خصائص المعينة فحسب، يظهر القالب المنبثق بخلفية بيضاء، وزر إغلاق في الزاوية العلوية اليمنى. ويظهر سهم في الأسفل على الشاشات الصغيرة والمتوسطة. تظهر الإعدادات الافتراضية داخل جدول لجميع الخصائص بخلاف title وdescription. حتى عند الرجوع إلى الإعدادات الافتراضية، لا يزال من الممكن معالجة القالب المنبثق برمجيًا. على سبيل المثال، يمكن للمستخدمين إيقاف تشغيل الكشف عن الارتباط وستظل الإعدادات الافتراضية تنطبق على الخصائص الأخرى.

بمجرد التشغيل، يمكنك تحديد النقاط على الخريطة لمشاهدة النافذة المنبثقة. هناك نقطة على الخريطة لكل من القوالب المنبثقة التالية: قالب السلسلة، وقالب PropertyInfo، وقالب محتوى متعدد. توجد أيضًا ثلاث نقاط لإظهار كيفية عرض القوالب باستخدام الإعدادات الافتراضية.

function InitMap()
{
  var map = new atlas.Map('myMap', {
      zoom: 2,
      view: "Auto",

    //Add authentication details for connecting to Azure Maps.
      authOptions: {
          authType: 'subscriptionKey',
          subscriptionKey: '{Your-Azure-Maps-Subscription-key}'
      }
  });

  //Wait until the map resources are ready.
  map.events.add('ready', function() {
    //Create a data source and add it to the map.
    var datasource = new atlas.source.DataSource();
    map.sources.add(datasource);

    //Add sample data.
    datasource.add([
      new atlas.data.Feature(new atlas.data.Point([-20, 20]), {
        title: 'No template - title/description',
        description: 'This point doesn\'t have a template defined, fallback to title and description properties.'
      }),

      new atlas.data.Feature(new atlas.data.Point([20, 20]), {
        title: 'No template - property table',
        message: 'This point doesn\'t have a template defined, fallback to title and table of properties.',
        randomValue: 10,
        url: 'https://samples.azuremaps.com/',
        imageLink: 'https://samples.azuremaps.com/images/Pike_Market.jpg',
        email: 'info@microsoft.com'
      }),

      new atlas.data.Feature(new atlas.data.Point([40, 0]), {
        title: 'No template - hyperlink detection disabled',
        message: 'This point doesn\'t have a template defined, fallback to title and table of properties.',
        randomValue: 10,
        url: 'https://samples.azuremaps.com/',
        email: 'info@microsoft.com',
        popupTemplate: {
          detectHyperlinks: false
        }
      }),

      new atlas.data.Feature(new atlas.data.Point([-20, -20]), {
        title: 'Template 1 - String template',
        value1: 1.2345678,
        value2: {
          subValue: 'Pizza'
        },
        arrayValue: [3, 4, 5, 6],
        popupTemplate: {
          content: 'This template uses a string template with placeholders.<br/><br/> - Value 1 = {value1}<br/> - Value 2 = {value2/subValue}<br/> - Array value [2] = {arrayValue/2}',
          numberFormat: {
            maximumFractionDigits: 2
          }
        }
      }),

      new atlas.data.Feature(new atlas.data.Point([20, -20]), {
        title: 'Template 2 - PropertyInfo',
        createDate: new Date(),
        dateNumber: 1569880860542,
        url: 'https://samples.azuremaps.com/',
        email: 'info@microsoft.com',
        popupTemplate: {
          content: [{
            propertyPath: 'createDate',
            label: 'Created Date'
          },
                    {
                      propertyPath: 'dateNumber',
                      label: 'Formatted date from number',
                      dateFormat: {
                        weekday: 'long',
                        year: 'numeric',
                        month: 'long',
                        day: 'numeric',
                        timeZone: 'UTC',
                        timeZoneName: 'short'
                      }
                    },
                    {
                      propertyPath: 'url',
                      label: 'Code samples',
                      hideLabel: true,
                      hyperlinkFormat: {
                        label: 'Go to code samples!',
                        target: '_blank'
                      }
                    },
                    {
                      propertyPath: 'email',
                      label: 'Email us',
                      hideLabel: true,
                      hyperlinkFormat: {
                        target: '_blank',
                        scheme: 'mailto:'
                      }
                    }
                    ]
        }
      }),

      new atlas.data.Feature(new atlas.data.Point([0, 0]), {
        title: 'Template 3 - Multiple content template',
        value1: 1.2345678,
        value2: {
          subValue: 'Pizza'
        },
        arrayValue: [3, 4, 5, 6],
        imageLink: 'https://samples.azuremaps.com/images/Pike_Market.jpg',
        popupTemplate: {
          content: [
            'This template has two pieces of content; a string template with placeholders and a array of property info which renders a full width image.<br/><br/> - Value 1 = {value1}<br/> - Value 2 = {value2/subValue}<br/> - Array value [2] = {arrayValue/2}',
            [{
              propertyPath: 'imageLink',
              label: 'Image',
              hideImageLabel: true,
              hyperlinkFormat: {
                isImage: true
              }
            }]
          ],
          numberFormat: {
            maximumFractionDigits: 2
          }
        }
      }),
    ]);

    //Create a layer that defines how to render the points on the map.
    var layer = new atlas.layer.BubbleLayer(datasource);
    map.layers.add(layer);

    //Create a popup but leave it closed so we can update it and display it later.
    popup = new atlas.Popup();

    //Add a click event to the layer.
    map.events.add('click', layer, showPopup);
  });

  function showPopup(e) {
    if (e.shapes && e.shapes.length > 0) {
      var properties = e.shapes[0].getProperties();

      popup.setOptions({
        //Update the content of the popup.
        content: atlas.PopupTemplate.applyTemplate(properties, properties.popupTemplate),

        //Update the position of the popup with the pins coordinate.
        position: e.shapes[0].getCoordinates()
      });

      //Open the popup.
      popup.open(map);
    }
  }
}

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

للحصول على نموذج كامل الوظائف يظهر التشغيل السريع لإعادة استخدام قالب منبثق واحد مع ميزات متعددة تشترك في مجموعة مشتركة من حقول الخصائص، راجع إعادة استخدام قالب منبثق في خرائط Azure Samples. للحصول على التعليمات البرمجية المصدر لهذا النموذج، راجع إعادة استخدام التعليمات البرمجية لمصدر قالب منبثق.

يمكن فتح النوافذ المنبثقة وإغلاقها وسحبها. توفر فئة النافذة المنبثقة أحداثاً لمساعدة المطورين على التفاعل مع هذه الأحداث. تسلط العينة التالية الضوء على الأحداث التي يتم إطلاقها عند فتح المستخدم للنافذة المنبثقة أو إغلاقها أو سحبها.

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