Menambahkan popup ke peta

Artikel ini menunjukkan cara menambahkan popup ke titik pada peta.

Memahami kode

Kode berikut menambahkan fitur titik, yang memiliki properti name dan description, ke peta menggunakan lapisan simbol. Instans Kelas popup dibuat tetapi tidak ditampilkan. Peristiwa mouse ditambahkan ke lapisan simbol untuk memicu pembukaan dan penutupan popup. Saat pointer mouse diarahkan ke simbol penanda, properti position popup diperbarui dengan posisi penanda, dan opsi content diperbarui dengan beberapa HTML yang membungkus properti name dan description dari fitur titik tempat pointer diarahkan. Kemudian popup akan dimunculkan di peta menggunakan fungsi open-nya.

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

Berikut contoh lengkap menjalankan kode dari fungsi di atas.


Menggunakan kembali popup dengan beberapa titik

Ada kasus di mana praktik terbaiknya adalah membuat satu popup dan menggunakannya kembali. Misalnya, Anda mungkin memiliki banyak titik dan hanya ingin menampilkan satu popup dalam satu waktu. Dengan menggunakan kembali popup, jumlah elemen DOM yang dibuat oleh aplikasi akan berkurang drastis, yang dapat menghasilkan performa lebih baik. Berikut contoh membuat fitur 3 titik. Jika Anda mengeklik salah satu titiknya, sebuah popup akan muncul dengan konten untuk fitur titik tersebut.


Mengkustomisasi popup

Secara default, popup memiliki latar belakang putih, panah penunjuk di bagian bawah, dan tombol tutup di sudut kanan atas. Berikut contoh mengubah warna latar belakang menjadi hitam menggunakan opsi fillColor popup. Tombol tutup dapat dihilangkan dengan menetapkan opsi CloseButton ke false. Konten HTML popup menggunakan padding 10 piksel dari tepi popup. Teks berwarna putih, sangat cocok dengan latar belakang hitam.


Menambahkan templat popup ke peta

Templat popup memudahkan pembuatan tata letak berbasis data untuk popup. Bagian di bawah ini menunjukkan penggunaan berbagai templat popup untuk membuat konten berformat menggunakan properti fitur.

Catatan

Secara default, semua konten yang dirender menggunakan templat popup akan di-sandbox di dalam iframe sebagai fitur keamanan. Namun, ada beberapa batasan yang perlu diperhatikan:

  • Semua skrip, format, pointer lock, dan fungsionalitas navigasi atas dinonaktifkan. Tautan diizinkan untuk terbuka di tab baru saat diklik.
  • Browser lama yang tidak mendukung parameter srcdoc pada iframe hanya dapat merender konten dalam jumlah kecil.

Jika berharap data dimuat ke dalam popup dan ingin skrip yang dimuat ke dalam popup ini dapat mengakses aplikasi, Anda dapat menonaktifkan pengaturannya dengan menetapkan opsi sandboxContent templat popup ke false.

Templat string

Template String mengganti tempat penampung dengan nilai properti fitur. Properti fitur tidak harus diberi nilai jenis String. Misalnya, value1 bernilai bilangan bulat. Nilai-nilai ini kemudian diteruskan ke properti konten popupTemplate.

Opsi numberFormat menentukan format angka yang akan ditampilkan. Jika numberFormat tidak ditentukan, kode akan menggunakan format tanggal templat popup. Opsi numberFormat memformat angka menggunakan fungsi Number.toLocaleString. Untuk memformat angka besar, pertimbangkan untuk menggunakan opsi numberFormat dengan fungsi dari NumberFormat.format. Contohnya, cuplikan kode di bawah ini menggunakan maximumFractionDigits untuk membatasi jumlah angka pecahan menjadi dua.

Catatan

Hanya ada satu cara agar templat String dapat merender gambar. Pertama, templat String harus memiliki tag gambar. Nilai yang diteruskan ke tag gambar harus berupa URL ke gambar. Kemudian, templat String harus memiliki isImage yang ditetapkan ke true di HyperLinkFormatOptions. Opsi isImage menentukan bahwa hyperlink adalah untuk gambar, dan akan dimuat ke dalam tag gambar. Saat hyperlink diklik, gambar akan terbuka.

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

