Menggunakan Kit UI Places untuk Pengguna Places API yang Ada

Sasaran: Mengganti penerapan Places API atau Place Class dengan Places UI Kit.

Sasaran panduan ini

Developer yang:

  • Membuat permintaan HTTP ke endpoint Places API (Baru atau Lama).
  • Menggunakan Class Place dalam Maps JavaScript API.
  • Menangani respons API untuk merender informasi tempat di UI aplikasi web mereka.

Prasyarat

Aktifkan Places UI Kit di Project Google Cloud Anda. Anda dapat terus menggunakan kunci API yang ada, atau membuat kunci API baru untuk Places UI Kit. Lihat Menggunakan Kunci API untuk mengetahui informasi selengkapnya, termasuk cara membatasi kunci.

Memperbarui Pemuatan Maps JavaScript API

Kit UI Places memerlukan metode pemuatan Maps JavaScript API Dynamic Library Import. Jika Anda menggunakan tag pemuatan skrip langsung, tag ini harus diperbarui.

Setelah memperbarui skrip pemuatan untuk Maps JavaScript API, impor library yang diperlukan untuk menggunakan Places UI Kit.

Menerapkan Elemen Place Details

Elemen Detail Tempat dan Elemen Ringkas Detail Tempat adalah elemen HTML yang merender detail untuk suatu tempat.

Implementasi Saat Ini

  • Anda melakukan panggilan Place Details menggunakan permintaan HTTP, atau menggunakan Class Place API JavaScript.
  • Anda mengurai respons API, dan menampilkan detail tempat menggunakan HTML dan CSS.

Migrasi ke Elemen Detail Tempat

Mengubah Struktur HTML

Identifikasi penampung HTML tempat detail tempat dirender. Ganti elemen HTML kustom Anda (div, span untuk nama, alamat, foto, dll.) dengan HTML Elemen Detail Tempat.

Ada dua elemen yang dapat dipilih:

  • Elemen Ringkas Place Details
  • Elemen Place Details

Untuk mengetahui informasi selengkapnya tentang mana yang harus digunakan, lihat Elemen Detail Tempat.

HTML yang ada mungkin terlihat seperti ini.

<div id="my-place-details-container">
    <h2 id="place-name"></h2>
    <p id="place-address"></p>
    <img id="place-photo" src="" alt="Place photo">
    <!-- ... more custom elements -->
</div>

Contoh HTML baru, yang secara eksplisit menyatakan konten yang akan ditampilkan:

<gmp-place-details-compact orientation="horizontal" truncation-preferred style="display: none;">
    <gmp-place-details-place-request></gmp-place-details-place-request>
    <gmp-place-content-config>
        <gmp-place-media lightbox-preferred></gmp-place-media>
        <gmp-place-address></gmp-place-address>
        <gmp-place-rating></gmp-place-rating>
        <gmp-place-type></gmp-place-type>
        <gmp-place-price></gmp-place-price>
        <gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
        <gmp-place-open-now-status></gmp-place-open-now-status>
    </gmp-place-content-config>
</gmp-place-details-compact>

Menyesuaikan Logika JavaScript

Logika yang ada

Logika yang ada kemungkinan melibatkan:

  • Mengambil ID Tempat.
  • Menggunakan PlacesService().getDetails() atau melakukan panggilan layanan web.
  • Menentukan array kolom (untuk JS API) atau FieldMask (untuk layanan web) untuk meminta data tertentu.
  • Dalam penyelesaian callback, memilih elemen HTML Anda secara manual dan mengisinya dengan data yang diterima.

Berikut adalah contoh cara Anda menerapkan Detail Tempat:

async function getPlaceDetails(placeId) {
    const { Place } = await google.maps.importLibrary('places');
    // Use place ID to create a new Place instance.
    const place = new Place({
        id: placeId
    });
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // Log the result
    console.log(place.displayName);
    console.log(place.formattedAddress);
}
Logika baru

