Tujuan
Pelajari cara mengintegrasikan Elemen Place Search 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 Place Details Compact untuk memberikan detail selengkapnya tentang tempat yang ditampilkan di aplikasi Anda.
Apa yang dimaksud dengan Elemen Place Search?
Elemen Place Search adalah bagian dari Places UI Kit di Maps JavaScript API. Elemen ini adalah elemen HTML yang merender hasil penelusuran tempat langsung dalam format daftar di dalam aplikasi Anda. Elemen ini menyederhanakan proses menampilkan tempat yang ditemukan menggunakan Nearby Search atau Text Search, sehingga memberikan pengalaman pengguna yang lancar untuk penemuan tempat. Saat pengguna memilih tempat dari daftar, Anda dapat menampilkan detailnya di peta, sering kali menggunakan Info Window dan Elemen Place Details.
Memvisualisasikan penemuan tempat
Gambar berikut menunjukkan contoh Elemen Place Search yang sedang digunakan. Di sebelah kiri, daftar restoran ditampilkan (Elemen Place Search). Saat restoran dipilih, detailnya akan muncul di Info Window pada peta, dan peta akan berpusat pada lokasinya.
Kasus Penggunaan untuk Penemuan Tempat
Mengintegrasikan Elemen Place Search 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 stasiun pengisian kendaraan listrik umum, stasiun pengisian bahan bakar, atau pusat layanan tertentu.
Alur Kerja Solusi: Menerapkan Penemuan Tempat
Bagian ini akan memandu Anda melalui langkah-langkah untuk mengintegrasikan Elemen Place Search guna menemukan tempat di peta, termasuk cuplikan kode untuk berinteraksi dengan Places UI Kit. Kita akan membahas cara menginisialisasi peta, dan menerapkan fungsi Nearby Search dan Text Search. 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 Place Search - Digunakan untuk menampilkan tempat menggunakan Nearby Search atau Text Search
- Elemen Place Details - Digunakan untuk menampilkan detail tempat tertentu
- 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 kerja 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 Place Search 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 ingin Anda telusuri oleh pengguna, seperti hotel, atau diinisialisasi untuk meminta lokasi pengguna saat ini guna memusatkan peta. Untuk tujuan dokumen ini, kita akan menggunakan lokasi tetap untuk menambatkan 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 mewakili tempat yang kita telusuri di sekitar. Warna pin telah disesuaikan menggunakan
PinElement.
Kontrol Jenis Peta telah disembunyikan
dari UI.
Menyiapkan Elemen Place Search
Sekarang, kita dapat menyiapkan HTML dan CSS untuk menampilkan Elemen Place Search. Untuk contoh ini, kita akan mengapungkan elemen di sisi kiri peta, tetapi sebaiknya coba tata letak yang berbeda agar sesuai dengan aplikasi Anda.
Elemen Place Search menggunakan pendekatan deklaratif. Daripada mengonfigurasinya
sepenuhnya di JavaScript, Anda menentukan jenis penelusuran langsung di HTML dengan
menyarangkan elemen permintaan, seperti <gmp-place-nearby-search-request>, di dalam
komponen <gmp-place-search> utama.
Dalam kode HTML Anda, 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 pusat. 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:
Mengizinkan pengguna menelusuri
Elemen Place Search 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 in San Francisco".
Ini adalah elemen bertingkat di dalam <gmp-place-search>. Kemudian, Anda memicu penelusuran dengan menetapkan 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 agar mereka dapat memilih Place Type. 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 tempat 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 Anda. 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 menyarangkan 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. Pemroses 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. Kita juga menyediakan locationBias menggunakan batas peta saat ini, yang memberi tahu API untuk memprioritaskan 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 Place Search.
- Mengizinkan pengguna mengklik pin atau tempat dalam Elemen Place Search, untuk menampilkan detail selengkapnya tentang tempat tertentu tersebut.
Prinsip langkah ini sama, baik aplikasi menggunakan penelusuran di sekitar maupun 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. Fungsi ini akan:
- Menghapus penanda tempat yang ada dari peta.
- Melakukan loop melalui hasil dari Elemen Place Search dan menambahkan penanda untuk setiap hasil.
- Menyesuaikan 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 menggunakan opsi { once: true } untuk memastikan pemroses hanya dipicu untuk hasil penelusuran saat ini.
// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });
Fungsi addMarkers 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 Place Search:
Setelah kita memiliki penanda di peta, langkah terakhir adalah menangani peristiwa klik penanda dan elemen untuk menampilkan jendela info dengan detail tempat, yang disediakan oleh Place Details Element. Untuk contoh ini, kita akan menggunakan Elemen Place Details Compact.
Tambahkan HTML Elemen Place Details Compact 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 ditetapkan ke display: none; elemen ini tidak akan terlihat hingga diperlukan.
gmp-place-all-content diteruskan untuk merender semua konten elemen. Untuk memilih konten yang akan dirender, lihat dokumentasi Elemen Place Details Compact.
Buat variabel global di JavaScript untuk menyimpan referensi ke Elemen Place Details Compact, 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 Place Details Compact untuk menampilkan detail tempat dengan meneruskan Place ID penanda saat ini.
Setelah selesai, Info Window akan dibuka untuk menampilkan Elemen Place Details Compact, yang ditambatkan pada penanda.
Terakhir, peta diposisikan ke area pandang 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 mengizinkan pengguna mengklik tempat di Elemen Place List untuk menampilkan Elemen Place Details Compact, 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 Nearby Search atau Text Search untuk mengisi Elemen Place List. Hasilnya akan menampilkan pin di peta, dan mengklik pin atau tempat di Elemen Place List akan menampilkan Info Window dengan detail tempat, yang disediakan oleh Elemen Place Details Compact.
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 di sekitar & teks serta menampilkan detail tempat yang lengkap, sehingga meningkatkan interaksi mereka dengan kasus penggunaan penemuan tempat Anda.
Kontributor
Henrik Valve | DevX Engineer