Menggunakan Kit UI Places untuk Pengguna Places API yang Ada

Pelajari cara memigrasikan penerapan Places API atau Class Place yang ada ke komponen Kit UI Places.

Sasaran panduan ini

Panduan ini ditujukan bagi developer yang sudah memiliki implementasi menggunakan Places API dan tertarik untuk memperbarui kode mereka agar menggunakan Places UI Kit. Akan sangat membantu jika Anda sudah:

• 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 Anda.

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 membatasi kunci.

Memperbarui Pemuatan Maps JavaScript API

Kit UI Places memerlukan metode Dynamic Library Import untuk memuat Maps JavaScript API. 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.

Mengimplementasikan Elemen Place Details

Elemen Place Details dan Elemen Place Details Compact adalah elemen HTML yang merender detail untuk suatu tempat.

Penerapan Saat Ini

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

Migrasi ke Elemen Place Details

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

Ada dua elemen yang dapat dipilih:

• Elemen Ringkas Place Details
• Elemen Place Details

Untuk informasi selengkapnya tentang elemen yang akan digunakan, lihat Elemen Place Details.

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 resolusi callback, pilih elemen HTML secara manual dan isi dengan data yang diterima.

Berikut adalah contoh cara Anda menerapkan Place Details:

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);
}

Catatan: Logika Anda mungkin terlihat berbeda jika Anda menggunakan panggilan REST API, atau library JavaScript lama.

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 di elemen <gmp-place-details-place-request>.

Berikut adalah contoh cara menerapkan kit UI Place Details dalam logika JavaScript Anda. Dapatkan referensi ke Elemen Place Details. Jika ada, dapatkan referensi ke elemen Place Request Place Details, dan tetapkan properti tempat menggunakan ID Tempat. Dalam contoh kode HTML di atas, gaya Elemen Place Details ditetapkan ke display: none. Nilai 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);

Mengimplementasikan Elemen Place Search

Elemen Place Search adalah elemen HTML yang merender hasil penelusuran tempat dalam daftar.

Penerapan Saat Ini

• Anda melakukan Text Search atau Nearby Search menggunakan permintaan HTTP, atau menggunakan Class Place 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.

Migrasi ke Elemen Place Search

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 Elemen 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 Place Search 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 Text Search.
• <gmp-place-nearby-search-request> untuk Nearby Search.

Untuk menentukan cara hasil ditampilkan, Anda dapat menggunakan pintasan <gmp-place-all-content>, atau menyediakan kumpulan komponen presentasi individual Anda sendiri. Atribut kunci 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, dapatkan referensi ke komponen pengontrol penelusuran menggunakan document.querySelector(). Bergantung pada penyiapan Anda, ini akan menjadi elemen <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 Text Search (<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 <gmp-place-search> induk otomatis memulai penelusuran baru segera setelah properti yang diperlukan pengontrolnya ditetapkan.

• Untuk Text Search, penelusuran akan berjalan saat Anda menetapkan nilai ke textQuery.
• Untuk Nearby Search, penelusuran akan berjalan setelah locationRestriction yang valid diberikan.

Menerapkan Elemen Place Autocomplete Dasar

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

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 Autocomplete adalah memberikan prediksi tempat saat pengguna mengetik dan mengekspos ID Tempat secara terprogram untuk tempat yang dipilih.

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

Penerapan Saat Ini

Logika yang ada kemungkinan melibatkan:

• Merender kolom input teks di halaman Anda yang memanggil Place Autocomplete saat pengguna mengetik, yang 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 tempat Anda melampirkan widget Autocomplete. Kemungkinan besar, kolom tersebut menggunakan kolom input HTML standar.

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

Contoh HTML baru, menggunakan pendekatan komponen web untuk melakukan inisialisasi elemen Autocomplete Place Dasar di halaman Anda.

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

Menyesuaikan Logika JavaScript

Logika JavaScript Anda kemungkinan melibatkan pembuatan widget Autocomplete yang dilampirkan ke elemen HTML input. Widget ini kemudian 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 Place Autocomplete Dasar, dan memproses peristiwa gmp-select:

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

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

Saat memilih tempat di menu drop-down Autocomplete, peristiwa gmp-select akan diaktifkan. ID Tempat dari tempat yang dipilih dapat diambil dari objek event. ID Tempat kemudian dapat digunakan untuk melakukan inisialisasi instance Elemen Place Details, untuk menampilkan detail tempat yang dipilih.

Penyesuaian Nama Sebutan Channel

Tips: Untuk panduan mendetail tentang cara menyesuaikan tampilan dan nuansa, termasuk alat penataan gaya langsung dan persyaratan atribusi, lihat dokumentasi Penataan Gaya Kustom Kit UI Tempat.

Penyesuaian Elemen Place Details

Orientasi

Elemen Place Details dapat dirender dalam orientasi Horizontal dan Vertikal. Gunakan atribut orientation di 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 Place Details. Misalnya, mengecualikan elemen konten <gmp-place-type> akan menghentikan Elemen Place Details merender Jenis Tempat dari tempat yang dipilih. Untuk mengetahui daftar lengkap elemen konten, lihat dokumentasi referensi PlaceContentConfigElement.

Menambahkan atau menghapus kolom dari Elemen Place Details 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, setel properti CSS berikut:

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

Lihat dokumentasi referensi untuk PlaceDetailsCompactElement untuk mengetahui detail selengkapnya.

Penyesuaian Elemen Place Search

Orientasi

Elemen Place Search dapat dirender dalam orientasi Horizontal dan Vertikal. Gunakan atribut orientation di <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 Autocomplete. Misalnya, untuk menyetel warna latar belakang menjadi ungu muda, Anda harus menyetel properti background-color pada elemen.

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

Baca 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.
  • Pada Elemen Place Search, peristiwa ini dipicu saat pengguna mengklik tempat dalam daftar hasil.
  • Di Elemen Autocomplete Place Dasar, peristiwa ini dipicu saat pengguna mengklik prediksi dalam menu 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 Tampilan
• Untuk Elemen Place Autocomplete Dasar, Anda dapat mengambil informasi berikut:
  • ID tempat

Semua data lain yang terdapat 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 Kit UI Tempat, pengujian sangat penting untuk transisi yang lancar dan pengalaman pengguna yang positif. Pengujian Anda harus mencakup beberapa area utama, yang menangani semua elemen yang telah Anda terapkan: elemen Place Details, Place Search, dan Basic Place Autocomplete.

Elemen Place Details

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

Elemen Place Search

Jika Anda telah menerapkan Elemen Place Search, verifikasi rendering dan perilakunya dalam berbagai skenario penelusuran.

• Untuk Text Search, uji dengan menetapkan properti textQuery pada elemen <gmp-place-text-search-request> dengan berbagai input: kueri luas, alamat spesifik, dan kueri dengan bias lokasi.
• Untuk Nearby Search, uji dengan menetapkan properti locationRestriction dan includedTypes pada elemen <gmp-place-nearby-search-request>. Gunakan berbagai ukuran lokasi dan filter jenis.

Pastikan daftar diisi dengan hasil yang relevan dan peristiwa gmp-select diaktifkan dengan benar setelah dipilih.

Elemen Place Autocomplete Dasar

Untuk Elemen Place Autocomplete Dasar, fokuskan pengujian pada interaksi pengguna dan data yang diteruskan oleh peristiwa pemilihan. Pastikan peristiwa gmp-select diaktifkan dengan andal saat pengguna mengklik prediksi. Pastikan objek event.place dalam pengendali peristiwa berisi ID Tempat yang valid.

Yang terpenting, uji alur menyeluruh: 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. Picu 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.