Logika baru Anda akan melibatkan:

  • Ambil ID Tempat atau Objek Tempat Anda.
  • Dapatkan referensi ke elemen <gmp-place-details-place-request>.
  • Teruskan ID Tempat atau Objek Tempat ke properti tempat pada elemen <gmp-place-details-place-request>.

Berikut adalah contoh cara Anda dapat menerapkan kit UI Place Details dalam logika JavaScript Anda. Dapatkan referensi ke Elemen Detail Tempat. Jika elemen ini ada, dapatkan referensi ke elemen Place Request Place Details, dan tetapkan properti tempat menggunakan ID Tempat. Dalam contoh kode HTML di atas, gaya Elemen Detail Tempat ditetapkan ke display: none. Ini diperbarui menjadi display: block.

function displayPlaceDetailsWithUIKit(placeId) {
  const placeDetailsElement = document.querySelector('gmp-place-details-compact');
  if (placeDetailsElement) {
    const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
    // Configure the element with the Place ID
    placeDetailsRequest.place = placeId
    placeDetailsElement.style.display = 'block';
    console.log("PlaceDetailsElement configured for place:", placeId);
  } else {
    console.error("PlaceDetailsElement not found in the DOM.");
  }
}

// Example usage:
const placeId = 'ChIJC8HakaIRkFQRiOgkgdHmqkk';
displayPlaceDetailsWithUIKit(placeId);

Elemen Penelusuran Tempat adalah elemen HTML yang merender hasil penelusuran tempat dalam daftar.

  • Anda melakukan Penelusuran Teks atau Penelusuran Sekitar menggunakan permintaan HTTP, atau menggunakan Class Tempat JavaScript API.
  • Anda menentukan parameter kueri, pembatasan atau bias lokasi, jenis, dan kolom yang diminta menggunakan FieldMask.
  • Anda mengurai respons API, melakukan iterasi melalui array tempat, dan membuat item daftar HTML secara manual.

Mengubah Struktur HTML

Identifikasi penampung HTML tempat Anda merender daftar tempat. Ganti elemen HTML kustom Anda (div, span untuk nama, alamat, dll.) dengan elemen HTML Place Search.

HTML yang ada mungkin terlihat seperti ini:

<div id="search-results-area">
    <h3>Nearby Places:</h3>
    <ul id="manual-places-list">
        <!-- JavaScript would dynamically insert list items here -->
        <!-- Example of what JS might generate:
    <li class="place-entry" data-place-id="SOME_PLACE_ID_1">
      <img class="place-icon" src="icon_url_1.png" alt="Icon">
      <span class="place-name">Place Name One</span> -
      <span class="place-vicinity">123 Main St</span>
    </li>
    <li class="place-entry" data-place-id="SOME_PLACE_ID_2">
      <img class="place-icon" src="icon_url_2.png" alt="Icon">
      <span class="place-name">Place Name Two</span> -
      <span class="place-vicinity">456 Oak Ave</span>
    </li>
    -->
        <li class="loading-message">Loading places...</li>
    </ul>
</div>

Elemen Penelusuran Tempat diimplementasikan menggunakan komponen <gmp-place-search>. Untuk mengonfigurasi jenis penelusuran, sertakan salah satu komponen konfigurasi slot berikut di dalamnya:

  • <gmp-place-text-search-request> untuk Penelusuran Teks.
  • <gmp-place-nearby-search-request> untuk Nearby Search.

Untuk menentukan cara hasil ditampilkan, Anda dapat menggunakan pintasan <gmp-place-all-content>, atau memberikan kumpulan komponen presentasi individual Anda sendiri. Atribut utama seperti selectable (untuk mengizinkan klik pada item daftar) dan orientation (untuk tata letak horizontal atau vertikal) dapat ditetapkan langsung pada komponen induk.

Contoh Nearby Search
<gmp-place-search orientation="horizontal" selectable>
    <gmp-place-all-content> </gmp-place-all-content>
    <gmp-place-nearby-search-request></gmp-place-nearby-search-request>
</gmp-place-search>
Contoh Text Search
<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-all-content> </gmp-place-all-content>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Menyesuaikan Logika JavaScript

