Aggiungere un popup a un punto su una mappa

Articolo
08/09/2024

Questo articolo illustra come aggiungere un pop a un punto in una mappa.

Informazioni sul codice

Il codice seguente aggiunge una funzionalità punto con le proprietà name e description alla mappa usando un livello simbolo. Viene creata un'istanza della classe Popup ma non viene visualizzata. Gli eventi del mouse vengono aggiunti al livello simbolo per attivare l'apertura e la chiusura del popup. Quando si passa il puntatore del mouse sul simbolo del marcatore, la proprietà position del popup viene aggiornata con la posizione del marcatore e l'opzione content viene aggiornata con un codice HTML che esegue il wrapping delle proprietà name e description della funzionalità del punto al passaggio del mouse. Il popup viene quindi visualizzato sulla mappa usando la relativa funzione 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();
});

Esistono casi in cui l'approccio migliore consiste nel creare un popup e riutilizzarlo. Ad esempio, si potrebbe avere un numero elevato di punti e si desidera visualizzare un solo popup alla volta. Riutilizzando il popup, il numero di elementi DOM creati dall'applicazione è notevolmente ridotto, il che può fornire prestazioni migliori. Nell'esempio seguente vengono create funzionalità a 3 punti. Se si seleziona una di esse, verrà visualizzato un popup con il contenuto di tale funzionalità punto.

Per un esempio completamente funzionale che illustra come creare un popup e riutilizzarlo invece di creare un popup per ogni funzionalità di punto, vedere Popup di riutilizzo con più pin negli Esempi di Mappe di Azure. Per il codice sorgente di questo esempio, vedere Codice sorgente Riutilizzo di popup con segnaposto.

Per impostazione predefinita, il popup ha uno sfondo bianco, una freccia del puntatore in basso e un pulsante di chiusura nell'angolo superiore destro. Nell'esempio seguente il colore di sfondo viene modificato in nero usando l'opzione fillColor del popup. Il pulsante di chiusura viene rimosso impostando l'opzione CloseButton su false. Il contenuto HTML del popup usa una spaziatura interna di 10 pixel dai bordi del popup. Il testo viene reso bianco, quindi è visualizzabile con facilità sullo sfondo nero.

Per un esempio completamente funzionale che illustra come personalizzare l'aspetto di un popup, vedere Personalizzare un popup negli Esempi di Mappe di Azure. Per il codice sorgente per questo campione, vedere Personalizzare un codice sorgente popup.

I modelli popup semplificano la creazione di layout basati sui dati per i popup. Le sezioni seguenti illustrano l'uso di vari modelli popup per generare contenuto formattato usando le proprietà delle funzionalità.

Nota

Per impostazione predefinita, tutto il contenuto di cui è stato eseguito il rendering con il modello popup verrà sottoposto a sandbox all'interno di un iFrame come funzionalità di sicurezza. Esistono tuttavia limitazioni:

tutti gli script, i moduli, il blocco del puntatore e la funzionalità di spostamento superiore sono disabilitati. Quando l'opzione è selezionata, i collegamenti possono essere aperti in una nuova scheda.
I browser meno recenti che non supportano il parametro srcdoc negli iFrame saranno limitati al rendering di una piccola quantità di contenuto.

Se si considera attendibile il caricamento dei dati nei popup e si vuole che questi script caricati nei popup siano in grado di accedere all'applicazione, è possibile disabilitare questa opzione impostando l'opzione sandboxContent dei modelli popup su false.

Modello stringa

Il modello Stringa sostituisce i segnaposto con i valori delle proprietà della funzionalità. Non è necessario assegnare alle proprietà della funzionalità un valore di tipo Stringa. Ad esempio, value1 contiene un numero intero. Questi valori vengono quindi passati alla proprietà contenuto di popupTemplate.

L'opzione numberFormat specifica il formato del numero da visualizzare. Se numberFormat non è specificato, il codice usa il formato data dei modelli popup. L'opzione numberFormat formatta i numeri usando la funzione Number.toLocaleString. Per formattare numeri di grandi dimensioni, è consigliabile usare l'opzione numberFormat con le funzioni da NumberFormat.format. Ad esempio, il frammento di codice seguente usa maximumFractionDigits per limitare il numero di cifre frazionarie a due.

Nota

