Dodawanie wyskakującego okienka do punktu na mapie

Artykuł
10/24/2023

W tym artykule pokazano, jak dodać wyskakujące okienko do punktu na mapie.

Zrozumienie kodu

Poniższy kod dodaje funkcję punktu z właściwościami name i description do mapy przy użyciu warstwy symboli. Wystąpienie klasy Popup jest tworzone, ale nie jest wyświetlane. Zdarzenia myszy są dodawane do warstwy symboli w celu wyzwolenia otwierania i zamykania wyskakującego okienka. Po umieszczeniu kursora na symbolu znacznika właściwość wyskakującego okienka position zostanie zaktualizowana o położenie znacznika, a content opcja zostanie zaktualizowana przy użyciu kodu HTML, który opakowuje name właściwości i description funkcji punktu. Wyskakujące okienko zostanie wyświetlone na mapie przy użyciu jego open funkcji.

//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();
});

Istnieją przypadki, w których najlepszym rozwiązaniem jest utworzenie jednego wyskakującego okienka i ponowne użycie go. Na przykład może istnieć duża liczba punktów i chcieć wyświetlić tylko jedno wyskakujące okienko naraz. Po ponownym użyciu wyskakującego okienka liczba elementów DOM utworzonych przez aplikację jest znacznie zmniejszona, co może zapewnić lepszą wydajność. Poniższy przykład tworzy funkcje 3-punktowe. Jeśli wybierzesz dowolną z nich, zostanie wyświetlone okno podręczne z zawartością dla tej funkcji punktu.

Aby zapoznać się z w pełni funkcjonalnym przykładem przedstawiającym sposób tworzenia jednego wyskakującego okienka i ponownego używania go zamiast tworzenia wyskakujących okienek dla każdej funkcji punktu, zobacz Ponowne używanie wyskakujących okienek z wieloma pinezkami w przykładach usługi Azure Mapy. Aby zapoznać się z kodem źródłowym dla tego przykładu, zobacz Ponowne użycie wyskakujących okienek z kodem źródłowym z wieloma numerami PIN.

Domyślnie wyskakujące okienko ma białe tło, strzałkę wskaźnika w dolnej części i przycisk zamknięcia w prawym górnym rogu. Poniższy przykład zmienia kolor tła na czarny przy użyciu fillColor opcji wyskakującego okienka. Przycisk zamknięcia jest usuwany przez ustawienie CloseButton opcji false. Zawartość HTML wyskakującego okienka używa wyściełanego 10 pikseli z krawędzi wyskakujących okienek. Tekst jest biały, więc pojawia się ładnie na czarnym tle.

Aby uzyskać w pełni funkcjonalny przykład pokazujący sposób dostosowywania wyglądu wyskakującego okienka, zobacz Dostosowywanie wyskakującego okienka w przykładach usługi Azure Mapy. Aby zapoznać się z kodem źródłowym dla tego przykładu, zobacz Dostosowywanie kodu źródłowego wyskakującego okienka.

Szablony wyskakujące ułatwiają tworzenie układów opartych na danych dla wyskakujących okienek. W poniższych sekcjach przedstawiono użycie różnych szablonów wyskakujących do generowania sformatowanej zawartości przy użyciu właściwości funkcji.

Uwaga

Domyślnie cała zawartość renderowana przy użyciu szablonu wyskakującego będzie w trybie piaskownicy wewnątrz elementu iframe jako funkcji zabezpieczeń. Istnieją jednak ograniczenia:

Wszystkie skrypty, formularze, blokada wskaźnika i najważniejsze funkcje nawigacji są wyłączone. Linki mogą być otwierane na nowej karcie po kliknięciu.
Starsze przeglądarki, które nie obsługują parametru srcdoc w elementach iframe, będą ograniczone do renderowania niewielkiej ilości zawartości.

Jeśli ufasz ładowaniu danych do wyskakujących okienek i potencjalnie chcesz, aby te skrypty załadowane do okien podręcznych mogły uzyskać dostęp do aplikacji, możesz to wyłączyć, ustawiając opcję szablonów sandboxContent wyskakujących na wartość false.

Szablon ciągu

Szablon Ciąg zastępuje symbole zastępcze wartościami właściwości funkcji. Właściwości funkcji nie muszą mieć przypisanej wartości typu Ciąg. Na przykład value1 zawiera liczbę całkowitą. Te wartości są następnie przekazywane do właściwości content obiektu popupTemplate.

Opcja numberFormat określa format liczby do wyświetlenia. numberFormat Jeśli parametr nie zostanie określony, kod używa formatu daty szablonów wyskakujących. Opcja numberFormat formatuje liczby przy użyciu funkcji Number.toLocaleString . Aby sformatować duże liczby, rozważ użycie numberFormat opcji z funkcjami z formatu NumberFormat.format. Na przykład poniższy fragment kodu używa maximumFractionDigits metody w celu ograniczenia liczby cyfr ułamkowych do dwóch.

Uwaga

