Penemuan tempat dengan PlaceSearchElement

Tujuan

Pelajari cara mengintegrasikan PlaceSearchElement dengan Google Maps untuk membantu pengguna menemukan tempat menggunakan penelusuran terdekat 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 PlaceSearchElement?

PlaceSearchElement adalah bagian dari Places UI Kit 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 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 Jendela Info dan Elemen Detail Tempat.

Memvisualisasikan penemuan tempat

Gambar berikut menunjukkan contoh cara kerja PlaceSearchElement. Di sebelah kiri, daftar restoran ditampilkan (PlaceSearchElement). Saat restoran dipilih, detailnya akan muncul di Jendela Info pada peta, dan peta akan berpusat pada lokasinya.

gambar

Kasus Penggunaan untuk Penemuan Tempat

Mengintegrasikan PlaceSearchElement dapat meningkatkan 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 mengintegrasikan PlaceSearchElement untuk menemukan tempat di peta, dan menyertakan cuplikan kode untuk berinteraksi dengan Places UI Kit. Pelajari cara menginisialisasi peta dan menerapkan Nearby Search dan Text Search. Terakhir, gunakan elemen Detail Tempat untuk menampilkan detail selengkapnya tentang suatu tempat saat pengguna mengklik pinnya di peta.

Prasyarat

Sebaiknya Anda memahami dokumentasi berikut:

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 PlaceSearchElement sebagai pin yang dapat dipilih.

Ada dua cara untuk menambahkan peta ke halaman:

  1. Menggunakan komponen web HTML gmp-map.
  2. 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:

gambar

Peta dipusatkan di San Francisco, dengan pin biru untuk merepresentasikan tempat yang kita cari di sekitar. Warna pin telah disesuaikan menggunakan PinElement. Kontrol Jenis Peta telah disembunyikan dari UI.

Siapkan PlaceSearchElement

Sekarang, siapkan HTML dan CSS untuk menampilkan PlaceSearchElement. Contoh ini mengambangkan elemen di sisi kiri peta, tetapi Anda dapat mencoba tata letak yang berbeda agar sesuai dengan aplikasi Anda.

PlaceSearchElement 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. Lakukan 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:

gambar

PlaceSearchElement 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.

gambar

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 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

gambar

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 PlaceSearchElement.
  • Mengizinkan pengguna mengklik pin atau tempat dalam PlaceSearchElement, 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. Hal ini akan:

  • Hapus semua penanda tempat yang ada dari peta.
  • Lakukan loop pada hasil dari PlaceSearchElement dan tambahkan penanda untuk setiap hasil.
  • Sesuaikan batas peta agar 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 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 PlaceSearchElement:

gambar

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 Place Details 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; 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 Place Details, 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 konfigurasikan Elemen Ringkas Detail Tempat untuk menampilkan detail tempat dengan meneruskan ID Tempat penanda saat ini.

Setelah selesai, Jendela Info akan terbuka 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 Nearby Search atau Text Search untuk mengisi Place List Element. 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:

gambar

Kesimpulan

PlaceSearchElement yang dikombinasikan dengan Elemen Ringkas Detail Tempat 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