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. Aşağıdaki durumlarda bu kılavuzdan en iyi şekilde yararlanabilirsiniz:

  • Places API (yeni veya eski) uç noktalarına HTTP istekleri gönderme
  • Maps JavaScript API'deki 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 üzere gerekli kitaplıkları içe aktarın.

Yer Ayrıntıları öğesini uygulama

Yer Ayrıntıları Öğesi ve Yer Ayrıntıları Kompakt Öğesi, bir yerle ilgili ayrıntıları gösteren HTML öğeleridir.

Mevcut Yer Ayrıntıları Uygulaması

  • 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 HTML ile CSS kullanarak yer ayrıntılarını gösterirsiniz.

Yer Ayrıntıları Öğesi için 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 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-media lightbox-preferred></gmp-place-media>
    <gmp-place-name></gmp-place-name>
    <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-details-compact>

Yer Ayrıntıları Öğesi için 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 bir referans alın ve Place ID kullanarak place özelliğini ayarlayın. Yukarıdaki örnek HTML kodunda, Yer Ayrıntıları öğ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.

Yerleriniz listenizi oluşturduğunuz HTML kapsayıcısını tanımlayın. Ö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>

Text Search ö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>

Yer Arama Öğesi için 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, yaptığınız 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 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 deneyimine ihtiyaç duyan 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 Yer Adı Otomatik Tamamlama Uygulaması

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'sini kullanarak) alma.
  • Seçilen yerin ayrıntıları gösteriliyor.

Temel Yer Adı Otomatik Tamamlama Öğesi için 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 Yer Adı Otomatik Tamamlama öğesini 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ı temel Yer Adı Otomatik Tamamlama öğesine uyarlama

JavaScript mantığınız muhtemelen bir input HTML öğesine ekli 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 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ı Öğesi özelleştirmesi

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. İçerik öğelerini doğrudan Yer Ayrıntıları öğesine ekleyin. Ö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. Yalnızca eklediğiniz içerik öğeleri oluşturulur. Bu nedenle, yer adını göstermek için <gmp-place-name> öğesini ekleyin. İçerik öğelerinin tam listesi için Konum Widget'ları İçerik Özelleştirme referans belgelerine bakın.

Yer Ayrıntıları öğesine alan eklemek veya 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.

Oluşturulan içeriği yapılandırmak için içerik öğelerini <gmp-place-search> içindeki bir <template slot="details-item"> öğesine ekleyin. Örneğin, şablona yalnızca <gmp-place-name> ve <gmp-place-address> eklediğinizde her yer için yalnızca ad ve adres gösterilir:

<gmp-place-search orientation="horizontal" selectable>
  <template slot="details-item">
    <gmp-place-name></gmp-place-name>
    <gmp-place-address></gmp-place-address>
  </template>
  <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 programatik olarak belirli verileri 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.

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ş sorgular, belirli adresler ve konum eğilimleri olan 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

Tüm bileşenlerde hata işleme sürecinin 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. Uygulamanızın bu etkinliği sorunsuz bir şekilde işlediğinden 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.