Templat PropertyInfo

Templat PropertyInfo menampilkan properti fitur yang tersedia. Opsi label menentukan teks yang akan ditampilkan ke pengguna. Jika label tidak ditentukan, maka hyperlink akan ditampilkan. Kemudian, jika hyperlink adalah gambar, nilai yang ditetapkan ke tag "alt" akan ditampilkan. dateFormat menentukan format tanggal, jika format tanggal tidak ditentukan, maka tanggal akan dirender sebagai string. Opsi hyperlinkFormat merender tautan yang dapat diklik, sama halnya dengan opsi email yang dapat digunakan untuk merender alamat email yang dapat diklik.

Sebelum templat PropertyInfo menampilkan properti ke pengguna akhir, templat tersebut secara berulang akan memeriksa apakah properti memang ditentukan untuk fitur tersebut. Templat tersebut juga akan mengabaikan properti gaya dan judul yang ditampilkan. Misalnya, templat tersebut tidak akan menampilkan color, size, anchor, strokeOpacity, dan visibility. Jadi, setelah pemeriksaan jalur properti selesai di ujung belakang, templat PropertyInfo akan menampilkan konten dalam format tabel.

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://aka.ms/AzureMapsSamples',
    email: 'info@microsoft.com'
}),

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

Beberapa templat konten

Fitur juga dapat menampilkan konten menggunakan kombinasi templat String dan templat PropertyInfo. Dalam hal ini, templat String merender nilai tempat penampung pada latar belakang putih. Kemudian, templat PropertyInfo merender keseluruhan gambar di dalam tabel. Properti dalam sampel ini sama dengan properti yang telah dijelaskan pada sampel sebelumnya.

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://azuremapscodesamples.azurewebsites.net/common/images/Pike_Market.jpg'
});

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

Titik tanpa templat yang ditentukan

Jika templat Popup tidak ditentukan sebagai templat String, templat PropertyInfo, atau kombinasi keduanya, maka templat tersebut akan menggunakan pengaturan default. Jika title dan description adalah satu-satunya properti yang ditentukan, templat popup akan menampilkan latar belakang putih dan tombol tutup di sudut kanan atas. Serta, pada layar kecil dan sedang, templat akan menampilkan panah di bagian bawah. Pengaturan default menampilkan konten dalam tabel untuk semua properti selain title dan description. Bahkan ketika dikembalikan ke pengaturan default, templat popup masih dapat dimanipulasi secara terprogram. Misalnya, pengguna dapat menonaktifkan deteksi hyperlink dan pengaturan default akan tetap berlaku untuk properti lain.

Klik titik pada peta di CodePen. Ada titik di peta untuk setiap templat popup berikut: templat String, templat PropertyInfo, dan templat Beberapa konten. Ada juga tiga titik untuk menunjukkan bagaimana templat dirender menggunakan pengaturan default.


Menggunakan kembali templat popup

Sama halnya dengan menggunakan kembali popup, Anda juga dapat menggunakan kembali templat popup. Pendekatan ini berguna jika Anda hanya ingin menampilkan satu templat popup pada satu waktu, untuk beberapa titik. Dengan menggunakan kembali templat popup, jumlah elemen DOM yang dibuat oleh aplikasi akan berkurang, yang kemudian dapat meningkatkan performa aplikasi Anda. Contoh berikut menggunakan templat popup yang sama untuk tiga titik. Jika Anda mengeklik salah satu titiknya, sebuah popup akan muncul dengan konten untuk fitur titik tersebut.


Popup dapat dibuka, ditutup, dan diseret. Kelas popup menyediakan peristiwa untuk membantu pengembang bereaksi dengan peristiwa ini. Contoh berikut menyoroti peristiwa mana yang diaktifkan saat pengguna membuka, menutup, atau menyeret popup.


Langkah berikutnya

Pelajari selengkapnya tentang kelas dan metode yang digunakan di artikel ini:

Lihaf artikel penting berikut untuk contoh kode lengkap: