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);
Menerapkan Elemen Place Search
Elemen Penelusuran Tempat adalah elemen HTML yang merender hasil penelusuran tempat dalam daftar.
Implementasi Saat Ini
- 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.
Migrasi ke Elemen Penelusuran Tempat
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
danincludedTypes
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.