Di JavaScript Anda, dapatkan referensi ke komponen pengontrol penelusuran menggunakan document.querySelector(). Bergantung pada penyiapan Anda, elemen ini akan berupa <gmp-place-text-search-request> atau <gmp-place-nearby-search-request>.

Selanjutnya, tetapkan properti pada pengontrol ini untuk menentukan penelusuran Anda. Properti yang diperlukan bergantung pada jenis penelusuran yang Anda lakukan.

Untuk Penelusuran Teks (<gmp-place-text-search-request>), properti utamanya adalah textQuery:

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

Untuk Nearby Search (<gmp-place-nearby-search-request>), Anda harus menentukan area penelusuran menggunakan locationRestriction. Kemudian, Anda dapat menggunakan includedTypes untuk memfilter jenis tempat tertentu dalam area tersebut:

const nearbySearchController = document.querySelector('gmp-place-nearby-search-request');
nearbySearchController.locationRestriction = new google.maps.Circle({
    center: { lat: 51.5190, lng: -0.1347 },
    radius: 1000
});
nearbySearchController.includedTypes = ['restaurant'];

Komponen induk <gmp-place-search> secara otomatis memulai penelusuran baru segera setelah properti yang diperlukan pengontrolnya ditetapkan.

  • Untuk Penelusuran Teks, penelusuran akan berjalan saat Anda menetapkan nilai ke textQuery.
  • Untuk Penelusuran di Sekitar, penelusuran dijalankan setelah locationRestriction yang valid diberikan.

Menerapkan Elemen Place Autocomplete Dasar

Untuk developer yang memerlukan pengalaman penelusuran tanpa UI yang disediakan oleh Elemen Penelusuran Tempat, Elemen Basic Place Autocomplete tersedia.

Elemen ini ideal untuk membuat kolom input penelusuran sekaligus mempertahankan kontrol penuh atas cara hasil ditampilkan di antarmuka pengguna kustom Anda. Satu-satunya tanggung jawab Elemen Pelengkapan Otomatis adalah memberikan prediksi tempat saat pengguna mengetik dan mengekspos ID Tempat secara terprogram untuk tempat yang dipilih.

Objek ini tidak menampilkan detail apa pun atau memberikan informasi lain yang dapat diakses secara terprogram.

Implementasi Saat Ini

Logika yang ada kemungkinan melibatkan:

  • Merender kolom input teks di halaman Anda yang memanggil Place Autocomplete saat pengguna mengetik, menampilkan hasil.
  • Menggunakan ID Tempat dari tempat yang dipilih pengguna untuk mengambil detail selengkapnya, misalnya menggunakan Place Details API.
  • Menampilkan detail tempat yang dipilih.

Migrasi ke Elemen Place Autocomplete

Mengubah Struktur HTML

Identifikasi dan hapus elemen HTML yang Anda lampirkan ke widget Pelengkapan Otomatis. Kemungkinan menggunakan kolom input HTML standar.

<input id="pac-input" type="text" placeholder="Search for a location" />

Contoh HTML baru, menggunakan pendekatan komponen web untuk menginisialisasi elemen Basic Place Autocomplete di halaman Anda.

<gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>

Menyesuaikan Logika JavaScript

Logika JavaScript Anda kemungkinan melibatkan pembuatan widget Pelengkapan Otomatis yang terlampir ke elemen HTML input. Kemudian, widget ini memproses peristiwa place_changed , yang memicu tindakan dengan data yang ditampilkan.

Contoh JavaScript yang ada untuk dihapus:

// Get the input element
const input = document.getElementById("pac-input");

// Create the Autocomplete widget instance
const autocomplete = new google.maps.places.Autocomplete(input, {
  fields: ["place_id", "geometry", "name"]
});

// Add a listener for the 'place_changed' event
autocomplete.addListener("place_changed", () => {
  // Your logic to get and display place information
  console.log(place.place_id);
});

Logika JavaScript baru Anda akan mendapatkan referensi ke Elemen Pelengkapan Otomatis Tempat Dasar, dan memproses peristiwa gmp-select:

const placeAutocomplete = document.querySelector('gmp-basic-place-autocomplete');

placeAutocomplete.addEventListener('gmp-select', (event) => {
  console.log(event.place);
});

Saat tempat dipilih di menu drop-down Pelengkapan otomatis, peristiwa gmp-select akan diaktifkan. ID Tempat dari tempat yang dipilih dapat diambil dari objek event. ID Tempat kemudian dapat digunakan untuk menginisialisasi instance Elemen Detail Tempat, untuk menampilkan detail tempat yang dipilih.

Penyesuaian Gagang

Penyesuaian Elemen Place Details

Orientasi

Elemen Detail Tempat dapat dirender dalam orientasi Horizontal dan Vertikal. Gunakan atribut orientation pada gmp-place-details-compact untuk memilih antara vertikal dan horizontal. Contoh:

<gmp-place-details-compact orientation="vertical">

Memilih kolom yang akan dirender

Gunakan elemen konten untuk menentukan konten yang akan dirender dalam Elemen Detail Tempat. Misalnya, mengecualikan elemen konten <gmp-place-type> akan menghentikan Elemen Detail Tempat merender Jenis Tempat dari tempat yang dipilih. Untuk mengetahui daftar lengkap elemen konten, lihat dokumentasi referensi PlaceContentConfigElement.

Menambahkan atau menghapus kolom dari Elemen Detail Tempat tidak mengubah biaya rendering elemen di halaman.

Menetapkan Gaya CSS

Properti CSS kustom tersedia untuk mengonfigurasi warna dan font elemen. Misalnya, untuk menyetel latar belakang elemen menjadi hijau, tetapkan properti CSS berikut:

gmp-place-details-compact {
  --gmp-mat-color-surface: green;
}

Lihat dokumentasi referensi untuk PlaceDetailsCompactElement untuk mengetahui detail selengkapnya.

Penyesuaian Elemen Penelusuran Tempat

Orientasi

Elemen Penelusuran Tempat dapat dirender dalam orientasi Horizontal dan Vertikal. Gunakan atribut orientation pada <gmp-place-search> untuk memilih antara vertikal dan horizontal. Contoh:

<gmp-place-search orientation="horizontal" selectable>

Memilih kolom yang akan dirender

Gunakan elemen konten untuk menentukan konten yang akan dirender dalam Elemen Penelusuran Tempat. Elemen <gmp-place-all-content> dapat digunakan untuk menampilkan semua konten, atau pilihan tag HTML dapat digunakan untuk mengonfigurasi konten yang dirender.

Menyertakan <gmp-place-address> dalam <gmp-place-content-config> hanya akan merender alamat untuk setiap tempat, misalnya:

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-content-config>
    <gmp-place-address></gmp-place-address>
  </gmp-place-content-config>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Penyesuaian Elemen Place Autocomplete Dasar

Menetapkan Gaya CSS

Properti CSS kustom tersedia untuk menyesuaikan tampilan dan nuansa elemen Pelengkapan Otomatis. Misalnya, untuk menyetel warna latar belakang menjadi ungu muda, Anda harus menyetel properti background-color pada elemen.

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

Lihat dokumentasi referensi BasicPlaceAutocompleteElement untuk mengetahui detail selengkapnya.

Menangani peristiwa & data

Elemen Kit UI Places adalah komponen interaktif yang memungkinkan Anda memproses peristiwa dan mengambil data secara terprogram.

Memproses Peristiwa

Anda dapat menambahkan pemroses peristiwa ke elemen untuk memicu tindakan berdasarkan interaksi pengguna atau status elemen.

Peristiwa Pemilihan

  • gmp-select: Peristiwa ini diaktifkan saat pengguna membuat pilihan.
    • Di Elemen Penelusuran Tempat, peristiwa ini dipicu saat pengguna mengklik tempat dalam daftar hasil.
    • Pada Elemen Pelengkapan Otomatis Tempat Dasar, peristiwa ini dipicu saat pengguna mengklik prediksi dalam daftar drop-down.

Peristiwa Umum