Istnieje tylko jeden sposób, w jaki szablon Ciąg może renderować obrazy. Najpierw szablon Ciąg musi mieć w nim tag obrazu. Wartość przekazywana do tagu obrazu powinna być adresem URL obrazu. Następnie szablon Ciąg musi mieć isImage ustawioną wartość true w elemecie HyperLinkFormatOptions. Opcja isImage określa, że hiperlink jest przeznaczony dla obrazu, a hiperlink zostanie załadowany do tagu obrazu. Po kliknięciu hiperlinku zostanie otwarty obraz.

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

Szablon PropertyInfo

Szablon PropertyInfo wyświetla dostępne właściwości funkcji. Opcja label określa tekst do wyświetlenia użytkownikowi. Jeśli label nie zostanie określony, zostanie wyświetlone hiperłącze. Jeśli hiperlink jest obrazem, zostanie wyświetlona wartość przypisana do tagu "alt". Określa dateFormat format daty, a jeśli format daty nie jest określony, data jest renderowana jako ciąg. Opcja hyperlinkFormat renderuje linki do klikania, podobnie, email można użyć opcji do renderowania klikalnych adresów e-mail.

Zanim szablon PropertyInfo wyświetli właściwości użytkownikowi końcowemu, cyklicznie sprawdza, czy właściwości są rzeczywiście zdefiniowane dla tej funkcji. Ignoruje również wyświetlanie właściwości stylu i tytułu. Na przykład nie wyświetla color, , size, anchorstrokeOpacity, i visibility. Dlatego po zakończeniu sprawdzania ścieżki właściwości w zapleczu szablon PropertyInfo wyświetla zawartość w formacie tabeli.

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

Wiele szablonów zawartości

Funkcja może również wyświetlać zawartość przy użyciu kombinacji szablonu Ciąg i szablonu PropertyInfo. W takim przypadku szablon Ciąg renderuje wartości zastępcze na białym tle. Szablon PropertyInfo renderuje obraz o pełnej szerokości wewnątrz tabeli. Właściwości w tym przykładzie są podobne do właściwości opisanych w poprzednich przykładach.

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

Punkty bez zdefiniowanego szablonu

Jeśli szablon wyskakujące nie jest zdefiniowany jako szablon ciąg, szablon PropertyInfo lub kombinacja obu tych elementów, użyje ustawień domyślnych. title Gdy właściwości i description są jedynymi przypisanymi właściwościami, szablon podręczny wyświetla białe tło, przycisk zamknięcia w prawym górnym rogu. Na małych i średnich ekranach jest wyświetlana strzałka u dołu. Ustawienia domyślne są wyświetlane wewnątrz tabeli dla wszystkich właściwości innych niż title i description. Nawet w przypadku powrotu do ustawień domyślnych szablon podręczny nadal można manipulować programowo. Na przykład użytkownicy mogą wyłączyć wykrywanie hiperłączy, a ustawienia domyślne będą nadal stosowane do innych właściwości.

Po uruchomieniu możesz wybrać punkty na mapie, aby wyświetlić wyskakujące okienko. Na mapie znajduje się punkt dla każdego z następujących szablonów wyskakujących: szablon ciągu, szablon PropertyInfo i szablon zawartości Wiele. Istnieją również trzy punkty pokazujące sposób renderowania szablonów przy użyciu ustawień domyślnych.

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

Podobnie jak w przypadku ponownego użycia wyskakującego okienka, można ponownie użyć szablonów wyskakujących okienek. Takie podejście jest przydatne, gdy chcesz wyświetlić tylko jeden szablon podręczny w danym momencie dla wielu punktów. Ponowne stosowanie szablonów wyskakujących zmniejsza liczbę elementów DOM utworzonych przez aplikację, co zwiększa wydajność aplikacji. W poniższym przykładzie użyto tego samego szablonu wyskakującego dla trzech punktów. Jeśli wybierzesz dowolną z nich, zostanie wyświetlone okno podręczne z zawartością dla tej funkcji punktu.

Aby zapoznać się z w pełni funkcjonalnym przykładem, który pokazuje gorącą możliwość ponownego użycia pojedynczego szablonu podręcznego z wieloma funkcjami współużytkującym wspólny zestaw pól właściwości, zobacz Ponowne używanie szablonu podręcznego w przykładach usługi Azure Mapy. Aby zapoznać się z kodem źródłowym dla tego przykładu, zobacz Używanie kodu źródłowego szablonu podręcznego.

Wyskakujące okienka można otwierać, zamykać i przeciągać. Klasa podręczna udostępnia zdarzenia ułatwiające deweloperom reagowanie na te zdarzenia. Poniższy przykład wyróżnia zdarzenia uruchamiane po otwarciu, zamknięciu lub przeciągnięciu wyskakującego okienka.

Aby zapoznać się z w pełni funkcjonalnym przykładem dodawania zdarzeń do wyskakujących okienek, zobacz Wyskakujące zdarzenia w przykładach usługi Azure Mapy. Aby uzyskać kod źródłowy dla tego przykładu, zobacz Kod źródłowy zdarzeń wyskakujących.