Mevcut Places API Kullanıcıları için Places UI Kit'i kullanmaya başlama

Mevcut Places API veya Place sınıfı uygulamanızı Places UI Kit bileşenlerine nasıl taşıyacağınızı öğrenin.

Bu kılavuz kimlere yöneliktir?

Bu kılavuz, Places API'yi kullanan mevcut bir uygulaması olan ve kodunu Places UI Kit'i kullanacak şekilde güncellemek isteyen geliştiriciler için hazırlanmıştır. Bu kılavuz, aşağıdaki durumlarda en faydalı olacaktır:

  • Places API (yeni veya eski) uç noktalarına HTTP istekleri gönderme
  • Maps JavaScript API'de Place sınıfını kullanma
  • Web uygulamanızın kullanıcı arayüzünde yer bilgilerini oluşturmak için API yanıtını işleme

Ön koşullar

Google Cloud projenizde Places UI Kit'i etkinleştirin. Mevcut API anahtarınızı kullanmaya devam edebilir veya Places UI Kit için yeni bir anahtar oluşturabilirsiniz. Bir anahtarı kısıtlama da dahil olmak üzere daha fazla bilgi için API Anahtarlarını Kullanma başlıklı makaleyi inceleyin.

Maps JavaScript API yüklemesini güncelleme

Places UI Kit, Maps JavaScript API'yi yüklemek için Dinamik Kitaplık İçe Aktarma yöntemini kullanır. Doğrudan komut dosyası yükleme etiketini kullanıyorsanız bu etiketin güncellenmesi gerekir.

Maps JavaScript API için yükleme komut dosyasını güncelledikten sonra Places UI Kit'i kullanmak için gerekli kitaplıkları içe aktarın.

Yer Ayrıntıları öğesini uygulama

Place Details Element ve Place Details Compact Element, bir yerle ilgili ayrıntıları gösteren HTML öğeleridir.

Mevcut Uygulama

  • HTTP isteği kullanarak Yer Ayrıntıları çağrısı yapabilir veya JavaScript API Place sınıfını kullanabilirsiniz.
  • API yanıtını ayrıştırır ve yer ayrıntılarını HTML ve CSS kullanarak gösterirsiniz.

Yer Ayrıntıları Öğesine Geçiş

HTML yapısını değiştirme

Yer ayrıntılarının oluşturulduğu HTML kapsayıcısını tanımlayın. Özel HTML öğelerinizi (ad, adres, fotoğraflar vb. için div'ler, span'ler) Yer Ayrıntıları öğesi HTML'si ile değiştirin.

Seçebileceğiniz iki öğe vardır:

  • Yer Ayrıntıları Kompakt Öğesi
  • Yer Ayrıntıları Öğesi

Hangisini kullanacağınız hakkında daha fazla bilgi için Place Details Element (Yer Ayrıntıları Öğesi) başlıklı makaleyi inceleyin.

Mevcut HTML'niz aşağıdaki gibi görünebilir.

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

Hangi içeriğin gösterileceğini açıkça belirten yeni HTML örneği:

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

JavaScript Mantığını Uyarlama

Mevcut mantık

Mevcut mantığınız muhtemelen şunları içerir:

  • Yer kimliği alma
  • PlacesService().getDetails() kullanarak veya web hizmeti çağrısı yaparak.
  • Belirli verileri istemek için bir alan dizisi (JS API için) veya FieldMask (web hizmeti için) belirtme.
  • Geri çağırma çözümünde, HTML öğelerinizi manuel olarak seçip alınan verilerle doldurma.

Aşağıda, Yer Ayrıntıları'nı nasıl uygulayabileceğinize dair bir örnek verilmiştir:

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);
}
Yeni mantık

Yeni mantığınız şunları içerecek:

  • Yerleriniz Kimliğini veya Yerleriniz Nesnesini alın.
  • <gmp-place-details-place-request> öğesine referans alın.
  • Yer kimliğini veya yer nesnesini <gmp-place-details-place-request> öğesindeki yer mülküne iletin.

Aşağıda, Yer Ayrıntıları kullanıcı arayüzü kitini JavaScript mantığınıza nasıl uygulayabileceğinize dair bir örnek verilmiştir. Yer Ayrıntıları öğesine referans alın. Bu öğe varsa Yer Ayrıntıları Place Request öğesine referans alın ve Place ID kullanarak place özelliğini ayarlayın. Yukarıdaki örnek HTML kodunda, Place Details öğesinin stili display: none olarak ayarlanmıştır. Bu değer display: block olarak güncellendi.

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