Elemen Place Search, Place Details, dan Basic Place Autocomplete semuanya mendukung peristiwa berikut:

  • gmp-load: Diaktifkan saat elemen dan kontennya telah selesai dimuat dan dirender.
  • gmp-requesterror: Diaktifkan saat permintaan ke server gagal, misalnya, karena kunci API tidak valid.

Mengakses Data Elemen Secara Terprogram

Anda dapat mengambil data tertentu secara terprogram dari elemen setelah elemen tersebut berinteraksi atau dimuat.

  • Untuk Elemen Place Search dan Elemen Place Details, Anda dapat mengambil informasi berikut:
    • ID tempat
    • Lokasi (Lintang & Bujur)
    • Area Pandang
  • Untuk Elemen Place Autocomplete Dasar, Anda dapat mengambil informasi berikut:
    • ID tempat

Semua data lain yang ada dalam elemen tidak dapat diakses secara terprogram.

Untuk contoh yang lebih mendetail, lihat dokumentasi masing-masing untuk Elemen Place Search, Elemen Place Details, dan Elemen Place Autocomplete Dasar.

Pengujian dan Penyempurnaan

Setelah Anda mengintegrasikan elemen Places UI Kit, pengujian sangat penting untuk transisi yang lancar dan pengalaman pengguna yang positif. Pengujian Anda harus mencakup beberapa area utama, yang mencakup semua elemen yang telah Anda terapkan: elemen Place Details, Place Search, dan Place Autocomplete Dasar.

Elemen Detail Tempat

Untuk Elemen Detail Tempat, mulailah dengan memverifikasi bahwa detail ditampilkan dengan benar untuk berbagai tempat. Uji dengan meneruskan berbagai ID Tempat ke properti .place elemen <gmp-place-details-place-request>. Gunakan ID yang mewakili berbagai jenis tempat (bisnis dengan data lengkap, tempat menarik, alamat dasar) dan tempat di berbagai wilayah atau bahasa. Perhatikan baik-baik pemformatan, tata letak, dan kehadiran konten.

Elemen Penelusuran Tempat

Jika Anda telah menerapkan Elemen Penelusuran Tempat, verifikasi rendering dan perilakunya dalam berbagai skenario penelusuran.

  • Untuk Penelusuran Teks, lakukan pengujian dengan menyetel properti textQuery pada elemen <gmp-place-text-search-request> dengan berbagai input: kueri luas, alamat tertentu, dan kueri dengan bias lokasi.
  • Untuk Nearby Search, uji dengan menyetel properti locationRestriction dan includedTypes pada elemen <gmp-place-nearby-search-request>. Gunakan ukuran lokasi dan filter jenis yang berbeda.

Konfirmasi bahwa daftar diisi dengan hasil yang relevan dan bahwa peristiwa gmp-select diaktifkan dengan benar saat dipilih.

Elemen Place Autocomplete Dasar

Untuk Elemen Pelengkapan Otomatis Tempat Dasar, fokuskan pengujian pada interaksi pengguna dan data yang diteruskan oleh peristiwa pemilihan. Konfirmasi bahwa peristiwa gmp-select dipicu dengan andal saat pengguna mengklik prediksi. Pastikan objek event.place di pengendali peristiwa berisi ID Tempat yang valid.

Yang terpenting, uji alur end-to-end: pilih tempat dari drop-down Autocomplete dan verifikasi bahwa ID Tempatnya dapat berhasil digunakan untuk mengisi elemen lain, seperti Elemen Place Details.

Penanganan error

Pengujian penanganan error yang ketat sangat penting di semua komponen. Simulasikan penerusan ID Tempat yang tidak valid atau tidak ada ke Elemen Place Details, atau penggunaan parameter penelusuran yang tidak valid untuk Elemen Place Search. Aktifkan peristiwa gmp-requesterror dengan menyimulasikan masalah jaringan atau menggunakan kunci API yang tidak valid untuk memastikan aplikasi Anda menanganinya dengan baik. Terapkan pesan error dan logging yang mudah digunakan untuk mencegah UI yang rusak atau membingungkan.