Tujuan
Pelajari cara mengintegrasikan Elemen Penelusuran Tempat dengan Google Maps untuk membantu pengguna menemukan tempat menggunakan penelusuran di sekitar atau penelusuran teks, sehingga meningkatkan kemampuan mereka untuk menjelajahi tempat menarik. Gunakan Elemen Ringkas Place Details untuk memberikan detail selengkapnya tentang tempat yang ditampilkan di aplikasi Anda.
Apa yang dimaksud dengan Elemen Penelusuran Tempat?
Elemen Penelusuran Tempat adalah bagian dari Kit UI Places di Maps JavaScript API. Ini adalah elemen HTML yang merender hasil penelusuran tempat secara langsung dalam format daftar di dalam aplikasi Anda. Elemen ini menyederhanakan proses menampilkan tempat yang ditemukan menggunakan Penelusuran di Sekitar atau Penelusuran Teks, sehingga memberikan pengalaman pengguna yang lancar untuk penemuan tempat. Saat pengguna memilih tempat dari daftar, Anda dapat menampilkan detailnya di peta, sering kali menggunakan Jendela Info dan Elemen Detail Tempat.
Memvisualisasikan penemuan tempat
Gambar berikut menunjukkan contoh cara kerja Elemen Penelusuran Tempat. Di sebelah kiri, daftar restoran ditampilkan (Elemen Penelusuran Tempat). Saat restoran dipilih, detailnya akan muncul di Jendela Info pada peta, dan peta akan berpusat pada lokasinya.
Kasus Penggunaan untuk Penemuan Tempat
Mengintegrasikan Elemen Penelusuran Tempat dapat meningkatkan kualitas berbagai aplikasi di berbagai industri:
- Perjalanan dan Pariwisata: Memungkinkan wisatawan menelusuri tempat wisata, hotel, atau jenis masakan tertentu di suatu area.
- Real Estate: Memungkinkan calon pembeli atau penyewa menemukan sekolah, supermarket, atau opsi transportasi umum di sekitar.
- Logistik dan Layanan: Membantu pengemudi menemukan SPKLU, SPBU, atau pusat servis tertentu.
Alur Kerja Solusi: Menerapkan Penemuan Tempat
Bagian ini memandu Anda melalui langkah-langkah untuk mengintegrasikan Elemen Penelusuran Tempat untuk menemukan tempat di peta, termasuk cuplikan kode untuk berinteraksi dengan Places UI Kit. Kita akan membahas cara menginisialisasi peta, dan menerapkan fungsi Penelusuran di Sekitar dan Penelusuran Teks. Terakhir, kita akan menggunakan elemen Place Details untuk menampilkan detail selengkapnya tentang tempat tertentu, saat pinnya diklik di peta.
Prasyarat
Sebaiknya Anda memahami dokumentasi berikut:
- Elemen Penelusuran Tempat - Digunakan untuk mengekspos tempat menggunakan Nearby Search atau Text Search
- Elemen Place Details - Digunakan untuk menampilkan detail setiap tempat
- Maps JavaScript API - Digunakan untuk menampilkan peta di halaman Anda, dan untuk mengimpor Places UI Kit
Aktifkan Maps JavaScript API dan Places UI Kit di project Anda.
Pastikan Anda telah memuat Maps JavaScript API dan mengimpor library yang diperlukan sebelum memulai. Dokumen ini juga mengasumsikan pengetahuan yang baik tentang pengembangan web, termasuk HTML, CSS, dan JavaScript.
Menambahkan peta ke halaman
Langkah pertama adalah menambahkan peta ke halaman Anda. Peta ini akan digunakan untuk menampilkan hasil Elemen Penelusuran Tempat sebagai pin yang dapat dipilih.
Ada dua cara untuk menambahkan peta ke halaman:
- Menggunakan komponen web HTML
gmp-map. - Menggunakan JavaScript.
Cuplikan kode di halaman ini dibuat menggunakan peta JavaScript.
Peta dapat dipusatkan pada lokasi yang Anda inginkan agar pengguna menelusuri di sekitarnya, seperti hotel, atau diinisialisasi untuk meminta lokasi pengguna saat ini guna memusatkan peta. Untuk tujuan dokumen ini, kita akan menggunakan lokasi tetap untuk menyematkan penelusuran.
Jika Anda memvisualisasikan tempat di sekitar lokasi tetap, seperti hotel, tempatkan penanda di peta untuk mewakili tempat ini. Contoh:
Peta berpusat di San Francisco, dengan pin biru untuk menunjukkan tempat yang kita telusuri di sekitar. Warna pin telah disesuaikan menggunakan
PinElement.
Kontrol Jenis Peta telah disembunyikan dari UI.
Menyiapkan Elemen Penelusuran Tempat
Sekarang, kita dapat menyiapkan HTML dan CSS untuk menampilkan Elemen Penelusuran Tempat. Untuk contoh ini, kita akan mengapungkan elemen di sisi kiri peta, tetapi sebaiknya coba tata letak yang berbeda agar sesuai dengan aplikasi Anda.
Elemen Penelusuran Tempat menggunakan pendekatan deklaratif. Daripada mengonfigurasinya
sepenuhnya di JavaScript, Anda menentukan jenis penelusuran langsung di HTML dengan
menyusun elemen permintaan, seperti <gmp-place-nearby-search-request>, di dalam
komponen <gmp-place-search> utama.
Dalam kode HTML Anda, lakukan inisialisasi elemen <gmp-place-search>. Gunakan atribut
selectable untuk mengaktifkan peristiwa klik pada hasil. Di dalamnya, tambahkan
<gmp-place-nearby-search-request> untuk menentukan bahwa elemen ini akan digunakan
untuk penelusuran di sekitar.
<gmp-place-search selectable>
<gmp-place-nearby-search-request>
</gmp-place-nearby-search-request>
</gmp-place-search>
Untuk melakukan penelusuran awal dan menampilkan hasil, kita akan menggunakan JavaScript untuk mendapatkan referensi ke elemen permintaan bertingkat dan menetapkan propertinya. Inisialisasi
Lingkaran untuk digunakan sebagai locationRestriction, menggunakan posisi penanda dari
langkah sebelumnya sebagai titik tengah. Kemudian, tetapkan properti locationRestriction dan
includedPrimaryTypes pada elemen permintaan untuk memicu penelusuran.
Cuplikan kode untuk ini adalah sebagai berikut:
// Get references to the Place Search and its nested request element
const placeSearchElement = document.querySelector("gmp-place-search");
const placeSearchRequestElement = document.querySelector("gmp-place-nearby-search-request");
// Define the location restriction for the search
const circleRestriction = new Circle({
center: marker.position,
radius: 500
});
// Set the properties on the request element to perform an initial search for restaurants.
placeSearchRequestElement.locationRestriction = circleRestriction;
placeSearchRequestElement.includedPrimaryTypes = ['restaurant'];
Contoh tampilan aplikasi pada tahap ini adalah sebagai berikut:
Izinkan pengguna melakukan penelusuran
Elemen Penelusuran Tempat memungkinkan dua opsi penelusuran:
<gmp-place-nearby-search-request>- merender hasil penelusuran dari Places Nearby Search, menggunakan Place Types.<gmp-place-text-search-request>- merender hasil penelusuran dari Places Text Search, menggunakan input teks bebas seperti "Sushi di Jakarta".
Ini adalah elemen bertingkat di dalam <gmp-place-search>. Kemudian, Anda memicu penelusuran
dengan menyetel properti pada elemen permintaan bertingkat tersebut menggunakan JavaScript.
Bagian ini menjelaskan cara menerapkan kedua metode tersebut.
Penelusuran di sekitar
Untuk mengizinkan pengguna melakukan penelusuran di sekitar, Anda memerlukan elemen UI terlebih dahulu agar mereka dapat memilih Jenis Tempat. Pilih metode pemilihan yang paling sesuai untuk aplikasi Anda, misalnya, daftar drop-down yang diisi dengan pilihan jenis tempat.
Sebaiknya pilih subset jenis yang relevan dengan kasus penggunaan Anda.
Misalnya, jika Anda mengembangkan aplikasi untuk menunjukkan kepada wisatawan apa yang ada di sekitar hotel, Anda dapat memilih: bakery, coffee_shop, museum, restaurant, dan tourist_attraction.
HTML Anda harus berisi elemen <gmp-place-search> dengan
<gmp-place-nearby-search-request> yang disarangkan di dalamnya.
<gmp-place-search selectable>
<gmp-place-nearby-search-request>
</gmp-place-nearby-search-request>
</gmp-place-search>
Selanjutnya, buat pemroses JavaScript untuk peristiwa change pada pemilih jenis tempat. Pemroses ini akan memanggil fungsi yang memperbarui properti elemen
<gmp-place-nearby-search-request>, yang secara otomatis memicu penelusuran
baru dan memperbarui daftar.
// Get a reference to the nested request element
const placeSearchRequestElement = document.querySelector('gmp-place-nearby-search-request');
// Function to update the place search based on the selected type
function updatePlaceList() {
const selectedType = placeTypeSelect.value;
if (!selectedType) {
// If no type is selected, don't perform a search.
// You could optionally hide the list or clear previous results here.
placeSearchElement.style.display = 'none';
return;
}
placeSearchElement.style.display = 'block';
// Set properties on the request element to trigger a new search
placeSearchRequestElement.locationRestriction = searchCircle;
placeSearchRequestElement.maxResultCount = 8;
placeSearchRequestElement.includedPrimaryTypes = [selectedType];
}
searchCircle yang sama dari langkah penyiapan digunakan untuk
locationRestriction. Properti includedPrimaryTypes ditetapkan ke nilai
dari pilihan pengguna. maxResultCount opsional juga ditetapkan untuk membatasi
jumlah hasil.
Penelusuran Teks
Untuk mengaktifkan penelusuran teks, konfigurasi HTML Anda harus diubah. Daripada permintaan penelusuran di sekitar, Anda menyusun elemen <gmp-place-text-search-request>.
<gmp-place-search selectable>
<gmp-place-text-search-request>
</gmp-place-text-search-request>
</gmp-place-search>
Tambahkan input teks dan tombol penelusuran ke UI Anda. Buat pemroses JavaScript
untuk peristiwa click tombol. Handler peristiwa akan mengambil input pengguna dan
memperbarui properti elemen <gmp-place-text-search-request> untuk
melakukan penelusuran.
// Get a reference to the text search request element
const placeTextSearchRequestElement = document.querySelector('gmp-place-text-search-request');
const textSearchInput = document.getElementById('textSearchInput');
const textSearchButton = document.getElementById('textSearchButton');
textSearchButton.addEventListener('click', performTextSearch);
function performTextSearch() {
const query = textSearchInput.value.trim();
if (!query) {
console.log("Search query is empty.");
return;
}
// Set properties on the request element to trigger a new search
placeTextSearchRequestElement.textQuery = query;
placeTextSearchRequestElement.locationBias = map.getBounds();
placeTextSearchRequestElement.maxResultCount = 8;
}
Di sini, kita menetapkan properti textQuery dengan input pengguna. Kami juga menyediakan
locationBias menggunakan batas peta saat ini, yang memberi tahu API untuk lebih memilih
hasil dalam area tersebut tanpa membatasinya secara ketat. maxResultCount opsional membatasi jumlah hasil yang ditampilkan.
Menampilkan Pin dan Detail Tempat
Sekarang aplikasi dapat melakukan penelusuran tempat dan mengisi elemen. Pada langkah berikutnya, kita akan meningkatkan fungsinya dengan:
- Menampilkan pin di peta untuk setiap tempat yang diisi di elemen Penelusuran Tempat.
- Memungkinkan pengguna mengklik pin atau tempat dalam Elemen Penelusuran Tempat, untuk menampilkan detail selengkapnya tentang tempat tertentu tersebut.
Prinsip langkah ini sama, baik aplikasi menggunakan penelusuran di sekitar atau penelusuran teks.
Pertama, tambahkan variabel global ke kode JavaScript Anda untuk menyimpan penanda tempat. Hal ini akan memungkinkan Anda menghapusnya saat penelusuran berubah dan menangani peristiwa klik.
let markers = {};
Buat fungsi untuk menambahkan penanda ke peta. Fungsi ini akan dipanggil setiap kali hasil penelusuran baru dimuat. API ini akan:
- Hapus semua penanda tempat yang ada dari peta.
- Lakukan loop pada hasil dari Elemen Penelusuran Tempat dan tambahkan penanda untuk setiap hasil.
- Sesuaikan batas peta sehingga semua penanda baru terlihat.
Untuk memproses saat hasil penelusuran tersedia, tambahkan pemroses peristiwa gmp-load
ke elemen <gmp-place-search>. Peristiwa ini dipicu setelah penelusuran selesai
dan hasilnya dirender.
Kita akan menambahkan pemroses di dalam fungsi penelusuran (misalnya, updatePlaceList), dan
gunakan opsi { once: true } untuk memastikan bahwa tag hanya diaktifkan untuk hasil
penelusuran saat ini.
// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });
Fungsi addMarkers akan terlihat seperti ini:
async function addMarkers() {
const { LatLngBounds } = await google.maps.importLibrary("core");
const bounds = new LatLngBounds();
if (placeSearchElement.places.length > 0) {
// Remove existing markers
for (const m in markers) {
markers[m].map = null;
}
markers = {};
// Loop through each place from the search results
// and add a marker for each one.
for (const place of placeSearchElement.places) {
const marker = new google.maps.marker.AdvancedMarkerElement({
map: map,
position: place.location,
});
markers[place.id] = marker;
bounds.extend(place.location);
marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;
// Add a click listener for each marker.
marker.addListener('gmp-click', (event) => {
// The main logic for showing details will go here.
});
}
// Position the map to display all markers.
map.setCenter(bounds.getCenter());
map.fitBounds(bounds);
}
}
Setelah langkah ini selesai, aplikasi akan terlihat seperti berikut, dengan kemampuan untuk menampilkan penanda untuk setiap tempat yang ditampilkan oleh Elemen Penelusuran Tempat:
Setelah memiliki penanda di peta, langkah terakhir adalah menangani peristiwa klik penanda dan elemen untuk menampilkan jendela info dengan detail tempat, yang disediakan oleh Elemen Detail Tempat. Untuk contoh ini, kita akan menggunakan Elemen Ringkas Detail Tempat.
Tambahkan HTML Elemen Ringkas Detail Tempat ke kode Anda, misalnya:
<gmp-place-details-compact orientation="vertical" style="display: none;">
<gmp-place-all-content></gmp-place-all-content>
<gmp-place-attribution light-scheme-color="gray" dark-scheme-color="white"></gmp-place-attribution>
</gmp-place-details-compact>
style disetel ke display: none; tidak akan terlihat hingga diperlukan.
gmp-place-all-content diteruskan untuk merender semua konten elemen. Untuk memilih konten yang akan dirender, lihat dokumentasi Elemen Ringkas Detail Tempat.
Buat variabel global di JavaScript untuk menyimpan referensi ke Elemen Ringkas Detail Tempat, dan isi variabel ini dalam kode inisialisasi Anda, misalnya:
let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');
Dalam fungsi addMarkers, tambahkan pemroses peristiwa gmp-click ke setiap penanda, dan konfigurasi Elemen Ringkas Detail Tempat untuk menampilkan detail tempat dengan meneruskan ID Tempat penanda saat ini.
Setelah selesai, Jendela Info akan dibuka untuk menampilkan Elemen Ringkas Detail Tempat, yang ditambatkan pada penanda.
Terakhir, peta diposisikan ke area tampilan tempat yang dipilih, sehingga terlihat.
async function addMarkers() {
...
marker.addListener('gmp-click', (event) => {
//Set up Place Details Compact Widget
placeDetailsElement.style.display = "block";
// Remove any existing place request element
const existingPlaceRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
if (existingPlaceRequest) {
existingPlaceRequest.remove();
}
// Create and configure the new place request element
const placeRequestElement = new google.maps.places.PlaceDetailsPlaceRequestElement({ place: place.id });
// Prepend the new place request element to the main widget
placeDetailsElement.prepend(placeRequestElement);
if (infoWindow.isOpen) {
infoWindow.close();
}
infoWindow.setOptions({
content: placeDetailsElement
});
infoWindow.open({
anchor: marker,
map: map
});
// Position the map to show the selected place
placeDetailsElement.addEventListener('gmp-load', () => {
map.fitBounds(place.viewport, { top: 500, left: 400 });
});
});
...
});
}
}
Untuk memungkinkan pengguna mengklik tempat di Elemen Daftar Tempat untuk menampilkan Elemen Ringkas Detail Tempat, tambahkan kode berikut ke kode JavaScript setelah panggilan ke configureFromSearchNearbyRequest.
placeSearchElement.addEventListener("gmp-select", ({ place }) => {
if (markers[place.id]) {
markers[place.id].click();
}
});
Setelah langkah ini selesai, aplikasi akan dapat menggunakan Penelusuran di Sekitar atau Penelusuran Teks untuk mengisi Elemen Daftar Tempat. Hasilnya akan menampilkan pin di peta, dan mengklik pin atau tempat di Elemen Daftar Tempat akan menampilkan Jendela Info dengan detail tempat, yang disediakan oleh Elemen Ringkas Detail Tempat.
Aplikasi akan terlihat seperti berikut:
Kesimpulan
Elemen Place Search yang dikombinasikan dengan Elemen Place Details Compact memberikan cara yang efisien untuk menambahkan fitur penemuan tempat yang lengkap ke aplikasi Google Maps Platform Anda.
Coba Places UI Kit hari ini untuk memungkinkan pengguna menemukan dan menjelajahi tempat menggunakan penelusuran terdekat & teks, serta menampilkan detail tempat yang lengkap, sehingga meningkatkan interaksi mereka dengan kasus penggunaan penemuan tempat Anda.
Kontributor
Henrik Valve | DevX Engineer