Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Menggunakan Kit UI Places untuk Pengguna Places API yang Ada

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

Sasaran panduan ini

Panduan ini ditujukan untuk developer yang memiliki penerapan yang ada menggunakan Places API dan tertarik untuk memperbarui kode mereka agar menggunakan Places UI Kit. Panduan ini 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 baru untuk Places UI Kit. Lihat Menggunakan Kunci API untuk mengetahui informasi selengkapnya, termasuk membatasi kunci.

Memperbarui Pemuatan Maps JavaScript API

Places UI Kit memerlukan metode Impor Library Dinamis 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 Element dan Place Details Compact Element adalah elemen HTML yang merender detail untuk suatu tempat.

Implementasi 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 Place Details Compact
Elemen Place Details

Untuk mengetahui informasi selengkapnya tentang elemen mana yang akan digunakan, lihat Place Details Element.

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

Mengadaptasi Logika JavaScript

Logika yang ada

Logika Anda 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, memilih elemen HTML Anda secara manual dan mengisinya dengan data yang diterima.

Berikut adalah contoh cara Anda mengimplementasikan 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);
}

Logika baru

Logika baru Anda akan melibatkan:

Mengambil ID Tempat atau Objek Tempat.
Mendapatkan referensi ke elemen <gmp-place-details-place-request>.
Meneruskan ID Tempat atau Objek Tempat ke properti tempat pada elemen <gmp-place-details-place-request>.

Berikut adalah contoh cara Anda dapat mengimplementasikan Places UI Kit dalam logika JavaScript. Dapatkan referensi ke Elemen Place Details. Jika ada, dapatkan referensi ke elemen Place Details Place Request, dan tetapkan properti tempat menggunakan ID Tempat. Dalam contoh kode HTML di atas, gaya Elemen Place Details ditetapkan ke display: none. Gaya ini diperbarui ke 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 Element adalah elemen HTML yang merender hasil penelusuran tempat dalam daftar.

Implementasi Saat Ini

Anda melakukan Text Search atau Nearby Search menggunakan permintaan HTTP, atau menggunakan Class Place JavaScript API.
Anda menentukan parameter kueri, batasan 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 Anda 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 <gmp-place-search> komponen. Untuk mengonfigurasi jenis penelusuran, sertakan salah satu komponen konfigurasi yang ditempatkan di dalam berikut:

<gmp-place-text-search-request> untuk Text Search.
<gmp-place-nearby-search-request> untuk Nearby Search.

Untuk menentukan cara hasil ditampilkan, Anda dapat menggunakan <gmp-place-all-content> pintasan, atau menyediakan 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>

Mengadaptasi 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 induk <gmp-place-search> akan otomatis memulai penelusuran baru segera setelah properti pengontrolnya yang diperlukan ditetapkan.

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

Mengimplementasikan Elemen Place Autocomplete Dasar

Untuk developer yang memerlukan pengalaman penelusuran tanpa UI yang disediakan oleh Elemen Place Search, Elemen Basic Place Autocomplete Dasar 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 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.

Implementasi Saat Ini

Logika Anda 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 Autocomplete. 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 Place Autocomplete Dasar di halaman Anda.

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

Mengadaptasi 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 dropdown Autocomplete, 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 Place Details, guna menampilkan detail tempat yang dipilih.

Menangani Penyesuaian

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 place. Untuk mengetahui daftar lengkap elemen konten, lihat PlaceContentConfigElement dokumentasi referensi.

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 menetapkan latar belakang elemen menjadi hijau, tetapkan properti CSS berikut:

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

Lihat dokumentasi referensi untuk PlaceDetailsCompactElement guna 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 Place Search. Elemen <gmp-place-all-content> dapat digunakan untuk menampilkan semua konten, atau pilihan tag html dapat digunakan untuk mengonfigurasi konten yang dirender konten.

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 menetapkan warna latar belakang menjadi ungu muda, Anda akan menetapkan properti background-color pada elemen.

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

Lihat BasicPlaceAutocompleteElement untuk mengetahui detail selengkapnya.

Menangani peristiwa &data

Elemen Places UI Kit 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 melakukan pemilihan.
- Di Elemen Place Search, peristiwa ini dipicu saat pengguna mengklik tempat dalam daftar hasil.
- Di Elemen Place Autocomplete Dasar, peristiwa ini dipicu saat pengguna mengklik prediksi dalam daftar dropdown.

Peristiwa Umum

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

gmp-load: Diaktifkan saat elemen dan kontennya 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 dari elemen secara terprogram 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 individual untuk Elemen Place Search, Elemen Place Details, dan Elemen Place Autocomplete Dasar.

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 membahas semua elemen yang telah Anda implementasikan: elemen Place Details, Place Search, dan Place Autocomplete Dasar.

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 tempat (bisnis dengan data lengkap, tempat menarik, alamat dasar) dan tempat di berbagai wilayah atau bahasa. Perhatikan dengan cermat format, tata letak, dan keberadaan konten.

Elemen Place Search

Jika Anda telah mengimplementasikan 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 tertentu, dan kueri dengan bias lokasi.
Untuk Nearby Search, uji dengan menetapkan properti locationRestriction dan includedTypes pada elemen <gmp-place-nearby-search-request>. Gunakan ukuran lokasi dan filter jenis yang berbeda.

Pastikan daftar diisi dengan hasil yang relevan dan peristiwa gmp-select diaktifkan dengan benar saat pemilihan.

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. Verifikasi bahwa objek event.place di pengendali peristiwa berisi ID Tempat yang valid.

Yang terpenting, uji alur end-to-end: pilih tempat dari dropdown 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. Implementasikan pesan error dan logging yang mudah digunakan untuk mencegah UI yang rusak atau membingungkan.

Menggunakan Kit UI Places untuk Pengguna Places API yang Ada Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sasaran panduan ini

Prasyarat

Memperbarui Pemuatan Maps JavaScript API

Mengimplementasikan Elemen Place Details

Implementasi Saat Ini

Migrasi ke Elemen Place Details

Mengubah Struktur HTML

Mengadaptasi Logika JavaScript

Logika yang ada

Logika baru

Mengimplementasikan Elemen Place Search

Implementasi Saat Ini

Migrasi ke Elemen Place Search

Mengubah Struktur HTML

Contoh Nearby Search

Contoh Text Search

Mengadaptasi Logika JavaScript

Mengimplementasikan Elemen Place Autocomplete Dasar

Implementasi Saat Ini

Migrasi ke Elemen Place Autocomplete

Mengubah Struktur HTML

Mengadaptasi Logika JavaScript

Menangani Penyesuaian

Penyesuaian Elemen Place Details

Orientasi

Memilih kolom yang akan dirender

Menetapkan Gaya CSS

Penyesuaian Elemen Place Search

Orientasi

Memilih kolom yang akan dirender

Penyesuaian Elemen Place Autocomplete Dasar

Menetapkan Gaya CSS

Menangani peristiwa &data

Memproses Peristiwa

Peristiwa Pemilihan

Peristiwa Umum

Mengakses Data Elemen Secara Terprogram

Pengujian dan Penyempurnaan

Menggunakan Kit UI Places untuk Pengguna Places API yang Ada