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

Hedef: Places API veya Place Class uygulamanızı Places UI Kit ile değiştirin.

Bu kılavuz kimlere yöneliktir?

Şu geliştiriciler:

  • Places API (Yeni veya Eski) uç noktalarına HTTP istekleri gönderme.
  • Maps JavaScript API'deki Yer sınıfını kullanma.
  • Yer bilgilerini web uygulamalarının kullanıcı arayüzünde 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. 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ükleme İşlemini Güncelleme

Places UI Kit, Maps JavaScript API'nin yüklenmesi için Dynamic Library Import yöntemini gerektirir. Doğrudan komut dosyası yükleme etiketini kullanıyorsanız bu etiket güncellenmelidir.

Maps JavaScript API'nin 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

Yer Ayrıntıları Öğesi ve Yer Ayrıntıları Compact Öğesi, bir yerle ilgili ayrıntıları oluşturmak için kullanılan HTML öğeleridir.

Mevcut uygulama

  • HTTP isteği kullanarak Yer Ayrıntıları çağrısı yaparsınız veya JavaScript API Place Class'ı kullanırsınız.
  • API yanıtını ayrıştırır ve yer ayrıntılarını HTML ve CSS kullanarak görüntülersiniz.

Yer Ayrıntıları Öğesi'ne taşıma

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

