Penemuan tempat dengan PlaceSearchElement

Tujuan

Pelajari cara mengintegrasikan PlaceSearchElement dengan Google Maps untuk membantu pengguna menemukan tempat menggunakan Nearby Search atau Text Search, sehingga meningkatkan kemampuan mereka untuk menjelajahi lokasi menarik. Gunakan Elemen Ringkas Place Details untuk memberikan detail selengkapnya tentang tempat yang ditampilkan di aplikasi Anda.

Catatan: Panduan ini menjelaskan konsep inti. Untuk mempraktikkannya dengan implementasi yang lengkap dan terpandu, pelajari Codelab Membangun aplikasi penelusuran lokal dengan Kit UI Tempat.

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 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 Place Details.

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 dipusatkan pada lokasinya.

Kasus Penggunaan untuk Place Discovery

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 Estat: 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, pom bensin, atau pusat layanan tertentu.

Alur Kerja Solusi: Menerapkan Penemuan Tempat

Bagian ini akan memandu Anda mengintegrasikan PlaceSearchElement untuk menemukan tempat di peta, dan menyertakan cuplikan kode untuk berinteraksi dengan Kit UI Places. Pelajari cara melakukan inisialisasi peta dan menerapkan Nearby Search serta Text Search. Terakhir, gunakan elemen Place Details untuk menampilkan detail selengkapnya tentang suatu tempat saat pengguna mengklik pinnya di peta.

Prasyarat

Sebaiknya pahami dokumentasi berikut:

• PlaceSearchElement - Digunakan untuk menampilkan tempat menggunakan Nearby Search atau Text Search
• Elemen Place Details - Digunakan untuk menampilkan detail masing-masing tempat
• Maps JavaScript API - Digunakan untuk menampilkan peta di halaman Anda, dan untuk mengimpor Kit UI Places

Aktifkan Maps JavaScript API dan Kit UI Tempat 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.

Tips: Untuk contoh penggunaan PlaceSearchElement dengan peta komponen web HTML, lihat dokumentasi PlaceSearchElement.

Peta dapat dipusatkan pada lokasi yang Anda inginkan untuk ditelusuri pengguna, seperti hotel, atau diinisialisasi untuk meminta lokasi pengguna saat ini untuk 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 dipusatkan 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.

Siapkan PlaceSearchElement

Sekarang, siapkan HTML dan CSS untuk menampilkan PlaceSearchElement. Contoh ini mengambangkan elemen di atas 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 Nearby Search.

<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 Circle 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'];

Berikut adalah contoh tampilan aplikasi pada tahap ini:

Izinkan pengguna menelusuri

PlaceSearchElement memungkinkan dua opsi penelusuran:

• <gmp-place-nearby-search-request> - merender hasil penelusuran dari Places Nearby Search, menggunakan Jenis Tempat.
• <gmp-place-text-search-request> - merender hasil penelusuran dari Places Text Search, menggunakan input teks bebas seperti "Sushi di San Francisco".

Elemen 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 penerapan kedua metode tersebut.

Nearby Search

Agar pengguna dapat melakukan Nearby Search, Anda memerlukan elemen UI terlebih dahulu agar mereka dapat memilih Place Type. Pilih metode pemilihan yang paling sesuai untuk aplikasi Anda, misalnya, menu 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 saja 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> bertingkat 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 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. Sebagai ganti permintaan Nearby Search, Anda menyusun bertingkat 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. Pengendali 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.
• Memungkinkan pengguna mengklik pin atau tempat dalam PlaceSearchElement, untuk menampilkan detail selengkapnya tentang tempat tersebut.

Prinsip langkah ini sama, baik aplikasi menggunakan Nearby Search maupun Text Search.

Pertama, tambahkan variabel global ke kode JavaScript Anda untuk menyimpan penanda tempat. Tindakan 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. Tindakan ini akan:

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

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 Elemen Detail Tempat. Untuk contoh ini, kita akan menggunakan Elemen Ringkas Place Details.

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 sampai diperlukan. gmp-place-all-content diteruskan untuk merender semua konten elemen. Untuk memilih konten yang akan dirender, lihat dokumentasi Elemen Ringkas Place Details.

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 Place Details 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 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 });
                });
            });
          ...
        });
    }
}

Agar pengguna dapat 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 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

PlaceSearchElement yang digabungkan dengan Elemen Ringkas Place Details memberikan cara yang efisien untuk menambahkan fitur penemuan tempat yang lengkap ke aplikasi Google Maps Platform Anda.

Coba Kit UI Tempat sekarang untuk memberdayakan pengguna Anda dalam menemukan dan menjelajahi tempat menggunakan penelusuran di sekitar & Text Search, serta menampilkan Place Details yang lengkap, sehingga meningkatkan interaksi mereka dengan kasus penggunaan penemuan tempat Anda.

Kontributor

Henrik Valve | Engineer DevX