Esiste solo un modo in cui il modello Stringa può eseguire il rendering delle immagini. Prima di tutto, il modello Stringa deve avere un tag immagine. Il valore passato al tag immagine deve essere un URL di un'immagine. Il modello Stringa deve quindi avere isImage impostato su true in HyperLinkFormatOptions. L'opzione isImage specifica che il collegamento ipertestuale è relativo a un'immagine e che verrà caricato in un tag immagine. Quando si fa clic sul collegamento ipertestuale, si aprirà l'immagine.

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

Modello PropertyInfo

Il modello PropertyInfo visualizza le proprietà disponibili della funzionalità. L'opzione label specifica il testo da visualizzare all'utente. Se label non è specificato, viene visualizzato il collegamento ipertestuale. Se il collegamento ipertestuale è un'immagine, viene visualizzato il valore assegnato al tag "alt". dateFormat specifica il formato della data e, se questo non è specificato, la data viene visualizzata come stringa. L'opzione hyperlinkFormat esegue il rendering dei collegamenti selezionabili. Analogamente, l'opzione email può essere usata per eseguire il rendering degli indirizzi di posta elettronica selezionabili.

Prima che il modello PropertyInfo visualizzi le proprietà all'utente finale, verifica in modo ricorsivo che queste siano effettivamente definite per tale funzionalità. Ignora anche la visualizzazione delle proprietà dello stile e del titolo. Ad esempio, non visualizza color, size, anchor, strokeOpacity e visibility. Quindi, una volta completato il controllo del percorso delle proprietà nel back-end, il modello PropertyInfo mostra il contenuto in un formato di tabella.

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

Più modelli di contenuto

Una funzionalità potrebbe anche visualizzare il contenuto usando una combinazione del modello Stringa e del modello PropertyInfo. In questo caso, il modello Stringa esegue il rendering dei segnaposto su uno sfondo bianco. Il modello PropertyInfo esegue inoltre il rendering di un'immagine a larghezza intera all'interno di una tabella. Le proprietà di questo esempio sono simili a quelle illustrate negli esempi precedenti.

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

Punti senza un modello definito

Quando il modello Popup non è definito come modello Stringa, un modello PropertyInfo o una combinazione di entrambi, usa le impostazioni predefinite. Quando title e description sono le uniche proprietà assegnate, il modello Popup mostra uno sfondo bianco e un pulsante di chiusura nell'angolo superiore destro. E, su schermi piccoli e medi, mostra una freccia in basso. Le impostazioni predefinite vengono visualizzate all'interno di una tabella per tutte le proprietà diverse da title e da description. Anche quando si esegue il fallback alle impostazioni predefinite, il modello Popup può comunque essere modificato a livello di codice. Ad esempio, gli utenti possono disattivare il rilevamento dei collegamenti ipertestuali e le impostazioni predefinite verranno comunque applicate ad altre proprietà.

Dopo l'esecuzione, è possibile selezionare i punti sulla mappa per visualizzare il popup. È presente un punto sulla mappa per ognuno dei modelli popup seguenti: modello Stringa, modello PropertyInfo e modello Contenuto multiplo. Esistono anche tre punti per mostrare come viene eseguito il rendering dei modelli con le impostazioni predefinite.

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

Analogamente al riutilizzo di un popup, è possibile riutilizzare i modelli popup. Questo approccio è utile quando si vuole visualizzare un solo modello popup alla volta per più punti. Il riutilizzo dei modelli popup riduce il numero di elementi DOM creati dall'applicazione, migliorando le prestazioni delle applicazioni. L'esempio seguente usa lo stesso modello popup per tre punti. Se si seleziona una di esse, verrà visualizzato un popup con il contenuto di tale funzionalità punto.

Per un esempio completamente funzionale che mostra l'accesso frequente per riutilizzare un singolo modello popup con più funzionalità che condividono un set comune di campi delle proprietà, vedere Riutilizzare un modello popup negli Esempi di Mappe di Azure. Per il codice sorgente per questo campione, vedere Riutilizzare il codice sorgente di un modello popup.

I popup possono essere aperti, chiusi e trascinati. La classe popup fornisce eventi che consentono agli sviluppatori di reagire a questi ultimi. Nell'esempio seguente vengono evidenziati gli eventi generati quando l'utente apre, chiude o trascina il popup.

Per un esempio completamente funzionale che illustra come aggiungere eventi ai popup, vedere Eventi popup negli Esempi di Mappe di Azure. Per il codice sorgente per questo campione, vedere il codice sorgente degli eventi popup.