Yer Arama Öğesi, yer arama sonuçlarını liste halinde gösteren bir HTML öğesidir.

  • HTTP isteği kullanarak metin arama veya yakında arama yapabilir ya da JavaScript API Place sınıfını kullanabilirsiniz.
  • Sorgu parametrelerini, konum kısıtlamalarını veya ağırlıklarını, türleri ve istenen alanları FieldMask kullanarak belirtirsiniz.
  • API yanıtını ayrıştırır, yer dizisinde iterasyon yapar ve manuel olarak HTML liste öğeleri oluşturursunuz.

HTML yapısını değiştirme

Yerleriniz listesini oluşturduğunuz HTML kapsayıcısını belirleyin. Özel HTML öğelerinizi (ad, adres vb. için div'ler, span'ler) Yer Arama Öğesi HTML öğesiyle değiştirin.

Mevcut HTML'niz şuna benzer:

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

Yer Arama öğesi, <gmp-place-search> bileşeni kullanılarak uygulanır. Arama türünü yapılandırmak için aşağıdaki yuvalı yapılandırma bileşenlerinden birini ekleyin:

  • Metin arama için <gmp-place-text-search-request>.
  • Yakında Arama için <gmp-place-nearby-search-request>.

Sonuçların nasıl gösterileceğini tanımlamak için <gmp-place-all-content> kısayolunu kullanabilir veya kendi sunum bileşenlerinizi sağlayabilirsiniz. selectable (liste öğelerinin tıklanmasına izin vermek için) ve orientation (yatay veya dikey düzen için) gibi temel özellikler doğrudan üst bileşende ayarlanabilir.

Yakında Arama örneği
<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>
Metin arama örneği
<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>

JavaScript Mantığını Uyarlama

JavaScript'inizde document.querySelector() kullanarak arama denetleyici bileşenine bir referans alın. Kurulumunuza bağlı olarak bu, <gmp-place-text-search-request> veya <gmp-place-nearby-search-request> öğesi olur.

Ardından, aramanızı tanımlamak için bu denetleyicideki özellikleri ayarlayın. Gerekli özellikler, gerçekleştirdiğiniz aramanın türüne bağlıdır.

Metin Arama (<gmp-place-text-search-request>) için birincil özellik textQuery şeklindedir:

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

Yakında Arama (<gmp-place-nearby-search-request>) için arama alanını locationRestriction kullanarak tanımlamanız gerekir. Ardından, bu alandaki belirli yer türlerini filtrelemek için includedTypes simgesini kullanabilirsiniz:

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

Üst <gmp-place-search> bileşeni, denetleyicisinin gerekli özellikleri ayarlanır ayarlanmaz otomatik olarak yeni bir arama başlatır.

  • Metin Arama için arama, textQuery öğesine bir değer atadığınız anda çalışır.
  • Yakında Arama için arama, geçerli bir locationRestriction sağlandıktan sonra çalıştırılır.

Temel Yer Adı Otomatik Tamamlama öğesini uygulama

Yer Arama Öğesi'nin sağladığı kullanıcı arayüzü olmadan bir arama deneyimi isteyen geliştiriciler için Temel Yer Adı Otomatik Tamamlama Öğesi kullanılabilir.

Bu öğe, sonuçların özel kullanıcı arayüzünüzde nasıl gösterileceği üzerinde tam kontrol sahibi olurken bir arama giriş alanı oluşturmak için idealdir. Otomatik Tamamlama Öğesi'nin tek sorumluluğu, kullanıcı yazarken yer tahminleri sağlamak ve seçilen yer için programatik olarak bir yer kimliği göstermektir.

Kendisi herhangi bir ayrıntı göstermez veya programatik olarak erişilebilen başka bir bilgi sağlamaz.

Mevcut Uygulama