Yer ayrıntılarının oluşturulduğu HTML kapsayıcısını belirleyin. Özel HTML öğelerinizi (ad, adres, fotoğraf vb. için kullanılan 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ı Kü��ük Öğesi
  • Yer Ayrıntıları Öğesi

Hangisini kullanacağınız hakkında daha fazla bilgi için Yer Ayrıntıları Öğesi bölümüne bakın.

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 büyük olasılıkla şunları içerir:

  • Yer kimliği alma.
  • PlacesService().getDetails() kullanma veya web hizmeti çağrısı yapma
  • 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:

  • Yer kimliğinizi veya yer nesnenizi alın.
  • <gmp-place-details-place-request> öğesinin referansını alın.
  • Yer kimliğini veya yer nesnesini <gmp-place-details-place-request> öğesindeki yer özelliğine 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ı Öğesi'ne referans alın. Bu öğe varsa Yer Ayrıntıları Yer İsteği öğesine referans alın ve yer kimliği kullanarak yer özelliğini ayarlayın. Yukarıdaki örnek HTML kodunda Place Details Element stili display: none olarak ayarlanmıştır. Bu değer display: block olarak güncellenir.

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 oluşturmak için kullanılan bir HTML öğesidir.

  • HTTP isteği kullanarak Metin Arama veya Yakında Arama gerçekleştiriyorsunuz ya da JavaScript API Place Class'ı kullanıyorsunuz.
  • FieldMask kullanarak sorgu parametrelerini, konum kısıtlamalarını veya önyargılarını, türleri ve istenen alanları belirtirsiniz.
  • API yanıtını ayrıştırır, yer dizisinde yineler ve HTML liste öğelerini manuel olarak oluşturursunuz.

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

Yer listenizi 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 aşağıdaki gibi görünebilir:

<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 araması için <gmp-place-text-search-request> simgesine dokunun.
  • <gmp-place-nearby-search-request> simgesini tıklayın.

Sonuçların nasıl görüntüleneceğini tanımlamak için <gmp-place-all-content> kısayolunu kullanabilir veya kendi sunum bileşenleri grubunuzu sağlayabilirsiniz. selectable (liste öğelerinin tıklanmasına izin vermek için) ve orientation (yatay veya dikey düzen için) gibi önemli ö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 denetleyicisi bileşenine 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 arama türüne bağlıdır.

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

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, includedTypes simgesini kullanarak bu alan içindeki belirli yer türlerini filtreleyebilirsiniz:

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, textQuery değişkenine değer atadığınız anda arama çalıştırılır.
  • Yakındaki Arama için arama, geçerli bir locationRestriction sağlandıktan sonra çalıştırılır.

Temel Yer Adı Otomatik Tamamlama Öğesini Uygulama

Place Search Element'in sağladığı kullanıcı arayüzü olmadan arama deneyimi isteyen geliştiriciler için Basic Place Autocomplete Element kullanılabilir.

Bu öğe, sonuçların özel kullanıcı arayüzünüzde nasıl görüntülendiğ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 büyük olasılıkla şunları içerir:

  • Kullanıcı yazarken Yer Otomatik Tamamlama'yı çağıran ve sonuçları görüntüleyen bir metin girişi alanı oluşturma.
  • Kullanıcının seçtiği yerin yer kimliğini kullanarak daha fazla ayrıntı getirme (ör. Yer Ayrıntıları API'sini kullanarak).
  • Seçilen yerin ayrıntılarını gösterir.

Yer Adı Otomatik Tamamlama Öğesine Taşıma

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

Otomatik tamamlama widget'ını eklediğiniz HTML öğesini belirleyin ve kaldırın. Standart bir HTML giriş alanı kullanıyor olabilir.

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

Sayfanızda Temel Yer Otomatik Tamamlama öğesini başlatmak 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'ı oluşturmayı içerir. Bu widget daha sonra place_changed etkinliğini dinler ve 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, Basic Place Autocomplete Element'e bir 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. Yer kimliği daha sonra, seçilen yer ayrıntılarını göstermek için Yer Ayrıntıları Öğesi'nin bir örneğini başlatmak için kullanılabilir.

Handle Özelleştirme

Yer ayrıntıları öğesi ö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ı Öğesi'nde oluşturulacak içeriği belirtmek için içerik öğelerini kullanın. Örneğin, <gmp-place-type> içerik öğesini hariç tutmak, seçilen yerin Yer Türü'nün Yer Ayrıntıları Öğesi tarafından oluşturulmasını durdurur. İçerik öğelerinin tam listesi için PlaceContentConfigElement referans belgelerine bakın.

Yer Ayrıntıları Öğesi'ne alan eklemek veya bu öğ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 ayrıntı için PlaceDetailsCompactElement ile ilgili referans belgelerine bakın.

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 Öğesi'nde oluşturulacak içeriği belirtmek için içerik öğelerini kullanın. Öğe <gmp-place-all-content> tüm içeriği görüntülemek için kullanılabilir veya oluşturulan içeriği yapılandırmak için bir HTML etiketleri seçimi kullanılabilir.

<gmp-place-address> öğesini <gmp-place-content-config> içine eklemek yalnızca her yerin adresini oluşturur. Ö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ştirme

CSS stillerini ayarlama

Otomatik tamamlama öğesinin görünümünü ve tarzını özelleştirmek için özel CSS özellikleri 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 ayrıntı için BasicPlaceAutocompleteElement referans belgelerine göz atın.

Etkinlikleri ve verileri işleme

Places UI Kit Elements, 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 dinleyicileri ekleyebilirsiniz.

Seçim Etkinliği

  • gmp-select: Bu etkinlik, kullanıcı bir seçim yaptığında tetiklenir.
    • Yer Arama Öğesi'nde, kullanıcı sonuç listesindeki bir yeri tıkladığında tetiklenir.
    • Temel Yer 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 Otomatik Tamamlama öğeleri aşağıdaki etkinlikleri destekler:

  • gmp-load: Öğe ve içeriği yüklenip oluşturulduktan sonra tetiklenir.
  • gmp-requesterror: Sunucuya yapılan bir istek başarısız olduğunda (ör. geçersiz 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 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 Otomatik Tamamlama Öğesi ile ilgili ayrı dokümanlara 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 Otomatik Tamamlama öğeleri) ele alarak çeşitli temel alanları kapsamalıdır.

Yer Ayrıntıları Öğesi

Yer Ayrıntıları Öğesi için öncelikle ayrıntıların çeşitli yerlerde doğru şekilde gösterildiğini doğrulayın. .place öğesinin <gmp-place-details-place-request> özelliğine çeşitli yer kimlikleri ileterek test edin. Farklı kuruluş türlerini (zengin veriler içeren işletmeler, ilgi çekici yerler, temel adresler) ve farklı bölgelerdeki veya dillerdeki yerleri temsil eden kimlikler kullanın. Biçimlendirme, düzen ve içeriğin varlığına dikkat edin.

Yer Arama Öğesi

Yer Arama Öğesi'ni uyguladıysanız farklı arama senaryolarında öğenin oluşturulmasını ve davranışını doğrulayın.

  • Metin Arama için textQuery özelliğini <gmp-place-text-search-request> öğesinde çeşitli girişlerle (geniş kapsamlı sorgular, belirli adresler ve konum önyargıları içeren sorgular) ayarlayarak test edin.
  • Yakındaki 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 dolduğunu ve seçim yapıldığında gmp-select etkinliğin doğru şekilde tetiklendiğini onaylayın.

Temel Otomatik Yer Tamamlama Öğesi

Temel Yer Otomatik Tamamlama Öğesi için testi kullanıcı etkileşimi ve seçim etkinliği tarafından iletilen veriler üzerinde yoğunlaştırın. Kullanıcı bir tahmini tıkladığında gmp-select etkinliğinin güvenilir bir şekilde tetiklendiğini onaylayın. Etkinlik işleyicisindeki event.place nesnenin 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 Ayrıntıları Öğesi gibi başka bir öğeyi doldurmak için yer kimliğinin başarıyla kullanılabildiğini doğrulayın.

Hata işleme

Hata işlemeyle ilgili titiz testler, tüm bileşenlerde gereklidir. Geçersiz veya mevcut olmayan yer kimliklerini Yer Ayrıntıları öğesine iletmeyi ya da Yer Arama öğesi için geçersiz arama parametreleri kullanmayı simüle edin. Uygulamanızın bu durumu sorunsuz bir şekilde ele aldığından emin olmak için ağ sorunlarını simüle ederek veya geçersiz bir API anahtarı kullanarak gmp-requesterror etkinliğini tetikleyin. 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.