Mevcut mantığınız muhtemelen şunları içerir:

  • Sayfanızda, kullanıcı yazarken Yer Adı Otomatik Tamamlama'yı çağırıp sonuçları gösteren bir metin giriş alanı oluşturma.
  • Kullanıcının seçtiği yerin yer kimliğini kullanarak daha fazla ayrıntı (ör. Yer Ayrıntıları API'si) alma
  • Seçilen yerin ayrıntıları gösteriliyor.

Yer Adı Otomatik Tamamlama öğesine geçiş

HTML yapısını değiştirme

Otomatik tamamlama widget'ını eklediğiniz HTML öğesini belirleyip kaldırın. Büyük olasılıkla standart bir HTML giriş alanı kullanıyordur.

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

Sayfanızda temel bir Yer Adı Otomatik Tamamlama öğesi ilk kullanıma hazırlamak için web bileşeni yaklaşımını kullanan yeni HTML örneği.

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

JavaScript Mantığını Uyarlama

JavaScript mantığınız büyük olasılıkla bir input HTML öğesine eklenmiş Otomatik Tamamlama widget'ını oluşturmayı içerir. Bu widget daha sonra place_changed etkinliğini dinleyerek döndürülen verilerle bir işlemi tetikler.

Kaldırılacak mevcut JavaScript örneği:

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

Yeni JavaScript mantığınız, Temel Yer Adı Otomatik Tamamlama öğesine referans alır ve gmp-select etkinliklerini dinler:

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

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

Otomatik tamamlama açılır listesinde bir yer seçildiğinde gmp-select etkinliği tetiklenir. Seçilen yerin yer kimliği, event nesnesinden alınabilir. Ardından, seçilen yer ayrıntılarını görüntülemek için Yer Ayrıntıları Öğesi'nin bir örneğini ilk kullanıma hazırlamak üzere yer kimliği kullanılabilir.

Herkese açık kullanıcı adını özelleştirme

Yer Ayrıntıları öğesini özelleştirme

Yön

Yer Ayrıntıları öğesi hem yatay hem de dikey yönde oluşturulabilir. Dikey ve yatay arasında seçim yapmak için gmp-place-details-compact üzerinde orientation özelliğini kullanın. Örneğin:

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

Oluşturulacak alanları seçin

Yer Ayrıntıları öğesinde oluşturulacak içeriği belirtmek için içerik öğelerini kullanın. Örneğin, <gmp-place-type> içerik öğesini hariç tuttuğunuzda, Yer Ayrıntıları Öğesi, seçilen yerin Yer Türü'nü oluşturmayı durdurur. İçerik öğelerinin tam listesi için PlaceContentConfigElement referans belgelerine bakın.

Yer Ayrıntıları Öğesine alan eklemek veya öğeden alan kaldırmak, öğenin sayfada oluşturulma maliyetini değiştirmez.

CSS Stillerini Ayarlama

Öğenin renklerini ve yazı tiplerini yapılandırmak için özel CSS özellikleri kullanılabilir. Örneğin, öğe arka planını yeşil olarak ayarlamak için aşağıdaki CSS özelliğini ayarlayın:

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

Daha fazla bilgi için PlaceDetailsCompactElement ile ilgili referans belgelerini inceleyin.

Yer Arama öğesi özelleştirmesi

Yön

Yer Arama Öğesi hem yatay hem de dikey yönde oluşturulabilir. Dikey ve yatay arasında seçim yapmak için <gmp-place-search> öğesinde orientation özelliğini kullanın. Örneğin:

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

Oluşturulacak alanları seçin

Yer Arama öğesinde oluşturulacak içeriği belirtmek için içerik öğelerini kullanın. <gmp-place-all-content> öğesi tüm içeriği görüntülemek için kullanılabilir veya oluşturulan içeriği yapılandırmak için HTML etiketleri seçilebilir.

<gmp-place-content-config> içine <gmp-place-address> eklediğinizde yalnızca her yerin adresi oluşturulur. Örneğin:

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

Temel Yer Adı Otomatik Tamamlama öğesi özelleştirmesi

CSS Stillerini Ayarlama

Özel CSS özellikleri, otomatik tamamlama öğesinin görünümünü ve tarzını özelleştirmek için kullanılabilir. Örneğin, arka plan rengini açık mor olarak ayarlamak için öğede background-color özelliğini ayarlarsınız.

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

Daha fazla bilgi için BasicPlaceAutocompleteElement referans belgelerine bakın.

Etkinlikleri ve verileri işleme

Places UI Kit öğeleri, etkinlikleri dinlemenize ve verileri programatik olarak almanıza olanak tanıyan etkileşimli bileşenlerdir.

Etkinlikleri dinleme

Kullanıcı etkileşimine veya öğenin durumuna göre işlemleri tetiklemek için öğelere etkinlik işleyiciler ekleyebilirsiniz.

Seçim etkinliği

  • gmp-select: Bu etkinlik, kullanıcı bir seçim yaptığında tetiklenir.
    • Yer Arama öğesinde, kullanıcı sonuç listesindeki bir yeri tıkladığında tetiklenir.
    • Temel Yer Adı Otomatik Tamamlama Öğesi'nde, kullanıcı açılır listedeki bir tahmini tıkladığında tetiklenir.

Sık Kullanılan Etkinlikler

Yer Arama, Yer Ayrıntıları ve Temel Yer Adı Otomatik Tamamlama öğelerinin tümü aşağıdaki etkinlikleri destekler:

  • gmp-load: Öğe ve içeriğinin yüklenmesi ve oluşturulması tamamlandığında tetiklenir.
  • gmp-requesterror: Sunucuya gönderilen bir istek başarısız olduğunda (ör. geçersiz bir API anahtarı nedeniyle) tetiklenir.

Öğe Verilerine Programatik Olarak Erişme

Öğelerle etkileşim kurulduktan veya öğeler yüklendikten sonra belirli verileri programatik olarak alabilirsiniz.

  • Yer Arama Öğesi ve Yer Ayrıntıları Öğesi için aşağıdaki bilgileri alabilirsiniz:
    • Yer kimliği
    • Konum (Enlem ve Boylam)
    • Görüntü alanı
  • Temel Yer Adı Otomatik Tamamlama Öğesi için aşağıdaki bilgileri alabilirsiniz:
    • Yer kimliği

Öğelerde bulunan diğer tüm verilere programatik olarak erişilemez.

Daha ayrıntılı örnekler için Yer Arama Öğesi, Yer Ayrıntıları Öğesi ve Temel Yer Adı Otomatik Tamamlama Öğesi ile ilgili belgelere bakın.

Test ve İyileştirme

Places UI Kit öğelerini entegre ettikten sonra, sorunsuz bir geçiş ve olumlu bir kullanıcı deneyimi için test yapmak çok önemlidir. Testiniz, uyguladığınız tüm öğeleri (Yer Ayrıntıları, Yer Arama ve Temel Yer Adı Otomatik Tamamlama öğeleri) ele alarak birkaç önemli alanı kapsamalıdır.

Yer Ayrıntıları Öğesi

Yer Ayrıntıları Öğesi için, ayrıntıların çeşitli yerler için doğru şekilde gösterildiğini doğrulayarak başlayın. <gmp-place-details-place-request> öğesinin .place özelliğine çeşitli yer kimlikleri ileterek test edin. Farklı işletme türlerini (zengin verilere sahip işletmeler, önemli yerler, temel adresler) ve farklı bölgelerdeki veya dillerdeki yerleri temsil eden kimlikleri kullanın. İçeriğin biçimlendirmesine, düzenine ve varlığına dikkat edin.

Place Search Element

Yer Arama Öğesi'ni uyguladıysanız farklı arama senaryolarında nasıl oluşturulduğunu ve davrandığını doğrulayın.

  • Metin Arama için <gmp-place-text-search-request> öğesindeki textQuery özelliğini çeşitli girişlerle ayarlayarak test edin: geniş kapsamlı sorgular, belirli adresler ve konum tercihlerine sahip sorgular.
  • Yakında Arama için <gmp-place-nearby-search-request> öğesinde locationRestriction ve includedTypes özelliklerini ayarlayarak test edin. Farklı konum boyutları ve tür filtreleri kullanın.

Listenin alakalı sonuçlarla doldurulduğunu ve seçim yapıldığında gmp-select etkinliğinin doğru şekilde tetiklendiğini onaylayın.

Temel Yer Adı Otomatik Tamamlama Öğesi

Temel Yer Adı Otomatik Tamamlama Öğesi için testleri kullanıcı etkileşimine ve seçim etkinliği tarafından iletilen verilere odaklayın. Kullanıcı bir tahmini tıkladığında gmp-select etkinliğinin güvenilir bir şekilde tetiklendiğini doğrulayın. Etkinlik işleyicideki event.place nesnesinin geçerli bir yer kimliği içerdiğini doğrulayın.

En önemlisi, uçtan uca akışı test edin: Otomatik Tamamlama açılır listesinden bir yer seçin ve yer kimliğinin, Yer Ayrıntıları öğesi gibi başka bir öğeyi doldurmak için başarıyla kullanılabildiğini doğrulayın.

Hata işleme

Hata işleme sürecinin tüm bileşenlerde titizlikle test edilmesi çok önemlidir. Yer Ayrıntıları öğesine geçersiz veya mevcut olmayan yer kimlikleri iletmeyi ya da Yer Arama öğesi için geçersiz arama parametreleri kullanmayı simüle edin. Ağ sorunlarını simüle ederek veya geçersiz bir API anahtarı kullanarak gmp-requesterror etkinliğini tetikleyin ve uygulamanızın bu etkinliği sorunsuz bir şekilde işlediğinden emin olun. Bozuk veya kafa karıştırıcı bir kullanıcı arayüzünü önlemek için kullanıcı dostu hata mesajları ve günlük kaydı uygulayın.